logo
为了能更好地了解您的商业使用需求,请参与 Ant Design Blazor 商业应用调查,一起建设商业应用社区,为企业系统研发赋能!

Form表单

高性能表单控件,自带数据域管理。包含数据录入、校验以及对应样式。

何时使用

  • 用于创建一个实体或收集信息。
  • 需要对输入的数据类型进行校验时。

Examples

基本的表单数据域控制展示,包含布局、初始化、验证、提交。

expand code expand code

通过 @ref 获取Form引用。

expand code expand code

Form 支持 .NET 8 静态服务端渲染的表单验证,但有如下限制:

  1. 必须设置 Form 的 Name 属性, 另外也支持设置 MethodEnhance (分别对应 EditForm 的 FormNameMethodEnhance)。
  2. 表单组件的属性绑定,必须要用 Model.Field, 不能用 @context.Field
  3. 绑定的 Model 实例,需要标注 [SupplyParameterFromForm] 特性,当有多个表单时,还需要指定 FormName 参数与 Form 的 Name 一致。

注意:

  1. 由于在静态页面失去交互性,支持的输入组件仅限 Input、InputPassword、TextArea、Checkbox、Radio 以及使用 InputFile 的 Upload。其他的输入组件请使用原生 html 元素代替,也欢迎贡献。 2.由于Form组件内部封装了EditForm,因此防伪标记 会默认设置,如需取消请参考文档。
expand code expand code

表单有三种布局。

expand code expand code

通过 RequiredMark 切换必选与可选样式。

expand code expand code

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

expand code expand code

这里演示 FormItem 内有多个元素的使用方式。

这里展示了三种典型场景:

  • Username:输入框后面有描述文案或其他组件,在 FormItem 内只有使用了@bind-Value的组件才会绑定到FormItem,其他组件可任意添加。

  • Address:有两个控件,在 FormItem 内使用两个 <FormItem NoStyle /> 分别绑定对应控件(一个FormItem下只能出现一个使用了@bing-Value的控件),对FormItem使用NoStyle,则FormItem的Grid布局会被忽略,就算主动使用了LabelCol或WrapperCol也不会产生效果。

    这个场景还展示了复杂类型的表单验证,Address 属性是一个包含了两个属性的类型,当级联表单项绑定了它的属性时,会继承这个属性的所有 Attributes,但由于表单未绑定这个属性,外部表单无法获取 Required 和 Label。

  • BirthDate:有两个内联控件,错误信息展示各自控件下,使用两个 <FormItem /> 分别绑定对应控件,并修改 style 使其内联布局。

更复杂的封装复用方式可以参考下面的 自定义表单控件

expand code expand code

自定义或第三方的表单控件,也可以与 Form 组件一起使用。只要该组件遵循以下的约定:

  • 继承AntInputComponentBase
  • 当需要给控件值(Value)赋值时,改为给CurrentValue赋值(Value和CurrentValue均来自AntInputComponentBase)
  • 详情可参考:参考:如何实现支持Form表单的组件?

Price:

public class Price
{
    public int Number { get; set; }
    public string Currency { get; set; }
}

PriceInput.razor:

@namespace AntDesign.Docs
@inherits AntInputComponentBase<Price>

<span>
    <Input @bind-Value="@Value.Number"
           style="width: 100px" />
  
    <RadioGroup @bind-Value="@Value.Currency"
                style="width: 280px; margin: 0 8px">
        <Radio RadioButton Value=@("rmb")>RMB</Radio>
        <Radio RadioButton Value=@("dollar")>Dollar</Radio>
    </RadioGroup>
</span>
expand code expand code

支持使用表格作为表单组件,并验证单元格编辑。

expand code expand code

通过 IForm.IsModified 判断表单修改。

expand code expand code

使用Form Validator属性或<Validator>元素设置自定义验证器,会覆盖内置验证器。当不需要验证时,可以设置为 null 来提高表单的性能。

注意:使用<Validator>元素设置验证器时,需要将Form内其他组件用<ChildContent>包起来。

自定义验证组件开发见文档:ASP.NET Core Blazor 窗体和验证 - 验证器组件

expand code expand code

默认会尝试从内置的全球化资源文件中获取验证信息模板,这个语言包可以通过 Locale 统一替换。也可通过 数据声明特性 的 ErrorMessage 、Rules 的 Message 来修改。

另外,也支持 数据声明特性(DataAnnotations)的本地化方式。 当 FormItem.Label 未指定时,会自动从 DisplayAttributeDisplayNameAttribute 获取。

expand code expand code

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

expand code expand code

使用 FormItem.Name 动态绑定模型属性,支持模型对象和字典。

expand code expand code

绑定字典可以不必事先定义属性,因此能够方便地实现动态表单。

expand code expand code

可通过 TModel 类型自动生成表单元素。当前支持string、DateTime、number、enum类型成员自动生成,根据成员是否为可空控制是否为必填

注意: 此功能正在迭代中,后续本版可能会存在不兼容的变更。

expand code expand code

(v0.5+)为了性能考虑,默认关闭内容变更验证,在调用 form.Validate() 时才验证。使用 ValidateOnChange 属性可开启。

