时间选择器 - Semi Design Next

代码演示

如何引入

import { TimePicker } from '@fibrous/semi-ui-solid';

基础使用

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

代码

import { TimePicker } from '@fibrous/semi-ui-solid';

export default function TimePickerDemo() {
    return <TimePicker />;
}

无限滚动

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

代码

import { TimePicker } from '@fibrous/semi-ui-solid';

export default function TimePickerDemo() {
    return <TimePicker scrollItemProps={{ mode: 'wheel', cycled: true }} />;
}

受控组件

当使用 value 而不是 defaultValue 时，作为受控组件使用。value 和 onChange 需要配合使用，传 null 是受控的空值。

代码

import { createSignal } from 'solid-js';
import { TimePicker } from '@fibrous/semi-ui-solid';

export default function TimePickerDemo() {
    const [value, setValue] = createSignal<Date | Date[] | null>(null);

    const onChange = (time: Date | Date[]) => {
        console.log(time);
        setValue(time);
    };

    return <TimePicker value={value()} onChange={onChange} />;
}

不同的 Format 格式

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

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

代码

import { TimePicker } from '@fibrous/semi-ui-solid';

export default function TimePickerDemo() {
    return <TimePicker format="HH:mm" defaultValue="10:24" />;
}

设置面板头部，底部

代码

import { createSignal } from 'solid-js';
import { TimePicker, Button } from '@fibrous/semi-ui-solid';

export default function TimePickerDemo() {
    const [open, setOpen] = createSignal(false);
    const closePanel = () => setOpen(false);
    const onOpenChange = (open: boolean) => {
        setOpen(open);
        console.log(open);
    };

    return (
        <div>
            <TimePicker open={open()} onOpenChange={onOpenChange} panelHeader="Time Select" panelFooter={<Button onClick={closePanel}>close</Button>} />
            <br />
            <br />
            <TimePicker
                type="timeRange"
                panelHeader={['start header', 'end header']}
                panelFooter={[
                    <Button
                        onClick={() => {
                            console.log('start footer');
                        }}
                    >
                        start footer
                    </Button>,
                    <Button
                        onClick={() => {
                            console.log('end footer');
                        }}
                    >
                        end footer
                    </Button>,
                ]}
            />
        </div>
    );
}

禁用时间选择

代码

import { TimePicker } from '@fibrous/semi-ui-solid';

export default function TimePickerDemo() {
    return <TimePicker defaultValue="12:08:23" disabled />;
}

设置步长

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

代码

import { TimePicker } from '@fibrous/semi-ui-solid';

export default function TimePickerDemo() {
    return <TimePicker minuteStep={15} secondStep={10} />;
}

12 小时制

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

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

代码

import { TimePicker } from '@fibrous/semi-ui-solid';

export default function TimePickerDemo() {
    return (
        <div>
            <TimePicker use12Hours />
            <br />
            <br />
            <TimePicker use12Hours format="a h:mm" />
        </div>
    );
}

时间范围

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

代码

import { TimePicker } from '@fibrous/semi-ui-solid';

export default function TimePickerDemo() {
    return (
        <div>
            <TimePicker type="timeRange" defaultValue={['10:23:15', '12:38:32']} />
            <br />
            <br />
            <TimePicker type="timeRange" use12Hours format="a h:mm" defaultValue={['上午 08:11', '下午 11:21']} />
        </div>
    );
}

Range 模式下分别禁用左右面板（disabledTime）

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

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

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

代码

import { TimePicker } from '@fibrous/semi-ui-solid';

export default function TimePickerDemo() {
    return (
        <TimePicker
            type="timeRange"
            disabledTime={(value, panelType) => {
                const start = value[0];
                if (panelType === 'right' && start) {
                    const h = start.getHours();
                    const m = start.getMinutes();
                    return {
                        disabledHours: () => Array.from({ length: h }, (_, i) => i),
                        disabledMinutes: (hour) => (hour === h ? Array.from({ length: m }, (_, i) => i) : []),
                    };
                }
                return {};
            }}
        />
    );
}

自定义触发器

默认情况下我们使用 Input 组件作为 TimePicker 组件的触发器，通过传递 triggerRender 函数你可以自定义这个触发器。triggerRender 只调用一次，入参的字段都是活的，需要在返回的 JSX 中读取（如 props.placeholder）才会随之更新。

12:00:00

代码

import { createSignal, Show } from 'solid-js';
import * as dateFns from 'date-fns';
import { IconTimePicker } from '@fibrous/semi-icons-solid/lab';
import { Tag, TimePicker } from '@fibrous/semi-ui-solid';

