跳到主要内容
Ed. notes

可访问性与测试:让流式界面可用可验证

长文 · 2026-11-12 · 合集第 9 / 10 篇

  • 可访问性
  • 测试
  • Vitest
  • Playwright
第 9 / 10 篇 · 查看全部章节 → 当前:可访问性与测试:让流式界面可用可验证

结论

可访问性不是最后跑一次 axe 就能补齐的。对话框的语义、打开后的焦点、生成中的状态播报、错误和重试,都要在组件结构里写清楚。

测试按依赖分层:解析器测纯函数,状态机测假流,浮窗测焦点与滚动,代理测转发和取消,最后用浏览器测试键盘路径和 axe。除了 live 环境,不需要真实模型。

问题与设计

聊天界面有三个容易被忽略的可访问性风险:

  1. 焦点丢失。 浮窗打开后,键盘焦点还停在背景按钮上;关闭后,焦点掉到页面顶部。
  2. 状态不可感知。 视觉用户能看到“正在生成”,读屏用户只听到一片安静。
  3. 错误只看得见。 错误文字出现却没有播报,或者只给颜色不加语义。

对应的结构:

  • 浮窗按钮:aria-haspopup="dialog"、aria-expanded、aria-controls。
  • 对话框:role="dialog"、aria-modal="true"、aria-labelledby、tabindex="-1"。
  • 打开:焦点进入输入框;关闭:Escape 关闭并把焦点还给触发按钮。
  • 消息区:role="log" + aria-live="polite",新消息和文本变化会被读屏感知。
  • 生成中:role="status" 的“正在生成回答…”;错误:role="alert"。
  • 来源:普通链接列表,aria-label="参考来源",不把整块做成按钮。

消息区使用 aria-atomic="false",避免每次 token 更新都重读整段对话;aria-relevant="additions text" 让新增消息和文本变化进入播报范围。

<div
  role="log"
  aria-live="polite"
  aria-relevant="additions text"
  aria-atomic="false"
  :aria-label="messages.length ? '对话消息' : '对话尚未开始'"
>

输入框必须有可访问名称。这里的 label 是视觉隐藏还是显示都可以,但不能只靠 placeholder:

<label :for="inputId">向 AI 助手提问</label>
<textarea
  :id="inputId"
  v-model="draft"
  maxlength="500"
  :disabled="busy"
  @keydown.enter.exact.prevent="submit"
/>

焦点环使用设计 token,不覆盖浏览器默认行为:

.input:focus-visible {
  @include mixins.focus-ring;
}

focus-visible 而不是 focus,避免鼠标点击输入框时也出现一圈明显的键盘焦点环;键盘用户仍然能看到当前位置。

关键代码

状态机的测试用一个手工 ReadableStream 代替后端:

function eventStream(events: string[]) {
  const encoder = new TextEncoder()
  return new ReadableStream<Uint8Array>({
    start(controller) {
      for (const event of events) controller.enqueue(encoder.encode(event))
      controller.close()
    },
  })
}

vi.stubGlobal(
  'fetch',
  vi
    .fn()
    .mockResolvedValue(
      new Response(
        eventStream([
          'event: sources\ndata: {"sources":[{"n":1,"title":"笔记","url":"/notes/a","slug":"a","score":0.8}]}\n\n',
          'event: token\ndata: {"text":"你好"}\n\n',
          'event: done\ndata: {"finishReason":"stop"}\n\n',
        ]),
        { status: 200 },
      ),
    ),
)

这样可以断言“来源到达后消息里出现引用”“token 到达后文本增长”“done 后状态完成”,而不用启动 Postgres 或模型服务。

浮窗测试关注 DOM 行为:

await launcher.trigger('click')
const dialog = document.body.querySelector('[role="dialog"]')
expect(dialog?.getAttribute('aria-modal')).toBe('true')
expect(document.activeElement).toBe(dialog?.querySelector('textarea'))

dialog?.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
await new Promise((resolve) => setTimeout(resolve, 0))
expect(document.activeElement).toBe(launcher.element)

代理测试用 h3 + listten 起一个临时服务,注入假的 fetchImpl,验证 404、流式转发、客户端断开和上游错误不泄漏。这一层不需要 Nuxt 页面,也不需要真实后端。

浏览器层只保留无法在 jsdom 里可靠模拟的部分:

cd frontend
npx playwright test e2e/site.spec.ts e2e/a11y.spec.ts

a11y.spec.ts 在亮暗两套主题下检查 /、/notes、/notes/magpie、/notes/build-log-00-overview、/notes/build-practice-05-deployment-docker、/series、/about、/chat,并单独检查浮窗打开时的状态。它过滤 serious 和 critical 级别的 axe 违规;这不是“全部通过”,而是“没有已知的严重结构问题”。

验证

建议按这个顺序跑:

cd frontend
npm run test -- tests/nuxt/chat-stream.spec.ts tests/nuxt/chat.spec.ts
npm run test -- tests/nuxt/chat-launcher.spec.ts tests/nuxt/assistant-proxy.spec.ts
npx playwright test e2e/site.spec.ts e2e/a11y.spec.ts

每一层回答不同问题:

层 证明什么 不能证明什么
解析器 任意分块、CRLF、坏 JSON、取消释放 reader 页面是否真的更新
状态机 token 追加、终态、历史裁剪、错误恢复 焦点和读屏是否正确
组件 对话框语义、焦点进入与返回、滚动锁定 真实浏览器布局和移动端软键盘
代理 fail-closed、流式转发、断开取消、错误不泄漏 鉴权、配额和限流
浏览器 键盘路径、响应式、axe 严重违规 所有读屏组合和真实网络抖动

边界

  • role="log" 上的流式 token 仍可能让读屏频繁播报。当前优先保证“有反馈”,没有做句子级节流;更稳妥的方案是只播报状态和完成消息,把中间 token 视为装饰,但这需要真实读屏测试后再定。
  • 错误同时出现在消息级和会话级提示里,读屏可能重复播报;发布前应合并成单一 alert,或者给其中一处加 aria-hidden。
  • axe 只能发现结构性问题,不能证明阅读顺序、语气和错误恢复对真实用户友好。
  • 浮窗没有给背景加 inert,焦点陷阱也只覆盖 Tab;完整的模态可访问性还需要焦点哨兵和读屏验证。
  • 输入法组词时的 Enter、自动滚动和移动端软键盘仍是已知边界,测试里没有覆盖。

下一篇把本地链路跑通,并把“已实现”和“可以公开”分开列清楚。