From 0c62a706c225c55e833c05815aab4ffab552f593 Mon Sep 17 00:00:00 2001 From: "1445654576@qq.com" <1445654576@qq.com> Date: Sat, 1 Jan 2022 14:44:02 +0800 Subject: [PATCH 1/2] =?UTF-8?q?feat:=20=E5=A2=9E=E5=8A=A0=E8=8B=B1?= =?UTF-8?q?=E6=96=87=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../docs/en-US/components/form/index.md | 1678 +++++++++++++++++ 1 file changed, 1678 insertions(+) create mode 100644 packages/devui-vue/docs/en-US/components/form/index.md diff --git a/packages/devui-vue/docs/en-US/components/form/index.md b/packages/devui-vue/docs/en-US/components/form/index.md new file mode 100644 index 0000000000..ef57ae3473 --- /dev/null +++ b/packages/devui-vue/docs/en-US/components/form/index.md @@ -0,0 +1,1678 @@ +# Form + +A form that supports data collection, verification, and submission, including check boxes, option boxes, text boxes, and drop-down list boxes. + +### When to use + +Used for data collection, data verification, and data submission. + + + +### Basic usage + +In basic usage, the label is above the data box. + + +:::demo + +```vue + + + + + + + +``` + +::: + + +### Label horizontal arrangement + +Left-right layout of labels. + + +:::demo + +```vue + + + + + + + +``` + +::: + + +### Pop-up form + +> todo
+> To replace it with Modal component + +Pop-up form. The recommended pop-up box size is 400px, 550px, 700px, and 900px. The recommended aspect ratio is 16:9 or 3:2. + + +:::demo + +```vue + + + + + + + +``` + +::: + + +### Multiple Lists + +Multiple lists.The value of layout should be `columns` ，together with the columnsclass attribute, and the value should be "u - [row] - [column]".For example, 'u-1-3' is 1 row and 3 columns. + + +:::demo + +```vue + + + + + + +``` + +::: + + + +### Template driven form validation + +Use the `v-d-validate-rules` derective on form components such as `d-form` and `d-input` to configure verification rules. + + +#### Verify a single element, use the built-in validator, and configure error message + +The following built-in validators are currently supported by DevUI：`required`,`minlength`,`maxlength`,`min`,`max`,`requiredTrue`,`email`,`pattern`,`whitespace`. + +- To limit user input to not all spaces, use the `whitespace`built-in validator +- Setting the maximum limit to the actual check value `+1` is a good way to limit the length of user input. +- In addition to pattern, other built-in validators also provide built-in error alerts, which are used by default when you do not customize them. + +- The message configuration supports both string and object forms (supports internationalized term configurations such as `'zh-cn'`, which defaults to `'default'`). + +:::demo + +```vue + + + + + + + +``` + +::: + +#### Validate individual elements, customize validators + +Custom validators, which pass in `validators` field configuration checking rules, can simply return `true | false ` to identify whether the current check passes, to identify whether the current error is present, and to return an error message, suitable for dynamic error prompts. If it is an asynchronous validator, you can pass in the `asyncValidators` field to configure the validation rules. + +:::demo + +```vue + + + + + + + +``` + +::: + +#### Verify a single element. The update policy errorStrategy is incorrectly configured and the validation moment updateOn is incorrectly configured. + +- Set whether the `errorStrategy` property is checked when it is initialized + - Default configuration is `dirty`, check does not pass error prompt + - If you need to throw an error at initialization, configure it as `pristine` + +- Set `updateOn`, specify the time of the check + - Checker `updateOn` based on the `updateOn` settings of the model you are binding, you can specify them through `options`, defaulting to `change` + - Optional values are also `blur, ` `input`, `submit` + - Set to `submit`, then the check will be triggered when the form in which the element resides submits + +:::demo + +```vue + + + + + + + +``` + +::: + +#### Verify a single element and customize management message prompts + +Configure `messageShowType` to choose how messages are automatically prompted, defaulting to `popover`. + +- Set to `popover` error message will appear as `popover` when the element is focused. +- Set to `text` error messages will automatically appear as text beneath the element (required with the form control container). +- Error message set to `none` will not be automatically rendered to the view. +- Configure `popPosition` in `options` to customize `popover` content pop-up direction when the message prompt is `popover`, defaulting to `['right','bottom']`. More values refer to the Popover component. + +:::demo + +```vue + + + + + + + +``` + +::: + + + +#### Verify a single element and customize asyncDebounceTime + + +For asynchronous validators, a default of 300ms debounce time is provided. Set `asyncDebounceTime`(ms) display settings in options. + + +:::demo + +```vue + + + + + + + +``` + +::: + + + +#### Form Validation and Submission + +To validate when you click the submit button, you need to specify the name property and also bind the submit event of the `d-form` component to take effect. + +:::demo + +```vue + + + + + + + +``` + +::: + +#### Form verification and submission, user registration scenario + +For automatic error prompting, it is recommended that `messageShowType` be set uniformly at the `d-form` component in the form, and ref property must be set at the same time to take effect. + + +:::demo + +```vue + + + + + + + +``` + +::: + +### Reactive form validation + +Specify the validate rules in the `d-form` component and the value of `prop` in the `d-form-item` is the validate field name. + + +:::demo + +```vue + + + + + + + +``` + +::: + + +### Feedback status of a specified form + +You can manually specify the feedback status by setting `feedbackStatus` for `d-form-control`. Currently, the following statuses are supported: `success`, `error`, and `pending`. + + +:::demo + +```vue + + + + + + + +``` + +::: + + +You can customize the feedback status icon in `d-form-control` by `suffixTemplate` to a named slot. + + +:::demo + +```vue + + + + +``` + +::: + + +### Form collaboration verification + +In some scenarios, your multiple form components depend on each other and need to be checked together (for example, password entry and confirmation in registration scenarios) and implemented with a custom checker (comparing password entry with the value of confirmation). + + +:::demo + +```vue + + + + + + +``` + +::: + +### Cross-component verification + +> todo + + + + +:::demo + +```vue + + + + + + +``` +::: + + + +### API + +d-form Attribute + +| Attribute | Type | Default | Description | Jump to Demo | +| ------------- | ------------------------------------- | ------------ | ------------------------------------------------------------ | ----------------------------------------------------- | +| name | string | | Optional, set the form name property. Required for form submission validation. | [Basic usage](#basic-usage) | +| formData | object | | Required, form data | [Basic usage](#basic-usage) | +| layout | 'horizontal' \|'vertical' \|'columns' | 'horizontal' | Optional, set the way the forms are arranged | [Basic usage](#basic-usage) | +| labelSize | 'sm' \|'lg' | | Optional, set the width of label, no default of 100px, sm is 80px,lg is 150px | [Basic usage](#basic-usage) | +| labelAlign | 'start' \|'center' \|'end' | 'start' | Optional, set horizontal layout, label alignment | [Basic usage](#basic-usage) | +| columnsClass | string | | Optional, set multi-list style | [Multiple Lists](#multiple-lists) | +| rules | object | | Optional, set form validate rules | [Reactive form validation](#reactive-form-validation) | + + + +d-form Event + +| Event Name | Type | Description | Jump to Demo | +| ---------- | ---------- | ------------------ | --------------------------------- | +| submit | () => void | Optional, submit form events | [Form Validation and Submission](#Form Validation and Submission) | + + + +d-form-item Attribute + +| Attribute | Type | Default | Description | Jump to Demo | +| ------------- | ------- | ------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| prop | string | | Optional, specify the field to validate the form and select this property when validating the form | [Basic usage](#basic-usage) | +| dHasFeedback | boolean | 'false' | Optional, set whether the current form-control displays feedback icons | [Feedback status of a specified form](#feedback-status-of-a-specified-form) | + + + +d-form-label Attribute + +| Attribute | Type | Default | Description | Jump to Demo | +| ------------- | ------- | ------- | ------------------------------------------------------------ | --------------------- | +| required | boolean | 'false' | Optional, is form item required | [Basic usage](#basic-usage) | +| hasHelp | boolean | 'false' | Optional, Whether form items need help | [Basic usage](#basic-usage) | +| helpTips | string | | Optional, the form item help guide prompt content needs to be used with `hasHelp`, and the value of `helpTips` cannot be an empty string for it to take effect. | [Basic usage](#basic-usage) | + + + +d-form-control Attribute + +| Attribute | Type | Default | Description | Jump to Demo | +| -------------- | ------- | ------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| extraInfo | string | | Optional, additional information, usually used to supplement the description of form options | [Basic usage](#basic-usage) | +| feedbackStatus | boolean | 'false' | Optional, manually specify current control status feedback | [Basic usage](#basic-usage) | +| suffixTemplate | string | | Optional, pass an icon template as input box suffix (passing in icon component via slot) | [Feedback status of a specified form](#feedback-status-of-a-specified-form) | + + + +### Directives + +v-d-validate-rules + +| Attribute | Type | Default | Description | Jump to Demo | +| ------------- | ------ | ------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| rules | object | | Required, form validate rules, see [async-validator](https://www.npmjs.com/package/async-validator) for more rules | [Template driven form validation](#template-driven-form-validation) | +| options | object | | Optional, options | [Template driven form validation](#template-driven-form-validation) | + +> This directive is only valid on form class components such as the `d-form` label or `d-input`. + + + +- The rules are written as follows + +```js +{[validatorKey]: validatorValue, message: 'some tip messages.'} +``` + +The current DevUI-supported built-in validator keys are: `required`, `minlength`, `maxlength`, `min`, `max`, `requiredTrue`, `email`, `pattern`, `whitespace`. More rule references [async-validator]( https://www.npmjs.com/package/async-validator). + + + +
+ +- options + - errorStrategy，error update policy：`dirty`(default)、`prestine` + + - updateOn，check timing，optional value：`change`(default)、 `blur`、 `input` + + - popPosition，customize `popover` content pop-up direction. The default is `['right','bottom']`, and more values refer to the Popover component. + + + +### Interface & Types + +IForm + +```typescript +export interface IForm { + formData: any + labelData: IFormLabel + formMitt: Emitter + rules: any + columnsClass: string + messageShowType: string +} +``` + + + +IFormLabel + +```typescript +export interface IFormLabel { + layout: string + labelSize: string + labelAlign: string +} +``` + + + +IFormItem + +```typescript +export interface IFormItem { + dHasFeedback: boolean + prop: string + formItemMitt: Emitter + resetField(): void +} +``` + + + +IFormControl + +```ty +export interface IFormControl { + feedbackStatus: string + extraInfo: string + formItemMitt: Emitter + resetField(): void +} +``` + From 0967421f7ee025fa04de50af965edb1723e37c51 Mon Sep 17 00:00:00 2001 From: "1445654576@qq.com" <1445654576@qq.com> Date: Sun, 2 Jan 2022 21:11:23 +0800 Subject: [PATCH 2/2] =?UTF-8?q?fix:=20=E4=BF=AE=E5=A4=8Dmd=E4=BB=A3?= =?UTF-8?q?=E7=A0=81=E7=89=87=E6=AE=B5=E8=AF=AD=E6=B3=95=E9=94=99=E8=AF=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- packages/devui-vue/docs/en-US/components/form/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/devui-vue/docs/en-US/components/form/index.md b/packages/devui-vue/docs/en-US/components/form/index.md index ef57ae3473..5bb205bb6e 100644 --- a/packages/devui-vue/docs/en-US/components/form/index.md +++ b/packages/devui-vue/docs/en-US/components/form/index.md @@ -1667,7 +1667,7 @@ export interface IFormItem { IFormControl -```ty +```typescript export interface IFormControl { feedbackStatus: string extraInfo: string