Carbon React 自定义 DataTable 状态管理器基于 Vite 示例的启动、运行与源码拆解【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本文以 Carbon 仓库中 custom-data-table-state-manager-vite 示例为对象讲解如何从零启动并运行一个完全自定义状态管理的 Carbon React 数据表格包括仓库构建流程、Vite 开发服务器启动方式以及该示例背后如何用一组自定义 Hooks 接管筛选、排序、分页与行选择状态。读完本文你将掌握在 IBM Carbon React 中绕过内置DataTable状态机、自建数据表状态管理器的完整落地路径。示例是什么为什么需要自定义状态管理器在carbon/react中数据表由两层组成DataTable组件负责管理表格状态排序、筛选、分页、选择而Table、TableRow、TableCell、TableHeader等一系列组件只负责渲染 Carbon 设计语言的表格 UI。这一分层意味着当内置DataTable的状态管理无法满足业务场景时——例如需要懒加载当前页之外的表格行数据、与服务端状态源同步、或实现完全自定义的交互——应用完全可以放弃DataTable仅使用 Carbon 的展示型表格组件配合自己的状态管理器。这正是本示例存在的意义其源码注释也明确写到THIS COMPONENT IS FOR DEMONSTRATION PURPOSES ONLYCustomDataTable.jsx。示例目录的核心文件结构如下src/components/CustomDataTable.jsx自定义状态管理表格的主体组件替代内置DataTablesrc/components/Pagination.jsx对 CarbonPagination的包装将页码语义转换为起始行索引src/hooks/useFilteredRows、useSortInfo、useSortedRows、usePageInfo、useRowSelection、useCollator、useUniqueId七个状态管理 Hookssrc/misc/enums.js表格尺寸、排序方向、排序周期等枚举常量src/misc/doesRowMatchSearchString.js行与搜索串的匹配工具src/table-data.js演示用的列定义、基础行数据与 50 行扩充数据src/ExampleCustomDataTableApp.jsx组装所有演示数据的入口应用组件。启动与运行从仓库构建到浏览器预览第一步在 carbon 仓库根目录完成构建示例依赖仓库内构建产物carbon/react等包因此 README 要求先在 carbon 仓库根目录执行一次安装与构建yarn install yarn build该命令会安装仓库依赖并通过 Lerna/Nx 等工具构建各子包包括packages/react下的carbon/react确保后续示例引用的是本地最新构建的组件代码。第二步安装示例自身的依赖构建完成后进入示例目录安装其独立依赖cd packages/react/examples/custom-data-table-state-manager-vite yarn install # 或 npm install从示例的 package.json 可以看到其技术栈运行时依赖carbon/react、react/react-dom^18.2.0、prop-types、use-debounce用于搜索防抖、carbon-icons开发依赖vite^7.x、vitejs/plugin-react、sass、eslint及 React 相关插件。其中use-debounce是搜索功能防抖的关键依赖直接服务于useFilteredRowsHook。第三步启动开发服务器yarn dev # 或 npm run devdev脚本对应 package.json 中的dev: vite即直接调用 Vite 开发服务器。Vite 配置非常精简vite.config.js 仅注册了 React 插件import { defineConfig } from vite import react from vitejs/plugin-react export default defineConfig({ plugins: [react()], })第四步浏览器预览用浏览器打开 http://localhost:5173/ 即可看到示例效果。入口由 index.html 指向/src/main.jsx后者通过ReactDOM.createRoot(document.getElementById(root))挂载App /main.jsxApp再渲染ExampleCustomDataTableApp最终以pageSize{5}、start{0}、hasSelection{true}的配置实例化CustomDataTableExampleCustomDataTableApp.jsx。此外package.json还提供了npm run previewVite 构建产物预览与npm run buildvite build生产构建、npm run lintESLint 检查--max-warnings 0零容忍警告等脚本方便验证生产包与代码质量。核心 APICustomDataTable 的 props 契约CustomDataTable是示例对外暴露的唯一组件其 props 全部带 PropTypes 校验CustomDataTable.jsxprop类型默认值说明columnsArray{id, title, sortCycle}—列定义sortCycle指定该列的排序周期rowsArray{id, selected, ...}—表格数据行id为数字唯一键sortInfo{columnId, direction}—初始排序信息方向取NONE/ASC/DESChasSelectionbooleanfalse是否渲染行选择多选UIpageSizenumber5每页行数startnumber0当前页起始行索引从 0 开始sizestringlg表格尺寸见TABLE_SIZEcollatorIntl.Collatornew Intl.Collator()用于排序的国际化排序器zebraboolean—是否显示斑马纹idstring—用于生成选择框唯一 id 前缀其中sortInfo.direction、size的可选值均来自 enums.jsTABLE_SIZESHORT: short、REGULAR: lg、TALL: tallTABLE_SORT_DIRECTIONNONE、ASCENDING: ASC、DESCENDING: DESCTABLE_SORT_CYCLEbi-states-from-ascending、bi-states-from-descending、tri-states-from-ascending、tri-states-from-descending分别表示从升序开始的双态/三态与从降序开始的双态/三态四种循环模式映射关系集中在TABLE_SORT_CYCLESenums.js。状态管理拆解七个 Hooks 如何各司其职CustomDataTable的巧妙之处在于把所有表格状态拆解为可复用的 Hooks在组件内按固定顺序组合CustomDataTable.jsxconst [rows, setRows] useState(propRows); // 原始行数据含选中态 const [sortInfo, setSortInfo] useSortInfo(propSortInfo); // 排序状态 const [filteredRows, searchString, setSearchString] useFilteredRows(rows); // 搜索筛选 const [setRowSelection] useRowSelection( filteredRows, searchString, setRows); // 行选择 const [sortedRows] useSortedRows(filteredRows, sortInfo, collator); // 排序 const [start, pageSize, setStart, setPageSize] usePageInfo( propStart, propPageSize, filteredRows.length); // 分页useFilteredRows防抖搜索筛选useFilteredRows.js 借助use-debounce的useDebounce(searchString, 500)实现500ms 防抖用户在工具栏搜索框输入时不会立即触发昂贵的过滤计算而是在停止输入 500ms 后基于debouncedSearchString用useMemo重新计算filteredRows。行匹配规则由doesRowMatchSearchString定义doesRowMatchSearchString.js遍历行的每个字段排除id只要任一字段的字符串包含搜索串即视为命中const doesRowMatchSearchString (row, searchString) Object.keys(row).some( (key) key ! id String(row[key] ?? ).indexOf(searchString) 0 );useSortInfo排序状态机与周期切换useSortInfo.js 维护当前排序列与方向。核心是getNextSort()根据列的sortCycle从TABLE_SORT_CYCLES取方向数组oldDirection找到当前下标后(index 1) % length推进到下一状态。例如tri-states-from-ascending的循环是NONE → ASC → DESC → NONE而bi-states-from-ascending是ASC ↔ DESC。一个值得注意的细节当非主排序列columnId ! name进入NONE状态时会重置回initialSortInfo避免表格完全失去排序基准。useSortedRows结合 Intl.Collator 的稳定排序useSortedRows.js 通过useCollator封装Intl.Collator默认new Intl.Collator()对多语言文本排序更友好。排序方向映射为系数ASC → 1、DESC → -1方向为NONE时直接返回原数组排序时先用slice()复制再sort()避免原地修改 React state。usePageInfo起始行索引与越界修正usePageInfo.js 用start从 0 开始的起始行索引pageSize替代当前页码。组件渲染时通过sortedRows.slice(start, start pageSize)截取当前页。它还处理了一个边界场景当筛选/删除导致行数骤减、start越过数据末尾时会自动把start回退到合法的最后一页起点下限为 0。useRowSelection单选、全选与选中过滤后所有行useRowSelection.js 接受rowId与selected两个参数rowId为具体行 id 时只更新该行rowId为undefined时表示全选/全不选此时若存在搜索串只会把匹配搜索串的行doesRowMatchSearchString命中全部置为选中/取消实现了对当前过滤结果批量选择。useUniqueId选择框唯一 iduseUniqueId为表格生成稳定且唯一的 id 前缀配合useCollator国际化排序器共同服务于组件内部对选择框name/id的组装。渲染层如何拼装 Carbon 表格 UICustomDataTable的渲染完全使用carbon/react的展示型组件CustomDataTable.jsx结构如下TableContainer包裹容器提供标题titleDataTable与描述descriptionFully customizedTableToolbar工具栏内部含TableBatchActions批量操作区shouldShowBatchActions控制显隐totalSelected展示已选数量内含一个Delete批量删除按钮与TableToolbarContentTableToolbarSearch搜索框 TableToolbarMenu下拉菜单含三个alert演示动作。工具项在批量操作显示时通过tabIndex{-1}移出 Tab 焦点保证键盘可达性Table size{size} isSortable可排序表格主体。表头TableHeader通过data-column-id、data-sort-cycle、data-sort-direction三个 data 属性暴露排序所需信息点击时触发handleChangeSort调用setSortInfoisSortHeader与sortDirection驱动 Carbon 自带的排序箭头 UITableBody zebra{zebra}对sortedRows.slice(start, start pageSize)逐行渲染TableRow与TableCell每行用data-row-id标记行 id配合handleChangeSelection从event.currentTarget.closest(tr)反查行 id 完成单选hasSelection为真时额外渲染TableSelectAll/TableSelectRowPagination分页条。与内置DataTable相比示例的包装组件Pagination.jsx将 Carbon 的page从 1 开始换算为零基startpage Math.floor(start / pageSize) 1翻页时通过Math.min(Math.max(...), count)把新起始索引钳制在合法范围内再分别回调onChangePageSize与onChangeStart。值得注意的是示例在表头交互中大量使用data 属性 事件委托的方式而非向每个表头传入闭包这让表头组件保持纯展示性状态更新统一收敛到CustomDataTable的回调里是整个自定义状态管理器的关键设计。演示数据与可运行验证示例数据定义在 table-data.jscolumns包含name双态排序、protocol、port三态排序、rule、attachedGroups、status六列rows为 3 条负载均衡器示例数据其中一条默认selected: truerowsMany通过 50 次映射把 3 条模板行扩成 50 行并将name格式化为Load Balancer 001风格sortInfo初始化为按name升序。ExampleCustomDataTableApp最终以 50 行数据、每页 5 行、支持选择、默认按名称排序的配置渲染你可以直接在浏览器中验证搜索防抖、三态排序、批量删除、翻页与每页行数切换等全部交互。如果你需要将本示例移植到自己的应用只需保留src/hooks/、src/misc/与两个组件文件替换table-data.js中的业务数据与列定义即可获得一套与 Carbon 视觉规范完全一致、但状态完全自控的数据表方案——这正是该示例被定位为应用级状态管理器起点的原因。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Carbon React 自定义 DataTable 状态管理器：基于 Vite 示例的启动、运行与源码拆解
Carbon React 自定义 DataTable 状态管理器基于 Vite 示例的启动、运行与源码拆解【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本文以 Carbon 仓库中 custom-data-table-state-manager-vite 示例为对象讲解如何从零启动并运行一个完全自定义状态管理的 Carbon React 数据表格包括仓库构建流程、Vite 开发服务器启动方式以及该示例背后如何用一组自定义 Hooks 接管筛选、排序、分页与行选择状态。读完本文你将掌握在 IBM Carbon React 中绕过内置DataTable状态机、自建数据表状态管理器的完整落地路径。示例是什么为什么需要自定义状态管理器在carbon/react中数据表由两层组成DataTable组件负责管理表格状态排序、筛选、分页、选择而Table、TableRow、TableCell、TableHeader等一系列组件只负责渲染 Carbon 设计语言的表格 UI。这一分层意味着当内置DataTable的状态管理无法满足业务场景时——例如需要懒加载当前页之外的表格行数据、与服务端状态源同步、或实现完全自定义的交互——应用完全可以放弃DataTable仅使用 Carbon 的展示型表格组件配合自己的状态管理器。这正是本示例存在的意义其源码注释也明确写到THIS COMPONENT IS FOR DEMONSTRATION PURPOSES ONLYCustomDataTable.jsx。示例目录的核心文件结构如下src/components/CustomDataTable.jsx自定义状态管理表格的主体组件替代内置DataTablesrc/components/Pagination.jsx对 CarbonPagination的包装将页码语义转换为起始行索引src/hooks/useFilteredRows、useSortInfo、useSortedRows、usePageInfo、useRowSelection、useCollator、useUniqueId七个状态管理 Hookssrc/misc/enums.js表格尺寸、排序方向、排序周期等枚举常量src/misc/doesRowMatchSearchString.js行与搜索串的匹配工具src/table-data.js演示用的列定义、基础行数据与 50 行扩充数据src/ExampleCustomDataTableApp.jsx组装所有演示数据的入口应用组件。启动与运行从仓库构建到浏览器预览第一步在 carbon 仓库根目录完成构建示例依赖仓库内构建产物carbon/react等包因此 README 要求先在 carbon 仓库根目录执行一次安装与构建yarn install yarn build该命令会安装仓库依赖并通过 Lerna/Nx 等工具构建各子包包括packages/react下的carbon/react确保后续示例引用的是本地最新构建的组件代码。第二步安装示例自身的依赖构建完成后进入示例目录安装其独立依赖cd packages/react/examples/custom-data-table-state-manager-vite yarn install # 或 npm install从示例的 package.json 可以看到其技术栈运行时依赖carbon/react、react/react-dom^18.2.0、prop-types、use-debounce用于搜索防抖、carbon-icons开发依赖vite^7.x、vitejs/plugin-react、sass、eslint及 React 相关插件。其中use-debounce是搜索功能防抖的关键依赖直接服务于useFilteredRowsHook。第三步启动开发服务器yarn dev # 或 npm run devdev脚本对应 package.json 中的dev: vite即直接调用 Vite 开发服务器。Vite 配置非常精简vite.config.js 仅注册了 React 插件import { defineConfig } from vite import react from vitejs/plugin-react export default defineConfig({ plugins: [react()], })第四步浏览器预览用浏览器打开 http://localhost:5173/ 即可看到示例效果。入口由 index.html 指向/src/main.jsx后者通过ReactDOM.createRoot(document.getElementById(root))挂载App /main.jsxApp再渲染ExampleCustomDataTableApp最终以pageSize{5}、start{0}、hasSelection{true}的配置实例化CustomDataTableExampleCustomDataTableApp.jsx。此外package.json还提供了npm run previewVite 构建产物预览与npm run buildvite build生产构建、npm run lintESLint 检查--max-warnings 0零容忍警告等脚本方便验证生产包与代码质量。核心 APICustomDataTable 的 props 契约CustomDataTable是示例对外暴露的唯一组件其 props 全部带 PropTypes 校验CustomDataTable.jsxprop类型默认值说明columnsArray{id, title, sortCycle}—列定义sortCycle指定该列的排序周期rowsArray{id, selected, ...}—表格数据行id为数字唯一键sortInfo{columnId, direction}—初始排序信息方向取NONE/ASC/DESChasSelectionbooleanfalse是否渲染行选择多选UIpageSizenumber5每页行数startnumber0当前页起始行索引从 0 开始sizestringlg表格尺寸见TABLE_SIZEcollatorIntl.Collatornew Intl.Collator()用于排序的国际化排序器zebraboolean—是否显示斑马纹idstring—用于生成选择框唯一 id 前缀其中sortInfo.direction、size的可选值均来自 enums.jsTABLE_SIZESHORT: short、REGULAR: lg、TALL: tallTABLE_SORT_DIRECTIONNONE、ASCENDING: ASC、DESCENDING: DESCTABLE_SORT_CYCLEbi-states-from-ascending、bi-states-from-descending、tri-states-from-ascending、tri-states-from-descending分别表示从升序开始的双态/三态与从降序开始的双态/三态四种循环模式映射关系集中在TABLE_SORT_CYCLESenums.js。状态管理拆解七个 Hooks 如何各司其职CustomDataTable的巧妙之处在于把所有表格状态拆解为可复用的 Hooks在组件内按固定顺序组合CustomDataTable.jsxconst [rows, setRows] useState(propRows); // 原始行数据含选中态 const [sortInfo, setSortInfo] useSortInfo(propSortInfo); // 排序状态 const [filteredRows, searchString, setSearchString] useFilteredRows(rows); // 搜索筛选 const [setRowSelection] useRowSelection( filteredRows, searchString, setRows); // 行选择 const [sortedRows] useSortedRows(filteredRows, sortInfo, collator); // 排序 const [start, pageSize, setStart, setPageSize] usePageInfo( propStart, propPageSize, filteredRows.length); // 分页useFilteredRows防抖搜索筛选useFilteredRows.js 借助use-debounce的useDebounce(searchString, 500)实现500ms 防抖用户在工具栏搜索框输入时不会立即触发昂贵的过滤计算而是在停止输入 500ms 后基于debouncedSearchString用useMemo重新计算filteredRows。行匹配规则由doesRowMatchSearchString定义doesRowMatchSearchString.js遍历行的每个字段排除id只要任一字段的字符串包含搜索串即视为命中const doesRowMatchSearchString (row, searchString) Object.keys(row).some( (key) key ! id String(row[key] ?? ).indexOf(searchString) 0 );useSortInfo排序状态机与周期切换useSortInfo.js 维护当前排序列与方向。核心是getNextSort()根据列的sortCycle从TABLE_SORT_CYCLES取方向数组oldDirection找到当前下标后(index 1) % length推进到下一状态。例如tri-states-from-ascending的循环是NONE → ASC → DESC → NONE而bi-states-from-ascending是ASC ↔ DESC。一个值得注意的细节当非主排序列columnId ! name进入NONE状态时会重置回initialSortInfo避免表格完全失去排序基准。useSortedRows结合 Intl.Collator 的稳定排序useSortedRows.js 通过useCollator封装Intl.Collator默认new Intl.Collator()对多语言文本排序更友好。排序方向映射为系数ASC → 1、DESC → -1方向为NONE时直接返回原数组排序时先用slice()复制再sort()避免原地修改 React state。usePageInfo起始行索引与越界修正usePageInfo.js 用start从 0 开始的起始行索引pageSize替代当前页码。组件渲染时通过sortedRows.slice(start, start pageSize)截取当前页。它还处理了一个边界场景当筛选/删除导致行数骤减、start越过数据末尾时会自动把start回退到合法的最后一页起点下限为 0。useRowSelection单选、全选与选中过滤后所有行useRowSelection.js 接受rowId与selected两个参数rowId为具体行 id 时只更新该行rowId为undefined时表示全选/全不选此时若存在搜索串只会把匹配搜索串的行doesRowMatchSearchString命中全部置为选中/取消实现了对当前过滤结果批量选择。useUniqueId选择框唯一 iduseUniqueId为表格生成稳定且唯一的 id 前缀配合useCollator国际化排序器共同服务于组件内部对选择框name/id的组装。渲染层如何拼装 Carbon 表格 UICustomDataTable的渲染完全使用carbon/react的展示型组件CustomDataTable.jsx结构如下TableContainer包裹容器提供标题titleDataTable与描述descriptionFully customizedTableToolbar工具栏内部含TableBatchActions批量操作区shouldShowBatchActions控制显隐totalSelected展示已选数量内含一个Delete批量删除按钮与TableToolbarContentTableToolbarSearch搜索框 TableToolbarMenu下拉菜单含三个alert演示动作。工具项在批量操作显示时通过tabIndex{-1}移出 Tab 焦点保证键盘可达性Table size{size} isSortable可排序表格主体。表头TableHeader通过data-column-id、data-sort-cycle、data-sort-direction三个 data 属性暴露排序所需信息点击时触发handleChangeSort调用setSortInfoisSortHeader与sortDirection驱动 Carbon 自带的排序箭头 UITableBody zebra{zebra}对sortedRows.slice(start, start pageSize)逐行渲染TableRow与TableCell每行用data-row-id标记行 id配合handleChangeSelection从event.currentTarget.closest(tr)反查行 id 完成单选hasSelection为真时额外渲染TableSelectAll/TableSelectRowPagination分页条。与内置DataTable相比示例的包装组件Pagination.jsx将 Carbon 的page从 1 开始换算为零基startpage Math.floor(start / pageSize) 1翻页时通过Math.min(Math.max(...), count)把新起始索引钳制在合法范围内再分别回调onChangePageSize与onChangeStart。值得注意的是示例在表头交互中大量使用data 属性 事件委托的方式而非向每个表头传入闭包这让表头组件保持纯展示性状态更新统一收敛到CustomDataTable的回调里是整个自定义状态管理器的关键设计。演示数据与可运行验证示例数据定义在 table-data.jscolumns包含name双态排序、protocol、port三态排序、rule、attachedGroups、status六列rows为 3 条负载均衡器示例数据其中一条默认selected: truerowsMany通过 50 次映射把 3 条模板行扩成 50 行并将name格式化为Load Balancer 001风格sortInfo初始化为按name升序。ExampleCustomDataTableApp最终以 50 行数据、每页 5 行、支持选择、默认按名称排序的配置渲染你可以直接在浏览器中验证搜索防抖、三态排序、批量删除、翻页与每页行数切换等全部交互。如果你需要将本示例移植到自己的应用只需保留src/hooks/、src/misc/与两个组件文件替换table-data.js中的业务数据与列定义即可获得一套与 Carbon 视觉规范完全一致、但状态完全自控的数据表方案——这正是该示例被定位为应用级状态管理器起点的原因。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考