输入类

时间选择器

用户使用时间选择器可以方便地选择某一符合要求的、格式化的时间点

代码演示

如何引入

<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

基础使用

点击 TimePicker,然后可以在浮层中选择或者输入某一时间。

代码
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

<template>
    <TimePicker />
</template>

无限滚动

版本V2.22.0开始,我们将 TimePicker 内的 ScrollItem 的默认模式从 wheel 变更为了 normal, 若想应用回无限滚动的效果,可参考以下示例。

代码
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

<template>
    <TimePicker :scrollItemProps="{ mode: 'wheel', cycled: true }" />
</template>

受控组件

使用 v-model 作为受控组件,初始值用 defaultValue。传 null 是受控的空值,undefined 视为非受控;受控值从有值变回 undefined 时输入框清空并转为非受控。清除后 v-model 收到的单选值为 undefined,范围值为空数组。

代码
<script setup lang="ts">
    import { ref } from 'vue';
    import { TimePicker } from '@fibrous/semi-ui-vue';

    const value = ref<Date | (Date | undefined)[] | null | undefined>(null);
    const onChange = (time: unknown) => console.log(time);
</script>

<template>
    <TimePicker v-model="value" @change="onChange" />
</template>

不同的 Format 格式

TimePicker 浮层中的列会随着 format 变化,当略去 format 中的某部分时,浮层中对应的列也会消失。

NOTE: format 遵循 date-fns v4 的 format 格式。 https://date-fns.org/docs/format

代码
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

<template>
    <TimePicker defaultValue="10:24" format="HH:mm" />
</template>

设置面板头部,底部

禁用时间选择

代码
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

<template>
    <TimePicker defaultValue="12:08:23" disabled />
</template>

设置步长

可以使用 hourStep, minuteStep, secondStep 按步长展示可选的时分秒。

代码
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

<template>
    <TimePicker :minuteStep="15" :secondStep="10" />
</template>

12 小时制

12 小时制的时间选择器,默认的 format 为 a h:mm:ss,传入的 format 格式必须在 dateFns 日期格式范围之内。

例如默认的 12 小时制格式串为:a h:mm:ss,如果传入 A h:mm:ss 则会导致无法正确格式化。



代码
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <TimePicker use12Hours />
        <br />
        <br />
        <TimePicker format="a h:mm" use12Hours />
    </div>
</template>

时间范围

传入 type="timeRange" 开启时间范围选择。



代码
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <TimePicker :defaultValue="['10:23:15', '12:38:32']" type="timeRange" />
        <br />
        <br />
        <TimePicker :defaultValue="['上午 08:11', '下午 11:21']" format="a h:mm" type="timeRange" use12Hours />
    </div>
</template>

Range 模式下分别禁用左右面板(disabledTime)

当 type="timeRange" 时,你可以通过 disabledTime(value, panelType) 对左右面板分别应用不同的禁用规则。

  • value:当前已选时间数组,未选的一侧为 undefined(如 [date, undefined]);没有值时为空数组,value、defaultValue 或输入框只含一个时间时长度为 1
  • panelType:'left' | 'right',分别代表开始/结束面板

下面示例实现:选择开始时间后,右侧结束时间面板会禁用早于开始时间的选项。

代码
<script setup lang="ts">
    import { TimePicker } from '@fibrous/semi-ui-vue';

    const range = (length: number) => Array.from({ length }, (_, i) => i);

    // The right panel disables everything earlier than the start time picked on the left
    const disabledTime = (value: (Date | undefined)[], panelType: 'left' | 'right') => {
        const start = value[0];
        if (panelType === 'right' && start) {
            const h = start.getHours();
            const m = start.getMinutes();
            return {
                disabledHours: () => range(h),
                disabledMinutes: (hour: number) => (hour === h ? range(m) : []),
            };
        }
        return {};
    };
</script>

<template>
    <TimePicker :disabledTime="disabledTime" type="timeRange" />
</template>

自定义触发器

默认情况下我们使用 Input 组件作为 TimePicker 组件的触发器,通过 #trigger 作用域插槽你可以自定义这个触发器。作用域参数为 { value, inputValue, placeholder, disabled, componentProps, onChange },其中 value 未选的一侧为 undefined,onChange 用于更新输入框文本,效果同键入。

代码
<script setup lang="ts">
    import { ref } from 'vue';
    import * as dateFns from 'date-fns';
    import { IconTimePicker } from '@fibrous/semi-icons-vue/lab';
    import { Tag, TimePicker } from '@fibrous/semi-ui-vue';

    const formatToken = 'HH:mm:ss';
    const time = ref<Date | (Date | undefined)[] | undefined>(new Date(2024, 0, 1, 10, 30, 0));
</script>

<template>
    <TimePicker v-model="time" :format="formatToken">
        <template #trigger="{ placeholder }">
            <Tag color="cyan" shape="circle" size="large" :style="{ padding: '12px', paddingRight: '16px', fontSize: '14px' }" type="light">
                <template #prefixIcon>
                    <IconTimePicker />
                </template>
                {{ time instanceof Date ? dateFns.format(time, formatToken) : placeholder }}
            </Tag>
        </template>
    </TimePicker>
</template>

时区设置

Semi 所有关于时区的配置都收敛在 ConfigProvider 中,详细使用可以参考 ConfigProvider

Select Time Zone:


TimePicker:
代码
<script setup lang="ts">
    import { ref } from 'vue';
    import { ConfigProvider, Select, TimePicker } from '@fibrous/semi-ui-vue';

    const timeZone = ref('GMT+08:00');
    const defaultTimestamp = 1581599305265;
    const gmtList: string[] = [];
    for (let hourOffset = -11; hourOffset <= 14; hourOffset++) {
        const prefix = hourOffset >= 0 ? '+' : '-';
        gmtList.push(`GMT${prefix}${String(Math.abs(hourOffset)).padStart(2, '0')}:00`);
    }

    const onChange = (date: unknown, dateString: string | string[]) => console.log('DatePicker changed: ', date, dateString);
</script>

<template>
    <ConfigProvider :timeZone="timeZone">
        <div :style="{ width: '300px' }">
            <h5 :style="{ margin: '10px' }">Select Time Zone:</h5>
            <Select aria-label="时区" :modelValue="timeZone" placeholder="请选择时区" showClear :style="{ width: '300px' }" @select="timeZone = String($event)">
                <Select.Option v-for="gmt in gmtList" :key="gmt" :value="gmt">{{ gmt }}</Select.Option>
            </Select>
            <br />
            <br />
            <h5 :style="{ margin: '10px' }">TimePicker:</h5>
            <TimePicker :defaultValue="defaultTimestamp" @change="onChange" />
        </div>
    </ConfigProvider>
</template>

API 参考

Props

