用于數(shù)據(jù)錄入、校驗(yàn),支持輸入框、單選框、復(fù)選框、文件上傳等類型,需要與 Field 輸入框 組件搭配使用。
通過以下方式來全局注冊(cè)組件,更多注冊(cè)方式請(qǐng)參考組件注冊(cè)。
import { createApp } from 'vue';
import { Form, Field, CellGroup } from 'vant';
const app = createApp();
app.use(Form);
app.use(Field);
app.use(CellGroup);
在表單中,每個(gè) Field 組件 代表一個(gè)表單項(xiàng),使用 Field 的 rules 屬性定義校驗(yàn)規(guī)則。
<van-form @submit="onSubmit">
<van-cell-group inset>
<van-field
v-model="state.username"
name="用戶名"
label="用戶名"
placeholder="用戶名"
:rules="[{ required: true, message: '請(qǐng)?zhí)顚懹脩裘? }]"
/>
<van-field
v-model="state.password"
type="password"
name="密碼"
label="密碼"
placeholder="密碼"
:rules="[{ required: true, message: '請(qǐng)?zhí)顚懨艽a' }]"
/>
</van-cell-group>
<div style="margin: 16px;">
<van-button round block type="primary" native-type="submit">
提交
</van-button>
</div>
</van-form>
import { reactive } from 'vue';
export default {
setup() {
const state = reactive({
username: '',
password: '',
});
const onSubmit = (values) => {
console.log('submit', values);
};
return {
state,
onSubmit,
};
},
};
通過 rules 定義表單校驗(yàn)規(guī)則,所有可用字段見下方表格。
<van-form @failed="onFailed">
<van-cell-group inset>
<!-- 通過 pattern 進(jìn)行正則校驗(yàn) -->
<van-field
v-model="state.value1"
name="pattern"
placeholder="正則校驗(yàn)"
:rules="[{ pattern, message: '請(qǐng)輸入正確內(nèi)容' }]"
/>
<!-- 通過 validator 進(jìn)行函數(shù)校驗(yàn) -->
<van-field
v-model="state.value2"
name="validator"
placeholder="函數(shù)校驗(yàn)"
:rules="[{ validator, message: '請(qǐng)輸入正確內(nèi)容' }]"
/>
<!-- 通過 validator 返回錯(cuò)誤提示 -->
<van-field
v-model="state.value3"
name="validatorMessage"
placeholder="校驗(yàn)函數(shù)返回錯(cuò)誤提示"
:rules="[{ validator: validatorMessage }]"
/>
<!-- 通過 validator 進(jìn)行異步函數(shù)校驗(yàn) -->
<van-field
v-model="state.value4"
name="asyncValidator"
placeholder="異步函數(shù)校驗(yàn)"
:rules="[{ validator: asyncValidator, message: '請(qǐng)輸入正確內(nèi)容' }]"
/>
</van-cell-group>
<div style="margin: 16px;">
<van-button round block type="primary" native-type="submit">
提交
</van-button>
</div>
</van-form>
import { reactive } from 'vue';
import { Toast } from 'vant';
export default {
setup() {
const state = reactive({
value1: '',
value2: '',
value3: '',
value4: '',
});
const pattern = /\d{6}/;
// 校驗(yàn)函數(shù)返回 true 表示校驗(yàn)通過,false 表示不通過
const validator = (val) => /1\d{10}/.test(val);
// 校驗(yàn)函數(shù)可以直接返回一段錯(cuò)誤提示
const validatorMessage = (val) => `${val} 不合法,請(qǐng)重新輸入`;
// 校驗(yàn)函數(shù)可以返回 Promise,實(shí)現(xiàn)異步校驗(yàn)
const asyncValidator = (val) =>
new Promise((resolve) => {
Toast.loading('驗(yàn)證中...');
setTimeout(() => {
Toast.clear();
resolve(/\d{6}/.test(val));
}, 1000);
});
const onFailed = (errorInfo) => {
console.log('failed', errorInfo);
};
return {
state,
pattern,
onFailed,
validator,
asyncValidator,
};
},
};
在表單中使用 Switch 組件。
<van-field name="switch" label="開關(guān)">
<template #input>
<van-switch v-model="checked" size="20" />
</template>
</van-field>
import { ref } from 'vue';
export default {
setup() {
const checked = ref(false);
return { checked };
},
};
在表單中使用 Checkbox 組件。
<van-field name="checkbox" label="復(fù)選框">
<template #input>
<van-checkbox v-model="checked" shape="square" />
</template>
</van-field>
<van-field name="checkboxGroup" label="復(fù)選框組">
<template #input>
<van-checkbox-group v-model="groupChecked" direction="horizontal">
<van-checkbox name="1" shape="square">復(fù)選框 1</van-checkbox>
<van-checkbox name="2" shape="square">復(fù)選框 2</van-checkbox>
</van-checkbox-group>
</template>
</van-field>
import { ref } from 'vue';
export default {
setup() {
const checked = ref(false);
const groupChecked = ref([]);
return {
checked,
groupChecked,
};
},
};
在表單中使用 Radio 組件。
<van-field name="radio" label="單選框">
<template #input>
<van-radio-group v-model="checked" direction="horizontal">
<van-radio name="1">單選框 1</van-radio>
<van-radio name="2">單選框 2</van-radio>
</van-radio-group>
</template>
</van-field>
import { ref } from 'vue';
export default {
setup() {
const checked = ref('1');
return { checked };
},
};
在表單中使用 Stepper 組件。
<van-field name="stepper" label="步進(jìn)器">
<template #input>
<van-stepper v-model="value" />
</template>
</van-field>
import { ref } from 'vue';
export default {
setup() {
const value = ref(1);
return { value };
},
};
在表單中使用 Rate 組件。
<van-field name="rate" label="評(píng)分">
<template #input>
<van-rate v-model="value" />
</template>
</van-field>
import { ref } from 'vue';
export default {
setup() {
const value = ref(3);
return { value };
},
};
在表單中使用 Slider 組件。
<van-field name="slider" label="滑塊">
<template #input>
<van-slider v-model="value" />
</template>
</van-field>
import { ref } from 'vue';
export default {
setup() {
const value = ref(50);
return { value };
},
};
在表單中使用 Uploader 組件。
<van-field name="uploader" label="文件上傳">
<template #input>
<van-uploader v-model="value" />
</template>
</van-field>
import { ref } from 'vue';
export default {
setup() {
const value = ref([{ url: 'https://img.yzcdn.cn/vant/leaf.jpg' }]);
return { value };
},
};
在表單中使用 Picker 組件。
<van-field
v-model="state.value"
readonly
clickable
name="picker"
label="選擇器"
placeholder="點(diǎn)擊選擇城市"
@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>
import { reactive } from 'vue';
export default {
setup() {
const state = reactive({
value: '',
showPicker: false,
});
const columns = ['杭州', '寧波', '溫州', '嘉興', '湖州'];
const onConfirm = (value) => {
state.value = value;
state.showPicker = false;
};
return {
state,
columns,
onConfirm,
};
},
};
在表單中使用 DatetimePicker 組件。
<van-field
v-model="state.value"
readonly
clickable
name="datetimePicker"
label="時(shí)間選擇"
placeholder="點(diǎn)擊選擇時(shí)間"
@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>
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,
};
},
};
在表單中使用 Area 組件。
<van-field
v-model="state.value"
readonly
clickable
name="area"
label="地區(qū)選擇"
placeholder="點(diǎn)擊選擇省市區(qū)"
@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>
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: {}, // 數(shù)據(jù)格式見 Area 組件文檔
onConfirm,
};
},
};
在表單中使用 Calendar 組件。
<van-field
v-model="state.value"
readonly
clickable
name="calendar"
label="日歷"
placeholder="點(diǎn)擊選擇日期"
@click="state.showCalendar = true"
/>
<van-calendar v-model:show="state.showCalendar" @confirm="onConfirm" />
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,
};
},
};
參數(shù) | 說明 | 類型 | 默認(rèn)值 |
---|---|---|---|
label-width | 表單項(xiàng) label 寬度,默認(rèn)單位為px
|
number | string | 6.2em
|
label-align | 表單項(xiàng) label 對(duì)齊方式,可選值為 center right
|
string | left
|
input-align | 輸入框?qū)R方式,可選值為 center right
|
string | left
|
error-message-align | 錯(cuò)誤提示文案對(duì)齊方式,可選值為 center right
|
string | left
|
validate-trigger | 表單校驗(yàn)觸發(fā)時(shí)機(jī),可選值為 onChange 、onSubmit ,詳見下表 |
string | onBlur
|
colon | 是否在 label 后面添加冒號(hào) | boolean | false
|
disabled | 是否禁用表單中的所有輸入框 | boolean | false
|
readonly | 是否將表單中的所有輸入框設(shè)置為只讀狀態(tài) | boolean | false
|
validate-first | 是否在某一項(xiàng)校驗(yàn)不通過時(shí)停止校驗(yàn) | boolean | false
|
scroll-to-error | 是否在提交表單且校驗(yàn)不通過時(shí)滾動(dòng)至錯(cuò)誤的表單項(xiàng) | boolean | false
|
show-error | 是否在校驗(yàn)不通過時(shí)標(biāo)紅輸入框 | boolean | false
|
show-error-message | 是否在校驗(yàn)不通過時(shí)在輸入框下方展示錯(cuò)誤提示 | boolean | true
|
submit-on-enter | 是否在按下回車鍵時(shí)提交表單 | boolean | true
|
表單項(xiàng)的 API 參見:Field 組件
使用 Field 的rules屬性可以定義校驗(yàn)規(guī)則,可選屬性如下:
鍵名 | 說明 | 類型 |
---|---|---|
required | 是否為必選字段 | boolean |
message | 錯(cuò)誤提示文案 | string | (value, rule) => string |
validator | 通過函數(shù)進(jìn)行校驗(yàn) | (value, rule) => boolean | string | Promise |
pattern | 通過正則表達(dá)式進(jìn)行校驗(yàn) | RegExp |
trigger | 本項(xiàng)規(guī)則的觸發(fā)時(shí)機(jī),可選值為 onChange 、onBlur
|
string |
formatter | 格式化函數(shù),將表單項(xiàng)的值轉(zhuǎn)換后進(jìn)行校驗(yàn) | (value, rule) => any |
通過 validate-trigger 屬性可以自定義表單校驗(yàn)的觸發(fā)時(shí)機(jī)。
值 | 描述 |
---|---|
onSubmit | 僅在提交表單時(shí)觸發(fā)校驗(yàn) |
onBlur | 在提交表單和輸入框失焦時(shí)觸發(fā)校驗(yàn) |
onChange | 在提交表單和輸入框內(nèi)容變化時(shí)觸發(fā)校驗(yàn) |
事件名 | 說明 | 回調(diào)參數(shù) |
---|---|---|
submit | 提交表單且驗(yàn)證通過后觸發(fā) | values: object |
failed | 提交表單且驗(yàn)證不通過后觸發(fā) | errorInfo: { values: object, errors: object[] } |
通過 ref 可以獲取到 Form 實(shí)例并調(diào)用實(shí)例方法,詳見組件實(shí)例方法。
方法名 | 說明 | 參數(shù) | 返回值 |
---|---|---|---|
submit | 提交表單,與點(diǎn)擊提交按鈕的效果等價(jià) | - | - |
validate | 驗(yàn)證表單,支持傳入 name 來驗(yàn)證單個(gè)或部分表單項(xiàng) |
name?: string | string[] | Promise |
resetValidation | 重置表單項(xiàng)的驗(yàn)證提示,支持傳入 name 來重置單個(gè)或部分表單項(xiàng) |
name?: string | string[] | - |
scrollToField | 滾動(dòng)到對(duì)應(yīng)表單項(xiàng)的位置,默認(rèn)滾動(dòng)到頂部,第二個(gè)參數(shù)傳 false 可滾動(dòng)至底部 | name: string, alignToTop: boolean | - |
名稱 | 說明 |
---|---|
default | 表單內(nèi)容 |
更多建議: