FBaseDashboard

Facade API object bound to one persisted Base Dashboard.

Access

Access through:

• FBase.getDashboards()
• FBase.getDashboardById()
• FBase.createDashboard()

Setup

Register @univerjs-pro/bases-dashboard or a preset that includes it. In plugin mode, import @univerjs-pro/bases-dashboard/facade. Additional methods below require their listed plugin packages. See Facade setup.

@univerjs-pro/bases-dashboard

FBaseDashboard.addFormulaShape

Adds an Engine Shape-backed Formula Shape widget through the command system.

Create shapeData with createFormulaShapeData() from @univerjs-pro/shape-editor; formula evaluation, Doc Model text rendering, and number formatting remain owned by the Shape Engine.

addFormulaShape(tableId: string, options: IAddBaseDashboardFormulaShapeOptions): IBaseDashboardFormulaShapeWidget

Parameters

• tableId — Required. Stable table id used as the formula context.
• options — Required. Engine Shape data, layout, and optional appearance.

Returns

The added Formula Shape widget snapshot.

Throws

If the widget command fails.

Examples

import { ShapeTypeEnum } from '@univerjs-pro/engine-shape'import { createFormulaShapeData } from '@univerjs-pro/shape-editor'dashboard.addFormulaShape('orders', {  id: 'total-revenue',  shapeType: ShapeTypeEnum.RoundRect,  shapeData: createFormulaShapeData({ formula: '=SUM(Orders[Revenue])' }),  appearance: { backgroundColor: '#EEF2FF', textColor: '#4338CA', alignment: 'center' },  layout: { column: 8, row: 2, columnSpan: 4, rowSpan: 4 },})

Types: IBaseDashboardFormulaShapeWidget · IAddBaseDashboardFormulaShapeOptions

Package: @univerjs-pro/bases-dashboard · Type definitions

FBaseDashboard.addImage

Adds an Image widget through the command system.

For uploaded files, save the file with IImageIoService.saveImage() first. Pass the result's source as source and imageSourceType as sourceType. This model Facade never performs file selection or upload UI work.

addImage(options: IAddBaseDashboardImageOptions): IBaseDashboardImageWidget

Parameters

• options — Required. Persisted image source, layout, and presentation settings.

Returns

The added Image widget snapshot.

Throws

If the widget command fails.

Examples

import { ImageSourceType } from '@univerjs/core'dashboard.addImage({  id: 'strategy-image',  source: 'https://example.com/strategy.png',  sourceType: ImageSourceType.URL,  alt: 'FY26 growth strategy',  displayMode: 'cover',  layout: { column: 4, row: 2, columnSpan: 4, rowSpan: 4 },})

Types: IBaseDashboardImageWidget · IAddBaseDashboardImageOptions

Package: @univerjs-pro/bases-dashboard · Type definitions

FBaseDashboard.addPivotChart

Adds a Chart widget that references calculation data owned by a Pivot View.

The widget stores only the table and Pivot View ids plus optional Dashboard-local presentation overrides. Pivot fields, filters, sorting, and aggregation remain owned by the referenced Pivot View.

addPivotChart(tableId: string, pivotViewId: string, options: IAddBaseDashboardPivotChartOptions): IBaseDashboardPivotChartWidget

Parameters

• tableId — Required. Stable source table id.
• pivotViewId — Required. Stable Pivot View id in the source table.
• options — Required. Widget layout and optional presentation overrides.

Returns

The added widget snapshot.

Throws

If the widget command fails.

Examples

const widget = dashboard.addPivotChart('orders', 'revenue-pivot', {  layout: { column: 0, row: 0, columnSpan: 6, rowSpan: 6 },})

Types: IBaseDashboardPivotChartWidget · IAddBaseDashboardPivotChartOptions

Package: @univerjs-pro/bases-dashboard · Type definitions

FBaseDashboard.addTableFilter

Adds a Base table Filter widget through the command system.

The Filter widget stores a normal Base IFilterConfig; Dashboard rendering and sidebar editing remain UI concerns. Omit filter to create an empty control that the user can configure later.

addTableFilter(tableId: string, options: IAddBaseDashboardTableFilterOptions): IBaseDashboardTableFilterWidget

Parameters

• tableId — Required. Stable source table id.
• options — Required. Widget layout and optional initial Filter.

Returns

The added Filter widget snapshot.

Throws

If the widget command fails.

Examples

import { BaseFilterConjunction, BaseFilterOperator } from '@univerjs/core'dashboard.addTableFilter('orders', {  id: 'region-filter',  layout: { column: 0, row: 0, columnSpan: 4, rowSpan: 2 },  filter: {    conjunction: BaseFilterConjunction.AND,    conditions: [{ fieldId: 'region', operator: BaseFilterOperator.IS, operand: 'APAC' }],  },})

Types: IBaseDashboardTableFilterWidget · IAddBaseDashboardTableFilterOptions

Package: @univerjs-pro/bases-dashboard · Type definitions

FBaseDashboard.addText

Adds a Text widget backed by a Univer Doc Model snapshot.

Build rich text with the existing RichTextBuilder and pass getData() as document; the Dashboard does not maintain a parallel plain-text format.

addText(options: IAddBaseDashboardTextOptions): IBaseDashboardTextWidget

Parameters

