aria-controls 必须指向真实存在的唯一 ID，且需与 aria-expanded 或 aria-selected 配对使用；禁止用于非交互元素，动态加载时可省略，避免与 aria-hidden 冲突。

aria-controls 必须指向真实存在的 ID

它不是字符串占位符，而是 DOM 中必须能 document.getElementById() 找到的唯一标识。写错拼写、ID 不存在、或多个按钮共用同一 ID，都会让屏幕阅读器丢失目标关联。

• 确保被控元素（如 <div id="panel-1">）在 HTML 中真实存在，且不重复
• aria-controls 值必须与目标元素的 id 完全一致，大小写敏感
• 不要用 class 名、data 属性或动态生成但未挂载的 ID 替代——ARIA 只认已渲染的、可查的 ID

只用于可交互控件，且需配对 aria-expanded 或 aria-selected

aria-controls 单独存在没有语义价值。它必须和状态属性一起出现，否则读屏器只知道“控制谁”，不知道“当前状态如何”。

• 折叠面板场景：按钮上同时要有 aria-controls="panel-1" 和 aria-expanded="true"
• 选项卡场景：tab 上同时要有 aria-controls="tabpanel-1" 和 aria-selected="true"
• 禁止给 <div> 或纯展示元素加 aria-controls——它只应出现在可聚焦、可操作的元素上（如 <button>、<a href>、带 tabindex="0" 的元素）

动态加载内容时可以省略 aria-controls

当 tabpanel 或面板内容是按需加载、DOM 中暂不存在时，硬写 aria-controls="missing-id" 反而会触发读屏器报错或静默失败。ARIA 规范明确允许不使用它，只要用 aria-labelledby 反向关联即可。

Article To Html

文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。

下载

• 推荐做法：tab 元素设 aria-labelledby="tab-1"，对应 tabpanel 加 aria-labelledby="tab-1"
• 此时 tab 不必写 aria-controls，避免指向空 ID
• 仍需保证 tablist 与 tabpanel 在 DOM 中紧邻（通常 tablist 在前），提升读屏器上下文感知

别和 aria-hidden 混用导致语义冲突

如果被控元素设置了 aria-hidden="true"，而 aria-controls 又指向它，读屏器可能认为“这个目标不可访问”，从而忽略整个控制关系。

立即学习“前端免费学习笔记（深入）”；

• 面板收起时，优先用 display: none 或 visibility: hidden 隐藏，aria-hidden 可选但非必需
• 若显式加 aria-hidden="true"，必须和 aria-expanded="false" 同步更新，且确保目标元素本身仍保留在 DOM 中（不能 remove()）
• 绝对不要对父容器设 aria-hidden="true" 后，再在子元素里试图用 aria-controls 关联外部元素——继承规则会让关联失效

实际中最容易被忽略的是：ID 存在性验证和状态同步的时机。JS 切换面板时，先改 DOM 显隐，再设 aria-expanded，最后才触发 aria-controls 关联——但其实关联本身是静态的，真正易错的是“状态没跟上 DOM”。