Ant Design Blazor 多表单联动:FormProvider 在表单间处理数据的完整实践

原创2026-10-09 12:11:081,764 阅读
文章标签:前端UI组件设计系统WebAssembly

Ant Design Blazor 多表单联动:FormProvider 在表单间处理数据的完整实践

本文以 Ant Design Blazor 官方示例 form-context.md(多表单联动 / Form Provider)为核心,讲解 FormProvider 组件如何在多个表单之间传递、汇聚数据。读完本文,你将掌握 Modal 弹窗按钮在 Form 之外时如何通过 Form.Submit 触发提交、OnFormFinish 事件的注册与派发机制,以及如何通过 Name 属性跨表单取回任意表单的 Model 完成数据联动。

核心场景:Modal 确认按钮在 Form 之外

官方文档对该示例的说明是:

通过 FormProvider 在表单间处理数据。本例子中,Modal 的确认按钮在 Form 之外,通过 form.Submit 方法调用表单提交功能。反之,则推荐使用 <Button HtmlType="submit" /> 调用 web 原生提交逻辑。

英文文档(同一文件 en-US 小节)的表述一致:

Use FormProvider to process data between forms. In this case, the form's submit button is in the modal, outside of the Form component. You can use Form.Submit to submit the form. We recommend using the native submit input by using <Button HtmlType="submit" /> to submit a form.

这对应一个非常典型的实战问题:主表单的提交按钮放在 Form 内部时,可以直接写 <Button HtmlType="submit"> 走浏览器原生 <form> 提交逻辑;但当按钮出现在 Modal 的 footer 里(如"确认"按钮)时,它位于 Form 渲染边界之外,原生提交链路已经断裂,就必须拿到 Form 组件的引用,显式调用 Submit() 方法。而"表单 A 提交成功后,把数据写回表单 B 的 Model"这类跨表单数据联动,则完全交给 FormProvider 来协调。

完整示例:主表单 + 弹窗子表单的数据联动

以下代码完整来自示例文件 FormContext.razor,由三层结构组成:FormProvider 包裹两个 Form,主表单 basicForm 维护一个用户组,Modal 内的 userForm 负责新增单个用户,用户提交后数据回写主表单的 Users 列表。

@using System.Text.Json;
@using System.ComponentModel.DataAnnotations;

<FormProvider OnFormFinish="OnFormFinish">
    <!-- 主表单:basicForm,Model 为 UserGroup -->
    <Form Model="@_baseFormModel"
          Name="basicForm"
          OnFinish="OnBasicFinish"
      LabelColSpan="8"
      WrapperColSpan="16">
        <FormItem Label="Group Name">
            <Input @bind-Value="context.GroupName" />
        </FormItem>
        <FormItem Label="User List">
            @if (context.Users.Count > 0)
            {
                <ul>
                    @for (int i = 0; i < context.Users.Count; i++)
                    {
                        <li class="user">
                            <Icon Type="@IconType.Outline.User" />
                            @(context.Users[i].Name) - @(context.Users[i].Age)
                        </li>
                    }
                </ul>
            }
            else
            {
                <Paragraph>
                    <Text Class="ant-form-text">
                        ( <Icon Type="@IconType.Outline.Smile" /> No user yet. )
                    </Text>
                </Paragraph>
            }
        </FormItem>
        <FormItem WrapperColOffset="8" WrapperColSpan="16">
            <!-- 按钮在 Form 内:使用原生提交 -->
            <Button HtmlType="submit" Type="ButtonType.Primary">
                Submit
            </Button>
            <Button HtmlType="button" Style="margin: 0 8px" OnClick="ShowUserModal">
                Add User
            </Button>
        </FormItem>
    </Form>

    <!-- Modal 内的子表单:userForm,Model 为 User -->
    <Modal Title=@("Basic Drawer")
           Visible="@_modelVisible"
           OnOk="@HandleOk"
           OnCancel="@HideUserModal">
        <Form @ref="@_userForm" Model="@_userFormModel" Layout="FormLayout.Vertical" Name="userForm">
            <FormItem Label="User Name">
                <Input @bind-Value="@context.Name" />
            </FormItem>
            <FormItem Label="User Age">
                <AntDesign.InputNumber @bind-Value="@context.Age" />
            </FormItem>
        </Form>
    </Modal>
</FormProvider>

