Ant Design Table 自定义空状态Empty完整指南从 emptyText 到 renderEmpty 全局定制【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design导读在 Ant Design 的实际项目中表格无数据与筛选器无选项是两类最常见的空状态场景。本指南以仓库中的 custom-empty 示例 为核心骨架系统讲解 Table 空状态的三种定制层级——组件级locale.emptyText、全局级ConfigProvider.renderEmpty、以及 5.20.0 引入的Table.filter专用空状态并结合源码InternalTable.tsx、FilterDropdown.tsx剖析其底层决策逻辑帮助你写出可复制的实战方案彻底告别默认 Empty 样式千篇一律的困扰。示例总览一个演示三种空状态能力的 Demo仓库中的 custom-empty 示例components/table/demo/custom-empty.md 对应实现 custom-empty.tsx围绕一个核心交互展开表格初始渲染 5 条模拟数据genFakeData生成。点击Toggle Data按钮后清空dataSource表格进入无数据空状态。再次点击按钮随机恢复数据同时 Age 列的筛选项filters仅在存在数据时才会挂载。这一设计让开发者可以在一个 Demo 内同时验证数据空态与筛选器空态两条渲染路径其代码结构如下import type { GetProp } from antd; import { Button, Empty, ConfigProvider, Table } from antd; import React, { useState } from react; const genFakeData (count 5) Array.from({ length: count }).map((_, index) ({ key: index, name: Edward King ${index}, age: 32 index, address: London, Park Lane no. ${index}, })); const renderEmpty: GetProptypeof ConfigProvider, renderEmpty (componentName) { if (componentName Table.filter /** 5.20.0 */) { return Empty image{Empty.PRESENTED_IMAGE_SIMPLE} descriptionNo Filter(Custom) /; } }; function App() { const [dataSource, setDataSource] useState(genFakeData); const handleToggle () { setDataSource(dataSource.length ? [] : genFakeData(Math.floor(Math.random() * 10))); }; const columns: GetProptypeof Table, columns [ { title: Name, dataIndex: name, key: name }, { title: Age, dataIndex: age, key: age, filters: dataSource.length ? [ { text: 35, value: gte35 }, { text: 18, value: lt18 }, ] : [], }, { title: Address, dataIndex: address, key: address }, ]; const toggleButton ( Button typeprimary onClick{handleToggle} Toggle Data /Button ); return ( ConfigProvider renderEmpty{renderEmpty} {dataSource.length ? toggleButton : null} div style{{ marginBlock: 8 }} / Table bordered dataSource{dataSource} columns{columns} locale{{ emptyText: Empty descriptionNo Data{toggleButton}/Empty, }} / /ConfigProvider ); } export default App;两个关键细节值得注意emptyText允许嵌套任意 ReactNode示例把Toggle Data按钮作为Empty的子节点传入让空状态不再是静态文案而是可交互的引导入口。renderEmpty中未匹配Table.filter时返回undefined这样其他组件如Select、List仍回落到 ConfigProvider 的默认空状态逻辑不会误伤全局样式。第一层定制Table 组件级locale.emptyText用法与优先级locale.emptyText是作用域最小、最直接的定制方式直接挂在Table locale{{ emptyText: ... }} /上类型定义为React.ReactNode | (() React.ReactNode)见 components/table/interface.ts既支持静态节点也支持函数式延迟渲染。其决策逻辑位于 Table 内部实现 InternalTable.tsxconst emptyText typeof locale?.emptyText ! undefined ? locale.emptyText : renderEmpty?.(Table) || DefaultRenderEmpty componentNameTable /;即优先级为locale.emptyText 全局renderEmpty(Table) 内置DefaultRenderEmpty。只要显式传入了emptyText哪怕传null全局配置就不会介入这为单表特化定制提供了确定性保障。实战可交互的空状态Demo 中最具实操价值的写法是让空状态自带操作按钮Table bordered dataSource{dataSource} columns{columns} locale{{ emptyText: Empty descriptionNo Data{toggleButton}/Empty, }} /descriptionNo Data覆盖默认的 No data 文案按钮作为Empty的children渲染在描述文字下方引导用户重新加载数据当dataSource为空时toggleButton之外的上方按钮区{dataSource.length ? toggleButton : null}已被隐藏避免出现两个重复按钮。函数式 emptyText对于需要根据运行时状态动态渲染的场景可以传入函数locale{{ emptyText: () (hasError ? 加载失败请重试 : 暂无数据), }}注意emptyText的函数返回值同样可以是任意 ReactNode适合与 loading、error 状态机结合。第二层定制ConfigProvider 全局renderEmpty工作原理ConfigProvider的renderEmpty属性类型为RenderEmptyHandler (componentName?: ComponentName) React.ReactNode见 components/config-provider/defaultRenderEmpty.tsx支持componentName取值为componentName默认渲染Table简单版 EmptyPRESENTED_IMAGE_SIMPLEList简单版 EmptySelect/TreeSelect/Cascader/Transfer/Mentions简单版 Empty ant-empty-small小尺寸类Table.filter5.20.0返回null交由组件自身逻辑处理未匹配default完整版 Empty这段分支逻辑直接体现在 defaultRenderEmpty.tsx 的switch语句中。其中Table.filter分支返回null而非undefined注释专门说明这是为了兼容 React 16 旧版节点类型约束同时满足 nullish 合并运算符??左侧取值需求把渲染权交还给 Filter 组件内部。全局覆盖示例ConfigProvider renderEmpty{(componentName) { if (componentName Table) { return Empty description暂无数据点击右上角新建 /; } if (componentName Select) { return Empty image{Empty.PRESENTED_IMAGE_SIMPLE} description无匹配选项 /; } // 其余组件保持默认 return undefined; }} App / /ConfigProvider与locale.emptyText的关系可总结为locale.emptyText是针对单表的一等优先配置renderEmpty是面向全局的统一兜底。在 InternalTable.tsx 中locale.emptyText存在时renderEmpty完全不会被调用。第三层定制筛选器空状态Table.filter5.20.0背景与动机从 5.20.0 版本起Table.filter被正式纳入renderEmpty的componentName枚举参见 defaultRenderEmpty.tsx 中的注释标记。在此之前当列定义了filters但筛选项为空数组时筛选器下拉面板会渲染无筛选的空态该能力打通后开发者可以像定制表格空态一样定制筛选器空态。底层实现筛选器下拉的空态渲染位于 components/table/hooks/useFilter/FilterDropdown.tsxconst empty renderEmpty?.(Table.filter) ?? ( Empty image{Empty.PRESENTED_IMAGE_SIMPLE} description{locale.filterEmptyText} imageStyle{{ height: 24 }} / );这里同样遵循全局优先、内置兜底的模式若renderEmpty(Table.filter)返回非空值则使用该自定义内容否则使用内置Empty文案取自locale.filterEmptyText各语言包均有定义例如 components/locale/az_AZ.ts 的Filter yoxdu、components/locale/bn_BD.ts 的ফিল্টার নেই并压缩图片高度为 24px 以适配下拉面板的小尺寸场景。Demo 中的用法const renderEmpty: GetProptypeof ConfigProvider, renderEmpty (componentName) { if (componentName Table.filter /** 5.20.0 */) { return Empty image{Empty.PRESENTED_IMAGE_SIMPLE} descriptionNo Filter(Custom) /; } };Age 列的filters数组在无数据时为空点击筛选图标后下拉面板即展示这段自定义文案No Filter(Custom)。GetProptypeof ConfigProvider, renderEmpty直接从类型层面约束了回调签名避免了手写类型与官方类型漂移。测试佐证仓库测试 Table.filter.test.tsx 对该行为有完整覆盖返回自定义内容时断言下拉容器.ant-table-filter-dropdown包含foo文本且renderEmpty收到的第一个参数确实是Table.filter允许返回false以彻底不渲染空状态renderEmpty返回false时整个空态节点被抑制适合筛选项为空时隐藏整个面板区域的场景。测试与快照验证renderEmpty的全局行为在 components/config-provider/tests/renderEmpty.test.tsx 中以参数化用例逐项验证对Table、Table.filter、List、Select、TreeSelect、Cascader、Transfer、Mentions八个组件名逐一断言快照并额外验证Table.filter返回nullcontainer.firstChild为 falsy确保空态交给组件自身未匹配的componentName回落到默认完整版 Empty。对应的快照文件 renderEmpty.test.tsx.snap 也佐证了Table使用ant-empty-normal、下拉类组件附加ant-empty-small的类名细节。如果你在项目中自行封装全局空态可以用同样的思路编写快照测试防止回归。决策速查表场景推荐方案优先级仅单个表格定制空态Table locale.emptyText最高覆盖全局全站统一空态风格ConfigProvider renderEmpty次之兜底表格筛选器无选项空态renderEmpty(Table.filter)5.20.0独立于表格空态筛选器空态文案走国际化locale.filterEmptyText内置兜底最低默认隐藏筛选器空态renderEmpty(Table.filter)返回false—小结Ant Design Table 的空状态体系是组件级 → 全局级 → 内置默认三层逐级兜底的设计locale.emptyText负责单表单次定制ConfigProvider.renderEmpty负责全站统一5.20.0 的Table.filter则将定制能力延伸到筛选器下拉。结合 custom-empty.tsx 的完整示例你可以在 5 分钟内为项目落地一套数据空态可交互、筛选空态可定制、全局风格可统一的完整方案。若需查看该组件更多边界行为可继续阅读 InternalTable.tsx 与 useFilter 目录 下的实现与测试。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考