Vant4 Picker 选择器
2023-02-16 17:55 更新
介绍
提供多个选项集合供用户选择，支持单列选择、多列选择和级联选择，通常与弹出层组件配合使用。
引入
通过以下方式来全局注册组件，更多注册方式请参考组件注册。
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) | - |
常见问题
在桌面端无法操作组件？
参见桌面端适配。
以上内容是否对您有帮助：
更多建议：