Web SDK

儲存格資料結構

儲存格位置

Univer Sheets 中的儲存格資料儲存在 IWorksheetData 的 cellData 欄位中。cellData 為二維 Map 結構，第一層與第二層索引分別代表列號與欄號；每一個儲存格是一個 ICellData 物件，包含儲存格值、樣式、型別等所有資訊。

cellData 的結構如下

TypeScript
interface IWorksheetData {  cellData: {    // 第 1 列（row）    0: {      // 第 1 欄（column）      0: { v: 'A1' }      // 第 2 欄      1: { v: 'B1' }    }    // 第 2 列    1: {      // 第 1 欄      0: { v: 'A2' }      // 第 2 欄      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 欄位僅適用於部分特殊情境，儲存在該欄位中的資料可能因使用者的任何操作被覆蓋或刪除，請謹慎使用。

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

你覺得這篇文檔如何？

© 2026 DreamNum Co., Ltd.