@code {
    public class User
    {
        [Required]
        public string Name { get; set; }
        [Required]
        public int Age { get; set; }
    }

    public class UserGroup
    {
        [Required]
        public string GroupName { get; set; }
        // [ValidateComplexType]
        public List<User> Users { get; set; } = new List<User>();
    }

    private Form<User> _userForm;
    private User _userFormModel = new User();
    private UserGroup _baseFormModel = new UserGroup();
    private bool _modelVisible = false;

    // FormProvider 的统一完成回调:任何内部表单校验通过并提交后都会进入这里
    private void OnFormFinish(FormProviderFinishEventArgs args)
    {
        if (args.FinishForm.Name == "userForm")
        {
            // if you can't get the reference of _userForm and _baseFormModel, you should:
            User user = (User)args.FinishForm.Model;
            UserGroup userGroup = (UserGroup)args.Forms["basicForm"].Model;

            userGroup.Users.Add(new User { Name = user.Name, Age = user.Age });

            // if you have the reference of _userForm and _baseFormModel, you can:
            //_baseFormModel.Users.Add(new User { Name = _userFormModel.Name, Age = _userFormModel.Age });
        }
        HideUserModal();
    }

    private void OnBasicFinish(EditContext editContext)
    {
        Console.WriteLine($"Success:{JsonSerializer.Serialize(editContext.Model)}");
    }

    // Modal 确认按钮在 Form 之外:显式调用组件方法提交
    private void HandleOk(MouseEventArgs args)
    {
        _userForm?.Submit();
    }

    private void ShowUserModal()
    {
        _modelVisible = true;
    }

    private void HideUserModal()
    {
        _modelVisible = false;
        _userForm?.Reset();
    }
}

示例中有四个关键动作值得逐一对应源码理解:

  1. <Button HtmlType="submit">:主表单的 Submit 按钮在 Form 内部,走浏览器原生提交,最终触发 OnFinish(OnBasicFinish)。
  2. _userForm?.Submit():Modal 的 OnOk 处理函数里显式调用 Form.Submit(),这是"按钮在 Form 外"的标准解法。
  3. OnFormFinish:FormProvider 级的事件,两个表单中任何一个提交成功都会触发,用于跨表单数据汇聚。
  4. _userForm?.Reset():关闭弹窗时重置子表单,保证下次打开是干净状态。

FormProvider 的实现:CascadingValue + 表单注册表

注册链路

FormProvider.razor 的模板极其简洁,它通过一个固定命名的级联值把自己注入子树:

@namespace AntDesign
@inherits AntComponentBase

<CascadingValue Name="FormProvider" Value="this" IsFixed="@true">
    @ChildContent
</CascadingValue>

对应地,Form.razor.cs 中声明了接收端:

[CascadingParameter(Name = "FormProvider")]
private IFormProvider FormProvider { get; set; }

注意 CascadingParameter 匹配的是 Name = "FormProvider" 而非类型。Form 在 OnInitialized 里完成自注册(Form.razor.cs):

protected override void OnInitialized()
{
    base.OnInitialized();
    Model ??= (TModel)Expression.New(typeof(TModel)).Constructor.Invoke(new object[] { });
    _editContext = new EditContext(Model);
    FormProvider?.AddForm(this);
    // ...
}

也就是说:只要 Form 出现在某个 FormProvider 的 ChildContent 内(含 Modal 这类渲染到同一组件子树中的弹窗),它就会自动进入 Provider 的表单注册表,无需手动配置。

提交事件的汇聚与派发

FormProvider.razor.cs 的核心是一个以表单 Name 为键的字典,以及订阅每个表单完成事件的转发逻辑:

public partial class FormProvider : AntComponentBase, IFormProvider
{
    [Parameter]
    public EventCallback<FormProviderFinishEventArgs> OnFormFinish { get; set; }

    [Parameter]
    public RenderFragment ChildContent { get; set; }

    private Dictionary<string, IForm> _forms = new Dictionary<string, IForm>();

    void IFormProvider.AddForm(IForm form)
    {
        _forms.Add(form.Name, form);
        form.OnFinishEvent += OnFinish;
    }

    private void OnFinish(IForm form)
    {
        var args = new FormProviderFinishEventArgs
        {
            Forms = _forms,
            FinishForm = form
        };
        OnFormFinish.InvokeAsync(args);
    }

    public IForm GetForm(string formName)
    {
        if (_forms.TryGetValue(formName, out IForm form))
        {
            return form;
        }
        return null;
    }

    public bool TryGetForm(string formName, out IForm form)
    {
        if (_forms.TryGetValue(formName, out form))
        {
            return true;
        }
        return false;
    }
}

结合 Form<TModel>.Submit() 的实现(Form.razor.cs),完整调用链是:

Modal OnOk -> _userForm.Submit()
            -> Validate() 校验全部字段
            -> 校验通过: OnFinish 回调 + OnFinishEvent 内部事件
            -> FormProvider.OnFinish(form) 汇总
            -> OnFormFinish.InvokeAsync(args)
            -> 你的 OnFormFinish(args),args 含 FinishForm 与全部 Forms

