Outline
The outline feature (also known as grouping or dimension outline) allows you to group rows or columns in a worksheet. This is useful for organizing and summarizing large datasets by creating collapsible sections.
Introduction
In Univer Sheets, the outline feature enables you to:
- Group rows or columns: Create hierarchical groups of rows or columns to organize data.
- Collapse and expand groups: Show or hide grouped rows or columns with a single click.
- Nested groups: Create multiple levels of groups for complex data hierarchies.
Outline groups are commonly used in the following scenarios:
- Summarizing detailed data: Group detailed rows under summary rows to create a cleaner view.
- Organizing large datasets: Group related columns or rows together for easier navigation.
- Creating collapsible reports: Allow users to expand or collapse sections of a report as needed.
Preset Mode
The outline feature is included in the @univerjs/preset-sheets-advanced preset.
Installation
pnpm add @univerjs/preset-sheets-advancednpm install @univerjs/preset-sheets-advancedyarn add @univerjs/preset-sheets-advancedbun add @univerjs/preset-sheets-advancedUsage
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'import UniverPresetSheetsAdvancedEnUS from '@univerjs/preset-sheets-advanced/locales/en-US'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-advanced/lib/index.css'const { univerAPI } = createUniver({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales( UniverPresetSheetsCoreEnUS, UniverPresetSheetsAdvancedEnUS, ), }, presets: [ UniverSheetsCorePreset(), UniverSheetsAdvancedPreset(), ],})If you have a commercial license for Univer, please refer to Using License in Client for configuration.
Plugin Mode
Installation
pnpm add @univerjs-pro/sheets-outline @univerjs-pro/sheets-outline-uinpm install @univerjs-pro/sheets-outline @univerjs-pro/sheets-outline-uiyarn add @univerjs-pro/sheets-outline @univerjs-pro/sheets-outline-uibun add @univerjs-pro/sheets-outline @univerjs-pro/sheets-outline-uiUsage
import { UniverSheetsOutlinePlugin } from '@univerjs-pro/sheets-outline'import { UniverSheetsOutlineUIPlugin } from '@univerjs-pro/sheets-outline-ui'import SheetsOutlineUIEnUS from '@univerjs-pro/sheets-outline-ui/locale/en-US'import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import '@univerjs-pro/sheets-outline/facade'import '@univerjs-pro/sheets-outline-ui/lib/index.css'const univer = new Univer({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales( SheetsOutlineUIEnUS, ), },})univer.registerPlugin(UniverSheetsOutlinePlugin)univer.registerPlugin(UniverSheetsOutlineUIPlugin)If you have a commercial license for Univer, please refer to Using License in Client for configuration.
Facade API
Complete Facade API type definitions can be found in the FacadeAPI.
Importing
Plugin mode note
Only plugin mode requires manually importing the Facade package. Preset mode already includes the corresponding Facade package, so no extra import is needed.
import '@univerjs-pro/sheets-outline/facade'Creating Row Outlines
You can create a row outline group using the Facade API:
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Group rows 2 to 6 (0-based index: startRow=1, numRows=5)fWorksheet.addRowOutline(1, 5)Creating Column Outlines
Similarly, you can create a column outline group:
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Group columns B to E (0-based index: startColumn=1, numColumns=4)fWorksheet.addColumnOutline(1, 4)Collapsing and Expanding Outlines
You can collapse or expand an outline group programmatically:
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const rowOutlines = fWorksheet.getDimensionOutlines(univerAPI.Enum.DimensionOutlineAxis.ROW)if (rowOutlines.length > 0) { // Collapse the first row outline group fWorksheet.setDimensionOutlineCollapsed(rowOutlines[0].id, true) // Expand it later fWorksheet.setDimensionOutlineCollapsed(rowOutlines[0].id, false)}Removing Outlines
You can remove a specific outline group by its ID:
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const rowOutlines = fWorksheet.getDimensionOutlines(univerAPI.Enum.DimensionOutlineAxis.ROW)if (rowOutlines.length > 0) { fWorksheet.removeDimensionOutline(rowOutlines[0].id)}Clearing Outlines in a Range
You can clear all outline groups within a specific range:
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Remove all row outline groups fully contained in rows 2 to 10fWorksheet.clearDimensionOutlines(univerAPI.Enum.DimensionOutlineAxis.ROW, 1, 9)Querying Outlines
You can retrieve all outline groups on a worksheet:
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Get all row outlinesconst rowOutlines = fWorksheet.getDimensionOutlines(univerAPI.Enum.DimensionOutlineAxis.ROW)rowOutlines.forEach((outline) => { console.log(outline.id, outline.start, outline.end, outline.collapsed)})// Get all outlines (both row and column)const allOutlines = fWorksheet.getDimensionOutlines()Outline Data Structure
Each outline group has the following properties:
| Property | Type | Description |
|---|---|---|
id | string | Unique identifier for the outline group |
unitId | string | The workbook unit ID |
subUnitId | string | The worksheet sheet ID |
axis | DimensionOutlineAxis | The axis of the outline (row or column) |
start | number | Zero-based inclusive start index |
end | number | Zero-based inclusive end index |
collapsed | boolean | Whether the group is currently collapsed |
Validation and Errors
When creating outline groups, the following validations are performed:
- Invalid range: The range must be valid (non-negative, non-zero count).
- Out of bounds: The range must be within the worksheet boundaries.
- Crossing groups: New groups cannot cross existing groups.
- Maximum depth: There is a maximum nesting depth for outline groups.
The range for ungrouping must fully contain the outline group range, otherwise the validation will fail.
If a validation fails, the command will not execute and an error will be emitted through the SheetsOutlineErrorService.
How is this guide?