Skip to content

Picker 滚轮选择器 ​

提供多个选项集合供用户选择,支持单列选择、多列选择和级联选择,通常与弹出层组件、表单项组件配合使用。

导入 ​

js
// 基础滚轮选择器
import Picker from '@/components/form/Picker.vue';
// 级联滚轮选择器
import CascadePicker from '@/components/form/CascadePicker.vue';
// 日期选择器
import DatePicker from '@/components/form/DatePicker.vue';
// 时间选择器
import TimePicker from '@/components/form/TimePicker.vue';
// 日期时间选择器
import DateTimePicker from '@/components/form/DateTimePicker.vue';
// 表单项级联选择器
import CascadePickerField from '@/components/form/CascadePickerField.vue';
// 表单项滚轮选择器
import PickerField from '@/components/form/PickerField.vue';
// 表单项日期选择器
import DatePickerField from '@/components/form/DatePickerField.vue';
// 表单项时间选择器
import TimePickerField from '@/components/form/TimePickerField.vue';
// 表单项日期时间选择器
import DateTimePickerField from '@/components/form/DateTimePickerField.vue';

使用方法 ​

Picker - 基础滚轮选择器 ​

提供基础的单列或多列滚轮选择功能。

基础用法(单列) ​

vue
<template>
  <Picker 
    v-model:value="value1" 
    :columns="columns1"
  />
</template>

<script setup>
import { ref } from 'vue';
import Picker from '@/components/form/Picker.vue';

const value1 = ref(['Hangzhou']);
const columns1 = [[
  { text: '杭州', value: 'Hangzhou' },
  { text: '宁波', value: 'Ningbo' },
  { text: '温州', value: 'Wenzhou' },
  { text: '绍兴', value: 'Shaoxing' },
  { text: '湖州', value: 'Huzhou' },
]];
</script>

多列选择 ​

vue
<template>
  <Picker 
    v-model:value="value2" 
    :columns="columns2"
  />
</template>

<script setup>
import { ref } from 'vue';
import Picker from '@/components/form/Picker.vue';

const value2 = ref([]);
const columns2 = [
  // 第一列
  [
    { text: '周一', value: 'Monday' },
    { text: '周二', value: 'Tuesday' },
    { text: '周三', value: 'Wednesday' },
    { text: '周四', value: 'Thursday' },
    { text: '周五', value: 'Friday' },
  ],
  // 第二列
  [
    { text: '上午', value: 'Morning' },
    { text: '下午', value: 'Afternoon' },
    { text: '晚上', value: 'Evening' },
  ],
];
</script>

CascadePicker - 级联选择器 ​

提供层级关联的选择功能,如省市区选择。

vue
<template>
  <CascadePicker
    v-model:value="value4" 
    :columns="columns4"
    :columnsCount="2"
  />
</template>

<script setup>
import { ref } from 'vue';
import CascadePicker from '@/components/form/CascadePicker.vue';

const value4 = ref([]);
const columns4 = [
  {
    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' },
        ],
      },
    ],
  },
];
</script>

搭配表单项使用 ​

PickerField - 表单项滚轮选择器 ​

vue
<template>
  <Field label="城市" showRightArrow>
    <PickerField v-model="value3" :columns="columns1" placeholder="请选择城市" />
  </Field>
</template>

<script setup>
import { ref } from 'vue';
import Field from '@/components/form/Field.vue';
import PickerField from '@/components/form/PickerField.vue';

const value3 = ref([]);
const columns1 = [[
  { text: '杭州', value: 'Hangzhou' },
  { text: '宁波', value: 'Ningbo' },
  { text: '温州', value: 'Wenzhou' },
  { text: '绍兴', value: 'Shaoxing' },
  { text: '湖州', value: 'Huzhou' },
]];
</script>

时间日期选择器 ​

vue
<template>
  <Field name="date" label="选择日期" showRightArrow><DatePickerField /></Field>
  <Field name="time" label="选择时间" showRightArrow><TimePickerField /></Field>
  <Field name="datetime" label="选择日期+时间" showRightArrow><DateTimePickerField /></Field>
</template>

<script setup>
import Field from '@/components/form/Field.vue';
import DatePickerField from '@/components/form/DatePickerField.vue';
import TimePickerField from '@/components/form/TimePickerField.vue';
import DateTimePickerField from '@/components/form/DateTimePickerField.vue';
</script>

API 参考 ​

Picker ​

基础滚轮选择器组件。

Props ​

