企业官网建设流程全解析

Astryx useAnnounce指南：让屏幕阅读器"听"到动态状态变化

【免费下载链接】astryxAn open source design system that's fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx

Astryx 是一个完全可定制、面向 Agent 的开源设计系统，它的 useAnnounce 钩子可以一行代码为屏幕阅读器播报动态状态变化——搜索结果数量、"已保存"提示、表单错误，都能被无障碍用户"听"到。本文将从新手视角讲清楚它解决什么问题、如何工作，以及 Astryx 组件内部如何用它。

为什么需要 useAnnounce：屏幕阅读器的"盲区"

如果你的组件里有一个"保存成功"的绿色提示、一个"0 个结果"的空状态，键盘和屏幕阅读器用户是听不见的——这些状态只存在于视觉上。WCAG 4.1.3 要求状态消息必须能被非视觉方式感知。

而新手最常见的错误是手写一个aria-livediv 渲染提示文本。问题在于：大多数屏幕阅读器会忽略"和它的内容一起被插入"的 live region（业内称之为 "born with content"）。提示一闪而过，读屏器却什么都没说。

useAnnounce的价值正是解决这个问题，而不是让你重复造轮子。

useAnnounce 如何工作：常驻的"播报频道"

useAnnounce返回一个announce(message, politeness?)函数，背后的机制很巧妙：

• 单例常驻：首次调用时，它会在页面中创建一对视觉上隐藏的 live region（polite与assertive），并一直挂载在文档里。区域先空着、之后才改写文本，读屏器就一定会播报。
• 两种"礼貌度"：
  • polite（默认）：等读屏器空闲时再读，适合状态更新、结果计数、"无结果"等非紧急提示；
  • assertive：立即打断当前朗读，仅留给错误和时效性强的警报。
• 自动清理：每条消息播报约 2 秒后自动清空，避免过期状态文本残留在可访问性树里；再次播报会重置倒计时。
• 相同消息也能重复播报：内部会先清空再写入，绕过读屏器对相同内容的去重。

核心实现只有 200 多行，可以直接阅读 useAnnounce.ts 与它的官方文档描述 useAnnounce.doc.mjs。

快速上手：让搜索结果被"听到"

从@astryxdesign/core/hooks导入即可（导出入口见 hooks/index.ts）：

import {useAnnounce} from '@astryxdesign/core/hooks'; function Search() { const announce = useAnnounce(); const handleResults = (n: number) => { announce(n === 0 ? '未找到结果' : `${n} 个结果`); }; // ... }

三个使用要点：

1. 播报结果，而不是交互过程——说"12 个结果"，而不是"搜索完成"；
2. 传空字符串等于清空：announce('')会移除残留状态，适合在搜索条件被清除时调用；
3. 不要播报页面上已经可见且标签正确的内容，否则读屏用户会听到两遍。

内置集成：Astryx 组件已经替你接好了

在 Astryx 中，useAnnounce不是孤立的工具，而是贯穿组件库的"无障碍基础设施"。这些真实代码可以直接参考：

• CommandPalette.tsx：加载时播报"正在加载"，无结果时播报"未找到 xxx"，关闭时announce('')清理残留；
• ToastViewport.tsx：错误类 Toast 走assertive，其余走polite；
• FileInput.tsx、Calendar.tsx、FieldStatus.tsx 等表单与日期组件也用它在状态切换时同步播报。

这意味着你直接消费组件时就天然获得无障碍体验；自己封装组件时，照抄这些用法即可。

常见误区清单 📋

其单元测试 useAnnounce.test.tsx 覆盖了区域挂载、消息路由、重复播报与自动清理等场景，是理解行为的最佳"活文档"。

延伸阅读

• 钩子源码与类型定义：useAnnounce.ts
• 钩子统一导出：hooks/index.ts
• 分层运行时架构（含公告机制的位置）：docs/architecture/layer-runtime.md
• 无障碍规格说明：docs/specs/AST-003/spec.md

用useAnnounce给你的动态状态装上"声音"，Astryx 的无障碍体验就补齐了关键一环。🎧

【免费下载链接】astryxAn open source design system that's fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx