FSheetTimeline

A live Timeline hosted by a Worksheet Drawing. Source/cache filtering is shared; presentation is per view. All public visual dimensions are CSS pixels. Missing resource placeholders retain Drawing capabilities. Business setters resolve false on ordinary validation/permission refusal. Exceptional inverse-recovery listener failures reject and may require reconciliation of the coherent committed forward state.

Access

Access through:

• FWorkbook.getTimelineById()
• FWorksheet.insertTimeline()
• FWorksheet.getTimeline()
• FWorksheet.getTimelines()

Setup

Register @univerjs-pro/sheets-slicer 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.

@univerjs-pro/sheets-slicer

FSheetTimeline.bringForward

Moves only this Drawing forward one position in the official Worksheet Drawing order; source/cache/filter are unchanged.

bringForward(): this

Returns

This live facade after synchronous command acceptance (or an already-satisfied order); not remotely saved/rendered.

Throws

If the hosted Drawing is unavailable, input is invalid, permission is refused, or the synchronous command fails.

Examples

control.bringForward()

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.bringToFront

Moves only this Drawing to the front of the official Worksheet Drawing order; source/cache/filter are unchanged.

bringToFront(): this

Returns

This live facade after synchronous command acceptance (or an already-satisfied order); not remotely saved/rendered.

Throws

If the hosted Drawing is unavailable, input is invalid, permission is refused, or the synchronous command fails.

Examples

control.bringToFront()

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.clearFilter

Clears the source field filter shared by all views/connected reports of this cache, without deleting the view. For Table sources, clears only the source column native filter; other columns are unchanged.

clearFilter(): Promise<boolean>

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected command/listener errors; presentation inverse-recovery errors may require reconciliation.

Examples

const accepted = await control.clearFilter()

Types: Promise

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.clearStyle

Clears only this view style override with an own undefined value, restoring the document default. Shared cache/source/filter are unchanged.

clearStyle(): Promise<boolean>

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected command/listener errors; presentation inverse-recovery errors may require reconciliation.

Examples

const accepted = await control.clearStyle()

Types: Promise

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.getCache

Returns a defensive shared cache definition in its persisted domain representation, not public px settings.

getCache(): DeepReadonly<ITimelineCacheDefinition> | undefined

Returns

A defensive current value (where applicable), with missing-resource behavior described above.

Examples

const cache = control.getCache()

Types: DeepReadonly · ITimelineCacheDefinition

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.getCacheId

Returns the current shared cache ID, or undefined when the view/cache resource is missing.

getCacheId(): string | undefined

Returns

A defensive current value (where applicable), with missing-resource behavior described above.

Examples

const cacheId = control.getCacheId()

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.getConnectionCandidates

Queries compatible same-Workbook Pivot report targets for this shared source/cache. Table sources return []; missing source/cache rejects. Linked charts normalize to their owner PivotTable.

getConnectionCandidates(): Promise<ISlicerConnectionCandidate[]>

Returns

Compatible same-Workbook Pivot report targets.

Throws

If required source/host data is unavailable, input is unsupported, or the documented query/command fails.

Examples

const candidates = await control.getConnectionCandidates()

Types: ISlicerConnectionCandidate · Promise

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.getConnections

Returns a defensive shared Pivot report connection snapshot; Table sources return undefined.

getConnections(): DeepReadonly<ISheetSlicerConnections> | undefined

Returns

A defensive current value (where applicable), with missing-resource behavior described above.

Examples

const connections = control.getConnections()

Types: DeepReadonly · ISheetSlicerConnections

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.getDateBounds

Queries real inclusive source minDate/maxDate and the Workbook Date1900/Date1904 system. These are Excel serial values, NOT viewport limits or an end-exclusive selection upper bound. Missing reliable bounds remain undefined; source/identity/disposal query failures reject.

getDateBounds(): Promise<{ minDate?: number; maxDate?: number; dateSystem: DateSystem; }>

Returns

Inclusive original-source date bounds and the host Workbook date system.

Throws

If required source/host data is unavailable, input is unsupported, or the documented query/command fails.

Examples

const { minDate, maxDate, dateSystem } = await control.getDateBounds()

Types: DateSystem · Promise

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.getDateRange

Returns the retained shared Excel serial selection [startDate, endDate), including after source loss. Returns undefined when unfiltered or the hosted view/cache is missing; does not validate the current source. Uses the host Workbook Date1900/Date1904 system, not JavaScript Date or viewport bounds.

getDateRange(): DeepReadonly<ITimelineRange> | undefined

Returns

