Form form
introduce
Used for data entry and verification. It supports input boxes, radio boxes, check boxes, file uploads, etc. It needs to be used in conjunction with the Field input box component.
Code Demo
Basic usage
In the form, each Field component represents a form item, and the validation rules are defined using the rules
attribute of the Field.
<z-form ref="formBasic" @submit="onSubmitBasic">
<z-field
v-model="username"
name="username"
label="username"
placeholder="username"
:rules="[{ required: true, message: 'Please fill in your username' }]"
/>
<z-field
v-model="password"
type="password"
name="password"
label="password"
placeholder="password"
:rules="[{ required: true, message: 'Please fill in your password' }]"
/>
</z-form>
<view class="button">
<z-button block type="primary" @click="submitFormBasic">
submit
</z-button>
</view>
import { ref } from 'vue';
const username = ref('')
const password = ref('')
const onSubmitBasic = (values: any) => {
console.log('submit', values)
}
<style lang="scss" scoped>
.demo-form {
.button {
margin-top: 20rpx;
}
}
</style>
Verification rules
Define form validation rules through rules
. All available fields are shown in table below.
<z-form @failed="onFailed">
<z-cell-group inset>
<!-- Regularity verification through pattern -->
<z-field
v-model="value1"
name="pattern"
placeholder="Regular check"
:rules="[{ pattern, message: 'Please enter the correct content' }]"
/>
<!-- Function verification through validator -->
<z-field
v-model="value2"
name="validator"
placeholder="function check"
:rules="[{ validator, message: 'Please enter the correct content' }]"
/>
<!-- Return error message through validator -->
<z-field
v-model="value3"
name="validatorMessage"
placeholder="The verification function returns an error message"
:rules="[{ validator: validatorMessage }]"
/>
<!-- Asynchronous function verification through validator -->
<z-field
v-model="value4"
name="asyncValidator"
placeholder="Asynchronous function verification"
:rules="[{ validator: asyncValidator, message: 'Please enter the correct content' }]"
/>
</z-cell-group>
<div style="margin: 16px;">
<z-button round block type="primary" native-type="submit">
submit
</z-button>
</div>
</z-form>
import { ref } from 'vue';
import { useToast } from '../../uni_modules/zebra-ui'
const toast = useToast()
const value1 = ref('')
const value2 = ref('')
const value3 = ref('abc')
const value4 = ref('')
const pattern = /\d{6}/
const validator = (val: any) => /1\d{10}/.test(val)
const validatorMessage = (val: any) => `${val} is illegal, please re-enter`
const asyncValidator = (val: any) =>
new Promise((resolve) => {
toast.showLoadingToast('Verifying...')
setTimeout(() => {
toast.closeToast()
resolve(val === '1234')
}, 1000)
})
const onFailed = (errorInfo: any) => {
console.log('failed', errorInfo)
}
Form item type - switch
Use the Switch component in your form.
<z-field name="switch" label="switch">
<template #input>
<z-switch v-model="switchChecked" />
</template>
</z-field>
Form item type - checkbox
Use the Checkbox component in your form.
<z-field name="checkbox" label="checkbox">
<template #input>
<z-checkbox v-model="checked" shape="square" />
</template>
</z-field>
<z-field name="checkboxGroup" label="checkbox group">
<template #input>
<z-checkbox-group v-model="groupChecked" direction="horizontal">
<z-checkbox name="1" shape="square">Checkbox 1</z-checkbox>
<z-checkbox name="2" shape="square">Checkbox 2</z-checkbox>
</z-checkbox-group>
</template>
</z-field>
Form item type - radio button
Use the Radio component in your form.
<z-field name="radio" label="radio button">
<template #input>
<z-radio-group v-model="checked" direction="horizontal">
<z-radio name="1">Radio button 1</z-radio>
<z-radio name="2">Radio button 2</z-radio>
</z-radio-group>
</template>
</z-field>
Form item type - stepper
Use the Stepper component in your form.
<z-field name="stepper" label="Stepper">
<template #input>
<z-stepper v-model="value" />
</template>
</z-field>
Form Item Type - Rating
Use the Rate component in your form.
<z-field name="rate" label="rating">
<template #input>
<z-rate v-model="value" />
</template>
</z-field>
Form Item Type - Slider
Use the Slider component in your form.
<z-field name="slider" label="Slider">
<template #input>
<z-slider v-model="value" />
</template>
</z-field>
Form item type - file upload
Use the Uploader component in your form.
<z-field name="uploader" label="File upload">
<template #input>
<z-uploader v-model="value" />
</template>
</z-field>
Form item type - selector
Use the Picker component in your form.
<z-field
v-model="result"
is-link
readonly
name="picker"
label="selector"
placeholder="Click to select city"
@click="showPicker = true"
/>
<z-popup v-model:show="showPicker" position="bottom">
<z-picker
:columns="columns"
@confirm="onConfirm"
@cancel="showPicker = false"
/>
</z-popup>
Form Item Type - Date Picker
Use the DatePicker component in your form.
<z-field
v-model="result"
is-link
readonly
name="datePicker"
label="Time selection"
placeholder="Click to select time"
@click="showPicker = true"
/>
<z-popup v-model:show="showPicker" position="bottom">
<z-date-picker @confirm="onConfirm" @cancel="showPicker = false" />
</z-popup>
Form item type - Province and city selector
Use the Area component in your form.
<z-field v-model="result"
is-link
readonly
name="area"
label="region selection"
placeholder="Click to select province and city"
@click="showArea = true"
/>
<z-popup v-model:show="showArea" position="bottom">
<z-area
:area-list="areaList"
@confirm="onConfirm"
@cancel="showArea = false"
/>
</z-popup>
Form Item Type - Calendar
Use the Calendar component in your form.
<z-field
v-model="result"
is-link
readonly
name="calendar"
label="calendar"
placeholder="Click to select date"
@click="showCalendar = true"
/>
<z-calendar v-model:show="showCalendar" @confirm="onConfirm" />
API
Props
Parameters | Description | Type | Default value |
---|---|---|---|
label-width | Form item label width, default unit is px | number | string | 6.2em |
label-align | Form item label alignment, optional values are center right top | string | left |
input-align | Input box alignment, optional values are center right | string | left |
error-message-align | Error text alignment, optional values are center right | string | left |
validate-trigger | Form verification trigger timing, optional values are onChange , onSubmit , supports setting multiple values at the same time through arrays, specific usage is shown in the table below | string | string | onBlur |
colon | Whether to add a colon after label | boolean | false |
disabled | Whether to disable all input boxes in the form | boolean | false |
readonly | Whether to set all input boxes in the form to read-only | boolean | false |
required | Whether to display the form required asterisk | boolean | 'auto' | null |
validate-first | Whether to stop verification when a certain verification item fails | boolean | false |
scroll-to-error | Whether to scroll to the wrong form item when the form is submitted and validation fails | boolean | false |
show-error | Whether to mark the input box red when the verification fails | boolean | false |
show-error-message | Whether to display an error message below the input box when the verification fails | boolean | true |
submit-on-enter | Whether to submit the form when the enter key is pressed | boolean | true |
For the API of form items, see: Field component
Rule data structure
Validation rules can be defined using the rules
attribute of Field. The optional attributes are as follows:
Key name | Description | Type |
---|---|---|
required | Whether it is a required field. When the value is a null value (empty string, empty array, false , undefined , null ), the verification fails | boolean |
message | Error message copy, which can be set as a function to return dynamic copy content | string | (value, rule) => string |
validator | Verify through functions, you can return a Promise for asynchronous verification | (value, rule) => boolean | string | Promise |
pattern | Verification is performed through regular expressions. If the regular expression cannot be matched, the verification fails | RegExp |
trigger | Set the triggering time of this rule. The priority is higher than the validate-trigger attribute set by the Form component. The optional values are onChange , onBlur , onSubmit | string | string |
formatter | Formatting function, converts the value of the form item and then verifies it | (value, rule) => any |
validateEmpty | Set whether validator and pattern should be used to verify empty values. The default value is true and can be set to false to disable this behavior | boolean |
validate-trigger optional value
The trigger timing of form validation can be customized through the validate-trigger
attribute.
value | description |
---|---|
onSubmit | Validation is only triggered when the form is submitted |
onBlur | Trigger validation when the form is submitted and the input box is out of focus |
onChange | Trigger verification when the form is submitted and the content of the input box changes |
Events
Event name | Description | Callback parameters |
---|---|---|
submit | Triggered after the form is submitted and verification passes | values: object |
failed | Triggered after the form is submitted and verification fails | errorInfo: { values: object, errors: object } |
method
Through ref, you can get the Form instance and call instance methods.
Method name | Description | Parameters | Return value |
---|---|---|---|
submit | Submit the form, which is equivalent to clicking the submit button | - | - |
getValues | Get the current values of all form items | - | Record<string, unknown> |
validate | Validation form, supports passing in one or more name to validate single or partial form items. When name is not passed in, all form items will be verified | name?: string | string | Promise <void> |
resetValidation | Reset the validation prompt of form items. It supports passing in one or more name to reset single or partial form items. If name is not passed in, all form items will be reset | _name?: string \ | string_ |
getValidationStatus | Get the validation status of all form items, the status includes passed , failed , unvalidated | - | Record<string, FieldValidationStatus> |
Slots
Name | Description |
---|---|
default | form content |