# 侧边菜单

后台常见的左侧导航：多级分组、当前页标记、可折叠成 64px 图标栏，支持键盘（方向键、Home/End、字母）。用嵌套的 <ul> 写，库会补齐 ARIA 树结构。

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

## 用法

```html
<nav class="zh-side" data-zh-side aria-label="站点导航" style="height:420px">
  <div class="zh-side-head"><i aria-hidden="true"></i><span>ZhaoUI</span></div>
  <ul>
    <li class="zh-side-group">工作台</li>
    <li><a href="#" data-icon="layout-dashboard">概览</a></li>
    <li><a href="#" data-icon="file-text">内容管理</a>
      <ul>
        <li><a href="#" aria-current="page" data-badge="12" data-badge-tone="soft">文章</a></li>
        <li><a href="#">媒体库</a></li>
      </ul>
    </li>
    <li><a href="#" data-icon="settings">系统设置</a></li>
  </ul>
</nav>
```

## 样式类

`zh-side`、`zh-side-head`、`zh-side-scroll`、`zh-side-group`、`zh-side-foot`

## 属性

| 属性 | 用在 | 取值 | 说明 |
|---|---|---|---|
| `data-zh-side` | <nav class="zh-side"> |  | 声明为侧边菜单；里面放一个嵌套 <ul> |
| `data-icon` | 每个 <a> | 图标名 | 可选，菜单项前的图标 |
| `data-num` | 每个 <a> | 序号文字，如 1 | 可选，在名称前显示序号（文档导航常用）；读屏读名称时忽略序号，折叠成图标栏时隐藏 |
| `data-badge` | <a> | 文字 \| dot | 可选，右侧角标；dot 是小红点 |
| `data-badge-tone` | <a> | soft | 角标用淡色底而不是红底 |
| `aria-current="page"` | 当前页的 <a> | page | 当前页；它所在的分组会默认展开 |
| `aria-disabled="true"` | <a> | true | 禁用的菜单项，不可点、不可跳转 |
| `data-open` | 含子菜单的 <li> |  | 该分组默认展开 |
| `data-collapsed` | <nav> |  | 初始为折叠的图标栏 |
| `data-collapsible` | <nav> | false | 不显示折叠按钮 |
| `zh-side-group` | <li>（class） | 分组标题文字 | 菜单里的分组小标题，不可点 |

## 方法

- `ZhaoUI.side.setActive(nav, hrefOrElement)`：按链接地址或元素设置当前页，并展开它的祖先；找不到返回 false
- `ZhaoUI.side.collapse(nav, collapsed?)`：折叠（默认）或展开图标栏

## 事件

| 事件 | 触发于 | detail | 说明 |
|---|---|---|---|
| `zh:side-select` | nav.zh-side | { item, href, label, path } | 点击叶子项时触发，可 preventDefault 取消；path 是从顶层到该项的名称数组。href 为 # 或为空时库不会跳转，只切换当前页 |
| `zh:side-collapse` | nav.zh-side | { collapsed } | 折叠或展开图标栏 |

## 无障碍

- 外层是 <nav aria-label="…">，库给列表加 role=tree，项加 role=treeitem 和 aria-level
- 键盘：上下键移动，右键展开或进入子级，左键收起或回到父级，Home/End 到首尾，空格激活
- 折叠成图标栏后，每项通过 title 显示名称；点击有子菜单的项会先展开侧栏

## 常见问题

### 侧边菜单是什么？

后台常见的左侧导航：多级分组、当前页标记、可折叠成 64px 图标栏，支持键盘（方向键、Home/End、字母）。用嵌套的 <ul> 写，库会补齐 ARIA 树结构。

### 怎么使用侧边菜单？

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

### 侧边菜单有哪些事件？

zh:side-select（点击叶子项时触发，可 preventDefault 取消；path 是从顶层到该项的名称数组。href 为 # 或为空时库不会跳转，只切换当前页）；zh:side-collapse（折叠或展开图标栏）。

### 侧边菜单有哪些方法？

ZhaoUI.side.setActive(nav, hrefOrElement)：按链接地址或元素设置当前页，并展开它的祖先；找不到返回 false；ZhaoUI.side.collapse(nav, collapsed?)：折叠（默认）或展开图标栏。

### 侧边菜单支持键盘和读屏吗？

外层是 <nav aria-label="…">，库给列表加 role=tree，项加 role=treeitem 和 aria-level；键盘：上下键移动，右键展开或进入子级，左键收起或回到父级，Home/End 到首尾，空格激活；折叠成图标栏后，每项通过 title 显示名称；点击有子菜单的项会先展开侧栏。

### 侧边菜单需要依赖框架吗？

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