跳到主要内容

类型参考

所有类型均从 @dhx/react-spreadsheet 或 @dhtmlx/trial-react-spreadsheet 导出。

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

CellData​

单个单元格的声明式状态。所有属性均为可选；更新时省略的属性将保留其当前值。

属性类型描述
valuestring | number单元格值：文本、数字或公式字符串（以 = 开头）。
cssstringCSS 类名，引用顶层 styles 映射中的键。
formatstring数字格式掩码或别名（例如 "currency" 或 "#,##0.00"）。
lockedboolean单元格是否锁定（禁止编辑）。
validationstring | string[]数据验证下拉选项。

RowConfig​

行元数据。只有具有非默认配置的行才需要条目。

属性类型描述
heightnumber行高（像素）。
hiddenboolean行是否隐藏。

ColConfig​

列元数据。只有具有非默认配置的列才需要条目。

属性类型描述
widthnumber列宽（像素）。
hiddenboolean列是否隐藏。

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​

sheet 的冻结窗格配置。

属性类型描述
colnumber冻结至此从 0 开始的列号之前的所有列。undefined 表示不冻结列。
rownumber冻结至此从 0 开始的行号之前的所有行。undefined 表示不冻结行。

SheetFilter​

sheet 中某列的筛选配置。

属性类型描述
cellstring标识筛选列的单元格引用（例如 "A1"）。
rulesIFilterRules[]要应用的筛选规则。空数组将清除筛选。

SheetSort​

sheet 中某列的排序配置。

属性类型描述
cellstring排序操作的单元格引用或范围（例如 "B1" 或 "A1:E8"）。使用范围可在保持行完整性的同时对多列排序。
dir1 | -1排序方向：1 = 升序，-1 = 降序。

SheetData​

单个电子表格 sheet 的完整声明式状态。

属性类型必填描述
idId是唯一的 sheet 标识符。必须在渲染间保持稳定。
namestring是显示在 sheet 标签上的名称。
cellsRecord<string, CellData>是以单元格引用为键的单元格数据（例如 "A1" 或 "B2"）。只有具有非默认数据的单元格才需要条目。
rowsRecord<number, RowConfig>否以从 0 开始的行号为键的行配置。
colsRecord<number, ColConfig>否以从 0 开始的列号为键的列配置。
mergedMergedRange[]否合并单元格范围。
freezeFreezeConfig否冻结窗格配置。
filterSheetFilter否列筛选配置。设为 undefined 可清除筛选。
sortSheetSort否排序配置。

示例：

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 可关闭搜索。

属性类型必填描述
querystring是要搜索的文本。
openboolean否是否打开内置搜索 UI。默认值：false。
sheetIdId否按 id 将搜索限定在特定 sheet 中。

SpreadsheetLocale​

UI 标签和公式名称的本地化配置。

属性类型描述
localeRecord<string, string>UI 字符串覆盖。键与库的语言字典匹配。
formulasRecord<string, [string, string?][]>按分类分组的本地化公式名称。每个条目为元组：[localizedName, optionalDescription?]。

SpreadsheetTheme​

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

内置颜色主题。也接受自定义主题名称字符串。

IExecuteConfig​

传递给 onBeforeAction / onAfterAction 的操作执行配置。形状因操作类型而异。

属性类型描述
rownumber目标行索引。
colnumber目标列索引。
targetunknown特定操作的目标。
valunknown新值。
prevunknown原值。
actionActions | string操作标识符。
groupActionActions | string父组操作标识符。
cellstring单元格引用（例如 "A1"）。
pageIdId目标 sheet id。
pageNamestring目标 sheet 名称。
[key: string]unknown其他特定操作属性。

SpreadsheetRef​

通过 React.forwardRef 暴露的命令式句柄。提供对底层 DHTMLX Spreadsheet 实例的直接访问，用于无法映射到声明式 props 的操作。

属性类型描述
instanceISpreadsheet | null底层 widget 实例。初始化前和卸载后为 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添加新 sheet。
deleteSheet删除 sheet。
renameSheet重命名 sheet。
clearSheet清除 sheet 中的所有数据。
clear清除选中的单元格。
resizeCol调整列宽。
resizeRow调整行高。
setValidation为单元格设置数据验证。
sortCells对单元格排序。
insertLink插入超链接。
fitColumn自动调整列宽以适应内容。
filter应用或更改列筛选。
merge合并单元格。
unmerge取消合并单元格。
toggleFreeze切换冻结窗格。
toggleVisibility切换行/列可见性。

处理器类型别名​

事件 callback props 所用函数签名的便捷别名。导入这些别名可对处理器函数进行显式类型标注。

类型签名用于
BeforeActionHandler(action: Actions | string, config: IExecuteConfig) => boolean | voidonBeforeAction
AfterActionHandler(action: Actions | string, config: IExecuteConfig) => voidonAfterAction
BeforeCellHandler(cell: string) => boolean | voidonBeforeSelectionSet、onBeforeSelectionRemove、onBeforeFocusSet
AfterCellHandler(cell: string) => voidonAfterSelectionSet、onAfterSelectionRemove、onAfterFocusSet
BeforeEditHandler(cell: string, value: string) => boolean | voidonBeforeEditStart、onBeforeEditEnd
AfterEditHandler(cell: string, value: string) => voidonAfterEditStart、onAfterEditEnd
BeforeSheetHandler(sheet: ISheet) => boolean | voidonBeforeSheetChange
AfterSheetHandler(sheet: ISheet) => voidonAfterSheetChange

SpreadsheetConfigProps​

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

组件 props 的基础类型。将所有 ISpreadsheetConfig 构造函数选项作为扁平 props 暴露。

重新导出的上游类型​

以下类型从 @dhx/ts-spreadsheet 重新导出，以便使用：

类型描述
ISpreadsheet主电子表格 widget 实例接口。
ISpreadsheetConfig构造函数配置接口。
ISheetSheet 实例接口（在 sheet 事件 callbacks 中使用）。
IFormats自定义数字格式定义。
IFilterRules筛选规则配置。
IFilter筛选实例接口。
IStylesList样式定义映射。
IDataWithStyles含内嵌样式的数据结构（由 serialize()/parse() 使用）。
ICellInfowidget 方法返回的单元格信息。
FileFormat数据加载的文件格式（例如 "json" 或 "xlsx"）。
ToolbarBlocks工具栏块标识符（例如 "default"、"undo" 或 "font"）。
FilterConditions可用筛选条件类型的枚举。
Id通用标识符类型（string | number）。
Need more help?Contact Support