mirror/ant-design
1
0
Fork 0
mirror of https://github.com/ant-design/ant-design.git synced 2024-12-01 23:29:30 +08:00
Code Issues Actions 29 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 english: Form
--- ---
Forms are used to collect, validate and submit user input, forms contains form elements. Forms are used to collect, validate, and submit the user input. They contain one or more form items.
Forms elements are different types of checkboxes, radios, input elements, selectboxes, and more. There are many types of form items including checkbox, radio, input, select, and more.
## Form ## 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. - `horizontal`：to horizontally align the `label`s and controls of the fields.
- inline align：to set the display property of form controls to `inline-block`. - `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, A form consists of one or more form fields whose type includes input, textarea, checkbox, radio, select, tag, and more.
tag, selectboxes, textareas, and more. A form field is defined using `<Form.Item />`.
We encapsulate form field in `<Form.Item />`.
```jsx ```jsx
<Form.Item {...props}> <Form.Item {...props}>
@ -27,7 +26,7 @@ We encapsulate form field in `<Form.Item />`.
</Form.Item> </Form.Item>
``` ```
> PS：Standard form always use large size control。 > PS：By default, large size controls are used within a form.
## API ## API
@ -35,13 +34,13 @@ We encapsulate form field in `<Form.Item />`.
**more example [rc-form](http://react-component.github.io/form/)**。 **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 | 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 | Horizontal align | boolean | false | | horizontal | Use horizontal alignment. | boolean | false |
| inline | Inline align | boolean | false | | inline | Use inline alignment. | boolean | false |
| onSubmit | Defines a function will be called if form data validation is successful | Function(e:Event) | | | 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' | | prefixCls | Set the CSS class name of form component (optional). | string | 'ant-form' |
### Form.create(options) ### Form.create(options)
@ -53,33 +52,33 @@ class CustomizedForm extends React.Component {}
CustomizedForm = Form.create({})(CustomizedForm); CustomizedForm = Form.create({})(CustomizedForm);
``` ```
To set `options` as follows. The following `options` are available:
| Property | Description | Type | | 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) | | 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，you can read the values of Redux store in this function if you need | Function(props): Object{ fieldName: Object{ value } } | | 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 | | Property | Description | Type |
|-----------|------------------------------------------|------------| |-----------|------------------------------------------|------------|
| getFieldsValue | get specified fields' value, if you don't specify any parameters, you will get all fields' value. | Function([fieldNames: string[]]) | | getFieldsValue | Get the specified fields' values. If you don't specify a parameter, you will get all fields' values. | Function([fieldNames: string[]]) |
| getFieldValue | get specified field's value | Function(fieldName: string) | | getFieldValue | Get the value of a field. | Function(fieldName: string) |
| setFieldsValue | set specified fields' value | Function(obj: object) | | setFieldsValue | Set the value of a field. | Function(obj: object) |
| setFields | set specified fields' value and Error | Function(obj: object) | | setFields | Set the value and error of a field. | Function(obj: object) |
| validateFields | validate specified fields and get theirs value and Error | Function([fieldNames: string[]], [options: object], callback: Function(errors, values)) | | 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 | reference to `validateFields` | | 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 specified field's Error | Function(name) | | getFieldError | Get the error of a field. | Function(name) |
| isFieldValidating | To check specified field is being validated | Function(name) | | isFieldValidating | Check if the 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[]]) | | 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 | | | getFieldProps | Two-way binding for form, please read below for details. | |
### this.props.form.getFieldProps(id, options) ### this.props.form.getFieldProps(id, options)
#### Special attention #### 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`. 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 #### getFieldProps options
| Property | Description | Type | Default | | Property | Description | Type | Default Value |
|-----------|-----------------------------------------|-----|--------| |-----------|-----------------------------------------|-----|--------|
| options.id | The unique identity is required | string | | | 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.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.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.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.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.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.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 wnat to bind these events, please set them in `options` | function | no | | 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 | | options.exclusive | Whether it is exclusive with other controls, particularly for Radio. | boolean | false |
### Form.Item ### 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 | | | | 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 | | | | labelCol | The layout of label. You can set `span` `offset` to something like `{span: 3, offset: 12}` same as with `<Col>` | object | | |
| wrapperCol | To set layout for input controls, reference to labelCol | object | | | | wrapperCol | The layout for input controls. Same as `labelCol` | object | | |
| help | Prompt message, if you don't specify it, the prompt message will be generated by validation rule | string | | | | help | The prompt message. If not provided, the prompt message will be generated by the 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 | | | | 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 it is required, if you don't specify it, it will be generated by validation rule| bool | | false | | required | Whether provided or not, it will be generated by the 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' | | | validateStatus | The validation status. If not provided, 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 | | hasFeedback | Used with `validateStatus`, this option specifies the validation status icon. Recommended to be used only with `Input`. | 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' | | prefixCls | The CSS class name of form item (optional). | string | | 'ant-form' |
<style> <style>
.code-box-demo .ant-form-horizontal { .code-box-demo .ant-form-horizontal {