aria-haspopup="grid" 必须搭配 role="grid" 容器及完整 ARIA 网格结构才能被屏幕阅读器正确识别，仅写该属性无效；需同时满足：按钮设 aria-haspopup="grid" 和 aria-expanded，通过 aria-controls 关联带 role="grid" 的弹出容器，且容器内含 role="row" 和 role="gridcell"，每个单元格有可访问名称。
aria-haspopup="grid" 必须搭配 role="grid" 容器才能被正确识别
只写 aria-haspopup="grid" 不会触发屏幕阅读器朗读“关联网格”，它只是声明“这个按钮会展开一个 grid 类型的弹出内容”，但若弹出层没按 ARIA 规范实现，AT 就无法建立语义链。常见错误是：按钮写了 aria-haspopup="grid"，弹出层却用 div + display: grid，没设 role="grid"，也没标记 role="row" 和 role="gridcell" —— 这时 NVDA 或 VoiceOver 会忽略“grid”语义，只当普通弹窗处理。
必须满足以下三点，AT 才会把按钮和弹出网格关联起来并朗读状态：
- 按钮上同时设置
aria-haspopup="grid"和aria-expanded="false"（初始态） - 弹出容器有唯一 ID，并被按钮通过
aria-controls="popup-id"显式引用 - 弹出容器本身设
role="grid"，且内部结构符合 WAI-ARIA 网格规范：含role="row"行、每行含role="gridcell"单元格、所有单元格有可访问名称（aria-label或aria-labelledby）
为什么 grid 弹出层不能只靠 display: grid 布局
display: grid 是纯视觉布局，对屏幕阅读器完全透明。即使你用 CSS 划了 4×3 网格，AT 也只看到一堆无序的 div，读不出行列关系，更不会响应方向键导航。所以 aria-haspopup="grid" 的语义落地，必须靠 DOM 结构补全，不是靠样式。
典型错误写法：
立即学习“前端免费学习笔记（深入）”；
<button aria-haspopup="grid" aria-expanded="false">打开数据面板</button> <div class="popup-grid"> <div>A1</div><div>B1</div> <div>A2</div><div>B2</div> </div>
这段代码里，aria-haspopup="grid" 实际无效——因为弹出层没角色、没行列标记、没可访问名称。正确写法必须显式标注：
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
<button aria-haspopup="grid" aria-expanded="false" aria-controls="data-grid">打开数据面板</button>
<div id="data-grid" role="grid">
<div role="row">
<div role="gridcell" aria-label="销售额">¥120,000</div>
<div role="gridcell" aria-label="完成率">92%</div>
</div>
</div>
aria-expanded 要随真实状态同步更新
aria-expanded 不是静态属性，它必须与弹出层的显示/隐藏状态严格一致。如果用户点击按钮后 JS 没调用 element.setAttribute('aria-expanded', 'true')，或者关闭时没设回 'false'，屏幕阅读器就会误判当前状态——比如读作“已展开”，实际弹窗根本没出来，或反过来。
容易被忽略的细节：
- 用
dialog元素时，showModal()/close()不会自动更新aria-expanded，必须手动同步 - 如果弹出层用
visibility: hidden或opacity: 0隐藏，但 DOM 仍在，aria-expanded仍需设为false，否则 AT 认为它“逻辑可见” - 键盘用户按 Esc 关闭弹窗时，也要记得重置
aria-expanded，否则 Tab 键再聚焦按钮时，AT 仍会读“已展开”
网格内单元格必须有可访问名称，否则 aria-haspopup="grid" 失效
WAI-ARIA 规范要求：role="grid" 容器下的每个 role="gridcell" 必须有可访问名称（accessible name），否则会被判定为“结构不完整”，部分读屏器直接跳过整个网格，连带让 aria-haspopup="grid" 失去上下文依据。
可访问名称来源优先级： aria-labelledby > aria-label > 可见文本（仅当无其他属性时才 fallback）。但注意：
- 纯数字或符号单元格（如
<div role="gridcell">✓</div>）必须加aria-label，否则 AT 读作“方块”或静默跳过 - 用
aria-labelledby关联表头时，目标元素必须存在且非aria-hidden="true" - 不要依赖
title属性提供名称——它不参与可访问名称计算，且多数读屏器不朗读title
最常被跳过的环节，就是以为“写了 role="gridcell" 就够了”，结果单元格既无文本又无 ARIA 名称，整个网格在无障碍树里变成空节点。这时 aria-haspopup="grid" 就像挂了个空招牌，AT 根本找不到它承诺的“网格”在哪。
