🎉 v0.5.0 版本已发布。查看详情 →
指南Univer Sheets开始使用单元格数据结构

单元格数据结构

单元格位置

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

cellData 的结构如下

// 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 存放公式的计算结果。

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

// IWorksheetData
{
  cellData: {
    0: {
      0: { v: 'A1' },
      1: { v: 1 },
    },
  }
}

单元格样式

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

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

// IWorkbookData
{
  styles: {
    'random_style_id_1': {
      fs: 12,
      bg: {
        rgb: '#ff0000'
      }
    }
  }
}

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

// 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文字旋转
td文字方向
ht水平对齐方式
vt垂直对齐方式
tb截断溢出
pd内边距

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

字体

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

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

字体大小

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

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

是否斜体

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

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

是否加粗

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

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

下划线

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

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

删除线

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

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

上划线

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

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

背景颜色

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

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

边框

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

// 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 是一个对象，表示字体颜色。

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

上标下标

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

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

文字旋转

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

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

文字方向

td 是一个数字枚举，1 表示从左到右，2 表示从右到左。

// IStyleData
{
  td: 1 // 从左到右
}

水平对齐方式

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

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

垂直对齐方式

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

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

截断溢出

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

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

内边距

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

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

单元格类型

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

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

// IWorksheetData
{
  cellData: {
    0: {
      0: {
        v: 'A1',
        t: 1 // 字符串
      },
      1: {
        v: 1,
        t: 2 // 数字
      },
      1: {
        v: 1, // TRUE
        t: 2 // 布尔值
      },
    },
  }
}

富文本

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

公式

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

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

公式 ID

cellData.si 是一个字符串，表示公式 ID。Univer Sheets 支持对公式做引用优化，单元格中用 si 关联上当前公式后，其他单元格可以通过 si 引用到当前公式。

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

// 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 数据合并成新的数据后再更新。

// IWorksheetData
{
  cellData: {
    0: {
      0: {
        custom: {
          key: 'value'
        }
      },
    },
  }
}
工作表数据结构高级安装