mirror/ant-design
1
0
Fork 0
mirror of https://github.com/ant-design/ant-design.git synced 2024-11-29 05:29:37 +08:00
Code Issues Actions 20 Packages Projects Releases Wiki Activity

docs: Review (#2573)

Browse Source 
Please excuse any mistake. I just discovered this library the other day, I felt in love with it and I really like to contribute. :-)
This commit is contained in:
Marius Ileana 2016-08-02 04:32:50 +03:00 committed by Benjy Cui
parent be181a7cc7
commit 23e5912384
1 changed files with 48 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
components/form/index.en-US.md
View File

@ -5,21 +5,20 @@ cols: 1
english: Form
---
Forms are used to collect, validate and submit user input, forms contains form elements.
Forms elements are different types of checkboxes, radios, input elements, selectboxes, and more.
Forms are used to collect, validate, and submit the user input. They contain one or more form items.
There are many types of form items including checkbox, radio, input, select, and more.
## Form
You can align controls of `form` use following methods：
You can align the controls of a `form` using one of the following attributes：
- horizontal align：to horizontally align `label` tag with form control.
- inline align：to set the display property of form controls to `inline-block`.
- `horizontal`：to horizontally align the `label`s and controls of the fields.
- `inline`：to render the labels and controls of the fields in one line (by setting the display property of form controls to `inline-block`).
## Form field
## Form fields
Form must contains form field, form field could be input elements, standard elements,
tag, selectboxes, textareas, and more.
We encapsulate form field in `<Form.Item />`.
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 />`.
```jsx
<Form.Item {...props}>
@ -27,7 +26,7 @@ We encapsulate form field in `<Form.Item />`.
</Form.Item>
```
> PS：Standard form always use large size control。
> PS：By default, large size controls are used within a form.
## API
@ -35,13 +34,13 @@ We encapsulate form field in `<Form.Item />`.
**more example [rc-form](http://react-component.github.io/form/)**。
| Property | Description | Type | Default |
| Property | Description | Type | Default Value |
|-----------|------------------------------------------|------------|---------|
| 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 | No
| horizontal | Horizontal align | boolean | false |
| inline | Inline align | boolean | false |
| onSubmit | Defines a function will be called if form data validation is successful | Function(e:Event) | |
| prefixCls | This is the css class name of form component，default value is ant-form，generally you don't need to set it by yourself | string | 'ant-form' |
| 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
| horizontal | Use horizontal alignment. | boolean | false |
| inline | Use inline alignment. | boolean | false |
| onSubmit | Defines a function will be called if form data validation is successful. | Function(e:Event) | |
| prefixCls | Set the CSS class name of form component (optional). | string | 'ant-form' |
### Form.create(options)
@ -53,33 +52,33 @@ class CustomizedForm extends React.Component {}
CustomizedForm = Form.create({})(CustomizedForm);
```
To set `options` as follows.
The following `options` are available:
| Property | Description | Type |
|-----------|------------------------------------------|------------|
| onFieldsChange | Defines a function will called When the value of child of `Form.Item` changed, you can save filed value to Redux store in this function if you need. | Function(props, fields) |
| mapPropsToFields | Convert props to corresponding field value，you can read the values of Redux store in this function if you need | Function(props): Object{ fieldName: Object{ value } } |
| 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) |
| mapPropsToFields | Convert props to corresponding field value. Usage example: reading the values from Redux store. | Function(props): Object{ fieldName: Object{ value } } |
If you the form has been decorated by `Form.create` then it has `this.props.form` property, `this.props.form` provides some APIs as follows:
If the form has been decorated by `Form.create` then it has `this.props.form` property. `this.props.form` provides some APIs as follows:
| Property | Description | Type |
|-----------|------------------------------------------|------------|
| getFieldsValue | get specified fields' value, if you don't specify any parameters, you will get all fields' value. | Function([fieldNames: string[]]) |
| getFieldValue | get specified field's value | Function(fieldName: string) |
| setFieldsValue | set specified fields' value | Function(obj: object) |
| setFields | set specified fields' value and Error | Function(obj: object) |
| validateFields | validate specified fields and get theirs value and Error | 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 | reference to `validateFields` |
| getFieldError | get specified field's Error | Function(name) |
| isFieldValidating | To check specified field is being validated | Function(name) |
| resetFields | reset specified fields' value and status, if you don't specify any parameters, it will reset all fields of form | Function([names: string[]]) |
| getFieldProps | two-way binding for form, please read below for details | |
| 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) |
| setFieldsValue | Set the value of a field. | Function(obj: object) |
| setFields | Set the value and error of a field. | Function(obj: object) |
| validateFields | Validate the specified fields and get theirs values and errors. | 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) |
| isFieldValidating | Check if the specified field is being validated. | Function(name) |
| resetFields | Reset the specified fields' value and status. If you don't specify a parameter, all the fields will be reset. | Function([names: string[]]) |
| getFieldProps | Two-way binding for form, please read below for details. | |
### this.props.form.getFieldProps(id, options)
#### Special attention
Can't use `getFieldProps` in functional component: https://github.com/facebook/react/pull/6534
Can't use `getFieldProps` in functional components: https://github.com/facebook/react/pull/6534
The return value of `getFieldProps` contains `id`、`value`(or any other props `valuePropName` that you specified),`ref`,`onChange`(or any other `trigger` `validateTrigger` that you specified), **shouldn't set same property again** in order to avoid conflict. If you concerntate on the details on return value, you can print them to console by `console.log`.
@ -87,33 +86,33 @@ The return value of `getFieldProps` contains `id`、`value`(or any other props `
#### getFieldProps options
| Property | Description | Type | Default |
| Property | Description | Type | Default Value |
|-----------|-----------------------------------------|-----|--------|
| options.id | The unique identity is required | string | |
| options.valuePropName | Props of children node, for exmaple, the prop of Switch is 'checked' | string | 'value' |
| options.initialValue | You can specify initial value, type, optional value of children node | | |
| options.id | The unique identifier is required. | string | |
| options.valuePropName | Props of children node, for exmaple, the prop of Switch is 'checked'. | string | 'value' |
| options.initialValue | You can specify initial value, type, optional value of children node. | | n/a |
| options.trigger | When to collect the value of children node | string | 'onChange' |
| options.getValueFromEvent | To convert parameters of onChange to the value of control, for example, set value of DatePicker: `(date, dateString) => dateString` | function(..args) | [reference](https://github.com/react-component/form#optiongetvaluefromevent) |
| options.validateTrigger | When to validate the value of children node | string | 'onChange' |
| options.rules | validation rule，reference to [async-validator](https://github.com/yiminghe/async-validator) | array | |
| options.onXXX | Because `getFieldProps` will replace events like `onChange` (`trigger` `validateTrigger`, if you still wnat to bind these events, please set them in `options` | function | no |
| options.exclusive | Whether it is exclusive with other controls, particularly for Radio | boolean | false |
| options.validateTrigger | When to validate the value of children node. | string | 'onChange' |
| options.rules | Includes validation rules. Please refer to [async-validator](https://github.com/yiminghe/async-validator) for details. | array | n/a |
| options.onXXX | Because `getFieldProps` will replace events like `onChange`, `trigger`, `validateTrigger`, if you still want to bind these events, you may set them in `options` | function | n/a |
| options.exclusive | Whether it is exclusive with other controls, particularly for Radio. | boolean | false |
### Form.Item
> To put one child in Form.Item is recommended, if it has multiple children, `help` `required` `validateStatus` can't be generated automatically.
> If Form.Item has multiple children, `help`, `required`, and `validateStatus` can't be generated automatically.
| Property | Description | Type | Optional | Default |
| Property | Description | Type | Optional | Default Value |
|-----------|------------------------------------------|-----------|-------|--------|
| label | Label text | string | | |
| labelCol | The lay out of label, you can set `span` `offset` to something like `{span: 3, offset: 12}` that same with `<Col>` | object | | |
| wrapperCol | To set layout for input controls, reference to labelCol | object | | |
| help | Prompt message, if you don't specify it, the prompt message will be generated by validation rule | string | | |
| extra | Provide extra prompt message, it is similar to help, if you need to display error message and prompt message in the same time, please use this | string | | |
| required | Whether it is required, if you don't specify it, it will be generated by validation rule| bool | | false |
| validateStatus | The validation status, if you don't specify it, it will be generated by validation rule | string | 'success' 'warning' 'error' 'validating' | |
| hasFeedback | To use this with validateStatus, display validation status icon, only use with Input component is recommended | bool | | false |
| prefixCls | This is the css class name of form component，default value is ant-form，generally you don't need to set it by yourself | string | | 'ant-form' |
| labelCol | The layout of label. You can set `span` `offset` to something like `{span: 3, offset: 12}` same as with `<Col>` | object | | |
| wrapperCol | The layout for input controls. Same as `labelCol` | object | | |
| help | The prompt message. If not provided, the prompt message will be generated by the validation rule. | string | | |
| extra | The extra prompt message. It is similar to help. Usage example: to display error message and prompt message at the same time. | string | | |
| required | Whether provided or not, it will be generated by the validation rule. | bool | | false |
| validateStatus | The validation status. If not provided, it will be generated by validation rule | string | 'success' 'warning' 'error' 'validating' | |
| hasFeedback | Used with `validateStatus`, this option specifies the validation status icon. Recommended to be used only with `Input`. | bool | | false |
| prefixCls | The CSS class name of form item (optional). | string | | 'ant-form' |
<style>
.code-box-demo .ant-form-horizontal {