# FBaseTableField

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

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

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

- Requested language: `zh-CN`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

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:

* [`FBaseTable.getFields()`](https://docs.univer.ai/zh-CN/reference/facade/base-table.md#getfields)
* [`FBaseTable.getFieldById()`](https://docs.univer.ai/zh-CN/reference/facade/base-table.md#getfieldbyid)
* [`FBaseTable.getFieldByName()`](https://docs.univer.ai/zh-CN/reference/facade/base-table.md#getfieldbyname)
* [`FBaseTable.getPrimaryField()`](https://docs.univer.ai/zh-CN/reference/facade/base-table.md#getprimaryfield)
* [`FBaseTable.addField()`](https://docs.univer.ai/zh-CN/reference/facade/base-table.md#addfield)
* [`FBaseTableView.getVisibleFields()`](https://docs.univer.ai/zh-CN/reference/facade/base-table-view.md#getvisiblefields)

## Example

Update field metadata

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

## `@univerjs-pro/bases`

### `FBaseTableField.changeType`

Change this field type.

```typescript
changeType(type: BaseFieldType.Formula, config: FieldConfig, options: IBaseFormulaFieldWriteOptions): boolean
changeType(type: Exclude<BaseFieldType, BaseFieldType.Formula>, config?: FieldConfig): boolean
changeType(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**

```ts
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`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts) · [`FieldConfig`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts) · [`IBaseFormulaFieldWriteOptions`](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-field.d.ts) · [`Exclude`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`BaseFieldType`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts)

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

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

```ts
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`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-field.d.ts)

### `FBaseTableField.getConfig`

Get the field configuration.

```typescript
getConfig(): FieldConfig
```

**Returns**

The field configuration.

**Examples**

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

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

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

### `FBaseTableField.getDefaultValue`

Get the default value configured for this field.

```typescript
getDefaultValue(): IFieldSnapshot['defaultValue']
```

**Returns**

The default value for this field, if any.

**Examples**

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

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

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

### `FBaseTableField.getDescription`

Get the field description.

```typescript
getDescription(): string | undefined
```

**Returns**

The field description, if any.

**Examples**

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

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

### `FBaseTableField.getField`

Get the field snapshot.

```typescript
getField(): IFieldSnapshot
```

**Returns**

The field snapshot.

**Examples**

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

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

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

### `FBaseTableField.getId`

Get the field id.

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

**Returns**

The field id.

**Examples**

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

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

### `FBaseTableField.getName`

Get the field name.

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

**Returns**

The field name.

**Examples**

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

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

### `FBaseTableField.getPermission`

Returns the Field object permission facade.

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

**Returns**

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

**Examples**

```ts
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`](https://docs.univer.ai/zh-CN/reference/facade/base-object-permission.md)

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

### `FBaseTableField.getType`

Get the field type.

```typescript
getType(): BaseFieldType
```

**Returns**

The field type.

**Examples**

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

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

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

### `FBaseTableField.isReadonly`

Check whether this field is readonly.

```typescript
isReadonly(): boolean
```

**Returns**

True if the field is readonly, false otherwise.

**Examples**

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

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

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

```ts
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`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-field.d.ts)

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

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

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

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

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

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

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

```ts
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`](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/bases.md) · [Type definitions](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-field.d.ts)

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

```ts
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`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IFieldSnapshot`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/bases/typedef.d.ts) · [`IBaseFormulaFieldWriteOptions`](https://unpkg.com/@univerjs-pro/bases@1.0.0-rc.0/lib/types/facade/f-field.d.ts)

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