mirror of
https://github.com/element-plus/element-plus.git
synced 2024-11-21 01:02:59 +08:00
refactor(docs): [form] improve docs and typings (#6447)
This commit is contained in:
三咲智子
GitHub
parent
f3819db8bc
commit
eab6be93e7
@ -13,7 +13,7 @@ The component has been upgraded with a flex layout to replace the old float layo
|
||||
|
||||
:::
|
||||
|
||||
## Basic form
|
||||
## Basic Form
|
||||
|
||||
It includes all kinds of input items, such as `input`, `select`, `radio` and `checkbox`.
|
||||
|
||||
@ -33,7 +33,7 @@ To prevent this behavior, you can add `@submit.prevent` on `<el-form>`.
|
||||
|
||||
:::
|
||||
|
||||
## Inline form
|
||||
## Inline Form
|
||||
|
||||
When the vertical space is limited and the form is relatively simple, you can put it in one line.
|
||||
|
||||
@ -57,13 +57,13 @@ form/alignment
|
||||
|
||||
Form component allows you to verify your data, helping you find and correct errors.
|
||||
|
||||
:::demo Just add the `rules` attribute for `Form` component, pass validation rules, and set `prop` attribute for `Form-Item` as a specific key that needs to be validated. See more information at [async-validator](https://github.com/yiminghe/async-validator).
|
||||
:::demo Just add the `rules` attribute for `Form` component, pass validation rules, and set `prop` attribute for `FormItem` as a specific key that needs to be validated. See more information at [async-validator](https://github.com/yiminghe/async-validator).
|
||||
|
||||
form/validation
|
||||
|
||||
:::
|
||||
|
||||
## Custom validation rules
|
||||
## Custom Validation Rules
|
||||
|
||||
This example shows how to customize your own validation rules to finish a two-factor password verification.
|
||||
|
||||
@ -79,7 +79,7 @@ Custom validate callback function must be called. See more advanced usage at [as
|
||||
|
||||
:::
|
||||
|
||||
## Delete or add form items dynamically
|
||||
## Add/Delete Form Item
|
||||
|
||||
:::demo In addition to passing all validation rules at once on the form component, you can also pass the validation rules or delete rules on a single form field dynamically.
|
||||
|
||||
@ -89,7 +89,7 @@ form/form-items
|
||||
|
||||
## Number Validate
|
||||
|
||||
:::demo Number Validate need a `.number` modifier added on the input `v-model` binding，it's used to transform the string value to the number which is provided by Vuejs.
|
||||
:::demo Number Validate need a `.number` modifier added on the input `v-model` binding，it's used to transform the string value to the number which is provided by Vue.
|
||||
|
||||
form/number-validate
|
||||
|
||||
@ -101,7 +101,7 @@ When an `el-form-item` is nested in another `el-form-item`, its label width will
|
||||
|
||||
:::
|
||||
|
||||
## Size control
|
||||
## Size Control
|
||||
|
||||
All components in a Form inherit their `size` attribute from that Form. Similarly, FormItem also has a `size` attribute.
|
||||
|
||||
@ -111,77 +111,81 @@ form/size-control
|
||||
|
||||
:::
|
||||
|
||||
## Form Attributes
|
||||
## Form API
|
||||
|
||||
| Attribute | Description | Type | Accepted Values | Default |
|
||||
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------- | ----------------------- | ------- |
|
||||
| model | data of form component | object | — | — |
|
||||
| rules | validation rules of form | object | — | — |
|
||||
| inline | whether the form is inline | boolean | — | false |
|
||||
| label-position | position of label. If set to 'left' or 'right', `label-width` prop is also required | string | left / right / top | right |
|
||||
| label-width | width of label, e.g. '50px'. All its direct child form items will inherit this value. Width `auto` is supported. | string / number | — | — |
|
||||
| label-suffix | suffix of the label | string | — | — |
|
||||
| hide-required-asterisk | whether required fields should have a red asterisk (star) beside their labels | boolean | — | false |
|
||||
| show-message | whether to show the error message | boolean | — | true |
|
||||
| inline-message | whether to display the error message inline with the form item | boolean | — | false |
|
||||
| status-icon | whether to display an icon indicating the validation result | boolean | — | false |
|
||||
| validate-on-rule-change | whether to trigger validation when the `rules` prop is changed | boolean | — | true |
|
||||
| size | control the size of components in this form | string | large / default / small | — |
|
||||
| disabled | whether to disabled all components in this form. If set to true, it cannot be overridden by its inner components' `disabled` prop | boolean | — | false |
|
||||
### Form Attributes
|
||||
|
||||
## Form Methods
|
||||
| Attribute | Description | Type | Default |
|
||||
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | --------- |
|
||||
| `model` | Data of form component. | `Record<string, any>` | — |
|
||||
| `rules` | Validation rules of form. | `FormRules` | — |
|
||||
| `inline` | Whether the form is inline. | `boolean` | `false` |
|
||||
| `label-position` | Position of label. If set to `'left'` or `'right'`, `label-width` prop is also required. | `'left' \| 'right' \| 'top'` | `'right'` |
|
||||
| `label-width` | Width of label, e.g. `'50px'`. All its direct child form items will inherit this value. `auto` is supported. | `string \| number` | — |
|
||||
| `label-suffix` | Suffix of the label. | `string` | — |
|
||||
| `hide-required-asterisk` | Whether required fields should have a red asterisk (star) beside their labels. | `boolean` | `false` |
|
||||
| `show-message` | Whether to show the error message. | `boolean` | `true` |
|
||||
| `inline-message` | Whether to display the error message inline with the form item. | `boolean` | `false` |
|
||||
| `status-icon` | Whether to display an icon indicating the validation result. | `boolean` | `false` |
|
||||
| `validate-on-rule-change` | Whether to trigger validation when the `rules` prop is changed. | `boolean` | `true` |
|
||||
| `size` | Control the size of components in this form. | `'large' \| 'default' \| 'small'` | — |
|
||||
| `disabled` | Whether to disable all components in this form. If set to `true`, it will override the `disabled` prop of the inner component. | `boolean` | `false` |
|
||||
|
||||
| Method | Description | Parameters |
|
||||
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| validate | validate the whole form. Takes a callback as a param. After validation, the callback will be executed with two params: a boolean indicating if the validation has passed, and an object containing all fields that fail the validation. Returns a promise if callback is omitted | Function(callback: Function(boolean, object)) |
|
||||
| validateField | validate one or several form items | Function(props: string \| array, callback: Function(errorMessage: string)) |
|
||||
| resetFields | reset all the fields and remove validation result | — |
|
||||
| scrollToField | Scroll to the specified form field | Function(prop: string) |
|
||||
| clearValidate | clear validation message for certain fields. The parameter is prop name or an array of prop names of the form items whose validation messages will be removed. When omitted, all fields' validation messages will be cleared | Function(props: string \| array) |
|
||||
### Form Methods
|
||||
|
||||
## Form Events
|
||||
| Method | Description | Type |
|
||||
| --------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `validate` | Validate the whole form. Receives a callback or returns `Promise`. | `(callback?: (isValid: boolean, invalidFields?: ValidateFieldsError) => void) => Promise<void>` |
|
||||
| `validateField` | Validate specified fields. | `(props?: Arrayable<FormItemProp>, callback?: (isValid: boolean, invalidFields?: ValidateFieldsError) => void) => Promise<void>` |
|
||||
| `resetFields` | Reset specified fields and remove validation result. | `(props?: Arrayable<FormItemProp>) => void` |
|
||||
| `scrollToField` | Scroll to the specified fields. | `(prop: FormItemProp) => void` |
|
||||
| `clearValidate` | Clear validation message for specified fields. | `(props?: Arrayable<FormItemProp>) => void` |
|
||||
|
||||
| Event Name | Description | Parameters |
|
||||
| ---------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| validate | triggers after a form item is validated | prop name of the form item being validated, whether validation is passed and the error message if not |
|
||||
### Form Events
|
||||
|
||||
## Form Slots
|
||||
| Event Name | Description | Parameters |
|
||||
| ---------- | --------------------------------------- | ----------------------------------------------------------------- |
|
||||
| `validate` | triggers after a form item is validated | `(prop: FormItemProp, isValid: boolean, message: string) => void` |
|
||||
|
||||
| Name | Description | Subtags |
|
||||
| ---- | -------------------------- | --------- |
|
||||
| — | customize of Dropdown Item | Form-Item |
|
||||
### Form Slots
|
||||
|
||||
## Form-Item Attributes
|
||||
| Name | Description | Subtags |
|
||||
| ---- | ------------------------- | -------- |
|
||||
| - | customize default content | FormItem |
|
||||
|
||||
| Attribute | Description | Type | Accepted Values | Default |
|
||||
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ----------------------------------- | ------- |
|
||||
| prop | a key of `model`. In the use of validate and resetFields method, the attribute is required | string | keys of model that passed to `form` |
|
||||
| label | label | string | — | — |
|
||||
| label-width | width of label, e.g. '50px'. Width `auto` is supported. | string / number | — | — |
|
||||
| required | whether the field is required or not, will be determined by validation rules if omitted | boolean | — | false |
|
||||
| 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 | large / default / small | default |
|
||||
## Form Item API
|
||||
|
||||
## Rules
|
||||
### Form Item Attributes
|
||||
|
||||
| Attribute | Description | Type | Accepted Values | Default |
|
||||
| --------- | ------------------------------ | ------ | --------------- | ------- |
|
||||
| trigger | how the validator is triggered | string | blur / change | — |
|
||||
| Attribute | Description | Type | Default |
|
||||
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------- |
|
||||
| `prop` | A key of `model`. It could be an array of property paths (e.g `['a', 'b', 0]`). In the use of `validate` and `resetFields` method, the attribute is required. | `string \| string[]` | — |
|
||||
| `label` | Label text. | `string` | — |
|
||||
| `label-width` | Width of label, e.g. `'50px'`. `'auto'` is supported. | `string \| number` | — |
|
||||
| `required` | Whether the field is required or not, will be determined by validation rules if omitted. | `boolean` | `false` |
|
||||
| `rules` | Validation rules of form, see the [following table](#formitemrule), more advanced usage at [async-validator](https://github.com/yiminghe/async-validator). | `FormItemRule \| FormItemRule[]` | — |
|
||||
| `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. | `'large' \| 'default' \| 'small'` | `'default'` |
|
||||
|
||||
## Form-Item Slots
|
||||
#### FormItemRule
|
||||
|
||||
| Name | Description |
|
||||
| ----- | ------------------------------------------------------------------------------ |
|
||||
| — | content of Form Item |
|
||||
| label | Custom content to display on label. The scope parameter is { label } |
|
||||
| error | Custom content to display validation message. The scope parameter is { error } |
|
||||
| Name | Description | Type | Default |
|
||||
| --------- | ------------------------------- | -------------------- | ------- |
|
||||
| `trigger` | How the validator is triggered. | `'blur' \| 'change'` | — |
|
||||
|
||||
## Form-Item Methods
|
||||
### Form Item Slots
|
||||
|
||||
| Method | Description | Parameters |
|
||||
| ------------- | ------------------------------------------------ | ---------- |
|
||||
| resetField | reset current field and remove validation result | — |
|
||||
| clearValidate | remove validation status of the field | — |
|
||||
| Name | Description | Slot Scope |
|
||||
| ------- | --------------------------------------------- | ----------- |
|
||||
| — | Content of Form Item. | — |
|
||||
| `label` | Custom content to display on label. | `{ label }` |
|
||||
| `error` | Custom content to display validation message. | `{ error }` |
|
||||
|
||||
### Form Item Methods
|
||||
|
||||
| Method | Description | Type |
|
||||
| --------------- | ------------------------------------------------- | ------------ |
|
||||
| `resetField` | Reset current field and remove validation result. | `() => void` |
|
||||
| `clearValidate` | Remove validation status of the field. | `() => void` |
|
||||
|
||||
@ -14,6 +14,8 @@ export const formItemValidateStates = [
|
||||
] as const
|
||||
export type FormItemValidateState = typeof formItemValidateStates[number]
|
||||
|
||||
export type FormItemProp = Arrayable<string>
|
||||
|
||||
export const formItemProps = buildProps({
|
||||
label: String,
|
||||
labelWidth: {
|
||||
@ -21,7 +23,7 @@ export const formItemProps = buildProps({
|
||||
default: '',
|
||||
},
|
||||
prop: {
|
||||
type: definePropType<Arrayable<string>>([String, Array]),
|
||||
type: definePropType<FormItemProp>([String, Array]),
|
||||
},
|
||||
required: {
|
||||
type: Boolean,
|
||||
|
||||
@ -257,7 +257,7 @@ const validate: FormItemContext['validate'] = async (trigger, callback) => {
|
||||
validateMessage.value = errors
|
||||
? errors[0].message || `${props.prop} is required`
|
||||
: ''
|
||||
formContext.emit('validate', props.prop, !errors, validateMessage.value)
|
||||
formContext.emit('validate', props.prop!, !errors, validateMessage.value)
|
||||
return Promise.reject(fields)
|
||||
})
|
||||
}
|
||||
|
||||
@ -8,7 +8,7 @@ import {
|
||||
} from '@element-plus/utils'
|
||||
|
||||
import type { ExtractPropTypes } from 'vue'
|
||||
import type { FormItemProps } from './form-item'
|
||||
import type { FormItemProp } from './form-item'
|
||||
import type { FormRules } from './types'
|
||||
import type Form from './form.vue'
|
||||
|
||||
@ -51,7 +51,7 @@ export const formProps = buildProps({
|
||||
export type FormProps = ExtractPropTypes<typeof formProps>
|
||||
|
||||
export const formEmits = {
|
||||
validate: (prop: FormItemProps['prop'], isValid: boolean, message: string) =>
|
||||
validate: (prop: FormItemProp, isValid: boolean, message: string) =>
|
||||
(isArray(prop) || isString(prop)) &&
|
||||
isBoolean(isValid) &&
|
||||
isString(message),
|
||||
|
||||
@ -14,6 +14,7 @@ import { useFormLabelWidth, filterFields } from './utils'
|
||||
import type { ValidateFieldsError } from 'async-validator'
|
||||
import type { FormItemContext, FormContext } from '@element-plus/tokens'
|
||||
import type { FormValidateCallback } from './types'
|
||||
import type { FormItemProp } from './form-item'
|
||||
|
||||
const COMPONENT_NAME = 'ElForm'
|
||||
defineOptions({
|
||||
@ -113,7 +114,7 @@ const validateField: FormContext['validateField'] = async (
|
||||
}
|
||||
}
|
||||
|
||||
const scrollToField = (prop: string) => {
|
||||
const scrollToField = (prop: FormItemProp) => {
|
||||
const field = filterFields(fields, prop)[0]
|
||||
if (field) {
|
||||
field.$el?.scrollIntoView()
|
||||
|
||||
@ -2,7 +2,7 @@ import { computed, ref } from 'vue'
|
||||
import { debugWarn, ensureArray } from '@element-plus/utils'
|
||||
import type { Arrayable } from '@element-plus/utils'
|
||||
import type { FormItemContext } from '@element-plus/tokens'
|
||||
import type { FormItemProps } from './form-item'
|
||||
import type { FormItemProp } from './form-item'
|
||||
|
||||
const SCOPE = 'ElForm'
|
||||
|
||||
@ -48,7 +48,7 @@ export function useFormLabelWidth() {
|
||||
|
||||
export const filterFields = (
|
||||
fields: FormItemContext[],
|
||||
props: Arrayable<FormItemProps['prop']>
|
||||
props: Arrayable<FormItemProp>
|
||||
) => {
|
||||
const normalized = ensureArray(props)
|
||||
return normalized.length > 0
|
||||
|
||||
@ -3,6 +3,7 @@ import type { ComponentSize } from '@element-plus/constants'
|
||||
import type {
|
||||
FormProps,
|
||||
FormEmits,
|
||||
FormItemProp,
|
||||
FormItemProps,
|
||||
FormValidateCallback,
|
||||
FormLabelWidthContext,
|
||||
@ -16,10 +17,10 @@ export type FormContext = FormProps &
|
||||
// expose
|
||||
addField: (field: FormItemContext) => void
|
||||
removeField: (field: FormItemContext) => void
|
||||
resetFields: (props?: Arrayable<string>) => void
|
||||
clearValidate: (props?: Arrayable<string>) => void
|
||||
resetFields: (props?: Arrayable<FormItemProp>) => void
|
||||
clearValidate: (props?: Arrayable<FormItemProp>) => void
|
||||
validateField: (
|
||||
props?: Arrayable<string>,
|
||||
props?: Arrayable<FormItemProp>,
|
||||
callback?: FormValidateCallback
|
||||
) => Promise<void>
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user