流式输出的无障碍陷阱：别让Live Region每吐一个字就打断朗读

在给一个聊天Demo做键盘无障碍测试时，一个被延迟唤醒的回复暴露了问题：画面上的段落渲染得很流畅，但变更日志显示，那个被标记为 assertive 的气泡几乎在每一个数据块到达时都在重写自己。对普通视觉用户来说，这只是光标在平滑移动；但对依赖屏幕阅读器的用户来说，每一个新片段都在中止上一句朗读——这是一场"播报风暴"。

这篇文章记录了一位前端开发者排查这个问题的完整过程，核心结论很直接：流式Token需要一个安静的缓冲区，而不是一个激进的实时气泡。

看起来完成了，听起来却崩了

问题的本质是视觉层与无障碍层的严重错位。视觉层会立即追加Token，这正是大多数人用来截图炫耀"进度演示"的行为。而无障碍层把整个助手气泡当成了一个 assertive 实时区域，于是每个数据块都会打断前一段语音。

更隐蔽的是焦点问题：当一个代码围栏（Markdown fence）刚打开时，一个"复制"按钮就被挂载进了DOM，它偷走了输入框本该拥有的Tab停靠点。草稿还在内存里，但焦点已经移走，于是用户按下的下一个回车，落空了。

作者强调了一个容易被忽略的自检问题：你的状态文本只描述当前阶段，还是偷偷把整段对话内容复制了一遍？在这个案例里，状态区逐字复述了整段文字——这正是需要解开的第一个"谎言"。

ARIA Live Region 是W3C无障碍规范中用于动态内容通知的机制。当一个DOM区域被标记为 aria-live，屏幕阅读器就会监听其内容变化并自动朗读更新内容，无需用户将焦点移入该区域。assertive（急切）模式会立即打断当前正在朗读的任何内容；polite（礼貌）模式则等待当前语音结束后再播报。这个区别在静态内容场景下几乎不成问题——通知出现频率低，打断偶尔发生。但在流式AI输出场景中，Token以每秒数十次的速度到达，assertive 区域就会变成一台每隔几十毫秒就重启一次的播报机器，用户根本无法听清任何一个完整句子。主流屏幕阅读器（NVDA、JAWS、VoiceOver）在处理高频 Live Region 更新时的行为并不完全一致，有些会尝试合并短时间内的多次更新，有些则会老实地逐次打断，这进一步增加了跨平台调试的复杂度。

用"症状表"替代拍脑袋的归因

作者分享了一个实用的调试习惯：在编辑器旁放一张四列笔记——动作、像素表现、语音策略、我最初错怪的对象。只要某一行的"语音"列是空的，这个Bug就不算修完。

几个典型的误判值得警惕：

• 提交一个Prompt，看到流畅的Token，日志里每块都在重写，于是错怪"模型太啰嗦"。
• 在数据流爆发期按Tab，落进了代码围栏里一个无名的复制按钮，于是错怪浏览器。
• 按Esc，Spinner消失了，但没有阶段变化，于是错把"取消"当成纯视觉问题。
• 冷启动后数据洪流涌入，日志里是一次 assertive 的整段倾泻，于是错把延迟当成只是Spinner的事。

这张表的价值在于：当你因为"Spinner和设计稿一致"就关闭了Bug时，空着的"语音"列会让你无法心安理得地放手。

改CSS之前，先挂三个监听器

这个Bug活在焦点顺序和Live Region的变更里，所以作者没有先打开布局工具，而是在 focusin、助手节点变更、数据块到达这三个事件上各挂了一个微型日志器，先搞清楚"到底谁先触发"。

<div id="log" role="region" aria-label="Debug log" tabindex="0"></div>
<script>
  const log = document.querySelector("#log");
  const note = (line) => {
    const item = document.createElement("p");
    item.textContent = new Date().toISOString() + " " + line;
    log.appendChild(item);
  };
  document.addEventListener("focusin", (event) => {
    note("focusin " + (event.target.id || event.target.tagName));
  });
  const bubble = document.querySelector("#assistant");
  new MutationObserver(() => note("assistant mutated")).observe(bubble, {
    childList: true, characterData: true, subtree: true
  });
