跳到主要内容

Props 参考

所有 props 均为可选。若未提供任何 props，组件将以默认设置渲染一个空白电子表格。

仅初始化 props​

修改这些 props 中的任意一个都会导致 widget 被销毁并重新创建。电子表格数据会被保留，但撤销/重做历史记录及 UI 状态（选区、滚动位置）将被重置。

Prop类型描述
menuboolean显示右键菜单。JS API 参见：menu。
editLineboolean在表格上方显示公式/编辑栏。JS API 参见：editLine。
toolbarBlocksToolbarBlocks[]要显示的工具栏块。JS API 参见：toolbarBlocks。
multiSheetsboolean启用多工作表标签页。JS API 参见：multisheets。
formatsIFormats[]自定义数字格式定义。JS API 参见：formats。
localizationISpreadsheetConfig["localization"]数字/日期格式化区域设置，例如小数分隔符和货币符号。与 spreadsheetLocale 独立。JS API 参见：localization。
importModulePathstringXLSX 导入模块的路径。JS API 参见：importModulePath。
exportModulePathstringXLSX 导出模块的路径。JS API 参见：exportModulePath。
spreadsheetLocaleSpreadsheetLocaleUI 翻译及本地化公式名称。与 localization 独立。
readonlyboolean启用只读模式。用户可以导航、选择、复制和搜索单元格，编辑操作会被拒绝。JS API 参见：readonly。
警告

修改任何仅初始化 prop 都会触发完整的销毁/重建周期。撤销/重做历史记录、选区和滚动位置将被重置。

运行时 props​

这些 props 无需销毁 widget 即可立即生效，不会造成数据丢失或 UI 状态重置。

Prop类型描述
rowsCountnumber表格的行数。JS API 参见：rowsCount。
colsCountnumber表格的列数。JS API 参见：colsCount。
selectionboolean开启或关闭单元格选择。默认值：true。设为 false 时，电子表格没有活动单元格，也无法通过 UI 选择或编辑单元格。JS API 参见：selection。

数据 props​

sheets prop 是所有电子表格内容的唯一数据源。变更以增量方式应用：仅将已修改的单元格、区域或设置更新到 widget 中。

Prop类型描述
sheetsSheetData[]所有电子表格数据的唯一数据源。每个条目代表一个工作表，包含其单元格、结构和元数据。变更以增量方式应用。
stylesRecord<string, Record<string, string>>由 CellData.css 引用的共享 CSS 样式定义。键为类名，值为 CSS 属性映射。参见 样式示例。
activeSheetId活动（可见）工作表的 Id。更改此值将切换显示的工作表标签页。
警告

修改 styles 会触发完整的数据重新加载。电子表格数据会被保留，但撤销/重做历史记录及 UI 状态（选区、滚动位置）将被重置。

搜索 props​

从组件外部控制搜索栏状态。配合 onSearchResults 使用，可构建自定义搜索 UI。

Prop类型描述
searchSearchConfig受控搜索状态。传入 SearchConfig 对象以触发/更新搜索。传入 undefined 以关闭搜索栏。

数据加载 props​

从远程 URL 加载电子表格数据，而非通过 sheets prop 提供。

Prop类型描述
loadUrlstring加载电子表格数据的 URL。若同时提供 loadUrl 和 sheets，则 sheets 优先。
loadFormatFileFormatloadUrl 的文件格式提示。默认值："json"。

主题 prop​

控制应用于电子表格的视觉主题。由于 theme 是运行时 prop，值变更后 widget 会立即更新。

Prop类型描述
themeSpreadsheetTheme颜色主题。内置值："light"、"dark"、"contrast-light"、"contrast-dark"。也接受自定义主题名称字符串。参见 主题。

容器 props​

应用于包裹电子表格的 <div> 的标准 React DOM props，用于控制尺寸和布局。

Prop类型描述
classNamestring追加到封装器 <div> 的 CSS 类名。
styleReact.CSSProperties应用于封装器 <div> 的内联样式。

示例​

包含单元格数据的工作表​

一个完整的 SheetData 示例，包含单元格、行列尺寸、合并区域和冻结标题行。

