# 儲存格資料結構

- Human documentation: [https://docs.univer.ai/zh-TW/guides/sheets/model/cell-data](https://docs.univer.ai/zh-TW/guides/sheets/model/cell-data)

- Agent Markdown: [https://docs.univer.ai/zh-TW/guides/sheets/model/cell-data.md](https://docs.univer.ai/zh-TW/guides/sheets/model/cell-data.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [sheets/model/cell-data.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/model/cell-data.zh-TW.mdx)

---

## 儲存格位置

Univer Sheets 中的儲存格資料儲存在 [IWorksheetData](https://docs.univer.ai/zh-TW/reference/types/worksheet-data.md) 的 [cellData](https://docs.univer.ai/zh-TW/reference/types/worksheet-data.md#celldata) 欄位中。cellData 為二維 Map 結構，第一層與第二層索引分別代表列號與欄號；每一個儲存格是一個 [ICellData](https://docs.univer.ai/zh-TW/reference/types/cell-data.md) 物件，包含儲存格值、樣式、型別等所有資訊。

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](https://docs.univer.ai/zh-TW/reference/types/cell-data.md) 各欄位的型別資訊。

### 儲存格原始值

`cellData.v` 儲存了儲存格的原始值，可以是字串或數字。有公式的儲存格，`v` 儲存公式的計算結果。

如下展示兩種不同的儲存格值。

```typescript
interface IWorksheetData {
  cellData: {
    0: {
      0: { v: 'A1' }
      1: { v: 1 }
    }
  }
}
```

### 儲存格樣式

`cellData.s` 儲存了儲存格的樣式 id 或樣式物件。

如果 `s` 是字串，表示樣式 id。Univer Sheets 支援對樣式做參照最佳化，將重複的樣式物件儲存在 IWorkbookData 的 [styles](https://docs.univer.ai/zh-TW/reference/types/workbook-data.md#styles) 欄位中，為 Map 結構，每個 key 是樣式 id，value 是樣式物件。

> [!WARNING]
> 請儘量避免使用帶透明度的顏色值（如 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](https://docs.univer.ai/zh-TW/reference/types/style-data.md)。

完整的樣式欄位如下。

| 屬性 | 說明     |
| -- | ------ |
| ff | 字型     |
| fs | 字型大小   |
| it | 斜體     |
| bl | 粗體     |
| ul | 底線     |
| st | 刪除線    |
| ol | 上劃線    |
| bg | 背景顏色   |
| bd | 邊框     |
| cl | 字型顏色   |
| va | 上標下標   |
| tr | 文字旋转   |
| ht | 水平對齊方式 |
| vt | 垂直對齊方式 |
| tb | 截斷溢出   |
| pd | 內邊距    |
| n  | 數字格式   |

詳細了解 [IStyleData](https://docs.univer.ai/zh-TW/reference/types/style-data.md) 各欄位的型別資訊。

#### 字型

`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` 欄位表示數字格式。數字格式是一個字串，請參考[這裡](https://support.microsoft.com/zh-tw/office/%E6%95%B8%E5%AD%97%E6%A0%BC%E5%BC%8F%E4%BB%A3%E7%A2%BC-5026bbd6-04bc-48cd-bf33-80f18b4eae68)。

當 `n` 為 `null` 或 `pattern` 為 `null` 時，表示一般格式。

```typescript
import type { DEFAULT_TEXT_FORMAT_EXCEL } from '@univerjs/core'

interface IStyleData {
  n: {
    pattern: DEFAULT_TEXT_FORMAT_EXCEL // 文字格式
  }
}
```

[關於在儲存格輸入以 0 開頭或可轉換為日期格式的數字時，不想被預設轉換](https://docs.univer.ai/zh-TW/guides/sheets/features/core/numfmt.md#usage)

### 儲存格型別

`cellData.t` 是一個列舉 [CellValueType](https://docs.univer.ai/zh-TW/reference/enums/cell-value-type.md)，表示儲存格的型別。`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` 來禁用強制文字警告和標記，配置項位置見：

* [預設模式](https://docs.univer.ai/zh-TW/guides/sheets/features/core.md#univerjspreset-sheets-core)
* [外掛模式](https://docs.univer.ai/zh-TW/guides/sheets/features/core.md#univerjssheets-ui)

### 豐富文字

`cellData.p` 是物件，表示豐富文字，同時也是一個 Univer Doc。詳細了解 [IDocumentData](https://docs.univer.ai/zh-TW/reference/types/document-data.md)。

> [!NOTE]
> 當 `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` 資料，請先取得並與新資料合併後再更新。

> [!WARNING]
> `custom` 欄位僅適用於部分特殊情境，儲存在該欄位中的資料可能因使用者的任何操作被覆蓋或刪除，請謹慎使用。

```typescript
interface IWorksheetData {
  cellData: {
    0: {
      0: {
        custom: {
          key: 'value'
        }
      }
    }
  }
}
```