PickerGroup 选择器组 - Vant 4

🎛️ PickerGroup 选择器组

🎯 介绍

PickerGroup 组件用于结合多个 Picker 选择器组件，在一次交互中完成多个值的选择。让复杂选择变得简单高效！

PickerGroup 中可以放置以下组件：

Picker
Area
DatePicker
TimePicker
其他基于 Picker 封装的自定义组件

📦 引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from'vue'; import { PickerGroup } from'vant'; const app = createApp(); app.use(PickerGroup);

🎯 代码演示

📅 选择日期时间

想要同时选择日期和时间？PickerGroup 就像一个贴心的管家，帮你把多个选择器完美组合在一起！🎭 只需在默认插槽中放置 DatePicker 和 TimePicker 组件，就能实现一站式的日期时间选择体验。

PickerGroup 会统一管理标题栏，让界面更加简洁美观。所有与标题栏相关的属性和事件都交给 PickerGroup 处理，子组件专注于自己的选择逻辑即可。

html

<template>
  <van-picker-group
    title="选择日期时间"
    :tabs="['选择日期', '选择时间']"
    @confirm="onConfirm"
    @cancel="onCancel"
  >
    <van-date-picker
      v-model="currentDate"
      :min-date="minDate"
      :max-date="maxDate"
    />
    <van-time-picker v-model="currentTime" />
  </van-picker-group>
</template>

import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const currentDate = ref(['2022', '06', '01']);
    const currentTime = ref(['12', '00']);
    
    const onConfirm = () => {
      showToast(
        `选择的日期时间：${currentDate.value.join('/')} ${currentTime.value.join(':')}`,
      );
    };
    
    const onCancel = () => {
      showToast('取消选择');
    };
    
    return {
      minDate: new Date(2020, 0, 1),
      maxDate: new Date(2025, 5, 1),
      currentDate,
      currentTime,
      onConfirm,
      onCancel,
    };
  },
};

🚀 下一步按钮

有时候我们希望用户能够按顺序完成所有选择，就像填写表单一样循序渐进。设置 next-step-text 属性后，PickerGroup 会智能地在「下一步」和「确认」之间切换，引导用户完成所有选择步骤。

html

<template>
  <van-picker-group
    title="预约时间"
    :tabs="['选择日期', '选择时间']"
    next-step-text="下一步"
    @confirm="onConfirm"
    @cancel="onCancel"
  >
    <van-date-picker
      v-model="currentDate"
      :min-date="minDate"
      :max-date="maxDate"
    />
    <van-time-picker v-model="currentTime" />
  </van-picker-group>
</template>

import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const currentDate = ref(['2022', '06', '01']);
    const currentTime = ref(['12', '00']);
    
    const onConfirm = () => {
      showToast(
        `预约成功！时间：${currentDate.value.join('/')} ${currentTime.value.join(':')}`,
      );
    };
    
    const onCancel = () => {
      showToast('取消预约');
    };
    
    return {
      minDate: new Date(2020, 0, 1),
      maxDate: new Date(2025, 5, 1),
      currentDate,
      currentTime,
      onConfirm,
      onCancel,
    };
  },
};

📆 选择日期范围

需要选择一个时间段？比如预订酒店的入住和退房日期，PickerGroup 让范围选择变得轻而易举！🏨 通过放置两个 DatePicker 组件，用户可以直观地选择开始和结束日期。

html

<template>
  <van-picker-group
    title="选择入住日期"
    :tabs="['入住日期', '退房日期']"
    @confirm="onConfirm"
    @cancel="onCancel"
  >
    <van-date-picker
      v-model="startDate"
      :min-date="minDate"
      :max-date="maxDate"
    />
    <van-date-picker
      v-model="endDate"
      :min-date="endMinDate"
      :max-date="maxDate"
    />
  </van-picker-group>
</template>

import { computed, ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const startDate = ref(['2022', '06', '01']);
    const endDate = ref(['2023', '06', '01']);
    
    // 智能计算退房日期的最小值，确保逻辑正确
    const endMinDate = computed(
      () => new Date(
        Number(startDate.value[0]),
        Number(startDate.value[1]) - 1,
        Number(startDate.value[2]),
      ),
    );
    
    const onConfirm = () => {
      showToast(`入住期间：${startDate.value.join('/')} 至 ${endDate.value.join('/')}`);
    };
    
    const onCancel = () => {
      showToast('取消预订');
    };
    
    return {
      minDate: new Date(2020, 0, 1),
      maxDate: new Date(2025, 5, 1),
      endMinDate,
      endDate,
      startDate,
      onConfirm,
      onCancel,
    };
  },
};

⏰ 选择时间范围

工作时间、营业时间、活动时间段...时间范围选择在生活中无处不在！通过组合两个 TimePicker 组件，让用户轻松设定时间区间。

html

<template>
  <van-picker-group
    title="设置营业时间"
    :tabs="['开始时间', '结束时间']"
    @confirm="onConfirm"
    @cancel="onCancel"
  >
    <van-time-picker v-model="startTime" />
    <van-time-picker v-model="endTime" />
  </van-picker-group>
