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

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

Данные ячеек в Univer Sheets хранятся в поле cellData объекта IWorksheetData. Оно содержит всю информацию о ячейках: значения, стили, типы и другие данные.

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

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' }    }  }}

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

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

Сведения о типах каждого поля см. в описании ICellData.

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

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

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

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

Стиль ячейки

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

Если s — строка, она представляет идентификатор стиля. Univer Sheets поддерживает оптимизацию стилей с помощью ссылок. Повторяющиеся объекты стилей хранятся в поле styles объекта IWorkbookData. Это структура Map, в которой ключом служит идентификатор стиля, а значением — объект стиля.

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

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

interface IWorksheetData {  cellData: {    0: {      0: {        v: 'A1'        s: 'random_style_id_1'      }      1: {        v: 'B1'        s: 'random_style_id_1'      }    }  }}

Если s — объект, он представляет полный объект стиля ячейки IStyleData.

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

Сведения о типах каждого поля см. в описании IStyleData.

Шрифт

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

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

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

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

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

Курсив

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

interface IStyleData {  it: 1 // Italic}

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

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

interface IStyleData {  bl: 1 // Bold}

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

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

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 — объект, описывающий стиль зачёркивания.

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 — объект, описывающий стиль надчёркивания.

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 — объект, описывающий цвет фона.

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

Граница

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

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 — объект, описывающий цвет шрифта.

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

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

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

interface IStyleData {  va: 2 // Subscript}

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

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

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 — по правому краю.

interface IStyleData {  ht: 1 // Left alignment}

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

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

interface IStyleData {  vt: 1 // Top alignment}

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

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

interface IStyleData {  tb: 1 // Overflow}

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

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

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

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

n — объект, поле pattern которого задаёт числовой формат. Числовой формат указывается строкой; дополнительные сведения см. здесь。

Если n равно null или pattern равно null, используется общий формат.

import type { DEFAULT_TEXT_FORMAT_EXCEL } from '@univerjs/core'interface IStyleData {  n: {    pattern: DEFAULT_TEXT_FORMAT_EXCEL // text format  }}

Как предотвратить автоматическое преобразование ячейки при вводе числа, начинающегося с 0, или числа, которое можно преобразовать в формат даты

Тип ячейки

cellData.t — перечисление CellValueType, определяющее тип ячейки. 1 означает строку, 2 — число, 3 — логическое значение, 4 — принудительный текстовый формат. Если значение не задано, Univer распознаёт тип автоматически.

Если ячейка имеет логический тип, значение cellData.v хранится как 0 или 1: 0 означает false, 1 — true.

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
• Режим Plugin

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

cellData.p — объект с форматированным текстом, который также является документом Univer Docs. Подробнее об IDocumentData.

cellData.p.body.dataStream содержит форматированный текст.

Формула

cellData.f — строка с формулой.

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, а затем с учётом смещения текущей ячейки относительно ячейки с формулой вычисляется фактическая формула.

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, объедините их с новыми и только затем выполните обновление.

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