FBaseTableField

Facade API object bound to a Base field.

A Base field is equivalent to a column in a table. Field type and type-specific config live on the field snapshot. Cell values should reference field ids and should not duplicate field type as their source of truth.

Access

Access through:

Example

Update field metadata

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const field = fBaseTable.getFieldByName('Name')if (field) {  field.setName('Stage')  field.changeType(univerAPI.Enum.BaseFieldType.SingleSelect, {    options: [      { id: 'todo', name: 'To Do', color: 'blue' },      { id: 'inProgress', name: 'In Progress', color: 'yellow' },      { id: 'done', name: 'Done', color: 'green' },    ],  })  field.setDefaultValue('todo')  field.update({ description: 'Workflow stage from server auth.' })}

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`

`FBaseTableField.changeType`

Change this field type.

TypeScript

changeType(type: BaseFieldType.Formula, config: FieldConfig, options: IBaseFormulaFieldWriteOptions): booleanchangeType(type: Exclude<BaseFieldType, BaseFieldType.Formula>, config?: FieldConfig): booleanchangeType(type: BaseFieldType, config: FieldConfig, options: IBaseFormulaFieldWriteOptions): boolean

Parameters

type — Required. The new field type.
config — Required. The new field configuration.
options — Optional. Required when type is Formula.

Returns

True if the type change was successful, false otherwise.

Examples

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const field = fBaseTable.getFieldByName('Status')const success = field.changeType(univerAPI.Enum.BaseFieldType.Number, {  decimalPlaces: 2,})console.log(success ? 'Field type changed' : 'Failed to change field type')

Types: BaseFieldType.Formula · FieldConfig · IBaseFormulaFieldWriteOptions · Exclude · BaseFieldType

Package: @univerjs-pro/bases · Type definitions

`FBaseTableField.delete`

Delete this field.

The table's primary field cannot be deleted. Calling this method on the primary field leaves the table unchanged and returns false.

TypeScript

delete(): boolean

Returns

True if the deletion was successful, false if the field is the primary field or the deletion otherwise failed.

Examples

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const field = fBaseTable.getFieldByName('Status')const success = field.delete()console.log(success ? 'Field deleted' : 'Failed to delete field')

Package: @univerjs-pro/bases · Type definitions

`FBaseTableField.getConfig`

Get the field configuration.

TypeScript

getConfig(): FieldConfig

Returns

The field configuration.

Examples

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const fields = fBaseTable.getFields()console.log(fields[0]?.getConfig())

Types: FieldConfig

Package: @univerjs-pro/bases · Type definitions

`FBaseTableField.getDefaultValue`

Get the default value configured for this field.

TypeScript

getDefaultValue(): IFieldSnapshot['defaultValue']

Returns

The default value for this field, if any.

Examples

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const fields = fBaseTable.getFields()console.log(fields[0]?.getDefaultValue())

Types: IFieldSnapshot

Package: @univerjs-pro/bases · Type definitions

`FBaseTableField.getDescription`

Get the field description.

TypeScript

getDescription(): string | undefined

Returns

The field description, if any.

Examples

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const fields = fBaseTable.getFields()console.log(fields[0]?.getDescription())

Package: @univerjs-pro/bases · Type definitions

`FBaseTableField.getField`

Get the field snapshot.

TypeScript

getField(): IFieldSnapshot

Returns

The field snapshot.

Examples

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const fields = fBaseTable.getFields()console.log(fields[0]?.getField())

Types: IFieldSnapshot

Package: @univerjs-pro/bases · Type definitions

`FBaseTableField.getId`

Get the field id.

TypeScript

getId(): string

Returns

The field id.

Examples

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const fields = fBaseTable.getFields()console.log(fields[0]?.getId())

Package: @univerjs-pro/bases · Type definitions

`FBaseTableField.getName`

Get the field name.

TypeScript

getName(): string

Returns

The field name.

Examples

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const fields = fBaseTable.getFields()console.log(fields[0]?.getName())

Package: @univerjs-pro/bases · Type definitions

`FBaseTableField.getPermission`

Returns the Field object permission facade.

TypeScript

getPermission(): FBaseObjectPermission

Returns

Permission facade combining the Base, Table, and Field Edit points.

Examples

TypeScript

const table = univerAPI.getActiveBase()?.getTables()[0]const field = table?.getFields()[0]if (!field) throw new Error('Field not found.')await field.getPermission().setReadOnly()

Types: FBaseObjectPermission

Package: @univerjs-pro/bases · Type definitions

`FBaseTableField.getType`

Get the field type.

TypeScript

getType(): BaseFieldType

Returns

The field type.

Examples

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const fields = fBaseTable.getFields()console.log(fields[0]?.getType())

Types: BaseFieldType

Package: @univerjs-pro/bases · Type definitions

`FBaseTableField.isReadonly`

Check whether this field is readonly.

TypeScript

isReadonly(): boolean

Returns

True if the field is readonly, false otherwise.

Examples

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const fields = fBaseTable.getFields()console.log(fields[0]?.isReadonly())

Package: @univerjs-pro/bases · Type definitions

`FBaseTableField.move`

Move this field relative to another field.

TypeScript

move(target: { beforeFieldId?: string; afterFieldId?: string; }): boolean

Parameters

target — Required. The target field to move before or after.

Returns

True if the move was successful, false otherwise.

Examples

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const field = fBaseTable.getFieldByName('Status')const success = field.move({ afterFieldId: 'Priority' })console.log(success ? 'Field moved' : 'Failed to move field')

Package: @univerjs-pro/bases · Type definitions

`FBaseTableField.setConfig`

Replace the field configuration.

Config is type-specific. Keep select options, attachment restrictions, formula expressions, number/date formatting, and similar field metadata here so formulas and renderers can resolve behavior from the field.

Formula fields additionally require options.externalReferences. The Facade persists those Host bindings before it updates the field config; if binding fails, the field is left unchanged. Pass [] only when the formula references fields in this Host Base and has no external Unit qualifier.

TypeScript

setConfig(config: FieldConfig, options?: IBaseFormulaFieldWriteOptions): boolean

Parameters

config — Required. The new field configuration.
options — Optional. Required for Formula fields.

Returns

True if the config update was successful, false otherwise.

Examples

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const field = fBaseTable.getFieldByName('Total')const success = field.setConfig(  {    formula: '=SUM([Pricing]!Tax[Amount])',    numberFormat: {      type: 'currency',      pattern: '"$"#,##0.00',    },  },  {    externalReferences: [      {        qualifier: 'Pricing',        sourceUnitId: 'pricing-base',        sourceUnitType: univerAPI.Enum.UniverInstanceType.UNIVER_BASE,      },    ],  },)console.log(success ? 'Field config updated' : 'Failed to update field config')

Types: FieldConfig · IBaseFormulaFieldWriteOptions

Package: @univerjs-pro/bases · Type definitions

`FBaseTableField.setDefaultValue`

Set the default value for this field.

TypeScript

setDefaultValue(defaultValue: IFieldSnapshot['defaultValue']): boolean

Parameters

defaultValue — Required. The new default value.

Returns

True if the default value update was successful, false otherwise.

Examples

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const field = fBaseTable.getFieldByName('Status')const success = field.setDefaultValue('todo')console.log(success ? 'Default value set' : 'Failed to set default value')

Types: IFieldSnapshot

Package: @univerjs-pro/bases · Type definitions

`FBaseTableField.setName`

Rename this field.

TypeScript

setName(name: string): boolean

Parameters

name — Required. The new field name.

Returns

True if the rename was successful, false otherwise.

Examples

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const field = fBaseTable.getFieldByName('Status')const success = field.setName('Priority')console.log(success ? 'Field renamed' : 'Failed to rename field')

Package: @univerjs-pro/bases · Type definitions

`FBaseTableField.update`

Update this field. When this operation writes Formula config or changes the field type to Formula, options.externalReferences is required. Metadata-only updates to an existing Formula field, such as changing its name or description, do not need the mapping again.

TypeScript

update(patch: Partial<IFieldSnapshot>, options?: IBaseFormulaFieldWriteOptions): boolean

Parameters

patch — Required. The field snapshot patch to apply.
options — Optional. Required when this update writes a Formula field.

Returns

True if the update was successful, false otherwise.

Examples

TypeScript

const fBase = univerAPI.getActiveBase()const fBaseTable = fBase.getTableById('table-1')const field = fBaseTable.getFieldByName('Status')const success = field.update({  name: 'Stage',  description: 'Workflow stage from server auth.',})console.log(success ? 'Field updated' : 'Failed to update field')

Types: Partial · IFieldSnapshot · IBaseFormulaFieldWriteOptions

Package: @univerjs-pro/bases · Type definitions

How is this guide?