From c37f1c9f5cc1802937f68671b67d81b4134a7b80 Mon Sep 17 00:00:00 2001
From: tangjinzhou <415800467@qq.com>
Date: Sat, 8 Dec 2018 19:24:30 +0800
Subject: [PATCH] feat: update form

---
 components/form/Form.jsx                      |  2 ++
 components/form/demo/dynamic-form-item.vue    |  4 +--
 components/form/demo/index.vue                |  5 ++++
 .../form/demo/time-related-controls.vue       |  4 +--
 components/form/demo/validate-other.vue       |  2 +-
 components/form/index.en-US.md                | 29 +++++++++++++------
 components/form/index.zh-CN.md                | 23 +++++++++++----
 7 files changed, 48 insertions(+), 21 deletions(-)

diff --git a/components/form/Form.jsx b/components/form/Form.jsx
index bf27ecc96..1406fb800 100755
--- a/components/form/Form.jsx
+++ b/components/form/Form.jsx
@@ -100,6 +100,8 @@ export const ValidationRule = {
 //   trigger?: string;
 //   /** 可以把 onChange 的参数转化为控件的值，例如 DatePicker 可设为：(date, dateString) => dateString */
 //   getValueFromEvent?: (...args: any[]) => any;
+//   /** Get the component props according to field value. */
+//   getValueProps?: (value: any) => any;
 //   /** 校验子节点值的时机 */
 //   validateTrigger?: string | string[];
 //   /** 校验规则，参见 [async-validator](https://github.com/yiminghe/async-validator) */
diff --git a/components/form/demo/dynamic-form-item.vue b/components/form/demo/dynamic-form-item.vue
index 1ca81b73f..7a14a434b 100644
--- a/components/form/demo/dynamic-form-item.vue
+++ b/components/form/demo/dynamic-form-item.vue
@@ -53,7 +53,6 @@ Add or remove form items dynamically.
 </template>
 
 <script>
-let uuid = 0
 export default {
   beforeCreate () {
     this.form = this.$form.createForm(this)
@@ -99,8 +98,7 @@ export default {
       const { form } = this
       // can use data-binding to get
       const keys = form.getFieldValue('keys')
-      const nextKeys = keys.concat(uuid)
-      uuid++
+      const nextKeys = keys.concat(keys.length)
       // can use data-binding to set
       // important! notify form to detect changes
       form.setFieldsValue({
diff --git a/components/form/demo/index.vue b/components/form/demo/index.vue
index 168aefc0e..51ed6c52e 100644
--- a/components/form/demo/index.vue
+++ b/components/form/demo/index.vue
@@ -79,6 +79,7 @@ export default {
   category: 'Components',
   subtitle: '表单',
   type: 'Data Entry',
+  zhType: '数据录入',
   cols: 1,
   title: 'Form',
   render () {
@@ -144,4 +145,8 @@ export default {
 .code-box-demo .ant-form:not(.ant-form-inline):not(.ant-form-vertical) {
   max-width: 600px;
 }
+.markdown.api-container table td:last-child {
+  white-space: nowrap;
+  word-wrap: break-word;
+}
 </style>
diff --git a/components/form/demo/time-related-controls.vue b/components/form/demo/time-related-controls.vue
index ab9e717d2..50e5baaa1 100644
--- a/components/form/demo/time-related-controls.vue
+++ b/components/form/demo/time-related-controls.vue
@@ -1,11 +1,11 @@
 <cn>
 #### 时间类控件
-时间类组件的 `value` 为 `moment` 类型，所以在提交前需要预处理。
+时间类组件的 `value` 类型为 `moment` 对象，所以在提交服务器前需要预处理。
 </cn>
 
 <us>
 #### Time-related Controls
-the `value` of time-related components is `moment`. So, we need to pre-process those values.
+The `value` of time-related components is a `moment` object, which we need to pre-process it before we submit to server.
 </us>
 
 <template>
diff --git a/components/form/demo/validate-other.vue b/components/form/demo/validate-other.vue
index 9f72aa875..f3d67588d 100644
--- a/components/form/demo/validate-other.vue
+++ b/components/form/demo/validate-other.vue
@@ -30,7 +30,7 @@ Demostration for validataion configuration for form controls which are not show
       placeholder='Please select a country'
     >
       <a-select-option value='china'>China</a-select-option>
-      <a-select-option value='use'>U.S.A</a-select-option>
+      <a-select-option value='usa'>U.S.A</a-select-option>
     </a-select>
   </a-form-item>
 
diff --git a/components/form/index.en-US.md b/components/form/index.en-US.md
index 1bc5c6063..6e7579887 100644
--- a/components/form/index.en-US.md
+++ b/components/form/index.en-US.md
@@ -6,7 +6,7 @@
 | -------- | ----------- | ---- | ------------- |
 | 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(Support after 2.8) | 'horizontal'\|'vertical'\|'inline' | 'horizontal' |
+| layout | Define form layout | 'horizontal'\|'vertical'\|'inline' | 'horizontal' |
 | 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 | {} |
 
@@ -67,13 +67,25 @@ If the form has been decorated by `Form.create` then it has `this.form` property
 | isFieldTouched | Check whether a field is touched by `getFieldDecorator`'s `options.trigger` event | (name: string) => boolean |
 | isFieldValidating | Check if the specified field is being validated. | Function(name) |
 | 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\[]]) |
-| setFields | Set the value and error of a field. | Function({ [fieldName]&#x3A; { value: any, errors: [Error] } }) |
-| setFields |  | Function(obj: object) |
+| setFields | Set value and error state of fields | ({<br />&nbsp;&nbsp;\[fieldName\]: {value: any, errors: \[Error\] }<br />}) => void |
 | setFieldsValue | Set the value of a field. | Function({ [fieldName]&#x3A; value } |
-| 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)) |
+| 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. | (<br />&nbsp;&nbsp;\[fieldNames: string\[]],<br />&nbsp;&nbsp;\[options: object\],<br />&nbsp;&nbsp;callback(errors, values)<br />) => void |
 | 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` |
 
-### this.form.validateFields/validateFieldsAndScroll(\[fieldNames: string\[]], [options: object], callback: Function(errors, values))
+### validateFields/validateFieldsAndScroll
+
+```jsx
+const { form: { validateFields } } = this;
+validateFields((errors, values) => {
+  // ...
+});
+validateFields(['field1', 'field2'], (errors, values) => {
+  // ...
+});
+validateFields(['field1', 'field2'], options, (errors, values) => {
+  // ...
+});
+```
 
 | Method | Description | Type | Default |
 | ------ | ----------- | ---- | ------- |
@@ -125,7 +137,7 @@ To mark the returned fields data in `mapPropsToFields`, [demo](#components-form-
 After wrapped by `getFieldDecorator` or `v-decorator`, `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` to collect data, but you still can listen to `onChange`(and so on) events.
-2. You can not set value of form control via `value` `defaultValue` prop, and you should set default value with `initialValue` in `getFieldDecorator` instead.
+2. You cannot set value of form control via `value` `defaultValue` prop, and you should set default value with `initialValue` in `getFieldDecorator` instead.
 3. You shouldn't call `v-model` manually, please use `this.form.setFieldsValue` to change value programmatically.
 
 #### Special attention
@@ -139,6 +151,7 @@ After wrapped by `getFieldDecorator` or `v-decorator`, `value`(or other property
 | -------- | ----------- | ---- | ------------- |
 | id | The unique identifier is required. support [nested fields format](https://github.com/react-component/form/pull/48). | string |  |
 | 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.getValueProps | Get the component props according to field value. | function(value): any | [reference](https://github.com/react-component/form#option-object)
 | 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 variable as `initialValue`, instead of literal) |  | n/a |
 | options.normalize | Normalize value to form component, [a select-all example](https://codesandbox.io/s/kw4l2vqqmv) | function(value, prevValue, allValues): any | - |
 | options.rules | Includes validation rules. Please refer to "Validation Rules" part for details. | object\[] | n/a |
@@ -149,9 +162,7 @@ After wrapped by `getFieldDecorator` or `v-decorator`, `value`(or other property
 
 ### Form.Item
 
-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.
+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 |
 | -------- | ----------- | ---- | ------------- |
diff --git a/components/form/index.zh-CN.md b/components/form/index.zh-CN.md
index d3d651a88..9193bdca0 100644
--- a/components/form/index.zh-CN.md
+++ b/components/form/index.zh-CN.md
@@ -45,7 +45,7 @@ export default {
 | 参数 | 说明 | 类型 |
 | --- | --- | --- |
 | props | 仅仅支持Form.create({})(CustomizedForm)的使用方式，父组件需要映射到表单项上的属性声明(和[vue组件props一致]( https://vuejs.org/v2/api/#props)) | {} |
-| mapPropsToFields | 把父组件的属性映射到表单项上（如：把 Redux store 中的值读出），需要对返回值中的表单域数据用 [`Form.createFormField`](#Form.createFormField) 标记，如果使用$form.createForm创建收集器，你可以将任何数据映射到Field中，不受父组件约束 | (props) => Object{ fieldName: FormField { value } } |
+| mapPropsToFields | 把父组件的属性映射到表单项上（如：把 Redux store 中的值读出），需要对返回值中的表单域数据用 [`Form.createFormField`](#Form.createFormField) 标记，如果使用$form.createForm创建收集器，你可以将任何数据映射到Field中，不受父组件约束 | (props) => ({ \[fieldName\]: FormField { value } }) |
 | validateMessages | 默认校验信息，可用于把默认错误信息改为中文等，格式与 [newMessages](https://github.com/yiminghe/async-validator/blob/master/src/messages.js) 返回值一致 | Object { [nested.path]&#x3A; String } |
 | onFieldsChange | 当 `Form.Item` 子节点的值发生改变时触发，可以把对应的值转存到 Redux store | Function(props, fields) |
 | onValuesChange | 任一表单域的值发生改变时的回调 | (props, values) => void |
@@ -65,12 +65,25 @@ export default {
 | isFieldTouched | 判断一个输入控件是否经历过 `getFieldDecorator` 的值收集时机 `options.trigger` | (name: string) => boolean |
 | isFieldValidating | 判断一个输入控件是否在校验状态 | Function(name) |
 | resetFields | 重置一组输入控件的值（为 `initialValue`）与状态，如不传入参数，则重置所有组件 | Function(\[names: string\[]]) |
-| setFields | 设置一组输入控件的值与 Error。 | Function({ [fieldName]&#x3A; { value: any, errors: [Error] } }) |
+| setFields | 设置一组输入控件的值与错误状态。 | Function({ [fieldName]&#x3A; { value: any, errors: [Error] } }) |
 | setFieldsValue | 设置一组输入控件的值 | Function({ [fieldName]&#x3A; value } |
 | validateFields | 校验并获取一组输入域的值与 Error，若 fieldNames 参数为空，则校验全部组件 | Function(\[fieldNames: string\[]], [options: object], callback: Function(errors, values)) |
 | validateFieldsAndScroll | 与 `validateFields` 相似，但校验完后，如果校验不通过的菜单域不在可见范围内，则自动滚动进可见范围 | 参考 `validateFields` |
 
-### this.form.validateFields/validateFieldsAndScroll(\[fieldNames: string\[]], [options: object], callback: Function(errors, values))
+### validateFields/validateFieldsAndScroll
+
+```jsx
+const { form: { validateFields } } = this;
+validateFields((errors, values) => {
+  // ...
+});
+validateFields(['field1', 'field2'], (errors, values) => {
+  // ...
+});
+validateFields(['field1', 'field2'], options, (errors, values) => {
+  // ...
+});
+```
 
 | 参数 | 说明 | 类型 | 默认值 |
 | --- | --- | --- | --- |
@@ -147,9 +160,7 @@ export default {
 
 ### Form.Item
 
-注意：
-
-- 一个 Form.Item 建议只放一个被 getFieldDecorator或v-decorator 装饰过的 child，当有多个被装饰过的 child 时，`help` `required` `validateStatus` 无法自动生成。
+注意：一个 Form.Item 建议只放一个被 getFieldDecorator或v-decorator 装饰过的 child，当有多个被装饰过的 child 时，`help` `required` `validateStatus` 无法自动生成。
 
 | 参数 | 说明 | 类型 | 默认值 |
 | --- | --- | --- | --- |