# 时间选择

时、分（可选秒）三列滚动选择，也可以直接键入。分钟可按步长取整。

**依赖**：`zhaoui.css` 与 `zhaoui.js`（原生 HTML、CSS、JS，不需要框架或 jQuery）。只用核心包时，还要加 `modular/date.min.js` 和 `modular/date.min.css`；全量版已包含。

## 用法

```html
<div data-zh-time data-name="at" data-value="09:30" aria-label="提醒时间"></div>
<div data-zh-time data-seconds data-step-minutes="15" data-value="14:15:10" aria-label="精确时间"></div>

<script>
document.querySelector('[data-zh-time]').addEventListener('zh:time-change', function (e) {
  console.log(e.detail.value);   // 09:45
});
</script>
```

## 样式类

`zh-dp`、`zh-tp-panel`、`zh-tp-cols`

## 属性

| 属性 | 用在 | 取值 | 说明 |
|---|---|---|---|
| `data-zh-time` | <div> | 无 | 声明这是时间选择 |
| `data-value` | 容器 | HH:mm 或 HH:mm:ss | 初始时间 |
| `data-seconds` | 容器 | 布尔属性 | 显示并允许选择秒 |
| `data-step-minutes` | 容器 | 整数，默认 1 | 分钟的步长，如 15；键入的分钟会四舍五入到最近的步长 |
| `data-name` | 容器 | 字段名 | 生成隐藏 <input name=…> 参与表单提交 |
| `data-size` | 容器 | sm \| md（默认）\| lg | 尺寸 |
| `aria-label / data-labelledby / data-label` | 容器 | 字符串 / 标签元素 id / 弹层标题 | 输入框的无障碍名称；data-label 是弹出面板的标题 |
| `<label for="容器 id">` | 容器所在页面的 <label> | for 指向容器的 id | label 会成为输入框的无障碍名称，点击 label 会聚焦输入框；容器是空 <div>，label 的 for 指向它的 id 即可 |

## 方法

- `ZhaoUI.timePicker(host, { value: { h, m, s }, seconds, stepM, size, label, onChange })`：命令式创建；value 是 { h, m, s } 对象
- `el.zhTime.get() / .set(value) / .open() / .close()`：get 返回 { h, m, s } 或 null；set 接受对象或 HH:mm 字符串，不触发事件

## 事件

| 事件 | 触发于 | detail | 说明 |
|---|---|---|---|
| `zh:time-change` | 容器 | { value: 'HH:mm' \| 'HH:mm:ss' \| '', time: { h, m, s } \| null } | 选择、键入确认、点「此刻」或清除后触发（冒泡） |

## 无障碍

- 每一列是一个 listbox，↑ ↓ 逐项移动，PageUp / PageDown 一次移动五个步长，Home / End 到首尾，← → 在时分秒列之间切换，Enter 确定
- 键入不合法（如 25:00）时标记 aria-invalid
- 面板底部有「此刻」和「确定」按钮

## 常见问题

### 时间选择是什么？

时、分（可选秒）三列滚动选择，也可以直接键入。分钟可按步长取整。

### 怎么使用时间选择？

先在页面里引入 zhaoui.css 和 zhaoui.js（放在 </body> 前，不加 defer），再照本页「用法」里的标记书写；需要用代码控制时，用「方法」里列出的接口。

### 时间选择有哪些事件？

zh:time-change（选择、键入确认、点「此刻」或清除后触发（冒泡））。

### 时间选择有哪些方法？

ZhaoUI.timePicker(host, { value: { h, m, s }, seconds, stepM, size, label, onChange })：命令式创建；value 是 { h, m, s } 对象；el.zhTime.get() / .set(value) / .open() / .close()：get 返回 { h, m, s } 或 null；set 接受对象或 HH:mm 字符串，不触发事件。

### 时间选择支持键盘和读屏吗？

每一列是一个 listbox，↑ ↓ 逐项移动，PageUp / PageDown 一次移动五个步长，Home / End 到首尾，← → 在时分秒列之间切换，Enter 确定；键入不合法（如 25:00）时标记 aria-invalid；面板底部有「此刻」和「确定」按钮。

### 时间选择需要依赖框架吗？

不需要。ZhaoUI 是原生 HTML、CSS 和 JavaScript，不依赖 jQuery、Vue 或 React。