Ant Design Blazor 表单尺寸设置：Form 组件 Size 参数的用法与级联实现原理

• 前端
• UI组件
• 设计系统

本文讲解 Ant Design Blazor 中 Form 组件的Size参数：通过一个枚举值统一控制表单内各类 Ant Design 受控组件（Input、Select、DatePicker、Button 等）的尺寸，并深入剖析其基于CascadingValue级联机制的底层实现，帮助你在实际项目中快速做出紧凑或大气的表单布局。

功能概述

Ant Design Blazor 的表单（Form）组件支持通过Size参数设置表单内各 Ant Design 组件的尺寸，官方演示文档（size.md）给出的说明是：

设置表单组件尺寸，仅对 antd 组件有效。

即：给<Form>设置一个尺寸值后，表单内所有支持尺寸联动的 Ant Design 组件都会跟随该尺寸渲染，无需为每个输入控件单独配置Size。需要注意的是，这一联动仅对 Ant Design Blazor 自家的组件有效——如果你把第三方 UI 控件放在表单里，它们不会感知表单尺寸，需要自行设置。

Size参数在 Form 的 API 表中定义如下（见 Form 组件 API 文档）：

对应的枚举定义非常简洁，见 FormSize.cs：

namespace AntDesign { public enum FormSize { Large, Default, Small } }

完整示例：一个尺寸联动的表单

官方演示组件 Size.razor 展示了该功能的完整用法：用一个单选组切换FormSize，下方各类输入组件随之改变尺寸。示例核心结构如下（为便于说明，保留了所有关键行）：

