doc: update form doc

Author: tangjinzhou

components/form/__tests__/__snapshots__/demo.test.js.snap

@@ -197,6 +197,42 @@ exports[`renders ./components/form/demo/custom-validation.vue correctly 1`] = `
 </form>
 `;
 
+exports[`renders ./components/form/demo/customized-form-controls.vue correctly 1`] = `
+<form class="ant-form ant-form-inline">
+  <div class="ant-row ant-form-item">
+    <div class="ant-col ant-form-item-label"><label html-for="customized_form_controls_price" class="" title="Price">Price
+        <!---->
+      </label></div>
+    <div class="ant-col ant-form-item-control">
+      <div class="ant-form-item-control-input">
+        <div class="ant-form-item-control-input-content"><span><input type="text" style="width: 100px;" class="ant-input"><div style="width: 80px; margin: 0px 8px;" class="ant-select ant-select-single ant-select-show-arrow"><!----><!----><div class="ant-select-selector"><span class="ant-select-selection-search"><input id="rc_select_TEST_OR_SSR" autocomplete="off" class="ant-select-selection-search-input" style="opacity: 0;" role="combobox" aria-haspopup="listbox" aria-owns="rc_select_TEST_OR_SSR_list" aria-autocomplete="list" aria-controls="rc_select_TEST_OR_SSR_list" aria-activedescendant="rc_select_TEST_OR_SSR_list_0" readonly="" unselectable="on" type="search"></span><span class="ant-select-selection-item" title="RMB">RMB</span>
+          <!---->
+        </div><span class="ant-select-arrow" style="user-select: none;" unselectable="on" aria-hidden="true"><span role="img" aria-label="down" class="anticon anticon-down ant-select-suffix"><svg focusable="false" class="" data-icon="down" width="1em" height="1em" fill="currentColor" aria-hidden="true" viewBox="64 64 896 896"><path d="M884 256h-75c-5.1 0-9.9 2.5-12.9 6.6L512 654.2 227.9 262.6c-3-4.1-7.8-6.6-12.9-6.6h-75c-6.5 0-10.3 7.4-6.5 12.7l352.6 486.1c12.8 17.6 39 17.6 51.7 0l352.6-486.1c3.9-5.3.1-12.7-6.4-12.7z"></path></svg></span></span>
+        <!---->
+      </div></span>
+    </div>
+    <!---->
+  </div>
+  <!---->
+  <!---->
+  </div>
+  </div>
+  <div class="ant-row ant-form-item">
+    <!---->
+    <div class="ant-col ant-form-item-control">
+      <div class="ant-form-item-control-input">
+        <div class="ant-form-item-control-input-content"><button class="ant-btn ant-btn-primary" type="submit">
+            <!----><span>Submit</span>
+          </button></div>
+        <!---->
+      </div>
+      <!---->
+      <!---->
+    </div>
+  </div>
+</form>
+`;
+
 exports[`renders ./components/form/demo/dynamic-form-item.vue correctly 1`] = `
 <form class="ant-form ant-form-horizontal">
   <div class="ant-row ant-form-item">

components/form/__tests__/demo.test.js

@@ -1,3 +1,3 @@
 import demoTest from '../../../tests/shared/demoTest';
 
-demoTest('form');
+demoTest('form', { skip: ['price-input'] });

components/form/demo/basic.vue

@@ -61,7 +61,9 @@ Basic Form data control. Includes layout, initial values, validation and submit.
 </template>
 <script lang="ts">
 import { Dayjs } from 'dayjs';
-import { defineComponent, reactive, toRaw, UnwrapRef } from 'vue';
+import { defineComponent, reactive, toRaw } from 'vue';
+import type { UnwrapRef } from 'vue';
+
 interface FormState {
   name: string;
   region: string | undefined;

components/form/demo/custom-validation.vue

@@ -44,8 +44,9 @@ See more advanced usage at [async-validator](https://github.com/yiminghe/async-v
   </a-form>
 </template>
 <script lang="ts">
-import { RuleObject, ValidateErrorEntity } from 'ant-design-vue/es/form/interface';
-import { defineComponent, reactive, ref, UnwrapRef } from 'vue';
+import { RuleObject } from 'ant-design-vue/es/form';
+import { defineComponent, reactive, ref } from 'vue';
+import type { UnwrapRef } from 'vue';
 interface FormState {
   pass: string;
   checkPass: string;
@@ -59,7 +60,7 @@ export default defineComponent({
       checkPass: '',
       age: undefined,
     });
-    let checkAge = async (rule: RuleObject, value: number) => {
+    let checkAge = async (_rule: RuleObject, value: number) => {
       if (!value) {
         return Promise.reject('Please input the age');
       }
@@ -73,7 +74,7 @@ export default defineComponent({
         }
       }
     };
-    let validatePass = async (rule: RuleObject, value: string) => {
+    let validatePass = async (_rule: RuleObject, value: string) => {
       if (value === '') {
         return Promise.reject('Please input the password');
       } else {
@@ -83,7 +84,7 @@ export default defineComponent({
         return Promise.resolve();
       }
     };
-    let validatePass2 = async (rule: RuleObject, value: string) => {
+    let validatePass2 = async (_rule: RuleObject, value: string) => {
       if (value === '') {
         return Promise.reject('Please input the password again');
       } else if (value !== formState.pass) {
@@ -105,7 +106,7 @@ export default defineComponent({
     const handleFinish = (values: FormState) => {
       console.log(values, formState);
     };
-    const handleFinishFailed = (errors: ValidateErrorEntity<FormState>) => {
+    const handleFinishFailed = errors => {
       console.log(errors);
     };
     const resetForm = () => {

components/form/demo/dynamic-form-item.vue

@@ -55,8 +55,8 @@ Add or remove form items dynamically.
 
 <script lang="ts">
 import { MinusCircleOutlined, PlusOutlined } from '@ant-design/icons-vue';
-import { ValidateErrorEntity } from 'ant-design-vue/es/form/interface';
-import { defineComponent, reactive, ref, UnwrapRef } from 'vue';
+import { defineComponent, reactive, ref } from 'vue';
+import type { UnwrapRef } from 'vue';
 
 interface Domain {
   value: string;
@@ -94,7 +94,7 @@ export default defineComponent({
         .then(() => {
           console.log('values', dynamicValidateForm.domains);
         })
-        .catch((error: ValidateErrorEntity<any>) => {
+        .catch(error => {
           console.log('error', error);
         });
     };

components/form/demo/horizontal-login.vue

@@ -45,8 +45,10 @@ Inline login form is often used in navigation bar.
 </template>
 <script lang="ts">
 import { UserOutlined, LockOutlined } from '@ant-design/icons-vue';
-import { ValidateErrorEntity } from 'ant-design-vue/es/form/interface';
-import { defineComponent, reactive, UnwrapRef } from 'vue';
+import { defineComponent, reactive } from 'vue';
+import type { UnwrapRef } from 'vue';
+import type { FormProps } from 'ant-design-vue';
+
 interface FormState {
   user: string;
   password: string;
@@ -61,10 +63,10 @@ export default defineComponent({
       user: '',
       password: '',
     });
-    const handleFinish = (values: FormState) => {
+    const handleFinish: FormProps['onFinish'] = values => {
       console.log(values, formState);
     };
-    const handleFinishFailed = (errors: ValidateErrorEntity<FormState>) => {
+    const handleFinishFailed: FormProps['onFinishFailed'] = errors => {
       console.log(errors);
     };
     return {

components/form/demo/lable-width.vue

@@ -45,7 +45,9 @@ Set label width by labelCol.style
   </a-form>
 </template>
 <script lang="ts">
-import { defineComponent, reactive, toRaw, UnwrapRef } from 'vue';
+import { defineComponent, reactive, toRaw } from 'vue';
+import type { UnwrapRef } from 'vue';
+
 interface FormState {
   name: string;
   delivery: boolean;

components/form/demo/layout.vue

@@ -36,7 +36,8 @@ There are three layout for form: `horizontal`, `vertical`, `inline`.
   </a-form>
 </template>
 <script lang="ts">
-import { computed, defineComponent, reactive, UnwrapRef } from 'vue';
+import { computed, defineComponent, reactive } from 'vue';
+import type { UnwrapRef } from 'vue';
 
 interface FormState {
   layout: 'horizontal' | 'vertical' | 'inline';

components/form/demo/validation.vue

@@ -67,9 +67,10 @@ Just add the `rules` attribute for `Form` component, pass validation rules, and
   </a-form>
 </template>
 <script lang="ts">
-import { ValidateErrorEntity } from 'ant-design-vue/es/form/interface';
 import { Dayjs } from 'dayjs';
-import { defineComponent, reactive, ref, toRaw, UnwrapRef } from 'vue';
+import { defineComponent, reactive, ref, toRaw } from 'vue';
+import type { UnwrapRef } from 'vue';
+
 interface FormState {
   name: string;
   region: string | undefined;
@@ -115,7 +116,7 @@ export default defineComponent({
         .then(() => {
           console.log('values', formState, toRaw(formState));
         })
-        .catch((error: ValidateErrorEntity<FormState>) => {
+        .catch(error => {
           console.log('error', error);
         });
     };

components/form/index.en-US.md

@@ -25,7 +25,6 @@ You can align the controls of a `form` using the `layout` prop：
 
 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 `<a-form-item />`.
 
-
 ## API
 
 ### Form
@@ -48,7 +47,7 @@ A form consists of one or more form fields whose type includes input, textarea,
 ### Events
 
 | Events Name | Description | Arguments | Version |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- |
 | submit | Defines a function will be called if form data validation is successful. | Function(e:Event) |  |
 | validate | triggers after a form item is validated | name of the form item being validated, whether validation is passed and the error message if not |  |
 | finish | Trigger after submitting the form and verifying data successfully | function(values) | - | 2.0.0 |
@@ -57,7 +56,7 @@ A form consists of one or more form fields whose type includes input, textarea,
 ### Methods
 
 | Method | Description | Parameters |
-| --- | --- | --- |
+| --- | --- | --- | --- |
 | validate | Validate fields, it is same as validateFields | (nameList?: [NamePath](#NamePath)[]) => Promise |  |
 | validateFields | Validate fields | (nameList?: [NamePath](#NamePath)[]) => Promise |  |
 | scrollToField | Scroll to field position | (name: [NamePath](#NamePath), options: [[ScrollOptions](https://github.com/stipsan/scroll-into-view-if-needed/tree/ece40bd9143f48caf4b99503425ecb16b0ad8249#options)]) => void |  |
@@ -85,11 +84,65 @@ A form consists of one or more form fields whose type includes input, textarea,
 | validateFirst | Whether stop validate on first rule of error for this field. | boolean | false |  |
 | validateTrigger | When to validate the value of children node | string \| string[] | `change` |  |
 
-#### Note
+### Note
+
+#### 3.x
+
+Since version 3.0, Form.Item no longer hijacks child elements, but automatically checks through provider/inject dependency injection. This method can improve component performance, and there is no limit to the number of child elements. The same is true for child elements. It can be a high-level component that is further encapsulated.
+
+You can reference [Customized Form Controls](#components-form-demo-customized-form-controls)
+
+But it also has some disadvantages:
+
+1. If the custom component wants Form.Item to be verified and displayed, you need to inject `const {id, onFieldChange, onFieldBlur} = useFormItemContext` and call the corresponding method.
+
+2. A Form.Item can only collect the data of one form item. If there are multiple form items, it will cause collection confusion, for example,
+
+```html
+<a-form-item>
+  <a-input name="a"></a-input>
+  <a-input name="b"></a-input>
+</a-form-item>
+```
+
+As above Form.Item does not know whether to collect `name="a"` or `name=`b``, you can solve this kind of problem in the following two ways:
+
+The first is to use multiple `a-form-item`:
+
+```html
+<a-form-item>
+  <a-input name="a"></a-input>
+  <a-form-item><a-input name="b"></a-input></a-form-item>
+</a-form-item>
+```
 
-Form.Item will hijack the only child element and listen to the `blur` and`change` events to achieve the purpose of automatic verification, so please ensure that the form field is not wrapped by other elements. If there are multiple child elements, only the first child element will be monitored for changes.
+The second way is to wrap it with a custom component and call `useFormItemContext` in the custom component
 
-If the form field to be monitored does not meet the conditions for automatic monitoring, you can associate the form field as follows:
+```html
+<script>
+  import { Form } from 'ant-desing-vue';
+  export default {
+    setup() {
+      const formItemContext = Form.useFormItemContext();
+    },
+  };
+</script>
+```
+
+```html
+<a-form-item>
+  <custom-com>
+    <a-input name="a"></a-input>
+    <a-input name="b"></a-input>
+  </custom-com>
+</a-form-item>
+```
+
+#### 2.x
+
+Form.Item hijacks the only child element and listens to the `blur` and `change` events to achieve the purpose of automatic verification, so please make sure that the form field is not wrapped by other elements. If there are multiple child elements, only the change of the first child element will be monitored.
+
+If the form field to be monitored does not meet the conditions of automatic monitoring, you can associate the form field as follows:
 
 ```html
 <a-form-item name="form.name" ref="name" :autoLink="false">
@@ -124,20 +177,17 @@ If the form field to be monitored does not meet the conditions for automatic mon
 
 See more advanced usage at [async-validator](https://github.com/yiminghe/async-validator).
 
-
 ### useForm (v2.2)
 
 `useForm` is a method that can run independently of the Form component. It uses the Vue response mechanism to monitor and verify data, and returns the verification result. You can bind the verification result to any component, `Form. Item` only displays the results.
 
 The following versions need to be provided separately by `@ant-design-vue/use` library, it is not recommended to continue to use, you should upgrade to version 2.2+ as soon as possible
 
-
 ```ts
 import { Form } from 'ant-design-vue';
 const useForm = Form.useForm;
 
 useForm(modelRef, ruleRef, [options]);
-
 ```
 
 参数说明：
@@ -174,5 +224,5 @@ function useForm(
   ) => Promise<RuleError[]>;
   mergeValidateInfo: (items: ValidateInfo | ValidateInfo[]) => ValidateInfo;
   clearValidate: (names?: namesType) => void;
-}
-```
+};
+```