슬라이서와 타임라인

Headless 지원

슬라이서는 소스 멤버를 기준으로 테이블, 피벗 테이블 및 피벗 차트를 필터링합니다. 타임라인은 지원되는 피벗 원본 날짜 필드를 필터링하며, 테이블 열, 텍스트 필드, 계산 필드 및 파생 그룹 필드는 소스로 사용할 수 없습니다.

통합 설정

기존 Sheets 설정에 다음 내용을 추가하고 그리기 지원과 소스로 사용할 테이블 또는 피벗 테이블을 설정하세요. 워크북을 만들기 전에 언어 팩을 로드하고 플러그인을 등록합니다.

Shell
pnpm add @univerjs-pro/sheets-slicer @univerjs-pro/sheets-slicer-ui
TypeScript
import { UniverSheetsSlicerPlugin } from '@univerjs-pro/sheets-slicer'import { UniverSheetsSlicerUIPlugin } from '@univerjs-pro/sheets-slicer-ui'import SheetsSlicerUILocale from '@univerjs-pro/sheets-slicer-ui/locale/ko-KR'import { LocaleType } from '@univerjs/core'import '@univerjs-pro/sheets-slicer/facade'import '@univerjs-pro/sheets-slicer-ui/lib/index.css'univerAPI.loadLocales(LocaleType.KO_KR, SheetsSlicerUILocale)univer.registerPlugin(UniverSheetsSlicerPlugin)univer.registerPlugin(UniverSheetsSlicerUIPlugin)

Worker를 쓰면 고급 프리셋에 useWorker: true를 설정하고 Worker에서 UniverSheetsAdvancedWorkerPreset()을 등록합니다. 슬라이서 계산 플러그인도 포함됩니다.

슬라이서 만들기

이 예제는 활성 시트의 I1에 있는 피벗 테이블과 Region이라는 소스 필드를 사용합니다. getSourceFieldsInfo()로 원본 필드의 안정적인 ID를 가져오세요. 표시 이름이나 보고서 필드 ID는 newSlicer()에 전달할 수 없습니다.

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook?.getActiveSheet()if (!fWorkbook || !fWorksheet) throw new Error('No active worksheet')const pivotTable = fWorkbook.getPivotTableByCell(  fWorkbook.getId(),  fWorksheet.getSheetId(),  0,  8,)const regionField = pivotTable?.getSourceFieldsInfo().find((field) => field.name === 'Region')if (!pivotTable || !regionField) throw new Error('Region source field not found')const slicer = await fWorksheet.insertSlicer(  pivotTable.newSlicer(regionField.id)    .setCaption(regionField.name)    .setPosition('N2')    .build(),)

pivotTable.newSlicer()는 빌더를 소스에 연결합니다. build()는 설정만 생성하고 insertSlicer()가 컨트롤을 삽입합니다. 컨트롤이 위치한 시트와 소스 시트는 서로 달라도 되지만 같은 워크북에 있어야 합니다. 테이블 소스에는 fWorksheet.newSlicer(columnId).setTableReference({ subUnitId, tableId })를 사용합니다. columnId는 테이블 열의 안정적인 ID입니다.

타임라인 만들기

같은 피벗 테이블을 사용하는 다음 예제에는 Date라는 원본 날짜 필드가 필요합니다. newTimeline()은 소스를 검증하고 지원하지 않는 필드를 거부합니다. 타임라인 범위 API는 JavaScript Date 객체가 아닌 워크북 날짜 시스템의 Excel 일련번호 값을 사용합니다.

TypeScript
const dateField = pivotTable.getSourceFieldsInfo().find((field) => field.name === 'Date')if (!dateField) throw new Error('Date source field not found')const timeline = await fWorksheet.insertTimeline(  pivotTable.newTimeline(dateField.id)    .setCaption(dateField.name)    .setLevel(univerAPI.Enum.TimelineLevel.Month)    .setPosition('N18')    .build(),)

컨트롤 조회 및 변경 감지

컨트롤이 위치한 워크시트에서 getSlicer(viewId) / getSlicers() 및 getTimeline(viewId) / getTimelines()을 호출합니다. viewId는 컨트롤의 getId()가 반환하는 ID이며, 그리기 ID가 아닙니다.

univerAPI.addEvent()로 SlicerAdded, SlicerChanged, SlicerRemoved, TimelineAdded, TimelineChanged, TimelineRemoved를 구독할 수 있습니다. 이 이벤트는 확정된 로컬 변경을 알리며 원격 저장이나 렌더링 완료를 의미하지 않습니다. 더 이상 필요하지 않으면 반환된 구독의 dispose()를 호출하세요.

API 참조:

멤버 조회와 공유 필터

setSelection()에는 타입이 있는 원본 값을 전달합니다. 숫자 1, 문자열 '1', 빈 값은 서로 다른 멤버입니다. 표시 라벨이나 목록 인덱스를 전달하지 마세요. 필터는 같은 캐시의 모든 뷰와 연결된 보고서에 공유됩니다. Table 소스에서는 해당 열의 필터만 교체하며 다른 열은 유지합니다. clearFilter()로 해제할 수 있습니다.

TypeScript
import { FilterSelectionMode, RecordValueType } from '@univerjs/core'const accepted = await slicer.setSelection({  mode: FilterSelectionMode.Include,  values: [{ type: RecordValueType.String, value: 'EMEA' }],})

getItems({ start, count })는 일부 구간만 조회하며 선택을 변경하지 않습니다. 기본 100개를 조회하고 양의 정수인 maxMemberWindowSize로 제한합니다(기본 200). 현재 구간 밖의 선택도 유지하세요. setConnections()는 피벗 보고서 연결을 교체하며 getConnectionCandidates()로 호환 보고서를 조회합니다. 편집에는 해당 시트 권한이 필요합니다. FSheetSlicer를 참고하세요.

이 가이드는 어떠셨나요?

© 2026 DreamNum Co., Ltd.