ant-design-blazor 中 Mentions 组件配合 Form 的受控模式完整指南
ant-design-blazor 中 Mentions 组件配合 Form 的受控模式完整指南
本篇指南围绕 ant-design-blazor 官方示例“配合 Form 使用(With Form)”展开,讲解如何让 Mentions 提及组件以受控模式接入 <AntDesign.Form>,实现模型绑定、必填校验、自定义文本域(TextareaTemplate)与提交回调的完整闭环。读完本文,你将掌握受控数据流(@bind-Value)在 Mentions 上的实际用法、表单布局参数(LabelColSpan / WrapperColSpan)的配置方法,以及组件底层如何在输入、选词时同步更新表单模型并触发验证。
一、受控模式:Mentions 与 Form 协作的基石
在 ant-design-blazor 中,Mentions 组件本身支持两种取值方式:
- 非受控:仅在组件内部维护文本,外部无法可靠感知值的变化;
- 受控:通过
Value参数 +ValueChanged回调(即@bind-Value双向绑定)把当前文本交给父组件或表单模型管理。
“配合 Form 使用”的官方说明原文为“受控模式,例如配合 Form 使用”,其本质就是:让 Mentions 的输入内容成为表单模型(Model)属性的一部分,从而让 Form 的验证、序列化、提交逻辑可以统一接管该字段。
从源码看,Mentions 的受控通道定义在 Mentions.razor.cs 中:
[Parameter]
public string Value { get; set; } = string.Empty;
[Parameter]
public EventCallback<string> ValueChanged { get; set; }
每次键盘输入,组件都会把最新文本写回 Value 并触发 ValueChanged(见 OnInput 与 ItemClick 两处调用),这正是 @bind-Value 语法展开后的实际行为,也是它能作为表单受控控件工作的前提。
二、官方示例完整拆解:Form + Mentions 最小可运行代码
官方 Demo 位于 Form.razor,完整代码如下(已保留原样):
@using System.ComponentModel.DataAnnotations;
@using System.Text.Json;
@using System.ComponentModel
<AntDesign.Form Model="@model"
OnFinish="OnFinish"
OnFinishFailed="OnFinishFailed"
LabelColSpan="8"
WrapperColSpan="16">
<FormItem Label="Comment">
<Mentions @bind-Value=@model.Comment>
<MentionsOption Value="afc163">afc163</MentionsOption>
<MentionsOption Value="zombieJ">zombieJ</MentionsOption>
<MentionsOption Value="yesmeck">yesmeck</MentionsOption>
</Mentions>
</FormItem>
<FormItem Label="Another Comment">
<Mentions @bind-Value="@model.AnotherComment">
<ChildContent>
<MentionsOption Value="afc163">afc163</MentionsOption>
<MentionsOption Value="zombieJ">zombieJ</MentionsOption>
<MentionsOption Value="yesmeck">yesmeck</MentionsOption>
</ChildContent>
<TextareaTemplate Context="mentionsContext">
<TextArea RefBack=@mentionsContext.RefBack
OnInput=@mentionsContext.OnInput
BindOnInput=false
OnKeyDown=@mentionsContext.OnKeyDown
Value=@mentionsContext.Value
ShowCount=true
MaxLength="200" />
</TextareaTemplate>
</Mentions>
</FormItem>
<FormItem WrapperColOffset="8" WrapperColSpan="16">
<Button Type="ButtonType.Primary" HtmlType="submit">
Submit
</Button>
</FormItem>
</AntDesign.Form>
@code
{
public class Model
{
[Required]
public string Comment { get; set; }
[Required]
public string AnotherComment{ get; set; }
}
private Model model = new Model();
private void OnFinish(EditContext editContext)
{
Console.WriteLine($"Success:{JsonSerializer.Serialize(model)}");
}
private void OnFinishFailed(EditContext editContext)
{
Console.WriteLine($"Failed:{JsonSerializer.Serialize(model)}");
}
}
该示例覆盖了四个关键实战点:
- 模型绑定:
<AntDesign.Form Model="@model">声明表单模型,<Mentions @bind-Value=@model.Comment">把提及输入框的文本直接双向绑定到模型属性; - 必填校验:模型属性上标注
[Required],提交时若为空则进入OnFinishFailed分支; - 自定义文本域:第二个 FormItem 通过
TextareaTemplate把默认<textarea>替换为带字数统计(ShowCount)和长度限制(MaxLength="200")的TextArea; - 提交回调:
OnFinish校验通过后执行(示例中序列化模型输出),OnFinishFailed校验失败时执行。
三、数据流原理:输入、选词与表单模型的同步
要理解受控模式为何能配合 Form 工作,需要看清 Mentions 内部的数据更新路径。以 Mentions.razor.cs 为据:
路径一:普通输入(OnInput)
用户在文本域输入时,OnInput 把 args.Value 写入 Value 并立即调用 ValueChanged:
private async Task OnInput(ChangeEventArgs args)
{
Value = args.Value.ToString();
await ValueChanged.InvokeAsync(Value);
// ... 之后按光标位置查找前缀,决定是否弹出候选列表
}
在 Form 场景下,ValueChanged 会被 @bind-Value=@model.Comment 转发为对模型属性的赋值,因此每一次按键都会实时同步到模型。
路径二:选择候选(ItemClick)
当用户从下拉列表选中一个 MentionsOption 时,ItemClick 会在光标处拼接 前缀 + 选项值 + 空格,同样写回 Value 并触发 ValueChanged:
Value = new StringBuilder()
.Append(preText)
.Append(' ').Append(_currentPrefix).Append(optionValue).Append(' ')
.Append(nextText)
.ToString();
await ValueChanged.InvokeAsync(Value);
路径三:模板回传(TextareaTemplate)
使用 TextareaTemplate 时,Mentions 通过 MentionsTextareaTemplateOptions.cs 把四个成员交给自定义模板:
public class MentionsTextareaTemplateOptions
{
public string Value { get; set; }
public ForwardRef RefBack { get; set; }
public Func<KeyboardEventArgs, Task> OnKeyDown { get; set; }
public Func<ChangeEventArgs, Task> OnInput { get; set; }
}
模板中必须把 OnInput、OnKeyDown、Value、RefBack 回绑到实际的 TextArea(见示例代码),Mentions 才能继续接管输入事件、前缀解析与候选框定位。官方 TextareaTemplate.razor 与 Form 示例中的用法完全一致,可以对照参考。
四、Form 侧如何识别 Mentions 字段并完成验证
4.1 FormItem 的字段识别
FormItem 会通过级联参数与内部控件通信。对于 Mentions @bind-Value=@model.Comment,FormItem 从控件的 ValueExpression(@bind-Value 编译产物)解析出 FieldIdentifier 与属性反射器,相关实现见 FormItem.razor.cs:
else if (control.ValueExpression is not null)
{
_propertyReflector = PropertyReflector.Create(control.ValueExpression);
}
_fieldValueGetter = _propertyReflector?.GetValueDelegate;
_fieldIdentifier = new FieldIdentifier(Form.Model, Name);
这意味着只要控件(Mentions)提供标准的 ValueExpression,FormItem 就能自动把它的值纳入验证体系,无需手写任何接线代码。
4.2 必填校验与错误状态
示例模型中的 <a href="https://link.gitcode.com/i/f69431f900dd7dca71c4b7ef5a40bb77" target="_blank">Required] 注解会被 FormItem 解析为验证规则;当触发校验(提交表单)时,FormItem 通过 _fieldValueGetter 读取模型当前值并执行规则(IFormItem.ValidateFieldWithRules(),见 [FormItem.razor.cs)。校验失败时 FormItem 会显示错误状态与消息。这正是官方 Demo 中两个字段都标注 [Required] 的原因——用于演示“空值提交 → 校验失败 → OnFinishFailed”的完整链路。
4.3 提交与回调
表单提交由 Form.razor.cs 驱动:OnFinish(校验通过)与 OnFinishFailed(校验失败)均为 EventCallback<EditContext>,参数是 Blazor 标准的 EditContext。注意示例中 OnFinish 直接序列化的是 model 字段而非 editContext——因为受控绑定已经把最新值同步进了模型,序列化模型即可拿到完整表单数据。
五、布局参数:LabelColSpan / WrapperColSpan / WrapperColOffset
Form 示例中通过三个参数控制两列布局:
| 参数 | 作用 | 类型 | 说明 |
|---|---|---|---|
LabelColSpan |
标签列宽度 | OneOf<string, int> |
值为栅格 24 分栏中的格数,示例 8 表示标签占 8/24 |
WrapperColSpan |
输入控件列宽度 | OneOf<string, int> |
示例 16 表示输入区占 16/24 |
WrapperColOffset |
输入区左偏移 | OneOf<string, int> |
示例中“Submit”按钮所在 FormItem 用它抵消标签列宽度(8),使按钮与输入区左对齐 |
这三个参数同时存在于 AntDesign.Form 与 FormItem 上,分别对应 Form.razor.cs 与 FormItem.razor.cs 中的同名参数;它们本质是操作内部 ColLayoutParam 的 Span / Offset 属性。Form 上的设置作为默认值,FormItem 可单独覆盖。
六、从源码与测试验证受控行为的可靠性
仓库中 MentionsTests.razor 提供了受控数据流的直接证据:测试通过模拟输入 "@username" 断言 LoadOptions 收到搜索值、通过断言渲染出的下拉 li 列表验证选项展示,还覆盖了静态 MentionsOption 按搜索词过滤的逻辑(ItShouldDisplayOptionsWithValueContainingSearchValueWhenUserTypesForStaticOptions)。这些测试佐证了“输入 → 前缀识别 → 候选展示 → 选词回写”这一受控链条的实现是稳定可测的。
结合组件实现可以确认的完整工作流程为:
- 用户输入
@(默认前缀,见Prefix参数默认值)后,Mentions 根据光标位置识别前缀与搜索词(源码位于 Mentions.razor.cs 的OnInput); - 通过
OriginalOptions(静态MentionsOption注册)或LoadOptions(动态加载,可配合OnSearch回调)筛选候选; - 选中后由
ItemClick拼接文本并同步ValueChanged,表单模型随之更新; - 点击 Submit 触发 Form 校验,结果分流到
OnFinish/OnFinishFailed。
七、实战要点与注意事项
- 默认前缀为
@:Prefix参数可自定义(如"@,#"以逗号分隔多个前缀),InitializePrefixes()会按前缀长度降序编译正则,多个前缀场景下优先匹配更长前缀(见 Mentions.razor.cs); - 模板绑定不要遗漏:一旦使用
TextareaTemplate,OnInput、OnKeyDown、Value、RefBack四个上下文成员必须全部回绑到自定义TextArea,否则候选框无法弹出或无法更新值; - 受控与非受控二选一:与 Form 集成时必须使用
@bind-Value(受控模式),这也是官方将该 Demo 命名为“受控模式”的原因;单纯独立使用时可直接@bind-Value到局部变量(参考 Basic.razor); - 组件 API 一览:完整的参数说明(
autoFocus、defaultValue、prefix、split、notFoundContent、placement等)与Option参数(value、children)可查阅官方组件文档 index.zh-CN.md; - 动态选项场景:如果候选数据来自服务端,可使用
LoadOptions委托(签名Func<string, CancellationToken, Task<IEnumerable<MentionsDynamicOption>>>),测试用例ItShouldCallLoadOptionsWithSearchValueWhenUserEntersValueAfterPrefix验证了该路径的搜索值传递行为。
按照以上结构,你可以在自己的 Blazor 表单中直接复用官方 Demo 的写法:定义一个带 [Required] 的模型类,用 <Mentions @bind-Value="..."> 绑定字段,配合 TextareaTemplate 定制输入体验,最后通过 OnFinish / OnFinishFailed 接管提交结果,即可获得一套完整、可校验的“提及”数据录入方案。