github
/
ant-design-vue
mirror of https://github.com/vueComponent/ant-design-vue
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

doc: update form doc

v2.3
tangjinzhou 2021-09-22 16:22:34 +08:00
parent 4914864313
commit f793a85582
17 changed files with 192 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
components/form/__tests__/__snapshots__/demo.test.js.snap
View File

@ -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">

2
components/form/__tests__/demo.test.js
View File

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

4
components/form/demo/basic.vue
View File

@ -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;

13
components/form/demo/custom-validation.vue
View File

@ -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 = () => {

6
components/form/demo/dynamic-form-item.vue
View File

@ -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);
});
};

10
components/form/demo/horizontal-login.vue
View File

@ -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 {

4
components/form/demo/lable-width.vue
View File

@ -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;

3
components/form/demo/layout.vue
View File

@ -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';

7
components/form/demo/validation.vue
View File

@ -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);
});
};

72
components/form/index.en-US.md
View File

@ -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
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.
#### 3.x
If the form field to be monitored does not meet the conditions for automatic monitoring, you can associate the form field as follows:
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>
```
The second way is to wrap it with a custom component and call `useFormItemContext` in the custom component
```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;
}
```
};
```

64
components/form/index.zh-CN.md
View File

@ -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
<a-form-item>
<a-input name="a"></a-input>
<a-input name="b"></a-input>
</a-form-item>
```
如上 Form.Item 并不知道需要收集 `name="a"` 还是 `name=`b``，你可以通过如下两种方式去解决此类问题：
第一种，使用多个 `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>
```
第二种，使用自定义组件包裹，并在自定义组件中调用 `useFormItemContext`
```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 会对唯一子元素进行劫持，并监听 `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<RuleError[]>;
mergeValidateInfo: (items: ValidateInfo | ValidateInfo[]) => ValidateInfo;
clearValidate: (names?: namesType) => void;
}
```
};
```

3
components/table/demo/edit-row.vue
View File

@ -48,7 +48,8 @@ Table with editable rows.
</template>
<script lang="ts">
import { cloneDeep } from 'lodash-es';
import { defineComponent, reactive, ref, UnwrapRef } from 'vue';
import { defineComponent, reactive, ref } from 'vue';
import type { UnwrapRef } from 'vue';
const columns = [
{

3
plugin/docs/index.ts
View File

@ -19,8 +19,9 @@ export default (options: Options = {}): Plugin => {
(id.endsWith('.vue') && id.indexOf('/demo/') > -1 && id.indexOf('index.vue') === -1) ||
id.indexOf('/examples/App.vue') > -1
) {
const res = vueToMarkdown(code, id);
// transform .md files into vueSrc so plugin-vue can handle it
return { code: markdownToVue(vueToMarkdown(code, id).vueSrc, id).vueSrc, map: null };
return { code: res.ignore ? res.vueSrc : markdownToVue(res.vueSrc, id).vueSrc, map: null };
}
},
};

1
plugin/docs/vueToMarkdown.ts
View File

@ -36,6 +36,7 @@ ${style}
debug(`[render] ${file} in ${Date.now() - start}ms.`);
const result = {
vueSrc: newContent?.trim(),
ignore: !docs,
};
cache.set(src, result);
return result;

2
site/debugger/index.tsx
View File

@ -1,5 +1,5 @@
// debugger tsx
import Demo from '../../components/form/demo/validation.vue';
import Demo from '../../components/form/demo/customized-form-controls.vue';
export default {
render() {

3
site/src/App.vue
View File

@ -5,7 +5,8 @@
</template>
<script lang="ts">
import { computed, defineComponent, provide, Ref, watch, ref } from 'vue';
import { computed, defineComponent, provide, watch, ref } from 'vue';
import type { Ref } from 'vue';
import { useRoute } from 'vue-router';
import { useI18n } from 'vue-i18n';
import useMediaQuery from './hooks/useMediaQuery';

2
site/src/layouts/header/Ecosystem.vue
View File

@ -42,7 +42,7 @@
</template>
<script lang="ts">
import { computed, defineComponent, inject } from 'vue';
import { GlobalConfig } from '../../App.vue';
import type { GlobalConfig } from '../../App.vue';
import { GLOBAL_CONFIG } from '../../SymbolKey';
import { getLocalizedPathname } from '../../utils/util';