mirror of
https://gitee.com/vant-contrib/vant.git
synced 2025-06-17 10:19:16 +08:00
530 lines
11 KiB
Markdown
530 lines
11 KiB
Markdown
# Form
|
||
|
||
### Install
|
||
|
||
```js
|
||
import { createApp } from 'vue';
|
||
import { Form } from 'vant';
|
||
|
||
const app = createApp();
|
||
app.use(Form);
|
||
```
|
||
|
||
## Usage
|
||
|
||
### Basic Usage
|
||
|
||
```html
|
||
<van-form @submit="onSubmit">
|
||
<van-field
|
||
v-model="state.username"
|
||
name="Username"
|
||
label="Username"
|
||
placeholder="Username"
|
||
:rules="[{ required: true, message: 'Username is required' }]"
|
||
/>
|
||
<van-field
|
||
v-model="state.password"
|
||
type="password"
|
||
name="Password"
|
||
label="Password"
|
||
placeholder="Password"
|
||
:rules="[{ required: true, message: 'Password is required' }]"
|
||
/>
|
||
<div style="margin: 16px;">
|
||
<van-button round block type="primary" native-type="submit">
|
||
Submit
|
||
</van-button>
|
||
</div>
|
||
</van-form>
|
||
```
|
||
|
||
```js
|
||
import { reactive } from 'vue';
|
||
|
||
export default {
|
||
setup() {
|
||
const state = reactive({
|
||
username: '',
|
||
password: '',
|
||
});
|
||
const onSubmit = (values) => {
|
||
console.log('submit', values);
|
||
};
|
||
|
||
return {
|
||
state,
|
||
onSubmit,
|
||
};
|
||
},
|
||
};
|
||
```
|
||
|
||
### Validate Rules
|
||
|
||
```html
|
||
<van-form validate-first @failed="onFailed">
|
||
<van-field
|
||
v-model="state.value1"
|
||
name="pattern"
|
||
placeholder="USe pattern"
|
||
:rules="[{ pattern, message: 'Error message' }]"
|
||
/>
|
||
<van-field
|
||
v-model="state.value2"
|
||
name="validator"
|
||
placeholder="Use validator"
|
||
:rules="[{ validator, message: 'Error message' }]"
|
||
/>
|
||
<van-field
|
||
v-model="state.value3"
|
||
name="asyncValidator"
|
||
placeholder="Use async validator"
|
||
:rules="[{ validator: asyncValidator, message: 'Error message' }]"
|
||
/>
|
||
<div style="margin: 16px;">
|
||
<van-button round block type="primary" native-type="submit">
|
||
Submit
|
||
</van-button>
|
||
</div>
|
||
</van-form>
|
||
```
|
||
|
||
```js
|
||
import { reactive } from 'vue';
|
||
import { Toast } from 'vant';
|
||
|
||
export default {
|
||
setup() {
|
||
const state = reactive({
|
||
value1: '',
|
||
value2: '',
|
||
value3: '',
|
||
});
|
||
const pattern = /\d{6}/;
|
||
|
||
const validator = (val) => /1\d{10}/.test(val);
|
||
|
||
const asyncValidator = (val) =>
|
||
new Promise((resolve) => {
|
||
Toast.loading('Validating...');
|
||
|
||
setTimeout(() => {
|
||
Toast.clear();
|
||
resolve(/\d{6}/.test(val));
|
||
}, 1000);
|
||
});
|
||
|
||
const onFailed = (errorInfo) => {
|
||
console.log('failed', errorInfo);
|
||
};
|
||
|
||
return {
|
||
state,
|
||
pattern,
|
||
onFailed,
|
||
validator,
|
||
asyncValidator,
|
||
};
|
||
},
|
||
};
|
||
```
|
||
|
||
### Field Type - Switch
|
||
|
||
```html
|
||
<van-field name="switch" label="Switch">
|
||
<template #input>
|
||
<van-switch v-model="checked" size="20" />
|
||
</template>
|
||
</van-field>
|
||
```
|
||
|
||
```js
|
||
import { ref } from 'vue';
|
||
|
||
export default {
|
||
setup() {
|
||
const checked = ref(false);
|
||
return { checked };
|
||
},
|
||
};
|
||
```
|
||
|
||
### Field Type - Checkbox
|
||
|
||
```html
|
||
<van-field name="checkbox" label="Checkbox">
|
||
<template #input>
|
||
<van-checkbox v-model="checked" shape="square" />
|
||
</template>
|
||
</van-field>
|
||
<van-field name="checkboxGroup" label="CheckboxGroup">
|
||
<template #input>
|
||
<van-checkbox-group v-model="groupChecked" direction="horizontal">
|
||
<van-checkbox name="1" shape="square">Checkbox 1</van-checkbox>
|
||
<van-checkbox name="2" shape="square">Checkbox 2</van-checkbox>
|
||
</van-checkbox-group>
|
||
</template>
|
||
</van-field>
|
||
```
|
||
|
||
```js
|
||
import { ref } from 'vue';
|
||
|
||
export default {
|
||
setup() {
|
||
const checked = ref(false);
|
||
const groupChecked = ref([]);
|
||
return {
|
||
checked,
|
||
groupChecked,
|
||
};
|
||
},
|
||
};
|
||
```
|
||
|
||
### Field Type - Radio
|
||
|
||
```html
|
||
<van-field name="radio" label="Radio">
|
||
<template #input>
|
||
<van-radio-group v-model="checked" direction="horizontal">
|
||
<van-radio name="1">Radio 1</van-radio>
|
||
<van-radio name="2">Radio 2</van-radio>
|
||
</van-radio-group>
|
||
</template>
|
||
</van-field>
|
||
```
|
||
|
||
```js
|
||
import { ref } from 'vue';
|
||
|
||
export default {
|
||
setup() {
|
||
const checked = ref('1');
|
||
return { checked };
|
||
},
|
||
};
|
||
```
|
||
|
||
### Field Type - Stepper
|
||
|
||
```html
|
||
<van-field name="stepper" label="Stepper">
|
||
<template #input>
|
||
<van-stepper v-model="value" />
|
||
</template>
|
||
</van-field>
|
||
```
|
||
|
||
```js
|
||
import { ref } from 'vue';
|
||
|
||
export default {
|
||
setup() {
|
||
const value = ref(1);
|
||
return { value };
|
||
},
|
||
};
|
||
```
|
||
|
||
### Field Type - Rate
|
||
|
||
```html
|
||
<van-field name="rate" label="Rate">
|
||
<template #input>
|
||
<van-rate v-model="value" />
|
||
</template>
|
||
</van-field>
|
||
```
|
||
|
||
```js
|
||
import { ref } from 'vue';
|
||
|
||
export default {
|
||
setup() {
|
||
const value = ref(3);
|
||
return { value };
|
||
},
|
||
};
|
||
```
|
||
|
||
### Field Type - Slider
|
||
|
||
```html
|
||
<van-field name="slider" label="Slider">
|
||
<template #input>
|
||
<van-slider v-model="value" />
|
||
</template>
|
||
</van-field>
|
||
```
|
||
|
||
```js
|
||
import { ref } from 'vue';
|
||
|
||
export default {
|
||
setup() {
|
||
const value = ref(50);
|
||
return { value };
|
||
},
|
||
};
|
||
```
|
||
|
||
### Field Type - Uploader
|
||
|
||
```html
|
||
<van-field name="uploader" label="Uploader">
|
||
<template #input>
|
||
<van-uploader v-model="value" />
|
||
</template>
|
||
</van-field>
|
||
```
|
||
|
||
```js
|
||
import { ref } from 'vue';
|
||
|
||
export default {
|
||
setup() {
|
||
const value = ref([{ url: 'https://img.yzcdn.cn/vant/leaf.jpg' }]);
|
||
return { value };
|
||
},
|
||
};
|
||
```
|
||
|
||
### Field Type - Picker
|
||
|
||
```html
|
||
<van-field
|
||
v-model="state.value"
|
||
readonly
|
||
clickable
|
||
name="picker"
|
||
label="Picker"
|
||
placeholder="Select city"
|
||
@click="state.showPicker = true"
|
||
/>
|
||
<van-popup v-model:show="state.showPicker" position="bottom">
|
||
<van-picker
|
||
:columns="columns"
|
||
@confirm="onConfirm"
|
||
@cancel="state.showPicker = false"
|
||
/>
|
||
</van-popup>
|
||
```
|
||
|
||
```js
|
||
import { reactive } from 'vue';
|
||
|
||
export default {
|
||
setup() {
|
||
const state = reactive({
|
||
value: '',
|
||
showPicker: false,
|
||
});
|
||
const columns = ['Delaware', 'Florida', 'Georqia', 'Indiana', 'Maine'];
|
||
|
||
const onConfirm = (value) => {
|
||
state.value = value;
|
||
state.showPicker = false;
|
||
};
|
||
|
||
return {
|
||
state,
|
||
columns,
|
||
onConfirm,
|
||
};
|
||
},
|
||
};
|
||
```
|
||
|
||
### Field Type - DatetimePicker
|
||
|
||
```html
|
||
<van-field
|
||
v-model="state.value"
|
||
readonly
|
||
clickable
|
||
name="datetimePicker"
|
||
label="Datetime Picker"
|
||
placeholder="Select time"
|
||
@click="state.showPicker = true"
|
||
/>
|
||
<van-popup v-model:show="state.showPicker" position="bottom">
|
||
<van-datetime-picker
|
||
type="time"
|
||
@confirm="onConfirm"
|
||
@cancel="state.showPicker = false"
|
||
/>
|
||
</van-popup>
|
||
```
|
||
|
||
```js
|
||
import { reactive } from 'vue';
|
||
|
||
export default {
|
||
setup() {
|
||
const state = reactive({
|
||
value: '',
|
||
showPicker: false,
|
||
});
|
||
const onConfirm = (value) => {
|
||
state.value = value;
|
||
state.showPicker = false;
|
||
};
|
||
|
||
return {
|
||
state,
|
||
onConfirm,
|
||
};
|
||
},
|
||
};
|
||
```
|
||
|
||
### Field Type - Area
|
||
|
||
```html
|
||
<van-field
|
||
v-model="state.value"
|
||
readonly
|
||
clickable
|
||
name="area"
|
||
label="Area Picker"
|
||
placeholder="Select area"
|
||
@click="state.showArea = true"
|
||
/>
|
||
<van-popup v-model:show="state.showArea" position="bottom">
|
||
<van-area
|
||
:area-list="areaList"
|
||
@confirm="onConfirm"
|
||
@cancel="state.showArea = false"
|
||
/>
|
||
</van-popup>
|
||
```
|
||
|
||
```js
|
||
import { reactive } from 'vue';
|
||
|
||
export default {
|
||
setup() {
|
||
const state = reactive({
|
||
value: '',
|
||
showArea: false,
|
||
});
|
||
const onConfirm = (value) => {
|
||
state.showArea = false;
|
||
state.value = values
|
||
.filter((item) => !!item)
|
||
.map((item) => item.name)
|
||
.join('/');
|
||
};
|
||
|
||
return {
|
||
state,
|
||
areaList: {},
|
||
onConfirm,
|
||
};
|
||
},
|
||
};
|
||
```
|
||
|
||
### Field Type - Calendar
|
||
|
||
```html
|
||
<van-field
|
||
v-model="state.value"
|
||
readonly
|
||
clickable
|
||
name="calendar"
|
||
label="Calendar"
|
||
placeholder="Select date"
|
||
@click="state.showCalendar = true"
|
||
/>
|
||
<van-calendar v-model="state.showCalendar" @confirm="onConfirm" />
|
||
```
|
||
|
||
```js
|
||
import { reactive } from 'vue';
|
||
|
||
export default {
|
||
setup() {
|
||
const state = reactive({
|
||
value: '',
|
||
showCalendar: false,
|
||
});
|
||
const onConfirm = (date) => {
|
||
state.value = `${date.getMonth() + 1}/${date.getDate()}`;
|
||
state.showCalendar = false;
|
||
};
|
||
|
||
return {
|
||
state,
|
||
onConfirm,
|
||
};
|
||
},
|
||
};
|
||
```
|
||
|
||
## API
|
||
|
||
### Props
|
||
|
||
| Attribute | Description | Type | Default |
|
||
| --- | --- | --- | --- |
|
||
| label-width | Field label width | _number \| string_ | `6.2em` |
|
||
| label-align | Field label align, can be set to `center` `right` | _string_ | `left` |
|
||
| input-align | Field input align, can be set to `center` `right` | _string_ | `left` |
|
||
| error-message-align | Error message align, can be set to `center` `right` | _string_ | `left` |
|
||
| validate-trigger `v2.5.2` | When to validate the form，can be set to `onChange`、`onSubmit` | _string_ | `onBlur` |
|
||
| colon | Whether to display colon after label | _boolean_ | `false` |
|
||
| disabled `v2.12.2` | Whether to disable form | _boolean_ | `false` |
|
||
| readonly `v2.12.2` | Whether to be readonly | _boolean_ | `false` |
|
||
| validate-first | Whether to stop the validation when a rule fails | _boolean_ | `false` |
|
||
| scroll-to-error `v2.5.2` | Whether to scroll to the error field when validation failed | _boolean_ | `false` |
|
||
| show-error `v2.6.0` | Whether to highlight input when validation failed | _boolean_ | `true` |
|
||
| show-error-message `v2.5.8` | Whether to show error message when validation failed | _boolean_ | `true` |
|
||
| submit-on-enter `v2.8.3` | Whether to submit form on enter | _boolean_ | `true` |
|
||
|
||
### Data Structure of Rule
|
||
|
||
| Key | Description | Type |
|
||
| --- | --- | --- |
|
||
| required | Whether to be a required field | _boolean_ |
|
||
| message `v2.5.3` | Error message | _string \| (value, rule) => string_ |
|
||
| validator `v2.5.3` | Custom validator | _(value, rule) => boolean \| Promise_ |
|
||
| pattern `v2.5.3` | Regex pattern | _RegExp_ |
|
||
| trigger `v2.5.2` | When to validate the form，can be set to `onChange`、`onBlur` | _string_ |
|
||
| formatter `v2.5.3` | Format value before validate | _(value, rule) => any_ |
|
||
|
||
### validate-trigger
|
||
|
||
| Value | Description |
|
||
| -------- | --------------------------------------------------------------- |
|
||
| onSubmit | Trigger validation after submiting form |
|
||
| onBlur | Trigger validation after submiting form or bluring input |
|
||
| onChange | Trigger validation after submiting form or changing input value |
|
||
|
||
### Events
|
||
|
||
| Event | Description | Arguments |
|
||
| --- | --- | --- |
|
||
| submit | Emitted after submitting the form and validation passed | _values: object_ |
|
||
| failed | Emitted after submitting the form and validation failed | _errorInfo: { values: object, errors: object[] }_ |
|
||
|
||
### Methods
|
||
|
||
Use [ref](https://v3.vuejs.org/guide/component-template-refs.html) to get Form instance and call instance methods.
|
||
|
||
| Name | Description | Attribute | Return value |
|
||
| --- | --- | --- | --- |
|
||
| submit | Submit form | - | - |
|
||
| validate | Validate form | _name?: string \| string[]_ | _Promise_ |
|
||
| resetValidation | Reset validation | _name?: string \| string[]_ | - |
|
||
| scrollToField `v2.8.3` | Scroll to field | _name: string, alignToTop: boolean_ | - |
|
||
|
||
### Slots
|
||
|
||
| Name | Description |
|
||
| ------- | ------------ |
|
||
| default | Form content |
|