README

关于Sa11y和Editoria11y的全面概述，它们如何通过支持内容编辑器来帮助维护无障碍网站，以及了解此插件背后的理由，请查看https://sebastiangreger.net/2021/11/sa11y-editoria11y-and-a-kirby-plugin上的深入博客文章或项目页面https://sebastiangreger.net/projects/a11yprompter

概述

A11yprompter（如无障碍性中的a11y和提示员，类似于帮助演员的舞台提示员）是一个小型的包装器，可以轻松地将用户友好的自动内容无障碍检查器添加到使用Kirby CMS构建的网站的前端。

该插件目前集成了Editoria11y和Sa11y，甚至允许随机尝试它们两者。它们专门开发出来帮助内容编辑在创建内容时不会破坏网站的无障碍性；不是完整的无障碍性验证器，而是引导编辑遵循a11y指南的工具。

此外，书签无障碍审计工具BAAT（更多面向专业审计员）或旧工具Tota11y可以配置为用于特定目的（不适用于日常生产使用中的非技术内容编辑）。

安装

下载并将此存储库复制到/site/plugins/kirby-a11yprompter

或者使用Composer

composer require sgkirby/a11yprompter

或者作为Git子模块安装

git submodule add https://codeberg.org/sebastiangreger/kirby-a11yprompter site/plugins/kirby-a11yprompter

设置

要开始，只需要一步。将以下内容添加到模板或片段中，该模板或片段渲染HTML body的结尾（例如，Kirby Starterkit中的site/snippets/footer.php），在关闭</body>标签之前

<?= snippet('a11yprompter') ?>

这将在页面上渲染所需的<script>和<style>标签以包含检查工具；默认情况下，两个工具之一会随机选择——可以将其视为一种“试用”模式（虽然两者非常相似，但它们具有不同的UI和功能集，这可能会很有用，以找到您最喜欢的解决方案）。

该工具仅在以登录用户加载网页时显示——如果Kirby内置的页面缓存正在使用，请小心；您可能希望禁用登录用户的页面缓存。

现在您应该已经准备好了——请确保您已登录到您的Kirby网站，并打开任何使用此代码渲染的模板/片段的前端页面。

配置

可以在片段调用中包含额外的配置变量以自定义设置。期望$data变量是一个关联数组，就像任何其他Kirby片段

<?= snippet('a11yprompter', $data) ?>

检查器引擎选择

要关闭随机的“试用”模式并永久选择一个引擎，请相应地设置engine值

值	描述
`'engine' => 'sa11y'`	使用Sa11y
`'engine' => 'editoria11y'`	使用Editoria11y
`'engine' => 'random'`或空（默认值）	随机在每次页面加载时加载Sa11y或Editoria11y，这有助于找到最合适的工具或比较结果
`引擎'engine' => 'baat'`	使用BAAT；由于它的目标受众更专业，并且这可能是为了开发期间的可访问性测试而临时使用，所以在使用`random`选项时，它永远不会显示。
`'engine' => 'tota11y'`	使用Tota11y；这是较新解决方案的“前辈”，自2019年以来未更新，仅在此处用于参考或非常具体的用例，使用`random`选项时永远不会显示，因为其目标受众与其他不同。

因此，要仅使用Sa11y，请设置

<?= snippet('a11yprompter', ['engine' => 'sa11y']) ?>

注意。这两个引擎名称都不包含L字母，而是数字字符1。

模板限制

默认情况下，检查工具会显示在包含此代码段的每个包含模板的页面上。要限制，您可以向代码段提供一个模板名称数组。

值	描述
`templates` => 数组	包含检查工具的模板ID数组，例如`'templates' => ['article']`

访问控制

默认情况下，检查工具会显示给每位登录用户。您可以通过在$data变量中设置以下数组之一来进一步限制。

值	描述
`'users' =>` 数组	将看到检查工具的用户ID数组，例如`'users' => ['ascd1234', 'b2cy82t5']`
`'roles' =>` 数组	将看到检查工具的用户角色数组，例如`'roles' => ['admin']`

例如，一个完整的设置，具有模板和访问限制可能如下所示

<?= snippet('a11yprompter', [
  'engine'    => 'sa11y',
  'templates' => ['article', 'note'],
  'roles'     => ['admin', 'leadeditor'],
]) ?>

脚本参数

要覆盖检查脚本的一些默认设置，请使用以工具名称命名的数组覆盖它们。

值	描述
`sa11y` => 数组	用于Sa11y工具的属性数组；请参阅https://sa11y.netlify.app/developers/props/
`editoria11y` => 数组	用于Editoria11y工具的参数数组；请参阅https://editoria11y.princeton.edu/configuration/#parameters

例如，要将Editoria11y变量alertMode从其默认值polite更改为assertive并排除所有标记为aria-hidden="true"的元素（这是一个黑客技巧！），请使用以下代码

<?= snippet('a11yprompter', [
  'engine'      => 'editoria11y',
  'editoria11y' => [
    // make sure to include quotation marks for variables that are strings
    'alertMode' => "'assertive'",
    'ignoreElements' => "'*[aria-hidden=\"true\"]'"    
  ],
]) ?>

或者，要覆盖Sa11y默认属性checkRoot（检查器检查的DOM范围）从其默认值body更改为main，请使用

<?= snippet('a11yprompter', [
  'engine' => 'sa11y',
  'sa11y'  => [
    'checkRoot' => 'main',
  ],
]) ?>

查看这两个脚本的各个配置变量 – 每个变量都允许大量（但不同）的自定义，从包括/排除某些区域到其他界面设置。

可能最重要的设置是将测试区域限制为特定的DOM元素（例如，仅针对作者可以编辑的区域，而不是页面的其余部分，通常由固定模板渲染）；默认为整个body。

Sa11y	Editoria11y
`'checkRoot' => '#content'`	`'checkRoots' => '#content'`（以逗号分隔多个）

致谢

此插件仅是嵌入到使用Kirby 3构建的网站中的Editoria11y和Sa11y工具的小助手。我的原始贡献仅限于通过模板中的Kirby代码段使它们可用。

Editoria11y 由 John Jameson 维护，得益于普林斯顿大学网络发展服务办公室的数字无障碍倡议，为社区提供支持。它最初是从加拿大多伦多瑞尔森大学数字媒体项目、计算与通信服务（CCS）创建的 Sa11y 分支而来，由 Adam Chaboryk 主导并维护，后来发展至第2版本。Sa11y 本身最初是 Khan Academy 的 Tota11y 的分支，并使用 FontAwesome 图标和 jQuery。由 Mindscreen GmbH 开发的 BAAT 运行的是 Deque Systems, Inc. 的 axe-core 测试引擎。

许可协议

Kirby A11yprompter 是开源软件，遵循 GPLv2 许可协议，以符合 Editoria11y 的原始 GPLv2 许可协议。Sa11y、Tota11y 和 BAAT 采用 MIT 许可协议，axe-core 则采用 Mozilla 公共许可证 2.0，两者都允许它们被包含在 GPLv2 许可协议的软件中。所包含的 BAAT 版本已被修改，以从本地加载 axe-core 验证器，而不是从 CDN 加载。

强烈建议不要在推广破坏我们星球、种族主义、性别歧视、恐同、虐待动物、暴力或其他任何形式的仇恨言论的项目中使用此插件。

sgkirby / a11yprompter

维护者

详细信息