export default function TimePickerDemo() {
    const formatToken = 'HH:mm:ss';
    const [time, setTime] = createSignal<Date | undefined>(new Date(2024, 4, 6, 12));

    return (
        <TimePicker
            value={time()}
            format={formatToken}
            onChange={(value: Date) => setTime(value)}
            triggerRender={(props) => (
                <Tag color="cyan" size="large" shape="circle" style={{ padding: '12px', 'padding-right': '16px', 'font-size': '14px' }} type="light" prefixIcon={<IconTimePicker />}>
                    <Show when={time()} fallback={props.placeholder}>
                        {(date) => dateFns.format(date(), formatToken)}
                    </Show>
                </Tag>
            )}
        />
    );
}

时区设置

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

Select Time Zone:

TimePicker:

代码

import { createSignal, For } from 'solid-js';
import { ConfigProvider, Select, TimePicker } from '@fibrous/semi-ui-solid';

const defaultTimestamp = 1581599305265;

const gmtList = Array.from({ length: 26 }, (_, i) => {
    const hourOffset = i - 11;
    const prefix = hourOffset >= 0 ? '+' : '-';
    return `GMT${prefix}${String(Math.abs(hourOffset)).padStart(2, '0')}:00`;
});

export default function TimePickerDemo() {
    const [timeZone, setTimeZone] = createSignal('GMT+08:00');

    return (
        <ConfigProvider timeZone={timeZone()}>
            <div style={{ width: '300px' }}>
                <h5 style={{ margin: '10px' }}>Select Time Zone:</h5>
                <Select aria-label="时区" placeholder="请选择时区" style={{ width: '300px' }} value={timeZone()} showClear onSelect={(value) => setTimeZone(String(value))}>
                    <For each={gmtList}>{(gmt) => <Select.Option value={gmt}>{gmt}</Select.Option>}</For>
                </Select>
                <br />
                <br />
                <h5 style={{ margin: '10px' }}>TimePicker:</h5>
                <TimePicker defaultValue={defaultTimestamp} onChange={(date: Date, dateString: string) => console.log('DatePicker changed: ', date, dateString)} />
            </div>
        </ConfigProvider>
    );
}

API 参考

Props

