timePicker 时间选择

timePicker 支持用户输入或选择时间。

XML 元素

timePicker

Java 类

TypedTimePicker

基本用法

在线示例

时间可以直接通过键盘输入，或者在带有时间列表的弹窗选择。当点击控件或时钟按钮时，会显示弹窗。

下面的示例定义了带标签的 localTime 类型的 timePicker：

<timePicker id="timePicker" label="TimePicker" datatype="localTime"/>

数据类型

timePicker 是一个带类型的组件，支持通用的时间类型：

  • localTime

  • offsetTime

  • time

如需修改类型，使用 datatype 属性。

数据感知的 timePicker

在线示例

使用 dataContainer 和 property 属性将 timePicker 与一个实体属性绑定。数据容器提供实体实例，property 表示需要使用该组件编辑的属性。

<data>
    <instance id="taskDc"
              class="io.jmix.uisamples.entity.Task"
              fetchPlan="_local"/>
</data>
    <timePicker id="timePicker" label="TimePicker"
                     dataContainer="taskDc" property="dueDate"/>

间隔

在线示例

弹窗中显示时间的默认间隔为 1 小时。通过 step 属性可以自定义间隔。

在视图 XML 中设置 step 属性:

<timePicker id="timePicker" label="TimePicker" datatype="localTime"
            step="15m"/>

m 后缀 表示分钟。

step 属性支持通过不同的时间（chrono）单位设置灵活的间隔。时间值支持通过单位后缀实现便捷设置。

<timePicker step="2h"/> (1)
<timePicker step="1600s"/> (2)
<timePicker step="20m"/> (3)
1 2 小时间隔。
2 1600 秒（26 分 40 秒）间隔。
3 20 分钟间隔。

视图控制器中也可以设置：

@ViewComponent
private TypedTimePicker<Comparable> timePicker;

@Subscribe
public void onInit(InitEvent event) {
    timePicker.setStep(Duration.ofMinutes(30));
}

设置的时间间隔必须能整除一小时或一天。例如，“15分钟”、“30分钟”、“2小时” 都是有效的间隔；而 “42分钟” 则不是。

弹窗不会显示小于 15 分钟的间隔，是为了避免无效的时间选取。

时间范围

在线示例

如需将用户的输入控制在某个特定的时间范围内，使用 max 和 min 属性指定组件的最大最小值。

@ViewComponent
protected TypedTimePicker<LocalTime> timePicker;

@Subscribe
protected void onInit(InitEvent event) {
    timePicker.setMin(LocalTime.of(8, 0));
    timePicker.setMax(LocalTime.of(17, 0));
}

还可以使用 validator 检查是否符合某个特定的时间范围。

样式版本

在线示例

使用 themeNames 属性配置一个或多个样式。

样式 描述 支持的主题

small

组件尺寸较小

Aura, Lumo

align-left

字段值左对齐

Aura, Lumo

align-center

字段值居中

Aura, Lumo

align-right

字段值右对齐

Aura, Lumo

helper-above-field

帮助文字显示在字段上方，标题下方。

Aura, Lumo

XML 属性

下面是 timePicker 的特殊属性：

名称 描述 默认值

autoOpen

当用户开始使用控件时是否显示弹窗。

—

max

设置可选择的最大时间。

—

min

设置可选择的最小时间。

—

下面是 timePicker 支持的其他通用属性：

id - alignSelf - allowedCharPattern - ariaLabel - ariaLabelledBy - classNames - clearButtonVisible - colspan - css - dataContainer - datatype - enabled - errorMessage - focusShortcut - height - helperText - label - maxHeight - maxWidth - minHeight - minWidth - placeholder - property - readOnly - required - requiredMessage - step - tabIndex - themeNames - visible - width

事件和处理器

下面是 timePicker 的特殊事件和处理器：

名称 描述

InvalidChangeEvent

当组件的无效状态发生变化时触发。

validator

验证组件值。

下面是 timePicker 支持的其他通用事件：

AttachEvent - BlurEvent - ClientValidatedEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent - TypedValueChangeEvent - statusChangeHandler

XML 内部元素

一个 timePicker 可以包含 tooltip、validator 和 prefix 作为其内部元素。

参考