配置单元格数据

📊 Univer Sheet

单元格位置

Univer Sheet 中的单元格数据存储在 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 Doc
f	公式
si	公式 ID
custom	自定义字段

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

单元格原始值

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

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

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

单元格样式

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

如果 s 是一个字符串，表示样式 id。Univer Sheet 支持对样式做引用优化，将重复的样式对象存储在 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
}

是否斜体

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 Sheet 支持对公式做引用优化，单元格中用 si 关联上当前公式后，其他单元格可以通过 si 引用到当前公式。

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

自定义字段

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

// IWorksheetData
{
  cellData: {
    0: {
      0: {
        custom: {
          key: 'value'
        }
      },
    },
  }
}

简化引入核心功能