Web SDK

아웃라인

아웃라인 기능(그룹화 또는 차원 아웃라인이라고도 함)을 사용하면 워크시트의 행이나 열을 그룹화할 수 있습니다. 접을 수 있는 섹션을 만들어 대규모 데이터 세트를 체계적으로 정리하고 요약할 때 유용합니다.

소개

Univer Sheets의 아웃라인 기능으로 다음 작업을 할 수 있습니다.

  • 행 또는 열 그룹화: 행이나 열을 계층적으로 그룹화하여 데이터를 정리합니다.
  • 그룹 접기 및 펼치기: 클릭 한 번으로 그룹화된 행이나 열을 표시하거나 숨깁니다.
  • 중첩 그룹: 복잡한 데이터 계층 구조에 맞게 여러 단계의 그룹을 만듭니다.

아웃라인 그룹은 일반적으로 다음과 같은 상황에서 사용합니다.

  • 상세 데이터 요약: 상세 행을 요약 행 아래에 그룹화하여 화면을 깔끔하게 정리합니다.
  • 대규모 데이터 세트 정리: 관련된 열이나 행을 묶어 데이터를 더 쉽게 탐색합니다.
  • 접을 수 있는 보고서 만들기: 사용자가 필요에 따라 보고서의 각 섹션을 펼치거나 접을 수 있도록 합니다.

플러그인 모드

설치

Shell
pnpm add @univerjs-pro/sheets-outline @univerjs-pro/sheets-outline-ui

사용법

TypeScript
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)

Univer 상용 라이선스를 보유하고 있다면 클라이언트에서 라이선스 사용하기를 참고하여 설정하세요.

모바일 지원

먼저 모바일 에디터를 구성하세요. 이 페이지의 플러그인 모드 초기화 코드에서 아래 데스크톱 등록을 같은 패키지의 모바일 버전으로 바꾸고 문서를 열기 전에 완료하세요. 모델 플러그인, 스타일, 언어 파일과 Facade 가져오기는 유지하며 두 버전을 동시에 등록하지 마세요.

패키지데스크톱 등록모바일 등록
@univerjs-pro/sheets-outline-uiUniverSheetsOutlineUIPluginUniverSheetsOutlineMobileUIPlugin

프리셋 모드

아웃라인 기능은 @univerjs/preset-sheets-advanced 프리셋에 포함되어 있습니다.

설치

Shell
pnpm add @univerjs/preset-sheets-advanced

사용법

TypeScript
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(),   ],})

Univer 상용 라이선스를 보유하고 있다면 클라이언트에서 라이선스 사용하기를 참고하여 설정하세요.

Facade API

전체 Facade API 타입 정의는 FacadeAPI에서 확인할 수 있습니다.

가져오기

플러그인 모드 안내

플러그인 모드에서만 Facade 패키지를 직접 가져와야 합니다. 프리셋 모드에는 해당 Facade 패키지가 이미 포함되어 있으므로 별도로 가져올 필요가 없습니다.

TypeScript
import '@univerjs-pro/sheets-outline/facade'

행 아웃라인 만들기

Facade API를 사용하여 행 아웃라인 그룹을 만들 수 있습니다.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Group rows 2 to 6 (0-based index: startRow=1, numRows=5)fWorksheet.addRowOutline(1, 5)

열 아웃라인 만들기

같은 방법으로 열 아웃라인 그룹을 만들 수 있습니다.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Group columns B to E (0-based index: startColumn=1, numColumns=4)fWorksheet.addColumnOutline(1, 4)

아웃라인 접기 및 펼치기

아웃라인 그룹을 프로그래밍 방식으로 접거나 펼칠 수 있습니다.

TypeScript
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)}

아웃라인 삭제하기

ID를 사용하여 특정 아웃라인 그룹을 삭제할 수 있습니다.

TypeScript
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)}

범위 내 아웃라인 지우기

특정 범위 안의 모든 아웃라인 그룹을 지울 수 있습니다.

TypeScript
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)

아웃라인 조회하기

워크시트의 모든 아웃라인 그룹을 가져올 수 있습니다.

TypeScript
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()

아웃라인 데이터 구조

각 아웃라인 그룹에는 다음 속성이 있습니다.

속성타입설명
idstring아웃라인 그룹의 고유 식별자
unitIdstring워크북 단위 ID
subUnitIdstring워크시트 시트 ID
axisDimensionOutlineAxis아웃라인의 축(row 또는 column)
startnumber0부터 시작하는 범위의 시작 인덱스(포함)
endnumber0부터 시작하는 범위의 끝 인덱스(포함)
collapsedboolean그룹이 현재 접혀 있는지 여부

유효성 검사 및 오류

아웃라인 그룹을 만들 때 다음 항목을 검사합니다.

  • 잘못된 범위: 범위가 유효해야 합니다(음수가 아니며 개수가 0이 아니어야 함).
  • 범위 초과: 범위가 워크시트 경계 안에 있어야 합니다.
  • 그룹 교차: 새 그룹은 기존 그룹과 교차할 수 없습니다.
  • 최대 깊이: 아웃라인 그룹에는 허용되는 최대 중첩 깊이가 있습니다.

이 가이드는 어떠셨나요?

© 2026 DreamNum Co., Ltd.