定价

DataTable

Figma 源代码

统一管理数据的查询、排序与分页状态，可自由组合工具栏、表格和分页器，构建完整的数据浏览界面。

我们正在让 SnowUI 组件成为 AI 对话中可直接操作的界面。目前对话交互能力仍在建设中；本页展示网站用法，支持的对话平台与组件版本将在验证后公布。 AI 对话内生成和使用 SnowUI 界面完全免费，不属于项目，不占项目或开发者席位额度，无需 SnowUI 注册、激活或付费证明。

如何使用

文件或记录列表需要搜索、筛选、排序、分页、勾选或操作列时使用。DataTable 协调数据状态，内部组合 TableToolbar、Table 系列与 Pagination；纯展示用 Table。选择需显式启用 selection，并使用稳定 rowKey 与行 rowId；操作列通过 actions 配置。业务请求函数与数据格式化由页面提供。

  • client 模式在本地处理数据，server 模式由页面请求与提供结果；children 接收当前渲染状态。

  • 显式启用 selection / actions；rowKey 默认是索引，排序或更新数据时应改用稳定业务 ID，并让 TableRow.rowId 与其一致。

  • 页码从 1 开始；首次 loading、后台 refreshing 和追加 loadMore 是不同状态。

导入

import { DataTable } from '@snowui-design-system/components';

用法

分隔样式

选择

服务端分页

加载更多

API 参考

属性 类型 默认值 示例 描述
rows T[] [] rows={rows} 当前数据
mode DataTableMode "client" mode={value} 客户端切片或服务端受控模式 默认行为：client。
sorters Record<string, Sorter<T>> {} sorters={sortersOptions} 仅复杂派生列需要显式提供
searcher Searcher<T> — searcher={value} 覆盖 client 模式搜索逻辑 默认行为：浅层字符串/数字匹配。
filterer Filterer<T> — filterer={value} 覆盖 client 模式筛选逻辑 默认行为：字段等值匹配。
rowKey (row: T, index: number) => string | number (_row, index) => index rowKey={(value) => { /* handle value */ }} 稳定行身份读取器 默认行为：index。
sort TableSortState defaultSort sort={value} 当前排序列与方向；client 模式执行排序，server 模式由调用方处理。
defaultSort TableSortState — defaultSort={value} 兼容用的初始单列排序；新代码优先在 TableHead 上声明 defaultSort
query string "" query="Example" 当前搜索文本；client 模式执行搜索，server 模式由调用方处理。
filters Record<string, unknown> {} filters={filtersOptions} client 模式按字段执行等值或数组包含过滤
page number 1 page={42} 当前页码，从 1 开始；渲染状态会夹取到有效页范围。
pageSize number 10 pageSize={42} 每页行数；变化时自动回到第 1 页
totalRows number — totalRows={42} server 模式总行数
loading boolean false loading 首次加载状态，传递给表格加载与渲染状态。
refreshing boolean false refreshing 后台刷新状态，保留现有数据并通过渲染状态提供。
loadMore DataTableLoadMore<T> — loadMore={value} 增量数据源；request 包含 offset、limit 和 AbortSignal
loadMoreSize number 5 loadMoreSize={42} 每次增量加载的最大行数
loadMoreMode DataTableLoadMoreMode "manual" loadMoreMode={value} 手动调用 state.loadMore()，或由内部表尾哨兵自动触发 默认行为：manual。
loadMoreThreshold number 80 loadMoreThreshold={42} auto 模式越过表格底部后继续滚动多少 px 才触发
loadMoreThrottleMs number 500 loadMoreThrottleMs={42} auto 模式首次进入触发区后的确认等待时间，同时作为连续请求的最小间隔；首次等待期间离开触发区则取消
hasMore boolean — hasMore 显式覆盖是否仍可加载；否则优先按 totalRows 推导，再按返回数量推断 默认行为：自动推导。
error unknown — error={value} 外部错误，优先于增量加载错误进入 state.error；组件不自动生成业务错误文案。
resetPageOnQuery boolean true resetPageOnQuery 查询或筛选变化时将页码重置为 1。
onSortChange (sort: TableSortState | undefined) => void — onSortChange={(value) => { /* handle value */ }} 排序变化回调，取消排序时传入 undefined。
onQueryChange (query: string) => void — onQueryChange={(value) => { /* handle value */ }} 查询文本变化时回调。
onPageChange (page: number) => void — onPageChange={(value) => { /* handle value */ }} 页码变化时回调，参数从 1 开始。
onPageSizeChange (pageSize: number) => void — onPageSizeChange={(value) => { /* handle value */ }} 规范化后的每页行数变化时触发
onStateChange (state: DataTableRenderState<T>) => void — onStateChange={(value) => { /* handle value */ }} 当前渲染状态更新时回调，包含可见行、分页、选择及加载状态。
state DataTableRenderState<T> — state={value} 可绑定的当前渲染状态
variant DataTableVariant "divided" variant={value} 行视觉；斑马纹或分割线 默认行为：divided。
selectedRowIds Array<string | number> [] selectedRowIds={selectedRowIds} 已选行 id；选择状态由 DataTable 持有
selection boolean false selection 是否显示 checkbox 选择列；为 false 时 as="selection" 的 Head/Cell 不渲染
actions boolean | DataTableActionsConfig<T> false actions={value} 是否显示操作列；配置对象会在空 actions Cell 中默认生成 OverflowActions
horizontalScroll boolean true horizontalScroll 向 Table 下发横向滚动策略；false 时从右向左收起允许隐藏的普通列，保护列仍超宽时滚动兜底。
roleLayout TableRoleLayout "auto" roleLayout={value} 宽时角色列常驻，空间不足先转 hover 浮层；column / overlay 固定指定布局。
roleOverlayLayers number 4 roleOverlayLayers={42} overlay 渐进模糊层数
roleOverlayBlurMode TableRoleOverlayBlurMode "progressive" roleOverlayBlurMode={value} overlay 模糊算法 默认行为：progressive。
roleOverlayUniformFeather number 0.3 roleOverlayUniformFeather={42} uniform 模式内侧羽化比例
onRowPreview (row: T, state: DataTableRenderState<T>, event: MouseEvent) => void — onRowPreview={(value) => { /* handle value */ }} 配置后，TableRow 行内空白点击打开行预览；未配置时空白点击不响应
onSelectedRowIdsChange (rowIds: Array<string | number>) => void — onSelectedRowIdsChange={(value) => { /* handle value */ }} 选择变化后的完整快照
children Snippet<[DataTableRenderState<T>]> — <DataTable>Content</DataTable> 表格、工具栏和分页组合内容，接收当前渲染状态。