aria-atomic

何时使用

在更新内容只有作为完整单元朗读才有意义的实时区域上使用。典型示例是单行状态提示，如 “找到 3 条结果”——若实时区域设为 aria-atomic="false"（默认值），且仅数字发生变化，屏幕阅读器可能只播报 “3”，缺失上下文。设置 aria-atomic="true" 后，将播报完整句子。

在以下情况下设置 aria-atomic="false"（或省略该属性）：

• 区域是日志或聊天面板，每条新消息自成一体——“Alice：你好”、“Bob：嗨”。每次都播报整个日志会令人难以忍受。
• 只有新内容才携带新信息。

在以下情况下设置 aria-atomic="true"：

• 区域是含义依赖相邻词语的简短固定短语——“购物车合计：$42.18”、“第 3 页，共 12 页”、“已应用筛选条件：2 个”。
• 区域内部的小型 DOM 变更本身意义有限。

aria-atomic 独立于 aria-live 和 aria-busy，三者协同工作，但调节的是不同方面。

如何保持同步

有效值为 "true" 和 "false"，默认值为 "false"。

在实时区域上一次性设置该属性后保持不变——它是区域播报方式的属性，而非随时间变化的状态。该属性也会继承：对父元素应用 aria-atomic="true" 会使后代实时区域同样具有原子性，除非被覆盖。

若更新策略是”替换整个区域的文本”，aria-atomic="true" 能产生最自然的播报效果。若更新策略是”追加新行”，通常应使用 aria-atomic="false"，以便仅朗读追加的行。

常见失误

• 将 aria-atomic 保持默认值用于单行状态提示，结果只听到 “5” 而非 “找到 5 条结果”。
• 在聊天日志上设置 aria-atomic="true"——每条新消息都会导致整个日志被重新朗读。
• 仅更新原子区域内的某个 <span>，却对周围文本也被播报感到困惑。这正是原子性的含义。
• 在没有 aria-live 且没有隐式实时角色的区域上使用 aria-atomic——该属性不会生效。
• 在可聚焦控件上设置 aria-atomic。实时区域属性应放在状态容器上，而非交互元素上。

示例

<!-- 原子模式：整个句子是完整消息 -->
<p aria-live="polite" aria-atomic="true">
  Cart total: <span id="cart-total">$0.00</span>
</p>

<!-- 非原子模式：仅播报新增行 -->
<ul aria-live="polite" aria-atomic="false" id="chat-log">
  <li>Alice: hi there</li>
</ul>