ContiNew
前端开发

组件库

介绍 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 dialog

CLI 按 components.json 的别名与 CSS 路径写入对应位置,之后照常 import { Dialog } from '@/components/ui/dialog'。组件主题来自 Tailwind CSS 变量(见布局与主题),改主题色不需要动组件源码;确需定制时直接改拷贝进来的文件即可。

选用建议

新列表页从 ListPageCard + useListTable + DataTable 起步,只写列定义、筛选控件和工具栏按钮;表单放 EntityDrawer,删除确认不要手写弹窗。展示组件(状态、标签、复制文本)在单元格和详情里保持一致,别在页面里临时拼样式。

相关源码

目录