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

Form表单

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

何时使用

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

Examples

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

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

通过 @ref 获取Form引用。

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 属性表单中表单项的布局 FormLayout 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组件的大小 FormSize? --
Name 属性获取或设置表单处理程序名称。这是将其发布到服务器端终端节点所必需的。或者使用 for 从 FormProviderFinishEventArgs 获取表单实例。 String --
Method 属性用于提交表单的 Http 方法 HttpMethod --
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.