new-api 前端数据表格组件体系解析core / layout / toolbar / static / hooks 五层架构与实战指南【免费下载链接】new-apiA unified AI model hub for aggregation distribution. It supports cross-converting various LLMs into OpenAI-compatible, Claude-compatible, or Gemini-compatible formats. A centralized gateway for personal and enterprise model management.项目地址: https://gitcode.com/gh_mirrors/ne/new-api导读new-api 的 Web 控制台web/src中沉淀了一套统一的数据表格组件体系用于支撑「渠道Channels、令牌API Keys、用户Users、模型Models、订阅Subscriptions等管理页面的列表展示。该体系以 web/src/components/data-table/README.md 为设计与维护契约围绕 TanStack Table 构建将「渲染原语、页面布局、工具栏、静态渲染、状态 Hooks」拆分为五个职责清晰的模块并通过index.ts对外暴露稳定公共 API。本文将以这份 README 为主体骨架结合仓库源码逐层拆解组件结构、关键 Props、状态持久化与真实业务用法帮助读者快速掌握这套表格组件的使用方式、扩展边界与源码级实现原理。一、包结构与设计哲学一个表格五种职责data-table是一个完整的前端子包位于 web/src/components/data-table其 README 明确规定了包的内部组织方式子目录职责core/TanStack Table 渲染原语表头、行、分页、加载、空状态以及固定列pinned-column行为layout/响应式页面级组合把工具栏、桌面表格、移动端列表、批量操作和分页位置统一编排toolbar/过滤 / 搜索 / 视图选项控件以及选中态操作工具栏static/面向本地静态数组的轻量表格渲染不依赖 TanStack 状态hooks/表格状态与过滤相关的 Hooks该 README 同时规定了组件的归属边界功能相关的列、操作、对话框放在各自 feature 目录内例如 web/src/features/channels/components 中的渠道表格只有被多个 feature 复用的通用表格代码才应放进本包。这一约定保证了共享代码与业务代码解耦data-table只沉淀通用能力业务页面通过组合这些原语表达自己的特有交互。二、index.ts稳定公共 API 契约README 强调「本包通过index.ts维持稳定的公共 API功能代码应从/components/data-table导入」。这意味着内部文件路径不是 API任何引用都应走包入口。查看 web/src/components/data-table/index.ts公共导出可归纳为五类渲染原语DataTableView、DataTableRow、DataTablePagination、DataTableColumnHeader、BadgeCell、BadgeListCell、TruncatedCell、DataTableRowActionMenu页面级布局DataTablePage、MobileCardList、DataTableCardGrid、CardRowContent、tableHasCompactMeta工具栏控件DataTableToolbar、DataTableMobileFilterPanel、DataTableViewOptions、DataTableBulkActions、DataTableViewModeToggle静态表格StaticDataTable、StaticRowActions、staticDataTableClassNamesHooksuseDataTable、useDataTableViewMode、useDebouncedColumnFilter。入口还导出了两个可直接复用的禁用态样式常量DISABLED_ROW_DESKTOP与DISABLED_ROW_MOBILEindex.ts分别对应桌面行与移动卡片的禁用视觉业务方无需自己重写 CSS。三、core/TanStack 渲染原语与固定列机制core/是整个体系的地基核心是DataTableView与配套类型。3.1 DataTableView统一表格视图DataTableViewTData接收一个 TanStackTable实例完成表头、表体、骨架屏、空态与固定列的渲染。其核心逻辑见 core/data-table-view.tsx支持splitHeader分裂表头模式把表头从滚动区域中分离sticky top-0 z-10固定正文独立滚动用于固定高度页面列数colSpan由table.getVisibleLeafColumns().length动态计算保证空态单元格正确跨列通过colgroupgetTableSizeStyle支持列宽与等宽表头对齐applyHeaderSize开启时生效。DataTableViewPropsTData的完整定义见 core/types.ts关键字段包括字段作用table/rowsTanStack 表格实例或直接注入已计算好的行支持受控行集isLoading加载态渲染TableSkeleton骨架屏可配skeletonKeyPrefix/skeletonRowHeightemptyTitle/emptyDescription/emptyIcon/emptyAction空态文案与操作emptyContent可完全自定义空态节点renderRow自定义行渲染配合getCellClassNamehelpers 实现展开行、汇总行、整行点击跳转等getRowClassName/getColumnClassName行 / 列 className 解析器pinnedColumns固定列配置见 3.2applyHeaderSize是否把header.getSize()应用到表头宽度默认关闭TanStack 默认给所有列 150px 宽度避免无 size 定义的布局被意外约束splitHeader/bodyContainerClassName等分裂表头与滚动容器样式3.2 固定列Pinned Column的源码实现固定列在DataTableView中被集中管理而非散落在各业务页。核心逻辑在 core/column-pinning.ts左侧固定列使用sticky left-0shadow-[8px_0_10px_-10px_hsl(var(--foreground))]右侧固定列使用sticky right-0 反向阴影形成悬浮层次感表头固定列提升到z-30单元格为z-10并处理了 hover / selected 状态下的背景过渡useResolvedColumnClassName会把显式pinnedColumns与列定义columnDef.meta.pinned声明的固定列合并去重data-table-view.tsx两种声明方式可混用。DataTablePinnedColumn类型types.ts支持按列指定className、headerClassName、cellClassName粒度可到表头与单元格。3.3 分页、徽章与截断单元格DataTablePaginationcore/pagination.tsx完整分页条内置页码序列通过getPageNumbers生成带省略号的分页、「每页行数」下拉可选10 / 20 / 30 / 40 / 50 / 100、首页 / 末页跳转compact模式只保留「上一页 / 下一页 总数」的极简形态BadgeCell/BadgeListCell状态徽章与徽章列表单元格适合「状态」「标签」类列TruncatedCell超长文本截断配合 tooltip 悬浮展示完整内容static表格同样复用了该组件。四、hooks/表格状态管理与持久化hooks/负责把 TanStack Table 的「状态」包装成更易用的 API核心是useDataTable。4.1 useDataTable一行代码创建表格实例useDataTableTData(options)hooks/use-data-table.ts把数据、列定义与全部状态选项收拢为{ table }。其设计要点可控 / 非可控双模式sorting、columnVisibility、columnSizing、rowSelection、expanded、pagination均可通过xxx onXxxChange受控传入或仅传initialXxx交给内部useState管理useControllableTableState实现见 use-data-table.ts手动 / 自动行模型可切换通过manualFiltering/manualPagination/manualSorting三开关控制并自动推导客户端行模型——例如withFilteredRowModel !manualFiltering即默认开启本地过滤withSortedRowModel在手动排序或手动分页时自动关闭use-data-table.ts服务端分页支持totalCount与pageCount二选一传入配合manualPagination后由useDataTable计算resolvedPageCount并通过ensurePageInRange回调在页码越界时自动修正列宽 / 列可见性持久化传入columnVisibilityStorageKey/columnSizingStorageKey后自动读写localStorage。列宽写入做了 250ms 防抖COLUMN_SIZING_PERSIST_DELAY_MS见 use-data-table.ts避免拖动列宽时频繁写盘读取时会对存储值做类型校验readColumnVisibility/readColumnSizing并依据列定义中的minSize/maxSize对持久化列宽做边界钳制getBoundedColumnSize见 use-data-table.ts。隐私模式下localStorage不可用时会被 try/catch 静默降级表格功能不受影响列宽边界自动推导buildColumnSizingBounds会递归遍历列定义含columns分组列收集每列的minSize/maxSizeuse-data-table.ts列 ID 归一化getColumnId对嵌套 accessor如user.name会替换为下划线形式user_name保证列 ID 稳定可用use-data-table.ts。4.2 useDataTableViewMode 与 useDebouncedColumnFilteruseDataTableViewModehooks/use-data-table-view-mode.ts管理「表格 / 卡片」两种视图模式DATA_TABLE_VIEW_MODES.TABLE/.CARD支持storageKey按表格维度持久化到localStorage切换 storageKey例如从 A 表切到 B 表时会自动重新水合re-hydrate已保存的视图模式useDebouncedColumnFilter面向列的防抖过滤 Hook与工具栏的防抖搜索配合使用实现「输入即过滤、性能不抖动」。五、layout/响应式页面组合层layout/解决「一个列表页长什么样」的问题旗舰组件是DataTablePage。5.1 DataTablePage标准列表页的规范结构layout/data-table-page.tsx 的 JSDoc 给出了它的设计意图统一所有列表页的规范结构——工具栏 → 桌面表格 / 移动端列表 → 分页外加加载 / 空态与可选的批量操作栏。其组合流程isMobile useMediaQuery((max-width: 640px)) ↓ showMobile isMobile !hideMobile ↓ renderToolbar → renderMobile → renderDesktop → renderPagination核心 Props 一览完整定义见>const { table } useDataTable({ data: channels, columns, totalCount, sorting, initialColumnVisibility: { models: false, tag: false }, columnVisibilityStorageKey: CHANNELS_COLUMN_VISIBILITY_STORAGE_KEY, columnSizingStorageKey: isMobile ? false : CHANNELS_COLUMN_SIZING_STORAGE_KEY, columnFilters, pagination, globalFilter, enableRowSelection: batchMode ? (row) !isTagAggregateRow(row.original) : false, onSortingChange: handleSortingChange, onColumnFiltersChange: handleColumnFiltersChange, onPaginationChange, onGlobalFilterChange, getRowId: getChannelTableRowId, getSubRows: (row) row.children, manualPagination: true, manualSorting: true, manualFiltering: true, withExpandedRowModel: true, enableColumnResizing: !isMobile, ensurePageInRange, })该案例印证了多个机制服务端分页 / 排序 / 过滤全部走手动模式manualXxx: true并配合totalCount与回调上抛列可见性与列宽按桌面端持久化移动端显式false关闭节省空间行模型自由组合withExpandedRowModel: true支持渠道按标签聚合的分组展开行。页面层则通过DataTablePage组合channels-table.tsxDataTablePage table{table} columns{columns} isLoading{isLoading} isFetching{isFetching} emptyTitle{t(No Channels Found)} emptyDescription{t(No channels available. Create your first channel to get started.)} skeletonKeyPrefixchannel-skeleton enableCardView viewModeStorageKey{CHANNELS_VIEW_MODE_STORAGE_KEY} renderCard{(row, { isSelected }) ChannelCard row{row} isSelected{isSelected} /} cardGridClassNamegrid grid-cols-1 gap-3 sm:gap-4 lg:grid-cols-3 applyHeaderSize toolbarProps{{ collapsibleOnMobile: true, searchPlaceholder: t(Filter by name, ID, or key...), searchDebounceMs: 500, onReset: () resetModelFilterInput(), additionalSearch: ( Input placeholder{t(Filter by model...)} value{modelFilterInput} onChange{onModelFilterInputChange} onCompositionStart{onModelFilterCompositionStart} onCompositionEnd{onModelFilterCompositionEnd} classNamew-full sm:w-[150px] lg:w-[180px] / ), filters: [ { columnId: status, title: t(Status), options: [...CHANNEL_STATUS_OPTIONS], singleSelect: true }, { columnId: type, title: t(Type), options: typeFilterOptions, singleSelect: true }, ], }} /可以看到卡片视图enableCardViewrenderCardviewModeStorageKey、防抖搜索searchDebounceMs: 500、自定义附加搜索框模型过滤、状态 / 类型过滤芯片被一次性组合起来。类似的用法还分布在 api-keys-table.tsx、users-table.tsx、models-table.tsx、usage-logs-table.tsx 等十余个 feature 页面中DataTablePage也因此成为 new-api 控制台列表页的规范骨架。九、边界与最佳实践基于 README 的约定与源码实现使用这套组件时建议遵循以下边界只从index.ts导入内部文件路径属于实现细节稳定的公共 API 以 web/src/components/data-table/index.ts 为准避免跨子目录深路径引用造成升级断裂业务代码不进共享包列定义、行操作菜单、对话框等 feature 专属内容放在各自 feature 目录如features/channels/components/只有跨页面复用的逻辑才下沉到data-table按数据源选择渲染层需要交互状态排序 / 过滤 / 分页 / 选中走useDataTableDataTablePage纯静态展示走StaticDataTable零状态开销服务端与客户端模式不要混用服务端分页必须同时置manualPagination、manualSorting、manualFiltering并提供totalCount客户端过滤则保持默认行模型自动推导善用持久化但注意容量columnVisibilityStorageKey/columnSizingStorageKey/viewModeStorageKey让列布局与视图偏好「记住用户选择」移动端可通过传false关闭列宽持久化以节省空间固定列声明二选一优先在列定义的columnDef.meta.pinned中声明或统一通过pinnedColumns传入二者会被去重合并避免重复声明。结语new-api 的data-table组件包是一套「约定优于配置」的表格基础设施core/提供渲染原语与固定列机制hooks/封装可控状态与持久化layout/统一响应式页面骨架toolbar/沉淀搜索过滤交互static/覆盖轻量静态场景最终由index.ts收敛为稳定的公共 API。理解这五层结构开发者既可以像渠道列表页一样通过少量 Props 快速产出标准列表页也可以借助renderRow、toolbar、mobile等插槽为复杂场景定制专属交互而无需触碰底层表格实现。【免费下载链接】new-apiA unified AI model hub for aggregation distribution. It supports cross-converting various LLMs into OpenAI-compatible, Claude-compatible, or Gemini-compatible formats. A centralized gateway for personal and enterprise model management.项目地址: https://gitcode.com/gh_mirrors/ne/new-api创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 new-api 前端数据表格组件体系解析：core / layout / toolbar / static / hooks 五层架构与实战指南
new-api 前端数据表格组件体系解析core / layout / toolbar / static / hooks 五层架构与实战指南【免费下载链接】new-apiA unified AI model hub for aggregation distribution. It supports cross-converting various LLMs into OpenAI-compatible, Claude-compatible, or Gemini-compatible formats. A centralized gateway for personal and enterprise model management.项目地址: https://gitcode.com/gh_mirrors/ne/new-api导读new-api 的 Web 控制台web/src中沉淀了一套统一的数据表格组件体系用于支撑「渠道Channels、令牌API Keys、用户Users、模型Models、订阅Subscriptions等管理页面的列表展示。该体系以 web/src/components/data-table/README.md 为设计与维护契约围绕 TanStack Table 构建将「渲染原语、页面布局、工具栏、静态渲染、状态 Hooks」拆分为五个职责清晰的模块并通过index.ts对外暴露稳定公共 API。本文将以这份 README 为主体骨架结合仓库源码逐层拆解组件结构、关键 Props、状态持久化与真实业务用法帮助读者快速掌握这套表格组件的使用方式、扩展边界与源码级实现原理。一、包结构与设计哲学一个表格五种职责data-table是一个完整的前端子包位于 web/src/components/data-table其 README 明确规定了包的内部组织方式子目录职责core/TanStack Table 渲染原语表头、行、分页、加载、空状态以及固定列pinned-column行为layout/响应式页面级组合把工具栏、桌面表格、移动端列表、批量操作和分页位置统一编排toolbar/过滤 / 搜索 / 视图选项控件以及选中态操作工具栏static/面向本地静态数组的轻量表格渲染不依赖 TanStack 状态hooks/表格状态与过滤相关的 Hooks该 README 同时规定了组件的归属边界功能相关的列、操作、对话框放在各自 feature 目录内例如 web/src/features/channels/components 中的渠道表格只有被多个 feature 复用的通用表格代码才应放进本包。这一约定保证了共享代码与业务代码解耦data-table只沉淀通用能力业务页面通过组合这些原语表达自己的特有交互。二、index.ts稳定公共 API 契约README 强调「本包通过index.ts维持稳定的公共 API功能代码应从/components/data-table导入」。这意味着内部文件路径不是 API任何引用都应走包入口。查看 web/src/components/data-table/index.ts公共导出可归纳为五类渲染原语DataTableView、DataTableRow、DataTablePagination、DataTableColumnHeader、BadgeCell、BadgeListCell、TruncatedCell、DataTableRowActionMenu页面级布局DataTablePage、MobileCardList、DataTableCardGrid、CardRowContent、tableHasCompactMeta工具栏控件DataTableToolbar、DataTableMobileFilterPanel、DataTableViewOptions、DataTableBulkActions、DataTableViewModeToggle静态表格StaticDataTable、StaticRowActions、staticDataTableClassNamesHooksuseDataTable、useDataTableViewMode、useDebouncedColumnFilter。入口还导出了两个可直接复用的禁用态样式常量DISABLED_ROW_DESKTOP与DISABLED_ROW_MOBILEindex.ts分别对应桌面行与移动卡片的禁用视觉业务方无需自己重写 CSS。三、core/TanStack 渲染原语与固定列机制core/是整个体系的地基核心是DataTableView与配套类型。3.1 DataTableView统一表格视图DataTableViewTData接收一个 TanStackTable实例完成表头、表体、骨架屏、空态与固定列的渲染。其核心逻辑见 core/data-table-view.tsx支持splitHeader分裂表头模式把表头从滚动区域中分离sticky top-0 z-10固定正文独立滚动用于固定高度页面列数colSpan由table.getVisibleLeafColumns().length动态计算保证空态单元格正确跨列通过colgroupgetTableSizeStyle支持列宽与等宽表头对齐applyHeaderSize开启时生效。DataTableViewPropsTData的完整定义见 core/types.ts关键字段包括字段作用table/rowsTanStack 表格实例或直接注入已计算好的行支持受控行集isLoading加载态渲染TableSkeleton骨架屏可配skeletonKeyPrefix/skeletonRowHeightemptyTitle/emptyDescription/emptyIcon/emptyAction空态文案与操作emptyContent可完全自定义空态节点renderRow自定义行渲染配合getCellClassNamehelpers 实现展开行、汇总行、整行点击跳转等getRowClassName/getColumnClassName行 / 列 className 解析器pinnedColumns固定列配置见 3.2applyHeaderSize是否把header.getSize()应用到表头宽度默认关闭TanStack 默认给所有列 150px 宽度避免无 size 定义的布局被意外约束splitHeader/bodyContainerClassName等分裂表头与滚动容器样式3.2 固定列Pinned Column的源码实现固定列在DataTableView中被集中管理而非散落在各业务页。核心逻辑在 core/column-pinning.ts左侧固定列使用sticky left-0shadow-[8px_0_10px_-10px_hsl(var(--foreground))]右侧固定列使用sticky right-0 反向阴影形成悬浮层次感表头固定列提升到z-30单元格为z-10并处理了 hover / selected 状态下的背景过渡useResolvedColumnClassName会把显式pinnedColumns与列定义columnDef.meta.pinned声明的固定列合并去重data-table-view.tsx两种声明方式可混用。DataTablePinnedColumn类型types.ts支持按列指定className、headerClassName、cellClassName粒度可到表头与单元格。3.3 分页、徽章与截断单元格DataTablePaginationcore/pagination.tsx完整分页条内置页码序列通过getPageNumbers生成带省略号的分页、「每页行数」下拉可选10 / 20 / 30 / 40 / 50 / 100、首页 / 末页跳转compact模式只保留「上一页 / 下一页 总数」的极简形态BadgeCell/BadgeListCell状态徽章与徽章列表单元格适合「状态」「标签」类列TruncatedCell超长文本截断配合 tooltip 悬浮展示完整内容static表格同样复用了该组件。四、hooks/表格状态管理与持久化hooks/负责把 TanStack Table 的「状态」包装成更易用的 API核心是useDataTable。4.1 useDataTable一行代码创建表格实例useDataTableTData(options)hooks/use-data-table.ts把数据、列定义与全部状态选项收拢为{ table }。其设计要点可控 / 非可控双模式sorting、columnVisibility、columnSizing、rowSelection、expanded、pagination均可通过xxx onXxxChange受控传入或仅传initialXxx交给内部useState管理useControllableTableState实现见 use-data-table.ts手动 / 自动行模型可切换通过manualFiltering/manualPagination/manualSorting三开关控制并自动推导客户端行模型——例如withFilteredRowModel !manualFiltering即默认开启本地过滤withSortedRowModel在手动排序或手动分页时自动关闭use-data-table.ts服务端分页支持totalCount与pageCount二选一传入配合manualPagination后由useDataTable计算resolvedPageCount并通过ensurePageInRange回调在页码越界时自动修正列宽 / 列可见性持久化传入columnVisibilityStorageKey/columnSizingStorageKey后自动读写localStorage。列宽写入做了 250ms 防抖COLUMN_SIZING_PERSIST_DELAY_MS见 use-data-table.ts避免拖动列宽时频繁写盘读取时会对存储值做类型校验readColumnVisibility/readColumnSizing并依据列定义中的minSize/maxSize对持久化列宽做边界钳制getBoundedColumnSize见 use-data-table.ts。隐私模式下localStorage不可用时会被 try/catch 静默降级表格功能不受影响列宽边界自动推导buildColumnSizingBounds会递归遍历列定义含columns分组列收集每列的minSize/maxSizeuse-data-table.ts列 ID 归一化getColumnId对嵌套 accessor如user.name会替换为下划线形式user_name保证列 ID 稳定可用use-data-table.ts。4.2 useDataTableViewMode 与 useDebouncedColumnFilteruseDataTableViewModehooks/use-data-table-view-mode.ts管理「表格 / 卡片」两种视图模式DATA_TABLE_VIEW_MODES.TABLE/.CARD支持storageKey按表格维度持久化到localStorage切换 storageKey例如从 A 表切到 B 表时会自动重新水合re-hydrate已保存的视图模式useDebouncedColumnFilter面向列的防抖过滤 Hook与工具栏的防抖搜索配合使用实现「输入即过滤、性能不抖动」。五、layout/响应式页面组合层layout/解决「一个列表页长什么样」的问题旗舰组件是DataTablePage。5.1 DataTablePage标准列表页的规范结构layout/data-table-page.tsx 的 JSDoc 给出了它的设计意图统一所有列表页的规范结构——工具栏 → 桌面表格 / 移动端列表 → 分页外加加载 / 空态与可选的批量操作栏。其组合流程isMobile useMediaQuery((max-width: 640px)) ↓ showMobile isMobile !hideMobile ↓ renderToolbar → renderMobile → renderDesktop → renderPagination核心 Props 一览完整定义见>const { table } useDataTable({ data: channels, columns, totalCount, sorting, initialColumnVisibility: { models: false, tag: false }, columnVisibilityStorageKey: CHANNELS_COLUMN_VISIBILITY_STORAGE_KEY, columnSizingStorageKey: isMobile ? false : CHANNELS_COLUMN_SIZING_STORAGE_KEY, columnFilters, pagination, globalFilter, enableRowSelection: batchMode ? (row) !isTagAggregateRow(row.original) : false, onSortingChange: handleSortingChange, onColumnFiltersChange: handleColumnFiltersChange, onPaginationChange, onGlobalFilterChange, getRowId: getChannelTableRowId, getSubRows: (row) row.children, manualPagination: true, manualSorting: true, manualFiltering: true, withExpandedRowModel: true, enableColumnResizing: !isMobile, ensurePageInRange, })该案例印证了多个机制服务端分页 / 排序 / 过滤全部走手动模式manualXxx: true并配合totalCount与回调上抛列可见性与列宽按桌面端持久化移动端显式false关闭节省空间行模型自由组合withExpandedRowModel: true支持渠道按标签聚合的分组展开行。页面层则通过DataTablePage组合channels-table.tsxDataTablePage table{table} columns{columns} isLoading{isLoading} isFetching{isFetching} emptyTitle{t(No Channels Found)} emptyDescription{t(No channels available. Create your first channel to get started.)} skeletonKeyPrefixchannel-skeleton enableCardView viewModeStorageKey{CHANNELS_VIEW_MODE_STORAGE_KEY} renderCard{(row, { isSelected }) ChannelCard row{row} isSelected{isSelected} /} cardGridClassNamegrid grid-cols-1 gap-3 sm:gap-4 lg:grid-cols-3 applyHeaderSize toolbarProps{{ collapsibleOnMobile: true, searchPlaceholder: t(Filter by name, ID, or key...), searchDebounceMs: 500, onReset: () resetModelFilterInput(), additionalSearch: ( Input placeholder{t(Filter by model...)} value{modelFilterInput} onChange{onModelFilterInputChange} onCompositionStart{onModelFilterCompositionStart} onCompositionEnd{onModelFilterCompositionEnd} classNamew-full sm:w-[150px] lg:w-[180px] / ), filters: [ { columnId: status, title: t(Status), options: [...CHANNEL_STATUS_OPTIONS], singleSelect: true }, { columnId: type, title: t(Type), options: typeFilterOptions, singleSelect: true }, ], }} /可以看到卡片视图enableCardViewrenderCardviewModeStorageKey、防抖搜索searchDebounceMs: 500、自定义附加搜索框模型过滤、状态 / 类型过滤芯片被一次性组合起来。类似的用法还分布在 api-keys-table.tsx、users-table.tsx、models-table.tsx、usage-logs-table.tsx 等十余个 feature 页面中DataTablePage也因此成为 new-api 控制台列表页的规范骨架。九、边界与最佳实践基于 README 的约定与源码实现使用这套组件时建议遵循以下边界只从index.ts导入内部文件路径属于实现细节稳定的公共 API 以 web/src/components/data-table/index.ts 为准避免跨子目录深路径引用造成升级断裂业务代码不进共享包列定义、行操作菜单、对话框等 feature 专属内容放在各自 feature 目录如features/channels/components/只有跨页面复用的逻辑才下沉到data-table按数据源选择渲染层需要交互状态排序 / 过滤 / 分页 / 选中走useDataTableDataTablePage纯静态展示走StaticDataTable零状态开销服务端与客户端模式不要混用服务端分页必须同时置manualPagination、manualSorting、manualFiltering并提供totalCount客户端过滤则保持默认行模型自动推导善用持久化但注意容量columnVisibilityStorageKey/columnSizingStorageKey/viewModeStorageKey让列布局与视图偏好「记住用户选择」移动端可通过传false关闭列宽持久化以节省空间固定列声明二选一优先在列定义的columnDef.meta.pinned中声明或统一通过pinnedColumns传入二者会被去重合并避免重复声明。结语new-api 的data-table组件包是一套「约定优于配置」的表格基础设施core/提供渲染原语与固定列机制hooks/封装可控状态与持久化layout/统一响应式页面骨架toolbar/沉淀搜索过滤交互static/覆盖轻量静态场景最终由index.ts收敛为稳定的公共 API。理解这五层结构开发者既可以像渠道列表页一样通过少量 Props 快速产出标准列表页也可以借助renderRow、toolbar、mobile等插槽为复杂场景定制专属交互而无需触碰底层表格实现。【免费下载链接】new-apiA unified AI model hub for aggregation distribution. It supports cross-converting various LLMs into OpenAI-compatible, Claude-compatible, or Gemini-compatible formats. A centralized gateway for personal and enterprise model management.项目地址: https://gitcode.com/gh_mirrors/ne/new-api创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考