Справочник типов

Все типы экспортируются из @dhx/react-spreadsheet или @dhtmlx/trial-react-spreadsheet.

import type { SheetData, CellData, SpreadsheetRef /* ... */ } from "@dhtmlx/trial-react-spreadsheet";

CellData

Декларативное состояние одной ячейки. Все свойства необязательны; пропущенные свойства сохраняют своё текущее значение при обновлениях.

Свойство	Тип	Описание
`value`	`string \| number`	Значение ячейки: текст, число или строка формулы (с префиксом `=`).
`css`	`string`	Имя (имена) CSS-класса, ссылающееся на ключи в карте `styles` верхнего уровня.
`format`	`string`	Маска формата числа или псевдоним (например, `"currency"` или `"#,##0.00"`).
`locked`	`boolean`	Заблокирована ли ячейка (защищена от редактирования).
`validation`	`string \| string[]`	Варианты выпадающего списка для валидации данных.

RowConfig

Метаданные строки. Записи нужны только для строк с нестандартной конфигурацией.

Свойство	Тип	Описание
`height`	`number`	Высота строки в пикселях.
`hidden`	`boolean`	Скрыта ли строка.

ColConfig

Метаданные столбца. Записи нужны только для столбцов с нестандартной конфигурацией.

Свойство	Тип	Описание
`width`	`number`	Ширина столбца в пикселях.
`hidden`	`boolean`	Скрыт ли столбец.

MergedRange

Определяет диапазон объединённых ячеек с использованием координат строк/столбцов, начиная с 0.

Свойство	Тип	Описание
`from`	`{ row: number; column: number }`	Верхний левый угол объединения (индекс с 0).
`to`	`{ row: number; column: number }`	Нижний правый угол объединения (индекс с 0).

Пример:

// Объединение A1:B2
const merge: MergedRange = {
    from: { row: 0, column: 0 },
    to: { row: 1, column: 1 },
};

FreezeConfig

Конфигурация закреплённой панели для листа.

Свойство	Тип	Описание
`col`	`number`	Закрепить столбцы до этого номера столбца (индекс с 0). `undefined` = без закрепления столбцов.
`row`	`number`	Закрепить строки до этого номера строки (индекс с 0). `undefined` = без закрепления строк.

SheetFilter

Конфигурация фильтра для столбца внутри листа.

Свойство	Тип	Описание
`cell`	`string`	Ссылка на ячейку, идентифицирующую отфильтрованный столбец (например, `"A1"`).
`rules`	`IFilterRules[]`	Применяемые правила фильтрации. Пустой массив сбрасывает фильтр.

SheetSort

Конфигурация сортировки для столбца внутри листа.

Свойство	Тип	Описание
`cell`	`string`	Ссылка на ячейку или диапазон для операции сортировки (например, `"B1"` или `"A1:E8"`). Используйте диапазон для сортировки нескольких столбцов с сохранением целостности строк.
`dir`	`1 \| -1`	Направление сортировки: `1` = по возрастанию, `-1` = по убыванию.

SheetData

Полное декларативное состояние одного листа таблицы.

Свойство	Тип	Обязательно	Описание
`id`	`Id`	Да	Уникальный идентификатор листа. Должен быть стабильным между рендерами.
`name`	`string`	Да	Отображаемое имя на вкладке листа.
`cells`	`Record<string, CellData>`	Да	Данные ячеек, с ключом по ссылке на ячейку (например, `"A1"` или `"B2"`). Записи нужны только для ячеек с нестандартными данными.
`rows`	`Record<number, RowConfig>`	Нет	Конфигурация строк с ключом по номеру строки (индекс с 0).
`cols`	`Record<number, ColConfig>`	Нет	Конфигурация столбцов с ключом по номеру столбца (индекс с 0).
`merged`	`MergedRange[]`	Нет	Диапазоны объединённых ячеек.
`freeze`	`FreezeConfig`	Нет	Конфигурация закреплённых панелей.
`filter`	`SheetFilter`	Нет	Конфигурация фильтра столбца. Установите `undefined`, чтобы сбросить.
`sort`	`SheetSort`	Нет	Конфигурация сортировки.