属性	说明	类型	默认值
autoAdjustOverflow	浮层被遮挡时是否自动调整方向。	`boolean`	`true`
borderless	无边框模式。	`boolean`	`false`
class	根元素的类名。	`string`	-
clearIcon	自定义清除图标，showClear 为 true 时有效。	`JSX.Element`	-
defaultOpen	非受控时面板是否默认打开。	`boolean`	-
defaultValue	非受控时的初始时间，形态同 value；type 为 timeRange 时为数组。	`BaseValueType \| BaseValueType[]`	-
disabled	禁用全部操作。	`boolean`	-
disabledHours	返回禁止选择的小时。	`Type`	-
disabledMinutes	按所选小时返回禁止选择的分钟。	`Type`	-
disabledSeconds	按所选小时和分钟返回禁止选择的秒。	`Type`	-
disabledTime	仅范围模式生效：按当前值与面板位置返回左右面板各自的禁用规则。value 中未选的一侧为 undefined；返回值中的 disabledHours、disabledMinutes、disabledSeconds 覆盖顶层的同名属性，未返回的回退到顶层。单选模式下忽略。	`Type`	-
focusOnOpen	挂载后让输入框获得焦点并选中内容，同时打开面板。	`boolean`	`false`
format	展示的时间格式，遵循 date-fns 的 format；use12Hours 为 true 时默认为 a h:mm:ss，否则为 HH:mm:ss。	`string`	-
hideDisabledOptions	隐藏禁止选择的选项。	`boolean`	`false`
hourStep	小时选项的间隔，必须是正整数。	`number`	-
inputReadOnly	输入框只读，避免在移动设备上打开虚拟键盘；只读时清除按钮仍可用。	`boolean`	`false`
inputStyle	输入框根元素的样式，接受对象（键用 kebab-case）或字符串。	`JSX.CSSProperties \| string`	-
insetLabel	输入框内部的前缀标签，显示在输入框内。	`JSX.Element`	-
insetLabelId	insetLabel 的 id，用于 aria-labelledby 等关联。	`string`	-
maxLength	输入框的最大字符数，透传给输入框。	`number`	-
minLength	输入框的最小字符数，透传给输入框。	`number`	-
minuteStep	分钟选项的间隔，必须是正整数。	`number`	-
motion	是否展示弹出层动画。	`boolean`	`true`
onBlur	点击外部关闭面板时的回调，参数为该次 mousedown 的原生事件。	`Type`	-
onChange	时间变化的回调。type 为 time 时参数为 (Date, 格式化字符串)，type 为 timeRange 时两者都是数组。	`Type`	-
onFocus	输入框获得焦点时的回调。	`Type`	-
onOpenChange	面板打开或关闭时的回调，参数为是否打开。	`Type`	-
open	面板是否打开，受控属性；undefined 视为非受控。	`boolean`	-
panelFooter	面板底部的内容。范围模式下可传数组，第 i 项用于第 i 个面板。	`JSX.Element`	-
panelHeader	面板头部的内容。范围模式下可传数组，第 i 项用于第 i 个面板。	`JSX.Element`	-
panels	仅范围模式：第 i 项同时作为第 i 个面板的头部和底部，优先于 panelHeader 与 panelFooter。单选模式下忽略。	`JSX.Element[]`	-
placeholder	没有值时显示的提示，默认取语言包中对应 type 的文案。	`string`	-
popupClassName	弹出层的类名。	`string`	-
popupStyle	弹出层的样式，接受对象（键用 kebab-case）或字符串。	`JSX.CSSProperties \| string`	-
position	浮层位置，type 为 timeRange 时默认为 bottom，为 time 时默认为 bottomLeft；RTL 方向下默认为 bottomRight。	`Position`	-
prefix	输入框的前缀内容。	`JSX.Element`	-
prefixCls	样式类名的前缀。	`string`	`"semi-timepicker"`
preventScroll	指示浏览器是否应滚动文档以显示新聚焦的元素，作用于组件内的 focus 调用。	`boolean`	-
rangeSeparator	时间范围的分隔符。	`string`	`" ~ "`
ref	根元素的引用；其 focus() 与 blur() 作用于输入框，使用自定义触发器时无效。	`Type`	-
scrollItemProps	传给各列的属性，只支持 cycled、mode、motion、transform，含义同 ScrollList 的 ScrollItem。	`Type`	-
secondStep	秒选项的间隔，必须是正整数。	`number`	-
showClear	是否展示清除按钮。	`boolean`	`true`
size	输入框的大小，可选 large、default 或 small。	`InputSize`	`"default"`
stopPropagation	是否阻止弹出层上的点击事件冒泡。	`boolean`	`true`
style	根元素的样式，接受对象（键用 kebab-case）或字符串。	`JSX.CSSProperties \| string`	-
timeZone	时区：数字为相对 UTC 的小时偏移，字符串为 IANA 时区名；未设置时取 ConfigProvider 的 timeZone。	`string \| number`	-
triggerRender	自定义触发器的渲染函数，只调用一次，入参的字段都是活的，在返回的 JSX 中读取才会更新。入参含 disabled、placeholder、value（Date 数组，未选的一侧为 undefined）、inputValue、componentProps（TimePicker 的属性，不含 ref）和 onChange（更新输入框文本，效果同键入）。	`Type`	-
type	选择类型，time 为单个时间，timeRange 为时间范围。	`Type`	`"time"`
use12Hours	使用 12 小时制，为 true 时 format 默认为 a h:mm:ss。	`boolean`	`false`
validateStatus	校验状态，仅影响展示样式。	`ValidateStatus`	-
value	当前时间，type 为 timeRange 时为数组；传 null 是受控的空值，undefined 视为非受控。	`BaseValueType \| BaseValueType[] \| null`	-

class、style 与 ref 落在根元素上，其余未声明的属性（id、title、aria-*、data-*、原生事件等）落在内部输入框上；使用 triggerRender 自定义触发器时，这些属性不落在任何元素上。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-border	var(--semi-color-border)	时间选择器菜单分割线颜色
$color-timePicker_range_panel-border	rgba(0, 0, 0, 0.1)	时间选择器描边颜色
$width-timePicker_range_panel-border	1px	时间选择器菜单分割线宽度
$height-timePicker_panel_body	252px	时间选择器菜单高度
$width-timePicker_panel_list_ampm	72px	时间选择器菜单中列宽度 - 上午下午
$width-timePicker_panel_list_hour	64px	时间选择器菜单中列宽度 - 小时
$width-timePicker_panel_list_minute	64px	时间选择器菜单中列宽度 - 分钟
$width-timePicker_panel_list_second	64px	时间选择器菜单中列宽度 - 秒
$width-timePicker_range_panel_scrolllist_body-border	2px	时间范围选择器双排菜单中间分割线宽度
$spacing-timePicker_range_panel_scrolllist_header_body-padding	0	时间范围选择器菜单header与内容内边距
$radius-timePicker_range_panel	var(--semi-border-radius-medium)	时间范围选择器菜单圆角
$radius-timePicker_input	var(--semi-border-radius-small)	时间范围选择器圆角
$shadow-timePicker_range_panel	var(--semi-shadow-elevated)	时间范围选择器菜单阴影