可访问性与测试:让流式界面可用可验证
结论
可访问性不是最后跑一次 axe 就能补齐的。对话框的语义、打开后的焦点、生成中的状态播报、错误和重试,都要在组件结构里写清楚。
测试按依赖分层:解析器测纯函数,状态机测假流,浮窗测焦点与滚动,代理测转发和取消,最后用浏览器测试键盘路径和 axe。除了 live 环境,不需要真实模型。
问题与设计
聊天界面有三个容易被忽略的可访问性风险:
- 焦点丢失。 浮窗打开后,键盘焦点还停在背景按钮上;关闭后,焦点掉到页面顶部。
- 状态不可感知。 视觉用户能看到“正在生成”,读屏用户只听到一片安静。
- 错误只看得见。 错误文字出现却没有播报,或者只给颜色不加语义。
对应的结构:
- 浮窗按钮:
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、自动滚动和移动端软键盘仍是已知边界,测试里没有覆盖。
下一篇把本地链路跑通,并把“已实现”和“可以公开”分开列清楚。