Editoria11y for Drupal

核心功能

Drupal 模块将检查器库与编辑后台对接，并增加了许多用于报告、治理与配置的服务器端工具。

Drupal 编辑器显示内联提示
问题会在前端页面加载时以及在 CKEditor 和 Gutenberg 中输入内容时实时检测。
提示指出某链接仅被命名为
工具提示新增按钮，可跳转至编辑器、忽略当前提示（仅对当前用户有效）或将其标记为无误（对所有用户有效）。对于重复出现的提示，还提供整页或全站范围的操作选项。
自定义测试构建器界面，显示提示标题与内容字段，以及元素选择器与排除项。

CSA 子模块新增：

  • 自定义测试构建器
  • 40 余项开发者测试
  • 对比度检查
  • 站点爬虫
  • 可读性分析
  • 开发者/编辑分离配置
报告仪表板，显示最近的问题及问题最多的页面。
全站仪表板提供可筛选、可导出的提示与忽略记录报告。

安装与关键配置步骤

Drupal.org 上的捆绑安装包包含以下几个模块：

  • Editoria11y：核心内容检查器与仪表板。
  • Editoria11y CSA：开发者测试与仪表板维护工具。
  • Editoria11y Export：CSV 报告工具。

像安装其他模块一样完成安装，然后执行以下关键步骤：

  1. 检查权限。受信任的作者应拥有"标记为无误"、"标记为已忽略"和"查看仪表板"权限。
  2. 检查关键页面，排查重复或无用的提示。可在工具提示中将其标记为无误，或通过调整配置按选择器忽略相关元素。
  3. 寻找难以看到的提示——例如超出屏幕、被截断、位于其他元素之后或处于隐藏元素中的提示。请参考下方"修复提示定位"中的建议进行修复。
  4. 如果站点已有内容，且您拥有 CSA 订阅，请访问仪表板的"重新检查"标签页，爬取整个站点以预先加载站点报告。此步骤为可选，但较旧的页面在被爬取或被已登录用户访问之前不会显示在报告中。

观看配置选项视频介绍（v2.4）。

隐藏无用提示

良好的配置能屏蔽无用提示，让内容作者专注于真正需要修复的问题。

虽然可以完全关闭某些测试，但通常更好的做法是针对特定元素或页面隐藏提示。

每次测试运行时，Editoria11y 会从"检查这些容器中的内容"设置中获取一组元素，并对其进行多次过滤。测试运行的流程如下：

  1. 若配置阻止在当前页面或对当前用户进行检查，则取消检查。
  2. 收集指定页面区域中的元素，例如：
    body > *:not('.ed11y-element')
    对于 Editoria11y CSA 用户，这些区域显示在开发者测试标签页中。
  3. 排除匹配忽略选择器的元素，例如：
    .widgets, .utility-menu
    对于 Editoria11y CSA 用户，这些选择器显示在开发者测试标签页中。
  4. 运行测试并将结果同步至仪表板。
  5. 若已启用分离配置且当前用户是内容编辑，则过滤开发者结果：
    • 排除设置为"仅开发者"的测试结果。
    • 排除指定内容区域之外的元素结果，例如：
      main, footer
    • 排除匹配内容忽略选择器的元素结果。
    请注意，不存在第二个"收集"阶段。开发者页面区域必须包含内容区域。
  6. 若配置匹配自动展开设置，则打开面板并显示提示。

忽略提示

测试可在库中配置为错误或警告（"手动检查"）。警告可被忽略。每个工具提示底部提供两种忽略方式：

  • "忽略"作为用户偏好保存：该提示现在仅对当前用户隐藏，不影响其他用户。
  • "标记为无误"将对所有用户隐藏该提示。

用户是否能忽略提示，由 Drupal 用户权限中的角色级别控制。大多数作者应被授予忽略提示的权限。如果用户无法将某项标记为已检查，那么为其分配人工检查任务便毫无意义。

忽略元素

以下两项配置设置最为重要！

第一项应包含内容作者可编辑的所有页面区域。例如，若作者可编辑 main 内容区、.sidebar 和 .footer-column-two，则将这些选择器设置为内容检查区域。

第二项用于"屏蔽"子区域。例如，若 main 包含仅开发者可修改的各种小部件和嵌入内容，则在此列出：.widget-1, .social-embed。

如果您使用分离配置，则会在"开发者测试"标签页看到一对类似的设置：

开发者检查区域

关于开发者检查区域，有一点至关重要：它们与内容检查区域并非相互独立。在分离配置中，开发者区域会被检查，随后其结果会被过滤以匹配内容区域。对开发者排除的区域同样会对内容编辑排除。请勿排除可编辑的内容区域！

