Sidebar 侧边导航
Sidebar 侧边导航是在同一产品或模块内,以纵向列表持续呈现多个目的地的导航区域。它适合桌面管理工具、开发工具和复杂工作台;它不是任意放在页面左边的工具面板,也不等于 ARIA menu 或 tree。
能力边界与前置知识
本文讨论用于页面导航的 Sidebar,不讨论:
- 文档大纲;
- 筛选面板;
- 属性检查器;
- 聊天联系人列表;
- 只放图标的应用启动栏;
- 可拖动改变主内容的分栏容器。
这些结构可能也位于侧边,但任务、语义和键盘模型不同。
前置知识:
- 能区分产品级、模块级、对象内导航;
- 了解 URL、页面标题、当前项和深链;
- 了解 HTML 链接、列表、
nav地标与焦点顺序; - 能列出加载、无权限、窄屏和错误状态。
完成本文后,应能决定是否使用 Sidebar,定义导航数据模型,处理分组、折叠、权限、当前项和窄屏转换,并验证键盘、屏幕阅读器和路由行为。
Sidebar 解决什么问题
Sidebar 适合以下条件同时成立的任务:
- 同一产品范围内有较多稳定目的地;
- 用户会在多个目的地之间反复切换;
- 当前目的地需要持续可见;
- 纵向空间比横向空间充足;
- 桌面是重要使用环境;
- 目的地名称需要比图标提供更多信息。
不适用情形:
- 只有 3 到 5 个稳定顶级区域,顶部导航已足够;
- 内容阅读需要占满横向空间,导航使用频率低;
- 侧边内容本质是当前页面筛选;
- 层级频繁变化且没有稳定命名;
- 移动端是唯一平台;
- 用户需要同时查看两个工作对象,实际需要的是分栏而非导航。
Sidebar 的组成
导航地标
使用 <nav> 表达一组页面导航链接。
页面只有一个导航地标时,名称可以省略;页面同时有产品导航、项目导航和页内导航时,每个地标需要按目的区分:
<nav aria-label="产品">
<!-- 产品级目的地 -->
</nav>
<nav aria-label="项目">
<!-- 当前项目目的地 -->
</nav>2
3
4
5
6
7
名称应表达用途,不写“左侧导航”。位置会随窄屏布局改变,“左侧”不能说明这组链接负责什么。
产品或模块身份
Sidebar 顶部可以显示:
- 产品名;
- 当前工作区;
- 当前项目;
- 工作区切换入口。
身份区与目的地列表分开。切换工作区会改变整组导航数据和 URL 范围,不应伪装成普通目的地。
分组
分组降低长列表扫描成本。每组需要稳定规则,例如:
- 工作对象:项目、任务、成员;
- 运营能力:自动化、报表;
- 管理能力:权限、账单、审计。
不要按页面所有者团队分组。用户不应先知道功能由“平台组”还是“增长组”开发。
分组标题通常是静态文本。只有标题确实控制子项显示时才使用按钮。
目的地
目的地使用链接,因为它改变页面位置并应支持:
- 新标签页打开;
- 复制链接;
- 浏览器后退和前进;
- 深链;
- 访问历史;
- 链接上下文菜单。
不要用只有 onClick 的 <div> 模拟链接。
当前项
当前项需要同时满足:
- 视觉高亮;
aria-current="page";- 页面标题与链接名称对应;
- URL 匹配正确;
- 祖先分组在需要时展开;
- 颜色不是唯一提示。
aria-selected 用于特定复合控件的选择状态,不是普通导航当前页的默认表达。
折叠控制
折叠可以有两种含义:
- 整个 Sidebar 从完整模式变成紧凑模式;
- 某个分组展开或收起子项。
两者状态、按钮名称和持久化策略必须分开。
整栏折叠按钮应说明结果,例如“收起项目导航”;折叠后按钮名称变为“展开项目导航”。
辅助操作
创建项目、添加成员等高频操作可以靠近相关导航,但必须与目的地链接区分:
- 导航使用链接;
- 写操作使用按钮;
- 危险操作不进入主导航;
- 操作完成后的目标位置和结果反馈明确。
信息模型
一个目的地至少包含:
{
"id": "project.members",
"label": "成员",
"href": "/workspaces/w-17/projects/p-42/members",
"group": "project",
"requiredCapability": "project.members.read",
"match": {
"kind": "route-segment",
"value": "members"
},
"badge": {
"kind": "count",
"value": 3,
"accessibleLabel": "3 个待处理邀请"
}
}2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
字段作用:
| 字段 | 作用 | 错误表现 |
|---|---|---|
id | 跨语言和改名稳定识别目的地 | 用 label 作键导致改名丢状态 |
label | 可见链接文本和可访问名称来源 | 只显示图标,目的不可理解 |
href | 深链和浏览器历史 | 点击后只改本地面板 |
group | 稳定分组 | 相同入口在多组重复 |
requiredCapability | 服务端返回的发现能力 | 前端按角色名硬编码 |
match | 当前项匹配规则 | /team 错误匹配 /teams |
badge | 补充状态,不替代链接名 | 只显示红点且读屏无信息 |
Sidebar 配置只决定呈现。服务端仍要对目标页面和所有数据执行授权。
路由与当前项匹配
精确匹配
适合没有子路由的目的地:
/settings/billing只有规范化路径完全相同时标记当前。
分段匹配
项目任务入口可以覆盖:
/projects/p-42/tasks
/projects/p-42/tasks/t-92
匹配应基于路由结构,不使用简单字符串前缀。否则 /tasks-old 也可能被误判。
查询参数
查询参数只改变筛选时,当前目的地通常不变:
/orders?status=refunding如果参数改变的是稳定任务模式,例如“设计”和“运行”两个独立工作区,应评估是否需要独立路由段或 Tabs。
重定向
先完成规范化重定向,再计算当前项。旧 URL 跳转后,导航只标记最终目的地。
多入口
搜索、通知和最近访问都可以进入同一页面。当前项由目标页面身份决定,不由来源入口决定。
层级:列表、Disclosure 还是 Tree
普通列表
多数 Sidebar 使用嵌套列表和普通链接已经足够:
<nav aria-labelledby="project-nav-title">
<h2 id="project-nav-title">项目</h2>
<ul>
<li><a href="/overview">概览</a></li>
<li><a href="/tasks" aria-current="page">任务</a></li>
<li><a href="/members">成员</a></li>
</ul>
</nav>2
3
4
5
6
7
8
Tab 键按页面顺序逐个到达链接。方向键不应被 JavaScript 接管。
Disclosure 分组
当分组可以折叠时,使用按钮控制嵌套列表:
<li>
<button
type="button"
aria-expanded="true"
aria-controls="automation-links">
自动化
</button>
<ul id="automation-links">
<li><a href="/rules">规则</a></li>
<li><a href="/runs">运行记录</a></li>
</ul>
</li>2
3
4
5
6
7
8
9
10
11
12
行为要求:
- Enter 或 Space 切换展开;
aria-expanded与真实可见状态同步;- 收起包含当前页的分组前应评估是否会隐藏当前位置;
- 收起时若焦点在子项内,先把焦点移到控制按钮;
- 页面重新加载后,至少自动展开当前项祖先。
Tree
只有在 Sidebar 真正是可交互层级树,并准备实现完整 Tree View 键盘模型时才使用 role="tree"。
Tree 会改变:
- Tab 序列;
- 方向键行为;
- 焦点管理;
- 展开状态;
- 层级和选中状态的程序化表达。
把普通站点导航加上 role="tree",却仍让 Tab 遍历每个链接,会制造不一致语义。
整栏展开与折叠
完整模式
显示图标和文字。文字是目的地的主要名称。
紧凑模式
只显示图标时必须保证:
- 每个链接仍有可访问名称;
- 图标含义在产品中稳定;
- 鼠标和键盘都能获得文字说明;
- 当前项不只通过背景色表达;
- 徽标不会遮挡图标或焦点;
- 200% 缩放后仍可操作。
紧凑模式适合熟练用户节省空间,不应作为新用户默认方案,除非同时提供可理解标签。
持久化
折叠偏好可以保存在:
- 当前页面内存;
- 当前设备本地存储;
- 服务端个人偏好。
不要跨不同屏幕宽度直接复用同一个布尔值。桌面“紧凑”与移动端“抽屉关闭”是不同状态。
状态模型
| 状态 | 可见结果 | 可用操作 | 退出条件 |
|---|---|---|---|
| 加载导航 | 保留稳定框架或明确加载 | 主内容按独立条件处理 | 权限与导航数据返回 |
| 完整 | 图标、文字、分组可见 | 跳转、展开、收起整栏 | 用户收起或进入窄屏 |
| 紧凑 | 图标与必要状态可见 | 跳转、展开整栏 | 用户展开 |
| 分组收起 | 子链接不可见 | 展开分组 | 用户展开或进入子路由 |
| 窄屏关闭 | 主内容可用,显示菜单按钮 | 打开导航 | 用户打开 |
| 窄屏打开 | 导航覆盖或推动内容 | 跳转、关闭 | 选择目的地、Escape 或关闭 |
| 无权限 | 受限入口被过滤或解释 | 申请权限、返回 | 权限改变 |
| 当前项失效 | 当前路由不再可访问 | 进入安全上级 | 重定向完成 |
| 导航加载失败 | 已知当前上下文仍保留 | 重试、使用主内容 | 请求恢复 |
导航加载失败不应把主内容中的已确认数据一起清空。主内容和导航可以有不同请求生命周期。
键盘与焦点
桌面普通列表
- Tab 和 Shift+Tab 按 DOM 顺序移动;
- Enter 激活链接;
- 浏览器提供链接上下文菜单;
- 不接管方向键;
- 焦点指示满足可见性与对比要求;
- 固定头部或底部不能完全遮住焦点。
窄屏抽屉
打开:
- 菜单按钮更新
aria-expanded="true"; - 导航变为可见;
- 焦点进入导航标题或当前项,选择规则保持一致;
- 主内容是否变为 inert 取决于是否为模态实现。
关闭:
- Escape、关闭按钮或选择目的地可关闭;
aria-expanded变为false;- 焦点回到菜单按钮;若导航触发了页面跳转,则进入新页合理起点;
- 不把焦点留在已隐藏链接中。
若导航不是模态抽屉而是推动内容,不应错误实现焦点陷阱。
分组收起
焦点位于被收起子项时,收起操作前把焦点移到分组按钮。直接 display:none 会使焦点落到不可见节点。
窄屏与重排
可选方案:
| 方案 | 适用条件 | 主要风险 |
|---|---|---|
| 模态抽屉 | 目的地多,打开时专注导航 | 焦点陷阱和背景禁用 |
| 非模态覆盖 | 用户可能同时参考主内容 | 覆盖内容、焦点位置不清 |
| 推动内容 | 导航与主内容都需可见 | 320 CSS px 下空间不足 |
| 独立导航页 | 层级深、移动任务以导航为主 | 多一次页面转换 |
| 精简顶栏 + 更多页 | 移动端高频目的地少 | “更多”中的可发现性 |
窄屏不能简单设置 display:none。必须提供可见触发器、展开状态、关闭方式和焦点恢复。
测试条件:
- 320 CSS px 等效宽度;
- 200% 文本缩放;
- 40 字目的地名称;
- 系统大字体;
- 横屏与竖屏切换;
- 触屏、键盘和读屏;
- 当前项在列表底部;
- 导航内容本身可滚动。
权限与动态导航
隐藏还是禁用
用于导航的无权限目的地通常有三种处理:
| 处理 | 适用情况 | 风险 |
|---|---|---|
| 隐藏 | 用户无需知道该能力存在 | 难以发现升级或申请路径 |
| 显示并进入说明页 | 允许了解能力和申请方式 | 必须避免泄露受限数据 |
| 禁用并解释 | 当前上下文暂不可用 | 禁用链接的语义和键盘体验较差 |
选择必须按产品权限模型确定,不是一条通用规则。
权限变化
权限可能在页面打开后变化:
- 服务端返回新的导航能力;
- 当前项仍可读时更新其他入口;
- 当前项不可读时进入明确无权限状态;
- 提供安全上级或申请权限;
- 不把用户静默送回首页;
- 所有目标页面继续执行服务端授权。
功能开关
功能开关改变入口时,记录:
- 谁能看见;
- 旧深链怎样处理;
- 当前项在开关关闭后去哪里;
- 搜索和帮助文档是否同步;
- 已保存书签怎样恢复。
徽标与动态数量
徽标适合补充:
- 未读数;
- 待处理数;
- 运行中状态;
- 新功能标记。
边界:
- 链接名称仍能独立表达目的地;
- 数量说明对象,例如“3 个待处理邀请”;
- 高频更新不反复打断读屏;
- 大数量使用明确上限展示,但可访问名称不制造错误精度;
- 数量请求失败不让整个导航不可用;
- 徽标不作为高风险告警的唯一入口。
案例一:资产管理平台
任务与数据
管理员在设备、成员、策略、自动化和审计之间频繁切换。
固定数据:
- 6 个顶级模块;
- “设备”下 4 个子目的地;
- 2 个角色;
- 18,000 台设备;
- 3 个待处理策略;
- 一个被功能开关关闭的实验模块。
方案
使用完整 Sidebar:
资产平台
├─ 概览
├─ 设备
│ ├─ 全部设备
│ ├─ 分组
│ ├─ 软件
│ └─ 合规
├─ 成员
├─ 策略 [3]
├─ 自动化
└─ 审计2
3
4
5
6
7
8
9
10
11
“设备”分组使用 disclosure;各子项仍是普通链接。“策略 3”表达待处理策略,不是未读消息。
当前项
访问:
/workspaces/w-17/devices/d-2048/softwareSidebar 标记“软件”为当前页,同时展开“设备”。“设备”父项不再额外标记为当前页,只通过展开和视觉层级表达祖先关系。
权限分支
普通成员不能访问“审计”:
- 导航不显示“审计”;
- 直接 URL 返回无权限页;
- 无权限页仍显示工作区身份;
- 提供返回“概览”的链接;
- 不显示任何审计事件名称或数量。
失败注入
导航数量请求返回 503。
正确结果:
- 目的地链接仍可使用;
- “策略”徽标显示不可用或暂时省略;
- 当前项不丢失;
- 不把整个 Sidebar 替换成错误页;
- 错误日志包含徽标请求 ID。
验证
- Owner 与 Member 的入口符合服务端能力;
- 旧审计书签对 Member 不泄露数据;
- Tab 顺序与视觉顺序一致;
- 收起“设备”时焦点不会消失;
- 当前项重载后自动展开;
- 200% 缩放后长名称可换行。
案例二:移动端告警深链
任务
值班人员从通知打开服务告警,查看详情后切换到同一服务的运行记录。
入口
/services/s-42/alerts/a-9窄屏默认关闭 Sidebar,页面顶部显示:
- 产品名;
- 当前服务“支付 API”;
- “打开服务导航”按钮;
- 告警详情标题。
打开导航
导航内容:
支付 API
├─ 概览
├─ 告警
├─ 运行记录
├─ 部署
└─ 设置2
3
4
5
6
当前项为“告警”。选择“运行记录”后:
- 路由进入
/services/s-42/runs; - Sidebar 关闭;
- 页面标题更新;
- 焦点进入新页面主标题;
- 浏览器后退回到原告警详情,不重复打开导航。
会话过期
如果用户打开导航后会话过期:
- 认证界面不保留敏感告警名称;
- 登录后恢复原深链;
- 重新获取当前服务和权限;
- 若服务已删除,进入明确失效状态;
- 不回退到不相关的产品首页。
窄屏失败
旧实现把 Sidebar 放在 position: fixed 层,关闭后没有恢复焦点,键盘焦点仍进入隐藏链接。
修正:
- 关闭时把导航从可交互树移除;
- 若没有发生跳转,焦点回菜单按钮;
- 若已跳转,焦点进入新页主标题;
- 自动化测试检查隐藏区域不存在可聚焦后代。
工程实现
数据与渲染分层
- 服务端根据主体、工作区和功能开关返回能力。
- 路由配置把能力映射为允许发现的目的地。
- 当前路由通过结构化匹配计算当前项。
- 展开状态由当前项祖先和用户偏好共同决定。
- 视口状态决定呈现为固定 Sidebar 还是窄屏导航。
- 目标页面独立执行授权。
不变量
- 同一 Sidebar 最多一个
aria-current="page"; - 所有可见目的地 ID 唯一;
- 当前项可见时,其祖先分组必须展开;
- 隐藏分组中不能保留焦点;
- 窄屏关闭后导航链接不可交互;
- 当前 URL 必须映射到一个目的地或明确“未映射”;
- 权限过滤不产生空分组;
- 折叠偏好不覆盖窄屏打开状态。
性能
Sidebar 通常不需要虚拟化。若目的地多到必须虚拟化,应先检查信息架构是否失控。
可优化:
- 导航配置与主内容并行获取;
- 对稳定配置使用版本化缓存;
- 徽标独立请求和独立失败;
- 预取高频只读页面,但缓存键包含工作区与权限;
- 路由切换不重新挂载整个导航;
- 图标使用可缓存资源,不为每项加载独立大图。
不要预取用户无权限的数据,也不要让旧权限缓存长期保留入口。
调试路径
当前项错误
检查顺序:
- 浏览器最终 URL;
- 重定向是否完成;
- 路由参数是否规范化;
- 查询参数是否参与页面身份;
- 匹配规则是否误用字符串前缀;
- 是否有两个目的地同时匹配;
- 页面标题是否来自同一节点配置。
折叠后焦点丢失
检查:
- 收起动作发生时
document.activeElement; - 子列表隐藏前是否移动焦点;
- CSS 只改变透明度还是同时禁止交互;
- 动画期间是否仍可 Tab 进入;
- 组件卸载后焦点是否退回
body。
窄屏不能关闭
检查:
- Escape 监听是否只在导航打开时启用;
- 关闭按钮是否在 Tab 顺序内;
- 遮罩是否遮挡按钮;
aria-expanded与视觉状态是否同步;- 路由变化后是否清理打开状态;
- 焦点陷阱是否把用户困在已关闭区域。
权限变化出现空组
检查服务端能力结果、客户端过滤顺序和分组清理。先过滤目的地,再删除没有任何可见子项且没有独立作用的分组。
指标与验证
任务指标
- 从入口到目标页面的成功率;
- 错误进入相邻模块的比例;
- 进入后 10 秒内返回或改用搜索的比例;
- 桌面与窄屏的导航打开到选择转化;
- 深链后使用 Sidebar 切换同对象页面的成功率。
指标按角色、平台、入口、数据规模和新旧用户分群。点击多可能代表高频使用,也可能代表绕路,不能单独判断。
无障碍验证
- 用地标列表识别“产品”和“项目”导航。
- 用 Tab 遍历所有可见链接和分组按钮。
- 检查当前页被程序化表达。
- 收起含焦点的分组。
- 打开和关闭窄屏导航。
- 在 200% 缩放下滚动到末项。
- 开启高对比模式检查当前项和焦点。
- 使用屏幕阅读器确认徽标数量有对象名称。
- 禁用 CSS 后检查链接列表仍有合理顺序。
- 直接进入深链并确认页面标题和导航上下文。
失败注入
- 导航配置请求失败;
- 徽标请求失败;
- 当前角色权限被撤销;
- 当前项目归档;
- 当前项名称为 40 个汉字;
- 路由重定向两次;
- 功能开关在页面打开后关闭;
- 窄屏打开时发生路由跳转;
- 当前项位于收起分组;
- 浏览器从后退缓存恢复页面。
每次记录可见结果、焦点位置、URL、当前项、网络响应和控制台错误。
综合练习
为一个至少有 20 个目的地的管理工具设计并实现 Sidebar。
交付物:
- 产品、模块和对象内导航边界;
- 节点数据模型;
- 分组与当前项匹配规则;
- 普通列表或 disclosure 的语义 HTML;
- 完整、紧凑、窄屏打开和窄屏关闭状态;
- Owner 与 Member 权限差异;
- 两个徽标及其失败降级;
- 深链、重定向和浏览器历史测试;
- 键盘与屏幕阅读器记录;
- 失败注入结果。
验收标准:
- 每个目的地使用真实链接;
- 同时只有一个当前页;
- 当前项祖先不会被隐藏;
- 无权限入口与目标页面授权一致;
- 整栏折叠、分组折叠和移动端关闭是独立状态;
- 窄屏关闭后不存在隐藏可聚焦链接;
- Escape、关闭按钮和路由跳转后的焦点结果明确;
- 徽标失败不阻断导航;
- 320 CSS px、200% 缩放和长文本可完成任务;
- 服务端不信任 Sidebar 的显示状态进行授权。
来源
- W3C WAI — Landmark Regions(访问日期:2026-07-18)
- W3C WAI — Navigation Landmark Example(访问日期:2026-07-18)
- W3C WAI — Disclosure Navigation Menu Example(访问日期:2026-07-18)
- W3C — Web Content Accessibility Guidelines (WCAG) 2.2(访问日期:2026-07-18)
- GOV.UK Design System — Navigate a service(访问日期:2026-07-18)