# Структура данных ячейки

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

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

- Requested language: `ru-RU`

- Content language: `ru-RU`

- Documentation version: `1.2.0`

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

---

## Положение ячейки

Данные ячеек в Univer Sheets хранятся в поле [cellData](https://docs.univer.ai/ru-RU/reference/types/worksheet-data.md#celldata) объекта [IWorksheetData](https://docs.univer.ai/ru-RU/reference/types/worksheet-data.md). Оно содержит всю информацию о ячейках: значения, стили, типы и другие данные.

Структура cellData выглядит следующим образом:

```typescript
interface IWorksheetData {
  cellData: {
    // first row
    0: {
      // first column
      0: { v: 'A1' }
      // second column
      1: { v: 'B1' }
    }
    // second row
    1: {
      // first column
      0: { v: 'A2' }
      // second column
      1: { v: 'B2' }
    }
  }
}
```

## Данные ячейки

Полный набор данных ячейки выглядит следующим образом:

| Свойство | Описание                                                                |
| -------- | ----------------------------------------------------------------------- |
| v        | Исходное значение ячейки                                                |
| s        | Идентификатор или объект стиля ячейки                                   |
| t        | Тип ячейки                                                              |
| p        | Форматированный текст, который также является документом 📝 Univer Docs |
| f        | Формула                                                                 |
| si       | Идентификатор формулы                                                   |
| custom   | Пользовательское поле                                                   |

Сведения о типах каждого поля см. в описании [ICellData](https://docs.univer.ai/ru-RU/reference/types/cell-data.md).

### Исходное значение ячейки

`cellData.v` хранит исходное значение ячейки: строку или число. Для ячеек с формулами в `v` хранится результат вычисления формулы.

Ниже показаны два разных значения ячейки.

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

### Стиль ячейки

`cellData.s` хранит идентификатор или объект стиля ячейки.

Если `s` — строка, она представляет идентификатор стиля. Univer Sheets поддерживает оптимизацию стилей с помощью ссылок. Повторяющиеся объекты стилей хранятся в поле [styles](https://docs.univer.ai/ru-RU/reference/types/workbook-data.md#styles) объекта IWorkbookData. Это структура Map, в которой ключом служит идентификатор стиля, а значением — объект стиля.

> [!WARNING]
> Старайтесь не использовать значения цвета с прозрачностью (например, rgba), иначе при переходе в режим редактирования сквозь фон будет видно содержимое ячейки под ним.

```typescript
interface IWorkbookData {
  styles: {
    random_style_id_1: {
      fs: 12
      bg: {
        rgb: '#ff0000'
      }
    }
  }
}
```

Затем сохраните идентификатор в стиле ячейки, чтобы использовать стиль повторно.

```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/ru-RU/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/ru-RU/reference/types/style-data.md).

#### Шрифт

`ff` — строка с названием шрифта.

```typescript
interface IStyleData {
  ff: 'Arial' // Font name is Arial
}
```

#### Размер шрифта

`fs` — число, единица измерения — **pt**.

```typescript
interface IStyleData {
  fs: 12 // Font size is 12 pt
}
```

#### Курсив

`it` — логическое число: `0` означает обычное начертание, `1` — курсив.

```typescript
interface IStyleData {
  it: 1 // Italic
}
```

#### Полужирное начертание

`bl` — логическое число: `0` означает обычное начертание, `1` — полужирное.

```typescript
interface IStyleData {
  bl: 1 // Bold
}
```

#### Подчёркивание

`ul` — объект, описывающий стиль подчёркивания.

```typescript
interface IStyleData {
  ul: {
    s: 1 // Whether to show underline
    c: 0 // Whether the color follows the font color. When `c` is 1 (TRUE), cl does not work. The default value is 1
    cl: { // Underline color
      rgb: '#ff0000'
    }
    t: 0 // Underline type
  }
}
```

#### Зачёркивание

`st` — объект, описывающий стиль зачёркивания.

```typescript
interface IStyleData {
  st: {
    s: 1 // Whether to show strikethrough
    c: 0 // Whether the color follows the font color. When `c` is 1 (TRUE), cl does not work. The default value is 1
    cl: { // Strikethrough color
      rgb: '#ff0000'
    }
    t: 0 // Strikethrough type
  }
}
```

#### Надчёркивание

`ol` — объект, описывающий стиль надчёркивания.

```typescript
interface IStyleData {
  ol: {
    s: 1 // Whether to show overline
    c: 0 // Whether the color follows the font color. When `c` is 1 (TRUE), cl does not work. The default value is 1
    cl: { // Overline color
      rgb: '#ff0000'
    }
    t: 0 // Overline type
  }
}
```

#### Цвет фона

`bg` — объект, описывающий цвет фона.

```typescript
interface IStyleData {
  bg: {
    rgb: '#ff0000' // Background color is red
  }
}
```

#### Граница

`bd` — объект, описывающий стиль границы.

```typescript
interface IStyleData {
  bd: {
    // Top border
    t: {
      s: 0 // Border style
      cl: { // Border color
        rgb: '#ff0000'
      }
    }
    // Bottom border
    b: {
      s: 0 // Border style
      cl: { // Border color
        rgb: '#ff0000'
      }
    }
    // Left border
    l: {
      s: 0 // Border style
      cl: { // Border color
        rgb: '#ff0000'
      }
    }
    // Right border
    r: {
      s: 0 // Border style
      cl: { // Border color
        rgb: '#ff0000'
      }
    }
  }
}
```

#### Цвет шрифта

`cl` — объект, описывающий цвет шрифта.

```typescript
interface IStyleData {
  cl: {
    rgb: '#ff0000' // Font color is red
  }
}
```

#### Верхний или нижний индекс

`va` — числовое перечисление: `1` означает обычный текст, `2` — нижний индекс, `3` — верхний индекс.

```typescript
interface IStyleData {
  va: 2 // Subscript
}
```

#### Поворот текста

`tr` — объект, описывающий поворот текста.

```typescript
interface IStyleData {
  tr: {
    a: 0 // Text rotation angle
    v: 0 // Whether it is vertical. 1 means vertical, 0 means horizontal. The default value is 0. When v is 1, a is invalid
  }
}
```

#### Выравнивание по горизонтали

`ht` — числовое перечисление: `1` означает выравнивание по левому краю, `2` — по центру, `3` — по правому краю.

```typescript
interface IStyleData {
  ht: 1 // Left alignment
}
```

#### Выравнивание по вертикали

`vt` — числовое перечисление: `1` означает выравнивание по верхнему краю, `2` — по центру, `3` — по нижнему краю.

```typescript
interface IStyleData {
  vt: 1 // Top alignment
}
```

#### Обработка текста, выходящего за границы

`tb` — числовое перечисление: `1` разрешает выход за границы, `2` обрезает текст, `3` переносит текст.

```typescript
interface IStyleData {
  tb: 1 // Overflow
}
```

#### Внутренние отступы

`pd` — объект, описывающий внутренние отступы.

```typescript
interface IStyleData {
  pd: {
    t: 0 // Top padding
    b: 0 // Bottom paddingAdd commentMore actions
    l: 0 // Left padding
    r: 0 // Right padding
  }
}
```

#### Числовой формат

`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 // text format
  }
}
```

[Как предотвратить автоматическое преобразование ячейки при вводе числа, начинающегося с 0, или числа, которое можно преобразовать в формат даты](https://docs.univer.ai/ru-RU/guides/sheets/features/core/numfmt.md#usage)

### Тип ячейки

`cellData.t` — перечисление [CellValueType](https://docs.univer.ai/ru-RU/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 // String
      }
      1: {
        v: 1
        t: 2 // Number
      }
      2: {
        v: 1 // TRUE
        t: 3 // Boolean
      }
      3: {
        v: '012.0'
        t: 4 // Force text
      }
    }
  }
}
```

Параметры `disableForceStringAlert` и `disableForceStringMark` позволяют включать и отключать предупреждение и метку принудительного текстового формата. Где находятся эти настройки:

* [Режим Preset](https://docs.univer.ai/ru-RU/guides/sheets/features/core.md#univerjspreset-sheets-core)
* [Режим Plugin](https://docs.univer.ai/ru-RU/guides/sheets/features/core.md#univerjssheets-ui)

### Форматированный текст

`cellData.p` — объект с форматированным текстом, который также является документом Univer Docs. Подробнее об [IDocumentData](https://docs.univer.ai/ru-RU/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)' // function SUM
      }
    }
  }
}
```

### Идентификатор формулы

`cellData.si` — строка с идентификатором формулы. Univer Sheets поддерживает оптимизацию формул с помощью ссылок. После того как текущая формула связана с `si` в ячейке, другие ячейки могут ссылаться на неё через `si`. Обратите внимание: ячейка с `si` должна находиться ниже и правее ячейки, которая на неё ссылается, иначе при экспорте в XLSX возникнет ошибка.

Фактическую формулу можно получить через Facade API `range.getFormulas()`. Для этого находится формула `f`, соответствующая `si`, а затем с учётом смещения текущей ячейки относительно ячейки с формулой вычисляется фактическая формула.

```typescript
interface IWorksheetData {
  cellData: {
    0: {
      0: {
        f: '=SUM(A1:B1)' // Sum formula
        si: 'random_formula_id_1' // ID of the current formula
      }
      1: {
        si: 'random_formula_id_1' // Take the formula corresponding to this ID during calculation
      }
    }
  }
}
```

### Пользовательское поле

`cellData.custom` — объект, представляющий пользовательское поле. В него можно поместить любые данные в формате JSON для хранения дополнительной информации.

При обновлении данных `custom` прежние данные `custom` перезаписываются. Если исходные данные `custom` нужно сохранить, заранее получите текущие данные `custom`, объедините их с новыми и только затем выполните обновление.

> [!WARNING]
> Поле `custom` подходит только для особых сценариев. Данные в нём могут быть перезаписаны или удалены при любой пользовательской операции, поэтому используйте это поле с осторожностью.

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