</template>

import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const startTime = ref(['09', '00']);
    const endTime = ref(['18', '00']);
    
    const onConfirm = () => {
      showToast(`营业时间：${startTime.value.join(':')} - ${endTime.value.join(':')}`);
    };
    
    const onCancel = () => {
      showToast('取消设置');
    };
    
    return {
      endTime,
      startTime,
      onConfirm,
      onCancel,
    };
  },
};

🎮 受控模式

想要完全掌控标签页的切换？PickerGroup 提供了灵活的控制模式：

自由模式：不绑定 v-model:active-tab，组件自主管理切换逻辑
受控模式：绑定 v-model:active-tab，你可以通过代码精确控制当前显示的标签页

html

<template>
  <div>
    <van-button @click="setActiveTab" style="margin-bottom: 20px;">
      切换到{{ activeTab === 0 ? '时间' : '日期' }}选择
    </van-button>
    
    <van-picker-group
      v-model:active-tab="activeTab"
      title="受控模式演示"
      :tabs="['选择日期', '选择时间']"
      @confirm="onConfirm"
      @cancel="onCancel"
    >
      <van-date-picker
        v-model="currentDate"
        :min-date="minDate"
        :max-date="maxDate"
      />
      <van-time-picker v-model="currentTime" />
    </van-picker-group>
  </div>
</template>

import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const activeTab = ref(0);
    const currentDate = ref(['2022', '06', '01']);
    const currentTime = ref(['12', '00']);
    
    const setActiveTab = () => {
      activeTab.value = activeTab.value ? 0 : 1;
    };
    
    const onConfirm = () => {
      showToast(
        `选择完成：${currentDate.value.join('/')} ${currentTime.value.join(':')}`,
      );
    };
    
    const onCancel = () => {
      showToast('取消选择');
    };
    
    return {
      minDate: new Date(2020, 0, 1),
      maxDate: new Date(2025, 5, 1),
      activeTab,
      currentDate,
      currentTime,
      setActiveTab,
      onConfirm,
      onCancel,
    };
  },
};

API

Props

参数	说明	类型	默认值
v-model:active-tab `v4.3.2`	当前选中的标签索引，控制显示哪个选择器 🎯	number \| string	`0`
tabs	标签页标题数组，为每个选择器定义名称 📋	string[]	`[]`
title	顶部栏标题，整个选择器组的主标题 📝	string	`''`
show-toolbar	是否显示顶部栏，控制标题栏的显示隐藏 👁️	boolean	`true`
next-step-text `v4.0.8`	下一步按钮文字，引导用户逐步完成选择 ➡️	string	`''`
confirm-button-text	确认按钮文字，自定义确认操作的文案 ✅	string	`确认`
cancel-button-text	取消按钮文字，自定义取消操作的文案 ❌	string	`取消`

Events

事件名	说明	回调参数
confirm	点击确认按钮时触发，完成选择操作 ✨	-
cancel	点击取消按钮时触发，取消选择操作 🚫	-
change	切换标签页时触发，监听标签页变化 🔄	activeTab: number \| string

Slots

名称	说明	参数
toolbar	自定义整个顶部栏内容，完全控制标题栏样式 🎨	-
title	自定义标题内容，个性化标题显示 📄	-
confirm	自定义确认按钮内容，打造独特的确认按钮 🎯	-
cancel	自定义取消按钮内容，个性化取消按钮 🔙	-

类型定义

组件导出以下类型定义：

importtype { PickerGroupProps, PickerGroupThemeVars } from'vant';

主题定制

样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--van-picker-group-background	--van-background-2	选择器组背景色，营造舒适的选择环境 🎨

📚 相关文档

Picker 选择器 - 基础选择器组件，万能的选择工具 🎛️
DatePicker 日期选择 - 日期选择组件，时光穿梭的利器 📅
TimePicker 时间选择 - 时间选择组件，精确到分秒的时间控制 ⏰
Area 省市区选择 - 省市区选择组件，地理位置的智能选择 🗺️
Popup 弹出层 - 弹出层组件，承载选择器的舞台 📱
ActionSheet 动作面板 - 动作面板组件，快速选择的好帮手 📋

🎛️ PickerGroup 选择器组 ​

🎯 介绍 ​

📦 引入 ​

🎯 代码演示 ​

📅 选择日期时间 ​

🚀 下一步按钮 ​

📆 选择日期范围 ​

⏰ 选择时间范围 ​

🎮 受控模式 ​

API ​

Props ​

Events ​

Slots ​

类型定义 ​

主题定制 ​

样式变量 ​

📚 相关文档 ​

🎛️ PickerGroup 选择器组

🎯 介绍

📦 引入

🎯 代码演示

📅 选择日期时间

🚀 下一步按钮

📆 选择日期范围

⏰ 选择时间范围

🎮 受控模式

API

Props

Events

Slots

类型定义

主题定制

样式变量

📚 相关文档