Ant Design Blazor Result 结果反馈组件:状态图标、自定义内容与错误处理实战指南
Ant Design Blazor Result 结果反馈组件:状态图标、自定义内容与错误处理实战指南
Result 是 ant-design-blazor 中用于反馈操作任务处理结果的反馈类组件,适合在提交成功、操作失败、权限不足、页面丢失等需要“郑重告知用户结果”的场景使用。本文以官方文档(Result 组件文档)为核心,结合组件源码、官方示例与样式实现,系统讲解其状态体系、API 用法、自定义图标、动态切换状态以及结合 Blazor ErrorBoundary 的错误处理方案,帮助你快速在项目中落地各类结果页。
组件定位:何时使用 Result
根据官方文档定义,Result 组件“用于反馈一系列操作任务的处理结果”。它面向的是重要操作的结果告知场景,且“反馈内容较为复杂”时才推荐使用:
- 一个操作占用较长时间(如创建订单、提交表单、部署任务),完成后需要向用户明确展示最终状态;
- 结果本身包含多条信息,例如错误详情列表、订单号、后续操作按钮等,用一行 Toast 或消息框无法承载;
- 需要给用户提供“继续操作”的入口(如返回首页、再次购买、前往控制台)。
当反馈内容很简单、只需轻量提示时,应优先考虑 Message、Notification 等轻量反馈组件,而不是 Result 这种整页级别的结果展示。
快速上手:最小可用的 Result
Result 组件定义在 components/result/Result.razor,命名空间为 AntDesign。一个最基本的用法只需设置标题:
<Result Title="操作已完成" />
组件会按默认状态渲染为一个居中的结果展示区块:标题使用 ant-result-title,副标题使用 ant-result-subtitle,图标区域使用 ant-result-icon 或 ant-result-image,操作区使用 ant-result-extra,中间内容区使用 ant-result-content(见 components/result/Result.razor 的模板结构)。
API 详解:参数与默认值
官方文档给出了完整的参数表,结合 components/result/Result.razor.cs 的源码声明,各参数的说明如下:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| Title | title 文字 | string | RenderFragment | - |
| SubTitle | subTitle 文字 | string | RenderFragment | - |
| Status | 结果的状态,决定图标和颜色 | success | error | info | warning | 404 | 403 | 500 |
info |
| Icon | 自定义 icon | string({type}-{theme}) |
- |
| Extra | 操作区 | RenderFragment | - |
需要说明的是,文档表格中的 Title、SubTitle、Status 等参数在 C# 源码中对应 PascalCase 属性名(Title、SubTitle、Status、Icon、Extra),Razor 模板中直接按属性名使用。此外源码还公开了文档表格之外的几个可用成员,便于更灵活地组合内容:
| 额外参数 | 说明 | 默认值 |
|---|---|---|
| TitleTemplate | Title 的 RenderFragment 版本,优先级高于 Title | - |
| SubTitleTemplate | SubTitle 的 RenderFragment 版本,优先级高于 SubTitle | - |
| ChildContent | 子内容,渲染在标题/副标题与操作区之间 | - |
| IsShowIcon | 是否显示图标 | true |
模板中的渲染优先级逻辑见 components/result/Result.razor:TitleTemplate != null 时渲染 TitleTemplate,否则渲染 Title 字符串;SubTitle 同理。
Status:七种状态与默认图标
Status 是组件的核心参数,类型为 ResultStatus 枚举(定义见 components/result/ResultStatus.cs),共 7 个取值:Success、Error、Info、Warning、Http404、Http403、Http500。默认值为 Info。
源码中的类型映射表(components/result/Result.razor.cs)把枚举值映射为 CSS 修饰类名:success、error、info、warning、403、404、500,最终形成 ant-result-success、ant-result-error 等容器类,用于驱动不同状态的颜色和图标。
未自定义 Icon 时,DetermineIconType() 方法(components/result/Result.razor.cs)会按状态选择默认图标:
| Status | 默认图标 type | 图标主题 theme | 展示形式 |
|---|---|---|---|
| Success | check-circle | fill | 图标 |
| Error | close-circle | fill | 图标 |
| Warning | warning | fill | 图标 |
| Info | info-circle | fill | 图标 |
| Http403 | __unauthorized | 默认 | 整幅 SVG 图片 |
| Http404 | __not-found | 默认 | 整幅 SVG 图片 |
| Http500 | __bad-request | 默认 | 整幅 SVG 图片 |
从源码结构可以推断(见 IsImage 属性,components/result/Result.razor.cs):403、404、500 这三种“异常状态”不再使用普通图标,而是通过 IconService.GetIconImg 从图标存储中取出整幅 SVG 插图(见 components/icon/IconService.cs),以 MarkupString 形式渲染在 ant-result-image 容器内(components/result/Result.razor);其余四种状态渲染 Icon 组件并应用 fill 主题。
样式上,状态颜色由 components/result/style/index.less 控制:success 使用 @success-color、error 使用 @error-color、info 使用 @info-color、warning 使用 @warning-color,这些颜色变量定义在 components/style/themes 主题文件中,跟随主题切换。异常状态图片固定为 250×295 居中显示(components/result/style/index.less)。
状态示例:Success / Info / Warning / Error
官方示例 site/AntDesign.Docs/Demos/Components/Result/demo 给出了各状态的完整用法。
Success:成功结果
适用于“购买成功”“创建成功”“提交成功”等场景,通过 Extra 放入主要操作按钮:
<Result Status="ResultStatus.Success"
Title="Successfully Purchased Cloud Server ECS!"
SubTitle="Order number: 2017182818828182881 Cloud server configuration takes 1-5 minutes, please wait.">
<Extra>
<Button Type="ButtonType.Primary">Go Console</Button>
<Button>Buy Again</Button>
</Extra>
</Result>
完整示例见 demo/Success.razor。
Info:展示处理结果
Info 是默认状态,省略 Status 参数即为 Info。注意 Extra 既可以用子内容(ChildContent)传入,也可以绑定为一个 RenderFragment 变量:
<Result
Title="Your operation has been executed"
Extra=extra
/>
@code {
RenderFragment extra =
@<Button Type="ButtonType.Primary">
Go Console
</Button>;
}
示例见 demo/Info.razor。这里体现了 RenderFragment 类型参数的两种常见用法:直接写在标签内,或在 @code 块中构造后以属性绑定方式传入。
Warning:警告结果
<Result Status="ResultStatus.Warning"
Title="There are some problems with your operation."
Extra=extra />
@code
{
RenderFragment extra = @<Button Type="ButtonType.Primary">Go Console</Button>;
}
示例见 demo/Warning.razor。
Error:复杂错误反馈
Error 场景常需要展示多条错误明细,可以结合 Typography 组件(Paragraph、Text、Icon)在 ChildContent 中组织内容,Extra 提供补救操作:
<Result
Status="ResultStatus.Error"
Title="Submission Failed"
SubTitle="Please check and modify the following information before resubmitting."
Extra=extra>
<div class="desc">
<Paragraph>
<Text Strong Style="font-size: 16px;">
The content you submitted has the following error:
</Text>
</Paragraph>
<Paragraph>
<Icon Type="@IconType.Outline.CloseCircle" Class="site-result-demo-error-icon" /> Your account has been frozen
<a>Thaw immediately ></a>
</Paragraph>
<Paragraph>
<Icon Type="@IconType.Outline.CloseCircle" Class="site-result-demo-error-icon" /> Your account is not yet
eligible to apply <a>Apply Unlock ></a>
</Paragraph>
</div>
</Result>
@code {
RenderFragment extra =
@<Template>
<Button Type="ButtonType.Primary">Go Console</Button>
<Button>Buy Again</Button>
</Template>
;
}
示例见 demo/Error.razor。从渲染模板(components/result/Result.razor)可以看到,ChildContent 会被包在带背景色的 ant-result-content 容器中(样式见 components/result/style/index.less),适合承载这类“附加说明内容”。
异常状态页:403 / 404 / 500
三个异常状态各有一个官方示例,结构一致,仅状态枚举与文案不同:
<Result Status="ResultStatus.Http403"
Title="403"
SubTitle="Sorry, you are not authorized to access this page."
Extra="extra" />
@code
{
RenderFragment extra = @<Button Type="ButtonType.Primary">Back Home</Button>;
}
- 403:无权访问页面,见 demo/_403.razor
- 404:页面不存在,见 demo/_404.razor
- 500:服务器内部错误,见 demo/_500.razor
此类场景通常会作为全局兜底页使用:在路由无法匹配、权限校验失败或服务异常时,将整个页面替换为对应的 Result。由于这三个状态渲染的是内置 SVG 插图(而非图标字体),无需额外引入图标资源即可直接使用。
自定义 Icon:{type}-{theme} 格式解析
Icon 参数接收字符串,格式为 {type}-{theme},例如 smile-outline、like-outline、bug-outline。解析逻辑在 DetermineIconType() 方法中(components/result/Result.razor.cs):
- 以最后一个
-为分隔符拆出图标type与主题后缀; - 主题后缀
fill映射为IconThemeType.Fill,twotone映射为IconThemeType.TwoTone,其余(如outline)映射为IconThemeType.Outline; - 只要
Icon非空,就会覆盖状态对应的默认图标。
官方示例 demo/CustomIcon.razor 同时演示了自定义图标与隐藏图标:
<Result Icon="smile-outline"
Title="Great, we have done all the operations!"
Extra="extra">
</Result>
<Divider></Divider>
<Result IsShowIcon="false"
Title="Great, we can hide the icon!"
Extra="extra">
</Result>
@code
{
RenderFragment extra =@<Button Type="ButtonType.Primary">Next</Button>;
}
第二个 Result 通过 IsShowIcon="false" 完全隐藏图标区域(对应源码中的条件渲染,components/result/Result.razor)。注意:即使设置了 IsShowIcon="false",异常状态对应的 LoadImage() 逻辑仍会执行,但模板不会输出图片容器,因此展示效果不受影响。
动态修改结果:在运行时切换状态与图标
结果页不一定是静态的,可能需要根据用户操作实时切换。官方示例 demo/ChangeTheResult.razor 演示了通过 RadioGroup 选择图标、通过 Select 切换 ResultStatus 的完整方案:
<Result Icon="@icon"
Status="@status"
Title="@title"
SubTitle="@subTitle">
</Result>
<Divider/>
<Space Direction="SpaceDirection.Vertical" Size="SpaceSize.Large">
<SpaceItem>
<Space>
<SpaceItem>
<Text>Select Icon</Text>
</SpaceItem>
<SpaceItem>
<RadioGroup TValue="string" @bind-Value="icon" Size="InputSize.Large" OnChange="Rb_OnChange">
<Radio RadioButton Value="@("smile-outline")">
<Icon Type="@IconType.Outline.Smile" />
</Radio>
<Radio RadioButton Value="@("like-outline")">
<Icon Type="@IconType.Outline.Like" />
</Radio>
<Radio RadioButton Value="@("bug-outline")">
<Icon Type="@IconType.Outline.Bug" />
</Radio>
<Radio RadioButton Value="@("")">
Use Image
</Radio>
</RadioGroup>
</SpaceItem>
</Space>
</SpaceItem>
<SpaceItem>
<Space>
<SpaceItem>
<Text>Select Result</Text>
</SpaceItem>
<SpaceItem>
<Select TItem="ResultStatus" TItemValue="ResultStatus" Style="width: 150px;" @bind-Value="@status" OnSelectedItemChanged="Cbo_OnSelectedItemChanged">
<SelectOptions>
<SelectOption Label="Icon-Info" Value="ResultStatus.Info" />
<SelectOption Label="Icon-Warning" Value="ResultStatus.Warning" />
<SelectOption Label="Icon-Error" Value="ResultStatus.Error" />
<SelectOption Label="Icon-Success" Value="ResultStatus.Success" />
<SelectOption Label="Image-403" Value="ResultStatus.Http403" />
<SelectOption Label="Image-404" Value="ResultStatus.Http404" />
<SelectOption Label="Image-500" Value="ResultStatus.Http500" />
</SelectOptions>
</Select>
</SpaceItem>
</Space>
</SpaceItem>
</Space>
代码逻辑中有两个值得注意的联动细节:
- 图标与图片互斥:当选择
403/404/500这类图片状态时,代码会把icon清空,避免图标与内置插图冲突;反之,当图片状态被切换到普通图标状态时,会恢复使用Icon参数。 - 状态类型判断:示例使用
status.IsIn(ResultStatus.Http403, ResultStatus.Http404, ResultStatus.Http500)来判断是否为图片类状态,这与源码中IsImage属性的判定逻辑(components/result/Result.razor.cs)一致。
组件层面的响应机制在于:Status、Icon 参数变化后,OnParametersSet() 会重新调用 LoadImage()(components/result/Result.razor.cs),保证异常状态插图随参数联动更新。
进阶场景:结合 ErrorBoundary 做 Blazor 错误处理
Result 组件最常见的进阶用法之一,是配合 .NET 6 提供的 ErrorBoundary 组件做友好的错误兜底。官方示例 demo/ErrorBoundaryDemo.razor 展示了完整模式:
<ErrorBoundary @ref="errorBoundary">
<ChildContent>
<Button Danger OnClick="OnClick">
Click me to throw a error
</Button>
</ChildContent>
<ErrorContent Context="ex">
<Result Status="ResultStatus.Error"
Title="@ex.Message"
SubTitle="@ex.StackTrace">
<Extra>
<Button Type="ButtonType.Primary" OnClick="errorBoundary.Recover"> Recover </Button>
</Extra>
</Result>
</ErrorContent>
</ErrorBoundary>
@code {
ErrorBoundary errorBoundary;
void OnClick()
{
throw new Exception("An Uncaught Error");
}
}
该模式的要点:
- 用
ErrorBoundary包裹可能抛异常的组件树,ChildContent是正常渲染内容; - 当内部抛出未捕获异常时,
ErrorContent上下文中的ex为Exception实例,将其Message与StackTrace分别绑定到 Result 的Title与SubTitle,即可把原始错误信息组织成结构化结果页; Extra中的按钮调用errorBoundary.Recover()重置边界,让组件树恢复渲染,实现“出错后一键重试”。
这样既避免了浏览器默认的错误白屏或难读的堆栈页,又为用户保留了恢复操作的入口,是 Result 在真实应用中最有实战价值的用法之一。
样式与主题适配
Result 的样式入口为 components/result/style/index.less,由 entry.less 汇总,另外还有 patch.less 与 rtl.less 分别承载补丁样式与 RTL 适配。组件默认内边距为 48px 32px,标题使用 @heading-color、副标题使用 @text-color-secondary,图标区域底部留白 24px,操作区元素之间间距 8px(components/result/style/index.less)。
在暗色主题下,如果自定义了错误图标颜色,示例中通过 <a href="https://link.gitcode.com/i/444049ee39c15ae224230187fb23a71e" target="_blank">data-theme="dark"] 选择器覆盖(见 [demo/error.md 中的内联样式):
[data-theme="dark"] .site-result-demo-error-icon {
color: #a61d24;
}
另外,组件继承 AntDomComponentBase,支持 RTL 渲染:当配置为 RTL 时,容器会追加 ant-result-rtl 类(components/result/Result.razor.cs),由 rtl.less 负责方向翻转。
小结
ant-design-blazor 的 Result 组件覆盖了从“轻量状态告知”到“整页异常兜底”的完整结果反馈需求:7 种 Status 自动匹配图标/插图与主题色,Title/SubTitle/Extra/ChildContent 组合出任意复杂度的结果内容,Icon 参数按 {type}-{theme} 规则自定义图标,IsShowIcon 可完全隐藏图标区;动态场景下可实时切换状态与图标,配合 ErrorBoundary 还能把未处理异常包装成可恢复的友好错误页。若需查看所有官方示例,可继续阅读 site/AntDesign.Docs/Demos/Components/Result/demo 目录下的各 demo 文件。