ant-design-blazor TreeSelect 自定义状态指南:error 与 warning 状态实战解析

原创2026-10-15 14:44:441,751 阅读
文章标签:前端UI组件设计系统WebAssembly

ant-design-blazor TreeSelect 自定义状态指南:error 与 warning 状态实战解析

TreeSelect(树型选择控件)在表单场景中经常需要与错误、警告等校验状态联动。本指南基于 ant-design-blazor 官方 Demo 文档与源码,系统讲解如何通过 status 参数为 TreeSelect 添加 error 或 warning 状态,并深入剖析其底层类名映射、样式实现与表单联动原理,帮助你掌握独立定制与表单内自动校验两种用法。

一、status 参数概述

在 status.md 中,官方对 TreeSelect 自定义状态的说明非常简洁:

使用 status 为 TreeSelect 添加状态,可选 error 或者 warning。

与 Ant Design 其他输入类组件一致,TreeSelect 的 status 参数支持两种取值:

取值 含义 视觉表现
error 错误状态 边框与聚焦态使用错误主题色(@error-color)
warning 警告状态 边框与聚焦态使用警告主题色(@warning-color)

status 的语义是"强制手动指定组件的展示状态"。它既可以在独立使用时直接控制外观,也可以与 FormItem 的自动校验状态协同工作(详见下文"与表单的联动"一节)。

二、基本用法:独立指定状态

官方示例 Status.razor 展示了两种最典型的用法——单选模式下的 error 状态,以及多选(Multiple)模式下的 warning 状态:

<Space Direction="SpaceDirection.Vertical" Style="width: 100%">
  <SpaceItem>
        <TreeSelect TItem="string" TItemValue="string" Status="error" Style="width: 100%" Placeholder="Error" />
  </SpaceItem>
  <Space>
        <TreeSelect TItem="string" TItemValue="string" Status="warning" Style="width: 100%" Multiple Placeholder="Warning multiple" />
  </Space>
</Space>

要点说明:

  • TItem 与 TItemValue 泛型参数:TreeSelect 是泛型组件,需要同时指定数据项类型 TItem 与值类型 TItemValue,示例中均为 string。
  • Status 参数直接赋值:写法为 Status="error" / Status="warning",字符串写法与 Ant Design 原版保持一致。
  • Style="width: 100%":让选择框占满容器宽度(TreeSelect 默认宽度样式为 width: 100%;,见 SelectBase.razor.cs 中的 DefaultWidth)。
  • Placeholder:未选择时显示的占位文本,与状态样式互不影响。
  • Multiple:开启多选模式,演示了 warning 状态在多选场景同样生效。

示例中还使用了 Space / SpaceItem 布局组件来垂直排列两个示例,这部分仅是展示用途,并非 TreeSelect 状态功能的必需配置。

三、状态样式是如何生效的:类名映射与样式源码

status 并不是一个魔法参数,它的最终效果由"类名生成 + Less 样式"两层机制共同完成。

3.1 类名生成:ant-select-status-error / ant-select-status-warning

TreeSelect 直接继承自 SelectBase<TItemValue, TItem>(见 TreeSelect.razor.cs),状态类名正是由基类的 SetClassMap() 逻辑生成的。在 SelectBase.razor.cs 中可以看到核心代码:

var classPrefix = "ant-select";
ClassMapper
    .If($"{classPrefix}-in-form-item ", () => FormItem != null)
    .If($"{classPrefix}-has-feedback", () => FormItem?.HasFeedback == true)
    .GetIf(() => $"{classPrefix}-status-{FormItem?.ValidateStatus.ToString().ToLowerInvariant()}", () => FormItem is { ValidateStatus: not FormValidateStatus.Default });

这里有一个值得注意的实现细节:TreeSelect 的状态样式统一通过 FormItem.ValidateStatus 驱动,Status 参数在组件内部会被转换为 FormItem.ValidateStatus,最终拼出 ant-select-status-error、ant-select-status-warning、ant-select-status-success、ant-select-status-validating 等类名。也就是说,即使组件不在任何 Form/FormItem 中,独立使用 Status="error" 时也会映射出等价的 FormValidateStatus.Error,从而挂上对应类名。

3.2 样式实现:status.less 中的主题色渲染

类名对应的视觉样式定义在 status.less(TreeSelect 的样式入口 entry.less 会引入 select/style 的整套样式,因此这些规则对 TreeSelect 同样生效)。

