ant-design/components/form/index.en-US.md

370 lines
18 KiB
Markdown
Raw Normal View History

2016-07-31 09:53:51 +08:00
---
category: Components
type: Data Entry
2016-07-31 09:53:51 +08:00
cols: 1
2016-09-21 11:28:38 +08:00
title: Form
cover: https://gw.alipayobjects.com/zos/alicdn/ORmcdeaoO/Form.svg
2016-07-31 09:53:51 +08:00
---
High performance Form component with data scope management. Including data collection, verification, and styles.
2016-07-31 09:53:51 +08:00
## When to use
2020-02-23 01:26:35 +08:00
- When you need to create an instance or collect information.
- When you need to validate fields in certain rules.
2016-07-31 09:53:51 +08:00
## API
### Form
| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| component | Set the Form rendering element. Do not create a DOM node for `false` | ComponentType \| false | form | |
| colon | Configure the default value of `colon` for Form.Item. Indicates whether the colon after the label is displayed (only effective when prop layout is horizontal) | boolean | true | |
| fields | Control of form fields through state management (such as redux). Not recommended for non-strong demand. View [example](#components-form-demo-global-state) | [FieldData](#FieldData)\[] | - | |
| form | Form control instance created by `Form.useForm()`. Automatically created when not provided | [FormInstance](#FormInstance) | - | |
| hideRequiredMark | Hide required mark for all form items | boolean | false | |
| initialValues | Set value by Form initialization or reset | object | - | |
| labelAlign | The text align of label of all items | `left` \| `right` | `right` | |
| labelCol | Label layout, like `<Col>` component. Set `span` `offset` value like `{span: 3, offset: 12}` or `sm: {span: 3, offset: 12}` | [object](/components/grid/#Col) | - | |
| layout | Form layout | `horizontal` \| `vertical` \| `inline` | `horizontal` | |
| name | Form name. Will be the prefix of Field `id` | string | - | |
merge master into Feature (#25262) * feat: add successColor for Progress (#24655) * feat: add successColor for Progress * feat: update * fix: update test * remove snap * feat: add test case * refactor success * feat: adjust styyle * feat: add DevWarning * feat: Support rowSelection.dirty (#24718) * feat: Support rowSelection.dirty * rename to reserveKeys * preserveKeys will keep record also * to preserveSelectedRowKeys * feat: add ghost prop for collapse (#24734) * feat: add ghost prop for collapse * doc: version of collapse's ghost prop * refactor: make ghost collapse's less code to a nested style * chore: remove redundant codes in ghost collapse's less & doc * doc: add a background wrapper for ghost collapse demo * doc: dark-theme wrapper bg-color for ghost collapse demo * test: update snapshot of ghost collapse * doc: use softer bg-color on ghost collapse demo * doc: remove disabled panel in ghost collapse demo * feat: form instance support getFieldInstance (#24711) * support getFieldInstance * update doc * fix lint * move func * move into hooks * update ref logic * fix lint * rm only * fix docs * feat: dropdown support arrow (#23869) * feat: dropdown support arrow prop close #22758 * test: update snapshot * fix: fix dropdown cls names * test: update snapshot * test: update snapshot * doc: update demo * test: update demo snapshot * demo * fix: snapshot * chore: change the style of ghost collapse & demo modified (#24762) * refactor: reduce content padding in ghost collapse * doc: remove the wrapper outside ghost collapse Designer want the demo differs from other demos * refactor: remove redundant .less code in collapse * feat: cascader dropdown-render prop (#24812) * feat: cascader dropdown-render prop * fix: update Cascader dropdownRender type annotation * fix: set rc-cascader semver from ^ to ~ * docs: fix coding style in cascader/custom-dropdown * feat: 🆕 support Drawer closeIcon (#24842) * feat: :new: support Drawer closeIcon close #19283 close #19153 * add test case * update docs * feat: 🆕 Cascader expandIcon (#24865) * feat: cascader expandIcon * fix: snap * refactor: reduce CSS size (#24846) * refactor: reduce button css size * refactor: remove redundant button .less code * feat: add Table onChange an action param (#24697) * Working on tests * created TableAction type * changed TableActions to tuple * removed chinese documentation line * refactor TableActions * fix documentation * Moved action into extra param * minor doc change * feat: add closeIcon customize tag close (#24885) * feat: add closeIcon customize tag close * docs fix * update snap * fix: css name * update snapshot * snapshot * feat: add radio `optionType` api to set radio option type (#24809) * feat: radio component * docs: update md * fix: snap * test components * fix: use optionType * fix name * add warning * fix * feat: expand rate character (#24903) * feat: expand rate character * fix: demo * fix: snap * Update components/rate/index.zh-CN.md Co-authored-by: 偏右 <afc163@gmail.com> * fix Co-authored-by: 偏右 <afc163@gmail.com> * Refactor demo code box actions (#24887) * refactor: refine the styling of actions part of demo code-box * fix: lint style * refactor: move Result children to end (#24945) * feat: remove content max-width on dot-step (#24907) * feat: add Skeleton-Image (#24805) * feat: add Skeleton-Image * feat: add docs * fix: adjust skeleton * feat: adjust Image Component * feat: rebase * feat: adjust style * fix: lint * feat: remove size * feat: delete md * feat: fix style * ✨ feat: Mentions support autoSize (#24961) close #17746 * chore: replace textarea with rc-textarea (#24966) * feat: update pagination@2.3.0 support onChange called when pageSize change (#24964) * feat: update pagination@2.5.0 and add test case to relative component * fix: lint * delete * feat: add test case for pagination * adjust test case * feat: Implement centered prop in Tabs (#24958) * Implement centered in Tabs along with its tests and docs * Fix build error * Add Chinese translations and remove test case Co-authored-by: Ashkan Pourghasem <ashkan.pourghasem@gmail.com> * feat: Add modal style parameter (#24773) * add some paramters in default.less * Update components/style/themes/default.less Co-authored-by: Amumu <yoyo837@hotmail.com> * change parameter in compact.less Co-authored-by: Crystal Gao <jinggao@ebay.com> Co-authored-by: Amumu <yoyo837@hotmail.com> * feat: export Tabs addIcon (#25006) * feat: export Tabs addIcon * update snapshot * feat: showNow on timepicker and datetimepicker (#25032) * feat: update rc-picker@1.7.1 and fix icons of month and quarter picker in DatePicker Component (#25035) * feat: update rc-picker@1.7.1 * delete * add * feat: expand rate support props (#24993) * docs: :memo: Add Form.Item hidden in doc (#25108) close #25101 * fix: ⌨️ Improve Pagination accessibility issue (#25119) * ⌨️ Improve Pagination a11y by fixing a W3C error https://github.com/react-component/pagination/issues/280 * update snapshot * :up: rc-pagination to 2.4.1 * feat: support triggerSubMenuAction for <Menu /> (#25127) * feat(menu): add triggerSubMenuAction for Menu * feat(menu): test cases * chore: Adjust picker logic (#25135) * chore: update rc-picker 1.10.0 (#25174) * feat: table row check strictly (#24931) * feat: add checkStrictly on Table.rowSelection * fix: LGTM warnings * test: table rowSelection.checkStrictly * test: add cov [wip] * refactor: tree.rowSelection.checkStrictly [wip] * test: table.rowSelection.checkStrictly basic case * feat: support rowKey on checkStrictly table * feat: Table checkStrictly support getCheckboxProps * docs: Table checkStrictly * chore: typo * chore: remove useless comment * chore: update snapshot * chore: update snapshot * fix: fire selectAll on selection dropdown menu & changeRows incorrect in selectAll callback * docs: typo * chore * chore * fix: expand buttons of leaf rows in tree data are not hidden * feat: Table warning about rowKey index parameter * perf: only generate keyEntities when not checkStrictly * refactor: remove useless parseCheckedKeys * refactor: get derived selected & half selected keys from selectedRowKeys * chore: remove env condition stmt * chore: revert index usage & code formatting * chore: rerun ci * docs: table tree-data checkstrictly * test: update snapshots * refactor: use useMergedState hook * chore: rerun ci * chore: rerun ci 2 * chore: revert selection select all behavior * refactor: refactor code based on feature * chore: revert table code format * chore: revert table code format * fix: useMemo deps * fix: useMemo deps * fix: useMemo deps * feat: support preserve (#25186) * docs: add responsibly order for Col (#25139) * feat: add type * feat: add responsibly order cols * feat: add docs * feat: add test case * fix test Co-authored-by: 二货机器人 <smith3816@gmail.com> Co-authored-by: 偏右 <afc163@gmail.com> Co-authored-by: zoomdong <1344492820@qq.com> Co-authored-by: 07akioni <07akioni2@gmail.com> Co-authored-by: wendellhu <wendellhu95@gmail.com> Co-authored-by: xrkffgg <xrkffgg@gmail.com> Co-authored-by: Neto Braghetto <netow93@gmail.com> Co-authored-by: Kermit Xuan <kermitlx@outlook.com> Co-authored-by: Ashkan Pourghasem <64011067+ashkan-pm@users.noreply.github.com> Co-authored-by: Ashkan Pourghasem <ashkan.pourghasem@gmail.com> Co-authored-by: hicrystal <295247343@qq.com> Co-authored-by: Crystal Gao <jinggao@ebay.com> Co-authored-by: Amumu <yoyo837@hotmail.com> Co-authored-by: Li Ming <armyiljfe@gmail.com>
2020-06-28 22:41:59 +08:00
| preserve | Keep field value even when field removed | boolean | true | 4.4.0 |
| scrollToFirstError | Auto scroll to first failed field when submit | boolean | false | |
| size | Set field component size (antd components only) | `small` \| `middle` \| `large` | - | |
| validateMessages | Validation prompt template, description [see below](#validateMessages) | [ValidateMessages](https://github.com/react-component/field-form/blob/master/src/utils/messages.ts) | - | |
| validateTrigger | Config field validate trigger | string \| string[] | `onChange` | 4.3.0 |
| wrapperCol | The layout for input controls, same as `labelCol` | [object](/components/grid/#Col) | - | |
| onFinish | Trigger after submitting the form and verifying data successfully | function(values) | - | |
| onFinishFailed | Trigger after submitting the form and verifying data failed | function({ values, errorFields, outOfDate }) | - | |
| onFieldsChange | Trigger when field updated | function(changedFields, allFields) | - | |
| onValuesChange | Trigger when value updated | function(changedValues, allValues) | - | |
### validateMessages
2020-02-23 01:26:35 +08:00
Form provides [default verification error messages](https://github.com/react-component/field-form/blob/master/src/utils/messages.ts). You can modify the template by configuring `validateMessages` property. A common usage is to configure localization:
2016-07-31 09:53:51 +08:00
```jsx
const validateMessages = {
required: "'${name}' is required!",
// ...
};
2016-07-31 09:53:51 +08:00
<Form validateMessages={validateMessages} />;
```
Besides, [ConfigProvider](/components/config-provider/) also provides a global configuration scheme that allows for uniform configuration error notification templates:
2016-07-31 09:53:51 +08:00
```jsx
const validateMessages = {
required: "'${name}' is Required!",
// ...
};
2016-07-31 09:53:51 +08:00
<ConfigProvider form={{ validateMessages }}>
<Form />
</ConfigProvider>;
2016-07-31 09:53:51 +08:00
```
## Form.Item
2016-07-31 09:53:51 +08:00
Form field component for data bidirectional binding, validation, layout, and so on.
2020-04-07 20:43:19 +08:00
| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| colon | Used with `label`, whether to display `:` after label text. | boolean | true | |
| dependencies | Set the dependency field. See [below](#dependencies) | [NamePath](#NamePath)[] | - | |
| extra | The extra prompt message. It is similar to help. Usage example: to display error message and prompt message at the same time | string \| ReactNode | - | |
2020-04-07 20:43:19 +08:00
| getValueFromEvent | Specify how to get value from event or other onChange arguments | (..args: any[]) => any | - | |
| getValueProps | Additional props with sub component | (value: any) => any | - | 4.2.0 |
2020-04-07 20:43:19 +08:00
| 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 \| ReactNode | - | |
2020-04-07 20:43:19 +08:00
| htmlFor | Set sub label `htmlFor` | string | - | |
| initialValue | Config sub default value. Form `initialValues` get higher priority when conflict | string | - | 4.2.0 |
2020-04-07 20:43:19 +08:00
| noStyle | No style for `true`, used as a pure field control | boolean | false | |
| label | Label text | string \| ReactNode | - | |
| labelAlign | The text align of label | `left` \| `right` | `right` | |
2020-04-07 20:43:19 +08:00
| 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 `<Col>`. You can set `labelCol` on Form. If both exists, use Item first | [object](/components/grid/#Col) | - | |
| name | Field name, support array | [NamePath](#NamePath) | - | |
| normalize | Normalize value from component value before passing to Form instance | (value, prevValue, prevValues) => any | - | |
merge master into Feature (#25262) * feat: add successColor for Progress (#24655) * feat: add successColor for Progress * feat: update * fix: update test * remove snap * feat: add test case * refactor success * feat: adjust styyle * feat: add DevWarning * feat: Support rowSelection.dirty (#24718) * feat: Support rowSelection.dirty * rename to reserveKeys * preserveKeys will keep record also * to preserveSelectedRowKeys * feat: add ghost prop for collapse (#24734) * feat: add ghost prop for collapse * doc: version of collapse's ghost prop * refactor: make ghost collapse's less code to a nested style * chore: remove redundant codes in ghost collapse's less & doc * doc: add a background wrapper for ghost collapse demo * doc: dark-theme wrapper bg-color for ghost collapse demo * test: update snapshot of ghost collapse * doc: use softer bg-color on ghost collapse demo * doc: remove disabled panel in ghost collapse demo * feat: form instance support getFieldInstance (#24711) * support getFieldInstance * update doc * fix lint * move func * move into hooks * update ref logic * fix lint * rm only * fix docs * feat: dropdown support arrow (#23869) * feat: dropdown support arrow prop close #22758 * test: update snapshot * fix: fix dropdown cls names * test: update snapshot * test: update snapshot * doc: update demo * test: update demo snapshot * demo * fix: snapshot * chore: change the style of ghost collapse & demo modified (#24762) * refactor: reduce content padding in ghost collapse * doc: remove the wrapper outside ghost collapse Designer want the demo differs from other demos * refactor: remove redundant .less code in collapse * feat: cascader dropdown-render prop (#24812) * feat: cascader dropdown-render prop * fix: update Cascader dropdownRender type annotation * fix: set rc-cascader semver from ^ to ~ * docs: fix coding style in cascader/custom-dropdown * feat: 🆕 support Drawer closeIcon (#24842) * feat: :new: support Drawer closeIcon close #19283 close #19153 * add test case * update docs * feat: 🆕 Cascader expandIcon (#24865) * feat: cascader expandIcon * fix: snap * refactor: reduce CSS size (#24846) * refactor: reduce button css size * refactor: remove redundant button .less code * feat: add Table onChange an action param (#24697) * Working on tests * created TableAction type * changed TableActions to tuple * removed chinese documentation line * refactor TableActions * fix documentation * Moved action into extra param * minor doc change * feat: add closeIcon customize tag close (#24885) * feat: add closeIcon customize tag close * docs fix * update snap * fix: css name * update snapshot * snapshot * feat: add radio `optionType` api to set radio option type (#24809) * feat: radio component * docs: update md * fix: snap * test components * fix: use optionType * fix name * add warning * fix * feat: expand rate character (#24903) * feat: expand rate character * fix: demo * fix: snap * Update components/rate/index.zh-CN.md Co-authored-by: 偏右 <afc163@gmail.com> * fix Co-authored-by: 偏右 <afc163@gmail.com> * Refactor demo code box actions (#24887) * refactor: refine the styling of actions part of demo code-box * fix: lint style * refactor: move Result children to end (#24945) * feat: remove content max-width on dot-step (#24907) * feat: add Skeleton-Image (#24805) * feat: add Skeleton-Image * feat: add docs * fix: adjust skeleton * feat: adjust Image Component * feat: rebase * feat: adjust style * fix: lint * feat: remove size * feat: delete md * feat: fix style * ✨ feat: Mentions support autoSize (#24961) close #17746 * chore: replace textarea with rc-textarea (#24966) * feat: update pagination@2.3.0 support onChange called when pageSize change (#24964) * feat: update pagination@2.5.0 and add test case to relative component * fix: lint * delete * feat: add test case for pagination * adjust test case * feat: Implement centered prop in Tabs (#24958) * Implement centered in Tabs along with its tests and docs * Fix build error * Add Chinese translations and remove test case Co-authored-by: Ashkan Pourghasem <ashkan.pourghasem@gmail.com> * feat: Add modal style parameter (#24773) * add some paramters in default.less * Update components/style/themes/default.less Co-authored-by: Amumu <yoyo837@hotmail.com> * change parameter in compact.less Co-authored-by: Crystal Gao <jinggao@ebay.com> Co-authored-by: Amumu <yoyo837@hotmail.com> * feat: export Tabs addIcon (#25006) * feat: export Tabs addIcon * update snapshot * feat: showNow on timepicker and datetimepicker (#25032) * feat: update rc-picker@1.7.1 and fix icons of month and quarter picker in DatePicker Component (#25035) * feat: update rc-picker@1.7.1 * delete * add * feat: expand rate support props (#24993) * docs: :memo: Add Form.Item hidden in doc (#25108) close #25101 * fix: ⌨️ Improve Pagination accessibility issue (#25119) * ⌨️ Improve Pagination a11y by fixing a W3C error https://github.com/react-component/pagination/issues/280 * update snapshot * :up: rc-pagination to 2.4.1 * feat: support triggerSubMenuAction for <Menu /> (#25127) * feat(menu): add triggerSubMenuAction for Menu * feat(menu): test cases * chore: Adjust picker logic (#25135) * chore: update rc-picker 1.10.0 (#25174) * feat: table row check strictly (#24931) * feat: add checkStrictly on Table.rowSelection * fix: LGTM warnings * test: table rowSelection.checkStrictly * test: add cov [wip] * refactor: tree.rowSelection.checkStrictly [wip] * test: table.rowSelection.checkStrictly basic case * feat: support rowKey on checkStrictly table * feat: Table checkStrictly support getCheckboxProps * docs: Table checkStrictly * chore: typo * chore: remove useless comment * chore: update snapshot * chore: update snapshot * fix: fire selectAll on selection dropdown menu & changeRows incorrect in selectAll callback * docs: typo * chore * chore * fix: expand buttons of leaf rows in tree data are not hidden * feat: Table warning about rowKey index parameter * perf: only generate keyEntities when not checkStrictly * refactor: remove useless parseCheckedKeys * refactor: get derived selected & half selected keys from selectedRowKeys * chore: remove env condition stmt * chore: revert index usage & code formatting * chore: rerun ci * docs: table tree-data checkstrictly * test: update snapshots * refactor: use useMergedState hook * chore: rerun ci * chore: rerun ci 2 * chore: revert selection select all behavior * refactor: refactor code based on feature * chore: revert table code format * chore: revert table code format * fix: useMemo deps * fix: useMemo deps * fix: useMemo deps * feat: support preserve (#25186) * docs: add responsibly order for Col (#25139) * feat: add type * feat: add responsibly order cols * feat: add docs * feat: add test case * fix test Co-authored-by: 二货机器人 <smith3816@gmail.com> Co-authored-by: 偏右 <afc163@gmail.com> Co-authored-by: zoomdong <1344492820@qq.com> Co-authored-by: 07akioni <07akioni2@gmail.com> Co-authored-by: wendellhu <wendellhu95@gmail.com> Co-authored-by: xrkffgg <xrkffgg@gmail.com> Co-authored-by: Neto Braghetto <netow93@gmail.com> Co-authored-by: Kermit Xuan <kermitlx@outlook.com> Co-authored-by: Ashkan Pourghasem <64011067+ashkan-pm@users.noreply.github.com> Co-authored-by: Ashkan Pourghasem <ashkan.pourghasem@gmail.com> Co-authored-by: hicrystal <295247343@qq.com> Co-authored-by: Crystal Gao <jinggao@ebay.com> Co-authored-by: Amumu <yoyo837@hotmail.com> Co-authored-by: Li Ming <armyiljfe@gmail.com>
2020-06-28 22:41:59 +08:00
| preserve | Keep field value even when field removed | boolean | true | 4.4.0 |
| required | Display required style. It will be generated by the validation rule | boolean | false | |
2020-04-07 20:43:19 +08:00
| rules | Rules for field validation. Click [here](#components-form-demo-basic) to see an example | [Rule](#Rule)[] | - | |
| shouldUpdate | Custom field update logic. See [below](#shouldUpdate) | boolean \| (prevValue, curValue) => boolean | false | |
| trigger | When to collect the value of children node | string | `onChange` | |
| validateFirst | Whether stop validate on first rule of error for this field. Will parallel validate when `parallel` cofigured | boolean \| `parallel` | false | `parallel`: 4.5.0 |
| validateStatus | The validation status. If not provided, it will be generated by validation rule. options: `success` `warning` `error` `validating` | string | - | |
| validateTrigger | When to validate the value of children node | string \| string[] | `onChange` | |
| valuePropName | Props of children node, for example, the prop of Switch is 'checked'. This prop is an encapsulation of `getValueProps`, which will be invalid after customizing `getValueProps` | string | `value` | |
2020-04-07 20:43:19 +08:00
| wrapperCol | The layout for input controls, same as `labelCol`. You can set `wrapperCol` on Form. If both exists, use Item first | [object](/components/grid/#Col) | - | |
| hidden | Whether to hide Form.Item (still collect and validate value) | boolean | false | |
After wrapped by `Form.Item` with `name` property, `value`(or other property defined by `valuePropName`) `onChange`(or other property defined by `trigger`) props will be added to form controls, the flow of form data will be handled by Form which will cause:
1. You shouldn't use `onChange` on each form control to **collect data**(use `onValuesChange` of Form), but you can still listen to `onChange`.
2. You cannot set value for each form control via `value` or `defaultValue` prop, you should set default value with `initialValues` of Form. Note that `initialValues` cannot be updated by `setState` dynamiclly, you should use `setFieldsValue` in that situation.
3. You shouldn't call `setState` manually, please use `form.setFieldsValue` to change value programmatically.
### dependencies
2020-02-23 01:26:35 +08:00
Used when there are dependencies between fields. If a field has the `dependencies` prop, this field will automatically trigger updates and validations when upstream is updated. A common scenario is a user registration form with "password" and "confirm password" fields. The "Confirm Password" validation depends on the "Password" field. After setting `dependencies`, the "Password" field update will re-trigger the validation of "Check Password". You can refer [examples](#components-form-demo-register).
`dependencies` shouldn't be used together with `shouldUpdate`. Since it may cause chaos in updating logic.
`dependencies` supports `Form.Item` with render props children since `4.5.0`.
### shouldUpdate
2020-02-23 01:26:35 +08:00
Form updates only the modified field-related components for performance optimization purposes by incremental update. In most cases, you only need to write code or do validation with the [`dependencies`](#dependencies) property. In some specific cases, such as when a new field option appears with a filed value changed, or you just want to keep some area updating by form update, you can modify the update logic of Form.Item via the `shouldUpdate`.
When `shouldUpdate` is `true`, any Form update will cause the Form.Item to be re-rendered. This is very helpful for custom rendering some areas:
```jsx
<Form.Item shouldUpdate>
{() => {
return <pre>{JSON.stringify(form.getFieldsValue(), null, 2)}</pre>;
}}
</Form.Item>
```
2016-07-31 09:53:51 +08:00
You can ref [example](#components-form-demo-horizontal-login) to see detail.
2016-07-31 09:53:51 +08:00
When `shouldUpdate` is a function, it will be called by form values update. Providing original values and current value to compare. This is very helpful for rendering additional fields based on values:
2018-09-12 22:16:53 +08:00
```jsx
<Form.Item shouldUpdate={(prevValues, curValues) => prevValues.additional !== curValues.additional}>
{() => {
return (
<Form.Item name="other">
<Input />
</Form.Item>
);
}}
</Form.Item>
2018-09-12 22:16:53 +08:00
```
You can ref [example](#components-form-demo-control-hooks) to see detail.
## Form.List
Provides array management for fields.
| Property | Description | Type | Default |
2019-05-07 14:57:32 +08:00
| --- | --- | --- | --- |
| name | Field name, support array | [NamePath](#NamePath) | - |
2019-12-31 20:10:39 +08:00
| children | Render function | (fields: Field[], operation: { add, remove, move }) => React.ReactNode | - |
```tsx
<Form.List>
{fields => (
<div>
{fields.map(field => (
<Form.Item {...field}>
<Input />
</Form.Item>
))}
</div>
)}
</Form.List>
```
## operation
Some operator functions in render form of Form.List.
| Property | Description | Type | Default |
| -------- | ---------------- | ----------------------------------- | --------------- |
| add | add form item | (defaultValue?: any) => void | - |
| remove | remove form item | (index: number \| number[]) => void | number[]: 4.5.0 |
| move | move form item | (from: number, to: number) => void | - |
## Form.Provider
Provide linkage between forms. If a sub form with `name` prop update, it will auto trigger Provider related events. See [example](#components-form-demo-form-context).
2017-11-17 21:19:10 +08:00
| Property | Description | Type | Default |
| --- | --- | --- | --- |
2020-08-03 15:01:16 +08:00
| onFormChange | Triggered when a sub form field updates | function(formName: string, info: { changedFields, forms }) | - |
| onFormFinish | Triggered when a sub form submits | function(formName: string, info: { values, forms }) | - |
2017-11-17 21:19:10 +08:00
```jsx
<Form.Provider
onFormFinish={name => {
if (name === 'form1') {
// Do something...
}
}}
>
<Form name="form1">...</Form>
<Form name="form2">...</Form>
</Form.Provider>
```
2016-07-31 09:53:51 +08:00
### FormInstance
2016-10-18 21:12:52 +08:00
merge master into Feature (#25262) * feat: add successColor for Progress (#24655) * feat: add successColor for Progress * feat: update * fix: update test * remove snap * feat: add test case * refactor success * feat: adjust styyle * feat: add DevWarning * feat: Support rowSelection.dirty (#24718) * feat: Support rowSelection.dirty * rename to reserveKeys * preserveKeys will keep record also * to preserveSelectedRowKeys * feat: add ghost prop for collapse (#24734) * feat: add ghost prop for collapse * doc: version of collapse's ghost prop * refactor: make ghost collapse's less code to a nested style * chore: remove redundant codes in ghost collapse's less & doc * doc: add a background wrapper for ghost collapse demo * doc: dark-theme wrapper bg-color for ghost collapse demo * test: update snapshot of ghost collapse * doc: use softer bg-color on ghost collapse demo * doc: remove disabled panel in ghost collapse demo * feat: form instance support getFieldInstance (#24711) * support getFieldInstance * update doc * fix lint * move func * move into hooks * update ref logic * fix lint * rm only * fix docs * feat: dropdown support arrow (#23869) * feat: dropdown support arrow prop close #22758 * test: update snapshot * fix: fix dropdown cls names * test: update snapshot * test: update snapshot * doc: update demo * test: update demo snapshot * demo * fix: snapshot * chore: change the style of ghost collapse & demo modified (#24762) * refactor: reduce content padding in ghost collapse * doc: remove the wrapper outside ghost collapse Designer want the demo differs from other demos * refactor: remove redundant .less code in collapse * feat: cascader dropdown-render prop (#24812) * feat: cascader dropdown-render prop * fix: update Cascader dropdownRender type annotation * fix: set rc-cascader semver from ^ to ~ * docs: fix coding style in cascader/custom-dropdown * feat: 🆕 support Drawer closeIcon (#24842) * feat: :new: support Drawer closeIcon close #19283 close #19153 * add test case * update docs * feat: 🆕 Cascader expandIcon (#24865) * feat: cascader expandIcon * fix: snap * refactor: reduce CSS size (#24846) * refactor: reduce button css size * refactor: remove redundant button .less code * feat: add Table onChange an action param (#24697) * Working on tests * created TableAction type * changed TableActions to tuple * removed chinese documentation line * refactor TableActions * fix documentation * Moved action into extra param * minor doc change * feat: add closeIcon customize tag close (#24885) * feat: add closeIcon customize tag close * docs fix * update snap * fix: css name * update snapshot * snapshot * feat: add radio `optionType` api to set radio option type (#24809) * feat: radio component * docs: update md * fix: snap * test components * fix: use optionType * fix name * add warning * fix * feat: expand rate character (#24903) * feat: expand rate character * fix: demo * fix: snap * Update components/rate/index.zh-CN.md Co-authored-by: 偏右 <afc163@gmail.com> * fix Co-authored-by: 偏右 <afc163@gmail.com> * Refactor demo code box actions (#24887) * refactor: refine the styling of actions part of demo code-box * fix: lint style * refactor: move Result children to end (#24945) * feat: remove content max-width on dot-step (#24907) * feat: add Skeleton-Image (#24805) * feat: add Skeleton-Image * feat: add docs * fix: adjust skeleton * feat: adjust Image Component * feat: rebase * feat: adjust style * fix: lint * feat: remove size * feat: delete md * feat: fix style * ✨ feat: Mentions support autoSize (#24961) close #17746 * chore: replace textarea with rc-textarea (#24966) * feat: update pagination@2.3.0 support onChange called when pageSize change (#24964) * feat: update pagination@2.5.0 and add test case to relative component * fix: lint * delete * feat: add test case for pagination * adjust test case * feat: Implement centered prop in Tabs (#24958) * Implement centered in Tabs along with its tests and docs * Fix build error * Add Chinese translations and remove test case Co-authored-by: Ashkan Pourghasem <ashkan.pourghasem@gmail.com> * feat: Add modal style parameter (#24773) * add some paramters in default.less * Update components/style/themes/default.less Co-authored-by: Amumu <yoyo837@hotmail.com> * change parameter in compact.less Co-authored-by: Crystal Gao <jinggao@ebay.com> Co-authored-by: Amumu <yoyo837@hotmail.com> * feat: export Tabs addIcon (#25006) * feat: export Tabs addIcon * update snapshot * feat: showNow on timepicker and datetimepicker (#25032) * feat: update rc-picker@1.7.1 and fix icons of month and quarter picker in DatePicker Component (#25035) * feat: update rc-picker@1.7.1 * delete * add * feat: expand rate support props (#24993) * docs: :memo: Add Form.Item hidden in doc (#25108) close #25101 * fix: ⌨️ Improve Pagination accessibility issue (#25119) * ⌨️ Improve Pagination a11y by fixing a W3C error https://github.com/react-component/pagination/issues/280 * update snapshot * :up: rc-pagination to 2.4.1 * feat: support triggerSubMenuAction for <Menu /> (#25127) * feat(menu): add triggerSubMenuAction for Menu * feat(menu): test cases * chore: Adjust picker logic (#25135) * chore: update rc-picker 1.10.0 (#25174) * feat: table row check strictly (#24931) * feat: add checkStrictly on Table.rowSelection * fix: LGTM warnings * test: table rowSelection.checkStrictly * test: add cov [wip] * refactor: tree.rowSelection.checkStrictly [wip] * test: table.rowSelection.checkStrictly basic case * feat: support rowKey on checkStrictly table * feat: Table checkStrictly support getCheckboxProps * docs: Table checkStrictly * chore: typo * chore: remove useless comment * chore: update snapshot * chore: update snapshot * fix: fire selectAll on selection dropdown menu & changeRows incorrect in selectAll callback * docs: typo * chore * chore * fix: expand buttons of leaf rows in tree data are not hidden * feat: Table warning about rowKey index parameter * perf: only generate keyEntities when not checkStrictly * refactor: remove useless parseCheckedKeys * refactor: get derived selected & half selected keys from selectedRowKeys * chore: remove env condition stmt * chore: revert index usage & code formatting * chore: rerun ci * docs: table tree-data checkstrictly * test: update snapshots * refactor: use useMergedState hook * chore: rerun ci * chore: rerun ci 2 * chore: revert selection select all behavior * refactor: refactor code based on feature * chore: revert table code format * chore: revert table code format * fix: useMemo deps * fix: useMemo deps * fix: useMemo deps * feat: support preserve (#25186) * docs: add responsibly order for Col (#25139) * feat: add type * feat: add responsibly order cols * feat: add docs * feat: add test case * fix test Co-authored-by: 二货机器人 <smith3816@gmail.com> Co-authored-by: 偏右 <afc163@gmail.com> Co-authored-by: zoomdong <1344492820@qq.com> Co-authored-by: 07akioni <07akioni2@gmail.com> Co-authored-by: wendellhu <wendellhu95@gmail.com> Co-authored-by: xrkffgg <xrkffgg@gmail.com> Co-authored-by: Neto Braghetto <netow93@gmail.com> Co-authored-by: Kermit Xuan <kermitlx@outlook.com> Co-authored-by: Ashkan Pourghasem <64011067+ashkan-pm@users.noreply.github.com> Co-authored-by: Ashkan Pourghasem <ashkan.pourghasem@gmail.com> Co-authored-by: hicrystal <295247343@qq.com> Co-authored-by: Crystal Gao <jinggao@ebay.com> Co-authored-by: Amumu <yoyo837@hotmail.com> Co-authored-by: Li Ming <armyiljfe@gmail.com>
2020-06-28 22:41:59 +08:00
| Name | Description | Type | Version |
| --- | --- | --- | --- |
| getFieldInstance | Get field instance | (name: [NamePath](#NamePath)) => any | 4.4.0 |
| getFieldValue | Get the value by the field name | (name: [NamePath](#NamePath)) => any | |
| getFieldsValue | Get values by a set of field names. Return according to the corresponding structure | (nameList?: [NamePath](#NamePath)[], filterFunc?: (meta: { touched: boolean, validating: boolean }) => boolean) => any | |
| getFieldError | Get the error messages by the field name | (name: [NamePath](#NamePath)) => string[] | |
| getFieldsError | Get the error messages by the fields name. Return as an array | (nameList?: [NamePath](#NamePath)[]) => FieldError[] | |
| isFieldTouched | Check if a field has been operated | (name: [NamePath](#NamePath)) => boolean | |
| isFieldsTouched | Check if fields have been operated. Check if all fields is touched when `allTouched` is `true` | (nameList?: [NamePath](#NamePath)[], allTouched?: boolean) => boolean | |
| isFieldValidating | Check fields if is in validating | (name: [NamePath](#NamePath)) => boolean | |
| resetFields | Reset fields to `initialValues` | (fields?: [NamePath](#NamePath)[]) => void | |
| scrollToField | Scroll to field position | (name: [NamePath](#NamePath), options: [[ScrollOptions](https://github.com/stipsan/scroll-into-view-if-needed/tree/ece40bd9143f48caf4b99503425ecb16b0ad8249#options)]) => void | |
| setFields | Set fields status | (fields: [FieldData](#FieldData)[]) => void | |
| setFieldsValue | Set fields value | (values) => void | |
| submit | Submit the form. It's same as click `submit` button | () => void | |
| validateFields | Validate fields | (nameList?: [NamePath](#NamePath)[]) => Promise | |
#### validateFields return sample
2016-10-18 21:12:52 +08:00
```jsx
validateFields()
.then(values => {
/*
values:
{
username: 'username',
password: 'password',
}
*/
})
.catch(errorInfo => {
/*
errorInfo:
{
values: {
username: 'username',
password: 'password',
},
errorFields: [
{ password: ['username'], errors: ['Please input your Password!'] },
],
outOfDate: false,
}
*/
});
```
2016-07-31 09:53:51 +08:00
### Interface
2016-07-31 09:53:51 +08:00
#### NamePath
2016-07-31 09:53:51 +08:00
`string | number | (string | number)[]`
#### FieldData
| Name | Description | Type |
| ---------- | ------------------------ | ----------------------- |
| touched | Whether is operated | boolean |
| validating | Whether is in validating | boolean |
| errors | Error messages | string[] |
| name | Field name path | [NamePath](#NamePath)[] |
| value | Field value | any |
#### Rule
2020-02-23 01:26:35 +08:00
Rule support config object, and also support function to get config object:
```tsx
type Rule = RuleConfig | ((form: FormInstance) => RuleConfig);
```
| Name | Description | Type |
| --- | --- | --- |
| enum | Match enum value | any[] |
| len | Length of string, number, array | number |
| max | `type` required: max length of `string`, `number`, `array` | number |
| message | Error message. Will auto generate by [template](#validateMessages) if not provided | string |
| min | `type` required: min length of `string`, `number`, `array` | number |
| pattern | Regex pattern | RegExp |
| required | Required field | boolean |
| transform | Transform value to the rule before validation | (value) => any |
| type | Normally `string` \|`number` \|`boolean` \|`url` \| `email`. More type to ref [here](https://github.com/yiminghe/async-validator#type) | string |
| validator | Customize validation rule. Accept Promise as return. See [example](#components-form-demo-register) | ([rule](#Rule), value) => Promise |
| whitespace | Failed if only has whitespace | boolean |
| validateTrigger | Set validate trigger event. Must be the sub set of `validateTrigger` in Form.Item | string \| string[] |
## Migrate to v4
2020-02-23 01:26:35 +08:00
If you are a user of v3, you can ref [migrate doc](/components/form/v3)。
2018-09-12 22:16:53 +08:00
<style>
.code-box-demo .ant-form:not(.ant-form-inline):not(.ant-form-vertical) {
max-width: 600px;
}
.markdown.api-container table td:nth-of-type(4) {
2018-09-12 22:16:53 +08:00
white-space: nowrap;
word-wrap: break-word;
}
</style>
## FAQ
### Custom validator not working
It may be caused by your `validator` if it has some errors that prevents `callback` to be called. You can use `async` instead or use `try...catch` to catch the error:
```jsx
validator: async (rule, value) => {
throw new Error('Something wrong!');
}
// or
validator(rule, value, callback) => {
try {
throw new Error('Something wrong!');
} catch (err) {
callback(err);
}
}
```
### How does name fill value when it's array?
2020-07-09 10:24:41 +08:00
`name` will fill value by array order. When there exists number in it and no related field in form store, it will auto convert field to array. If you want to keep it as object, use string like: `['1', 'name']`.
2020-02-23 01:26:35 +08:00
### Why is there a form warning when used in Modal?
> Warning: Instance created by `useForm` is not connect to any Form element. Forget to pass `form` prop?
2020-07-06 10:27:31 +08:00
Before Modal opens, children elements do not exist in the view. You can set `forceRender` on Modal to pre-render its children. Click [here](https://codesandbox.io/s/antd-reproduction-template-ibu5c) to view an example.
2020-07-06 10:27:31 +08:00
### Why is component `defaultValue` not working when inside Form.Item?
2020-07-06 10:27:31 +08:00
Components inside Form.Item with name property will turn into controlled mode, which makes `defaultValue` not work anymore. Please try `initialValues` of Form to set default value.
### Why `resetFields` will re-mount component?
2020-07-06 10:27:31 +08:00
`resetFields` will re-mount component under Field to clean up customize component side effects (like async data, cached state, etc.). It's by design.
### Difference between Form initialValues and Item initialValue?
2020-07-06 10:27:31 +08:00
In most case, we always recommend to use Form `initialValues`. Use Item `initialValue` only with dynamic field usage. Priority follows the rules:
1. Form `initialValues` is the first priority
2020-07-06 10:27:31 +08:00
2. Field `initialValue` is secondary \*. Does not work when multiple Item with same `name` setting the `initialValue`
2020-07-06 10:27:31 +08:00
### Why `onFieldsChange` triggers three times on change when field sets `rules`?
Validating is also part of the value updating. It pass follow steps:
1. Trigger value change
2. Rule validating
3. Rule validated
In each `onFieldsChange`, you will get `false` > `true` > `false` with `isFieldValidating`.
2019-12-23 20:07:56 +08:00
<style>
.site-form-item-icon {
color: rgba(0, 0, 0, 0.25);
}
[data-theme="dark"] .site-form-item-icon {
color: rgba(255,255,255,.3);
}
</style>