A defensive cached range, or undefined when unfiltered or the hosted view/cache is missing.

Examples

const range = control.getDateRange()

Types: DeepReadonly · ITimelineRange

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.getDrawing

Returns a defensive hosted Drawing snapshot, even for a resource-free placeholder.

getDrawing(): DeepReadonly<ISheetSlicerDrawing> | undefined

Returns

A defensive current value (where applicable), with missing-resource behavior described above.

Examples

const drawing = control.getDrawing()

Types: DeepReadonly · ISheetSlicerDrawing

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.getDrawingId

Returns the official Drawing ID for existing grouping and Drawing APIs.

getDrawingId(): string

Returns

A defensive current value (where applicable), with missing-resource behavior described above.

Examples

const drawingId = control.getDrawingId()

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.getId

Returns the stable business view ID, not the Drawing ID.

getId(): string

Returns

A defensive current value (where applicable), with missing-resource behavior described above.

Examples

const viewId = control.getId()

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.getInfo

Returns detached source, per-view settings and placement in CSS px; it contains no items or filter selection.

getInfo(): DeepReadonly<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

const info = control.getInfo()

Types: ISheetTimelineInfo · DeepReadonly

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.getSettings

Returns defensive per-view settings in CSS px, or undefined when the hosted view is missing.

getSettings(): DeepReadonly<SheetTimelineSettings> | undefined

Returns

A defensive current value (where applicable), with missing-resource behavior described above.

Examples

const settings = control.getSettings()

Types: DeepReadonly · SheetTimelineSettings

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.getSource

Returns a defensive current source snapshot; source identities cannot be replaced on a live control. The public signature uses SheetSlicerSourceSpec, but supported Timelines always resolve a Pivot original date source.

getSource(): DeepReadonly<SheetSlicerSourceSpec> | undefined

Returns

A defensive current value (where applicable), with missing-resource behavior described above.

Examples

const source = control.getSource()

Types: DeepReadonly · SheetSlicerSourceSpec

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.getSourceMetadata

Queries current source metadata without changing filtering or presentation. Missing/unavailable sources and late results after identity/disposal changes reject; this is not a rendered-state query.

getSourceMetadata(): Promise<ISlicerSourceMetadata>

Returns

Current source metadata, not rendered state.

Throws

If required source/host data is unavailable, input is unsupported, or the documented query/command fails.

Examples

const metadata = await control.getSourceMetadata()

Types: ISlicerSourceMetadata · Promise

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.remove

Requests official Sheet Drawing deletion and linked view removal, retaining shared cache and filter conditions. A valid hosted placeholder can be removed even when its view/cache/source is missing. The boolean reports command acceptance, NOT a no-change or rollback guarantee: a Drawing-stage listener refusal can return false after view deletion while the Drawing survives; a later failure can retain Drawing deletion too. Callers can re-read/reconcile committed state. Events describe final hosted state, not the boolean result. Acceptance does not mean remote persistence or rendering.

remove(): Promise<boolean>

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected errors propagated by permission checking or the outer official command. Mutation-sequence stage exceptions are converted to false, without a rollback guarantee.

Examples

const accepted = await control.remove()// Re-read the host when a refusal requires reconciliation.

Types: Promise

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.sendBackward

Moves only this Drawing backward one position in the official Worksheet Drawing order; source/cache/filter are unchanged.

sendBackward(): this

Returns

This live facade after synchronous command acceptance (or an already-satisfied order); not remotely saved/rendered.

Throws

If the hosted Drawing is unavailable, input is invalid, permission is refused, or the synchronous command fails.

Examples

control.sendBackward()

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.sendToBack

Moves only this Drawing to the back of the official Worksheet Drawing order; source/cache/filter are unchanged.

sendToBack(): this

Returns

This live facade after synchronous command acceptance (or an already-satisfied order); not remotely saved/rendered.

Throws

If the hosted Drawing is unavailable, input is invalid, permission is refused, or the synchronous command fails.

Examples

control.sendToBack()

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setAbsolutePosition

Moves only this Drawing to absolute Worksheet CSS px coordinates through the synchronous official command. Preserves size and existing anchoring/group semantics; valid resource-free placeholders remain movable.

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 live facade after synchronous command acceptance (or an already-satisfied order); not remotely saved/rendered.

Throws

If the hosted Drawing is unavailable, input is invalid, permission is refused, or the synchronous command fails.

Examples

control.setAbsolutePosition(100, 80)

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setCaption

Changes only this view caption, not its name or shared source/cache. The caption must be nonempty and at most 32767 characters.

setCaption(caption: string): Promise<boolean>