名称说明类型必填默认值
columns选择器列PickerItem[][]是-
value选中Value(number|string)[]是-
pickerHeightpicker高度string|number否300
pickerWidthpicker宽度string|number否750
singleValue是否在columns只有一列情况下value返回一个值boolean否false

Events ​

名称说明参数
update:value值改变事件(number|string)[]
selectTextChange选择文本改变事件string

类型定义 ​

ts
interface PickerItem {
  text: string;
  value: string|number;
}

PickerField ​

表单项滚轮选择器组件。

Props ​

名称说明类型必填默认值
modelValue绑定值(number|string)[]否[]
title标题string否'请选择选项'
titleProps标题属性ActionSheetTitleProps否{ cancelText: '取消', confirmText: '确定' }
showSelectText是否显示选中的文本boolean否true
placeholder占位符string否'请选择选项'
initalValue初始值(number|string)[]否-
shouldUpdateValueImmediately是否立即更新值boolean否false
textProps显示的文本属性TextProps否-
columns选择器列PickerItem[][]是-
pickerHeightpicker高度string|number否300
pickerWidthpicker宽度string|number否750
singleValue是否在columns只有一列情况下value返回一个值boolean否false

Events ​

名称说明参数
update:modelValue值改变事件(number|string)[]
cancel取消事件-
confirm确认事件-
selectTextChange选择文本改变事件string
tempValueChange临时值改变事件(number|string)[]

DateTimePicker ​

日期时间选择器组件,支持自定义显示年月日时分秒。

Props ​

名称说明类型必填默认值
modelValue绑定值Date否-
showYears是否显示年份boolean否true
showMonths是否显示月份boolean否true
showDays是否显示日期boolean否true
showHours是否显示小时boolean否true
showMinute是否显示分钟boolean否true
showSecond是否显示秒钟boolean否true
startYear开始年份number否当前年份-10
endYear结束年份number否当前年份+10
startMonth开始月份number否1
endMonth结束月份number否12
startDay开始日期number否1
endDay结束日期number否31
minuteText分钟单位文本string否'分'
secondText秒钟单位文本string否'秒'
hourText小时单位文本string否'时'
yearText年份单位文本string否'年'
monthText月份单位文本string否'月'
dayText日期单位文本string否'日'
pickerHeightpicker高度string|number否300
pickerWidthpicker宽度string|number否750

Events ​

名称说明参数
update:modelValue值改变事件Date
selectTextChange选择文本改变事件string

DateTimePickerField ​

表单项日期时间选择器组件。

Props ​

名称说明类型必填默认值
modelValue绑定值Date否-
title标题string否'请选择时间'
titleProps标题属性ActionSheetTitleProps否{ cancelText: '取消', confirmText: '确定' }
showSelectText是否显示选中的文本boolean否true
placeholder占位符string否'请选择时间'
initalValue初始值Date否-
shouldUpdateValueImmediately是否立即更新值boolean否false
textProps显示的文本属性TextProps否-
showYears是否显示年份boolean否true
showMonths是否显示月份boolean否true
showDays是否显示日期boolean否true
showHours是否显示小时boolean否true
showMinute是否显示分钟boolean否true
showSecond是否显示秒钟boolean否true
startYear开始年份number否当前年份-10
endYear结束年份number否当前年份+10
startMonth开始月份number否1
endMonth结束月份number否12
startDay开始日期number否1
endDay结束日期number否31
minuteText分钟单位文本string否'分'
secondText秒钟单位文本string否'秒'
hourText小时单位文本string否'时'
yearText年份单位文本string否'年'
monthText月份单位文本string否'月'
dayText日期单位文本string否'日'
pickerHeightpicker高度string|number否300
pickerWidthpicker宽度string|number否750

Events ​

名称说明参数
update:modelValue值改变事件Date
cancel取消事件-
confirm确认事件-
selectTextChange选择文本改变事件string
tempValueChange临时值改变事件Date

CascadePicker ​

级联滚轮选择器组件,用于层级关联的选择,如省市区选择。

Props ​

名称说明类型必填默认值
columns选择器列,子项在 children 下面CascadePickerItem[]是-
columnsCount选择器列数量,必须与 children 嵌套层数一致number否1
value选中Value(number|string)[]是-
pickerHeightpicker高度string|number否300
pickerWidthpicker宽度string|number否750

Events ​

名称说明参数
update:value值改变事件(number|string)[]
selectTextChange选择文本改变事件string

类型定义 ​

ts
interface CascadePickerItem {
  text: string;
  value: string|number;
  children?: CascadePickerItem[];
}

CascadePickerField ​

表单项级联滚轮选择器组件。

