Feature Request: Expose rowOutlineLevel as readable/writable on Excel.Range in office.js

SUMMARY

Excel VBA has long supported Range.OutlineLevel as a read/write property for inspecting and setting row or column grouping levels. Office.js currently has no functional equivalent.

We are requesting that rowOutlineLevel and columnOutlineLevel be exposed as functional read/write properties on Excel.Range.

CURRENT OFFICE.JS LIMITATION

Office.js provides Range.group() and Range.ungroup() starting with ExcelApi 1.9. However, there is currently no reliable way to read or restore the outline/grouping level of a row or column.

Example:

await Excel.run(async (context) => {

const range = context.workbook.worksheets.getActiveWorksheet().getRange("A5");

range.load("rowOutlineLevel");

await context.sync();

console.log(range.rowOutlineLevel); // undefined

range.rowOutlineLevel = 1;

 await context.sync(); // No error, but no effect

});

We verified this across ExcelApi requirement sets through 1.21, ExcelApiDesktop 1.1, and Preview APIs.

• rowOutlineLevel returns undefined after load() and context.sync().
• Setting rowOutlineLevel has no effect.
• The same behavior occurs when using getEntireRow().
• rowOutlineLevel and columnOutlineLevel are not exposed in the documented requirement sets.

VBA / COM PARITY

Excel VBA already provides this functionality through Range.OutlineLevel.

Read example:

level = Worksheets("Sheet1").Rows(2).OutlineLevel

Set or restore example:

Worksheets("Sheet1").Rows(2).OutlineLevel = 1

VBA also provides Worksheet.Outline, including ShowLevels, SummaryRow, and SummaryColumn.

Capability comparison:

Read grouping level:

VBA: Range.OutlineLevel

Office.js: Not available

Set grouping level:

VBA: Range.OutlineLevel = n

Office.js: Not available

Apply grouping:

VBA: Range.Group

Office.js: Range.group()

Remove grouping:

VBA: Range.Ungroup

Office.js: Range.ungroup()

Query or control outline structure:

VBA: Worksheet.Outline

Office.js: No equivalent

BUSINESS IMPACT

Our Excel add-in manages Multi-Dimensional Report (MDR) sections that use row grouping for collapse and expand behavior.

During refresh and mapping operations, we need to detect existing row grouping and outline levels and restore the grouping if operations such as range copies remove it.

Without readable outline levels, we cannot determine which rows are grouped or at what level. Without writable outline levels, we cannot reliably restore the previous structure.

Our current workaround requires users to manually fix grouping in Excel. This creates a poor enterprise experience and is a regression compared with our previous VBA-based automation.

REQUESTED CHANGES

Make rowOutlineLevel readable on Excel.Range so that it returns the actual outline level, such as 1, 2, or 3.

Make rowOutlineLevel writable so that grouping levels can be restored programmatically.

Provide equivalent read/write support for columnOutlineLevel.

As a stretch goal, expose a Worksheet.outline API similar to VBA's Worksheet.Outline, including showLevels(), summaryRow, and summaryColumn.

REFERENCES

VBA Range.OutlineLevel: https://learn.microsoft.com/en-us/office/vba/api/excel.range.outlinelevel

VBA Outline: https://learn.microsoft.com/en-us/office/vba/api/excel.outline

Office.js Range.group() and Range.ungroup():https://learn.microsoft.com/en-us/javascript/api/excel/excel.range

Office.js Preview APIs: https://learn.microsoft.com/en-us/javascript/api/requirement-sets/excel/excel-preview-apis

ExcelApiDesktop 1.1: https://learn.microsoft.com/en-us/javascript/api/requirement-sets/excel/excel-api-desktop-1-1-requirement-set

Office.js Range Grouping:https://learn.microsoft.com/en-us/office/dev/add-ins/excel/excel-add-ins-ranges-group