数据表格 React API · Needless UI

导入

import-grid.tsx

import { NuiGrid, type NuiGridColumn, type NuiGridHandle } from '@needless-ui/react/grid';

NuiGrid

基于原生 table 元素的数据表格。

NuiGrid: 属性
名称	类型	默认值	说明
`rows`prop	`readonly T[]`		数据。编辑会替换对应的行并调用 `onRowsChange`；之后传入的 `rows` 会取代这些编辑。
`onRowsChange`回调	`(rows: readonly T[]) => void`		每次提交编辑后调用，参数为编辑后的行。
`columns`prop	`NuiGridColumn<T>[]`		列，以 `NuiGridColumn` 对象的形式提供。
`rowId`prop	`(row: T) => unknown`	`row.id ?? row`	行的 key，用于选择和跟踪。
`label`prop	`string`		表格的可访问名称。
`selection`prop	`'none' \| 'single' \| 'multiple'`	`'none'`	行是否可选，以及可选几行。
`selected` `defaultSelected` `onSelectedChange`状态	`unknown[]`	`[]`	所选行的 key。
`sort` `defaultSort` `onSortChange`状态	`NuiGridSort[]`	`[]`	排序，以 `{ column, direction }` 对象的形式提供；排在前面的优先。
`filters` `defaultFilters` `onFiltersChange`状态	`Record<string, NuiGridFilter>`	`{}`	按列 id 设置的筛选条件：一个运算符和一个值。
`search` `defaultSearch` `onSearchChange`状态	`string`	`''`	必须全部出现在同一行中的词。
`pageSize` `defaultPageSize` `onPageSizeChange`状态	`number`	`0`	每页行数；设为 0 则显示为一个滚动列表。
`page` `defaultPage` `onPageChange`状态	`number`	`0`	当前显示的页，从 0 开始。
`pageSizes`prop	`number[]`	`[10, 25, 50, 100]`	分页器中可选的每页行数。
`virtual`prop	`boolean \| 'auto'`	`'auto'`	只渲染可见的行：始终、从不，或 `auto`（不分页且超过 100 行时启用）。
`height`prop	`string`		限制表格高度的 CSS 长度，内容在表格内部滚动。
`columnState` `defaultColumnState` `onColumnStateChange`状态	`NuiGridColumnState[]`	`[]`	每列的宽度、顺序、固定和可见性，用于保存和恢复。
`mode`prop	`'client' \| 'server'`	`'client'`	`server` 按原样显示收到的行，把排序、筛选和分页交给你处理。
`total`prop	`number`		服务器上的总行数。
`loading`prop	`boolean`	`false`	显示进度条；没有行时显示占位行。
`locale`prop	`string`	`'en-US'`	用于格式化数字和日期，以及解析输入的数字。
`labels`prop	`Partial<NuiGridLabels>`		表格显示或播报的所有文本，供翻译使用。
`corners`prop	`NuiCorners`		边角的形状：`round`、`squircle`、`bevel`、`scoop`、`notch` 或 `square`。
`radius`prop	`NuiRadius`		边角的大小：`none`、`small`、`medium`、`large` 或 `full`。
`density`prop	`NuiDensity`		占用的空间：`compact`、`regular` 或 `roomy`。
`groupBy`prop	`string[]`	`[]`	用于对行分组的列，从最外层开始。
`collapsed` `defaultCollapsed` `onCollapsedChange`状态	`string[]`	`[]`	已折叠分组的 key；分组默认展开。
`getChildren`prop	`(row: T) => T[] \| undefined`		行的子行：表格会显示树形数据。
`expanded` `defaultExpanded` `onExpandedChange`状态	`unknown[]`	`[]`	树形数据中已展开行的 key；行默认折叠。
`details` `defaultDetails` `onDetailsChange`状态	`unknown[]`	`[]`	已打开详情的行的 key。
`totals, flash`prop	`boolean`	`false`	一行汇总所有筛选后行的聚合值；以及文本变化时会闪烁的单元格，仅适用于具有固定 `rowId` 的行。
`layout`prop	`'table' \| 'list' \| 'auto'`	`'table'`	`list` 以卡片显示行，`auto` 则只在窄屏上这样显示。
`toolbar`prop	`boolean \| 'auto'`	`'auto'`	对行排序、筛选和全选的工具栏：始终、从不，或 `auto`（显示卡片时出现）。
`renderEmpty`渲染 prop	`(filtered: boolean) => ReactNode`		没有行时显示的内容；参数会说明这些行是否被筛选条件隐藏。
`renderDetail`渲染 prop	`(row: T) => ReactNode`		行的详情，打开后显示在该行下方。表格会添加一列切换按钮。
`onRowActivate`回调	`(row: T) => void`		按 Enter 键或双击打开某行时调用，参数为该行。
`onCellEdit`回调	`(edit: NuiGridEdit<T>) => void`		每次提交编辑时调用，参数为该编辑。
`onQueryChange`回调	`(query: NuiGridQuery) => void`		排序、筛选、搜索或页码变化时调用，参数为它们；开始时也会调用一次。
`ref`prop	`Ref<NuiGridHandle>`		表格的 `ref` 能调用的方法：导出、打印和焦点。
`exportXlsx, print`方法	`(options?) => Blob, () => void`		以电子表格形式导出筛选和排序后的行；打印所有行。
`exportCsv`方法	`(options?) => string`		以 CSV 格式返回筛选和排序后的行，只包含可见的列。
`expandAll`方法	`(open?: boolean) => void`		展开所有分组和所有带子行的行，或全部折叠。
`focusCell`方法	`(row: number, col: number) => void`		让某个单元格获得焦点；第 `-1` 行是表头。
`clearFilters`方法	`() => void`		清除所有筛选条件和搜索。
`fit`方法	`(id: string) => void`		把列宽调整为已渲染单元格中最宽的那个。

状态的用法与 React 自带的表单输入相同：传入一个值，并在它的 on…Change 回调中更新；或者传入 default… 值，让组件自己保存。

用于自定义的 prop 如果未设置，会沿用最近的 data-nui-* 属性。详见自定义指南。

NuiGridColumn

一列。接收 Angular 列的所有属性（只有 id 和 header 是必需的），以及用来绘制该列的这两个属性。

NuiGridColumn: 属性
名称	类型	默认值	说明
`renderCell`渲染 prop	`({ row, value, text, column }) => ReactNode`		自行绘制该列的单元格，参数为行、它的值和文本。
`renderHeader`渲染 prop	`(column) => ReactNode`		自行绘制该列的表头；列的名称仍由 `header` 提供。