# @azrico/reactgrid 中文文档

规范地址：https://npmcn.com/package/%40azrico/reactgrid/

版本：2\.2\.1
npm 元数据更新时间：2026-10-31T14:12:42.546Z
中文译文更新时间：2026-10-31T15:35:26.070Z
软件包许可：未声明

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40azrico/reactgrid
原文对照：https://npmcn.com/package/%40azrico/reactgrid/?lang=original
项目主页：http://./

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：810 kB，219 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：8 个
- peer 依赖：clsx \>=1\.2\.1，react \>=18\.2\.0 \|\| ^19\.0\.0，@azrico/object \>=1\.4\.97，react-use-size \>=3\.0\.1，@azrico/controls \>=1\.6\.4，@tanstack/react-table \>=8\.20\.0，@tanstack/react-virtual \>=3\.10\.0
- 首次发布：2022-11-29T21:47:21.462Z
- 最新版本发布：2026-10-31T14:12:42.368Z
- 已发布版本数：182（近 12 个月 30 个）

## 中文简介

React数据网格上的TanStack表

## 安装

```sh
npm install @azrico/reactgrid
```

也可以使用：`pnpm add @azrico/reactgrid`、`yarn add @azrico/reactgrid`、`bun add @azrico/reactgrid`

## README

# @azrico / reactgrid

用于Azrideus项目的私有React数据网格包。

## 使用

```tsx
import { AzGrid } from '@azrico/reactgrid';
import '@azrico/reactgrid/dist/src/themes/azgrid-theme.css'; // optional colours

const columns = [{ name: 'name', header: 'Name', defaultFlex: 1 }];
const rows = [{ __table_id: '1', name: 'Alice' }];

<AzGrid theme="light" columns={columns} dataSource={rows} />;
```

组件导入 `grid.css` （布局和结构，没有颜色）本身。 `azgrid-theme.css` 是可选的 令牌预设：它绘制的每一个元素 `--azgrid-*` 下面的变量具有内置的明暗回调。 如果没有它，网格呈现为未涂漆的，并继承页面的颜色，因此您可以根据样式表发布自己的样式表 稳定的 `azgrid__*` 类名代替。

