# セルデータ構造

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

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

- Requested language: `ja-JP`

- Content language: `ja-JP`

- Documentation version: `1.1.0`

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

---

## セル位置

Univer Sheets のセルデータは [IWorksheetData](https://docs.univer.ai/ja-JP/reference/types/worksheet-data.md) オブジェクトの [cellData](https://docs.univer.ai/ja-JP/reference/types/worksheet-data.md#celldata) フィールドに格納されており、セルの値、スタイル、タイプなどのすべてのセル情報が含まれています。

cellData の構造は以下の通りです

```typescript
interface IWorksheetData {
  cellData: {
    // 最初の行
    0: {
      // 最初の列
      0: { v: 'A1' }
      // 2 番目の列
      1: { v: 'B1' }
    }
    // 2 番目の行
    1: {
      // 最初の列
      0: { v: 'A2' }
      // 2 番目の列
      1: { v: 'B2' }
    }
  }
}
```

## セルデータ

完全なセル情報は以下の通りです。

| プロパティ  | 説明                       |
| ------ | ------------------------ |
| v      | セルの元の値                   |
| s      | セルスタイル ID またはスタイルオブジェクト  |
| t      | セルタイプ                    |
| p      | リッチテキスト、Univer Docs でもある |
| f      | 数式                       |
| si     | 数式 ID                    |
| custom | カスタムフィールド                |

[ICellData](https://docs.univer.ai/ja-JP/reference/types/cell-data.md) の各フィールドのタイプ情報を確認してください。

### セルの元の値

`cellData.v` はセルの元の値を格納し、文字列または数値にすることができます。数式を持つセルの場合、`v` は数式の計算結果を格納します。

ここでは 2 つの異なるセル値を示します。

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

### セルスタイル

`cellData.s` はセルのスタイル ID またはスタイルオブジェクトを格納します。

`s` が文字列の場合、スタイル ID を表します。Univer Sheets はスタイルの参照最適化をサポートしています。繰り返されるスタイルオブジェクトは IWorkbookData の [styles](https://docs.univer.ai/ja-JP/reference/types/workbook-data.md#styles) フィールドに格納され、これは Map 構造で、各キーはスタイル ID、値はスタイルオブジェクトです。

> [!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/ja-JP/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/ja-JP/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/en-us/office/number-format-codes-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/ja-JP/guides/sheets/features/core/numfmt.md#usage)

### セルタイプ

`cellData.t` は列挙 [CellValueType](https://docs.univer.ai/ja-JP/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/ja-JP/guides/sheets/features/core.md#univerjspreset-sheets-core)
* [プラグインモード](https://docs.univer.ai/ja-JP/guides/sheets/features/core.md#univerjssheets-ui)

### リッチテキスト

`cellData.p` はリッチテキストを表すオブジェクトであり、Univer Doc でもあります。[IDocumentData](https://docs.univer.ai/ja-JP/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)' // SUM 関数
      }
    }
  }
}
```

### 数式 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` データを取得し、新しいデータにマージしてから更新してください。

> [!WARNING]
> `custom` フィールドは一部の特殊なシナリオにのみ適しており、このフィールドに格納されたデータは任意のユーザー操作によって上書きまたは削除される可能性があります。注意して使用してください。

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