From f793a85582de8a7b998221ad7a0c69a93af6c0aa Mon Sep 17 00:00:00 2001 From: tangjinzhou <415800467@qq.com> Date: Wed, 22 Sep 2021 16:22:34 +0800 Subject: [PATCH] doc: update form doc --- .../__tests__/__snapshots__/demo.test.js.snap | 36 ++++++++++ components/form/__tests__/demo.test.js | 2 +- components/form/demo/basic.vue | 4 +- components/form/demo/custom-validation.vue | 13 ++-- components/form/demo/dynamic-form-item.vue | 6 +- components/form/demo/horizontal-login.vue | 10 +-- components/form/demo/lable-width.vue | 4 +- components/form/demo/layout.vue | 3 +- components/form/demo/validation.vue | 7 +- components/form/index.en-US.md | 72 ++++++++++++++++--- components/form/index.zh-CN.md | 64 +++++++++++++++-- components/table/demo/edit-row.vue | 3 +- plugin/docs/index.ts | 3 +- plugin/docs/vueToMarkdown.ts | 1 + site/debugger/index.tsx | 2 +- site/src/App.vue | 3 +- site/src/layouts/header/Ecosystem.vue | 2 +- 17 files changed, 192 insertions(+), 43 deletions(-) diff --git a/components/form/__tests__/__snapshots__/demo.test.js.snap b/components/form/__tests__/__snapshots__/demo.test.js.snap index 96a16c7e9..4735e9adb 100644 --- a/components/form/__tests__/__snapshots__/demo.test.js.snap +++ b/components/form/__tests__/__snapshots__/demo.test.js.snap @@ -197,6 +197,42 @@ exports[`renders ./components/form/demo/custom-validation.vue correctly 1`] = ` `; +exports[`renders ./components/form/demo/customized-form-controls.vue correctly 1`] = ` +
+
+
+
+
+
RMB + +
+ +
+
+ +
+ + +
+
+
+ +
+
+
+ +
+ + +
+
+
+`; + exports[`renders ./components/form/demo/dynamic-form-item.vue correctly 1`] = `
diff --git a/components/form/__tests__/demo.test.js b/components/form/__tests__/demo.test.js index 0247d5d30..9f04d13b7 100644 --- a/components/form/__tests__/demo.test.js +++ b/components/form/__tests__/demo.test.js @@ -1,3 +1,3 @@ import demoTest from '../../../tests/shared/demoTest'; -demoTest('form'); +demoTest('form', { skip: ['price-input'] }); diff --git a/components/form/demo/basic.vue b/components/form/demo/basic.vue index c668e7d9f..2a08f2f8d 100644 --- a/components/form/demo/basic.vue +++ b/components/form/demo/basic.vue @@ -61,7 +61,9 @@ Basic Form data control. Includes layout, initial values, validation and submit. +``` + +```html + + + + + + +``` + +#### 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 @@ -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; mergeValidateInfo: (items: ValidateInfo | ValidateInfo[]) => ValidateInfo; clearValidate: (names?: namesType) => void; -} -``` \ No newline at end of file +}; +``` diff --git a/components/form/index.zh-CN.md b/components/form/index.zh-CN.md index 1864efd63..e04ab9aba 100644 --- a/components/form/index.zh-CN.md +++ b/components/form/index.zh-CN.md @@ -48,7 +48,7 @@ cover: https://gw.alipayobjects.com/zos/alicdn/ORmcdeaoO/Form.svg ### 事件 | 事件名称 | 说明 | 回调参数 | 版本 | -| --- | --- | --- | --- | +| --- | --- | --- | --- | --- | | submit | 数据验证成功后回调事件 | Function(e:Event) | ｜ | | validate | 任一表单项被校验后触发 | 被校验的表单项 name 值，校验是否通过，错误消息（如果存在） | | finish | 提交表单且数据验证成功后回调事件 | function(values) | - | 2.0.0 | @@ -57,7 +57,7 @@ cover: https://gw.alipayobjects.com/zos/alicdn/ORmcdeaoO/Form.svg ### 方法 | 方法名 | 说明 | 参数 | -| --- | --- | --- | +| --- | --- | --- | --- | --- | | validate | 触发表单验证, 同 validateFields | (nameList?: [NamePath](#NamePath)[]) => Promise | | validateFields | 触发表单验证 | (nameList?: [NamePath](#NamePath)[]) => Promise | | scrollToField | 滚动到对应字段位置 | (name: [NamePath](#NamePath), options: [[ScrollOptions](https://github.com/stipsan/scroll-into-view-if-needed/tree/ece40bd9143f48caf4b99503425ecb16b0ad8249#options)]) => void | | | @@ -85,7 +85,59 @@ cover: https://gw.alipayobjects.com/zos/alicdn/ORmcdeaoO/Form.svg | validateFirst | 当某一规则校验不通过时，是否停止剩下的规则的校验。 | boolean | false | 2.0.0 | | validateTrigger | 设置字段校验的时机 | string \| string[] | `change` | 2.0.0 | -#### 注意： +### 注意： + +#### 3.x + +自 3.0 版本以后，Form.Item 不再劫持子元素，而是通过 provider / inject 依赖注入的方式进行自动校验，这种方式可以提高组件性能，子元素也不会限制个数，同样子元素也可以是进一步封装的高级组件。你可以参考[自定义表单控件示例](#components-form-demo-customized-form-controls) + +但它同样会有一些缺点： + +1、自定义组件如果希望 Form.Item 进行校验展示，你需要 `const {id, onFieldChange, onFieldBlur} = useFormItemContext` 注入，并调用相应的方法。 + +2、一个 Form.Item 只能收集一个表单项的数据，如果有多个表单项，会导致收集错乱，例如， + +```html + + + + +``` + +如上 Form.Item 并不知道需要收集 `name="a"` 还是 `name=`b``，你可以通过如下两种方式去解决此类问题： + +第一种，使用多个 `a-form-item`: + +```html + + + + +``` + +第二种，使用自定义组件包裹，并在自定义组件中调用 `useFormItemContext` + +```html + +``` + +```html + + + + + + +``` + +#### 2.x Form.Item 会对唯一子元素进行劫持，并监听 `blur` 和 `change` 事件，来达到自动校验的目的，所以请确保表单域没有其它元素包裹。如果有多个子元素，将只会监听第一个子元素的变化。 @@ -130,13 +182,11 @@ Form.Item 会对唯一子元素进行劫持，并监听 `blur` 和 `change` 事 2.2 以下版本需要需要 @ant-design-vue/use 库单独提供，不建议继续使用，你应该尽快升级到 2.2+ 版本 - ```ts import { Form } from 'ant-design-vue'; const useForm = Form.useForm; useForm(modelRef, ruleRef, [options]); - ``` 参数说明： @@ -173,5 +223,5 @@ function useForm( ) => Promise; mergeValidateInfo: (items: ValidateInfo | ValidateInfo[]) => ValidateInfo; clearValidate: (names?: namesType) => void; -} -``` \ No newline at end of file +}; +``` diff --git a/components/table/demo/edit-row.vue b/components/table/demo/edit-row.vue index 636c8d3f8..839f6f5fb 100644 --- a/components/table/demo/edit-row.vue +++ b/components/table/demo/edit-row.vue @@ -48,7 +48,8 @@ Table with editable rows.