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

167 lines
11 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
2016-07-31 09:53:51 +08:00
---
2016-10-07 14:33:08 +08:00
Form is used to collect, validate, and submit the user input, usually contains various form items including checkbox, radio, input, select, and etc.
2016-07-31 09:53:51 +08:00
## Form
You can align the controls of a `form` using one of the following attributes
2016-07-31 09:53:51 +08:00
2017-01-05 16:57:41 +08:00
- `horizontal`to horizontally align the `label`s and controls of the fields. (Default)
- `vertical`to vertically align the `label`s and controls of the fields.
- `inline`to render form fields in one line.
2016-07-31 09:53:51 +08:00
## Form fields
2016-07-31 09:53:51 +08:00
2016-09-01 18:12:12 +08:00
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 `<Form.Item />`.
2016-07-31 09:53:51 +08:00
```jsx
<Form.Item {...props}>
{children}
</Form.Item>
```
> PSBy default, large size controls are used within a form.
2016-07-31 09:53:51 +08:00
## API
### Form
**more example [rc-form](http://react-component.github.io/form/)**。
| Property | Description | Type | Default Value |
2016-07-31 09:53:51 +08:00
|-----------|------------------------------------------|------------|---------|
2016-09-01 18:12:12 +08:00
| form | Decorated by `Form.create()` will be automatically set `this.props.form` property, so just pass to form, you don't need to set it by yourself after 1.7.0. | object | n/a
| layout | Define form layout(Support after 2.8) | 'horizontal'\|'vertical'\|'inline' | 'horizontal' |
| horizontal | Use horizontal layout(Deprecated after 2.8) | boolean | true |
| vertical | Use vertical layout(Deprecated after 2.8) | boolean | false |
| inline | Use inline alignment(Deprecated after 2.8) | boolean | false |
| onSubmit | Defines a function will be called if form data validation is successful. | Function(e:Event) | |
| hideRequiredMark | Hide required mark of all form items | Boolean | false |
2016-07-31 09:53:51 +08:00
### Form.create(options)
How to use
```jsx
class CustomizedForm extends React.Component {}
CustomizedForm = Form.create({})(CustomizedForm);
```
The following `options` are available:
2016-07-31 09:53:51 +08:00
2016-11-21 14:28:20 +08:00
| Property | Description | Type |
2016-07-31 09:53:51 +08:00
|-----------|------------------------------------------|------------|
| onFieldsChange | Specify a function that will be called when the value a `Form.Item` gets changed. Usage example: saving the field's value to Redux store. | Function(props, fields) |
2017-08-19 12:10:46 +08:00
| mapPropsToFields | Convert props to field value. Usage example: reading the values from Redux store. | Function(props): Object{ fieldName: Object{ value } } |
2017-01-09 17:40:01 +08:00
| onValuesChange | A handler while value of any field is changed | (props, values) => void |
2016-07-31 09:53:51 +08:00
If the form has been decorated by `Form.create` then it has `this.props.form` property. `this.props.form` provides some APIs as follows:
2016-07-31 09:53:51 +08:00
> Note: Before using `getFieldsValue` `getFieldValue` `setFieldsValue` and so on, please make sure that corresponding field had been registered with `getFieldDecorator`.
2016-11-21 14:28:20 +08:00
| Property | Description | Type |
2016-07-31 09:53:51 +08:00
|-----------|------------------------------------------|------------|
| getFieldsValue | Get the specified fields' values. If you don't specify a parameter, you will get all fields' values. | Function([fieldNames: string[]]) |
| getFieldValue | Get the value of a field. | Function(fieldName: string) |
2016-09-15 01:21:48 +08:00
| setFieldsValue | Set the value of a field.(Note: please don't use it in `componentWillReceiveProps`, otherwise, it will cause an endless loop, [more](https://github.com/ant-design/ant-design/issues/2985)) | Function({ [fieldName]: value } |
| setFields | | Function(obj: object) |
| setFields | Set the value and error of a field. [Code Sample](https://github.com/react-component/form/blob/3b9959b57ab30b41d8890ff30c79a7e7c383cad3/examples/server-validate.js#L74-L79) | Function({ [fieldName]: { value: any, errors: [Error] } }) |
| validateFields | Validate the specified fields and get theirs values and errors. If you don't specify the parameter of fieldNames, you will vaildate all fields. | Function([fieldNames: string[]], [options: object], callback: Function(errors, values)) |
| validateFieldsAndScroll | This function is similar to `validateFields`, but after validation, if the target field is not in visible area of form, form will be automatically scrolled to the target field area. | same as `validateFields` |
| getFieldError | Get the error of a field. | Function(name) |
2017-01-09 17:40:01 +08:00
| getFieldsError | Get the specified fields' error. If you don't specify a parameter, you will get all fields' error. | Function([names: string[]]) |
| isFieldValidating | Check if the specified field is being validated. | Function(name) |
2017-01-09 17:40:01 +08:00
| isFieldTouched | Check whether a field is touched by `getFieldDecorator`'s `options.trigger` event | (name: string) => boolean |
| isFieldsTouched | Check whether any of fields is touched by `getFieldDecorator`'s `options.trigger` event | (names?: string[]) => boolean |
| resetFields | Reset the specified fields' value(to `initialValue`) and status. If you don't specify a parameter, all the fields will be reset. | Function([names: string[]]) |
| getFieldDecorator | Two-way binding for form, please read below for details. | |
2016-07-31 09:53:51 +08:00
### this.props.form.validateFields/validateFieldsAndScroll([fieldNames: string[]], [options: object], callback: Function(errors, values))
| 参数 | 说明 | 类型 | 默认值 |
|-----|-----|------|-------|
| options.first | If `true`, every field will stop validation at first failed rule | boolean | false |
| options.firstFields | Those fields will stop validation at first failed rule | String[] | [] |
| options.force | Should validate validated field again when `validateTrigger` is been triggered again | boolean | false |
| options.scroll | Config scroll behavior of `validateFieldsAndScroll`, more: [dom-scroll-into-view's config](https://github.com/yiminghe/dom-scroll-into-view#function-parameter) | Object | {} |
### this.props.form.getFieldDecorator(id, options)
2016-07-31 09:53:51 +08:00
2016-11-09 10:16:36 +08:00
After wrapped by `getFieldDecorator`, `value`(or other property defined by `valuePropName`) `onChange`(or other property defined by `trigger`) props will be added to form controlsthe flow of form data will be handled by Form which will cause:
2016-10-18 21:12:52 +08:00
2017-08-19 12:10:46 +08:00
1. You shouldn't to use `onChange` to collect data, but you still can listen to `onChange`(and so on) events.
2016-11-09 10:16:36 +08:00
2. You can not set value of form control via `value` `defaultValue` prop, and you should set default value with `initialValue` in `getFieldDecorator` instead.
2017-08-19 12:10:46 +08:00
3. You shouldn't to call `setState` manually, please use `this.props.form.setFieldsValue` to change value programmatically.
2016-10-18 21:12:52 +08:00
2016-07-31 09:53:51 +08:00
#### Special attention
2017-07-26 09:04:01 +08:00
1. `getFieldDecorator` can not be used to decorate stateless component.
1. If you use `react@<15.3.0`, then, you can't use `getFieldDecorator` in stateless component: https://github.com/facebook/react/pull/6534
2016-07-31 09:53:51 +08:00
#### getFieldDecorator(id, options) parameters
2016-07-31 09:53:51 +08:00
2016-11-21 14:28:20 +08:00
| Property | Description | Type | Default Value |
|-----------|-----------------------------------------|------|---------------|
| id | The unique identifier is required. support [nested fields format](https://github.com/react-component/form/pull/48). | string | |
2016-09-01 18:12:12 +08:00
| options.valuePropName | Props of children node, for example, the prop of Switch is 'checked'. | string | 'value' |
2017-02-14 10:29:06 +08:00
| options.initialValue | You can specify initial value, type, optional value of children node. (Note: Because `Form` will test equality with `===` internaly, we recommend to use vairable as `initialValue`, instead of literal) | | n/a |
2016-07-31 09:53:51 +08:00
| options.trigger | When to collect the value of children node | string | 'onChange' |
2017-07-16 15:05:48 +08:00
| options.getValueFromEvent | Specify how to get value from event or other onChange arguments | function(..args) | [reference](https://github.com/react-component/form#option-object) |
| options.validateTrigger | When to validate the value of children node. | string\|string[] | 'onChange' |
| options.rules | Includes validation rules. Please refer to "Validation Rules" part for details. | object[] | n/a |
| options.validateFirst | Whether stop validate on first rule of error for this field. | boolean | false |
| options.exclusive | Whether it is exclusive with other controls, particularly for Radio. | boolean | false |
2017-07-16 15:05:48 +08:00
| options.normalize | Normalize value to form component, [a select-all example](https://codepen.io/afc163/pen/JJVXzG?editors=001) | function(value, prevValue, allValues): any | - |
More option at [rc-form option](https://github.com/react-component/form#option-object)。
2016-07-31 09:53:51 +08:00
### Form.Item
2016-10-30 12:43:59 +08:00
Note:
* If Form.Item has multiple children that had been decorated by `getFieldDecorator`, `help` and `required` and `validateStatus` can't be generated automatically.
* Before `2.2.0`, form controls must be child of Form.Item, otherwise, you need to set `help`, `required` and `validateStatus` by yourself.
2016-07-31 09:53:51 +08:00
2016-11-21 14:28:20 +08:00
| Property | Description | Type | Default Value |
|---------------|--------------------------------------|--------|---------------|
| label | Label text | string\|ReactNode | |
| 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>` | [object](https://ant.design/components/grid/#Col) | |
| wrapperCol | The layout for input controls, same as `labelCol` | [object](https://ant.design/components/grid/#Col) | |
| help | The prompt message. If not provided, the prompt message will be generated by the validation rule. | string\|ReactNode | |
| 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 | |
2016-12-18 14:54:12 +08:00
| required | Whether provided or not, it will be generated by the validation rule. | boolean | false |
2016-11-21 14:28:20 +08:00
| validateStatus | The validation status. If not provided, it will be generated by validation rule. options: 'success' 'warning' 'error' 'validating' | string | |
| hasFeedback | Used with `validateStatus`, this option specifies the validation status icon. Recommended to be used only with `Input`. | boolean | false |
| colon | Used with `label`, whether to display `:` after label text. | boolean | true |
### Validation Rules
2017-03-07 22:38:01 +08:00
Property | Description | Type | Default Value
---------|-------------|------|--------------
message | validation error message | string | -
type | built-in validation type, [available options](https://github.com/yiminghe/async-validator#type) | string | 'string'
required | indicates whether field is required | boolean | `false`
2017-03-21 15:21:40 +08:00
whitespace | treat required fields that only contain whitespace as errors | boolean | `false`
2017-03-07 22:38:01 +08:00
len | validate an exact length of a field | number | -
min | validate a min length of a field | number | -
max | validate a max length of a field | number | -
enum | validate a value from a list of possible values | string | -
pattern | validate from a regular expression | RegExp | -
transform | transform a value before validation | function(value) => transformedValue:any | -
validator | custom validate function (Note: [callback must be called](https://github.com/ant-design/ant-design/issues/5155)) | function(rule, value, callback) | -
See more advanced usage at [async-validator](https://github.com/yiminghe/async-validator).
2016-07-31 09:53:51 +08:00
<style>
2017-01-05 16:57:41 +08:00
.code-box-demo .ant-form:not(.ant-form-inline):not(.ant-form-vertical) {
2016-07-31 09:53:51 +08:00
max-width: 540px;
}
</style>