注:
- 这 3 个组件是渐进式组件,可查看 渐进式组件 了解。
Import
import {
TaDatePicker,
TaDatePickerPopup,
TaDatePickerView
} from 'tantalum-ui-mobile-react'
具体的引入方式可以参考引入组件。
Import Type
组件导出的类型定义:
import type {
DatePickerMode,
DatePickerOptionFilter,
DatePickerOnConfirm,
SelectorOnChange,
SelectorModelValue,
DatePickerDetail,
SelectorValueParser,
SelectorValueFormatter,
VisibleState,
PopupOnVisibleStateChange,
PopupOnCancel
} from 'tantalum-ui-mobile-react'
公共 Props
属性 | 类型 | 默认值 | 必填 | 说明 |
---|
value | SelectorModelValue | | 否 | 选中值 |
initialMode | DatePickerMode | | 否 | 选择的模式,可选 'date', 'time', 'datetime' 等 |
minDate | Date | 当天对应 10 年前的 Date 实例 | 否 | 最小时间对应的 Date 实例(含) |
maxDate | Date | 当天最后一秒的 Date 实例 | 否 | 最大时间对应的 Date 实例(含) |
formatTemplate | string | | 否 | 格式的模板,如 YYYY-MM-DD ,模板规则参考 Dayjs。设置后 value 的绑定变为格式化后的 string 类型,不再是 Date 实例。推荐根据 initialMode 选型来确定,如 initialMode='minute-second' ,则可设置 formatTemplate='mm分ss秒' |
filter | DatePickerOptionFilter | | 否 | 选项过滤器 |
formatter | SelectorValueFormatter | | 否 | 和 parser 成对设置,对于 value 的值进行转化 |
parser | SelectorValueParser | | 否 | 和 formatter 成对设置,对于 value 的值进行反转化 |
注:Date 实例对未设置的前段值采用当前时间补上,后段则采用初始时间,如:initialMode='month-day-hour'下, 选取 5 月 7 日 12 点,则 Date 实例对应的时间为:Fri May 07 2021 12:00:00 GMT+0800
,设置 minDate
,maxDate
的时候需要考虑到。
DatePicker 时间选择器
注:
import {
showToast,
showDatePicker,
SelectorModelValue,
DatePickerOptionFilter,
TaGroup,
TaCell,
TaDatePicker
} from '@/index'
import dayjs from 'dayjs'
const title = 'DatePicker'
const minDate = dayjs().startOf('day').subtract(4, 'year').toDate()
const maxDate = dayjs().startOf('day').add(5, 'year').toDate()
const disableValue = new Date()
export default function ExpDatePicker() {
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}`)
}
}
})
}
return (
<>
<TaGroup title="initialMode">
<TaCell label="日期 date">
<TaDatePicker initialMode="date" />
</TaCell>
<TaCell label="时间 time">
<TaDatePicker initialMode="time" />
</TaCell>
<TaCell label="日期时间 datetime">
<TaDatePicker initialMode="datetime" />
</TaCell>
<TaCell label="分秒 minute-second">
<TaDatePicker initialMode="minute-second" />
</TaCell>
<TaCell label="时分 hour-minute">
<TaDatePicker initialMode="hour-minute" />
</TaCell>
<TaCell label="天时 day-hour">
<TaDatePicker initialMode="day-hour" />
</TaCell>
<TaCell label="月日 month-day">
<TaDatePicker initialMode="month-day" />
</TaCell>
<TaCell label="月日时 month-day-hour">
<TaDatePicker initialMode="month-day-hour" />
</TaCell>
<TaCell label="月日时分 month-day-hour-minute">
<TaDatePicker initialMode="month-day-hour-minute" />
</TaCell>
<TaCell label="年月 year-month">
<TaDatePicker initialMode="year-month" />
</TaCell>
<TaCell label="年月日时 year-month-day-hour">
<TaDatePicker initialMode="year-month-day-hour" />
</TaCell>
<TaCell label="年月日时分 year-month-day-hour-minute">
<TaDatePicker initialMode="year-month-day-hour-minute" />
</TaCell>
</TaGroup>
<TaGroup title="minDate & maxDate">
<TaCell label="-5year ~ 5year">
<TaDatePicker
initialMode="date"
minDate={maxDate}
maxDate={minDate}
/>
</TaCell>
</TaGroup>
<TaGroup title="filter">
<TaCell label="秒步进5">
<TaDatePicker initialMode="datetime" filter={filter} />
</TaCell>
</TaGroup>
<TaGroup title="formatTemplate">
<TaCell label="YYYY年MM月DD日">
<TaDatePicker
initialMode="date"
formatTemplate="YYYY年MM月DD日"
v-model="formatValue"
/>
</TaCell>
</TaGroup>
<TaGroup title="disabled">
<TaCell label="禁用">
<TaDatePicker initialMode="date" disabled value={disableValue} />
</TaCell>
</TaGroup>
<TaGroup title="事件监听">
<TaCell label="change">
<TaDatePicker initialMode="datetime" onChange={onChange} />
</TaCell>
</TaGroup>
<TaGroup title="API">
<TaCell label="showDatePicker" isLink onClick={() => onCallApi()} />
</TaGroup>
</>
)
}
DatePicker Props
属性 | 类型 | 默认值 | 必填 | 说明 |
---|
name | string | | 否 | 标识 |
placeholder | string | | 否 | 没有选中值的提示,也会用在弹窗标题上 |
disabled | boolean | false | 否 | 是否禁用 |
DatePicker Events
import {
showToast,
SelectorModelValue,
PickerOnConfirm,
PopupOnVisibleStateChange,
PopupOnCancel,
TaCell,
TaGroup,
TaNoticeBar,
TaDatePicker
} from '@/index'
import { useRef, useState } from 'react'
interface showArgs {
visibleEvent?: boolean
changeEvent?: boolean
clickEvent?: boolean
}
export default function ExpDatePickerPopup() {
const [popupValue, setPopupValue] = useState('')
const [visible, setVisible] = useState(false)
const clickEvent = useRef(false)
const changeEvent = useRef(false)
const visibleEvent = useRef(false)
function onShow(args: showArgs = {}) {
visibleEvent.current = !!args.visibleEvent
changeEvent.current = !!args.changeEvent
clickEvent.current = !!args.clickEvent
setVisible(true)
}
const onVisibleStateChange: PopupOnVisibleStateChange = res => {
if (visibleEvent.current) {
console.log('onVisibleStateChange', res)
showToast(`${res.state} 事件触发`)
}
if (res.state === 'hidden') {
clickEvent.current = false
visibleEvent.current = false
changeEvent.current = false
}
}
const onConfirm: PickerOnConfirm = res => {
if (clickEvent.current) {
console.log('onConfirm', res)
showToast(`点击确定按钮`)
}
}
function onChange(res: SelectorModelValue) {
if (changeEvent.current) {
console.log('onChange', res)
showToast(`值改为 ${res}`)
}
setPopupValue(res as string)
}
const onCancel: PopupOnCancel = res => {
if (clickEvent.current) {
console.log('onCancel', res)
if (res.source === 'cancelClick') {
showToast('点击了取消按钮')
} else if (res.source === 'maskClick') {
showToast('点击了蒙层')
}
}
}
return (
<>
<TaNoticeBar
className="top-notice-bar"
title="基础展示参数可以参考 DatePicker"
/>
<TaGroup title="基础用法">
<TaCell label="默认" isLink onClick={() => onShow({})}>
{popupValue}
</TaCell>
</TaGroup>
<TaGroup title="事件监听">
<TaCell
label="onChange"
isLink
onClick={() => onShow({ changeEvent: true })}
/>
<TaCell
label="onConfirm/onCancel"
isLink
onClick={() => onShow({ clickEvent: true })}
/>
<TaCell
label="onVisibleStateChange"
isLink
onClick={() => onShow({ visibleEvent: true })}
/>
</TaGroup>
<TaDatePicker.Popup
visible={visible}
initialMode="date"
formatTemplate="YYYY年MM月DD日"
title="DatePickerPopup"
value={popupValue}
onChange={onChange}
onConfirm={onConfirm}
onCancel={onCancel}
onVisibleStateChange={onVisibleStateChange}
onUpdateVisible={v => setVisible(v)}
/>
</>
)
}
属性 | 类型 | 默认值 | 必填 | 说明 |
---|
visible | boolean | false | 否 | 是否显示弹窗 |
title | string | | 否 | 弹窗标题 |
事件 | 描述 | 回调函数参数 | 函数 TypeScript |
---|
onConfirm | 点击确定按钮后触发 | payload: DatePickerDetail | DatePickerOnConfirm |
onCancel | 点击取消按钮后触发 | | PopupOnCancel |
onChange | 选中值发生变化时触发 | payload: SelectorModelValue | SelectorOnChange |
onVisibleStateChange | 展示隐藏时触发 | payload: { state: VisibleState } | PopupOnVisibleStateChange |
onUpdateVisible | 展示隐藏时触发 | visible: boolean 是否显示 | |
VisibleState 值说明
值 | 说明 | 备注 |
---|
show | 展示时触发 | |
shown | 展示且动画结束后触发 | |
hide | 隐藏时触发 | 可能携带其他参数 cancel, maskClick, closeClick 等 |
hidden | 隐藏且动画结束后触发 | 可能携带其他参数 cancel, maskClick, closeClick 等 |
DatePickerView 时间选择面板
import {
TaDatePicker,
TaNoticeBar,
TaGroup,
showToast,
SelectorModelValue
} from '@/index'
export default function ExpDatePickerView() {
function onChange(e: SelectorModelValue) {
console.log('change', e)
showToast(`change: ${e}`)
}
return (
<>
<TaNoticeBar
className="top-notice-bar"
title="基础展示参数可以参考 DatePicker"
/>
<TaGroup title="initialMode=datetime">
<TaDatePicker.View initialMode="datetime" />
</TaGroup>
<TaGroup title="change 事件">
<TaDatePicker.View initialMode="date" onChange={onChange} />
</TaGroup>
</>
)
}
DatePickerView Events
showDatePicker(object) 显示时间选择弹窗
object
属性 | 类型 | 默认值 | 必填 | 说明 |
---|
title | string | | 否 | 弹窗标题 |
value | number[] | | 否 | 默认选择值 |
mode | DatePickerMode | | 否 | 选择的模式,可选 'date', 'time', 'datetime' 等 |
minDate | Date | 当天对应 10 年前的 Date 实例 | 否 | 最小时间对应的 Date 实例(含) |
maxDate | Date | 当天最后一秒的 Date 实例 | 否 | 最大时间对应的 Date 实例(含) |
filter | DatePickerOptionFilter | | 否 | 选项过滤器 |
success | (payload: SuccessPayload) => void | | 否 | 接口调用成功(在用户做出选择后,如取消,选择选项)的回调函数 |
fail | (e: Error) => void | | 否 | 接口调用失败(如传入错误的参数)的回调函数(不传入 fail 遇错误直接抛出) |
complete | () => void | | 否 | 弹窗关闭或调用失败的回调函数 |
SuccessPayload
属性 | 类型 | 说明 |
---|
confirm? | boolean | 为 true 时,表示点击了确定,此时返回 detail |
cancel? | boolean | 为 true 时,表示取消 |
detail? | DatePickerDetail | |
Usage
具体调用方式可以参考API 调用。
showDatePicker({
title: 'DatePicker',
success: ({ confirm, cancel, detail }) => {
...
}
})
类型释义
SelectorValue
type SelectorValue = string | number | Date
SelectorModelValue
type SelectorModelValue = SelectorValue | SelectorValue[]
注:在不自定义 formatter/parser
的情况下,value 只有 number[]
这种情况。
DatePickerDetail
interface DatePickerDetail {
label: string
value: number[]
}
字段 | 说明 |
---|
label | 选中值对应的描述文本,如果设置了 formatTemplate 或 formatter ,则返回格式后文本 |
value | 选择的值,如 [2021, 5, 1],不受 formatTemplate 或 formatter 影响 |
interface SelectorValueFormatter {
(valueArray: SelectorValue[], labelArray: string[]):
| { value: SelectorModelValue; label: string }
| SelectorModelValue
}
将 value 的原始值转为需要的自定义值,值需要满足 SelectorModelValue
的类型约束,可以返回 { value, label } 对两个数据进行修改,或者单独返回 value。
SelectorValueParser
interface SelectorValueParser {
(value: unknown): SelectorValue[]
}
跟 SelectorValueFormatter
相反,将自定义 value 的值转为组件认识的原始数组。
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
interface DatePickerOptionFilter {
(
number: number,
type: 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second'
): boolean
}
通过返回 false
来过滤指定选项。