</script>

作者还用一个本地定时器伪造数据块，把网络和组件解耦，确保同样的状态转换能在笔记本上重复触发。关键原则是：如果你的伪造读取器无法触发取消、错误和完成这三种状态，它就只是个动画玩具，而不是测试工具。

async function fakeChunks(text, push, signal) {
  const parts = text.match(/\S+\s*|\s+/g) ?? [];
  for (const part of parts) {
    if (signal.aborted) return;
    await new Promise((resolve) => setTimeout(resolve, 40));
    push(part);
  }
}

MutationObserver 是浏览器原生提供的DOM变更监听API，可以异步观察目标节点的子节点变化（childList）、属性变化（attributes）或文本内容变化（characterData），并支持通过 subtree: true 递归监听后代节点。与早期的 DOMSubtreeModified 事件不同，MutationObserver 采用批处理机制，将一个事件循环内的所有变更合并为一次回调，避免了高频DOM操作导致的性能问题。在无障碍调试中，它扮演了"变更放大镜"的角色：屏幕阅读器内部也使用类似机制来侦测 Live Region 的更新，因此MutationObserver的触发频率可以粗略反映屏幕阅读器所感知到的"打断频率"。将其与 focusin 事件日志并排观察，就能清晰还原键盘用户在某次交互中实际经历的焦点漂移路径。

根因：把"播报"绑定在了"渲染"上

剥开各种表象后，根因有两条：播报策略直接绑定了渲染动作，以及控件在Markdown围栏闭合之前就被创建。

一个 assertive 区域同时扮演了对话记录、状态行和错误通道三种角色，于是每个角色都在打断其他角色。更糟的是，每个数据块都替换消息节点，元素身份一变，焦点就被甩向了日志区。而Send按钮只要文本框非空就被启用——哪怕回复还在传输中。

作者特别点明一个常见误区：仅仅把 assertive 换成一个"礼貌的"状态区域，并不能拯救这个Demo。如果你仍然把每个Token都灌进那个状态节点，你依然在重启语音，只是换了个更礼貌的打断方式而已。问题不在于用了什么role，而在于你在播报"渲染"本身。

正确的拆解方向是：把给视觉用户看的渲染，和给语音排队的措辞彻底分开；在容器结构完整、可命名之前，推迟任何新按钮的创建；当阶段进入取消或失败时清空待播语音；忽略"代次ID"不匹配的数据块，防止陈旧的Socket重写气泡。

焦点管理（Focus Management）在单页应用和动态界面中是一个常被忽视的无障碍维度。键盘用户和屏幕阅读器用户完全依赖焦点来感知当前操作位置——当DOM发生结构性变更（如新节点替换旧节点、模态框出现、列表项动态插入）时，浏览器并不会自动将焦点移到合理的位置，这个责任落在开发者手上。流式输出的特殊危险在于：每个Token到达时气泡节点可能被整体替换（而非追加），导致持有焦点的元素从DOM中消失，焦点回退到 <body> 或文档根节点，用户需要重新定向。更隐蔽的是"幽灵焦点"问题：焦点看似还在输入框，但被中途挂载的新控件（如代码块的复制按钮）在Tab序列中插了队，用户下一次按Tab时会落到一个意料之外的位置。这正是文章中描述的"按下回车落空"的底层机制。

渲染要急，播报要静

解决方案的核心思路一句话概括：渲染保持急切，播报保持安静。

视觉用户可以继续享受即时的Token渲染，因为移动的光标本身就是进度提示。而辅助技术需要的是合并后的短语或阶段更新，而不是每个音节都重启一次。作者的做法是把对话记录区设为 aria-live="off"，把阶段文案放进一个已经存在于Tab顺序中的 polite 状态区。错误则只在阶段真正变为error时，才用单次 assertive 播报。

function createBuffer(announce, delay = 700) {
  let timer = 0;
  let pending = "";
  return {
    push(chunk) {
      pending += chunk;
      window.clearTimeout(timer);
      timer = window.setTimeout(() => {
        const phrase = pending.trim();
        pending = "";
        if (phrase) announce(phrase);
      }, delay);
    },
    flush() {
      window.clearTimeout(timer);
      const phrase = pending.trim();
      pending = "";
      if (phrase) announce(phrase);
    },
    clear() {
      window.clearTimeout(timer);
      pending = "";
    }
  };
}

