读屏状态消息播报实现与修复
检查应用中的状态消息播报问题,实现统一无障碍播报组件,并提供调用修改、测试与人工检查表。
完整提示词
<context>
WCAG 4.1.3 requires status messages to reach screen-reader users without moving focus. Live regions are the tool, and they fail silently in predictable ways. A region inserted into the DOM together with its text is often not announced: the container must exist, empty, before the text changes. `role="status"` (polite) suits confirmations, counts and progress; `role="alert"` (assertive) interrupts and should be kept for errors that need action now. Writing the same string twice is ignored by some screen readers, so repeated messages need clearing first or a changing suffix. Rapid updates (a counter while typing, a progress percentage) flood the queue and must be debounced or reduced to milestones. Regions inside a container with `aria-hidden`, `display: none` or a closed modal's inert background say nothing. Toasts that vanish after three seconds also fail people who need more time (2.2.1) unless the message is also available elsewhere. One app-level announcer, mounted once near the root, is more reliable than many regions scattered through components.
</context>
<task>
Make these status messages reach screen-reader users in this {{framework}} app.
<messages>
{{messages}}
</messages>
1. Search the codebase for existing live regions, `aria-live`, `role="status"`, `role="alert"` and toast or notification utilities. List them and note any that are created at the same moment as their text, nested in hidden containers, or duplicated.
2. Build the message inventory: each message, its trigger, its urgency (polite or assertive), and whether it can repeat or fire rapidly.
3. Implement or repair one announcer: a polite and an assertive region rendered once at app root, visually hidden with a standard clip pattern (not `display: none`), and a small API such as `announce(message, { politeness })` that clears and sets text after a short delay so repeats are spoken. Reuse an existing utility if the project has one.
4. Route each message through the announcer. Debounce counts that change while typing (announce after the user pauses), reduce progress to a few milestones, and keep `assertive` for errors.
5. For toasts, make sure the message text is announced, that toasts with actions do not disappear before a keyboard user can reach them, and that the timing can be extended or the content found elsewhere.
6. Write tests that trigger each message and assert the region's text content. Run them and report results.
7. Give a manual check list for at least NVDA with a browser and VoiceOver, since automated tests cannot prove the screen reader spoke.
</task>
<constraints>
- Do not move focus to announce a status message.
- Do not mark large containers (whole lists, chat logs, forms) as live; announce a short summary instead.
- Do not use `assertive` for routine confirmations.
- Keep messages short, specific and in the page language.
{{> guardrails/scope-discipline}}
{{> guardrails/verify-before-done}}
</constraints>
<output_format>
## Message inventory
Table: message | trigger | politeness | repeat or rapid | current problem.
## Announcer implementation
Code with file path.
## Changes at each call site
Diffs.
## Tests and manual check
Test code, command result, then a short manual checklist per screen reader.
</output_format>可替换内容
- {{framework}}
- {{messages}}
- {{> guardrails/scope-discipline}}
- {{> guardrails/verify-before-done}}
分类与标签
编程开发、前端无障碍、读屏播报、状态消息、组件修复、无障碍测试