Props ​

名称说明类型必填默认值
modelValue绑定值(number|string)[]否[]
title标题string否'请选择选项'
titleProps标题属性ActionSheetTitleProps否{ cancelText: '取消', confirmText: '确定' }
showSelectText是否显示选中的文本boolean否true
placeholder占位符string否'请选择选项'
initalValue初始值(number|string)[]否-
shouldUpdateValueImmediately是否立即更新值boolean否false
textProps显示的文本属性TextProps否-
columns选择器列,子项在 children 下面CascadePickerItem[]是-
columnsCount选择器列数量,必须与 children 嵌套层数一致number否1
pickerHeightpicker高度string|number否300
pickerWidthpicker宽度string|number否750

Events ​

名称说明参数
update:modelValue值改变事件(number|string)[]
cancel取消事件-
confirm确认事件-
selectTextChange选择文本改变事件string
tempValueChange临时值改变事件(number|string)[]

TimePicker ​

时间选择器组件,用于选择小时、分钟和秒钟。

Props ​

名称说明类型必填默认值
modelValue绑定值Date否-
showHours是否显示小时boolean否true
showMinute是否显示分钟boolean否true
showSecond是否显示秒钟boolean否true
minuteText分钟单位文本string否'分'
secondText秒钟单位文本string否'秒'
hourText小时单位文本string否'时'
pickerHeightpicker高度string|number否300
pickerWidthpicker宽度string|number否750

Events ​

名称说明参数
update:modelValue值改变事件Date
selectTextChange选择文本改变事件string

TimePickerField ​

表单项时间选择器组件。

Props ​

名称说明类型必填默认值
modelValue绑定值Date否-
title标题string否'请选择时间'
titleProps标题属性ActionSheetTitleProps否{ cancelText: '取消', confirmText: '确定' }
showSelectText是否显示选中的文本boolean否true
placeholder占位符string否'请选择时间'
initalValue初始值Date否-
shouldUpdateValueImmediately是否立即更新值boolean否false
textProps显示的文本属性TextProps否-
showHours是否显示小时boolean否true
showMinute是否显示分钟boolean否true
showSecond是否显示秒钟boolean否true
minuteText分钟单位文本string否'分'
secondText秒钟单位文本string否'秒'
hourText小时单位文本string否'时'
pickerHeightpicker高度string|number否300
pickerWidthpicker宽度string|number否750

Events ​

名称说明参数
update:modelValue值改变事件Date
cancel取消事件-
confirm确认事件-
selectTextChange选择文本改变事件string
tempValueChange临时值改变事件Date

DatePicker ​

日期选择器组件,用于选择年、月、日。

Props ​

名称说明类型必填默认值
modelValue绑定值Date否-
showYears是否显示年份boolean否true
showMonths是否显示月份boolean否true
showDays是否显示日期boolean否true
startYear开始年份number否当前年份-10
endYear结束年份number否当前年份+10
startMonth开始月份number否1
endMonth结束月份number否12
startDay开始日期number否1
endDay结束日期number否31
yearText年份单位文本string否'年'
monthText月份单位文本string否'月'
dayText日期单位文本string否'日'
pickerHeightpicker高度string|number否300
pickerWidthpicker宽度string|number否750

Events ​

名称说明参数
update:modelValue值改变事件Date
selectTextChange选择文本改变事件string

DatePickerField ​

表单项日期选择器组件。

Props ​

名称说明类型必填默认值
modelValue绑定值Date否-
title标题string否'请选择时间'
titleProps标题属性ActionSheetTitleProps否{ cancelText: '取消', confirmText: '确定' }
showSelectText是否显示选中的文本boolean否true
placeholder占位符string否'请选择时间'
initalValue初始值Date否-
shouldUpdateValueImmediately是否立即更新值boolean否false
textProps显示的文本属性TextProps否-
showYears是否显示年份boolean否true
showMonths是否显示月份boolean否true
showDays是否显示日期boolean否true
startYear开始年份number否当前年份-10
endYear结束年份number否当前年份+10
startMonth开始月份number否1
endMonth结束月份number否12
startDay开始日期number否1
endDay结束日期number否31
yearText年份单位文本string否'年'
monthText月份单位文本string否'月'
dayText日期单位文本string否'日'
pickerHeightpicker高度string|number否300
pickerWidthpicker宽度string|number否750

Events ​

名称说明参数
update:modelValue值改变事件Date
cancel取消事件-
confirm确认事件-
selectTextChange选择文本改变事件string
tempValueChange临时值改变事件Date

主题变量 ​

无