# FSheetTimelineBuilder - Human documentation: [https://docs.univer.ai/reference/facade/sheet-timeline-builder](https://docs.univer.ai/reference/facade/sheet-timeline-builder) - Agent Markdown: [https://docs.univer.ai/reference/facade/sheet-timeline-builder.md](https://docs.univer.ai/reference/facade/sheet-timeline-builder.md) - Requested language: `en-US` - Content language: `en-US` - Documentation version: `1.3.0` - Source: [facade/sheet-timeline-builder.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/sheet-timeline-builder.mdx) --- Detached Timeline configuration for a supported original Pivot date field; visual dimensions use CSS px. Setters/build do not run commands. Date navigation uses Workbook Excel serials, not JavaScript Date. ## Access Access through: - [`FWorksheet.newTimeline()`](https://docs.univer.ai/reference/facade/worksheet.md#newtimeline) ## Setup Register [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) or a preset that includes it. In plugin mode, import `@univerjs-pro/sheets-slicer/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/guides/sheets/getting-started/facade.md). ## `@univerjs-pro/sheets-slicer` ### `FSheetTimelineBuilder.build` Returns defensive insert/update information without executing any command or copying runtime filtering. Requires a resolved source. Insertion validates names/style/placement at command execution; omitted names are generated uniquely then, and current live names remain valid on update. ```typescript build(): ISheetTimelineInfo ``` **Returns** A defensive current value (where applicable), with missing-resource behavior described above. **Throws** If required source/host data is unavailable, input is unsupported, or the documented query/command fails. **Examples** ```ts const info = builder.build() ``` **Types:** [`ISheetTimelineInfo`](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/types.d.ts) **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.clearStyle` Stores an own undefined style override in detached settings; insert/update restores the document default. Does not execute a command or change shared cache/filtering. ```typescript clearStyle(): this ``` **Returns** This detached Builder for chaining; no command has run. **Examples** ```ts builder.clearStyle() ``` **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setAbsolutePosition` Stores finite absolute Worksheet CSS px coordinates, clearing the detached anchor. No command runs; placement is validated on insert/update. ```typescript setAbsolutePosition(x: number, y: number): this ``` **Parameters** - `x` — Required. Finite absolute horizontal CSS px coordinate. - `y` — Required. Finite absolute vertical CSS px coordinate. **Returns** This detached Builder for chaining; no command has run. **Examples** ```ts builder.setAbsolutePosition(100, 80) ``` **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setCaption` Stores the detached view caption, not its name or shared source/cache. The caption must be nonempty and at most 32767 characters. Only this detached configuration changes; no command or model write runs. Validation occurs on insert/update. ```typescript setCaption(caption: string): this ``` **Parameters** - `caption` — Required. Nonempty caption, at most 32767 characters; independent of name. **Returns** This detached Builder for chaining; no command has run. **Examples** ```ts builder.setCaption('Sales') ``` **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setLevel` Stores detached display grain using TimelineLevel; shared date range and selectionLevel stay unchanged. Only this detached configuration changes; no command or model write runs. Validation occurs on insert/update. ```typescript setLevel(level: TimelineLevel): this ``` **Parameters** - `level` — Required. Owner TimelineLevel value for this per-view grain. **Returns** This detached Builder for chaining; no command has run. **Examples** ```ts builder.setLevel(univerAPI.Enum.TimelineLevel.Month) ``` **Types:** [`TimelineLevel`](https://unpkg.com/@univerjs-pro/slicer/lib/types/definition.d.ts) **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setName` Stores the detached view name, not its caption or shared source/cache. Names must be nonempty and unique across Workbook Slicers/Timelines (case-insensitive). Only this detached configuration changes; no command or model write runs. Validation occurs on insert/update. ```typescript setName(name: string): this ``` **Parameters** - `name` — Required. Nonempty Workbook-unique view name (case-insensitive). **Returns** This detached Builder for chaining; no command has run. **Examples** ```ts builder.setName('Sales filter') ``` **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setPivotChart` Resolves the Builder original source field ID against a same-Workbook PivotChart without inserting. Linked charts normalize to their owner PivotTable; owned charts retain their owned report connection. Only supported original Pivot date fields are accepted, not Table/text/calculated/grouped sources. ```typescript setPivotChart(pivotChart: FSheetPivotChart): this ``` **Parameters** - `pivotChart` — Required. Same-Workbook PivotChart source facade. **Returns** This detached Builder for chaining; no command has run. **Throws** If required source/host data is unavailable, input is unsupported, or the documented query/command fails. Source replacement through a cast on a prelinked/bound Builder also throws. **Examples** ```ts builder.setPivotChart(pivotChart) ``` **Types:** [`FSheetPivotChart`](https://docs.univer.ai/reference/facade/sheet-pivot-chart.md) **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setPivotChartReference` Resolves the Builder original source field ID against an explicit same-Workbook PivotChart reference. Linked charts normalize to their owner; this does not insert or modify filtering. Only supported original Pivot date fields are accepted, not Table/text/calculated/grouped sources. ```typescript setPivotChartReference(reference: { unitId: string; subUnitId: string; pivotChartId: string; }): this ``` **Parameters** - `reference` — Required. Explicit same-Workbook source identity. **Returns** This detached Builder for chaining; no command has run. **Throws** If required source/host data is unavailable, input is unsupported, or the documented query/command fails. Source replacement through a cast on a prelinked/bound Builder also throws. **Examples** ```ts builder.setPivotChartReference({ unitId: 'unit', subUnitId: 'source', pivotChartId: 'chart' }) ``` **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setPivotTable` Resolves the Builder original source field ID against a same-Workbook PivotTable, without inserting. Display names/report tableFieldIds are not substitutes for stable source IDs. Only supported original Pivot date fields are accepted, not Table/text/calculated/grouped sources. ```typescript setPivotTable(pivotTable: FPivotTable): this ``` **Parameters** - `pivotTable` — Required. Same-Workbook PivotTable source facade. **Returns** This detached Builder for chaining; no command has run. **Throws** If required source/host data is unavailable, input is unsupported, or the documented query/command fails. Source replacement through a cast on a prelinked/bound Builder also throws. **Examples** ```ts builder.setPivotTable(pivotTable) ``` **Types:** [`FPivotTable`](https://docs.univer.ai/reference/facade/pivot-table.md) **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setPivotTableReference` Resolves the Builder original source field ID against an explicit same-Workbook PivotTable reference. Does not insert or mutate filtering. Only supported original Pivot date fields are accepted, not Table/text/calculated/grouped sources. ```typescript setPivotTableReference(reference: { unitId: string; subUnitId: string; pivotTableId: string; }): this ``` **Parameters** - `reference` — Required. Explicit same-Workbook source identity. **Returns** This detached Builder for chaining; no command has run. **Throws** If required source/host data is unavailable, input is unsupported, or the documented query/command fails. Source replacement through a cast on a prelinked/bound Builder also throws. **Examples** ```ts builder.setPivotTableReference({ unitId: 'unit', subUnitId: 'source', pivotTableId: 'pivot' }) ``` **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setPosition` Stores an A1 or zero-based row/column anchor with CSS px offsets, clearing detached absolute position. No command runs; placement is validated on insert/update. ```typescript setPosition(anchor: SheetSlicerAnchorSpec): this ``` **Parameters** - `anchor` — Required. A1 cell or zero-based row/column anchor with CSS px offsets. **Returns** This detached Builder for chaining; no command has run. **Examples** ```ts builder.setPosition('J2') ``` **Types:** [`SheetSlicerAnchorSpec`](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/types.d.ts) **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setScrollPosition` Stores detached navigation position to a finite Excel serial in the Workbook date system. Fractional serials are allowed; this is NOT an item index, CSS px or a filter range. Only this detached configuration changes; no command or model write runs. Validation occurs on insert/update. ```typescript setScrollPosition(position: number): this ``` **Parameters** - `position` — Required. Finite Excel serial navigation position, including fractional values. **Returns** This detached Builder for chaining; no command has run. **Examples** ```ts builder.setScrollPosition(44927.5) ``` **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setSelectionLevel` Stores detached selection grain using TimelineLevel; display level and shared date range stay unchanged. Only this detached configuration changes; no command or model write runs. Validation occurs on insert/update. ```typescript setSelectionLevel(level: TimelineLevel): this ``` **Parameters** - `level` — Required. Owner TimelineLevel value for this per-view grain. **Returns** This detached Builder for chaining; no command has run. **Examples** ```ts builder.setSelectionLevel(univerAPI.Enum.TimelineLevel.Day) ``` **Types:** [`TimelineLevel`](https://unpkg.com/@univerjs-pro/slicer/lib/types/definition.d.ts) **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setShowHeader` Stores detached header visibility without changing shared filtering. Only this detached configuration changes; no command or model write runs. Validation occurs on insert/update. ```typescript setShowHeader(visible: boolean): this ``` **Parameters** - `visible` — Required. Whether this per-view element is visible. **Returns** This detached Builder for chaining; no command has run. **Examples** ```ts builder.setShowHeader(true) ``` **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setShowHorizontalScrollbar` Stores detached scrollbar visibility without changing shared filtering. Only this detached configuration changes; no command or model write runs. Validation occurs on insert/update. ```typescript setShowHorizontalScrollbar(visible: boolean): this ``` **Parameters** - `visible` — Required. Whether this per-view element is visible. **Returns** This detached Builder for chaining; no command has run. **Examples** ```ts builder.setShowHorizontalScrollbar(true) ``` **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setShowSelectionLabel` Stores detached selection-label visibility without changing shared filtering. Only this detached configuration changes; no command or model write runs. Validation occurs on insert/update. ```typescript setShowSelectionLabel(visible: boolean): this ``` **Parameters** - `visible` — Required. Whether this per-view element is visible. **Returns** This detached Builder for chaining; no command has run. **Examples** ```ts builder.setShowSelectionLabel(true) ``` **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setShowTimeLevel` Stores detached grain-control visibility without changing shared filtering. Only this detached configuration changes; no command or model write runs. Validation occurs on insert/update. ```typescript setShowTimeLevel(visible: boolean): this ``` **Parameters** - `visible` — Required. Whether this per-view element is visible. **Returns** This detached Builder for chaining; no command has run. **Examples** ```ts builder.setShowTimeLevel(true) ``` **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setSize` Stores finite positive CSS px size in detached configuration without executing a command. Insert/update validates it; omitted insertion sizes default to 220 x 280 (Slicer) or 420 x 140 (Timeline). ```typescript setSize(width: number, height: number): this ``` **Parameters** - `width` — Required. Finite positive width in CSS px. - `height` — Required. Finite positive height in CSS px. **Returns** This detached Builder for chaining; no command has run. **Examples** ```ts builder.setSize(220, 280) ``` **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts) ### `FSheetTimelineBuilder.setStyle` Stores detached style override to an available Workbook builtin/custom style name. Use clearStyle to restore the document default; source/cache/filter are unchanged. Only this detached configuration changes; no command or model write runs. Validation occurs on insert/update. ```typescript setStyle(style: string): this ``` **Parameters** - `style` — Required. Available Workbook builtin/custom style name. **Returns** This detached Builder for chaining; no command has run. **Examples** ```ts builder.setStyle(styleNames[0]) ``` **Package:** [`@univerjs-pro/sheets-slicer`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/sheets-slicer.md) · [Type definitions](https://unpkg.com/@univerjs-pro/sheets-slicer/lib/types/facade/f-timeline-builder.d.ts)