ant-design-blazor 中 Mentions 组件配合 Form 的受控模式完整指南

原创2026-10-11 17:58:431,976 阅读
文章标签:UI组件前端

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)}");
    }
}

该示例覆盖了四个关键实战点:

  1. 模型绑定:<AntDesign.Form Model="@model"> 声明表单模型,<Mentions @bind-Value=@model.Comment"> 把提及输入框的文本直接双向绑定到模型属性;
  2. 必填校验:模型属性上标注 [Required],提交时若为空则进入 OnFinishFailed 分支;
  3. 自定义文本域:第二个 FormItem 通过 TextareaTemplate 把默认 <textarea> 替换为带字数统计(ShowCount)和长度限制(MaxLength="200")的 TextArea;
  4. 提交回调: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)。这些测试佐证了“输入 → 前缀识别 → 候选展示 → 选词回写”这一受控链条的实现是稳定可测的。

结合组件实现可以确认的完整工作流程为:

  1. 用户输入 @(默认前缀,见 Prefix 参数默认值)后,Mentions 根据光标位置识别前缀与搜索词(源码位于 Mentions.razor.cs 的 OnInput);
  2. 通过 OriginalOptions(静态 MentionsOption 注册)或 LoadOptions(动态加载,可配合 OnSearch 回调)筛选候选;
  3. 选中后由 ItemClick 拼接文本并同步 ValueChanged,表单模型随之更新;
  4. 点击 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 接管提交结果,即可获得一套完整、可校验的“提及”数据录入方案。

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