FSheetSlicer

A live Slicer 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.getSlicerById()
• FWorksheet.insertSlicer()
• FWorksheet.getSlicer()
• FWorksheet.getSlicers()

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

FSheetSlicer.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

FSheetSlicer.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

FSheetSlicer.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

FSheetSlicer.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

FSheetSlicer.getCache

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

getCache(): DeepReadonly<SlicerCacheDefinition> | undefined

Returns

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

Examples

const cache = control.getCache()

Types: DeepReadonly · SlicerCacheDefinition

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

FSheetSlicer.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

FSheetSlicer.getCacheOptions

Returns defensive options shared by every view of this Slicer cache, or undefined when unavailable.

getCacheOptions(): DeepReadonly<SheetSlicerCacheOptions> | undefined

Returns

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

Examples

const options = control.getCacheOptions()

Types: DeepReadonly · SheetSlicerCacheOptions

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

FSheetSlicer.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 report targets, or [] for a Table source.

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

FSheetSlicer.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

FSheetSlicer.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

FSheetSlicer.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

FSheetSlicer.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

FSheetSlicer.getInfo

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

getInfo(): DeepReadonly<ISheetSlicerInfo>

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: ISheetSlicerInfo · DeepReadonly

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

FSheetSlicer.getItems

Queries a bounded defensive window of raw typed members with hasData and the real total, not all members. Defaults to start 0/count 100, capped by business maxMemberWindowSize (default 200). start/count must be finite integers, start >= 0 and count > 0. AbortSignal, source invalidation, missing source and unit/plugin disposal reject instead of fabricating empty results. Reads do not set selection/startItem; UI/callers format labels.

getItems(request?: ISheetSlicerItemsRequest): Promise<ISlicerSourceMemberWindow>

Parameters

• request — Optional. Finite integer window start/count and optional cancellation signal.

Returns

A bounded defensive member window with hasData and the real total.

Throws

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

Examples

const window = await control.getItems({ start: 0, count: 100 })

Types: ISlicerSourceMemberWindow · Promise · ISheetSlicerItemsRequest

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

FSheetSlicer.getSelection

Returns the current shared field selection, or undefined when the hosted view/cache is missing. Table selection reads the native source and returns undefined when that source is unavailable; retained Pivot cache selection remains readable after source loss. Table condition/color/manual native filters return restricted mode markers, not their full configuration or guessed includes. Typed Blank is distinct from the literal "(blanks)"; deleted source values remain filter conditions.

getSelection(): DeepReadonly<TableSlicerSelection> | undefined

Returns

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

Examples

const selection = control.getSelection()

Types: DeepReadonly · TableSlicerSelection

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

FSheetSlicer.getSettings

Returns defensive per-view settings in CSS px, or undefined when the hosted view is missing. Row heights are read as persisted EMU / 9525 and may reflect integer EMU rounding.

getSettings(): DeepReadonly<SheetSlicerSettings> | undefined

Returns

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

Examples

const settings = control.getSettings()

Types: DeepReadonly · SheetSlicerSettings

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

FSheetSlicer.getSource

Returns a defensive current source snapshot; source identities cannot be replaced on a live control.

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

FSheetSlicer.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

FSheetSlicer.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

FSheetSlicer.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

FSheetSlicer.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

FSheetSlicer.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

FSheetSlicer.setCacheOptions

Patches shared sortOrder/customListSort/crossFilter/hideItemsWithNoData at transaction execution time. Affects every cache view; preserves locked source, selection and connections. Own undefined clears optional options.

setCacheOptions(patch: Partial<SheetSlicerCacheOptions>): 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.setCacheOptions({  sortOrder: univerAPI.Enum.SlicerCacheSortOrder.Ascending,})

Types: Promise · Partial · SheetSlicerCacheOptions

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

FSheetSlicer.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

FSheetSlicer.setColumnCount

Sets this view button column count to an integer in [1, 20000], without changing shared filtering.

setColumnCount(count: number): Promise<boolean>

Parameters

• count — Required. Integer button column count in [1, 20000].

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.setColumnCount(2)

Types: Promise

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

FSheetSlicer.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

FSheetSlicer.setLockedPosition

Sets this view persisted position-lock flag, not a shared filter or transient gesture state.

setLockedPosition(locked: boolean): Promise<boolean>

Parameters

• locked — Required. Persisted per-view position-lock flag.

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.setLockedPosition(true)

Types: Promise

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

FSheetSlicer.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

FSheetSlicer.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

FSheetSlicer.setRowHeight

Sets this view item row height in finite positive CSS px, without changing shared filtering. Persists Math.round(height * 9525) as a positive unsigned integer EMU (at most 4294967295); reads divide by 9525.

setRowHeight(height: number): Promise<boolean>

Parameters

• height — Required. Finite positive CSS px height (rowHeight converts to rounded EMU).

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.setRowHeight(24)

Types: Promise

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

FSheetSlicer.setSelection

Sets the typed source field selection shared by every cache view and connected report. For Table sources, replaces this column native condition/color/manual filter; other columns are unchanged. Typed Blank differs from the literal "(blanks)". Values outside the current window or absent/deleted from the source remain valid conditions; do not pass labels or item indexes. All clears the field filter.

setSelection(selection: RecordSelection): Promise<boolean>

Parameters

• selection — Required. Typed selection, not a localized label or window index.

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.setSelection({  mode: univerAPI.Enum.FilterSelectionMode.Include,  values: [{ type: univerAPI.Enum.RecordValueType.Blank }],})

Types: Promise · RecordSelection

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

FSheetSlicer.setShowCaption

Sets this view caption visibility without changing its caption or shared filtering.

setShowCaption(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.setShowCaption(true)

Types: Promise

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

FSheetSlicer.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

FSheetSlicer.setStartItem

Sets this view zero-based visible member offset to an unsigned integer [0, 4294967295]. This is navigation, not member identity or shared filter selection.

setStartItem(index: number): Promise<boolean>

Parameters

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

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.setStartItem(0)

Types: Promise

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

FSheetSlicer.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

FSheetSlicer.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

FSheetSlicer.subUnitId

readonly subUnitId: string

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

FSheetSlicer.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(): FBoundSheetSlicerBuilder

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: FBoundSheetSlicerBuilder

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

FSheetSlicer.unitId

readonly unitId: string

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

FSheetSlicer.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: ISheetSlicerInfo): 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 · ISheetSlicerInfo

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

FSheetSlicer.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. Visual dimensions are CSS px; rowHeight persists as Math.round(px * 9525), within the unsigned EMU range.

updateSettings(patch: Partial<SheetSlicerSettings>): 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 · SheetSlicerSettings

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