网页无障碍辅助小部件

A11y 是一个轻量、独立、可无缝集成到任何网页的无障碍工具栏。它通过浮动按钮提供 20 余项辅助功能，覆盖视觉、运动、认知与听觉障碍，帮助您快速提升网站的可访问性，并满足 WCAG 2.1 合规要求。

🚀 快速开始

方式一：Script 标签

在 HTML 中引入脚本，小部件即自动初始化，无需额外 JavaScript 代码：

<script src="/path/to/c-a11y.min.js" defer></script>

方式二：NPM

npm install @william-xu-web/c-a11y

import { init } from "@william-xu-web/c-a11y";

const widget = init({
  lang: "zh",
  position: "bottom-left",
});

// 需要时销毁小部件并清理所有事件监听
widget.destroy();

✨ 功能全景

所有功能均按需启用，用户可随时开关，偏好设置自动保存至本地。

👁️ 视觉与显示辅助

功能	WCAG 参考	适用人群
字体缩放（放大/缩小/重置）	1.4.4	低视力、老年人
高对比度模式（深色/浅色/反色）	1.4.3	低视力
深色模式	1.4.3	光敏感人群
灰度显示	1.4.1	色盲
色彩饱和度滑块	1.4.1	色彩敏感者
文字间距调整	1.4.12	阅读障碍、低视力
阅读障碍专用字体（OpenDyslexic）	最佳实践	阅读障碍
隐藏图片	最佳实践	认知障碍
色盲模拟滤镜	1.4.1	开发者测试、无障碍意识教育

🧭 导航与阅读辅助

功能	WCAG 参考	适用人群
全键盘导航支持	2.1.1	运动障碍
焦点指示器增强	2.4.7	运动障碍、低视力
标题地图 / 页面目录	2.4.10	屏幕阅读器用户
ARIA 地标结构展示	2.4.1	屏幕阅读器用户
阅读辅助标尺（遮光引导线）	最佳实践	阅读障碍、多动症
行聚焦 / 内容遮罩	最佳实践	多动症、认知障碍
大光标模式	最佳实践	运动障碍、低视力
屏幕阅读器预览	1.1.1, 1.3.1	开发者、测试人员

🔊 媒体与内容辅助

功能	WCAG 参考	适用人群
悬停朗读（TTS）	最佳实践	视障、低视力
选中朗读（TTS）	最佳实践	视障、低视力
整页朗读（TTS）	最佳实践	视障、低视力
链接高亮显示	1.4.1, 2.4.4	低视力、认知障碍
图片替代文本覆盖显示	1.1.1	视障、低视力
停止所有动画	2.3.1, 2.3.3	癫痫、前庭障碍
静音所有声音	1.4.2	听障、认知障碍

⚙️ 配置参数

您可以通过全局对象 window.OpenA11yConfig 在脚本加载前进行配置。

<script>
  window.OpenA11yConfig = {
    position: "bottom-left", // 按钮位置
    lang: "zh", // 界面语言
    bottomOffset: 20, // 桌面端向上偏移（px）
    mobileBottomOffset: 60, // 移动端向上偏移（px）
    statementUrl: "/accessibility-statement", // 外部无障碍声明链接
    statementData: {
      // 内置声明生成器数据
      orgName: "我的公司",
      orgPhone: "13088888888",
      orgEmail: "access@example.com",
      coordinatorName: "张三",
      lastAuditDate: "2026-01-15",
    },
  };
</script>
<script src="/path/to/c-a11y.min.js" defer></script>

配置项说明

参数	类型	默认值	说明
position	string	'bottom-left'	可选：bottom-left、bottom-right、top-left、top-right
lang	string	自动检测	界面语言：'zh' 或 'en'
bottomOffset	number	0	桌面端（屏幕 > 768px）按钮额外向上偏移，仅对底部位置生效
mobileBottomOffset	number	0	移动端（屏幕 ≤ 768px）额外向上偏移，适用于底部固定导航栏的页面
statementUrl	string	—	若您已有无障碍声明页面，可在此填写完整 URL
statementData	object	—	若需内置声明生成器，提供机构信息即可自动生成声明

🌐 多语言支持

小部件界面内置 中文（zh） 和 英语（en） 两种语言，用户可随时在工具栏中切换。

📜 合规性说明

本小部件不仅覆盖 WCAG 2.1 的常用标准，还额外支持以下成功准则：

• 1.4.10 回流（Reflow）
• 1.4.12 文字间距（Text Spacing）
• 1.4.13 悬停或焦点时的内容（Content on Hover or Focus）
• 2.3.3 交互动画（Animation from Interactions）
• 4.1.3 状态消息（Status Messages）

🧱 项目架构

目录结构

src/
  c-a11y.js            # 主入口
  styles.js            # 所有 CSS（注入 Shadow DOM）
  i18n.js              # 中/英翻译
  storage.js           # localStorage 持久化
  utils.js             # 共用工具函数
  modules/             # 每个功能独立模块（共 24 个）
dist/
  c-a11y.min.js        # 压缩版 IIFE（约 89 KB）
  c-a11y.esm.js        # ES Module 版本（供打包工具使用）
demo.html              # 功能演示页面

设计特点

• Shadow DOM — 样式隔离，完全避免与宿主页面 CSS 冲突。
• 零依赖 — 纯原生 JavaScript，无需加载任何第三方库。
• 模块化 — 每个功能提供 enable() / disable() / toggle() 方法，便于扩展。
• 状态持久化 — 用户偏好自动保存至 localStorage，跨会话保留。
• ARIA 实时区域 — 为屏幕阅读器提供状态通知（WCAG 4.1.3）。

🌍 浏览器支持

浏览器	最低版本
Chrome	80+
Firefox	78+
Safari	14+
Edge	80+

🔗 相关链接

• WCAG 2.1 规范（英文原版）
• Web 无障碍倡议（WAI）