这个700毫秒的合并缓冲区会在阶段进入waiting时播报"正在生成回复"，在streaming期间播报合并后的短语，done时冲刷一次并播报"回复完成"，cancel时则先清空缓冲区再写"回复已停止"，确保延迟的定时器不会盖过停止提示。

复制按钮也必须等到围栏闭合后才挂载——因为过早出现的按钮是一个没有稳定可访问名称的Tab停靠点。这对想立刻复制半成品的鼠标用户来说确实慢了一点，但作者认为这个延迟是有意为之，直到控件能对所有用户诚实地命名为止。

贴在文件旁的阶段表

作者还维护了一张状态机表格，清晰定义了每个阶段下各控件的行为：

阶段	Send	Stop	状态文本	记录区live	缓冲区
idle	启用	禁用	Idle	off	空
waiting	禁用	启用	正在生成回复	off	空
streaming	禁用	启用	正在生成回复	off	合并中
cancelled	启用	禁用	回复已停止	off	已清空
error	启用	禁用	回复失败，请稍后重试	off	已清空
done	启用	禁用	回复完成	off	冲刷一次

焦点管理也有讲究：用户主动点Stop时焦点留在Stop上；只有在用户没有移动过焦点时，才自动归还给文本框。作者通过一个 userMovedFocus 标志位来避免"贴心的焦点移动"变成键盘陷阱。

文章中700毫秒的防抖延迟并非随意选取的魔法数字，其背后有语音交互的认知依据。人类对自然语音的感知需要一定的语义完整性——单个音节或孤立词语被打断后，大脑重新建立上下文需要额外的认知负荷。研究无障碍可用性的学者通常将500-800毫秒视为"可感知的自然停顿窗口"：短于这个范围，用户会感觉语音被截断；长于这个范围，则会产生明显的等待感，尤其在高信息密度的技术内容中。700毫秒的选择在两者之间取得平衡，同时也兼顾了"用户在流式输出中途按Stop"的场景——clear() 方法能确保尚未播报的缓冲内容被立即丢弃，而不是在停止指令之后姗姗来迟地朗读出来。实际部署时，这个延迟值可以根据目标用户群体和内容类型做适当调整，例如代码输出场景可适当延长，短文本对话场景可适当缩短。

什么时候不该用这个缓冲区

作者难得地给出了方案的适用边界，这比方案本身更能体现专业度：

• 当每个片段都必须逐字播报时，700毫秒的合并会隐藏Token级语音，此时应跳过缓冲。
• assertive 错误仍需要独立时机，否则礼貌的延迟会把它埋在已排队的短语后面。
• 这个缓冲区修不了缺失的label、非控件上的正数tabindex，也修不了从不管理焦点的对话框。
• 如果你需要正式的无障碍合规声明，应把这个文件当作回归测试辅助，而非声明本身。

至于远程流，作者坦承本文是某产品（MonkeyCode）推广的一部分，但始终坚持先跑本地伪造读取器——因为抖动的Socket会掩盖你本可以用定时器稳定复现的播报Bug。一个关于验证的务实提醒是：不要附上借来的通过率、浏览器版本或辅助技术版本，这些数据应属于你自己的运行环境。如果某个转换失败，记录下浏览器、操作系统、辅助技术版本和确切的阶段变化——这比再截一张永远解释不了语音问题的Spinner截图有用得多。

结语

这篇文章的价值不在于那段缓冲区代码，而在于它揭示了一个被普遍忽视的工程直觉错误：我们太容易因为"加了一个role"就认为交互完成了。 流式AI对话界面正在成为标配，但大多数实现只优化了视觉上的"忙碌感"，却让屏幕阅读器用户陷入永无止境的打断。

忙碌的语音不等于可理解的回复。让渲染保持急切，让播报保持安静，再用一张阶段表告诉你——回复到底是不是真的结束了。