const [sheets, setSheets] = useState<SheetData[]>([
    {
        id: "sheet1",
        name: "Budget",
        cells: {
            A1: { value: "Item", css: "header" },
            B1: { value: "Amount", css: "header", format: "currency" },
            A2: { value: "Rent" },
            B2: { value: 2000, format: "currency" },
            A3: { value: "=SUM(B2:B3)" },
        },
        rows: { 0: { height: 40 } },
        cols: { 0: { width: 150 }, 1: { width: 120 } },
        merged: [{
            from: { row: 0, column: 0 },
            to: { row: 0, column: 1 }
        }],
        freeze: { row: 1 },
    },
]);

<ReactSpreadsheet sheets={sheets} activeSheet="sheet1" />

样式示例​

在 styles prop 中将命名样式定义为 CSS 属性映射，然后通过 CellData.css 按名称引用。

const styles = {
    header: {
        "font-weight": "bold",
        "background": "#e3f2fd",
        "color": "#1565c0",
    },
    highlight: {
        "background": "#ffeb3b",
        "color": "#333",
    },
};

<ReactSpreadsheet sheets={sheets} styles={styles} />

工具栏自定义​

<ReactSpreadsheet
    sheets={sheets}
    toolbarBlocks={["undo", "colors", "decoration", "align", "format"]}
/>

多工作表模式​

通过 multiSheets={true} 启用工作表标签页。传入 false 可完全隐藏标签栏。

<ReactSpreadsheet sheets={sheets} multiSheets={true} />
<ReactSpreadsheet sheets={sheets} multiSheets={false} />

Excel 导入/导出​

<ReactSpreadsheet
    sheets={sheets}
    importModulePath="../libs/excel2json/next/worker.js"   
    exportModulePath="../libs/json2excel/next/worker.js"   
/>

如需使用特定版本，请将 next 替换为版本号（参见 Excel2Json 和 Json2Excel GitHub 仓库）。

欧式数字格式化​

<ReactSpreadsheet
    sheets={sheets}
    localization={{
        decimal: ",",
        thousands: ".",
        currency: "€",
    }}
/>

传入 SearchConfig 对象以编程方式打开搜索栏。使用 onSearchResults 接收匹配的单元格引用。

const [search, setSearch] = useState<SearchConfig | undefined>();
const [results, setResults] = useState<string[]>([]);

<input onChange={(e) =/> setSearch({ query: e.target.value, open: true })} />
<button onClick={() => setSearch(undefined)}>Close Search</button>
<p>Found in: {results.join(", ")}</p>

<ReactSpreadsheet
    sheets={sheets}
    search={search}
    onSearchResults={setResults}
/>

主题切换​

const [theme, setTheme] = useState<SpreadsheetTheme>("light");

<select onChange={(e) => setTheme(e.target.value as SpreadsheetTheme)}>
    <option value="light">Light</option>
    <option value="dark">Dark</option>
    <option value="contrast-light">Contrast Light</option>
    <option value="contrast-dark">Contrast Dark</option>
</select>

<ReactSpreadsheet sheets={sheets} theme={theme} />

只读模式​

在只读模式下，用户可以使用键盘在单元格间导航，用鼠标选择单元格，以及复制和搜索单元格。编辑操作会被拒绝，并向屏幕阅读器播报。由于 readonly 是仅初始化 prop，修改它会重新创建 widget。数据会被保留，而撤销/重做历史记录及 UI 状态（选区、滚动位置）将被重置。

<ReactSpreadsheet sheets={sheets} readOnly={true} />

若要同时关闭键盘导航和选择，请添加 selection={false}。selection prop 在运行时生效，因此无需重新创建 widget 即可切换：

<ReactSpreadsheet sheets={sheets} readOnly={true} selection={false} />

从 URL 加载数据​

<ReactSpreadsheet loadUrl="/api/spreadsheet-data" loadFormat="json" />

锁定单元格​

使用 locked: true 将单个单元格标记为不可编辑。与 readonly 不同，此方式可在保持其余工作表可编辑的同时，保护特定单元格。

const sheets: SheetData[] = [
    {
        id: "sheet1",
        name: "Protected",
        cells: {
            A1: { value: "Header", locked: true },
            A2: { value: "Editable" },
        },
    },
];

<ReactSpreadsheet sheets={sheets} />

单元格校验​

向 CellData.validation 传入字符串数组，将单元格限制为下拉列表中的允许值。

const sheets: SheetData[] = [
    {
        id: "sheet1",
        name: "Form",
        cells: {
            A1: { value: "Status" },
            B1: { validation: ["Active", "Inactive", "Pending"] },
        },
    },
];

<ReactSpreadsheet sheets={sheets} />
Need more help?Contact Support