diff --git a/components/form/demo/index.vue b/components/form/demo/index.vue index 94ccf4028..fa60eab28 100644 --- a/components/form/demo/index.vue +++ b/components/form/demo/index.vue @@ -39,6 +39,11 @@ const md = { cn: `# Form 表单 具有数据收集、校验和提交功能的表单,包含复选框、单选框、输入框、下拉选择框等元素。 +## 何时使用 + +- 用于创建一个实体或收集信息。 +- 需要对输入的数据类型进行校验时。 + ## 表单 我们为 \`form\` 提供了以下三种排列方式: @@ -65,7 +70,12 @@ const md = { us: `# Form Form is used to collect, validate, and submit the user input, usually contains various form items including checkbox, radio, input, select, and etc. -## Form +## When to use + +- When you need to create a instance or collect information. +- When you need to validate fields in certain rules. + +## Form Component You can align the controls of a \`form\` using the \`layout\` prop: @@ -73,10 +83,9 @@ You can align the controls of a \`form\` using the \`layout\` prop: - \`vertical\`:to vertically align the \`label\`s and controls of the fields. - \`inline\`:to render form fields in one line. -## Form fields +## Form Item Component -A form consists of one or more form fields whose type includes input, textarea, checkbox, radio, select, tag, and more. -A form field is defined using \`\`. +A form consists of one or more form fields whose type includes input, textarea, checkbox, radio, select, tag, and more. A form field is defined using \`\`. ## Note: 1. If you use \`Form.create\` to process the form to have the ability to automatically collect data and verify it, it is recommended to use \`jsx\`. diff --git a/components/form/index.en-US.md b/components/form/index.en-US.md index a4febf4e1..7c4512288 100644 --- a/components/form/index.en-US.md +++ b/components/form/index.en-US.md @@ -2,15 +2,17 @@ ### Form -| Property | Description | Type | Default Value | -| --- | --- | --- | --- | -| form | Decorated by `Form.create()` will be automatically set `this.form` property, so just pass to form. If you use the template syntax, you can use `this.$form.createForm(this, options)` | object | n/a | -| hideRequiredMark | Hide required mark of all form items | Boolean | false | -| layout | Define form layout | 'horizontal'\|'vertical'\|'inline' | 'horizontal' | -| labelCol | The layout of label. You can set `span` `offset` to something like `{span: 3, offset: 12}` or `sm: {span: 3, offset: 12}` same as with `` | [object](/components/grid/#Col) | | -| wrapperCol | The layout for input controls, same as `labelCol` | [object](/components/grid/#Col) | | -| autoFormCreate(deprecated) | Automate Form.create, Recommended for use under the `template` component, and cannot be used with `Form.create()`. You should use `$form.createForm` to instead it after 1.1.9. | Function(form) | | -| options(deprecated) | The `options` corresponding to `Form.create(options)`. You should use `$form.createForm` to instead it after 1.1.9. | Object | {} | +| Property | Description | Type | Default Value | Version | +| --- | --- | --- | --- | --- | +| form | Decorated by `Form.create()` will be automatically set `this.form` property, so just pass to form. If you use the template syntax, you can use `this.$form.createForm(this, options)` | object | n/a | | +| hideRequiredMark | Hide required mark of all form items | Boolean | false | | +| layout | Define form layout | 'horizontal'\|'vertical'\|'inline' | 'horizontal' | | +| labelAlign | text align of label of all items | 'left' \| 'right' | 'right' | 1.5.0 | +| labelCol | The layout of label. You can set `span` `offset` to something like `{span: 3, offset: 12}` or `sm: {span: 3, offset: 12}` same as with `` | [object](/components/grid/#Col) | | | +| wrapperCol | The layout for input controls, same as `labelCol` | [object](/components/grid/#Col) | | | +| autoFormCreate(deprecated) | Automate Form.create, Recommended for use under the `template` component, and cannot be used with `Form.create()`. You should use `$form.createForm` to instead it after 1.1.9. | Function(form) | | | +| options(deprecated) | The `options` corresponding to `Form.create(options)`. You should use `$form.createForm` to instead it after 1.1.9. | Object | {} | 1.1.9 | +| colon | change default props colon value of Form.Item (only effective when prop layout is horizontal) | boolean | true | 1.5.0 | ### Events @@ -173,17 +175,19 @@ After wrapped by `getFieldDecorator` or `v-decorator`, `value`(or other property Note: If Form.Item has multiple children that had been decorated by `getFieldDecorator` or `v-decorator`, `help` and `required` and `validateStatus` can't be generated automatically. -| Property | Description | Type | Default Value | -| --- | --- | --- | --- | -| colon | Used with `label`, whether to display `:` after label text. | boolean | true | -| extra | The extra prompt message. It is similar to help. Usage example: to display error message and prompt message at the same time. | string\|slot | | -| hasFeedback | Used with `validateStatus`, this option specifies the validation status icon. Recommended to be used only with `Input`. | boolean | false | -| help | The prompt message. If not provided, the prompt message will be generated by the validation rule. | string\|slot | | -| label | Label text | string\|slot | | -| labelCol | The layout of label. You can set `span` `offset` to something like `{span: 3, offset: 12}` or `sm: {span: 3, offset: 12}` same as with `` | [object](/components/grid/#Col) | | -| required | Whether provided or not, it will be generated by the validation rule. | boolean | false | -| validateStatus | The validation status. If not provided, it will be generated by validation rule. options: 'success' 'warning' 'error' 'validating' | string | | -| wrapperCol | The layout for input controls, same as `labelCol` | [object](/components/grid/#Col) | | +| Property | Description | Type | Default Value | Version | +| --- | --- | --- | --- | --- | +| colon | Used with `label`, whether to display `:` after label text. | boolean | true | | +| extra | The extra prompt message. It is similar to help. Usage example: to display error message and prompt message at the same time. | string\|slot | | | +| hasFeedback | Used with `validateStatus`, this option specifies the validation status icon. Recommended to be used only with `Input`. | boolean | false | | +| help | The prompt message. If not provided, the prompt message will be generated by the validation rule. | string\|slot | | | +| htmlFor | Set sub label `htmlFor`. | string | | 1.5.0 | +| label | Label text | string\|slot | | | +| labelCol | The layout of label. You can set `span` `offset` to something like `{span: 3, offset: 12}` or `sm: {span: 3, offset: 12}` same as with `` | [object](/components/grid/#Col) | | | +| labelAlign | text align of label | 'left' \| 'right' | 'right' | 1.5.0 | +| required | Whether provided or not, it will be generated by the validation rule. | boolean | false | | +| validateStatus | The validation status. If not provided, it will be generated by validation rule. options: 'success' 'warning' 'error' 'validating' | string | | | +| wrapperCol | The layout for input controls, same as `labelCol` | [object](/components/grid/#Col) | | | ### Validation Rules diff --git a/components/form/index.zh-CN.md b/components/form/index.zh-CN.md index 209f8b9a9..9202559e5 100644 --- a/components/form/index.zh-CN.md +++ b/components/form/index.zh-CN.md @@ -2,14 +2,16 @@ ### Form -| 参数 | 说明 | 类型 | 默认值 | -| --- | --- | --- | --- | -| form | 经 `Form.create()` 包装过的组件会自带 `this.form` 属性,如果使用 template 语法,可以使用 this.\$form.createForm(this, options) | object | 无 | -| hideRequiredMark | 隐藏所有表单项的必选标记 | Boolean | false | -| layout | 表单布局 | 'horizontal'\|'vertical'\|'inline' | 'horizontal' | -| labelCol | label 标签布局,同 `` 组件,设置 `span` `offset` 值,如 `{span: 3, offset: 12}` 或 `sm: {span: 3, offset: 12}` | [object](/components/grid-cn/#Col) | | -| wrapperCol | 需要为输入控件设置布局样式时,使用该属性,用法同 labelCol | [object](/components/grid-cn/#Col) | | -| selfUpdate | 自定义字段更新逻辑,说明[见下](/components/form-cn/#selfUpdate),需 1.3.17 版本以上 | boolean | false | +| 参数 | 说明 | 类型 | 默认值 | 版本 | +| --- | --- | --- | --- | --- | +| form | 经 `Form.create()` 包装过的组件会自带 `this.form` 属性,如果使用 template 语法,可以使用 this.\$form.createForm(this, options) | object | 无 | | +| hideRequiredMark | 隐藏所有表单项的必选标记 | Boolean | false | | +| labelAlign | label 标签的文本对齐方式 | 'left' \| 'right' | 'right' | 1.5.0 | +| layout | 表单布局 | 'horizontal'\|'vertical'\|'inline' | 'horizontal' | | +| labelCol | label 标签布局,同 `` 组件,设置 `span` `offset` 值,如 `{span: 3, offset: 12}` 或 `sm: {span: 3, offset: 12}` | [object](/components/grid-cn/#Col) | | | +| wrapperCol | 需要为输入控件设置布局样式时,使用该属性,用法同 labelCol | [object](/components/grid-cn/#Col) | | | +| selfUpdate | 自定义字段更新逻辑,说明[见下](/components/form-cn/#selfUpdate),需 1.3.17 版本以上 | boolean | false | 1.3.17 | +| colon | 配置 Form.Item 的 colon 的默认值 (只有在属性 layout 为 horizontal 时有效) | boolean | true | 1.5.0 | ### 事件 @@ -171,18 +173,20 @@ validateFields(['field1', 'field2'], options, (errors, values) => { 注意:一个 Form.Item 建议只放一个被 getFieldDecorator 或 v-decorator 装饰过的 child,当有多个被装饰过的 child 时,`help` `required` `validateStatus` 无法自动生成。 -| 参数 | 说明 | 类型 | 默认值 | -| --- | --- | --- | --- | -| colon | 配合 label 属性使用,表示是否显示 label 后面的冒号 | boolean | true | -| extra | 额外的提示信息,和 help 类似,当需要错误信息和提示文案同时出现时,可以使用这个。 | string\|slot | | -| hasFeedback | 配合 validateStatus 属性使用,展示校验状态图标,建议只配合 Input 组件使用 | boolean | false | -| help | 提示信息,如不设置,则会根据校验规则自动生成 | string\|slot | | -| label | label 标签的文本 | string\|slot | | -| labelCol | label 标签布局,同 `` 组件,设置 `span` `offset` 值,如 `{span: 3, offset: 12}` 或 `sm: {span: 3, offset: 12}` | [object](/components/grid-cn/#Col) | | -| required | 是否必填,如不设置,则会根据校验规则自动生成 | boolean | false | -| validateStatus | 校验状态,如不设置,则会根据校验规则自动生成,可选:'success' 'warning' 'error' 'validating' | string | | -| wrapperCol | 需要为输入控件设置布局样式时,使用该属性,用法同 labelCol | [object](/components/grid-cn/#Col) | | -| selfUpdate | 自定义字段更新逻辑,你可以通过 Form 的 selfUpdate 进行统一设置。当和 Form 同时设置时,以 Item 为准。 说明[见下](/components/form-cn/#selfUpdate) 需 1.3.17 版本以上 | boolean | false | +| 参数 | 说明 | 类型 | 默认值 | 版本 | +| --- | --- | --- | --- | --- | +| colon | 配合 label 属性使用,表示是否显示 label 后面的冒号 | boolean | true | | +| extra | 额外的提示信息,和 help 类似,当需要错误信息和提示文案同时出现时,可以使用这个。 | string\|slot | | | +| hasFeedback | 配合 validateStatus 属性使用,展示校验状态图标,建议只配合 Input 组件使用 | boolean | false | | +| help | 提示信息,如不设置,则会根据校验规则自动生成 | string\|slot | | | +| htmlFor | 设置子元素 label `htmlFor` 属性 | string | | 1.5.0 | +| label | label 标签的文本 | string\|slot | | | +| labelCol | label 标签布局,同 `` 组件,设置 `span` `offset` 值,如 `{span: 3, offset: 12}` 或 `sm: {span: 3, offset: 12}` | [object](/components/grid-cn/#Col) | | | +| labelAlign | 标签文本对齐方式 | 'left' \| 'right' | 'right' | 1.5.0 | +| required | 是否必填,如不设置,则会根据校验规则自动生成 | boolean | false | | +| validateStatus | 校验状态,如不设置,则会根据校验规则自动生成,可选:'success' 'warning' 'error' 'validating' | string | | | +| wrapperCol | 需要为输入控件设置布局样式时,使用该属性,用法同 labelCol | [object](/components/grid-cn/#Col) | | | +| selfUpdate | 自定义字段更新逻辑,你可以通过 Form 的 selfUpdate 进行统一设置。当和 Form 同时设置时,以 Item 为准。 说明[见下](/components/form-cn/#selfUpdate) 需 1.3.17 版本以上 | boolean | false | 1.3.17 | ### 校验规则 diff --git a/types/form/form-item.d.ts b/types/form/form-item.d.ts index 5d06684b8..37d91331c 100644 --- a/types/form/form-item.d.ts +++ b/types/form/form-item.d.ts @@ -62,4 +62,7 @@ export declare class FormItem extends AntdComponent { * @type Col */ wrapperCol: Col; + colon: boolean; + labelAlign: 'left' | 'right'; + selfUpdate: boolean; } diff --git a/types/form/form.d.ts b/types/form/form.d.ts index 1cd0b8851..11cd388ab 100644 --- a/types/form/form.d.ts +++ b/types/form/form.d.ts @@ -390,6 +390,9 @@ export declare class Form extends AntdComponent { * @param field */ createFormField(field: any): any; + colon: boolean; + labelAlign: 'left' | 'right'; + selfUpdate: boolean; } declare module 'vue/types/vue' {