expand code expand code

使用ColLayoutParam对列宽度自定义设置

expand code expand code

表单的验证模式,包括:默认、Rules、混合。

使用Rules模式可以直接在FormItem上附加验证特性, 适用场景:需要复用model类,但不同的页面有不同的验证规则,采用Rules模式可以避免重复创建多个类似的model类

expand code expand code

根据不同情况执行不同的校验规则。

expand code expand code

我们提供了 validateStatus help hasFeedback 等属性,你可以不通过 Form 自己定义校验的时机和内容。

  1. validateStatus: 校验状态,可选 'success', 'warning', 'error', 'validating'。
  2. hasFeedback:用于给输入框添加反馈图标。
  3. help:设置校验文案。
expand code expand code

字段无效时,显示字段级错误指示器。此指示器将在表单验证时显示。

expand code expand code

可在任何时候设置验证信息。

expand code expand code

Form API#

属性 描述 类型 默认值
RequiredMark 属性更改必填/可选字段标签在表单上的显示方式。
  • Required - 将标记必填字段
  • Optional - 将标记可选字段
  • None - 将不标记任何字段,无论是必填还是可选
FormRequiredMark --
Layout 属性表单中表单项的布局 String FormLayout.Horizontal
ChildContent 属性表格的内容。通常包含不同的表单输入和布局元素。 RenderFragment<TModel> --
LabelCol 属性控制标签的布局。通常用于为不同的屏幕尺寸设置宽度。 ColLayoutParam --
LabelAlign 属性将标签向左或向右对齐 AntLabelAlignType? --
LabelColSpan 属性获取/设置 AntDesign.Form`1.LabelColSpan 属性。 OneOf<String, Int32> --
LabelColOffset 属性获取/设置 AntDesign.Form`1.LabelColOffset 属性。 OneOf<String, Int32> --
WrapperCol 属性控制输入​​元素包装器的布局。通常用于为不同的屏幕尺寸设置宽度。 ColLayoutParam --
WrapperColSpan 属性获取/设置 AntDesign.Form`1.WrapperColSpan 属性。 OneOf<String, Int32> --
WrapperColOffset 属性获取/设置 AntDesign.Form`1.WrapperColOffsetOffset 属性。 OneOf<String, Int32> --
Size 属性表单内ant组件的大小 String --
Name 属性获取或设置表单处理程序名称。这是将其发布到服务器端终端节点所必需的。或者使用 for 从 FormProviderFinishEventArgs 获取表单实例。 String --
Method 属性用于提交表单的 Http 方法 String --
Model 属性将表单输入绑定到的模型 TModel --
Loading 属性表单是否正在加载 Boolean false
OnFinish 属性提交表单并通过验证时执行的回调。 EventCallback<EditContext> --
OnFinishFailed 属性提交表单且验证失败时执行的回调。 EventCallback<EditContext> --
OnFieldChanged 属性当表单中的字段更改时执行的回调 EventCallback<FieldChangedEventArgs> --
OnValidationRequested 属性请求验证时执行的回调 EventCallback<ValidationRequestedEventArgs> --
OnValidationStateChanged 属性验证更改时执行的回调 EventCallback<ValidationStateChangedEventArgs> --
Validator 属性在表单中使用的验证器。当 AntDesign.Form`1.ValidateModeFormValidateMode.DefaultFormValidateMode.Complex 时使用 RenderFragment --
ValidateOnChange 属性组件值更改时启用验证 Boolean --
ValidateMode 属性表单应使用哪种验证模式将同时使用 attributes 和 rules。

Obsolete 将在未来的版本中删除。
FormValidateMode FormValidateMode.Complex
Enhance 属性如果启用,则无需完全重新加载页面即可执行表单提交。这相当于将 data-enhance 添加到表单中。 Boolean --
Autocomplete 属性默认情况下,input 元素是否可以由浏览器自动完成其值 String --
Locale 属性本地化选项 FormLocale --
IsModified 指示表单是否已修改的标志 Boolean --
EditContext 在表单中获取 AntDesign.Form'1.EditContext 实例 EditContext --
Id 属性组件 HTML 的 ID String Uniquely Generated ID
Class 属性为 DOM 元素指定一个或多个类名。 String --
Style 属性指定 DOM 元素的内联样式。 String --
RefBack 属性一个 ForwardRef 实例。您可以使用 AntDesign.ForwardRef.Current 获取对内部 DOM 的引用。 ForwardRef --
方法签名 返回类型 描述
Reset() void 重置表单中的所有值
Submit() void 提交表格。将触发验证和 AntDesign.Form`1.OnFinishAntDesign.Form`1.OnFinishFailed
Validate() Boolean 执行验证
ValidationReset() void 重置验证
SetValidationMessages(String field, String[] errorMessages) void 将验证消息设置为特定字段。

FormValidateMode API#

基础类型: Int32

名称 描述
Default 验证将来自提供给 AntDesign.Form`1.Model 的模型上的数据属性
Rules 验证将来自表单中 FormItems 的规则
Complex 同时使用默认模式和规则模式