<Form Model="@model" LabelColSpan="8" WrapperColSpan="16" OnFinish="OnFinish" OnFinishFailed="OnFinishFailed" Size="@model.Size"> <FormItem Label="Form Size"> <RadioGroup @bind-Value="@context.Size"> <Radio RadioButton Value="@FormSize.Small">Small</Radio> <Radio RadioButton Value="@FormSize.Default">Default</Radio> <Radio RadioButton Value="@FormSize.Large">Large</Radio> </RadioGroup> </FormItem> <FormItem Label="Input"> <Input @bind-Value="@context.Input" /> </FormItem> <FormItem Label="InputArea"> <TextArea @bind-Value="@context.InputArea" /> </FormItem> <FormItem Label="Cascader"> <Cascader @bind-Value="@context.Cascader" Options="districts" /> </FormItem> <FormItem Label="DatePicker"> <DatePicker @bind-Value="@context.DatePicker" /> </FormItem> <FormItem Label="RangePicker"> <RangePicker @bind-Value="@context.RangePicker" /> </FormItem> <FormItem Label="InputNumber"> <AntDesign.InputNumber @bind-Value="@context.Number" /> </FormItem> <FormItem Label="Switch"> <Switch @bind-Value="@context.Switch" /> </FormItem> <FormItem Label="Radio"> <RadioGroup @bind-Value="@context.Radio"> <Radio RadioButton Value="@("Hangzhou")">Hangzhou</Radio> <Radio RadioButton Value="@("Shanghai")">Shanghai</Radio> <Radio RadioButton Value="@("Beijing")">Beijing</Radio> <Radio RadioButton Value="@("Chengdu")">Chengdu</Radio> </RadioGroup> </FormItem> <FormItem Label="AutoComplete"> <AutoComplete @bind-Value="@context.AutoComplete" Options="@autoCompleteOptions" Placeholder="Input here" /> </FormItem> <FormItem Label="Select"> <Select Mode="SelectMode.Default" DataSource="@_persons" @bind-Value="@context.Name" LabelName="@nameof(Person.Name)" ValueName="@nameof(Person.Name)"> </Select> </FormItem> <FormItem Label="Multiselect"> <Select Mode="SelectMode.Multiple" DataSource="@_persons" @bind-Values="@context.Names" LabelName="@nameof(Person.Name)" ValueName="@nameof(Person.Name)"> </Select> </FormItem> <FormItem WrapperColOffset="8" WrapperColSpan="16"> <Button HtmlType="submit"> Submit </Button> </FormItem> </Form> @code { public class Model { public FormSize Size { get; set; } = FormSize.Small; public string Input { get; set; } = "input"; public string InputArea { get; set; } = "inputArea"; public string Cascader { get; set; } = "11"; public DateTime? DatePicker { get; set; } = DateTime.Now; public DateTime?[] RangePicker { get; set; } = new DateTime?[] { DateTime.Now, DateTime.Now.AddDays(10) }; public double Number { get; set; } = 1; public bool Switch { get; set; } = true; public string Radio { get; set; } = "Beijing"; public string AutoComplete { get; set; } public string Name { get; set; } public IEnumerable<string> Names { get; set; } = Array.Empty<string>(); } private Model model = new Model(); // districts、autoCompleteOptions、_persons 为演示数据，此处省略 ... }

从这个示例可以读出几个实战要点：

• Size可以直接绑定到模型属性（Size="@model.Size"），因此在运行时切换尺寸、并随表单数据一起提交后端都是可行的；
• 联动效果覆盖Input、TextArea、Cascader、DatePicker、RangePicker、InputNumber、Switch、AutoComplete、Select（单选/多选）等输入类组件，以及作为提交按钮的Button；
• 表单本身的布局参数（LabelColSpan、WrapperColSpan）与Size相互独立，尺寸只影响控件的渲染大小，不影响栅格布局。

实现原理：可空参数 + 条件级联

Size之所以能"一个参数管全局"，依赖 Blazor 的级联参数机制。在 Form.razor.cs 中，参数被声明为可空类型：

public FormSize? Size { get; set; }

并通过 IForm 接口向内部暴露非空视图：

FormSize IForm.Size => Size.GetValueOrDefault();

关键在于 Form.razor 的渲染逻辑——只有当Size显式赋值时，才会额外包裹一层名为FormSize的CascadingValue：

<CascadingValue Value="this" Name="Form" TValue="IForm" IsFixed="@true"> @if (Size.HasValue) { <CascadingValue Value="Size" Name="FormSize"> @ChildContent(Model) </CascadingValue> } else { @ChildContent(Model) } </CascadingValue>

从源码结构看，这里做了两层嵌套级联：

1. 外层CascadingValue（Name="Form"，TValue="IForm"）向下传递表单实例本身，供子组件访问表单上下文（校验、提交等）；
2. 内层CascadingValue（Name="FormSize"）只在Size非空时存在，向下广播尺寸值。

"条件级联"这个设计很巧妙：不设置Size时，下游组件的FormSize?级联参数拿到的是null，从而回退到各自默认尺寸，不产生任何干扰；设置后，所有订阅者一次性跟随切换。

组件侧如何消费表单尺寸

以输入类组件基类 AntInputComponentBase.cs 为例，它通过[CascadingParameter(Name = "FormSize")]接收级联值：

private FormSize _formSize; [CascadingParameter(Name = "FormSize")] public FormSize? FormSize { get => _formSize; set { _formSize = value.GetValueOrDefault(AntDesign.FormSize.Default); ... } }

随后基类内置了一张FormSize到InputSize的映射表，将表单尺寸翻译成输入控件的实际尺寸：

private static readonly Dictionary<FormSize, InputSize> _formSizeMap = new() { [AntDesign.FormSize.Large] = InputSize.Large, [AntDesign.FormSize.Default] = InputSize.Default, [AntDesign.FormSize.Small] = InputSize.Small, };

按钮组件同理，见 Button.razor.cs：

private FormSize? _formSize; [CascadingParameter(Name = "FormSize")] public FormSize? FormSize { get => _formSize; set { _formSize = value; switch (value) { case AntDesign.FormSize.Large: _buttonSize = ButtonSize.Large; break; case AntDesign.FormSize.Small: _buttonSize = ButtonSize.Small; break; ... } } }

因此"仅对 antd 组件有效"这句文档说明在源码层面有了精确解释：只有实现了Name = "FormSize"级联参数订阅的 Ant Design 组件才会响应表单尺寸；表单里的任意原生 HTML 控件或第三方组件不会订阅该级联值，自然不受影响。

实践建议

• 默认值：不设置Size时等价于FormSize.Default（各组件保持自身默认尺寸），无需显式声明；
• 紧凑表单：后台管理系统中信息密度较高的查询表单，推荐FormSize.Small，可显著提升单屏可见字段数；
• 局部覆盖：由于级联参数本质上是FormSize?，单个组件若在级联值之外显式设置了自身Size，仍可按组件级 API 单独控制，与表单级Size形成互补；
• 动态切换：如官方示例所示，将Size绑定到模型属性，即可实现运行时无刷新切换尺寸，适合需要"紧凑/舒适"视图模式的场景；
• 第三方控件：向表单内引入非 Ant Design 组件时，请自行设置其尺寸，不要依赖Size联动。

相关源码路径

• 前端
• UI组件
• 设计系统