feat: Form.Item support initialValue & getValueProps (#22993)

* add getValueProps

* field initialValue

* add faq

components/form/index.en-US.md

@@ -73,9 +73,11 @@ Form field component for data bidirectional binding, validation, layout, and so
 | 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 | - |  |
 | 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 |
 | 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 | - |  |
 | htmlFor | Set sub label `htmlFor` | string | - |  |
+| initialValue | Config sub default value. Form `initialValues` get higher priority when conflict | string | - | 4.2.0 |
 | noStyle | No style for `true`, used as a pure field control | boolean | false |  |
 | label | Label text | string\|ReactNode | - |  |
 | labelAlign | text align of label | `left` \| `right` | `right` |  |
@@ -89,7 +91,7 @@ Form field component for data bidirectional binding, validation, layout, and so
 | validateFirst | Whether stop validate on first rule of error for this field | boolean | false |  |
 | 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' | string | 'value' |  |
+| 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' |  |
 | 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) | - |  |
 
 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:
@@ -312,6 +314,15 @@ Before Modal open, children elements do not exist in the view. You can set `forc
 
 Components inside Form.Item with name property will turn into controlled mode, that makes `defaultValue` does not work anymore. Please try `initialValues` of Form to set default value.
 
+
+### Difference between Form initialValues and Item initialValue?
+
+In most case, we always recommend to use Form `initialValues`. Use Item `initialValue` only when dynamic field usage. Priority follow the rules:
+
+1. Form `initialValues` is the first priority
+2. Field `initialValue` is secondary
+    *. Not work when multiple Item with same `name` setting the `initialValue`
+
 <style>
   .site-form-item-icon {
     color: rgba(0, 0, 0, 0.25);

components/form/index.zh-CN.md

@@ -74,9 +74,11 @@ const validateMessages = {
 | dependencies | 设置依赖字段，说明[见下](#dependencies) | [NamePath](#NamePath)[] | - |  |
 | extra | 额外的提示信息，和 `help` 类似，当需要错误信息和提示文案同时出现时，可以使用这个。 | string\|ReactNode | - |  |
 | getValueFromEvent | 设置如何将 event 的值转换成字段值 | (..args: any[]) => any | - |  |
+| getValueProps | 为子元素添加额外的属性 | (value: any) => any | - | 4.2.0 |
 | hasFeedback | 配合 `validateStatus` 属性使用，展示校验状态图标，建议只配合 Input 组件使用 | boolean | false |  |
 | help | 提示信息，如不设置，则会根据校验规则自动生成 | string\|ReactNode | - |  |
 | htmlFor | 设置子元素 label `htmlFor` 属性 | string | - |  |
+| initialValue | 设置子元素默认值，如果与 Form 的 `initialValues` 冲突则以 Form 为准 | string | - | 4.2.0 |
 | noStyle | 为 `true` 时不带样式，作为纯字段控件使用 | boolean | false |  |
 | label | `label` 标签的文本 | string\|ReactNode | - |  |
 | labelAlign | 标签文本对齐方式 | `left` \| `right` | `right` |  |
@@ -90,7 +92,7 @@ const validateMessages = {
 | validateFirst | 当某一规则校验不通过时，是否停止剩下的规则的校验 | boolean | false |  |
 | validateStatus | 校验状态，如不设置，则会根据校验规则自动生成，可选：'success' 'warning' 'error' 'validating' | string | - |  |
 | validateTrigger | 设置字段校验的时机 | string \| string[] | onChange |  |
-| valuePropName | 子节点的值的属性，如 Switch 的是 'checked' | string | 'value' |  |
+| valuePropName | 子节点的值的属性，如 Switch 的是 'checked'。该属性为 `getValueProps` 的封装，自定义 `getValueProps` 后会失效 | string | 'value' |  |
 | wrapperCol | 需要为输入控件设置布局样式时，使用该属性，用法同 `labelCol`。你可以通过 Form 的 `wrapperCol` 进行统一设置。当和 Form 同时设置时，以 Item 为准。 | [object](/components/grid/#Col) | - |  |
 
 被设置了 `name` 属性的 `Form.Item` 包装的控件，表单控件会自动添加 `value`（或 `valuePropName` 指定的其他属性） `onChange`（或 `trigger` 指定的其他属性），数据同步将被 Form 接管，这会导致以下结果：
@@ -313,6 +315,14 @@ validator(rule, value, callback) => {
 
 当你为 Form.Item 设置 `name` 属性后，子组件会转为受控模式。因而 `defaultValue` 不会生效。你需要在 Form 上通过 `initialValues` 设置默认值。
 
+### Form 的 initialValues 与 Item 的 initialValue 区别？
+
+在大部分场景下，我们总是推荐优先使用 Form 的 `initialValues`。只有存在动态字段时你才应该使用 Item 的 `initialValue`。默认值遵循以下规则：
+
+1. Form 的 `initialValues` 拥有最高优先级
+2. Field 的 `initialValue` 次之
+    *. 多个同 `name` Item 都设置 `initialValue` 时，则 Item 的 `initialValue` 不生效
+
 <style>
   .site-form-item-icon {
     color: rgba(0, 0, 0, 0.25);

package.json

@@ -113,7 +113,7 @@
     "rc-dialog": "~7.6.0",
     "rc-drawer": "~3.1.1",
     "rc-dropdown": "~3.0.0",
-    "rc-field-form": "~1.1.0",
+    "rc-field-form": "~1.2.0",
     "rc-input-number": "~4.5.4",
     "rc-mentions": "~1.0.0",
     "rc-menu": "~8.0.1",