同行依赖性: `react`， `@tanstack/react-table` (>= 8.20 `@tanstack/react-virtual` (> = 3.10)。 从1.x升级？读 [MIGRATION-2.0.md](https://npmcn.com/package/%40azrico/reactgrid/MIGRATION-2.0.md)： `gridOptions` 消失了，每个选项都是顶级道具。

## 道具

每一个 `x` / `defaultX` / `onXChange` 三人工作控制（传球） `x`)或不受控制（传球） `defaultX`）。

### 数据

| 道具 | 类型 | 描述 |
| --- | --- | --- |
| `dataSource` | `any[]` | `{ data, count? }` | `(params) => rows | Promise` | 或调用的加载器 `{ skip, limit, filterValue, sortInfo }`。加载器返回行或 `{ data, count }`. |
| `loading` | `boolean` | 显示加载掩码。 |
| `looseCacheCheck` | `boolean` | 在确定缓存是否仍然有效时，忽略数据源标识。 |
| `pagination` | `false | 'local' | 'remote'` | `remote` 为每个页面请求数据源， `local` 对加载的行进行分页。 |
| `limit` / `defaultLimit` / `onLimitChange` | `number` | 页面大小。 |
| `skip` / `defaultSkip` / `onSkipChange` | `number` | 当前页的偏移量。 |
| `pageSizes` | `number[]` | 选择页面大小。 |
| `remoteFilter` / `remoteSort` | `boolean` | 将筛选器或排序发送到数据源，而不是将它们应用于已加载的行。 |

### 列

| 道具 | 类型 | 描述 |
| --- | --- | --- |
| `columns` | `(LooseColumnDefinition | string)[]` | 列定义，请参见 [列定义](https://npmcn.com/package/%40azrico/reactgrid/#readme-column-definition). |
| `columnExtensions` | `LooseColumnDefinition[]` | 合并到同名的列中，现有值优先。 |
| `customColumns` | `{ name, render }[]` | 替换同名列的呈现。 |
| `editableColumns` | `string[]` | 使列的名称可编辑。 |
| `leftColumns` / `rightColumns` | `string[]` | 固定在起始或结束边缘的列。 |
| `clipScrolledCells` | `boolean` | 剪切固定柱覆盖的滚动单元格，而不是将固定单元格涂成不透明的，因此固定单元格可以保持半透明的背景。默认的 `false`. |
| `gridId` | `string` | 保存调整过的宽度，请参阅 [保存的列宽度](https://npmcn.com/package/%40azrico/reactgrid/#readme-saved-column-widths). |
| `resizable` / `sortable` | `boolean` | 没有设置自己的列的默认值（默认值） `true`）。 |
| `filterable` | `boolean` | 显示筛选器行。默认的 `true` 当列是可过滤的或给定了过滤值时。 |
| `onColumnResize` | `({ column, width }) => void` | 当调整大小结束时调用。 |
| `onColumnVisibleChange` | `({ column, visible }) => void` | 当列菜单隐藏或显示列时调用。 |
| `columnMenu` | `boolean` | 带有排序和显示/隐藏条目的标题菜单（默认） `true`）。 |
| `columnMenuItems` | `(column, api) => menu items` | 附加到每列标题菜单的项。 |

### 排序和过滤

| 道具 | 类型 | 描述 |
| --- | --- | --- |
| `sortInfo` / `defaultSortInfo` / `onSortInfoChange` | `{ name, dir: 1 | -1 } | null` | 单列。标头点击循环升序，降序，无。 |
| `filterValue` / `defaultFilterValue` / `onFilterValueChange` | `{ name, operator, type, value }[]` | 筛选行值。 |
| `filterTypes` | `{ [type]: { operators: { name, fn }[] } }` | 通过内置过滤器类型合并。 `fn({ value, filterValue, data })` 返回一个布尔值。 |
| `filterDelay` | `number` | 输入过滤器后等待的时间（默认为250毫秒）。 |
| `advancedFilterFields` | `string[]` | 由网格上方的快速搜索框搜索的列。 |
| `advancedFilterLabel` / `advancedFilterPlaceholder` | `ReactNode` | 快速搜索框的标签和占位符。 |

内置操作符：string `contains`， `eq`， `neq`， `startsWith`， `endsWith`;数量 `eq`， `neq`， `gt`， `gte`， `lt`， `lte`， `inrange`;选择 `eq`， `inlist`;保龄球 `eq`.

### 行

| 道具 | 类型 | 描述 |
| --- | --- | --- |
| `rowHeight` | `number | ({ data, rowIndex }) => number` | 行高，单位为px（默认为35）。函数形式设置每行的高度。 |
| `headerHeight` | `number` | 页眉高度，单位为px。 |
| `rowClassName` / `rowStyle` | 值或 `(rowProps) => value` | 类和样式的行。 |
| `onRenderRow` | `(rowProps) => void` | 为每个渲染行调用。您添加的键 `rowProps` 变成DOM属性。 |
| `showZebraRows` / `showHoverRows` | `boolean` | 条纹行和悬停油漆。 |
| `emptyText` | `ReactNode` | 当没有行时显示。 |
| `footer` | `{ render: { [column]: node }, colspan?: { [column]: n } }` | 一脚行，粘在底部。 |
| `highlightedRow` | 行或行id | 用活动样式绘制的行。 |
| `onRowReorder` | `({ rows, data, fromIndex, toIndex }) => void` | 允许用户重新排序行（见下文）。 |

#### 行重新排序

与 `onRowReorder` 用户可以用鼠标将一行拖动到新的位置，或者用鼠标移动活动行 Alt+箭头向上/ Alt+箭头向下。网格不会改变它的数据： `rows` 是否有加载的顶级行的新数组 它们的新顺序（相同的行对象），将其作为 `dataSource`. `data` 是移动的行， `fromIndex` 和 `toIndex` 它在移动前后加载行的索引。

```tsx
const [rows, setRows] = React.useState(initialRows);
<AzGrid columns={columns} dataSource={rows} onRowReorder={({ rows }) => setRows(rows)} />;
```

在对行进行排序（显示的顺序不是数据顺序）时关闭重新排序 `allowChildRows` 和 `pagination: 'remote'`。不能拖动具有打开单元格编辑器的行。拖放使用原生HTML5拖放， 所以它可以在鼠标上工作，而不是在触摸屏上。被拖拽的一行落在比它低一行的后面，比它高一行的前面。 拖动时，行得到 `azgrid__row--dragging` 指针下的那一行 `azgrid__row--drop-after` 或者 `--drop-before`，画成一条线 `--azgrid-accent`.

以适应 `n` 没有滚动条的行，给出网格 `get_grid_height(n, rowHeight, headerHeight)` Px的高度： `headerHeight + 1 + n * rowHeight + 2` （头部的1px底部边框和网格的1px顶部和底部边框的默认主题）。在显示时添加筛选器行、页脚和分页栏。

### 树和细节

| 道具 | 类型 | 描述 |
| --- | --- | --- |
| `allowChildRows` | `boolean` | 行 `__children` (或 `__parent__table_id`)渲染为树。 |
| `expandedNodes` / `defaultExpandedNodes` / `onExpandedNodesChange` | `{ [rowId]: boolean }` | 扩展的树节点。 |
| `RowDetail` | `({ data, rowIndex, rowId, toggle }) => ReactNode` | 在展开的行下呈现。添加展开列。 |
| `rowExpandHeight` | `number | ({ data }) => number` | 细节块的高度。 |
| `expandedRows` / `defaultExpandedRows` / `onExpandedRowsChange` | `{ [rowId]: boolean }` | 其详细信息已打开的行。 |

### 选择

| 道具 | 类型 | 描述 |
| --- | --- | --- |
| `selected` / `defaultSelected` / `onSelectionChange` | `true | { [rowId]: row } | null` | 选定的行。 `true` 表示所有行。 |
| `multiSelect` | `boolean` | 复选框与其单元格切换行，shift单击选择区域。 |
| `toggleSelectionOnRowClick` | `boolean` | 单击行上的任何位置都可以切换该行，就像切换复选框一样。如果没有它，行单击只会使行处于活动状态，而不会改变所选内容。 |
| `checkboxColumn` | `boolean` | 添加带有“全部选择”标题的复选框列。 |
| `checkboxOnlyRowSelect` | `boolean` | 只有复选框选择，行单击不选择。 |
| `rowIndexColumn` | `boolean` | 添加行号列。 |
| `cellSelection` / `defaultCellSelection` / `onCellSelectionChange` | `{ "rowId,column": true }` | 细胞的选择。 |

### 编辑

| 道具 | 类型 | 描述 |
| --- | --- | --- |
| `editable` | `boolean | (value, cellProps) => boolean` | 打开编辑。列的 `editable` 决定每列。 |
| `editStartEvent` | `'click' | 'dblclick'` | 事件，打开单元格编辑器(默认 `'dblclick'`）. Enter键在活动行上打开它。 |
| `onEditComplete` | `({ value, columnId, rowId, data, rowIndex }) => void` | 当输入、Tab或blur完成编辑时调用。网格不改变行，您拥有数据。 |
| `onEditStart` / `onEditCancel` | `({ rowId, columnId }) => void` | 在编辑器打开或Escape取消编辑器时调用。 |

### 键盘和事件

| 道具 | 类型 | 描述 |
| --- | --- | --- |
| `activeIndex` / `defaultActiveIndex` / `onActiveIndexChange` | `number` | 活跃的行。方向键，Home, End， PageUp和PageDown移动它。与 `onRowReorder`， Alt+向上/向下箭头移动行本身。 |
| `onKeyDown` | `(event) => void` | 网格根的关键事件。除非你调用，否则它们会在网格自己的处理之后运行 `preventDefault`. |
| `onRowClick` / `onRowDoubleClick` | `(rowIndex, row) => void` | 行点击。 |
| `contextMenuItems` | 菜单项或 `(row) => items` | 行上下文菜单，建立在 `@azrico/controls`. |
| `contextMenuClassName` | `string` | 行上下文菜单的额外类，它被传送到 `<body>`. |
| `hideContextMenu` | `boolean` | 使浏览器的上下文菜单可用。 |
| `longPressContextMenu` | `boolean` | 在一行上触摸500毫秒将打开行上下文菜单，就像右键单击一样，而结束按下的单击将被吞下（默认值） `true`）。 |
| `dontAutoCloseContextMenu` / `escapeClosesContextMenu` | `boolean` | 上下文菜单关闭行为（都是默认的） `false`）。 |

### Misc

| 道具 | 类型 | 描述 |
| --- | --- | --- |
| `gridRef` | `MutableRefObject<AzGridApi | null>` | 接收 [网格的API](https://npmcn.com/package/%40azrico/reactgrid/#readme-grid-api). |
| `theme` | `'light' | 'dark' | string` | 主题类，参见 [主题](https://npmcn.com/package/%40azrico/reactgrid/#readme-themes). |
| `rtl` | `boolean` | 将网格从右向左布置。没有它，网格在RTL页面上保持从左到右。 |
| `className` / `style` |  | 类和样式的网格容器。 |
| `ariaLabel` | `string` | 网格的可访问名称。 |
| `delayedSize` | `boolean` | 对于动画容器，在布局之前等待容器大小。 |
| `children` | `ReactNode` | 渲染网格后，在其容器内。 |

## 列定义

| 场 | 描述 |
| --- | --- |
| `name` | 行中值的键。 `field`， `key` 和 `columnName` 别名。 |
| `header` | 标题内容。 `title` 是别名。 |
| `type` | `'string'`， `'number'`， `'select'` 或者 `'bool'`． 选择编辑器和过滤器。 `combo`， `boolean` 和 `truefalse` 别名。 |
| `items` | a的选项 `select` 列，普通值或 `{ id, label }` 对象。 |
| `editable` | `boolean` 或者 `(value, cellProps) => boolean`． 默认情况下，键入的列是可编辑的。 |
| `renderEditor` / `editorProps` | 自定义编辑器 `(editorProps) => node`，并为编辑提供额外的道具。 |
| `render` | 自定义单元格内容 `(cellProps) => node`. `cellProps` 有 `value`， `data`， `rowIndex`， `rowId`， `depth`， `selected` 和 `active`. |
| `onRender` | `(cellProps, { data }) => void`，在渲染之前运行，并且可能会更改 `cellProps.className` / `cellProps.style`. |
| `className` | 字符串或 `(cellProps) => string`，添加到每个细胞中。 |
| `cellDOMProps` / `headerDOMProps` | 额外的DOM属性。你赢了电网。 |
| `ariaLabel` | `(value, data) => string`, `aria-label` 细胞的。 |
| `width` / `defaultWidth`， `minWidth`， `maxWidth` | 宽度单位为px。保存的宽度替换 `width`. |
| `flex` / `defaultFlex` | 剩余宽度的份额。调整大小或保存的宽度将取代它。 |
| `resizable`， `sortable`， `filterable`， `hideable` | 每列的开关。 |
| `sort` | 比较器 `(a, b, rowA, rowB) => number`，或者 `false` 禁用排序。 |
| `filterEditor` / `filterEditorProps` | `'text'`， `'number'`， `'select'`， `'bool'` 或者一个组件，以及它的props (`placeholder`， `dataSource`）。 |
| `visible` / `defaultVisible` | 受控或初始能见度。 |
| `pinned` | `'left'` 或者 `'right'`． 通常通过 `leftColumns` / `rightColumns`. |
| `textAlign` | `'start'`， `'center'` 或者 `'end'`. |

## 网格的API

`gridRef.current` 公开:

| 成员 | 描述 |
| --- | --- |
| `focus()` | 聚焦网格。 |
| `setActiveIndex(index)` / `getActiveIndex()` | 设置或读取活动行并将其滚动到视图中。 |
| `getDOMNode()` | 网格根元素。 |
| `visibleColumns` | 显示顺序中的可见列。 |
| `getData()` | 已加载的顶级行。孩子们在 `__children`. |
| `setOriginalData(rows)` | 在不调用数据源的情况下替换已加载的行。 |
| `setItemAt(index, item, { replace? })` | 合并或替换已加载的一行。 |
| `setItemPropertyAt(index, property, value)` | 更改已加载行的一个值。 |
| `refresh()` / `refreshColumn(name)` | 重新呈现每行或一列的单元格。 |
| `reload()` | 删除缓存并再次调用数据源。 |
| `startEdit({ rowId, columnId })` / `cancelEdit()` | 打开或取消编辑器。 |
| `setSelected(value)` | 设置行选择。 |
| `hideColumnMenu()` | 关闭标题菜单。 |

## DOM类

网格呈现稳定的BEM类名。自由设置样式或查询它们。它们被输出为 `AZGRID_CLASSES`.

| 类 | 元素 |
| --- | --- |
| `azgrid` | 网格根(`role="grid"`), `azgrid--rtl` 当 `rtl` 是集, `azgrid--clip-scrolled` 与 `clipScrolledCells` 和 `azgrid--reorderable` 而行可以重新排序 |
| `azgrid__scroller` | 滚动页眉，正文和页脚的容器 |
| `azgrid__header`， `azgrid__header-row`， `azgrid__header-cell` | 头。细胞携带 `data-column` |
| `azgrid__sort-tool`， `azgrid__menu-tool`， `azgrid__resize-handle` | 标题单元格工具 |
| `azgrid__filter-row`， `azgrid__filter-cell` | 过滤行 |
| `azgrid__body`， `azgrid__row-wrapper`， `azgrid__row` | 体和行。行把 `data-row-id` |
| `azgrid__cell`， `azgrid__cell-content` | 身体细胞。细胞携带 `data-column` |
| `azgrid__row-index`， `azgrid__checkbox`， `azgrid__expander`， `azgrid__tree-tool` | 内置列和工具 |
| `azgrid__details` | 行详细信息块 |
| `azgrid__editor` | 打开单元格编辑器的包装器 |
| `azgrid__footer`， `azgrid__footer-cell` | 页脚行 |
| `azgrid__pagination` | 分页栏 |
| `azgrid__load-mask`， `azgrid__empty` | 加载掩码和空文本 |
| `azgrid-row--menu-open` | 行，其上下文菜单处于打开状态 |
| `azgrid-column-menu` | 标题菜单弹出(传送到 `<body>`，承载主题类和 `data-column`） |
| `azgrid-column-menu__submenu` | “列”子菜单弹出，也有 `azgrid-column-menu` |
| `azgrid-column-menu__list`， `azgrid-column-menu__separator` | 项目清单(`role="menu"`)和组与组之间的界限 |
| `azgrid-column-menu__item` | 菜单项，带有 `__icon`， `__label` 和（子菜单触发器） `__arrow` 孩子们 |
| `azgrid-column-menu__text`， `azgrid-column-menu__element` | `type: 'text'` / `type: 'element'` 条目的 `columnMenuItems` |

头菜单项获得命名条目的修饰符： `--sort-asc`， `--sort-desc`， `--unsort`， `--columns` (子菜单 触发), `--column` (子菜单中的显示/隐藏复选框，也带有 `data-column`), `--custom` （`columnMenuItems`）。 州修饰符: `--active` (当前排序，或 `isActive` （自定义项）， `--checked` （可见栏）和 `--open` （显示子菜单时触发子菜单）。

行得到 `--odd`/`--even`， `--selected`， `--active`， `--expanded` 和 `--editing` 修饰符, `--dragging`， `--drop-before`/`--drop-after` 在行重新排序期间。细胞变得 `--selected`， `--active`， `--editing`， `--readonly`， `--pinned-left`/`--pinned-right` 和 `--pinned-edge` 修饰符。标题单元格得到 `--sortable`， `--sorted-asc`/`--sorted-desc` 和 `--resizing` 修饰符。

## 保存的列宽度

集 `gridId` 为了保持列的宽度，用户可以在重新加载时调整大小。宽度保存在 `localStorage` 并按名称匹配到列。

```tsx
import { AzGrid, setGridStorageScope, clearColumnSizes } from '@azrico/reactgrid';

setGridStorageScope(user.id); // once, before the grids render, so users of one browser don't share widths

<AzGrid gridId="current-stock" columns={columns} dataSource={rows} />;

clearColumnSizes('current-stock'); // reset, takes effect when the grid remounts
```

一列的 `width` 被用作 `defaultWidth` 当 `gridId` 设置，因此可以调整其大小。

## 可访问性

网格公开ARIA网格语义，因此屏幕阅读器和自动化工具可以从可访问性树中读取它。

| 元素 | 属性 |
| --- | --- |
| 网格根 | `role="grid"`， `aria-rowcount` （包含header的总行数；分页时的完整数据计数）， `aria-colcount` (列)可见, `aria-label`， `aria-readonly="true"` 当网格不可编辑时， `aria-busy="true"` 同时加载 |
| 标题行 | `role="row"`， `aria-rowindex="1"` |
| 头细胞 | `role="columnheader"`， `aria-colindex`， `aria-sort` （`ascending` / `descending` / `none`（仅可排序的列）， `data-column="<column id>"` |
| 行 | `role="row"`， `aria-rowindex` （基于1，页眉为1，包括页偏移量）， `aria-selected` 启用选择后， `data-row-id` |
| 身体细胞 | `role="gridcell"`， `aria-colindex`， `data-column="<column name>"`， `aria-readonly="true"` 当单元格无法编辑时 |
| 行号细胞 | `role="rowheader"` |

新道具:

-   `ariaLabel?: string` 在网格上设置网格的可访问名称。
-   `ariaLabel?: (value, data) => string` 在列集上 `aria-label` 在细胞上。使用它的图标，徽章或值的可见文本不是描述性的。

```tsx
const columns = [{ name: 'status', header: 'Status', ariaLabel: (value) => `Status: ${value}` }];

<AzGrid ariaLabel="Orders" columns={columns} dataSource={rows} />;
```

用列的属性覆盖任何单元格属性 `cellDOMProps` / `headerDOMProps`． 您在那里设置的值将被保留。 一个 `onRenderRow` Prop在设置网格自身的行属性后运行，因此它也可以更改它们。

## 主题

使用 `theme="light"` (默认), `theme="dark"`，或自定义名称。网格包装器得到 `azgrid-scope` 和 `azgrid-theme-<name>`;传送的列和上下文菜单(`.azgrid-column-menu`， `.azgrid-context-menu`)得到 相同的主题类，所以它们读取相同的变量。自定义名称对未指定的变量使用少量回退。

`dark` 仍然是一个弃用的别名。 `theme` 优先。

集 `--azgrid-*` 包装器上的变量， `:root`，或者主题课。每个网格可以使用不同的调色板。主人 变量总是占上风：主题文件只声明 `--azgrid-preset-*` 后备方案，永远不要公开默认。

```tsx
<div className="my-grid">
  <AzGrid theme="light" columns={columns} dataSource={rows} />
</div>
```

```css
.my-grid {
  --azgrid-accent: #345b93;
  --azgrid-header-bg: #edf2f8;
  --azgrid-row-bg-hover: #e4ecf7;
}
```

行状态是按这个顺序绘制的（后期获胜）：斑马奇数/偶数，树行，活动，悬停（同时行） 上下文菜单打开)，选中。固定单元格复制行当前背景，以便在滚动时保持不透明。

检查样式表 `node config/check-theme.cjs`;重新生成预设块和下面的表格 `node config/generate-theme.cjs` 编辑该文件中的令牌清单后。

## CSS变量

所有变量都有浅/暗回退。为指定的属性使用有效的CSS值。 `--azgrid-locked-column-shadow` 接受完整的 `box-shadow` 价值。 `--azgrid-header-height` 不就是一个记号吗 网格将其设置在测量标题的根上，以便过滤器行可以粘贴在其下面。

| 变量 | 控制 |
| --- | --- |
| `--azgrid-bg` | 网格背景 |
| `--azgrid-fg` | 网格的文本 |
| `--azgrid-border` | 网格边框和分隔符 |
| `--azgrid-font-family` | 网格和控件字体 |
| `--azgrid-radius` | 网格、输入和菜单角半径；默认的 `0` |
| `--azgrid-accent` | 聚焦轮廓、排序箭头、调整大小手柄、复选框、单元格选择和行重新排序下拉线 |
| `--azgrid-transparent` | 透明结构表面（主体、行包装、工具按钮） |
| `--azgrid-muted-fg` | 只读单元格，非活动排序和菜单工具，删除行 |
| `--azgrid-shadow-color` | 菜单阴影颜色 |
| `--azgrid-header-bg` | 页眉和页脚背景 |
| `--azgrid-header-fg` | 页眉和页脚文本 |
| `--azgrid-header-border` | 页眉、过滤行和页脚分隔符 |
| `--azgrid-header-font-size` | 页眉字体大小 |
| `--azgrid-header-text-transform` | 标题文本转换 |
| `--azgrid-header-letter-spacing` | 页眉间距 |
| `--azgrid-header-font-weight` | 页眉字体粗细 |
| `--azgrid-row-bg-even` | 均匀和非斑马行 |
| `--azgrid-row-bg-odd` | 奇数行（斑马网格） |
| `--azgrid-row-bg-hover` | 悬停行，打开菜单的行，悬停按钮 |
| `--azgrid-row-fg-hover` | 悬停行文本 |
| `--azgrid-row-bg-selected` | 选定的行和单元格 |
| `--azgrid-row-fg-selected` | 选定的行和单元格文本 |
| `--azgrid-row-bg-active` | 活动的（聚焦的）行 |
| `--azgrid-cell-border` | 细胞边框颜色 |
| `--azgrid-cell-border-width` | 单元格边框宽度 |
| `--azgrid-cell-padding` | 数据和页脚单元格填充 |
| `--azgrid-filter-bg` | 过滤行，输入，编辑器和搜索背景 |
| `--azgrid-filter-fg` | 过滤输入和编辑文本 |
| `--azgrid-filter-border` | 过滤输入边界 |
| `--azgrid-filter-placeholder` | 输入占位符文本 |
| `--azgrid-filter-focus-ring` | 聚焦输入边框和环，打开编辑器大纲 |
| `--azgrid-pagination-bg` | 分页工具栏和控制背景 |
| `--azgrid-pagination-fg` | 分页文本和图标 |
| `--azgrid-pagination-border` | 分页控制边界 |
| `--azgrid-menu-bg` | 列和上下文菜单背景 |
| `--azgrid-menu-fg` | 菜单文本和图标 |
| `--azgrid-menu-border` | 菜单边界 |
| `--azgrid-menu-bg-hover` | 悬停和聚焦菜单项 |
| `--azgrid-scrollbar-track` | 滚动条铁轨 |
| `--azgrid-scrollbar-thumb` | 滚动条拇指 |
| `--azgrid-empty-bg` | 空状态背景 |
| `--azgrid-empty-fg` | 空状态文本 |
| `--azgrid-loading-bg` | 加载叠加背景 |
| `--azgrid-loading-fg` | 加载文本 |
| `--azgrid-tree-bg` | 树格行背景 |
| `--azgrid-tree-fg` | 树网格文本和展开工具 |
| `--azgrid-details-bg` | 行详情背景 |
| `--azgrid-locked-column-shadow` | 钉柱边缘阴影(完成 `box-shadow` 值) |
|  |  |

## 例子

看到 [src / example.tsx](https://npmcn.com/package/%40azrico/reactgrid/src/example.tsx) 对于明、暗有一个完整的习惯 `deco` 调色板。

自定义渲染器必须为自己的内容设置样式。需要外部菜单门户容器 `azgrid-scope`、匹配 `azgrid-theme-<name>` 类和主机变量。

## 常见问题

### @azrico/reactgrid 是什么？

React数据网格上的TanStack表

### 如何安装 @azrico/reactgrid？

在项目目录运行 npm install @azrico/reactgrid，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：clsx（\>=1\.2\.1）、react（\>=18\.2\.0 \|\| ^19\.0\.0）、@azrico/object（\>=1\.4\.97）、react-use-size（\>=3\.0\.1）、@azrico/controls（\>=1\.6\.4）、@tanstack/react-table（\>=8\.20\.0）、@tanstack/react-virtual（\>=3\.10\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @azrico/reactgrid 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @azrico/reactgrid 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @azrico/reactgrid 可以商用吗？

@azrico/reactgrid 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @azrico/reactgrid 还在维护吗？

最新版本 2\.2\.1 发布于 2026/10/31（2 天前）；至今共发布 182 个版本，其中过去 12 个月发布了 30 个；首次发布于 2022/11/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。