介绍
提供多个选项集合供用户选择,支持单列选择、多列选择和级联选择,通常与弹出层组件配合使用。
引入
通过以下方式来全局注册组件,更多注册方式请参考组件注册。
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 };
},
};
自定义 Columns 的结构
<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,
};
},
};
API
Props
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
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 |
Events
事件名 | 说明 | 回调参数 |
---|---|---|
confirm | 点击完成按钮时触发 | { selectedValues, selectedOptions, selectedIndexes } |
cancel | 点击取消按钮时触发 | { selectedValues, selectedOptions, selectedIndexes } |
change | 选项改变时触发 | { selectedValues, selectedOptions, selectedIndexes, columnIndex } |
click-option | 点击选项时触发 | { currentOption, selectedValues, selectedOptions, selectedIndexes, columnIndex } |
Slots
名称 | 说明 | 参数 |
---|---|---|
toolbar v3.1.2 | 自定义整个顶部栏的内容 | – |
title | 自定义标题内容 | – |
confirm | 自定义确认按钮内容 | – |
cancel | 自定义取消按钮内容 | – |
option | 自定义选项内容 | option: PickerOption |
columns-top | 自定义选项上方内容 | – |
columns-bottom | 自定义选项下方内容 | – |
PickerOption 数据结构
键名 | 说明 | 类型 |
---|---|---|
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) | – |
常见问题
在桌面端无法操作组件?
参见桌面端适配。
作者:terry,如若转载,请注明出处:https://www.web176.com/vant4/18923.html