TimePicker

TimePicker 通过两个模拟时钟（左侧为小时，右侧为分钟）配合可拖动的指针，或通过数字网格（列表模式）来选择小时和分钟。通过三个按钮确认：上午（AM）、下午（PM）和当前时间。遵循选择器的模式（参见 Picker）。

🟡 · 包： dev.crossfly.ui.picker · 继承： Picker · 样式： TimePickerStyle

何时使用

采集一个时刻（HH:MM）。

何时不要使用

采集日期 → 使用 DatePicker。

外观

顶部有大号显示（hh:mm）、一个时钟/网格切换按钮、时钟区域（或数字网格），以及一行 Manhã / Tarde / Atual 按钮。尺寸约为 Screen.minSize 的 85%。

完整示例（复制、粘贴并运行）

package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.picker.*;

/** 可执行的主界面。将 launcher 指向此类（classname）并运行：gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      Button abrir = new Button("Escolher hora");
      abrir.onAction(c ->
      {
         TimePicker tp = new TimePicker().setTime(8, 30);
         tp.show(answer -> Hint.show("Hora: " + (String) answer, 2000)); // "08:30"
      });
      add(LAY_AUTO, abrir);
   }
}

下面的片段仅展示核心部分（放入 onShow() 内的内容）。要运行它们，请将其放入上面的 MainWindow 骨架中。

基本用法

TimePicker tp = new TimePicker();
tp.show(answer -> campoHora.setText((String) answer)); // "08:30"

构造函数

构造函数	描述
`TimePicker()`	无参数；从当前时间开始。

属性与自定义

方法	类型	作用
`setTime(int hour, int minute)`	0-23 / 0-59（钳制）	预设时间。在 `show()` 之前调用。
`timeStyle(TimePickerStyle)`	样式	自定义样式。
`getHour()` / `getMinute()`	`int`	小时（0-23）/ 分钟。
`getTimeText()`	`String`	`HH:MM`（24 小时制），使用 `LocaleFormats.timeSeparator`。

回调与事件

回调	触发时机
`onSelect(Action)`	确认时（接收 `TimePicker`）。
`show(onAnswer)`	关闭时，交付 `String` 类型的 `HH:MM`。

getAnswer() 始终返回 24 小时制 HH:MM。标签和分隔符遵循 LocaleFormats.is24Hour/timeSeparator。

状态

时钟模式（listMode=false）或数字网格（listMode=true），通过切换按钮切换。
hide() 被重写，以在关闭前停止“当前时间”的计时器。

预设并响应选择

TimePicker tp = new TimePicker().setTime(8, 30);
tp.onSelect(p -> Debug.log("Escolhido: " + ((TimePicker) p).getTimeText()));
tp.show(answer -> campoHora.setText((String) answer)); // "08:30"

最佳实践

在 show() 之前调用 setTime —— 角度是在 onShow 中读取的。
结果始终是 24 小时制；如有需要，请在应用显示时转换为 12 小时制。

常见错误

在 show() 之后调用 setTime —— 不会反映到已构建的 UI 上。
假设 answer 为 12 小时制 —— 它始终是 24 小时制的 HH:MM。

另请参阅

领域指南：ui/ · 食谱：cookbook/
模式基础：Picker
相关组件：DatePicker