Date & Time: components 051-058 (wip)

2026-10-05 12:22:05 -04:00
1 parent cfc7ab023d
commit e61e38b656
@@ -0,0 +1,55 @@
+# 055 TimeRangePicker · 时间范围选择器
+
+## 用途
+
+编辑开始与结束时间，校验顺序；跨午夜必须显式开启。
+
+## 最小示例
+
+```go
+shift := mujica.TimeRange{Start: mujica.TimeOfDay{Hour: 22}, End: mujica.TimeOfDay{Hour: 6}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	opts := mujica.TimeRangePickerOptions{Label: "Night shift", AllowOvernight: true}
+	if mujica.TimeRangePicker(c, &shift, opts).Changed() {
+		fmt.Println("shift", shift.Start, shift.End, shift.Overnight())
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func TimeRangePicker(c *ui.Context, value *TimeRange, opts TimeRangePickerOptions) DateTimeResult`，返回值嵌入 `*ui.Element`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Seconds` | `bool` | false | 显示秒。 |
+| `Hour12` | `bool` | false | 12 小时制。 |
+| `MinuteStep` | `int` | 0（即 1） | 分钟步长。 |
+| `SecondStep` | `int` | 0（即 1） | 秒步长。 |
+| `Min` | `TimeOfDay` | 00:00:00 | 两端最早时间。 |
+| `Max` | `TimeOfDay` | 零值（即 23:59:59） | 两端最晚时间。 |
+| `AllowOvernight` | `bool` | false | 允许结束早于开始，表示次日结束，并显示“次日”。 |
+| `Disabled` | `bool` | false | 禁用。 |
+| `Label` | `string` | 空 | 整组名称。 |
+
+## 状态
+
+同 TimePicker；范围不合法时两端都显示错误边框；跨午夜时显示“+1 day / 次日”。
+
+## 事件
+
+`Changed()`：两端都合法且顺序正确、与原值不同时为 true。
+
+## 键盘操作
+
+- 两端各自按 TimePicker 操作；Tab 从开始移到结束。
+
+## 限制
+
+- 未开启 `AllowOvernight` 时传入跨午夜的值会 panic（编程错误）。
+- 开始等于结束视为错误。
+- `TimeRange.Overnight()` 报告是否跨午夜。
+- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
+- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。