FormItem API#

属性 描述 类型 默认值
Name 属性指定表单项的名称。它也可以用作 Member Path 来绑定 Model 的属性。 String --
ChildContent 属性表单项的内容。通常将包含输入元素之一 RenderFragment --
Label 属性项目的自定义标签。如果未提供 AntDesign.FormItem.LabelAntDesign.FormItem.LabelTemplate,则将使用 DisplayName 属性值或字段名称(按此顺序)。 String --
LabelTemplate 属性项目的自定义标签内容。优先于 AntDesign.FormItem.Label。如果未提供 AntDesign.FormItem.LabelAntDesign.FormItem.LabelTemplate,则将使用 DisplayName 属性值或字段名称(按此顺序)。 RenderFragment --
LabelCol 属性控制标签的布局。通常用于为不同的屏幕尺寸设置宽度。 ColLayoutParam --
LabelAlign 属性将标签向左或向右对齐 AntLabelAlignType? --
LabelColSpan 属性获取/设置 AntDesign.FormItem.LabelColSpan 属性。 OneOf<String, Int32> --
LabelColOffset 属性获取/设置 AntDesign.FormItem.LabelColOffset 属性。 OneOf<String, Int32> --
WrapperCol 属性控制输入​​元素包装器的布局。通常用于为不同的屏幕尺寸设置宽度。 ColLayoutParam --
WrapperColSpan 属性获取/设置 AntDesign.FormItem.WrapperColSpan 属性。 OneOf<String, Int32> --
WrapperColOffset 属性获取/设置 AntDesign.FormItem.WrapperColOffset 上的 Offset 属性。 OneOf<String, Int32> --
NoStyle 属性true时无样式,用作纯字段控件 Boolean --
Required 属性将此项目标记为验证所需 Boolean --
LabelStyle 属性仅应用于标签元素的样式。如果设置了 LabelTemplate,则不会应用。 String --
Rules 属性应用于此项目的验证规则 FormValidationRule[] --
HasFeedback 属性AntDesign.FormItem.ValidateStatus 配合使用,显示验证状态图标。建议仅与 Input 组件一起使用 Boolean --
ShowFeedbackOnError 属性是否在出错时显示反馈图标。如果设置为 false,则即使字段处于错误状态,它也不会显示图标。 Boolean --
ValidateStatus 属性验证状态,不设置则根据验证规则自动生成 FormValidateStatus --
Help 属性提示信息 String --
ToolTip 属性设置表单字段的帮助提示信息 String --
Id 属性组件 HTML 的 ID String Uniquely Generated ID
Class 属性为 DOM 元素指定一个或多个类名。 String --
Style 属性指定 DOM 元素的内联样式。 String --
RefBack 属性一个 ForwardRef 实例。您可以使用 AntDesign.ForwardRef.Current 获取对内部 DOM 的引用。 ForwardRef --

FormValidationRule API#

属性 描述 类型 默认值
Len 验证长度。有效的 AntDesign.FormValidationRule.Type:字符串、数字或数组。 Decimal? --
Min 验证长度是否大于或等于此数字。有效的 AntDesign.FormValidationRule.Type:字符串、数字或数组。 Decimal? --
Max 验证长度是否小于或等于此数字。有效的 AntDesign.FormValidationRule.Type:字符串、数字或数组。 Decimal? --
Required 填写必填字段 Boolean? --
Pattern 验证值是否传递正则表达式模式 String --
Message 自定义错误信息。如果没有提供,将自动生成。 String --
Range 验证值是否在指定范围内 ValueTuple<Double, Double?? --
DefaultField 验证所有数组元素的规则。有效的 AntDesign.FormValidationRule.Type:数组。 (现在不支持 FormItem FormValidationRule --
OneOf 该值是否在指定值内 Object[] --
Enum 验证该值是否在指定的枚举类型中。 Type --
Fields 验证子元素的规则。有效的 AntDesign.FormValidationRule.Type:数组、对象(现在不支持 FormItem Dictionary<Object, FormValidationRule> --
Validator 自定义验证函数 Func<FormValidationContext, ValidationResult> --
Transform 在执行验证之前调用的转换函数。返回值将对其运行验证。 Func<Object, Object> --
Type 表单域的类型。有关所有可能的值,请参阅 FormFieldType FormFieldType? --
ValidationAttribute 使用指定的属性验证值。 ValidationAttribute --

FormValidateErrorMessages API#

属性 描述 类型 默认值
Default 默认通用验证错误消息 String --
Required Required 规则的默认验证消息 String --
Enum Enum 规则的默认验证消息 String --
Whitespace 空白规则的默认验证消息 String --
Date 日期类型的消息 DateMessage --
Types 字段类型与预期类型不匹配时的消息 TypesMessage --
String 字符串类型的消息 CompareMessage --
Number 字符串类型的消息 CompareMessage --
Array 数组类型的消息 CompareMessage --
Pattern 模式验证规则的消息 PatternMessage --
DatePicker日期选择框 Input输入框
文档已更新,请点击 此处 更新。
A new version of this app is available. Click here to update.