Ant Design Result 结果组件全解:状态反馈、错误页与 Design Token 主题定制

原创2026-09-18 09:04:171,813 阅读
文章标签:前端UI组件设计系统

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>}
  />
);

源码中有两个值得注意的细节:

  1. 异常状态不受 icon 影响:当 status 命中 ExceptionStatus(403/404/500)时,直接渲染 SVG 插画并提前返回(index.tsx),此时传入的 icon 会被忽略;
  2. 显式隐藏图标:当 icon 为 null 或 false 时,图标区整体不渲染(index.tsx),测试用例 should hide icon by setting icon to false or null 对此有专门断言;
  3. 字符串图标的破坏性警告: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 精确定制。基于 文档、入口实现、样式实现 与 测试,可以完整复现和验证文中所述的全部行为。

登录后查看全文
ant-design