Fields

Fields define the schema of a Base table. Each field has a type, configuration, default value, and capabilities such as sorting, filtering, grouping, or card display.

Field types

Use option IDs for select values and application member IDs for people and groups. Numbering and audit fields are system-managed. See Formulas for calculations and Records, links, and hierarchy for relationships.

Add fields

const table = base.getTableById('tasks')if (!table) throw new Error('Tasks table not found')const title = table.addField('Title', univerAPI.Enum.BaseFieldType.Text)const priority = table.addField(  'Priority',  univerAPI.Enum.BaseFieldType.SingleSelect,  {    field: {      config: {        options: [          { id: 'high', name: 'High', color: '#ef4444' },          { id: 'low', name: 'Low', color: '#22c55e' },        ],      },    },  },)

Update fields

priority.setName('Impact')priority.update({ description: 'Business priority' })priority.setConfig({  options: [    { id: 'p0', name: 'P0', color: '#dc2626' },    { id: 'p1', name: 'P1', color: '#f97316' },  ],})

Change field type

priority.changeType(univerAPI.Enum.BaseFieldType.Text, {})

Changing a field type may normalize existing values. Validate data in your application before applying schema changes to production tables.

Attachment fields

Attachments need a stable ID, name, and accessible source. This example assumes your application has already uploaded the file:

const attachments = table.addField('Files', univerAPI.Enum.BaseFieldType.Attachment)const record = table.getRecords()[0]if (!record) throw new Error('Create a record first')record.setAttachments(attachments.getId(), [{  id: 'brief-1',  name: 'brief.pdf',  mimeType: 'application/pdf',  source: 'https://example.com/files/brief.pdf',}])

setAttachments() replaces the whole cell's attachment list. Use getAttachments() to read it and deleteAttachments() to remove selected entries. Replace the example URL with an accessible file address.

Configure upload handling in your existing Bases UI registration:

univer.registerPlugin(UniverBasesUIPlugin, {  attachment: {    accept: ['image/*', '.pdf'],    maxSize: 10 * 1024 * 1024,    upload: uploadAttachment,  },})

uploadAttachment is your application function, with signature (file: File) => Promise<IBaseAttachment>, returning attachment data like the example above. maxSize is in bytes. Without a custom uploader, the plugin tries image IO and then Base64, which increases snapshot size. For production, connect file storage and validate file type, size, and download permissions on the backend.

People and groups

Provide picker candidates through the Bases UI plugin's personOptions and groupOptions. Each item has id, name, and optional avatar. These options configure display only; your application still owns login and access permissions.