# 树

可展开的层级列表：文件目录、组织架构、分类。写一个嵌套的 <ul>，库渲染成带展开箭头的行；可选复选框（父级根据子级显示全选、半选、未选）、单选高亮和完整的键盘操作。

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

## 用法

```html
<div class="zh-tree" data-zh-tree data-checkable aria-label="文件" style="max-width:20rem">
  <ul>
    <li data-id="src" data-open data-icon="file-text">src
      <ul>
        <li data-id="a" data-checked>index.js</li>
        <li data-id="b">style.css</li>
        <li data-id="c" data-disabled>locked.txt</li>
      </ul>
    </li>
    <li data-id="docs" data-icon="file-text">docs
      <ul><li data-id="d">readme.md</li></ul>
    </li>
  </ul>
</div>
```

## 样式类

`zh-tree`、`zh-tree-row`、`zh-tree-toggle`、`zh-tree-check`、`zh-tree-icon`、`zh-tree-label`、`zh-tree--guides`

## 属性

| 属性 | 用在 | 取值 | 说明 |
|---|---|---|---|
| `data-zh-tree` | <div class="zh-tree"> | 里面放一个嵌套的 <ul> | 声明为树；<li> 的文字是节点名称，子级写在它里面的 <ul> 里 |
| `data-id` | <li> | 唯一标识 | 事件和方法里用它指代节点；不写会自动生成 |
| `data-icon` | <li> | 图标名 | 节点前的图标 |
| `data-open` | <li> |  | 该节点默认展开 |
| `data-checked` | <li> |  | 默认选中（仅复选模式；父级的状态由子级算出） |
| `data-disabled` | <li> |  | 禁用，不可选择、不可勾选 |
| `data-checkable` | 容器 |  | 显示复选框 |
| `data-no-select` | 容器 |  | 不要点击高亮（只做展开或勾选时用） |
| `data-toggle-on-click` | 容器 |  | 点击整行也展开或收起，不只是点箭头 |
| `zh-tree--guides` | 容器（class） |  | 显示缩进参考线 |

## 方法

- `ZhaoUI.tree.checked(el)`：返回选中的叶子节点 id 数组
- `ZhaoUI.tree.expandAll(el) / collapseAll(el)`：全部展开 / 收起
- `ZhaoUI.tree.select(el, id)`：选中某个节点并展开它的祖先；找不到返回 false

## 事件

| 事件 | 触发于 | detail | 说明 |
|---|---|---|---|
| `zh:tree-select` | 容器 | undefined | 点击或回车选中某个节点 |
| `zh:tree-check` | 容器 | undefined | 勾选变化；ids 是当前全部选中的叶子节点的 data-id |
| `zh:tree-toggle` | 容器 | undefined | 展开或收起 |

## 无障碍

- 容器 role=tree，行 role=treeitem，带 aria-level、aria-expanded、aria-checked、aria-selected
- 键盘：上下键移动，右键展开或进入子级，左键收起或回到父级，Home/End 到首尾，回车选中，空格勾选（无复选框时选中）
- 勾选结果通过隐藏的 aria-live 区域读出
- 请给容器加 aria-label 说明这棵树是什么
- 不含拖拽排序、行内重命名和按需加载子节点；这些需要你自己处理数据后重新渲染

## 常见问题

### 树是什么？

可展开的层级列表：文件目录、组织架构、分类。写一个嵌套的 <ul>，库渲染成带展开箭头的行；可选复选框（父级根据子级显示全选、半选、未选）、单选高亮和完整的键盘操作。

### 怎么使用树？

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

### 树有哪些事件？

zh:tree-select（点击或回车选中某个节点）；zh:tree-check（勾选变化；ids 是当前全部选中的叶子节点的 data-id）；zh:tree-toggle（展开或收起）。

### 树有哪些方法？

ZhaoUI.tree.checked(el)：返回选中的叶子节点 id 数组；ZhaoUI.tree.expandAll(el) / collapseAll(el)：全部展开 / 收起；ZhaoUI.tree.select(el, id)：选中某个节点并展开它的祖先；找不到返回 false。

### 树支持键盘和读屏吗？

容器 role=tree，行 role=treeitem，带 aria-level、aria-expanded、aria-checked、aria-selected；键盘：上下键移动，右键展开或进入子级，左键收起或回到父级，Home/End 到首尾，回车选中，空格勾选（无复选框时选中）；勾选结果通过隐藏的 aria-live 区域读出。

### 树需要依赖框架吗？

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