无障碍组件库介绍

# 无障碍组件库介绍 - TetraLogical 来源：https://tetralogical.com/blog/2026/10/14/accessible-components-library/ 发布于2026年10月14日，星期三，作者：Craig Abbott (https://tetralogical.com/about/team/cabbott)，分类：设计与开发 (https://tetralogical.com/blog/category/design-and-development/)、测试 (https://tetralogical.com/blog/category/testing/) 标签：代码 (https://tetralogical.com/blog/tag/code/)、WCAG (https://tetralogical.com/blog/tag/wcag/) 我们已将无障碍组件库 (https://tetralogical.com/resources/accessible-components-library/) 开源，如你所料，其中包括 HTML、CSS 和 JavaScript 代码。不过，我们想：“为什么止步于此？”于是，我们还发布了文档，包括无障碍要求、测试场景，甚至包括用于验证每项要求的可运行自动化测试。 下面介绍我们发布了哪些内容、它们如何运作，以及为什么自动化测试值得投入精力。需要提醒的是：这些组件有其特定的设计取向，并且是为满足我们自身的需求而构建的。欢迎复用或调整，但请先在你的产品中进行测试，再决定是否采用。它们并不是可以直接用于生产环境的设计系统。 ## 我们发布了哪些内容 为了向无障碍社区提供实用资源 (https://tetralogical.com/resources)，我们发布了 1\.0\.0 版本，其中包含八个组件。未来我们还会发布更多组件，目前你可以查看： - 手风琴 (https://tetralogical.com/resources/accessible-components-library/accordion) - 面包屑导航 (https://tetralogical.com/resources/accessible-components-library/breadcrumbs) - 对话框 (https://tetralogical.com/resources/accessible-components-library/dialog) - 展开与收起 (https://tetralogical.com/resources/accessible-components-library/disclosure) - 分页 (https://tetralogical.com/resources/accessible-components-library/pagination) - 选项卡 (https://tetralogical.com/resources/accessible-components-library/tabs) - 文本输入框 (https://tetralogical.com/resources/accessible-components-library/text-input) - 多行文本框 (https://tetralogical.com/resources/accessible-components-library/textarea) 每个组件都附带可运行的示例、实现它的 HTML、CSS 和 JavaScript 代码，以及说明以下内容的文档： - 它解决什么问题 - 何时使用 - 何时不使用 - 在哪里使用 - 无障碍要求- 测试场景 - 辅助技术兼容性 我们认为，无障碍要求是我们的工作区别于其他组件库的部分。对于每个组件，我们都记录了《Web 内容无障碍指南（WCAG）2\.2》 (https://www.w3.org/TR/WCAG22/) 中适用的 A、AA 和 AAA 级成功准则。对于 WCAG 未涵盖的内容，例如使用高对比度主题时的易用性，我们也加入了自己的建议。 由于 WCAG 的内容可能不容易查阅，我们将要求分为十个主题，包括： - 适应性 - 动画与运动 - 辅助技术与语义 - 颜色与对比度 - 一致性与可预测性 - 图像与媒体 - 输入辅助 - 键盘 - 导航 - 指针与触摸 这应该能让你更容易快速理解组件如何满足使用者的需求。 由于总会涉及一些技术术语和注意事项，我们还发布了： - 术语表 (https://tetralogical.com/resources/accessible-components-library/glossary/)，供你在遇到难以理解的术语时查阅 - 辅助技术兼容性说明 (https://tetralogical.com/resources/accessible-components-library/compatibility/)，记录了我们遇到的一些浏览器和工具的特殊行为 ## 将要求转化为自动化测试 记录要求很有用，但文档无法告诉你组件是否真正满足了所有要求。因此，我们使用 Gherkin (https://cucumber.io/docs/gherkin/reference/) 语法，将每项要求转化为测试场景，并编写了可运行的 Cucumber (https://cucumber.io/) 测试来验证它们。 Gherkin 的优点在于，它使用通俗语言描述复杂的自动化测试，通过 `Given`、`When` 和 `Then` 描述每个步骤。这让非开发人员也更容易理解测试在做什么，甚至能参与编写测试。我们之前介绍过 Gherkin，以及它为什么有助于使用通用语言标注设计 (https://tetralogical.com/blog/2025/09/23/annotating-designs-using-common-language/)。 我们的每个 Gherkin 场景都包含以下内容： - **标签**：用于运行部分测试。例如，你可能只想运行 A 级和 AA 级测试，而忽略所有建议项 - **规则**：相关的 WCAG 成功准则，或注明它是否属于建议项 - **场景**：描述测试要检查什么 - **测试步骤**：使用 `Given`、`When` 和 `Then` 步骤准确描述如何进行测试 例如，下面是面包屑导航 (https://tetralogical.com/resources/accessible-components-library/breadcrumbs) 组件针对 1\.4\.10 重排的测试场景： `` @1.4.10 @aa @automatic 规则: 1.4.10 重排，AA 级 场景: 在宽度为 320px 时，内容重排且无需水平滚动 假如 我加载示例 "https://tetralogical.com/resources/accessible-components-library/breadcrumbs/examples/default.html" 当 我查看已渲染的 '.tl-breadcrumbs' 并且 我将视口宽度设置为 320px 那么 它应当重排且无需水平滚动 `` 这很重要，因为你无需读懂所有复杂的 JavaScript 代码，就能理解测试在做什么。设计师、测试人员、产品经理和开发人员都可以阅读同一个场景，并对通过或失败的含义达成共识。而且，即使你的项目不使用 JavaScript，由于 Cucumber 支持大多数主流编程语言，你仍然可以使用这些 Gherkin 功能文件，并自行编写测试来验证它们。 我们所有的测试场景都由一组共享步骤编写而成，这在最初需要投入大量工作，因为我们必须编写底层代码来验证每个步骤。不过，每个步骤都可以复用，因此很容易扩展。 我们发布了开箱即用的完整测试步骤列表 (https://tetralogical.com/resources/accessible-components-library/test-steps/)。这个列表根据代码仓库中实际使用的步骤定义生成，因此会自动保持同步。这意味着，每当我们添加新步骤，你也可以免费使用。 ## 自动化测试检查什么 每个测试步骤背后都有 JavaScript 代码，通过 Playwright (https://playwright.dev/) 控制真实的浏览器。测试从 URL 加载示例，然后以真实用户的方式与其交互，例如点击元素，或使用键盘将焦点移到元素上。接着，测试从浏览器获取信息，例如元素的状态和属性，并验证预期发生的事情是否确实发生。 这正是我们的测试远远超出现成无障碍检查工具的地方。这些工具中有很多很有价值，我们也确实建议使用，但它们大多检查静态标记。它们通常会告诉你按钮缺少无障碍名称之类的问题，却往往无法告诉你更复杂的情况，例如焦点指示器是否被其他元素遮挡。 ## 无法自动化的内容 我们的*大多数*测试都是自动化的，为此有时需要发挥一些创造力。不过，并非所有内容都能可靠地实现自动化，而对于任何声称能够做到这一点的工具，我们都会有所怀疑。例如，自动化测试很容易确认表单字段是否有关联标签。然而，要判断标签对于阅读它的人来说是否真的有意义，就困难得多，因为这取决于上下文。或许，我们可以获取截图和代码片段，然后一股脑交给大语言模型，评估内容是否易读。不过，我们认为，让人来审核某些内容完全合理，因为这些内容是*为人*而设计的。 在 1\.0\.0 版本中，我们 97% 的场景已实现完全自动化。对于剩余的 3%，我们没有直接跳过，而是添加了相应功能，从浏览器中收集审核人员需要的信息，并生成需要手动检查的项目清单。每次测试运行都会生成一份 JSON 报告，记录自动化测试中通过和失败的项目，同时生成一份 Markdown 检查清单，列出仍需人工验证的内容。 最后，每个组件的所有辅助技术测试都是手动进行的。即使组件通过了全部自动化和手动测试，并且在技术上符合要求，也不能保证它在特定屏幕阅读器或浏览器中不会出现异常。因此，我们会手动检查每个组件，如果发现问题，就加以修复。 ## 为什么自动化测试很重要 在与大型组织开展战略工作 (https://tetralogical.com/blog/2026/09/14/sustainable-accessibility-compliance-capability-culture/) 时，我们经常发现，它们难以持续做好无障碍 (https://tetralogical.com/blog/2021/01/07/sustainable-accessibility/)。组织付费进行评估，然后修复问题，这种情况很常见。但在发布几个版本之后，各种问题又悄然出现，直到客户投诉，或者组织再次付费进行无障碍评估时才被发现，而这可能花费不菲。 自动化测试可以打破这个循环。你可以将它们接入持续集成（CI）流水线，针对每个拉取请求运行测试，从而在出现问题时迅速发现。 以下是我们认为自动化测试如此有价值的原因： - **即时反馈**：开发人员可以在自己的设备上用大约 30 秒运行所有测试，立即知道自己是否破坏了某项功能 - **防止回归**：每个拉取请求都会在 CI 中运行所有测试，因此代码审核人员可以快速检查是否出现回归问题 - **共同语言**：场景使用通俗英语编写，让无障碍要求不再只是技术性描述，而是成为整个团队都能读懂的验收标准 - **可追溯性**：每个场景都标记了成功准则和符合性级别，因此可以轻松运行部分测试，或搜索查看已覆盖哪些内容 - **编码规范**：内置了代码检查规则和 CI 检查，因此无论代码由谁编写，都应保持大家熟悉的风格 - **有更多时间关注易用性**：由于机械性检查已实现自动化，人们可以把更多时间用于真实场景测试，而不用一遍又一遍地检查文档对象模型（DOM），确认按钮是否有标签 ## 如何维护组件库 我们已将无障碍组件库 (https://tetralogical.com/resources/accessible-components-library/) 发布到 GitHub 上的独立仓库，并放在我们网站的资源 (https://tetralogical.com/resources) 栏目中。 不过，巧妙之处在于，我们的网站直接从 GitHub 获取所有文档和测试，因此只有一个权威来源。两者不会出现内容偏离或不同步的情况。所以，如果我们想在网站上添加新组件，就必须先将其发布到仓库中。这意味着你也能获得该组件，以及与之配套的所有测试和文档。 未来几个月，我们还会发布更多组件。目前我们先发布了一小组，以便收集反馈并解决初期问题。因此，记得为仓库点亮星标，以便在更新发布时及时获知。 ## 亲自试试 我们以 ISC 许可证 (https://github.com/TetraLogical/accessible-components-library/blob/main/LICENSE) 发布了组件库，因此，只要不删除版权声明，你就可以自由使用、复制、修改或分享其中的任何代码和文档。 如果你想运行测试，仓库中的 README (https://github.com/TetraLogical/accessible-components-library/tree/main) 说明了如何安装和运行测试。 如果你想创建分支副本并自行扩展，开发指南 (https://github.com/TetraLogical/accessible-components-library/blob/main/DEVELOPMENT.md) 介绍了仓库的组织方式，以及如何添加自己的组件和测试。 如果你发现缺陷，或者有想法和意见，请在 GitHub 上提交议题 (https://github.com/TetraLogical/accessible-components-library/issues)。 我们目前不接受拉取请求，因为每个组件都需要一套完整的要求、测试和辅助技术检查，而我们需要确保它们与代码保持同步。此外，由于这些组件也用于我们自己的工作，至少目前，我们会保留自己的设计取向，并在内部进行维护。 ## 致谢 这项工作量很大，想必并不令人意外。虽然这篇博文以及 1\.0\.0 版本的部署提交上署的是我的名字，但这个项目凝聚了多位 TetraLogical 现任和前任同事的热忱与心血，包括： - Alistair Duggin (https://tetralogical.com/blog/2023/07/05/meet-the-team-alistair-duggin/) - Demelza Feltham (https://tetralogical.com/about/team/dfeltham/) - Ela Gorla (https://tetralogical.com/about/team/egorla/) - Grace Snow (https://tetralogical.com/about/team/gsnow/) - Henny Swan (https://tetralogical.com/about/team/hswan/) - Ian Pouncey (https://tetralogical.com/about/team/ipouncey/) ## 后续步骤 浏览无障碍组件库 (https://tetralogical.com/resources/accessible-components-library/)，或了解我们的咨询 (https://tetralogical.com/services/consultancy/) 和培训 (https://tetralogical.com/services/training/) 服务如何帮助你的团队将无障碍测试融入工作方式。