docs: improve the document of form-item (#2372) (#2375)

2024-12-04 12:17:37 +08:00 · 2021-07-01 08:44:52 +08:00 · 2021-07-01 08:44:52 +08:00 · 6700fbc855
commit 6700fbc855
parent e10071a430
8 changed files with 46 additions and 10 deletions
--- a/packages/form/src/form-item.vue
+++ b/packages/form/src/form-item.vue
@ -42,16 +42,17 @@
 </template>

 <script lang="ts">
-import type { PropType } from 'vue'
 import { computed, defineComponent, getCurrentInstance, inject, nextTick, onBeforeUnmount, onMounted, provide, reactive, ref, toRefs, watch } from 'vue'
 import { NOOP } from '@vue/shared'
-import AsyncValidator, { RuleItem } from 'async-validator'
+import AsyncValidator from 'async-validator'
 import LabelWrap from './label-wrap'
 import { getPropByPath, useGlobalConfig } from '@element-plus/utils/util'
 import { isValidComponentSize } from '@element-plus/utils/validators'
 import mitt from 'mitt'
-import type { ElFormContext, ValidateFieldCallback } from './token'
 import { elFormEvents, elFormItemKey, elFormKey } from './token'
+import type { PropType } from 'vue'
+import type { ElFormContext, ValidateFieldCallback } from './token'
+import type { FormItemRule } from './form.type'

 export default defineComponent({
  name: 'ElFormItem',
@ -67,7 +68,7 @@ export default defineComponent({
      type: Boolean,
      default: undefined,
    },
-    rules: [Object, Array] as PropType<RuleItem | RuleItem[]>,
+    rules: [Object, Array] as PropType<FormItemRule | FormItemRule[]>,
    error: String,
    validateStatus: String,
    for: String,
--- a/packages/form/src/form.type.ts
+++ b/packages/form/src/form.type.ts
@ -0,0 +1,9 @@
+import { RuleItem } from 'async-validator'
+
+export declare interface FormItemRule extends RuleItem {
+  trigger?: string
+}
+
+export declare interface FormRulesMap {
+  [key: string]: FormItemRule | FormItemRule[]
+}
--- a/packages/form/src/form.vue
+++ b/packages/form/src/form.vue
@ -21,6 +21,7 @@ import {
  elFormEvents, ValidateFieldCallback,
 } from './token'
 import { FieldErrorList } from 'async-validator'
+import type { FormRulesMap } from './form.type'

 function useFormLabelWidth() {
  const potentialLabelWidthArr = ref([])
@ -66,7 +67,7 @@ export default defineComponent({
  name: 'ElForm',
  props: {
    model: Object,
-    rules: Object,
+    rules: Object as PropType<FormRulesMap>,
    labelPosition: String,
    labelWidth: String,
    labelSuffix: {
--- a/website/docs/en-US/form.md
+++ b/website/docs/en-US/form.md
@ -629,12 +629,17 @@ All components in a Form inherit their `size` attribute from that Form. Similarl
 | label | label | string | — | — |
 | label-width | width of label, e.g. '50px'. Width `auto` is supported. | string | — | — |
 | required | whether the field is required or not, will be determined by validation rules if omitted | boolean |  — | false |
-| rules | validation rules of form | object | — | — |
+| rules | validation rules of form, see the following table, more advanced usage at [async-validator](https://github.com/yiminghe/async-validator) | object / array | — | — |
 | error | field error message, set its value and the field will validate error and show this message immediately | string | — | — |
 | show-message  | whether to show the error message | boolean | — | true |
 | inline-message  | inline style validate message | boolean | — | false |
 | size  | control the size of components in this form-item | string | medium / small / mini | - |

+### Rules
+| Attribute       | Description                | Type     | Accepted Values  | Default  |
+| -------- | ----------------- | ------ | ---- | ---- |
+| trigger    | how the validator is triggered | string | blur / change   | —    |
+
 ### Form-Item Slots
 | Name | Description |
 |------|--------|
--- a/website/docs/es/form.md
+++ b/website/docs/es/form.md
@ -645,12 +645,17 @@ Todos los componentes de un formulario heredan su atributo `size`. De manera sim
 | label          | etiqueta                                                     | string  | —                                           | —           |
 | label-width    | ancho de la etiqueta, Ejemplo: '50px'. El valor `auto` esta soportado | string  | —                                           | —           |
 | required       | si el campo es obligatorio o no, estará determinado por las reglas de validación si se omite. | boolean | —                                           | false       |
-| rules          | reglas de validación del form                                | object  | —                                           | —           |
+| rules          | reglas de validación del form, ver más información en [async-validator](https://github.com/yiminghe/async-validator)  | object / array  | —                                           | —           |
 | error          | mensaje de error de campo, establezca su valor y el campo validará el error y mostrará este mensaje inmediatamente. | string  | —                                           | —           |
 | show-message   | si mostrar o no el mensaje de error                          | boolean | —                                           | true        |
 | inline-message | mensaje de validación estilo inline                          | boolean | —                                           | false       |
 | size           | Tamaño de los componentes en este form item                  | string  | medium / small / mini                       | -           |

+### Rules
+| Atributo       | Descripción  | Tipo    | Valores aceptados | Por defecto |
+| -------- | ----------------- | ------ | ---- | ---- |
+| trigger    | how the validator is triggered | string | blur / change   | —    |
+
 ### Form-Item Slot

 | Nombre | Descripción              |
--- a/website/docs/fr-FR/form.md
+++ b/website/docs/fr-FR/form.md
@ -629,12 +629,17 @@ Tout les composants d'un formulaire héritent leur attribut `size` de ce formula
 | label | Le label. | string | — | — |
 | label-width | Largeur du label, e.g. '50px'. La largeur `auto` est supportée. | string | — | — |
 | required | Si le champ est requis ou non. Si omis, sera déterminé par les règles de validation. | boolean |  — | false |
-| rules | Règles de validation du formulaire. | object | — | — |
+| rules | Règles de validation du formulaire, voir table suivante, plus d'informations ici:  [async-validator](https://github.com/yiminghe/async-validator)  | object / array | — | — |
 | error | Message d'erreur du champ. S'il est modifié, le champ l'affichera immédiatement. | string | — | — |
 | show-message  | Si le message d'erreur doit apparaître. | boolean | — | true |
 | inline-message  | Si le message d'erreur doit être en ligne avec le champ. | boolean | — | false |
 | size  | Contrôle la taille du FormItem. | string | medium / small / mini | - |

+### Rules
+| Attribut      | Description          | Type      | Valeurs acceptées       | Défaut  |
+| -------- | ----------------- | ------ | ---- | ---- |
+| trigger    | how the validator is triggered | string | blur / change   | —    |
+
 ### Slot de Form-Item
 | Nom | Description |
 |------|--------|
--- a/website/docs/jp/form.md
+++ b/website/docs/jp/form.md
@ -630,12 +630,17 @@ The component has been upgraded with a flex layout to replace the old float layo
 | label | ラベル | string | — | — |
 | label-width | ラベルの幅。Width `auto` がサポートされています。 | string | — | — |
 | required | フィールドが必須かどうか、省略された場合はバリデーションルールによって決定されます。 | boolean |  — | false |
-| rules | フォームのバリデーションルール | object | — | — |
+| rules | フォームのバリデーションルール | object / array | — | — |
 | error | フィールドのエラーメッセージ、値を設定すると、フィールドはエラーを検証し、このメッセージをすぐに表示します。 | string | — | — |
 | show-message  | エラーメッセージを表示するかどうか | boolean | — | true |
 | inline-message  | インラインスタイルバリデートメッセージ | boolean | — | false |
 | size  | フォームアイテムのコンポーネントのサイズを制御します。 | string | medium / small / mini | - |

+### Rules
+| Attribute       | Description                | Type     | Accepted Values  | Default  |
+| -------- | ----------------- | ------ | ---- | ---- |
+| trigger    | how the validator is triggered | string | blur / change   | —    |
+
 ### フォームアイテムスロット
 | Name | Description |
 |------|--------|
--- a/website/docs/zh-CN/form.md
+++ b/website/docs/zh-CN/form.md
@ -624,12 +624,17 @@ W3C 标准中有如下[规定](https://www.w3.org/MarkUp/html-spec/html-spec_8.h
 | label | 标签文本 | string | — | — |
 | label-width | 表单域标签的的宽度，例如 '50px'。支持 `auto`。 | string |       —       | — |
 | required | 是否必填，如不设置，则会根据校验规则自动生成 | boolean | — | false |
-| rules    | 表单验证规则 | object | — | — |
+| rules    | 表单验证规则, 具体配置见下表, 更多内容参考[async-validator](https://github.com/yiminghe/async-validator) | object / array | — | — |
 | error    | 表单域验证错误信息, 设置该值会使表单验证状态变为`error`，并显示该错误信息 | string | — | — |
 | show-message  | 是否显示校验错误信息 | boolean | — | true |
 | inline-message  | 以行内形式展示校验信息 | boolean | — | false |
 | size  | 用于控制该表单域下组件的尺寸 | string | medium / small / mini | - |

+### Rules
+| 参数       | 说明                | 类型     | 可选值  | 默认值  |
+| -------- | ----------------- | ------ | ---- | ---- |
+| trigger    | 验证触发方式 | string | blur / change   | —    |
+
 ### Form-Item Slot
 | name | 说明 |
 |------|--------|