# FBaseDashboard

> Language fallback: requested `zh-CN`; content is `en-US`.

- Human documentation: [https://docs.univer.ai/zh-CN/reference/facade/base-dashboard](https://docs.univer.ai/zh-CN/reference/facade/base-dashboard)

- Agent Markdown: [https://docs.univer.ai/zh-CN/reference/facade/base-dashboard.md](https://docs.univer.ai/zh-CN/reference/facade/base-dashboard.md)

- Requested language: `zh-CN`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/base-dashboard.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/base-dashboard.mdx)

---

Facade API object bound to one persisted Base Dashboard.

## Access

Access through:

* [`FBase.getDashboards()`](https://docs.univer.ai/zh-CN/reference/facade/base.md#getdashboards)
* [`FBase.getDashboardById()`](https://docs.univer.ai/zh-CN/reference/facade/base.md#getdashboardbyid)
* [`FBase.createDashboard()`](https://docs.univer.ai/zh-CN/reference/facade/base.md#createdashboard)

## Setup

Register [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) 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](https://docs.univer.ai/zh-CN/guides/bases/getting-started/facade.md).

## `@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.

```typescript
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**

```ts
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`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/types.d.ts) · [`IAddBaseDashboardFormulaShapeOptions`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

### `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.

```typescript
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**

```ts
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`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/types.d.ts) · [`IAddBaseDashboardImageOptions`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

### `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.

```typescript
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**

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

**Types:** [`IBaseDashboardPivotChartWidget`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/types.d.ts) · [`IAddBaseDashboardPivotChartOptions`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

### `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.

```typescript
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**

```ts
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`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/types.d.ts) · [`IAddBaseDashboardTableFilterOptions`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

### `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.

```typescript
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**

```ts
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`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/types.d.ts) · [`IAddBaseDashboardTextOptions`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

### `FBaseDashboard.delete`

Deletes this Dashboard through the command system.

```typescript
delete(): boolean
```

**Returns**

Whether the command succeeded.

**Examples**

```ts
dashboard.delete()
```

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

### `FBaseDashboard.getId`

Returns the stable Dashboard id.

```typescript
getId(): string
```

**Returns**

Stable Dashboard id.

**Examples**

```ts
const dashboardId = dashboard.getId()
```

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

### `FBaseDashboard.getName`

Returns the human-readable Dashboard name.

```typescript
getName(): string
```

**Returns**

Dashboard name.

**Examples**

```ts
const name = dashboard.getName()
```

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

### `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.

```typescript
getPermission(): FBaseObjectPermission
```

**Returns**

Permission facade for this Dashboard.

**Examples**

Make one Dashboard read-only and restore it

```ts
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()) // false
await dashboard.getPermission().setEditable()
```

**Types:** [`FBaseObjectPermission`](https://docs.univer.ai/zh-CN/reference/facade/base-object-permission.md)

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

### `FBaseDashboard.getSnapshot`

Returns a detached snapshot of the Dashboard.

```typescript
getSnapshot(): IBaseDashboardSnapshot
```

**Returns**

Dashboard snapshot safe for local inspection or editing.

**Throws**

If the Dashboard has been deleted.

**Examples**

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

**Types:** [`IBaseDashboardSnapshot`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/types.d.ts)

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

### `FBaseDashboard.getWidgetById`

Returns one widget by id.

```typescript
getWidgetById(widgetId: string): IBaseDashboardWidget | null
```

**Parameters**

* `widgetId` — Required. Stable Dashboard-local widget id.

**Returns**

Detached widget snapshot, or null when absent.

**Examples**

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

**Types:** [`IBaseDashboardWidget`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/types.d.ts)

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

### `FBaseDashboard.getWidgets`

Returns all widgets in persisted display order.

```typescript
getWidgets(): IBaseDashboardWidget[]
```

**Returns**

Detached widget snapshots.

**Examples**

```ts
const widgets = dashboard.getWidgets()
```

**Types:** [`IBaseDashboardWidget`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/types.d.ts)

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

### `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`.

```typescript
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**

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

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

### `FBaseDashboard.removeWidget`

Removes one widget through the command system.

```typescript
removeWidget(widgetId: string): boolean
```

**Parameters**

* `widgetId` — Required. Stable Dashboard-local widget id.

**Returns**

Whether the command succeeded.

**Examples**

```ts
dashboard.removeWidget('revenue-chart')
```

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

### `FBaseDashboard.setName`

Renames the Dashboard through the command system.

```typescript
setName(name: string): boolean
```

**Parameters**

* `name` — Required. New human-readable Dashboard name.

**Returns**

Whether the command succeeded.

**Examples**

```ts
dashboard.setName('FY 2026 overview')
```

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)

### `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.

```typescript
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**

```ts
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`](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/types.d.ts)

**Package:** [`@univerjs-pro/bases-dashboard`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases-dashboard.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases-dashboard@1.0.0-rc.0/lib/types/facade/f-base-dashboard.d.ts)