Ant Design Blazor Result 结果反馈组件:状态图标、自定义内容与错误处理实战指南

原创2026-10-12 00:19:011,860 阅读
文章标签:UI组件前端

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 &gt;</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 &gt;</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>;
}

此类场景通常会作为全局兜底页使用:在路由无法匹配、权限校验失败或服务异常时,将整个页面替换为对应的 Result。由于这三个状态渲染的是内置 SVG 插图(而非图标字体),无需额外引入图标资源即可直接使用。

自定义 Icon:{type}-{theme} 格式解析

Icon 参数接收字符串,格式为 {type}-{theme},例如 smile-outline、like-outline、bug-outline。解析逻辑在 DetermineIconType() 方法中(components/result/Result.razor.cs):

  1. 以最后一个 - 为分隔符拆出图标 type 与主题后缀;
  2. 主题后缀 fill 映射为 IconThemeType.Fill,twotone 映射为 IconThemeType.TwoTone,其余(如 outline)映射为 IconThemeType.Outline;
  3. 只要 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>

代码逻辑中有两个值得注意的联动细节:

  1. 图标与图片互斥:当选择 403/404/500 这类图片状态时,代码会把 icon 清空,避免图标与内置插图冲突;反之,当图片状态被切换到普通图标状态时,会恢复使用 Icon 参数。
  2. 状态类型判断:示例使用 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 文件。

登录后查看全文
ant-design-blazor