• options — Required. Doc Model, layout, and optional appearance.

Returns

The added Text widget snapshot.

Throws

If the widget command fails.

Examples

import { RichTextBuilder } from '@univerjs/core'dashboard.addText({  id: 'summary',  document: RichTextBuilder.create().text('Revenue increased by 18%.').getData(),  appearance: { backgroundColor: '#F8FAFC', textColor: '#111827', alignment: 'left' },  layout: { column: 0, row: 2, columnSpan: 4, rowSpan: 4 },})

Types: IBaseDashboardTextWidget · IAddBaseDashboardTextOptions

Package: @univerjs-pro/bases-dashboard · Type definitions

FBaseDashboard.delete

Deletes this Dashboard through the command system.

delete(): boolean

Returns

Whether the command succeeded.

Examples

dashboard.delete()

Package: @univerjs-pro/bases-dashboard · Type definitions

FBaseDashboard.getId

Returns the stable Dashboard id.

getId(): string

Returns

Stable Dashboard id.

Examples

const dashboardId = dashboard.getId()

Package: @univerjs-pro/bases-dashboard · Type definitions

FBaseDashboard.getName

Returns the human-readable Dashboard name.

getName(): string

Returns

Dashboard name.

Examples

const name = dashboard.getName()

Package: @univerjs-pro/bases-dashboard · Type definitions

FBaseDashboard.getPermission

Returns the Dashboard object permission facade.

canEdit() combines the Base unit and Dashboard object Edit points. Changing this permission does not affect other Dashboards in the same Base.

getPermission(): FBaseObjectPermission

Returns

Permission facade for this Dashboard.

Examples

Make one Dashboard read-only and restore it

const base = univerAPI.getActiveBase()const dashboard = base?.getDashboards()[0]if (!dashboard) throw new Error('Dashboard not found.')await dashboard.getPermission().setReadOnly()console.log(dashboard.getPermission().canEdit()) // falseawait dashboard.getPermission().setEditable()

Types: FBaseObjectPermission

Package: @univerjs-pro/bases-dashboard · Type definitions

FBaseDashboard.getSnapshot

Returns a detached snapshot of the Dashboard.

getSnapshot(): IBaseDashboardSnapshot

Returns

Dashboard snapshot safe for local inspection or editing.

Throws

If the Dashboard has been deleted.

Examples

const snapshot = dashboard.getSnapshot()console.log(snapshot.widgetOrder)

Types: IBaseDashboardSnapshot

Package: @univerjs-pro/bases-dashboard · Type definitions

FBaseDashboard.getWidgetById

Returns one widget by id.

getWidgetById(widgetId: string): IBaseDashboardWidget | null

Parameters

• widgetId — Required. Stable Dashboard-local widget id.

Returns

Detached widget snapshot, or null when absent.

Examples

const widget = dashboard.getWidgetById('revenue-chart')

Types: IBaseDashboardWidget

Package: @univerjs-pro/bases-dashboard · Type definitions

FBaseDashboard.getWidgets

Returns all widgets in persisted display order.

getWidgets(): IBaseDashboardWidget[]

Returns

Detached widget snapshots.

Examples

const widgets = dashboard.getWidgets()

Types: IBaseDashboardWidget

Package: @univerjs-pro/bases-dashboard · Type definitions

FBaseDashboard.moveWidget

Moves an existing widget to a new persisted display position.

This changes widgetOrder, not the widget's grid layout. Use upsertWidget() to change layout.

moveWidget(widgetId: string, index: number): boolean

Parameters

• widgetId — Required. Stable Dashboard-local widget id.
• index — Required. Zero-based target position in the widget order.

Returns

Whether the move command succeeded; false when the widget does not exist.

Examples

dashboard.moveWidget('total-revenue', 0)

Package: @univerjs-pro/bases-dashboard · Type definitions

FBaseDashboard.removeWidget

Removes one widget through the command system.

removeWidget(widgetId: string): boolean

Parameters

• widgetId — Required. Stable Dashboard-local widget id.

Returns

Whether the command succeeded.

Examples

dashboard.removeWidget('revenue-chart')

Package: @univerjs-pro/bases-dashboard · Type definitions

FBaseDashboard.setName

Renames the Dashboard through the command system.

setName(name: string): boolean

Parameters

• name — Required. New human-readable Dashboard name.

Returns

Whether the command succeeded.

Examples

dashboard.setName('FY 2026 overview')

Package: @univerjs-pro/bases-dashboard · Type definitions

FBaseDashboard.upsertWidget

Adds or replaces a widget through the command system.

Pass an existing widget id to update that widget. A new id appends the widget unless index is provided.

upsertWidget(widget: IBaseDashboardWidget, index?: number): boolean

Parameters

• widget — Required. Complete widget snapshot.
• index — Optional. Optional zero-based position in the widget order.

Returns

Whether the command succeeded.

Examples

import { BaseDashboardWidgetType } from '@univerjs-pro/bases-dashboard'dashboard.upsertWidget({  id: 'filter-status',  type: BaseDashboardWidgetType.TableFilter,  tableId: 'orders',  filter: null,  layout: { column: 0, row: 0, columnSpan: 3, rowSpan: 2 },})

Types: IBaseDashboardWidget

Package: @univerjs-pro/bases-dashboard · Type definitions