Ant Design Result 结果组件全解:状态反馈、错误页与 Design Token 主题定制
Ant Design Result 结果组件全解:状态反馈、错误页与 Design Token 主题定制
Result(结果)组件是 Ant Design 反馈类组件之一,用于在一系列操作任务处理完成后,向用户反馈较为复杂的处理结果,例如订单提交成功、服务开通完成,以及 403/404/500 这类全屏错误页面。本文基于 Ant Design 仓库中 Result 组件文档 与 核心实现源码,完整覆盖其使用场景、全部 API 参数、状态与图标映射机制、错误页插画实现、extra 操作区与 children 内容区结构,以及基于 Design Token 的主题定制方法,帮助你不仅会用,还能从源码层面理解它的渲染逻辑与样式组织方式。
何时使用
官方文档给出的适用条件是:
当有重要操作需告知用户处理结果,且反馈内容较为复杂时使用。
也就是说,Result 定位的是"结果页"级别的反馈:它比 Alert、message 这类轻量提示承载的信息更多(标题 + 副标题 + 操作区 + 可选自定义内容区),适合独立页面或模态中的最终状态呈现。
快速上手:一个典型的 success 场景
最典型的用法是业务操作完成后的成功页。仓库中的 success 示例 展示了完整形态——标题、副标题、以及包含两个按钮的操作区:
import React from 'react';
import { Button, Result } from 'antd';
const App: React.FC = () => (
<Result
status="success"
title="Successfully Purchased Cloud Server ECS!"
subTitle="Order number: 2017182818828182881 Cloud server configuration takes 1-5 minutes, please wait."
extra={[
<Button type="primary" key="console">
Go Console
</Button>,
<Button key="buy">Buy Again</Button>,
]}
/>
);
export default App;
组件渲染出的 DOM 结构为:根节点 div.ant-result 内依次是图标区、ant-result-title、ant-result-subtitle、ant-result-extra,以及传入 children 时的 ant-result-content。从 index.tsx 的返回结构可以确认这一顺序,其中 subTitle 与 extra 均为条件渲染——不传时对应节点根本不会出现在 DOM 中(subTitle 为空则跳过 subtitle 节点;extra 为 falsy 时 Extra 子组件 直接返回 null)。
状态体系:7 种 status 背后的两级映射
status 是 Result 最核心的属性,它同时决定图标/插画与根节点上的状态类名(ant-result-success、ant-result-404 等)。文档定义的取值为:
success | error | info | warning | 404 | 403 | 500
默认值为 info。这一默认值可以直接在 组件入口 的解构参数 status = 'info' 中得到确认。
从源码结构看,status 被分成了两个映射表处理(IconMap 与 ExceptionMap):
| 映射表 | 覆盖状态 | 渲染结果 |
|---|---|---|
IconMap |
success / error / info / warning |
内置图标组件:CheckCircleFilled / CloseCircleFilled / ExclamationCircleFilled / WarningFilled,包裹在 ant-result-icon 中 |
ExceptionMap |
404 / 403 / 500 |
内联 SVG 插画(尺寸约 250×295),包裹在 ant-result-icon ant-result-image 中 |
// components/result/index.tsx
export const IconMap = {
success: CheckCircleFilled,
error: CloseCircleFilled,
info: ExclamationCircleFilled,
warning: WarningFilled,
};
export const ExceptionMap = {
'404': noFound,
'500': serverError,
'403': unauthorized,
};
判断逻辑在 Icon 渲染函数 中:先把 status 转成字符串,若命中 ExceptionMap 的 key(即 '404'/'403'/'500'),就渲染对应的 SVG 插画组件;否则回退到 IconMap 中的图标。类型层面也有对应定义——ExceptionStatusType 同时接受数字与字符串形式(403 | 404 | 500 | '403' | '404' | '500'),所以 status={404} 与 status="404" 均合法。
测试用例 index.test.tsx 验证了这一行为:
status="warning"渲染出ant-result-warning类,rerender 为error、500后类名随之切换;status="404"时容器内存在.ant-result-404 .ant-result-image,即错误状态走插画分支。
四种语义状态的图标颜色并非硬编码,而是由样式层从主题色派生(见下文 Design Token 一节)。
API 参数详解
以下表格完整继承官方文档,并结合 ResultProps 类型定义 补充了类型层面的细节。通用属性(如 className、style、rootClassName 等)参考 通用属性文档。
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| extra | 操作区 | ReactNode |
- |
| icon | 自定义 icon | ReactNode |
- |
| status | 结果的状态,决定图标和颜色 | success | error | info | warning | 404 | 403 | 500 |
info |
| subTitle | subTitle 文字 | ReactNode |
- |
| title | title 文字 | ReactNode |
- |
文档未展开、但源码中实际支持的属性还有:
children:自定义内容区,渲染在ant-result-content容器内。该容器有marginTop: paddingLG、内边距与colorFillAlter背景色(见 genBaseStyle),适合放置需要弱视觉区隔的补充信息,例如错误原因列表。prefixCls/className/rootClassName/style:前缀与样式定制入口,遵循组件通用属性约定。- RTL 支持:组件从
ConfigContext读取direction,为rtl时自动附加ant-result-rtl类(index.tsx),并由 RTL 测试 保障行为。 - ConfigProvider 组件级定制:
ConfigProvider的theme.components.Result之外的组件级配置也会生效——result?.className与result?.style会合并到根节点与内联样式上(index.tsx)。
extra 操作区
extra 渲染在 ant-result-extra 容器中,容器本身是居中对齐(textAlign: 'center'),上边距由 extraMargin Token 控制,且直接子元素之间会自动附加 marginInlineEnd: paddingXS 间距、最后一个子元素去掉右侧间距(样式定义)。因此直接把多个 Button 以数组形式传入即可获得标准间距,无需手动加 Space:
extra={[
<Button type="primary" key="console">Go Console</Button>,
<Button key="buy">Buy Again</Button>,
]}
测试也验证了 extra 不传时 .ant-result-extra 节点不存在(对应用例)。
icon:自定义图标与隐藏图标
icon 接受任意 ReactNode。官方 customIcon 示例 展示了自定义图标用法:
import { SmileOutlined } from '@ant-design/icons';
import { Button, Result } from 'antd';
const App: React.FC = () => (
<Result
icon={<SmileOutlined />}
title="Great, we have done all the operations!"
extra={<Button type="primary">Next</Button>}
/>
);
源码中有两个值得注意的细节:
- 异常状态不受
icon影响:当status命中ExceptionStatus(403/404/500)时,直接渲染 SVG 插画并提前返回(index.tsx),此时传入的icon会被忽略; - 显式隐藏图标:当
icon为null或false时,图标区整体不渲染(index.tsx),测试用例 should hide icon by setting icon to false or null 对此有专门断言; - 字符串图标的破坏性警告:v4 起
icon从"图标名字符串"改为ReactNode。若传入长度超过 2 的字符串,开发环境下会通过devUseWarning输出 breaking 警告(index.tsx),对应测试 断言了icon="smile"会触发警告而icon="ab"不会。
错误页 403 / 404 / 500
三种 HTTP 语义的错误状态对应三个独立的插画组件,均为内联 SVG 实现(组件内置,无需额外资源加载):
- noFound.tsx —— 404 页面,252×294 的 "No Found" 插画;
- unauthorized.tsx —— 403 页面,251×294 的 "Unauthorized" 插画;
- serverError.tsx —— 500 页面,254×294 的 "Server Error" 插画。
典型用法(404 示例):
import React from 'react';
import { Button, Result } from 'antd';
const App: React.FC = () => (
<Result
status="404"
title="404"
subTitle="Sorry, the page you visited does not exist."
extra={<Button type="primary">Back Home</Button>}
/>
);
export default App;
除通过 status 触发插画外,组件还以静态成员的形式导出了这三个插画,方便在需要单独使用插画的场景(如登录页空状态、独立布局)中复用:
// components/result/index.tsx
Result.PRESETTED_IMAGE_403 = ExceptionMap['403'];
Result.PRESENTED_IMAGE_404 = ExceptionMap['404'];
Result.PRESENTED_IMAGE_500 = ExceptionMap['500'];
即可以直接写 <Result.PRESENTED_IMAGE_404 />(挂载逻辑,类型声明见 ResultType)。
错误状态下插画的尺寸由样式 Token imageWidth/imageHeight 约束(默认 250×295,见 mergeToken 默认值),并水平居中(margin: 'auto')。
主题变量(Design Token)
文档中的「主题变量(Design Token)」一节对应 Result 的组件级 Token。从 style/index.ts 的 ComponentToken 定义 与 prepareComponentToken 可以整理出完整的 Token 表(含默认值):
| Token | 说明 | 类型 | 默认值 |
|---|---|---|---|
titleFontSize |
标题字体大小 | number |
token.fontSizeHeading3(24) |
subtitleFontSize |
副标题字体大小 | number |
token.fontSize(14) |
iconFontSize |
图标大小 | number |
token.fontSizeHeading3 * 3(72) |
extraMargin |
额外区域外间距 | CSSProperties['margin'] |
${paddingLG}px 0 0 0(24px 0 0 0) |
通过 ConfigProvider 的 theme.components.Result 即可全局或局部覆盖。仓库中的 component-token 示例 是可直接复制的完整用法:
import React from 'react';
import { Button, ConfigProvider, Result } from 'antd';
const App: React.FC = () => (
<ConfigProvider
theme={{
components: {
Result: {
titleFontSize: 18,
subtitleFontSize: 14,
iconFontSize: 48,
extraMargin: `12px 0 0 0`,
},
},
}}
>
<Result
status="success"
title="Successfully Purchased Cloud Server ECS!"
subTitle="Order number: 2017182818828182881 Cloud server configuration takes 1-5 minutes, please wait."
extra={[
<Button type="primary" key="console">Go Console</Button>,
<Button key="buy">Buy Again</Button>,
]}
/>
</ConfigProvider>
);
除组件 Token 外,还有几个由算法 Token 派生、不直接暴露给用户但影响外观的实现细节:
- 图标状态色:
resultSuccessIconColor、resultErrorIconColor、resultInfoIconColor、resultWarningIconColor分别取自主题语义色colorSuccess/colorError/colorInfo/colorWarning(mergeToken)。因此换一套全局色板(如暗色主题、自定义 seed),Result 的图标颜色会整体联动。状态色通过 genStatusIconStyle 按ant-result-success/error/info/warning状态类分别作用于图标节点; - 文字层级:标题使用
colorTextHeading,副标题使用colorTextDescription(genBaseStyle); - 整体留白:根节点内边距为
paddingLG * 2×paddingXL,图标区下边距为paddingLG,children内容区使用colorFillAlter弱填充背景形成区隔(genBaseStyle)。
行为验证:测试用例如何印证上述机制
components/result/tests/index.test.tsx 覆盖了对应关键行为,可作为验收断言参考:
status="success"时恰好渲染一个.anticon-check-circle图标;- 切换
warning/error/500,根节点状态类名同步切换; status="404"时出现.ant-result-image插画容器;- 不传
extra时 DOM 中不存在.ant-result-extra; - 自定义
className能正确附加到根节点; icon传入长字符串触发 breaking 警告;icon={null}或icon={false}时图标区整体消失;- 组件通过
mountTest(挂载/卸载)与rtlTest(RTL 方向)基础校验。
小结
Result 组件的设计核心可以概括为三点:其一,status 单一属性驱动两级映射(语义图标 IconMap / 错误插画 ExceptionMap),并以状态类名 ant-result-{status} 暴露给样式系统;其二,title / subTitle / extra / children 四层内容槽位条件渲染,按需生成 DOM;其三,所有尺寸、间距与状态色均收敛到 Design Token 体系中,可通过 ConfigProvider 的 theme.components.Result 精确定制。基于 文档、入口实现、样式实现 与 测试,可以完整复现和验证文中所述的全部行为。