FBase

Facade API object bound to a Base unit.

Access

Access through:

• FUniver.createBase()
• FUniver.getActiveBase()
• FUniver.getBase()
• FUniver.getBases()

Setup

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

@univerjs-pro/bases

FBase.deleteTable

Delete a table from this Base.

deleteTable(table: FBaseTable | string): boolean

Parameters

• table — Required. The table facade instance or table id to delete.

Returns

True if the table was deleted, false if it did not exist.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTables()[1]if (fBaseTable) {  const result = fBase.deleteTable(fBaseTable)  console.log(result)}

const fBase = univerAPI.getActiveBase()const result = fBase.deleteTable('table-1')console.log(result)

Types: FBaseTable

Package: @univerjs-pro/bases · Type definitions

FBase.duplicateTable

Duplicate a table in this Base.

duplicateTable(table: FBaseTable | string, options?: { includeRecords?: boolean; regenerateViewIds?: boolean; }): FBaseTable

Parameters

• table — Required. The table facade instance or table id to duplicate.
• options — Optional. Optional parameters for table duplication.

Returns

The newly duplicated table facade.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTables()[0]if (fBaseTable) {  const fBaseTableCopy = fBase.duplicateTable(fBaseTable, { includeRecords: true })  console.log(fBaseTableCopy)}

Types: FBaseTable

Package: @univerjs-pro/bases · Type definitions

FBase.getBase

Get the underlying Base data model.

getBase(): BaseDataModel

Returns

The underlying Base data model.

Examples

const fBase = univerAPI.getActiveBase()console.log(fBase.getBase())

Types: BaseDataModel

Package: @univerjs-pro/bases · Type definitions

FBase.getId

Get the Base unit id.

getId(): string

Returns

The Base unit id.

Examples

const fBase = univerAPI.getActiveBase()console.log(fBase.getId())

Package: @univerjs-pro/bases · Type definitions

FBase.getName

Get the Base name.

getName(): string

Returns

The Base name.

Examples

const fBase = univerAPI.getActiveBase()console.log(fBase.getName())

Package: @univerjs-pro/bases · Type definitions

FBase.getPermission

Returns the Base unit permission facade.

getPermission(): FBasePermission

Returns

Permission facade for Edit, Copy, Export, and Comment.

Examples

const base = univerAPI.getActiveBase()if (!base) throw new Error('No active Base.')await base.getPermission().setReadOnly()

Types: FBasePermission

Package: @univerjs-pro/bases · Type definitions

FBase.getSchema

Get a compact schema snapshot for agent/tooling use.

getSchema() intentionally omits row values. Use it when an agent, server route, or prompt needs structure and ids without transferring the full data payload.

getSchema(): IBaseSchemaSnapshot

Returns

The compact Base schema snapshot.

Examples

const fBase = univerAPI.getActiveBase()console.log(fBase.getSchema())

Types: IBaseSchemaSnapshot

Package: @univerjs-pro/bases · Type definitions

FBase.getTableById

Get a table by id.

getTableById(tableId: string): FBaseTable | null

Parameters

• tableId — Required. The table id.

Returns

The table facade, or null if the table does not exist.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')console.log(fBaseTable)

Types: FBaseTable

Package: @univerjs-pro/bases · Type definitions

FBase.getTableByName

Get a table by its human-readable display name.

This method does not look up the stable identifier used in formulas. To author a structured reference, get the table first and call FBaseTable.getFormulaName().

getTableByName(displayName: string): FBaseTable | null

Parameters

• displayName — Required. The table display name.

Returns

The table facade, or null if the table does not exist.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableByName('Tasks')console.log(fBaseTable)

Types: FBaseTable

Package: @univerjs-pro/bases · Type definitions

FBase.getTables

Get all existing tables in this Base.

getTables(): FBaseTable[]

Returns

The table facade instances.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTables = fBase.getTables()console.log(fBaseTables)

Types: FBaseTable

Package: @univerjs-pro/bases · Type definitions

FBase.insertTable

Insert a new table into the Base.

The display name becomes an Excel worksheet name during export. It must contain 1-31 characters, not start or end with an apostrophe, not contain : \\ / ? * [ ], and be unique within the Base (case-insensitive). It may differ from the stable formula name. Use the returned table's getFormulaName() when authoring structured references.

insertTable(displayName: string, options?: { index?: number; table?: Partial<Omit<ITableSnapshot, 'id'>>; primaryFieldName?: string; }): FBaseTable

Parameters

• displayName — Required. The human-readable table display name.
• options — Optional. Optional parameters for table creation.

Returns

The newly created table facade.

Throws

If the effective display name violates the Excel worksheet-name rules. The error includes both the complete contract and the specific reason, so callers and agents can correct the input before retrying.