Пример:

const sheet: SheetData = {
    id: "sheet1",
    name: "Inventory",
    cells: {
        A1: { value: "Product", css: "bold" },
        B1: { value: "Quantity", css: "bold" },
        A2: { value: "Laptop" },
        B2: { value: 42 },
    },
    cols: { 0: { width: 200 } },
    freeze: { row: 1 },
};

SearchConfig

Управляемое состояние поиска. Передайте объект для запуска/обновления поиска, передайте undefined, чтобы закрыть его.

Свойство	Тип	Обязательно	Описание
`query`	`string`	Да	Текст для поиска.
`open`	`boolean`	Нет	Открыть ли встроенный интерфейс поиска. По умолчанию: `false`.
`sheetId`	`Id`	Нет	Ограничить поиск конкретным листом по id.

SpreadsheetLocale

Конфигурация локализации для меток интерфейса и названий формул.

Свойство	Тип	Описание
`locale`	`Record<string, string>`	Переопределения строк интерфейса. Ключи соответствуют словарю локализации библиотеки.
`formulas`	`Record<string, [string, string?][]>`	Локализованные имена формул, сгруппированные по категориям. Каждый элемент — кортеж: `[localizedName, optionalDescription?]`.

SpreadsheetTheme

type SpreadsheetTheme = "light" | "dark" | "contrast-light" | "contrast-dark" | string;

Встроенные цветовые темы. Также принимает строки с именами пользовательских тем.

IExecuteConfig

Конфигурация выполнения действия, передаваемая в onBeforeAction / onAfterAction. Форма зависит от типа действия.

Свойство	Тип	Описание
`row`	`number`	Индекс целевой строки.
`col`	`number`	Индекс целевого столбца.
`target`	`unknown`	Цель, специфичная для действия.
`val`	`unknown`	Новое значение.
`prev`	`unknown`	Предыдущее значение.
`action`	`Actions \| string`	Идентификатор действия.
`groupAction`	`Actions \| string`	Идентификатор родительского группового действия.
`cell`	`string`	Ссылка на ячейку (например, `"A1"`).
`pageId`	`Id`	Id целевого листа.
`pageName`	`string`	Имя целевого листа.
`[key: string]`	`unknown`	Дополнительные свойства, специфичные для действия.

SpreadsheetRef

Императивный дескриптор, доступный через React.forwardRef. Предоставляет прямой доступ к базовому экземпляру DHTMLX Spreadsheet для операций, которые не отображаются на декларативные пропсы.

Свойство	Тип	Описание
`instance`	`ISpreadsheet \| null`	Базовый экземпляр виджета. `null` до инициализации и после размонтирования.

Пример:

const ref = useRef<SpreadsheetRef>(null);

// Сериализация данных
const data = ref.current?.instance?.serialize();

// Программный выбор
ref.current?.instance?.selection.setSelectedCell("A1:C5");

// Отмена/возврат
ref.current?.instance?.undo();
ref.current?.instance?.redo();

Перечисление Actions

Известные идентификаторы действий таблицы. Используются в onBeforeAction / onAfterAction для типобезопасного сопоставления действий. Объединение | string в параметрах обработчиков обеспечивает прямую совместимость с будущими действиями.

Значение	Описание
`setCellStyle`	Применить CSS-стиль к ячейке(ям).
`setCellValue`	Установить значение ячейки.
`setCellFormat`	Установить числовой формат для ячейки(ек).
`removeCellStyles`	Удалить CSS-стили из ячейки(ек).
`lockCell`	Заблокировать или разблокировать ячейку(и).
`deleteRow`	Удалить строку(и).
`addRow`	Вставить строку(и).
`deleteColumn`	Удалить столбец(цы).
`addColumn`	Вставить столбец(цы).
`groupAction`	Групповое действие (несколько подзадач).
`groupRowAction`	Групповое действие со строками.
`groupColAction`	Групповое действие со столбцами.
`addSheet`	Добавить новый лист.
`deleteSheet`	Удалить лист.
`renameSheet`	Переименовать лист.
`clearSheet`	Очистить все данные на листе.
`clear`	Очистить выделенные ячейки.
`resizeCol`	Изменить ширину столбца.
`resizeRow`	Изменить высоту строки.
`setValidation`	Установить валидацию данных для ячейки(ек).
`sortCells`	Сортировать ячейки.
`insertLink`	Вставить гиперссылку.
`fitColumn`	Автоматически подогнать ширину столбца под содержимое.
`filter`	Применить или изменить фильтр столбца.
`merge`	Объединить ячейки.
`unmerge`	Разъединить ячейки.
`toggleFreeze`	Переключить закрепление панелей.
`toggleVisibility`	Переключить видимость строки/столбца.