&.@{select-prefix-cls}:not(.@{select-prefix-cls}-disabled):not(.@{select-prefix-cls}-customize-input) {
  .@{select-prefix-cls}-selector {
    background-color: @background-color;
    border-color: @border-color !important;
  }
  &.@{select-prefix-cls}-open .@{select-prefix-cls}-selector,
  &.@{select-prefix-cls}-focused .@{select-prefix-cls}-selector {
    .active(@border-color, @hoverBorderColor, @outlineColor);
  }
}
  • error 状态:边框使用 @error-color,聚焦/展开时使用 @error-color-hover 与 @error-color-outline,背景为 @select-background。
  • warning 状态:边框使用 @warning-color,聚焦/展开时使用 @warning-color-hover 与 @warning-color-outline,背景为 @input-bg。
  • 样式明确排除了 disabled 与自定义输入两种场景,保证禁用态的视觉优先级不受影响。

此外,状态类还针对带反馈图标(has-feedback)的情况调整了右侧布局——清空按钮右移、选中值文本预留出反馈图标空间(见 status.less 中 &-status-error, &-status-warning, &-status-success, &-status-validating 与 &-has-feedback 的组合规则)。

四、与表单的联动:自动校验状态

在真实业务中,状态值更多时候是由表单校验自动推导的,而不是手工写死。

4.1 级联参数链路

TreeSelect(SelectBase)通过级联参数获取所在 FormItem 的校验状态。在 AntInputComponentBase.cs 中:

[CascadingParameter(Name = "FormItem")]
protected IFormItem FormItem { get; set; }

而 FormItem 的校验状态定义在 FormItem.razor.cs:

[Parameter]
public FormValidateStatus ValidateStatus
{
    get => _validateStatus;
    set
    {
        _originalValidateStatus ??= value;
        if (_validateStatus != value)
        {
            _validateStatus = value;
            _vaildateStatusChanged?.Invoke();
        }
    }
}

FormValidateStatus 枚举(见 FormValidateStatus.cs)包含五个取值:Default、Success、Warning、Error、Validating。当 ValidateStatus 非 Default 时,TreeSelect 自动挂载对应状态类名;当为 Default 时不生成任何状态类,呈现普通样式。

4.2 配合校验规则使用

最常见的组合写法如下:

<Form Model="@model">
  <FormItem Label="所属部门" @bind-ValidateStatus="...">
    <TreeSelect TItem="Department" TItemValue="string"
                DataSource="@departments"
                TitleExpression="d => d.Name"
                KeyExpression="d => d.Id"
                ChildrenExpression="d => d.Children"
                Placeholder="请选择所属部门" />
  </FormItem>
</Form>

当字段校验失败时,FormItem 会将 ValidateStatus 更新为 Error,TreeSelect 自动呈现红色错误边框;校验通过时更新为 Success。若需要配合 HasFeedback="true" 显示校验反馈图标,TreeSelect 的后缀图标渲染逻辑(见 SelectSuffixIcon.razor)会在 ParentSelect.FeedbackIcon != null 时,将 FormItem 提供的图标一并渲染进箭头区域——FormItem 内部维护了 FormValidateStatus 到图标的映射(Success→CheckCircle、Warning→ExclamationCircle、Error→CloseCircle、Validating→Loading,见 FormItem.razor.cs)。

提示:手动指定的 Status 与表单自动校验的优先级关系,取决于两者的赋值时序。若希望状态完全由表单驱动,推荐让 FormItem.ValidateStatus 由校验规则自动生成,避免同时手工写死 Status 造成冲突。

五、TreeSelect 状态实战要点与 FAQ

5.1 状态与禁用、聚焦的视觉冲突

根据 status.less 的规则,状态色不会覆盖 disabled 与 customize-input 场景;同时当选择框处于 open(下拉展开)或 focused(聚焦)状态时,会使用更深的 hover/outline 色来强化反馈。

5.2 error/warning 之外还能用什么?

由于底层映射的是 FormValidateStatus 枚举,Status 在语义上还覆盖 success 与 validating 状态。不过官方 TreeSelect 文档(index.zh-CN.md)仅明确承诺 error 与 warning 两种取值,其他取值请结合主题变量确认视觉表现后再使用。

5.3 状态类名能否进一步定制?

可以。除了依赖内置主题色,你还可以通过 ClassMapper 对外暴露的类名在自定义样式文件中追加覆盖规则(例如针对 ant-select-status-error .ant-select-selector 调整边框粗细或背景色),实现与业务主题更契合的错误态外观。

5.4 与 Select 组件的状态差异

TreeSelect 的状态机制完全复用 Select 的 SelectBase 基类实现,因此 Select、AutoComplete、Cascader 等同族组件(它们同样在 Input.cs、Cascader.razor.cs 等处实现了 ant-*-status-* 类名逻辑)的状态用法保持一致,掌握 TreeSelect 的用法后可以无缝迁移。

六、参考链接

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