属性说明类型默认值
modelValue当前时间,配合 v-model 使用;type 为 timeRange 时为数组。传 null 是受控的空值,undefined 视为非受控。TimePickerValue | (TimePickerValue | undefined)[] | nullundefined
defaultValue非受控时的初始时间,形态同 modelValue。TimePickerValue | (TimePickerValue | undefined)[]semiGlobalDefault("TimePicker", "defaultValue")
open面板是否打开,配合 v-model:open 使用;undefined 视为非受控。booleanundefined
defaultOpen非受控时面板是否默认打开。booleansemiDefault("TimePicker", "defaultOpen", false)
type选择类型,time 为单个时间,timeRange 为时间范围。TimePickerTypesemiDefault("TimePicker", "type", strings.DEFAULT_TYPE)
format展示的时间格式,遵循 date-fns 的 format;use12Hours 时默认为 a h:mm:ss,否则为 HH:mm:ss。stringsemiGlobalDefault("TimePicker", "format")
use12Hours使用 12 小时制。booleansemiDefault("TimePicker", "use12Hours", false)
hourStep小时选项的间隔,必须是正整数。numbersemiGlobalDefault("TimePicker", "hourStep")
minuteStep分钟选项的间隔,必须是正整数。numbersemiGlobalDefault("TimePicker", "minuteStep")
secondStep秒选项的间隔,必须是正整数。numbersemiGlobalDefault("TimePicker", "secondStep")
disabled禁用全部操作。booleansemiDefault("TimePicker", "disabled", false)
disabledHours返回禁止选择的小时。Type(() => number[])undefined
disabledMinutes按所选小时返回禁止选择的分钟。Type((selectedHour: number) => number[])undefined
disabledSeconds按所选小时和分钟返回禁止选择的秒。Type((selectedHour: number, selectedMinute: number) => number[])undefined
disabledTime仅范围模式生效:按当前值与面板位置返回左右面板各自的禁用规则。value 中未选的一侧为 undefined;返回的 disabledHours、disabledMinutes、disabledSeconds 覆盖对应的同名属性,未返回的回退到同名属性。Type((value: (Date | undefined)[], panelType: PanelType) => DisabledTimeFns)undefined
hideDisabledOptions隐藏禁止选择的选项。booleansemiDefault("TimePicker", "hideDisabledOptions", false)
placeholder没有值时显示的提示,默认按 type 取语言包文案。stringsemiGlobalDefault("TimePicker", "placeholder")
rangeSeparator时间范围的分隔符。stringTypesemiDefault("TimePicker", "rangeSeparator", strings.DEFAULT_RANGE_SEPARATOR)
size输入框的大小。SizesemiDefault("TimePicker", "size", "default")
borderless无边框模式。booleansemiDefault("TimePicker", "borderless", false)
showClear是否展示清除按钮。booleansemiDefault("TimePicker", "showClear", true)
inputReadOnly输入框只读,避免在移动设备上打开虚拟键盘。booleansemiDefault("TimePicker", "inputReadOnly", false)
validateStatus校验状态。"default" | "error" | "warning" | "success"semiGlobalDefault("TimePicker", "validateStatus")
insetLabelIdinsetLabel 的 id,用于 aria-labelledby 关联。stringundefined
inputStyle输入框根元素的样式。StyleValuesemiGlobalDefault("TimePicker", "inputStyle")
autofocus挂载时让输入框获得焦点,同时打开面板。booleansemiDefault("TimePicker", "autofocus", false)
focusOnOpen挂载后让输入框获得焦点并选中内容,同时打开面板。booleansemiDefault("TimePicker", "focusOnOpen", false)
preventScroll指示浏览器是否应滚动文档以显示新聚焦的元素,作用于组件内的 focus 方法。booleansemiGlobalDefault("TimePicker", "preventScroll")
motion是否展示弹出层动画。booleansemiDefault("TimePicker", "motion", true)
autoAdjustOverflow浮层被遮挡时是否自动调整方向。booleansemiDefault("TimePicker", "autoAdjustOverflow", true)
position浮层位置,type 为 timeRange 时默认为 bottom,为 time 时默认为 bottomLeft。Type"top" | "bottom" | "left" | "right" | "topLeft" | "topRight" | "leftTop" | "leftBottom" | "rightTop" | "rightBottom" | "bottomLeft" | "bottomRight" | "leftTopOver" | "rightTopOver" | "leftBottomOver" | "rightBottomOver"semiGlobalDefault("TimePicker", "position")
popupClassName弹出层的类名。stringsemiGlobalDefault("TimePicker", "popupClassName")
popupStyle弹出层的样式。StyleValuesemiGlobalDefault("TimePicker", "popupStyle")
stopPropagation是否阻止弹出层上的点击事件冒泡。booleansemiDefault("TimePicker", "stopPropagation", true)
timeZone时区,未设置时依次取 ConfigProvider 的 timeZone、全局默认值。string | numberundefined
scrollItemProps传给各列的属性,只支持 cycled、mode、motion、transform,含义同 ScrollList 的 ScrollItem。TimePickerScrollItemPropssemiGlobalDefault("TimePicker", "scrollItemProps")

Events

事件说明回调参数
update:modelValue时间变化时触发,供 v-model 回写;清除后单选为 undefined,范围为空数组,范围中未选的一侧为 undefined。[value: Date | (Date | undefined)[] | undefined]
change时间变化时触发,参数为 (Date 值, 格式化字符串),范围模式下两者都是数组。Type[value: Date | (Date | undefined)[] | undefined, str: string | string[]]
update:open面板打开或关闭时触发,供 v-model:open 回写。[open: boolean]
openChange面板打开或关闭时触发。[open: boolean]
focus输入框根元素获得焦点时触发;焦点在输入框与清除按钮之间移动不触发。[event: FocusEvent]
blur点击外部关闭面板时触发,参数为该次 mousedown 的原生事件;离开输入框不触发。[event: MouseEvent]