Псевдонимы типов обработчиков

Удобные псевдонимы для сигнатур функций, используемых пропсами-колбэками событий. Импортируйте их для явного аннотирования функций-обработчиков.

Тип	Сигнатура	Используется в
`BeforeActionHandler`	`(action: Actions \| string, config: IExecuteConfig) => boolean \| void`	`onBeforeAction`
`AfterActionHandler`	`(action: Actions \| string, config: IExecuteConfig) => void`	`onAfterAction`
`BeforeCellHandler`	`(cell: string) => boolean \| void`	`onBeforeSelectionSet`, `onBeforeSelectionRemove`, `onBeforeFocusSet`
`AfterCellHandler`	`(cell: string) => void`	`onAfterSelectionSet`, `onAfterSelectionRemove`, `onAfterFocusSet`
`BeforeEditHandler`	`(cell: string, value: string) => boolean \| void`	`onBeforeEditStart`, `onBeforeEditEnd`
`AfterEditHandler`	`(cell: string, value: string) => void`	`onAfterEditStart`, `onAfterEditEnd`
`BeforeSheetHandler`	`(sheet: ISheet) => boolean \| void`	`onBeforeSheetChange`
`AfterSheetHandler`	`(sheet: ISheet) => void`	`onAfterSheetChange`

SpreadsheetConfigProps

type SpreadsheetConfigProps = Omit<
    ISpreadsheetConfig,
    "leftSplit" | "topSplit" | "dateFormat" | "timeFormat"
>;

Базовый тип для пропсов компонента. Открывает все параметры конструктора ISpreadsheetConfig как плоские пропсы.

Переэкспортируемые вышестоящие типы

Эти типы переэкспортируются из @dhx/ts-spreadsheet для удобства:

Тип	Описание
`ISpreadsheet`	Интерфейс основного экземпляра виджета таблицы.
`ISpreadsheetConfig`	Интерфейс конфигурации конструктора.
`ISheet`	Интерфейс экземпляра листа (используется в колбэках событий листа).
`IFormats`	Определение пользовательского числового формата.
`IFilterRules`	Конфигурация правила фильтрации.
`IFilter`	Интерфейс экземпляра фильтра.
`IStylesList`	Карта определений стилей.
`IDataWithStyles`	Структура данных со встроенными стилями (используется `serialize()`/`parse()`).
`ICellInfo`	Информация о ячейке, возвращаемая методами виджета.
`FileFormat`	Формат файла для загрузки данных (например, `"json"` или `"xlsx"`).
`ToolbarBlocks`	Идентификаторы блоков панели инструментов (например, `"default"`, `"undo"` или `"font"`).
`FilterConditions`	Перечисление доступных типов условий фильтрации.
`Id`	Универсальный тип идентификатора (string \| number).

CellData​

RowConfig​

ColConfig​

MergedRange​

FreezeConfig​

SheetFilter​

SheetSort​

SheetData​

SearchConfig​

SpreadsheetLocale​

SpreadsheetTheme​

IExecuteConfig​

SpreadsheetRef​

Перечисление Actions​

Псевдонимы типов обработчиков​

SpreadsheetConfigProps​

Переэкспортируемые вышестоящие типы​

CellData

RowConfig

ColConfig

MergedRange

FreezeConfig

SheetFilter

SheetSort

SheetData

SearchConfig

SpreadsheetLocale

SpreadsheetTheme

IExecuteConfig

SpreadsheetRef

Перечисление Actions

Псевдонимы типов обработчиков

SpreadsheetConfigProps

Переэкспортируемые вышестоящие типы