组件库
介绍 src/components 下的业务组件封装(列表页组合、抽屉、树选择等)与 shadcn/ui 组件层,说明选用方式。
写列表页、详情抽屉或表单时读这页,能把既有封装用满而不是重写。src/components/ 分两层:业务封装组件(本页主体)与 src/components/ui/ 下的 shadcn/ui 组件层。业务组件都要显式 import,没有全局自动注册。
列表页组合
一个标准列表页由这些件拼成(完整真实参考见本页末尾的用户管理页链接):
| 组件 | 职责 |
|---|---|
ListPageCard | 页面卡片外壳:标题、描述、筛选区、操作区、全屏 |
TableSearch / FilterSelect / DeptTreeSelect / DateRangeFilter | 筛选控件,放进 ListPageCard 的 filters 槽 |
TableToolbar | 工具栏:刷新、全屏、列重置 + 自定义按钮槽 |
DataTable | 表格本体:表头、行、加载/空/错态、分页脚 |
RowActionsMenu | 行内操作:主操作按钮 + 次操作下拉 |
StatusCell / TextCell / DataBadge(FlagBadge、TagList) | 单元格展示 |
分页、列显隐、查询状态这些重复管线由 src/hooks/use-list-table.ts 接管:传入 buildQuery(按分页构造查询键与请求)、buildColumns、getRowId,返回 query、table 实例与 resetPage / resetColumns。查询带 keepPreviousData,翻页时上一页数据保持展示(isPlaceholderData),表格以半透明过渡而不是转圈。TanStack Table v9 的特性注册表统一在 src/lib/data-table-features.ts,各列表页共用一份。
// 结构摘自 system/user/-components/user-list.tsx,实体做了改名
export function GoodsList() {
const [keyword, setKeyword] = useState('')
const { hasPermission } = usePermission()
const buildQuery = useCallback(
(pagination: PaginationState) => {
const params = { page: pagination.pageIndex + 1, size: pagination.pageSize, description: keyword || undefined }
return { queryKey: goodsKeys.list(params), queryFn: (signal: AbortSignal) => listGoods(params, signal) }
},
[keyword]
)
const buildColumns = useCallback((rowOffset: number) => createGoodsColumns(rowOffset), [])
const { query, table, resetPage } = useListTable<GoodsResp, PageResp<GoodsResp>>({
buildQuery,
buildColumns,
getRowId: row => String(row.id)
})
return (
<ListPageCard title="商品管理" filters={<TableSearch onSearch={next => { setKeyword(next); resetPage() }} />}>
<DataTable
table={table}
isLoading={query.isPending}
isError={query.isError}
isShowingPreviousRows={query.isPlaceholderData}
onRetry={() => void query.refetch()}
/>
</ListPageCard>
)
}树形列表(部门、菜单)走同一套件:DataTable 传 stickyHeader、showPagination={false},行展开由 rowExpandingFeature 承担。
抽屉与详情
EntityDrawer 是右侧抽屉外壳:声明宽度(30 到 48rem)、标题、图标、徽标与描述,表单和详情把内容放 children 里,页脚归各页面自管(保存按钮要随表单状态禁用时,由页面控制关闭行为 canClose)。表单抽屉配 TanStack Form + zod 校验。
详情抽屉用 DetailGrid / DetailField(标签/值两栏描述列表)拼装,值单元格复用展示组件(StatusCell、CopyableText、TagList);数据未就绪时 DetailGate 控制骨架屏与兜底。删除类确认统一走 DeleteConfirmDialog:传入 action(删除请求)与 invalidateKeys(成功后失效的查询键),组件负责 pending 阻断关闭、成功提示与缓存失效,文案和图标由页面给定。
树选择与选择器
| 组件 | 场景 |
|---|---|
DeptTreeSelect | 部门树选择(数据源 deptKeys.tree,支持「全部」选项) |
ParentTreeSelect | 通用父级树选择(菜单、分类等自引用表) |
CheckableTree | 可勾选树(角色分配菜单、租户分配菜单) |
UserPicker | 用户选择(公告指定用户等场景) |
FilterSelect | 筛选栏下拉,带「全部」语义与前置标签 |
树组件的通用工具(子树收集、级联勾选、索引换算)在 src/lib/tree-check.ts、collect-subtree-ids.ts、tree-index.ts,被单元测试覆盖(continew-ui/tests/)。
其余业务组件
按需取用:RichTextEditor(Tiptap 封装,公告正文)、DateRangePicker / DateRangeFilter、ExpiryPicker(过期时间选择)、PasswordInput、JsonViewer、CopyButton / CopyableText、RequiredMark、SimpleIcon(菜单图标)、QueryState(加载/错误/空态占位)、ListFilterRow、TableFillArea(全屏布局)、PaginationArrow。一次性组件放页面自己的 -components/ 目录,通用性足够才提升到 src/components/。
shadcn/ui 组件层
src/components/ui/ 下有 60 余个组件,源码经 shadcn CLI 拷贝进仓库(不是运行时依赖),风格配置在仓库根的 components.json:style 为 base-nova(原语基于 Base UI),图标库 lucide,路径别名 @/。多数组件可以直接用;少数组件(message-scroller、questionnaire)依赖 @shadcn/react 运行时包。
新增一个 shadcn 组件:
pnpm dlx shadcn@latest add dialogCLI 按 components.json 的别名与 CSS 路径写入对应位置,之后照常 import { Dialog } from '@/components/ui/dialog'。组件主题来自 Tailwind CSS 变量(见布局与主题),改主题色不需要动组件源码;确需定制时直接改拷贝进来的文件即可。
选用建议
新列表页从 ListPageCard + useListTable + DataTable 起步,只写列定义、筛选控件和工具栏按钮;表单放 EntityDrawer,删除确认不要手写弹窗。展示组件(状态、标签、复制文本)在单元格和详情里保持一致,别在页面里临时拼样式。
相关源码
- src/components/:业务组件全目录
- src/components/ui/:shadcn/ui 组件层
- components.json:shadcn CLI 配置
- src/hooks/use-list-table.ts:列表页管线 hook
- src/routes/(main)/(app)/system/user/-components/user-list.tsx:列表页组合的完整参考实现