Ant Design Empty 组件完全指南空状态占位符的定制、内置图片与全局配置【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design空状态Empty State是数据密集型界面的必备要素。在 Ant Designantd中Empty组件用于在没有数据或全新场景下给出友好提示本文以官方文档 components/empty/index.en-US.md 为骨架结合仓库源码深入讲解其 API、内置图片、自定义方式、全局 ConfigProvider 接入与 Design Token 样式体系帮助你在项目中正确使用并深度定制空状态展示。何时使用When To Use官方文档明确了两种典型场景无数据时的友好提示当列表、表格、下拉框等组件没有可展示的数据时用空状态占位符代替空白区域避免用户感到困惑。全新场景下的引导在新用户刚进入、还没有任何内容的场景中用空状态配合操作按钮引导用户去创建第一条数据。从源码看Empty并非只能单独使用。在 components/config-provider/defaultRenderEmpty.tsx 中Table、List、Select、TreeSelect、Cascader、Transfer、Mentions等组件在无数据时都会默认渲染Empty因此掌握该组件也就掌握了上述组件的空状态统一开关。基础用法最简单的用法是不传任何 props直接渲染import React from react; import { Empty } from antd; const App: React.FC () Empty /; export default App;上面的代码等价于显式传入默认图片与默认描述Empty ButtonCreate/Button /Empty从 components/empty/index.tsx 的实现可以看出description未显式传入时会回退到useLocale(Empty)读取的本地化文案即 locale 文件中Empty.description字段如 No data因此语言环境切换后描述会自动跟随。只显示图片、隐藏描述当图片已足够表达语义、无需文字时可将description设为false来关闭描述区域import React from react; import { Empty } from antd; const App: React.FC () Empty description{false} /; export default App;对应源码中{des div className{${prefixCls}-description}{des}/div}的判断逻辑description为false时描述节点不会被渲染。API 详解官方文档提供的EmptyAPI 如下PropertyDescriptionTypeDefaultVersiondescriptionCustomize descriptionReactNode-imageCustomize image. Will treat as image url when string providedReactNodeEmpty.PRESENTED_IMAGE_DEFAULTimageStyleThe style of imageCSSProperties-另有通用属性可参考 Common props如className、style、prefixCls、rootClassName等均可用于Empty。逐项说明与源码印证description自定义描述内容类型为ReactNode。源码 components/empty/index.tsx 中的逻辑为typeof description ! undefined ? description : locale?.description——未传时使用 locale 默认文案传false则完全隐藏。描述还会被用作字符串图片的alt文本typeof des string ? des : empty提升可访问性。image自定义图片。当传入字符串时会被当作图片 URL 渲染为img源码typeof image string分支当传入 ReactNode 时原样渲染。默认值为Empty.PRESENTED_IMAGE_DEFAULT。imageStyle图片区域的样式自 3.16.0 起支持作用于.ant-empty-image容器。结合image一起使用时可通过设置高度、宽度来缩放自定义图片。内置图片PRESENTED_IMAGE_DEFAULT 与 PRESENTED_IMAGE_SIMPLEEmpty是一个复合组件CompoundedComponent挂载了两个静态属性对应两套内置 SVG 图片Empty.PRESENTED_IMAGE_SIMPLE极简风格小图官方展示尺寸约 55×35适合空间紧凑的场景如表格、列表行内的空状态。Empty.PRESENTED_IMAGE_DEFAULT默认大图官方展示尺寸约 121×116适合整页或大面积区域的空状态。两套图片分别定义在 components/empty/empty.tsx默认图与 components/empty/simple.tsx简图均以内联 SVG 实现无需额外网络请求。使用简化图import React from react; import { Empty } from antd; const App: React.FC () Empty image{Empty.PRESENTED_IMAGE_SIMPLE} /; export default App;使用简化图时源码会自动加上${prefixCls}-normal类名image simpleEmptyImg判断渲染为常规normal尺寸样式。内置图片的智能配色值得注意的实现细节两套内置 SVG 都不是写死的颜色。默认图在 empty.tsx 中读取token.colorBgBase通过TinyColor计算亮度深色背景下会自动降低透明度opacity: 0.65以适配暗色主题简图在 simple.tsx 中基于colorFill、colorFillTertiary、colorFillQuaternary、colorBgContainer等主题 Token 计算边框色、阴影色与内容色因此能随主题变量自动变化。自定义空状态CustomizeEmpty支持完全自定义自定义图片、描述和操作区footer。import React from react; import { Button, Empty, Typography } from antd; const App: React.FC () ( Empty imagehttps://gw.alipayobjects.com/zos/antfincdn/ZHrcdLPrvN/empty.svg imageStyle{{ height: 60 }} description{ Typography.Text Customize a href#APIDescription/a /Typography.Text } Button typeprimaryCreate Now/Button /Empty ); export default App;本例同时演示了三个要点字符串图片 尺寸控制image传入 URL 字符串配合imageStyle{{ height: 60 }}控制图片高度样式作用于.ant-empty-image容器容器内的img默认height: 100%。富文本描述description传入任意 ReactNode不再局限于纯文本。子节点作为操作区Empty的子节点会被渲染到.ant-empty-footer中用于放置创建新建等引导按钮——这正是官方文档建议的新场景引导用法。源码对应关系见 components/empty/index.tsxdiv className{${prefixCls}-image} style{imageStyle}{imageNode}/div {des div className{${prefixCls}-description}{des}/div} {children div className{${prefixCls}-footer}{children}/div}通过 ConfigProvider 全局定制空状态很多组件Select、Table、List、Cascader、Transfer、TreeSelect、Mentions 等在无数据时默认渲染Empty。借助ConfigProvider的renderEmpty属性可以为整棵组件树统一替换空状态渲染import React, { useState } from react; import { SmileOutlined } from ant-design/icons; import { Cascader, ConfigProvider, Divider, List, Select, Space, Switch, Table, Transfer, TreeSelect } from antd; const customizeRenderEmpty () ( div style{{ textAlign: center }} SmileOutlined style{{ fontSize: 20 }} / pData Not Found/p /div ); const App: React.FC () { const [customize, setCustomize] useState(true); return ( Switch unCheckedChildrendefault checkedChildrencustomize checked{customize} onChange{setCustomize} / Divider / ConfigProvider renderEmpty{customize ? customizeRenderEmpty : undefined} Space directionvertical style{{ width: 100% }} h4Select/h4 Select style{{ width: 200 }} / h4TreeSelect/h4 TreeSelect style{{ width: 200 }} treeData{[]} / h4Cascader/h4 Cascader style{{ width: 200 }} options{[]} showSearch / h4Transfer/h4 Transfer / h4Table/h4 Table columns{[{ title: Name, dataIndex: name, key: name }, { title: Age, dataIndex: age, key: age }]} / h4List/h4 List / /Space /ConfigProvider / ); }; export default App;renderEmpty的实现位于 components/config-provider/defaultRenderEmpty.tsx其内部逻辑展示了不同组件使用不同空状态规格的约定Table、List使用Empty.PRESENTED_IMAGE_SIMPLE简化图Select、TreeSelect、Cascader、Transfer、Mentions使用简化图并追加ant-empty-small类${prefix}-small进一步缩小图片尺寸适配下拉面板等紧凑场景Table.filter返回null由表格组件自身处理筛选空态。也就是说各组件默认已经对空状态做了尺寸分级的取舍你可以在renderEmpty中按组件名componentName做更精细的差异化定制。Design Token 与样式定制Empty的样式基于 CSS-in-JS 与 Design Token 体系生成样式入口为 components/empty/style/index.ts。组件级 TokenEmpty的ComponentToken默认为空接口无专用 Token样式主要复用全局 alias TokencolorTextDescription描述文字颜色、opacityImage图片透明度、margin/marginXS/marginXL间距等。图片高度派生通过mergeToken基于controlHeightLG计算三档图片高度默认图高度controlHeightLG * 2.5normal 图高度简化图controlHeightLGsmall 图高度下拉面板内controlHeightLG * 0.875。由此调整全局基础 Token如controlHeightLG会同步影响空状态图片的整体视觉比例也可以通过 Theme 配置覆盖opacityImage、colorTextDescription等变量实现整体风格定制。无障碍与 RTL图片语义字符串图片的alt会取description文案字符串时否则回退为empty内置 SVG 也带有title如 empty image、Simple Empty便于屏幕阅读器理解。RTL 支持当ConfigProvider的direction为rtl时Empty根节点自动添加${prefixCls}-rtl类配合整体 RTL 布局正常工作见 components/empty/index.tsx。使用建议优先使用内置图片默认图与简化图已适配明暗主题无需额外资源需要更小尺寸时优先PRESENTED_IMAGE_SIMPLE。字符串 vs ReactNode 图片临时替换可用 URL 字符串并配合imageStyle控制大小需要主题联动或复杂矢量图时传自定义 ReactNode/SVG 组件。全局统一优先于逐个定制涉及多组件的空状态统一替换使用ConfigProvider renderEmpty避免重复代码。用 footer 引导操作空状态不仅是告知更应配合children中的按钮给出下一步行动入口提升转化。相关示例代码与测试均可在 components/empty/demobasic、simple、customize、config-provider、description 五个官方示例与 components/empty/tests中进一步查看验证。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ant Design Empty 组件完全指南：空状态占位符的定制、内置图片与全局配置
Ant Design Empty 组件完全指南空状态占位符的定制、内置图片与全局配置【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design空状态Empty State是数据密集型界面的必备要素。在 Ant Designantd中Empty组件用于在没有数据或全新场景下给出友好提示本文以官方文档 components/empty/index.en-US.md 为骨架结合仓库源码深入讲解其 API、内置图片、自定义方式、全局 ConfigProvider 接入与 Design Token 样式体系帮助你在项目中正确使用并深度定制空状态展示。何时使用When To Use官方文档明确了两种典型场景无数据时的友好提示当列表、表格、下拉框等组件没有可展示的数据时用空状态占位符代替空白区域避免用户感到困惑。全新场景下的引导在新用户刚进入、还没有任何内容的场景中用空状态配合操作按钮引导用户去创建第一条数据。从源码看Empty并非只能单独使用。在 components/config-provider/defaultRenderEmpty.tsx 中Table、List、Select、TreeSelect、Cascader、Transfer、Mentions等组件在无数据时都会默认渲染Empty因此掌握该组件也就掌握了上述组件的空状态统一开关。基础用法最简单的用法是不传任何 props直接渲染import React from react; import { Empty } from antd; const App: React.FC () Empty /; export default App;上面的代码等价于显式传入默认图片与默认描述Empty ButtonCreate/Button /Empty从 components/empty/index.tsx 的实现可以看出description未显式传入时会回退到useLocale(Empty)读取的本地化文案即 locale 文件中Empty.description字段如 No data因此语言环境切换后描述会自动跟随。只显示图片、隐藏描述当图片已足够表达语义、无需文字时可将description设为false来关闭描述区域import React from react; import { Empty } from antd; const App: React.FC () Empty description{false} /; export default App;对应源码中{des div className{${prefixCls}-description}{des}/div}的判断逻辑description为false时描述节点不会被渲染。API 详解官方文档提供的EmptyAPI 如下PropertyDescriptionTypeDefaultVersiondescriptionCustomize descriptionReactNode-imageCustomize image. Will treat as image url when string providedReactNodeEmpty.PRESENTED_IMAGE_DEFAULTimageStyleThe style of imageCSSProperties-另有通用属性可参考 Common props如className、style、prefixCls、rootClassName等均可用于Empty。逐项说明与源码印证description自定义描述内容类型为ReactNode。源码 components/empty/index.tsx 中的逻辑为typeof description ! undefined ? description : locale?.description——未传时使用 locale 默认文案传false则完全隐藏。描述还会被用作字符串图片的alt文本typeof des string ? des : empty提升可访问性。image自定义图片。当传入字符串时会被当作图片 URL 渲染为img源码typeof image string分支当传入 ReactNode 时原样渲染。默认值为Empty.PRESENTED_IMAGE_DEFAULT。imageStyle图片区域的样式自 3.16.0 起支持作用于.ant-empty-image容器。结合image一起使用时可通过设置高度、宽度来缩放自定义图片。内置图片PRESENTED_IMAGE_DEFAULT 与 PRESENTED_IMAGE_SIMPLEEmpty是一个复合组件CompoundedComponent挂载了两个静态属性对应两套内置 SVG 图片Empty.PRESENTED_IMAGE_SIMPLE极简风格小图官方展示尺寸约 55×35适合空间紧凑的场景如表格、列表行内的空状态。Empty.PRESENTED_IMAGE_DEFAULT默认大图官方展示尺寸约 121×116适合整页或大面积区域的空状态。两套图片分别定义在 components/empty/empty.tsx默认图与 components/empty/simple.tsx简图均以内联 SVG 实现无需额外网络请求。使用简化图import React from react; import { Empty } from antd; const App: React.FC () Empty image{Empty.PRESENTED_IMAGE_SIMPLE} /; export default App;使用简化图时源码会自动加上${prefixCls}-normal类名image simpleEmptyImg判断渲染为常规normal尺寸样式。内置图片的智能配色值得注意的实现细节两套内置 SVG 都不是写死的颜色。默认图在 empty.tsx 中读取token.colorBgBase通过TinyColor计算亮度深色背景下会自动降低透明度opacity: 0.65以适配暗色主题简图在 simple.tsx 中基于colorFill、colorFillTertiary、colorFillQuaternary、colorBgContainer等主题 Token 计算边框色、阴影色与内容色因此能随主题变量自动变化。自定义空状态CustomizeEmpty支持完全自定义自定义图片、描述和操作区footer。import React from react; import { Button, Empty, Typography } from antd; const App: React.FC () ( Empty imagehttps://gw.alipayobjects.com/zos/antfincdn/ZHrcdLPrvN/empty.svg imageStyle{{ height: 60 }} description{ Typography.Text Customize a href#APIDescription/a /Typography.Text } Button typeprimaryCreate Now/Button /Empty ); export default App;本例同时演示了三个要点字符串图片 尺寸控制image传入 URL 字符串配合imageStyle{{ height: 60 }}控制图片高度样式作用于.ant-empty-image容器容器内的img默认height: 100%。富文本描述description传入任意 ReactNode不再局限于纯文本。子节点作为操作区Empty的子节点会被渲染到.ant-empty-footer中用于放置创建新建等引导按钮——这正是官方文档建议的新场景引导用法。源码对应关系见 components/empty/index.tsxdiv className{${prefixCls}-image} style{imageStyle}{imageNode}/div {des div className{${prefixCls}-description}{des}/div} {children div className{${prefixCls}-footer}{children}/div}通过 ConfigProvider 全局定制空状态很多组件Select、Table、List、Cascader、Transfer、TreeSelect、Mentions 等在无数据时默认渲染Empty。借助ConfigProvider的renderEmpty属性可以为整棵组件树统一替换空状态渲染import React, { useState } from react; import { SmileOutlined } from ant-design/icons; import { Cascader, ConfigProvider, Divider, List, Select, Space, Switch, Table, Transfer, TreeSelect } from antd; const customizeRenderEmpty () ( div style{{ textAlign: center }} SmileOutlined style{{ fontSize: 20 }} / pData Not Found/p /div ); const App: React.FC () { const [customize, setCustomize] useState(true); return ( Switch unCheckedChildrendefault checkedChildrencustomize checked{customize} onChange{setCustomize} / Divider / ConfigProvider renderEmpty{customize ? customizeRenderEmpty : undefined} Space directionvertical style{{ width: 100% }} h4Select/h4 Select style{{ width: 200 }} / h4TreeSelect/h4 TreeSelect style{{ width: 200 }} treeData{[]} / h4Cascader/h4 Cascader style{{ width: 200 }} options{[]} showSearch / h4Transfer/h4 Transfer / h4Table/h4 Table columns{[{ title: Name, dataIndex: name, key: name }, { title: Age, dataIndex: age, key: age }]} / h4List/h4 List / /Space /ConfigProvider / ); }; export default App;renderEmpty的实现位于 components/config-provider/defaultRenderEmpty.tsx其内部逻辑展示了不同组件使用不同空状态规格的约定Table、List使用Empty.PRESENTED_IMAGE_SIMPLE简化图Select、TreeSelect、Cascader、Transfer、Mentions使用简化图并追加ant-empty-small类${prefix}-small进一步缩小图片尺寸适配下拉面板等紧凑场景Table.filter返回null由表格组件自身处理筛选空态。也就是说各组件默认已经对空状态做了尺寸分级的取舍你可以在renderEmpty中按组件名componentName做更精细的差异化定制。Design Token 与样式定制Empty的样式基于 CSS-in-JS 与 Design Token 体系生成样式入口为 components/empty/style/index.ts。组件级 TokenEmpty的ComponentToken默认为空接口无专用 Token样式主要复用全局 alias TokencolorTextDescription描述文字颜色、opacityImage图片透明度、margin/marginXS/marginXL间距等。图片高度派生通过mergeToken基于controlHeightLG计算三档图片高度默认图高度controlHeightLG * 2.5normal 图高度简化图controlHeightLGsmall 图高度下拉面板内controlHeightLG * 0.875。由此调整全局基础 Token如controlHeightLG会同步影响空状态图片的整体视觉比例也可以通过 Theme 配置覆盖opacityImage、colorTextDescription等变量实现整体风格定制。无障碍与 RTL图片语义字符串图片的alt会取description文案字符串时否则回退为empty内置 SVG 也带有title如 empty image、Simple Empty便于屏幕阅读器理解。RTL 支持当ConfigProvider的direction为rtl时Empty根节点自动添加${prefixCls}-rtl类配合整体 RTL 布局正常工作见 components/empty/index.tsx。使用建议优先使用内置图片默认图与简化图已适配明暗主题无需额外资源需要更小尺寸时优先PRESENTED_IMAGE_SIMPLE。字符串 vs ReactNode 图片临时替换可用 URL 字符串并配合imageStyle控制大小需要主题联动或复杂矢量图时传自定义 ReactNode/SVG 组件。全局统一优先于逐个定制涉及多组件的空状态统一替换使用ConfigProvider renderEmpty避免重复代码。用 footer 引导操作空状态不仅是告知更应配合children中的按钮给出下一步行动入口提升转化。相关示例代码与测试均可在 components/empty/demobasic、simple、customize、config-provider、description 五个官方示例与 components/empty/tests中进一步查看验证。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考