Astryx useAnnounce指南让屏幕阅读器听到动态状态变化【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryxAstryx 是一个完全可定制、面向 Agent 的开源设计系统它的 useAnnounce 钩子可以一行代码为屏幕阅读器播报动态状态变化——搜索结果数量、已保存提示、表单错误都能被无障碍用户听到。本文将从新手视角讲清楚它解决什么问题、如何工作以及 Astryx 组件内部如何用它。为什么需要 useAnnounce屏幕阅读器的盲区如果你的组件里有一个保存成功的绿色提示、一个0 个结果的空状态键盘和屏幕阅读器用户是听不见的——这些状态只存在于视觉上。WCAG 4.1.3 要求状态消息必须能被非视觉方式感知。而新手最常见的错误是手写一个aria-livediv 渲染提示文本。问题在于大多数屏幕阅读器会忽略和它的内容一起被插入的 live region业内称之为 born with content。提示一闪而过读屏器却什么都没说。useAnnounce的价值正是解决这个问题而不是让你重复造轮子。useAnnounce 如何工作常驻的播报频道useAnnounce返回一个announce(message, politeness?)函数背后的机制很巧妙单例常驻首次调用时它会在页面中创建一对视觉上隐藏的 live regionpolite与assertive并一直挂载在文档里。区域先空着、之后才改写文本读屏器就一定会播报。两种礼貌度polite默认等读屏器空闲时再读适合状态更新、结果计数、无结果等非紧急提示assertive立即打断当前朗读仅留给错误和时效性强的警报。自动清理每条消息播报约 2 秒后自动清空避免过期状态文本残留在可访问性树里再次播报会重置倒计时。相同消息也能重复播报内部会先清空再写入绕过读屏器对相同内容的去重。核心实现只有 200 多行可以直接阅读 useAnnounce.ts 与它的官方文档描述 useAnnounce.doc.mjs。快速上手让搜索结果被听到从astryxdesign/core/hooks导入即可导出入口见 hooks/index.tsimport {useAnnounce} from astryxdesign/core/hooks; function Search() { const announce useAnnounce(); const handleResults (n: number) { announce(n 0 ? 未找到结果 : ${n} 个结果); }; // ... }三个使用要点播报结果而不是交互过程——说12 个结果而不是搜索完成传空字符串等于清空announce()会移除残留状态适合在搜索条件被清除时调用不要播报页面上已经可见且标签正确的内容否则读屏用户会听到两遍。内置集成Astryx 组件已经替你接好了在 Astryx 中useAnnounce不是孤立的工具而是贯穿组件库的无障碍基础设施。这些真实代码可以直接参考CommandPalette.tsx加载时播报正在加载无结果时播报未找到 xxx关闭时announce()清理残留ToastViewport.tsx错误类 Toast 走assertive其余走politeFileInput.tsx、Calendar.tsx、FieldStatus.tsx 等表单与日期组件也用它在状态切换时同步播报。这意味着你直接消费组件时就天然获得无障碍体验自己封装组件时照抄这些用法即可。常见误区清单 误区正确做法手写aria-livediv 渲染一次性提示用useAnnounce区域常驻才可靠所有消息都用assertiveassertive会打断朗读只留给错误播报页面上已可见的文本只补视觉专属的动态状态忘记清理过期状态传announce()主动清空其单元测试 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 thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