需要注意两点细节:

  • Submit() 内部先执行 Validate(),只有校验通过才会触发 OnFinish 并广播 OnFinishEvent;校验失败只触发 OnFinishFailed,FormProvider 层感知不到失败提交。因此在 OnFormFinish 中处理数据联动时,可以假定数据已通过校验。
  • 从源码结构看,FormProvider 的 RemoveForm 实现(FormProvider.razor.cs)中解除订阅的代码行与 AddForm 相同(仍是 +=),如果页面存在表单频繁创建销毁的场景,事件转发可能重复触发。这是一个阅读源码时可以留意的实现细节,编写健壮业务代码时建议通过 FinishForm.Name 精确判定来源表单(示例已经这么做了)来降低影响。

事件参数 FormProviderFinishEventArgs:跨表单取数据的两条路

事件参数定义在 FormProviderFinishEventArgs.cs:

namespace AntDesign
{
    public class FormProviderFinishEventArgs
    {
        public Dictionary<string, IForm> Forms { get; set; }
        public IForm FinishForm { get; set; }
    }
}
  • FinishForm:本次触发提交的表单实例,可读取其 Name、Model、EditContext 等。
  • Forms:Provider 下全部已注册表单的字典,键为 Name 属性值——这就是"在拿不到其他表单组件引用时"跨表单取数据的官方方式。

示例中的 OnFormFinish 演示了两种写法:

写法一(无组件引用,纯事件驱动)——只依赖事件参数:

User user = (User)args.FinishForm.Model;
UserGroup userGroup = (UserGroup)args.Forms["basicForm"].Model;
userGroup.Users.Add(new User { Name = user.Name, Age = user.Age });

写法二(持有 @ref 与 Model 引用)——直接操作字段:

_baseFormModel.Users.Add(new User { Name = _userFormModel.Name, Age = _userFormModel.Age });

示例注释明确给出了取舍:当你拿不到 _userForm / _baseFormModel 的引用时(例如表单在其他组件里定义),用 args 中的 FinishForm.Model 与 args.Forms<a href="https://link.gitcode.com/i/a6b2c562ee34e6c87e0d5088bf6ed5cd" target="_blank">"basicForm"].Model 是可靠路径。IForm 接口([IForm.cs)同时暴露 Model、EditContext、Submit、Reset、Validate 等成员,配合 GetForm(string formName) / TryGetForm(string formName, out IForm form) 两个方法,你可以在 Provider 内任意时刻按 Name 查询表单实例。

这也解释了 Form.razor.cs 中 Name 参数的文档注释:

Gets or sets the form handler name. This is required for posting it to a server-side endpoint. Or using for get the form instance from FormProviderFinishEventArgs.

即 Name 的双重用途:一是服务端表单提交时的 action 名,二是作为 FormProvider 注册表的主键。

两种提交方式的对比与选择

文档给出了一条明确的选型准则,可以总结为:

场景 推荐方式 原理
提交按钮在 <Form> 内部 <Button HtmlType="submit" /> 走浏览器原生 <form> 提交流程,由 Enhance 等机制增强为无刷新提交,最终触发 OnFinish
提交按钮在 Form 之外(Modal footer、工具栏等) 持有 Form<T> 的 @ref,调用 Submit() Submit() 内部执行 Validate(),通过则触发 OnFinish 并向 FormProvider 广播

Submit() 与 Reset() 都定义在 Form<TModel> 上(Form.razor.cs 与 Form.razor.cs):Reset() 会遍历已注册的控件执行 item.Reset() 并重建 EditContext,因此示例在关闭 Modal 时调用它来清空输入;Submit() 则是同步返回校验结果并异步触发回调的完整提交入口。

小结:FormProvider 的使用要点

结合 form-context.md 文档与 FormContext.razor 示例源码,可以把多表单联动的落地要点归纳为:

  1. 用 <FormProvider OnFormFinish="..."> 包裹需要联动的全部表单,表单通过级联值自动注册,无需手工接线;
  2. 给每个 Form 设置唯一 Name,这是事件参数中 Forms 字典与 GetForm / TryGetForm 的查询键;
  3. 按钮在表单内用 HtmlType="submit",按钮在表单外(如 Modal 确认按钮)用 @ref + Submit();
  4. 在 OnFormFinish 中先以 args.FinishForm.Name 判定来源表单,再通过 FinishForm.Model 或 Forms["name"].Model 完成跨表单数据写入;
  5. 关闭弹窗等重置时机调用 Reset(),保证子表单状态干净。

相关文件清单,便于延伸阅读:

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