ant-design-blazor TreeSelect 自定义状态指南:error 与 warning 状态实战解析
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 的用法后可以无缝迁移。
六、参考链接
- 官方演示文档:status.md、演示源码 Status.razor
- 组件完整 API:index.zh-CN.md
- 组件实现:TreeSelect.razor.cs、TreeSelect.razor、基类 SelectBase.razor.cs
- 状态样式:status.less、样式入口 entry.less
- 表单联动:FormItem.razor.cs、FormValidateStatus.cs、AntInputComponentBase.cs
- 反馈图标渲染:SelectSuffixIcon.razor