Examples

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.insertTable('Risk tracker')console.log(fBaseTable.getName()) // Human-readable display name: "Risk tracker"console.log(fBaseTable.getFormulaName()) // Stable name for formulas: "Risk_tracker"

Full table creation flow

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.insertTable('Tasks', {  index: 0,  primaryFieldName: 'Title',})const field = fBaseTable.addField('Status', univerAPI.Enum.BaseFieldType.SingleSelect, {  index: 1,  field: {    config: {      options: [        { id: 'todo', name: 'Todo', color: 'blue' },        { id: 'done', name: 'Done', color: 'green' },      ],    },  },})const progress = fBaseTable.addField('Progress', univerAPI.Enum.BaseFieldType.Progress)const record = fBaseTable.addRecord(  {    Status: 'todo',    Progress: 10,  },  univerAPI.Enum.BaseFieldKeyEnum.Name,)console.log(fBaseTable.getTable())

Types: FBaseTable · Partial · Omit · ITableSnapshot

Package: @univerjs-pro/bases · Type definitions

FBase.save

Save and return the current complete Base snapshot.

This method intentionally returns the full in-memory IBaseSnapshot instead of performing I/O. The payload includes tables, fields, views, records, cell data, resources, table order, and metadata. The caller decides how to persist it, for example by sending it to the server-side protocol adapter.

save(): IBaseSnapshot

Returns

The current complete Base snapshot.

Examples

const fBase = univerAPI.getActiveBase()console.log(fBase.save())

Types: IBaseSnapshot

Package: @univerjs-pro/bases · Type definitions

FBase.setName

Set the Base name.

setName(name: string): void

Parameters

• name — Required. The new Base name.

Examples

const fBase = univerAPI.getActiveBase()fBase.setName('Product Roadmap')console.log(fBase.getName())

Package: @univerjs-pro/bases · Type definitions

@univerjs-pro/bases-dashboard

FBase.createDashboard

Creates an empty Dashboard through the command system, including undo and redo support.

createDashboard(name: string, options?: ICreateBaseDashboardOptions): FBaseDashboard

Parameters

• name — Required. Human-readable Dashboard name.
• options — Optional. Stable id and insertion position.

Returns

The created Dashboard Facade.

Throws

If the Dashboard cannot be created, for example because its id already exists.

Examples

const base = univerAPI.getActiveBase()if (!base) {  throw new Error('No active Base.')}const dashboard = base.createDashboard('Executive overview', { id: 'executive' })

Types: FBaseDashboard · ICreateBaseDashboardOptions

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

FBase.createPivotView

Creates a Pivot View backed by the target table.

The default Pivot snapshot is produced by engine-pivot, while the default Chart is a column Chart. Use the returned Facade's getPivotTable() to configure rows, columns, filters, values, and aggregation with the Engine API, then persist the resulting snapshot with updateConfig().

createPivotView(name: string, tableId: string, options?: ICreateBasePivotViewOptions): FBasePivotView

Parameters

• name — Required. Human-readable Pivot View name.
• tableId — Required. Stable source table id.
• options — Optional. Stable id, insertion position, and initial configuration.

Returns

The created Pivot View Facade.

Throws

If the table does not exist or the Pivot View cannot be created.

Examples

const base = univerAPI.getActiveBase()if (!base) {  throw new Error('No active Base.')}const pivot = base.createPivotView('Revenue by region', 'orders')

Types: FBasePivotView · ICreateBasePivotViewOptions

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

FBase.getDashboardById

Returns a Dashboard by id.

getDashboardById(dashboardId: string): FBaseDashboard | null

Parameters

• dashboardId — Required. Stable Dashboard id.

Returns

The Dashboard Facade, or null when absent.

Examples

const dashboard = univerAPI.getActiveBase()?.getDashboardById('executive')

Types: FBaseDashboard

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

FBase.getDashboards

Returns all Dashboards in persisted order.

getDashboards(): FBaseDashboard[]

Returns

Dashboard Facades for this Base.

Examples

const base = univerAPI.getActiveBase()const dashboards = base?.getDashboards() ?? []

Types: FBaseDashboard

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

FBase.getPivotView

Returns a Pivot View by id.

getPivotView(tableId: string, viewId: string): FBasePivotView | null

Parameters

• tableId — Required. Stable table id.
• viewId — Required. Stable Pivot View id.

Returns

The Pivot View Facade, or null when absent or not a Pivot View.

Examples

const pivot = univerAPI.getActiveBase()?.getPivotView('orders', 'revenue-pivot')

Types: FBasePivotView

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

FBase.getPivotViews

Returns all Pivot Views in a table's persisted view order.

getPivotViews(tableId: string): FBasePivotView[]

Parameters

• tableId — Required. Stable table id.

Returns

Pivot View Facades, or an empty array when the table does not exist.

Examples

const pivots = univerAPI.getActiveBase()?.getPivotViews('orders') ?? []

Types: FBasePivotView

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