Parameters

• caption — Required. Nonempty caption, at most 32767 characters; independent of name.

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected command/listener errors; presentation inverse-recovery errors may require reconciliation.

Examples

const accepted = await control.setCaption('Sales')

Types: Promise

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setConnections

Replaces, rather than appends, the shared cache report connections through the existing transaction. Targets must share this Workbook, Pivot cache and source field; duplicates normalize to owners without silently dropping unsupported targets. Linked charts use their owner PivotTable; owned charts use ownedPivotCharts. The source field stays locked. Table sources and ordinary unavailable/invalid targets resolve false.

setConnections(connections: ISheetSlicerConnections): Promise<boolean>

Parameters

• connections — Required. Replacement shared Pivot report reference collections.

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected command/listener errors; presentation inverse-recovery errors may require reconciliation.

Examples

const accepted = await control.setConnections({ pivotTables: connections.pivotTables })

Types: Promise · ISheetSlicerConnections

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setDateRange

Sets the shared Pivot original-date-field filter to Excel serial [startDate, endDate); endDate is excluded. Use finite serials with startDate < endDate in the Workbook Date1900/Date1904 system, not JavaScript Date. Undefined clears filtering. Updates connected reports/cache views, not their independent display/selection levels.

setDateRange(range: ITimelineRange | undefined): Promise<boolean>

Parameters

• range — Required. Half-open Excel serial range, or undefined to clear.

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected command/listener errors; presentation inverse-recovery errors may require reconciliation.

Examples

const accepted = await control.setDateRange({ startDate: 44927, endDate: 44958 })

Types: Promise · ITimelineRange

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setLevel

Sets only this Timeline view display grain using TimelineLevel; shared date range and selectionLevel stay unchanged.

setLevel(level: TimelineLevel): Promise<boolean>

Parameters

• level — Required. Owner TimelineLevel value for this per-view grain.

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected command/listener errors; presentation inverse-recovery errors may require reconciliation.

Examples

const accepted = await control.setLevel(univerAPI.Enum.TimelineLevel.Month)

Types: Promise · TimelineLevel

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setName

Changes only this view name, not its caption or shared source/cache. Names must be nonempty and unique across Workbook Slicers/Timelines (case-insensitive).

setName(name: string): Promise<boolean>

Parameters

• name — Required. Nonempty Workbook-unique view name (case-insensitive).

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected command/listener errors; presentation inverse-recovery errors may require reconciliation.

Examples

const accepted = await control.setName('Sales filter')

Types: Promise

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setPosition

Moves only this Drawing through the synchronous official placement command, preserving size/group semantics. Accepts A1 or zero-based row/column anchors with CSS px offsets; a valid hosted placeholder remains movable. Source/cache/filter are unchanged.

setPosition(anchor: SheetSlicerAnchorSpec): this

Parameters

• anchor — Required. A1 cell or zero-based row/column anchor with CSS px offsets.

Returns

This live facade after synchronous command acceptance (or an already-satisfied order); not remotely saved/rendered.

Throws

If the hosted Drawing is unavailable, input is invalid, permission is refused, or the synchronous command fails.

Examples

control.setPosition('J2')

Types: SheetSlicerAnchorSpec

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setScrollPosition

Sets only this Timeline view 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.

setScrollPosition(position: number): Promise<boolean>

Parameters

• position — Required. Finite Excel serial navigation position, including fractional values.

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected command/listener errors; presentation inverse-recovery errors may require reconciliation.

Examples

const accepted = await control.setScrollPosition(44927.5)

Types: Promise

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setSelectionLevel

Sets only this Timeline view selection grain using TimelineLevel; display level and shared date range stay unchanged.

setSelectionLevel(level: TimelineLevel): Promise<boolean>

Parameters

• level — Required. Owner TimelineLevel value for this per-view grain.

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected command/listener errors; presentation inverse-recovery errors may require reconciliation.

Examples

const accepted = await control.setSelectionLevel(univerAPI.Enum.TimelineLevel.Day)

Types: Promise · TimelineLevel

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setShowHeader

Sets only this Timeline view header visibility without changing shared filtering.

setShowHeader(visible: boolean): Promise<boolean>

Parameters

• visible — Required. Whether this per-view element is visible.

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected command/listener errors; presentation inverse-recovery errors may require reconciliation.

Examples

const accepted = await control.setShowHeader(true)

Types: Promise

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setShowHorizontalScrollbar

Sets only this Timeline view scrollbar visibility without changing shared filtering.

setShowHorizontalScrollbar(visible: boolean): Promise<boolean>