部分测试支持更精细的配置，可仅对受影响的元素隐藏特定提示。相关选项位于：

  • 内容测试：要检查的链接
  • 内容测试：要检查的嵌入内容
  • 内容测试：检测动态内容与 Shadow DOM 内容
  • 开发者测试：对比度

针对特定页面或用户隐藏

最简便的方法是将 CSS 类或 ID 传递给以下选项：

第一项将阻止检查运行，工具栏也不会显示。

第二项将以最小化状态启动检查器，并自动将所有问题（包括错误）对当前用户标记为"已忽略"。这样测试仍可运行并更新仪表板，而不会打扰用户。

若要通过这些设置控制哪些用户可以看到检查器，您可能需要调整主题以输出特定的 CSS 类，例如 .user-247。

管理全站结果

爬取与更新结果

Editoria11y 是一个实时监控工具，而非爬虫。其全站报告在作者浏览页面时更新，因此通常无需定期爬取。CSA 模块确实包含一个爬虫，但仅在以下三种情况下才需要使用：

  1. 在现有多页面站点上首次安装 Editoria11y 时。页面需要被访问后才会出现在仪表板中，因此进行一次初始爬取可节省时间。
  2. 主题或模块的重大更新可能会修复（或引入）许多页面上的问题，这些变化在页面被访问或爬取之前不会反映出来。
  3. 在管理界面批量删除页面或重定向等操作往往会留下已不存在或已移动页面的残留结果。此时，使用"刷新"标签页中的维护功能来刷新页面 URL、检测并清除已删除页面会很有帮助。

爬取过程中不会有任何数据离开您的站点。CSA 爬虫并非云端工具，它使用您的浏览器加载并检查您自己站点上的页面。这种方式的不足之处在于浏览器会暂停后台标签页。爬取期间需要保持电脑开启且不进入休眠。建议为爬虫单独开一个窗口，并在爬取过程中将其保持为该窗口的前台标签页。您可以在另一个窗口中继续工作。爬虫将在每批页面处理完成后更新进度估算。

查看报告

  • 最近支持按单条提示浏览，可用于筛选同一类型提示的所有实例、查看近期内容中频繁出现的提示，或了解哪些作者仍在重复同类错误。
  • 页面按页面显示提示数量，并按页面分组，便于找出问题最多的页面，也可按内容类型和发布状态等页面属性进行筛选。
  • 提示按类型显示问题。
  • 忽略记录支持监控作者的忽略操作是否得当，并提供"重置"按钮以恢复已忽略的提示。
  • 导出包含可筛选的页面、提示与忽略记录报告版本，可准备 CSV 下载。由 CSV Export 子模块提供
  • 刷新包含仪表板维护工具，可清除已删除页面的提示、清除 /search?query=example 等参数化伪页面的提示、更新已存储的页面标题和 URL，以及运行手动爬取。由 CSA 子模块提供

修复隐藏或超出屏幕的提示

该模块为库的两个配置选项提供了字段，用于调整提示的定位方式：

部分主题的列或小部件会隐藏水平或垂直方向的溢出内容。库会自动检测切换按钮是否会超出页面的可见区域。告知库哪些容器会隐藏溢出内容，库便会尝试将这些容器内元素的提示定位在容器边框范围之内。

部分主题包含可切换内容可见性的小部件，如手风琴、标签页和幻灯片。位于这些元素内部的提示也会被隐藏。为这些小部件提供选择器列表后，当用户尝试使用"前一个"或"后一个"按钮跳转到这些提示时，Editoria11y 会短暂暂停。Drupal 主题和模块随后可参照库中关于处理隐藏内容中的提示的说明来显示隐藏的内容。

编写自定义配置

在 PHP 中：Drupal 模块提供了 hook_editoria11y_alter_config，可在模块或主题中修改 drupalSettings.editoria11y 的内容。例如：

修改 drupalSettings 仅在模块 JavaScript 已配置好将该值传递给库的情况下才有效。若要添加额外参数，需要直接修改 JavaScript 的 options 对象。该模块会检测一个名为 editoria11yOptionsOverride 的全局 JavaScript 变量。若该变量已设置，模块将把 options 对象传递给您在模块或主题中提供的 editoria11yOptions 函数，届时即可设置任意库参数。

编写自定义测试

首先，在模块配置中将"自定义测试"选项设为 1，以便模块知道要监听这些测试。

然后在您的主题或模块中创建一个包含自定义测试的 Drupal JavaScript 库，参考编写自定义测试的库指南。

以下是普林斯顿大学提供的一个实际示例，用于对 Safe Links 发出警告的自定义测试。请注意，它通过 Drupal.Ed11y. 访问 Editoria11y 类。

获取帮助

请访问联系页面了解社区支持渠道。@itmaybejj 通常在西半球白天时段活跃于 Drupal Slack。

大多数 CSA 贡献级别均包含年度例会，可涵盖安装与配置方面的直接协助。