# TimePicker

> 通过模拟时钟表盘或数字网格选择小时与分钟，并回传选中的时间。

Source: https://crossfly.dev/zh/docs/ui/widgets/timepicker — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# TimePicker

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

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

## 何时使用
- 采集一个时刻（`HH:MM`）。

## 何时不要使用
- 采集日期 → 使用 [`DatePicker`](/docs/ui/widgets/datepicker)。

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

## 完整示例（复制、粘贴并运行）
```java
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` 骨架中。

## 基本用法
```java
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()` 被重写，以在关闭前**停止"当前时间"的计时器**。

### 预设并响应选择
```java
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/`](/docs/ui) · 食谱：[`cookbook/`](/docs/cookbook)
- 模式基础：[`Picker`](/docs/ui/widgets/picker)
- 相关组件：[`DatePicker`](/docs/ui/widgets/datepicker)