Parameters

• visible — Required. Whether this per-view element is visible.

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected command/listener errors; presentation inverse-recovery errors may require reconciliation.

Examples

const accepted = await control.setShowHorizontalScrollbar(true)

Types: Promise

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setShowSelectionLabel

Sets only this Timeline view selection-label visibility without changing shared filtering.

setShowSelectionLabel(visible: boolean): Promise<boolean>

Parameters

• visible — Required. Whether this per-view element is visible.

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected command/listener errors; presentation inverse-recovery errors may require reconciliation.

Examples

const accepted = await control.setShowSelectionLabel(true)

Types: Promise

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setShowTimeLevel

Sets only this Timeline view grain-control visibility without changing shared filtering.

setShowTimeLevel(visible: boolean): Promise<boolean>

Parameters

• visible — Required. Whether this per-view element is visible.

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected command/listener errors; presentation inverse-recovery errors may require reconciliation.

Examples

const accepted = await control.setShowTimeLevel(true)

Types: Promise

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setSize

Resizes only this Drawing in finite positive CSS px through the synchronous official placement command. Preserves anchor/group semantics; valid resource-free placeholders remain resizable. Source/cache/filter are unchanged.

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 live facade after synchronous command acceptance (or an already-satisfied order); not remotely saved/rendered.

Throws

If the hosted Drawing is unavailable, input is invalid, permission is refused, or the synchronous command fails.

Examples

control.setSize(220, 280)

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setStyle

Sets only this view style override to an available Workbook builtin/custom style name. Use clearStyle to restore the document default; source/cache/filter are unchanged.

setStyle(style: string): Promise<boolean>

Parameters

• style — Required. Available Workbook builtin/custom style name.

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected command/listener errors; presentation inverse-recovery errors may require reconciliation.

Examples

const accepted = await control.setStyle(styleNames[0])

Types: Promise

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.setZOrder

Sets only this Drawing order using the official command and its clamped zero-based order semantics. Source/cache/filter are unchanged; valid resource-free placeholders remain arrangeable.

setZOrder(index: number): this

Parameters

• index — Required. Zero-based order/member offset as described above.

Returns

This live facade after synchronous command acceptance (or an already-satisfied order); not remotely saved/rendered.

Throws

If the hosted Drawing is unavailable, input is invalid, permission is refused, or the synchronous command fails.

Examples

control.setZOrder(0)

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.subUnitId

readonly subUnitId: string

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.toBuilder

Copies configuration into a detached Builder whose source setters remain locked after every fluent call. No command runs; shared filtering/cache state is not duplicated.

toBuilder(): FBoundSheetTimelineBuilder

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

const info = control.toBuilder().setCaption('Sales').setSize(260, 320).build()

Types: FBoundSheetTimelineBuilder

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.unitId

readonly unitId: string

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.update

Atomically updates this view and Drawing placement through one undoable presentation command. Source identity and report connections must match; use setConnections separately. All dimensions are CSS px. Acceptance is local command completion, not remote persistence or rendering. Ordinary refusal rejects. Exceptional inverse-recovery listener failure also rejects and may retain the coherent forward view/Drawing pair; callers can re-read and reconcile that state.

update(info: ISheetTimelineInfo): Promise<this>

Parameters

• info — Required. Detached information with locked source/connections and CSS px presentation.

Returns

This live facade after local command acceptance, not remote persistence/rendering.

Throws

If required source/host data is unavailable, input is unsupported, or the documented query/command fails.

Examples

await control.update(control.toBuilder().setCaption('Sales').setSize(260, 320).build())

Types: Promise · ISheetTimelineInfo

Package: @univerjs-pro/sheets-slicer · Type definitions

FSheetTimeline.updateSettings

Patches this view at command execution time without overwriting unrelated queued settings. Source/cache/connections/filter are unchanged. An own style: undefined clears the override; optional undefined keys clear. Presentation uses this Timeline view settings; date navigation uses finite Workbook Excel serial values.

updateSettings(patch: Partial<SheetTimelineSettings>): Promise<boolean>

Parameters

• patch — Required. Presence-aware typed patch; own undefined clears optional values.

Returns

Whether the command was accepted; false on ordinary validation, permission or business-unavailable refusal.

Throws

The Promise rejects on unexpected command/listener errors; presentation inverse-recovery errors may require reconciliation.

Examples

const accepted = await control.updateSettings({ caption: 'Sales', style: undefined })

Types: Promise · Partial · SheetTimelineSettings

Package: @univerjs-pro/sheets-slicer · Type definitions