Web SDK

单元格数据结构

单元格位置

Univer Sheets 中的单元格数据存储在 IWorksheetData 的 cellData 字段中，cellData 是一个二维 Map 结构，一二级索引分别代表行号和列号，每一个单元格是一个 ICellData 对象，包含了单元格值、样式、类型等所有单元格信息。

cellData 的结构如下

TypeScript
interface IWorksheetData {  cellData: {    // 第一行    0: {      // 第一列      0: { v: 'A1' }      // 第二列      1: { v: 'B1' }    }    // 第二行    1: {      // 第一列      0: { v: 'A2' }      // 第二列      1: { v: 'B2' }    }  }}

单元格信息

完整的单元格信息如下。

属性说明
v单元格的原始值
s单元格的样式 id 或者样式对象
t单元格的类型
p富文本，同时也是一个 📝 Univer Docs
f公式
si公式 ID
custom自定义字段

详细了解 ICellData 每个字段的类型信息。

单元格原始值

cellData.v 存储了单元格的原始值，可以为字符串或者数字。有公式的单元格，v 存放公式的计算结果。

如下展示了两种不同的单元格值。

TypeScript
interface IWorksheetData {  cellData: {    0: {      0: { v: 'A1' }      1: { v: 1 }    }  }}

单元格样式

cellData.s 存储了单元格的样式 id 或者样式对象。

如果 s 是一个字符串，表示样式 id。Univer Sheets 支持对样式做引用优化，将重复的样式对象存储在 IWorkbookData 的 styles 字段中，是一个 Map 结构，每个 key 是样式 id，value 是样式对象。

请尽量避免使用带透明度的颜色值（如 rgba），否则在激活编辑状态时，背景会透出下方单元格的内容。

TypeScript
interface IWorkbookData {  styles: {    random_style_id_1: {      fs: 12      bg: {        rgb: '#ff0000'      }    }  }}

然后将 id 存储到单元格样式中，达到样式复用的目的。

TypeScript
interface IWorksheetData {  cellData: {    0: {      0: {        v: 'A1'        s: 'random_style_id_1'      }      1: {        v: 'B1'        s: 'random_style_id_1'      }    }  }}

如果 s 是一个对象，则表示一个完整的单元格样式对象 IStyleData。

完整的样式字段如下。

属性说明
ff字体
fs字体大小
it是否斜体
bl是否加粗
ul下划线
st删除线
ol上划线
bg背景颜色
bd边框
cl字体颜色
va上标下标
tr文字旋转
ht水平对齐方式
vt垂直对齐方式
tb截断溢出
pd内边距
n数字格式

详细了解 IStyleData 每个字段的类型信息。

字体

ff 是一个字符串，表示字体的名称。

TypeScript
interface IStyleData {  ff: 'Arial' // 字体名称为 Arial}

字体大小

fs 是一个数字，单位是 pt。

TypeScript
interface IStyleData {  fs: 12 // 字体大小为 12 pt}

是否斜体

it 是一个布尔数字，0 表示不斜体，1 表示斜体。

TypeScript
interface IStyleData {  it: 1 // 斜体}

是否加粗

bl 是一个布尔数字，0 表示不加粗，1 表示加粗。

TypeScript
interface IStyleData {  bl: 1 // 加粗}

下划线

ul 是一个对象，表示下划线样式。

TypeScript
interface IStyleData {  ul: {    s: 1 // 是否展示下划线    c: 0 // 颜色是否跟随字体颜色。当 `c` 为 1（TRUE） 时 cl 不起作用。默认值为 1    cl: { // 下划线颜色      rgb: '#ff0000'    }    t: 0 // 下划线类型  }}

删除线

st 是一个对象，表示删除线样式。

TypeScript
interface IStyleData {  st: {    s: 1 // 是否展示删除线    c: 0 // 颜色是否跟随字体颜色。当 `c` 为 1（TRUE） 时 cl 不起作用。默认值为 1    cl: { // 删除线颜色      rgb: '#ff0000'    }    t: 0 // 删除线类型  }}

上划线

ol 是一个对象，表示上划线样式。

TypeScript
interface IStyleData {  ol: {    s: 1 // 是否展示上划线    c: 0 // 颜色是否跟随字体颜色。当 `c` 为 1（TRUE） 时 cl 不起作用。默认值为 1    cl: { // 上划线颜色      rgb: '#ff0000'    }    t: 0 // 上划线类型  }}

背景颜色

bg 是一个对象，表示背景颜色。

TypeScript
interface IStyleData {  bg: {    rgb: '#ff0000' // 背景颜色为红色  }}

边框

bd 是一个对象，表示边框样式。

TypeScript
interface IStyleData {  bd: {    // 上边框    t: {      s: 0 // 边框样式      cl: { // 边框颜色        rgb: '#ff0000'      }    }    // 下边框    b: {      s: 0 // 边框样式      cl: { // 边框颜色        rgb: '#ff0000'      }    }    // 左边框    l: {      s: 0 // 边框样式      cl: { // 边框颜色        rgb: '#ff0000'      }    }    // 右边框    r: {      s: 0 // 边框样式      cl: { // 边框颜色        rgb: '#ff0000'      }    }  }}

字体颜色

cl 是一个对象，表示字体颜色。

TypeScript
interface IStyleData {  cl: {    rgb: '#ff0000' // 字体颜色为红色  }}

上标下标

va 是一个数字枚举，1 表示正常，2 表示下标，3 表示上标。

TypeScript
interface IStyleData {  va: 2 // 下标}

文字旋转

tr 是一个对象，表示文字旋转角度。

TypeScript
interface IStyleData {  tr: {    a: 0 // 文字旋转角度    v: 0 // 是否垂直。1 表示垂直，0 表示水平。默认值为 0。当 v 为 1 时，a 无效  }}

水平对齐方式

ht 是一个数字枚举，1 表示左对齐，2 表示居中，3 表示右对齐。

TypeScript
interface IStyleData {  ht: 1 // 左对齐}

垂直对齐方式

vt 是一个数字枚举，1 表示顶部对齐，2 表示居中，3 表示底部对齐。

TypeScript
interface IStyleData {  vt: 1 // 顶部对齐}

截断溢出

tb 是一个数字枚举，1 表示溢出，2 表示截断，3 表示自动换行。

TypeScript
interface IStyleData {  tb: 1 // 溢出}

内边距

pd 是一个对象，表示内边距。

TypeScript
interface IStyleData {  pd: {    t: 0 // 上边距    b: 0 // 下边距    l: 0 // 左边距    r: 0 // 右边距  }}

数字格式

n 是一个对象，其 pattern 字段表示数字格式。数字格式是一个字符串，具体请参考 这里。

n 为 null 或者 pattern 为 null 时，表示常规格式。

TypeScript
import type { DEFAULT_TEXT_FORMAT_EXCEL } from '@univerjs/core'interface IStyleData {  n: {    pattern: DEFAULT_TEXT_FORMAT_EXCEL // 文本格式  }}

关于单元格输入带有0开头或可转换为日期格式的数字时，不想被默认转换

单元格类型

cellData.t 是一个枚举 CellValueType，表示单元格的类型。1 表示字符串，2 表示数字，3 表示布尔值，4 表示强制文本，不设置时 Univer 会自动识别。

其中，如果单元格是布尔类型，则 cellData.v 的值存储为 0 或 1，0 表示 false，1 表示 true。

TypeScript
interface IWorksheetData {  cellData: {    0: {      0: {        v: 'A1'        t: 1 // 字符串      }      1: {        v: 1        t: 2 // 数字      }      2: {        v: 1 // TRUE        t: 3 // 布尔值      }      3: {        v: '012.0'        t: 4 // 强制文本      }    }  }}

可配置 disableForceStringAlert 和 disableForceStringMark 来禁用强制字符串警告和标记，配置项位置见：

富文本

cellData.p 是一个对象，表示富文本，同时也是一个 Univer Doc。详细了解 IDocumentData。

当 p 和 v 同时存在时，只会显示 p 的内容。

cellData.p.body.dataStream 是富文本的内容。

公式

cellData.f 是一个字符串，表示公式。

TypeScript
interface IWorksheetData {  cellData: {    0: {      0: {        f: '=SUM(A1:B1)' // 求和公式      }    }  }}

公式 ID

cellData.si 是一个字符串，表示公式 ID。Univer Sheets 支持对公式做引用优化，单元格中用 si 关联上当前公式后，其他单元格可以通过 si 引用到当前公式。注意，si 所在单元格的位置必须在引用单元格的右下角，否则导出为 XLSX 时会出现错误。

可以通过 Facade API range.getFormulas() 来获取实际的公式，规则是取 si 对应的公式 f 后，根据当前单元格位置到引用位置的偏移量来计算实际的公式。

TypeScript
interface IWorksheetData {  cellData: {    0: {      0: {        f: '=SUM(A1:B1)' // 求和公式        si: 'random_formula_id_1' // 当前公式的 id      }      1: {        si: 'random_formula_id_1' // 计算时取此 id 对应的公式      }    }  }}

自定义字段

cellData.custom 是一个对象，表示自定义字段。其中可以放入任何符合 JSON 格式的数据，用于自定义存储一些额外的信息。

更新 custom 数据会覆盖原有的 custom 数据，如果你在更新数据时需要保留原有的 custom 数据，请提前获取到 custom 数据合并成新的数据后再更新。

custom 字段仅适用于部分特殊场景，存储于该字段中的数据有可能因用户的任何操作被覆盖或删除，请谨慎使用。

TypeScript
interface IWorksheetData {  cellData: {    0: {      0: {        custom: {          key: 'value'        }      }    }  }}

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.