UI
本页目录

组件 · 数据展示

DataList 数据列表

将筛选、列表数据、标题操作与分页组合在一起；筛选表单和列表内容由使用方渲染。

入口 @selrux/ui/data-list · 源码 src/components/data-list/index.ts · 5 个组件 · 发布状态 preview

使用建议

  • 避免：把 DataList 当成内置表格或 CRUD 页面
  • 避免：假设 DataList.Filters 自动生成表单、按钮或折叠标题
  • 避免：接口不分页且数据规模未知时直接全量加载
  • 限制：source=all 的页面分页只限制挂载数量，不能减少接口响应体积；规模未知时须使用服务端有界查询或增量接口
  • 限制：页面不分页且数据量大时，内容渲染器须采用虚拟化或其他有界渲染策略
  • 限制：筛选表单自管字段时，调用 reset() 后仍需重置表单自身的值

引入

tsx
import {
  DataList,
  DataListContent,
  DataListFilters,
  DataListHeader,
  DataListPagination,
  useDataListContext,
  // …共 7 个导出
} from '@selrux/ui/data-list';

数据来源与展示模式

查询行为由 @selrux/headless/data-list 的 useDataListQuery 提供，UI 入口同步转发。先选接口形态 source，再选页面展示 view。request 接收筛选、页码、每页数量、游标和 AbortSignal；selectResult 从业务响应提取 items、total、hasMore 或 nextCursor。

  • source=all + view=page：接口一次返回全部记录；本地先筛选、排序，再切片。切页不重新请求。
  • source=all + view=continuous：页面不分页。大量记录须在 Content 中使用 Table.VirtualBody 或等价虚拟列表；DataList 不替业务选择行高与布局。
  • source=page + view=page：服务端负责筛选与分页；返回 total 时使用页码，没有 total 时需返回 hasMore。
  • source=page + view=continuous：逐页加载并追加，适合列表或卡片；数据持续增长时须考虑窗口化，或限制可累计的记录数。
  • source=cursor：后续位置由 nextCursor 给出。页码界面只支持上一页、下一页，不展示不可达的页号。

DataList.Filters 不生成标题、表单、按钮或折叠交互。使用函数子节点取得 search(values)、reset 和 loading，自行组合 Form、Card 或 Collapsible；也可放自定义组件，通过 useDataListContext 读取列表操作。search() 提交当前 draftFilters，search(values) 直接提交表单值；reset() 恢复列表的 initialFilters，自管表单还需同步重置自己的字段。刷新会重取当前数据。

mapItem 是可选展示转换。复杂列表可传 renderContent 回调，或在 DataList.Content 中放独立组件并通过 useDataListContext 读取数据与操作。

演练场

调节下方可实现的字面量属性，实时预览真实组件。函数、Portal、样式逃生口等见代码演示与 API 表。

DataList.Filters 只传递搜索与重置操作；筛选表单、按钮和折叠由示例自行组合。更多接口模式及大数据方案见下方示例。

无可调节的字面量属性；下方为组合用法预览。

高级筛选

成员列表

正在加载

代码演示

完整响应与页面分页

筛选和页码变化都在本地完成，列表接口只请求一次。

高级筛选

成员列表

正在加载

服务端分页与标题栏内联筛选

每次切页请求对应页，工具栏可刷新。

远端成员

正在加载

游标分页

仅提供可到达的上一页与下一页，不虚构总页数。

游标接口

正在加载

连续加载卡片

远端分页逐批追加，列表区域的渲染逻辑由页面决定。

卡片列表

正在加载

不分页的大数据

完整响应交给虚拟表体，只挂载视口附近的行。

完整响应 · 0 条

正在加载

列表项转换

mapItem 只转换当前可见页，再交给自定义渲染。

转换后的列表项

正在加载

空态与错误重试

切换模拟响应，展示 DataList.Content 的统一反馈。

结果状态

正在加载

API

属性覆盖：示例用到 6 / 6 个自有属性（100%）

由 scripts/demo-coverage.mjs 统计，不含 className / style / 原生透传属性与纯转发事件。

DataList

DataList 组合入口；四个区域可按页面需要选用。

静态成员：DataList.Filters DataList.Header DataList.Content DataList.Pagination

属性说明类型默认值
controller *-DataListController<TItem, TFilters>-
renderContent-((controller: DataListController<TItem, TFilters>) => ReactNode)-

另有 280 项原生属性与事件继承自 HTMLAttributes，原样透传。

DataListContent

列表区域统一反馈加载、失败和空态；内容由业务自定义渲染。

属性说明类型默认值
emptyText-string-

另有 280 项原生属性与事件继承自 HTMLAttributes，原样透传。

DataListFilters

DataList 筛选组合入口。

属性说明类型默认值
children *自定义内容，或接收筛选操作的渲染函数。ReactNode | ((actions: DataListFilterActions<TFilters>) => ReactNode)-

另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。

DataListHeader

标题栏为左侧标题或自定义内容、右侧业务工具提供稳定布局。

属性说明类型默认值
title-ReactNode-
actions-ReactNode-

另有 279 项原生属性与事件继承自 HTMLAttributes，原样透传。

DataListPagination

页码模式复用现有 Pagination；无总数或游标模式只开放可达的前后页。

属性说明类型默认值
hideOnSinglePage-boolean-

另有 280 项原生属性与事件继承自 HTMLAttributes，原样透传。

导出类型：DataListContentProps、DataListController、DataListFilterActions、DataListFiltersProps、DataListHeaderProps、DataListPaginationProps、DataListProps、DataListRequest、DataListResult、DataListSourceMode、DataListViewMode、UseDataListQueryOptions

函数与常量

名称说明签名 / 类型
useDataListContext在自定义工具栏、筛选项或列表组件中读取当前 DataList。<TItem = unknown, TFilters = unknown>() => DataListController<TItem, TFilters>
useDataListQuery管理列表查询、竞态和页面展示状态；应用通过 request 接入自己的 service。 完整响应的页面分页只切片已加载数据，不会再次请求接口。<TRow, TFilters, TResponse, TItem = TRow>(options: UseDataListQueryOptions<TRow, TFilters, TResponse, TItem>) => DataListController<TItem, TFilters>