Skip to content
On this page

DatePicker/DatePickerPopup/DatePickerView 时间选择器

注:

Import

js
import { TaDatePicker, TaDatePickerPopup, TaDatePickerView } from 'tantalum-ui-mobile'

具体的引入方式可以参考引入组件

Import Type

组件导出的类型定义:

ts
import type {
  DatePickerMode,
  DatePickerOptionFilter,
  DatePickerOnConfirm,
  SelectorOnChange,
  SelectorModelValue,
  DatePickerDetail,
  SelectorValueParser,
  SelectorValueFormatter,
  VisibleState,
  PopupOnVisibleStateChange,
  PopupOnCancel
} from 'tantalum-ui-mobile'

公共 Props

属性类型默认值必填说明
v-modelSelectorModelValue选中值
initial-modeDatePickerMode选择的模式,可选 'date', 'time', 'datetime' 等
min-dateDate当天对应 10 年前的 Date 实例最小时间对应的 Date 实例(含)
max-dateDate当天最后一秒的 Date 实例最大时间对应的 Date 实例(含)
format-templatestring格式的模板,如 YYYY-MM-DD,模板规则参考 Dayjs。设置后 v-model 的绑定变为格式化后的 string 类型,不再是 number[] 。推荐根据 initialMode 选型来确定,如 initialMode='minute-second',则可设置 formatTemplate='mm分ss秒'。优先级低于 formatter
filterDatePickerOptionFilter选项过滤器
formatterSelectorValueFormatterparser 成对设置,对于 v-model 和 change 的值进行转化
parserSelectorValueParserformatter 成对设置,对于 v-model 和 change 的值进行反转化

注:v-model 对未设置的前段值采用当前时间补上,后段则采用初始时间,如:initialMode='month-day-hour'下, 选取 5 月 7 日 12 点,则 v-model 对应的时间为:Fri May 07 2021 12:00:00 GMT+0800,设置 minDatemaxDate 的时候需要考虑到。

DatePicker 时间选择器

注:

  • 支持表单,具体可参考 Form
vue
<script setup lang="ts">
import { ref } from 'vue'
import dayjs from 'dayjs'
import {
  showToast,
  showDatePicker,
  type DatePickerOptionFilter,
  type SelectorModelValue
} from '@/index'

const title = 'DatePicker'

const dateValue = ref('')
const timeValue = ref('')
const dateTimeValue = ref('')
const minMaxValue = ref('')
const formatValue = ref('')
const filterValue = ref('')
const disableValue = ref(new Date())

const minDate = dayjs().startOf('day').subtract(4, 'year').toDate()
const maxDate = dayjs().startOf('day').add(5, 'year').toDate()

const filter: DatePickerOptionFilter = (number, type) => {
  if (type === 'second' && number % 5 !== 0) {
    return false
  }

  return true
}

function onChange(res: SelectorModelValue) {
  console.log('change', res)
  showToast(`值改为 ${res}`)
}

function onCallApi() {
  showDatePicker({
    title,
    success: res => {
      console.log(res)
      if (res.cancel) {
        showToast('取消了')
      } else {
        showToast(`选择了 ${res.detail.label}`)
      }
    }
  })
}
</script>

<script lang="ts">
export default {
  name: 'ExpDatePicker'
}
</script>

