summary 属性在屏幕阅读器和导出数据中均无效:html5 已废除该属性,主流读屏软件不解析,dom/css/js 均无法访问,且所有导出工具(csv/excel/json)均忽略它;替代方案需组合使用 caption、data-* 属性和 visually-hidden 元素。

summary 属性在屏幕阅读器和导出数据两个场景中,都不起作用——它既不会被读屏软件解析,也不会被任何导出逻辑(CSV/Excel/JSON)识别或提取。
为什么 summary 对屏幕阅读器完全失效
HTML5 已明确废除 summary 属性,主流屏幕阅读器(NVDA、JAWS、VoiceOver)不再读取它。部分旧版 JAWS 甚至会因检测到该属性而跳过整个表格,或报“obsolete attribute”警告。浏览器解析时直接忽略该属性:DOM 中查不到 table.summary,JS 无法读取,CSS 无法样式化,aria-label 也不会继承它。
- 用 VoiceOver 或 NVDA 测试时,聚焦表格只会朗读
caption内容(如果存在),然后直接进入第一行数据;summary不会出现 - axe、WAVE 等可访问性扫描工具会标记
summary为 “obsolete attribute”,并提示 “Missing caption” - 构建流程中(如 HTMLHint、eslint-plugin-jsx-a11y)会报错,CI 可能因此失败
导出数据时 summary 不会被任何工具识别
导出逻辑(无论是前端 JS 库如 SheetJS、TableExport,还是后端模板渲染)只依赖 DOM 结构和显式可读文本。由于 summary 不是文本节点、不参与渲染、不出现在 innerHTML 中,所有导出路径都无视它。
-
document.querySelector('table').outerHTML返回的字符串里不含summary属性值(浏览器已剥离) - CSV 导出通常遍历
th/td文本内容,或读取data-*属性,summary不在采集范围内 - 若想让字段说明进入导出文件,必须显式写入:比如在第一行插入说明行,或用
data-export-desc这类自定义属性配合 JS 提取
真正能同时服务读屏与导出的替代方案
靠单一属性实现“双场景辅助”不现实,但用组合结构可以兼顾两者:caption 服务读屏,data-* + JS 服务导出,visually-hidden 段落服务复杂语义。
-
caption必须是<table> 的第一个子元素,内容需具体(如 <code><caption>2024 年 Q2 用户退款申请汇总(含状态分类)</caption>),读屏优先读它 - 字段级说明不要塞
caption,改用<details><summary>销售额</summary>当月成交净额,不含运费补贴</details>,既可折叠展示,又可被 JS 提取为导出注释 - 导出前动态构造说明行:遍历
th,读取其data-desc属性(如<th data-desc="自然月累计,单位:万元">销售额</th>),插入 CSV 第一行 - 复杂口径说明用
<p id="sales-note" class="visually-hidden">注:退款率 = 退款金额 / 成交总额,剔除测试订单</p>,配合aria-describedby="sales-note"供读屏使用,JS 导出时也可按 ID 提取文本
最易被忽略的是:可访问性和导出不是“加个属性就完事”。summary 已是一条断路,修复它需要重写表格语义结构——从 caption 开始,用 scope 绑定单元格关系,再用 data- 属性锚定导出逻辑。三者缺一不可,否则读屏只报数字,导出只留空表头。