Slots

插槽说明作用域参数
trigger自定义触发器,替代默认的输入框,点击其中任意位置打开面板。参数含 value(未选的一侧为 undefined)、inputValue、placeholder、disabled、componentProps 与 onChange(更新输入框文本,效果同键入)。TimePickerTriggerSlotProps
panelHeader面板头部内容,参数 index 为面板序号(单选为 0,范围为 0 或 1)。范围模式下未提供时显示语言包的「开始时间」「结束时间」。TimePickerPanelSlotProps
panelFooter面板底部内容,参数 index 为面板序号。TimePickerPanelSlotProps
panel仅范围模式:同时作为第 index 个面板的头部和底部,有内容时优先于 panelHeader 与 panelFooter。TimePickerPanelSlotProps
prefix输入框的前缀内容。any
insetLabel输入框的内嵌标签。any
clearIcon自定义清除图标,showClear 为 true 时有效。any

Exposes

名称说明类型
focus使输入框获得焦点,同时打开面板;自定义触发器时无效。Type() => void
blur移除输入框的焦点;自定义触发器时无效。Type() => void

未声明的属性中,class、style 落在根元素上,其余(id、title、aria-*、data-*、事件监听等)落在内部输入框上;使用 #trigger 自定义触发器时,全部落在根元素上,传 aria-label 或 aria-labelledby 时根元素的 role 为 group。focus、blur 事件声明为组件事件,@focus、@blur 只收到组件事件,不再收到冒泡上来的原生事件。

通过 ref 调用 focus()、blur(),使用自定义触发器时无效。

Accessibility

ARIA

  • 输入框的 role 为 combobox,带 aria-haspopup="dialog"、随面板开关变化的 aria-expanded,aria-controls 指向面板
  • 时、分、秒与上午/下午列是 role 为 listbox 的列表,名称分别为「小时」「分钟」「秒」「上午或下午」

键盘和焦点

  • 输入框获得焦点时打开面板;面板打开后按 下箭头,焦点移入第一列
  • 每列是一个 Tab 停靠点,上箭头、下箭头、Home、End 或输入字符选择该列的值
  • 按 Esc 关闭面板;焦点在面板内时回到输入框

文案规范

  • 时间选择器至少包括时和分,如:11:30,它在本地化过程中,可以适应为12小时制或者24小时制
  • 当选择12小时制,需要和AM/PM一起搭配使用

设计变量

下表是组件内部的 Sass 变量,不能覆写。定制样式请覆写 --semi-* CSS 变量(见 Design Token 页),或写不分层的 CSS 规则。
Sass 变量值用法
$color-timePicker_range_picker_panel_split-bordervar(--semi-color-border)时间选择器菜单分割线颜色
$color-timePicker_range_panel-borderrgba(0, 0, 0, 0.1)时间选择器描边颜色
$width-timePicker_range_panel-border1px时间选择器菜单分割线宽度
$height-timePicker_panel_body252px时间选择器菜单高度
$width-timePicker_panel_list_ampm72px时间选择器菜单中列宽度 - 上午下午
$width-timePicker_panel_list_hour64px时间选择器菜单中列宽度 - 小时
$width-timePicker_panel_list_minute64px时间选择器菜单中列宽度 - 分钟
$width-timePicker_panel_list_second64px时间选择器菜单中列宽度 - 秒
$width-timePicker_range_panel_scrolllist_body-border2px时间范围选择器双排菜单中间分割线宽度
$spacing-timePicker_range_panel_scrolllist_header_body-padding0时间范围选择器菜单header与内容内边距
$radius-timePicker_range_panelvar(--semi-border-radius-medium)时间范围选择器菜单圆角
$radius-timePicker_inputvar(--semi-border-radius-small)时间范围选择器圆角
$shadow-timePicker_range_panelvar(--semi-shadow-elevated)时间范围选择器菜单阴影