<template>
  <ta-group title="initialMode">
    <ta-cell label="日期 date">
      <ta-date-picker initialMode="date" v-model="dateValue" />
    </ta-cell>
    <ta-cell label="时间 time">
      <ta-date-picker initialMode="time" v-model="timeValue" />
    </ta-cell>
    <ta-cell label="日期时间 datetime">
      <ta-date-picker initialMode="datetime" v-model="dateTimeValue" />
    </ta-cell>
    <ta-cell label="分秒 minute-second">
      <ta-date-picker initialMode="minute-second" />
    </ta-cell>
    <ta-cell label="时分 hour-minute">
      <ta-date-picker initialMode="hour-minute" />
    </ta-cell>
    <ta-cell label="天时 day-hour">
      <ta-date-picker initialMode="day-hour" />
    </ta-cell>
    <ta-cell label="月日 month-day">
      <ta-date-picker initialMode="month-day" />
    </ta-cell>
    <ta-cell label="月日时 month-day-hour">
      <ta-date-picker initialMode="month-day-hour" />
    </ta-cell>
    <ta-cell label="月日时分 month-day-hour-minute">
      <ta-date-picker initialMode="month-day-hour-minute" />
    </ta-cell>
    <ta-cell label="年月 year-month">
      <ta-date-picker initialMode="year-month" />
    </ta-cell>
    <ta-cell label="年月日时 year-month-day-hour">
      <ta-date-picker initialMode="year-month-day-hour" />
    </ta-cell>
    <ta-cell name="date-picker" label="年月日时分 year-month-day-hour-minute">
      <ta-date-picker initialMode="year-month-day-hour-minute" />
    </ta-cell>
  </ta-group>
  <ta-group title="minDate & maxDate">
    <ta-cell label="-5year ~ 5year">
      <ta-date-picker
        initialMode="date"
        :minDate="maxDate"
        :maxDate="minDate"
        v-model="minMaxValue"
      />
    </ta-cell>
  </ta-group>
  <ta-group title="filter">
    <ta-cell label="秒步进5">
      <ta-date-picker initialMode="datetime" :filter="filter" v-model="filterValue" />
    </ta-cell>
  </ta-group>
  <ta-group title="formatTemplate">
    <ta-cell label="YYYY年MM月DD日">
      <ta-date-picker initialMode="date" formatTemplate="YYYY年MM月DD日" v-model="formatValue" />
    </ta-cell>
  </ta-group>
  <ta-group title="disabled">
    <ta-cell label="禁用">
      <ta-date-picker initialMode="date" disabled :modelValue="disableValue" />
    </ta-cell>
  </ta-group>
  <ta-group title="事件监听">
    <ta-cell label="change">
      <ta-date-picker initialMode="datetime" @change="onChange" />
    </ta-cell>
  </ta-group>
  <ta-group title="API">
    <ta-cell label="showDatePicker" isLink @click="onCallApi" />
  </ta-group>
</template>

DatePicker Props

属性类型默认值必填说明
namestring标识
placeholderstring没有选中值的提示,也会用在弹窗标题上
disabledbooleanfalse是否禁用

DatePicker Events

事件描述回调函数参数函数 TypeScript
change选择后选中值发生变化时触发payload: SelectorModelValueSelectorOnChange

DatePickerPopup 时间选择弹窗

vue
<script setup lang="ts">
import { ref } from 'vue'
import {
  showToast,
  type SelectorModelValue,
  type DatePickerOnConfirm,
  type PopupOnVisibleStateChange,
  type PopupOnCancel
} from '@/index'

const popupValue = ref('')
const visible = ref(false)
const clickEvent = ref(false)
const changeEvent = ref(false)
const visibleEvent = ref(false)

const onVisibleStateChange: PopupOnVisibleStateChange = res => {
  if (visibleEvent.value) {
    console.log('visible-state-change', res)
    showToast(`${res.state} 事件触发`)
  }

  if (res.state === 'hidden') {
    clickEvent.value = false
    visibleEvent.value = false
    changeEvent.value = false
  }
}

function onChange(res: SelectorModelValue) {
  if (changeEvent.value) {
    console.log('change', res)
    showToast(`值改为 ${res}`)
  }
}

const onConfirm: DatePickerOnConfirm = res => {
  if (clickEvent.value) {
    console.log('confirm', res)
    showToast(`点击确定按钮`)
  }
}

const onCancel: PopupOnCancel = res => {
  if (clickEvent.value) {
    console.log('cancel', res)

    if (res.source === 'cancelClick') {
      showToast('点击了取消按钮')
    } else if (res.source === 'maskClick') {
      showToast('点击了蒙层')
    }
  }
}
</script>

<script lang="ts">
export default {
  name: 'ExpDatePickerPopup'
}
</script>

<template>
  <ta-notice-bar class="top-notice-bar" title="基础展示参数可以参考 DatePicker" />
  <ta-group title="基础用法">
    <ta-cell label="默认" isLink @click="visible = true" :content="popupValue" />
  </ta-group>
  <ta-group title="事件监听">
    <ta-cell
      label="change"
      isLink
      @click="
        () => {
          changeEvent = true
          visible = true
        }
      "
    />
    <ta-cell
      label="confirm/cancel"
      isLink
      @click="
        () => {
          clickEvent = true
          visible = true
        }
      "
    />
    <ta-cell
      label="visible-state-change"
      isLink
      @click="
        () => {
          visibleEvent = true
          visible = true
        }
      "
    />
  </ta-group>
  <ta-date-picker-popup
    initialMode="date"
    formatTemplate="YYYY年MM月DD日"
    v-model:visible="visible"
    title="DatePickerPopup"
    v-model="popupValue"
    @change="onChange"
    @confirm="onConfirm"
    @cancel="onCancel"
    @visibleStateChange="onVisibleStateChange"
  />
</template>

DatePickerPopup Props

属性类型默认值必填说明
v-model:visiblebooleanfalse是否显示弹窗
titlestring弹窗标题

