# 时间线

按时间顺序展示事件：左侧一条轨道和圆点，右侧是标题、时间、说明。圆点颜色表示状态（primary、success、warning、danger、info），进行中的项显示转圈。可以带头像、引用、附件，以及点击展开的详情。

**依赖**：`zhaoui.css` 与 `zhaoui.js`（原生 HTML、CSS、JS，不需要框架或 jQuery）。

## 用法

```html
<ol class="zh-tl">
  <li class="zh-tl-item zh-tl-item--success"><div class="zh-tl-rail"><span class="zh-tl-dot" aria-hidden="true"></span></div>
    <div class="zh-tl-body"><div class="zh-tl-head"><span class="zh-tl-title">订单已创建</span><time class="zh-tl-time" datetime="2026-10-04T09:00">09:00</time></div><div class="zh-tl-desc">订单 #20261004</div></div></li>
  <li class="zh-tl-item zh-tl-item--primary"><div class="zh-tl-rail"><span class="zh-tl-dot" aria-hidden="true"></span></div>
    <div class="zh-tl-body"><div class="zh-tl-head"><span class="zh-tl-title">仓库已接单</span><time class="zh-tl-time" datetime="2026-10-04T09:12">09:12</time></div>
      <button type="button" class="zh-tl-toggle" aria-expanded="false" aria-controls="tl-d1"><i data-i="chevron-right" data-s="14"></i><span>展开详情</span></button>
      <div class="zh-tl-detail" id="tl-d1"><div class="zh-tl-detail-wrap"><div class="zh-tl-detail-in">上海仓 · 拣货员 A12 已接单，预计 20 分钟内出库。</div></div></div></div></li>
  <li class="zh-tl-item zh-tl-item--pending" aria-label="进行中：派送中"><div class="zh-tl-rail"><span class="zh-tl-dot zh-tl-dot--icon" aria-hidden="true"><i data-i="loader-circle" data-s="14" class="zh-tl-spin"></i></span></div>
    <div class="zh-tl-body"><div class="zh-tl-head"><span class="zh-tl-title">派送中</span></div></div></li>
</ol>
```

## 样式类

`zh-tl`、`zh-tl-item`、`zh-tl-rail`、`zh-tl-dot`、`zh-tl-body`、`zh-tl-head`、`zh-tl-title`、`zh-tl-time`、`zh-tl-desc`、`zh-tl-quote`、`zh-tl-toggle`、`zh-tl-detail`、`zh-tl--alt`、`zh-tl--right`、`zh-tl--compact`、`zh-tl--feed`

## 属性

| 属性 | 用在 | 取值 | 说明 |
|---|---|---|---|
| `zh-tl` | <ol>（class） | 里面放 zh-tl-item | 时间线容器 |
| `zh-tl-item--primary\|success\|warning\|danger\|info\|pending` | <li>（class） |  | 圆点和轨道的状态色；pending 表示进行中，圆点换成转圈 |
| `zh-tl-dot--hollow` | 圆点（class） |  | 空心点；zh-tl-dot--icon 放图标，再加 zh-tl-dot--lg 变大 |
| `zh-tl-quote` | 正文里的容器 |  | 引用块，如审批意见 |
| `zh-tl-toggle + zh-tl-detail` | 展开按钮与详情容器 |  | 点击按钮展开详情，库负责切换 aria-expanded 与文字；按钮上可用 data-open / data-close 自定义文字 |
| `zh-tl--alt / --right / --compact / --feed` | <ol>（class） |  | 左右交替 / 靠右 / 紧凑 / 动态流（带头像） |

## 事件

| 事件 | 触发于 | detail | 说明 |
|---|---|---|---|
| `zh:timeline-toggle` | <ol> | undefined | 详情展开或收起 |

## 无障碍

- 用有序列表 <ol>，顺序对读屏有意义
- 时间用 <time datetime="…">
- 圆点是装饰，加 aria-hidden="true"；状态要在文字里体现，不要只靠颜色
- 进行中的项给 <li> 加 aria-label，如“进行中：派送中”

## 常见问题

### 时间线是什么？

按时间顺序展示事件：左侧一条轨道和圆点，右侧是标题、时间、说明。圆点颜色表示状态（primary、success、warning、danger、info），进行中的项显示转圈。可以带头像、引用、附件，以及点击展开的详情。

### 怎么使用时间线？

先在页面里引入 zhaoui.css 和 zhaoui.js（放在 </body> 前，不加 defer），再照本页「用法」里的标记书写。

### 时间线有哪些事件？

zh:timeline-toggle（详情展开或收起）。

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

用有序列表 <ol>，顺序对读屏有意义；时间用 <time datetime="…">；圆点是装饰，加 aria-hidden="true"；状态要在文字里体现，不要只靠颜色。

### 时间线需要依赖框架吗？

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