提供多个选项集合供用户选择,支持单列选择、多列选择和级联选择,通常与弹出层组件配合使用。
通过以下方式来全局注册组件,更多注册方式请参考组件注册。
import { createApp } from "vue";
import { Picker } from "vant";
const app = createApp();
app.use(Picker);
Picker 组件通过 columns
属性配置选项数据,columns
是一个包含字符串或对象的数组。
顶部栏包含标题、确认按钮和取消按钮,点击确认按钮触发 confirm
事件,点击取消按钮触发 cancel
事件。
<van-picker
title="标题"
:columns="columns"
@confirm="onConfirm"
@cancel="onCancel"
@change="onChange"
/>
import { showToast } from "vant";
export default {
setup() {
const columns = [
{ text: "杭州", value: "Hangzhou" },
{ text: "宁波", value: "Ningbo" },
{ text: "温州", value: "Wenzhou" },
{ text: "绍兴", value: "Shaoxing" },
{ text: "湖州", value: "Huzhou" },
];
const onConfirm = ({ selectedValues }) => {
showToast(`当前值: ${selectedValues.join(",")}`);
};
const onChange = ({ selectedValues }) => {
showToast(`当前值: ${selectedValues.join(",")}`);
};
const onCancel = () => showToast("取消");
return {
columns,
onChange,
onCancel,
onConfirm,
};
},
};
在实际场景中,Picker 通常作为用于辅助表单填写,可以搭配 Popup 和 Field 实现该效果。
<van-field
v-model="value"
is-link
readonly
label="城市"
placeholder="选择城市"
@click="showPicker = true"
/>
<van-popup v-model:show="showPicker" round position="bottom">
<van-picker
:columns="columns"
@cancel="showPicker = false"
@confirm="onConfirm"
/>
</van-popup>
import { ref } from "vue";
export default {
setup() {
const columns = [
{ text: "杭州", value: "Hangzhou" },
{ text: "宁波", value: "Ningbo" },
{ text: "温州", value: "Wenzhou" },
{ text: "绍兴", value: "Shaoxing" },
{ text: "湖州", value: "Huzhou" },
];
const result = ref("");
const showPicker = ref(false);
const onConfirm = ({ selectedOptions }) => {
showPicker.value = false;
fieldValue.value = selectedOptions[0].text;
};
return {
result,
columns,
onConfirm,
showPicker,
};
},
};
通过 v-model
可以绑定当前选中项的 values
,修改 v-model
绑定的值时,Picker 的选中状态也会随之改变。
v-model
的值是一个数组,数组的第一位对应第一列选中项的 value
,第二位对应第二列选中项的 value
,以此类推。
<van-picker v-model="selectedValues" title="标题" :columns="columns" />
import { showToast } from "vant";
export default {
setup() {
const columns = [
{ text: "杭州", value: "Hangzhou" },
{ text: "宁波", value: "Ningbo" },
{ text: "温州", value: "Wenzhou" },
{ text: "绍兴", value: "Shaoxing" },
{ text: "湖州", value: "Huzhou" },
];
const selectedValues = ref(["Wenzhou"]);
return {
columns,
selectedValues,
};
},
};
columns
属性可以通过二维数组的形式配置多列选择。
<van-picker title="标题" :columns="columns" />
export default {
setup() {
const columns = [
// 第一列
[
{ text: "周一", value: "Monday" },
{ text: "周二", value: "Tuesday" },
{ text: "周三", value: "Wednesday" },
{ text: "周四", value: "Thursday" },
{ text: "周五", value: "Friday" },
],
// 第二列
[
{ text: "上午", value: "Morning" },
{ text: "下午", value: "Afternoon" },
{ text: "晚上", value: "Evening" },
],
];
return { columns };
},
};
使用 columns
的 children
字段可以实现选项级联的效果。如果级联层级较多,推荐使用 Cascader 级联选项组件。
<van-picker title="标题" :columns="columns" />
export default {
setup() {
const columns = [
{
text: "浙江",
value: "Zhejiang",
children: [
{
text: "杭州",
value: "Hangzhou",
children: [
{ text: "西湖区", value: "Xihu" },
{ text: "余杭区", value: "Yuhang" },
],
},
{
text: "温州",
value: "Wenzhou",
children: [
{ text: "鹿城区", value: "Lucheng" },
{ text: "瓯海区", value: "Ouhai" },
],
},
],
},
{
text: "福建",
value: "Fujian",
children: [
{
text: "福州",
value: "Fuzhou",
children: [
{ text: "鼓楼区", value: "Gulou" },
{ text: "台江区", value: "Taijiang" },
],
},
{
text: "厦门",
value: "Xiamen",
children: [
{ text: "思明区", value: "Siming" },
{ text: "海沧区", value: "Haicang" },
],
},
],
},
];
return { columns };
},
};
级联选择的数据嵌套深度需要保持一致,如果部分选项没有子选项,可以使用空字符串进行占位。
选项可以为对象结构,通过设置 disabled
来禁用该选项。
<van-picker :columns="columns" />
export default {
setup() {
const columns = [
{ text: "杭州", value: "Hangzhou", disabled: true },
{ text: "宁波", value: "Ningbo" },
{ text: "温州", value: "Wenzhou" },
];
return { columns };
},
};
若选择器数据是异步获取的,可以通过 loading
属性显示加载提示。
<van-picker :columns="columns" :loading="loading" />
import { ref } from "vue";
export default {
setup() {
const columns = ref([]);
const loading = ref(true);
setTimeout(() => {
columns.value = [{ text: "选项", value: "option" }];
loading.value = false;
}, 1000);
return { columns, loading };
},
};
<van-picker
:title="标题"
:columns="columns"
:columns-field-names="customFieldName"
/>
export default {
setup() {
const columns = [
{
cityName: "浙江",
cities: [
{
cityName: "杭州",
cities: [{ cityName: "西湖区" }, { cityName: "余杭区" }],
},
{
cityName: "温州",
cities: [{ cityName: "鹿城区" }, { cityName: "瓯海区" }],
},
],
},
{
cityName: "福建",
cities: [
{
cityName: "福州",
cities: [{ cityName: "鼓楼区" }, { cityName: "台江区" }],
},
{
cityName: "厦门",
cities: [{ cityName: "思明区" }, { cityName: "海沧区" }],
},
],
},
];
const customFieldName = {
text: "cityName",
value: "cityName",
children: "cities",
};
return {
columns,
customFieldName,
};
},
};
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
columns | 对象数组,配置每一列显示的数据 | PickerOption[] | PickerOption[][] | []
|
columns-field-names | 自定义 columns 结构中的字段 |
object | { text: "text", value: "value", children: "children" }
|
title | 顶部栏标题 | string | - |
confirm-button-text | 确认按钮文字 | string | 确认
|
cancel-button-text | 取消按钮文字 | string | 取消
|
toolbar-position | 顶部栏位置,可选值为 bottom
|
string | top
|
loading | 是否显示加载状态 | boolean | false
|
show-toolbar | 是否显示顶部栏 | boolean | true
|
allow-html | 是否允许选项内容中渲染 HTML | boolean | false
|
option-height | 选项高度,支持 px vw vh rem 单位,默认 px
|
number | string | 44
|
visible-option-num | 可见的选项个数 | number | string | 6
|
swipe-duration | 快速滑动时惯性滚动的时长,单位 ms
|
number | string | 1000
|
事件名 | 说明 | 回调参数 |
---|---|---|
confirm | 点击完成按钮时触发 | { selectedValues, selectedOptions, selectedIndexes } |
cancel | 点击取消按钮时触发 | { selectedValues, selectedOptions, selectedIndexes } |
change | 选项改变时触发 | { selectedValues, selectedOptions, selectedIndexes, columnIndex } |
click-option | 点击选项时触发 | { currentOption, selectedValues, selectedOptions, selectedIndexes, columnIndex } |
名称 | 说明 | 参数 |
---|---|---|
toolbar v3.1.2
|
自定义整个顶部栏的内容 | - |
title | 自定义标题内容 | - |
confirm | 自定义确认按钮内容 | - |
cancel | 自定义取消按钮内容 | - |
option | 自定义选项内容 | option: PickerOption |
columns-top | 自定义选项上方内容 | - |
columns-bottom | 自定义选项下方内容 | - |
键名 | 说明 | 类型 |
---|---|---|
text | 选项文字内容 | string | number |
value | 选项对应的值 | string | number |
disabled | 是否禁用选项 | boolean |
children | 级联选项 | PickerOption[] |
className | 选项额外类名 | string | Array | object |
通过 ref 可以获取到 Picker 实例并调用实例方法,详见组件实例方法。
方法名 | 说明 | 参数 | 返回值 |
---|---|---|---|
confirm | 停止惯性滚动并触发 confirm 事件 |
- | - |
getSelectedOptions | 获取当前选中的选项 | - | (PickerOption | undefined)[] |
组件导出以下类型定义:
import type {
PickerProps,
PickerColumn,
PickerOption,
PickerInstance,
PickerFieldNames,
PickerToolbarPosition,
PickerCancelEventParams,
PickerChangeEventParams,
PickerConfirmEventParams,
} from "vant";
PickerInstance
是组件实例的类型,用法如下:
import { ref } from "vue";
import type { PickerInstance } from "vant";
const pickerRef = ref<PickerInstance>();
pickerRef.value?.confirm();
组件提供了下列 CSS 变量,可用于自定义样式,使用方法请参考 ConfigProvider 组件。
名称 | 默认值 | 描述 |
---|---|---|
--van-picker-background | var(--van-background-2) | - |
--van-picker-toolbar-height | 44px | - |
--van-picker-title-font-size | var(--van-font-size-lg) | - |
--van-picker-title-line-height | var(--van-line-height-md) | - |
--van-picker-action-padding | 0 var(--van-padding-md) | - |
--van-picker-action-font-size | var(--van-font-size-md) | - |
--van-picker-confirm-action-color | var(--van-link-color) | - |
--van-picker-cancel-action-color | var(--van-text-color-2) | - |
--van-picker-option-padding | 0 var(--van-padding-base) | - |
--van-picker-option-font-size | var(--van-font-size-lg) | - |
--van-picker-option-text-color | var(--van-text-color) | - |
--van-picker-option-disabled-opacity | 0.3 | - |
--van-picker-mask-color | linear-gradient | - |
--van-picker-loading-icon-color | var(--van-primary-color) | - |
--van-picker-loading-mask-color | rgba(255, 255, 255, 0.9) | - |
参见桌面端适配。
介绍用于配置 Vant 组件的主题样式,从 3.1.0 版本开始支持。实例演示引入通过以下方式来全局注册组件,更多注册方式请参考组件...
介绍用于在打开和关闭状态之间进行切换。实例演示引入通过以下方式来全局注册组件,更多注册方式请参考组件注册。import { creat...