DatePickerPopup Events

事件描述回调函数参数函数 TypeScript
confirm点击确定按钮后触发payload: DatePickerDetailDatePickerOnConfirm
cancel点击取消按钮后触发PopupOnCancel
change选中值发生变化时触发payload: SelectorModelValueSelectorOnChange
visible-state-change展示隐藏时触发payload: { state: VisibleState }PopupOnVisibleStateChange

VisibleState 值说明

说明备注
show展示时触发
shown展示且动画结束后触发
hide隐藏时触发可能携带其他参数 cancel, maskClick, closeClick 等
hidden隐藏且动画结束后触发可能携带其他参数 cancel, maskClick, closeClick 等

DatePickerView 时间选择面板

vue
<script setup lang="ts">
import { ref } from 'vue'
import { showToast, type SelectorModelValue } from '@/index'

const dateTimeValue = ref('')
const changeValue = ref('')

function onChange(e: SelectorModelValue) {
  console.log('change', e)
  showToast(`change: ${e}`)
}
</script>

<script lang="ts">
export default {
  name: 'ExpDatePickerView'
}
</script>

<template>
  <ta-notice-bar class="top-notice-bar" title="基础展示参数可以参考 DatePicker" />
  <ta-group title="initialMode=datetime">
    <ta-date-picker-view initialMode="datetime" v-model="dateTimeValue" />
  </ta-group>
  <ta-group title="change 事件">
    <ta-date-picker-view initialMode="date" v-model="changeValue" @change="onChange" />
  </ta-group>
</template>

DatePickerView Events

事件描述回调函数参数函数 TypeScript
change滑动后选中值发生变化时触发payload: SelectorModelValueSelectorOnChange

showDatePicker(object) 显示时间选择弹窗

object

属性类型默认值必填说明
titlestring弹窗标题
valuenumber[]默认选择值
modeDatePickerMode选择的模式,可选 'date', 'time', 'datetime' 等
minDateDate当天对应 10 年前的 Date 实例最小时间对应的 Date 实例(含)
maxDateDate当天最后一秒的 Date 实例最大时间对应的 Date 实例(含)
filterDatePickerOptionFilter选项过滤器
success(payload: SuccessPayload) => void接口调用成功(在用户做出选择后,如取消,选择选项)的回调函数
fail(e: Error) => void接口调用失败(如传入错误的参数)的回调函数(不传入 fail 遇错误直接抛出)
complete() => void弹窗关闭或调用失败的回调函数

SuccessPayload

属性类型说明
confirm?boolean为 true 时,表示点击了确定,此时返回 detail
cancel?boolean为 true 时,表示取消
detail?DatePickerDetail

Usage

具体调用方式可以参考API 调用

js
showDatePicker({
  title: 'DatePicker',
  success: ({ confirm, cancel, detail }) => {
    ...
  }
})

类型释义

SelectorValue

ts
type SelectorValue = string | number | Date

SelectorModelValue

ts
type SelectorModelValue = SelectorValue | SelectorValue[]

注:在不自定义 formatter/parser 的情况下,v-model 只有 number[] 这种情况。

DatePickerDetail

ts
interface DatePickerDetail {
  label: string
  value: number[]
}
字段说明
label选中值对应的描述文本,如果设置了 formatTemplateformatter,则返回格式后文本
value选择的值,如 [2021, 5, 1],不受 formatTemplateformatter 影响

SelectorValueFormatter

ts
interface SelectorValueFormatter {
  (valueArray: SelectorValue[], labelArray: string[]):
    | { value: SelectorModelValue; label: string }
    | SelectorModelValue
}

将 v-model 的原始值转为需要的自定义值,值需要满足 SelectorModelValue 的类型约束,可以返回 { value, label } 对两个数据进行修改,或者单独返回 value。

SelectorValueParser

ts
interface SelectorValueParser {
  (value: unknown): SelectorValue[]
}

SelectorValueFormatter 相反,将自定义 v-model 的值转为组件认识的原始数组。

DatePickerMode

说明
date日期 (同 year-month-day)
time时间 (同 hour-minute-second)
datetime日期时间 (同 year-month-day-hour-minute-second)
minute-second分秒
hour-minute时分
hour-minute-second时分秒
day-hour天时
month-day月日
month-day-hour月日时
month-day-hour-minute月日时分
year-month年月
year-month-day年月日
year-month-day-hour年月日时
year-month-day-hour-minute年月日时分
year-month-day-hour-minute-second年月日时分秒

DatePickerOptionFilter

ts
interface DatePickerOptionFilter {
  (number: number, type: 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second'): boolean
}

通过返回 false 来过滤指定选项。