安装与配置

预配置版本

• Drupal 安装程序
• WordPress 安装程序
• Kirby 安装程序 （社区贡献）
• CraftCMS 安装程序 （社区贡献）

自定义安装

如需构建自己的实现，请下载本地副本（或引用 CDN 版本），包含语言包、JS 压缩文件和 CSS 压缩文件，然后创建一个新的”Ed11y”实例。

使用 ESM/JS 模块导入：

对于旧版浏览器和系统，请使用 .umd JavaScript 文件：

参数

完整实现仅会为已登录的编辑者调用（您不希望网站访客看到检查器！），并可覆盖任何默认参数。

请注意，所有参数均已设有默认值；只需包含您希望覆盖的部分即可。

高度自定义的实现可能如下所示：

一键式集成通常会动态设置这些变量——例如，在页面近期被编辑时以 assertive 模式加载，几分钟后切换回 polite 模式。

主题定制

多个参数支持选择主题、覆盖颜色以及注入 CSS。

只需包含您需要覆盖的参数，以便日后更新更加便捷。

常用 JS 事件

主题开发者可以监听这些事件，以便在需要时对页面作出响应和修改。

按典型出现顺序排列……

• ed11yRunCustomTests：当 Results 对象就绪、可注入自定义结果时触发。请注意，必须将 customTests 参数设置为您将运行的自定义测试函数数量（……通常为一个……），该事件才会触发。详情见后续章节。
• ed11yResults：所有检查完成后触发。API 集成现在可以从 Ed11y.results 对象中提取数据。
• ed11yPanelOpened：面板自动或手动打开时触发。
• ed11yShowHidden：提供 data-ed11y-result 编号和 viaJump 布尔值。仅在设置了”ed11yShowHidden”参数且元素的某个父级匹配选择器时触发。用于在尚未展开的容器（如手风琴、标签页和轮播图）中显示警告。使用示例见下一章节。
• ed11yPop：提供 data-ed11y-result ID，以及 result 和 tip 对象的引用。在工具提示出现时触发，允许您在运行时修改提示内容。
• ed11yShut：提供 data-ed11y-result ID。在工具提示关闭时触发。
• ed11yDismissalUpdate：当用户忽略或恢复警告时提供详细信息。用于 API 集成。事件对象包含：
  • dismissPage
  • dismissTest
  • dismissKey
  • dismissAction

示例代码可在后续章节中找到。

修改提示内容

如果您只想修改提示的文本内容，可以直接覆盖 ed11yLang.en 全局对象（调用库之前）或 Ed11y.M 对象（调用库之后）中的对应条目。例如，在 Drupal 模块中，语言包被别名为 Drupal.ed11yLang：

Drupal.ed11yLang.lang.testNames.title = “Please write shorter headings.”

对于本地化文件中的任意默认键或当前使用的特定语言翻译，上述方式同样适用。

Drupal 模块还使用 editLinks 参数向提示中添加自定义编辑链接。请注意”页面编辑器”和”布局编辑器”：

设置该参数的简化版代码如下：

Drupal 模块随后使用 ed11yPop 事件，在显示提示时根据上下文动态显示或隐藏编辑链接。

该事件提供了 result 和 tip 对象的引用：

自定义测试

如果 customTests 参数为一个数字，Editoria11y 将在检查过程中触发”ed11yRunCustomTests”事件，然后暂停最多 500 毫秒，等待相应数量的”ed11yResume”事件。

利用这一机制，您可以调用任意数量包含自定义测试的脚本，这些脚本可以在绘制提示之前将结果推入结果数组。

例如，如果您想创建以下提示，以标记从电子邮件中粘贴的含有混淆 URL 的链接：

您需要：

1. 为 ed11yRunCustomTests 事件添加监听器
2. 查找匹配的元素
3. 定义提示消息
4. 触发”resume”事件，让 Editoria11y 绘制提示：

处理隐藏或尺寸受限内容中的警告

许多交互式组件（标签页、滑块、手风琴）会隐藏内容。Editoria11y 信息面板包含上一条/下一条按钮，可直接跳转至问题所在位置。如果 Editoria11y 判断问题的工具提示当前不可见，它会提示用户存在问题，并高亮显示第一个可见的祖先元素——例如手风琴外层的 div。

理想情况下，您的主题会在 Editoria11y 的可见性检查运行之前使这些元素可见，让一切对用户来说都浑然天成——轮播图自动前进，手风琴自动展开以显示问题。

要在面板首次打开时执行此操作（例如展开所有存在问题的手风琴面板），可为 ed11yPanelOpened 添加 JS 事件监听器，然后对相关 ed11y-element-result 元素执行 querySelectorAll，再触发主题用于显示该页面部分内容的函数。

以下是一个基于 jQuery 的示例。面板打开时，它会禁用固定菜单（避免元素被遮挡），然后查找已关闭手风琴项目内的所有 ed11y-element-result 元素，并模拟点击其切换按钮：

若要仅在通过面板”下一条”按钮跳转到特定提示时（例如在已关闭的标签页或下一张轮播幻灯片中）才显示内容，需要在参数中将 hiddenHandlers 设置为相关 CSS 选择器，并将 checkVisible 设置为 TRUE，然后为 ed11yShowHidden 事件添加监听器。当 Editoria11y 识别到提示位于包含 hiddenHandlers 选择器的容器内时，此事件会被触发。该 JS 事件将包含即将打开的提示的 ID。Editoria11y 随后会在触发此事件后短暂暂停，以便您的 JS 有时间使元素可见。

以下是来自宾夕法尼亚州立大学实现的示例。它查找与所提供 ID 匹配的元素，找到其父级交互组件容器，并触发其事件以激活切换：

最后说明：部分主题与可见性检查不兼容，例如 <main> 容器高度为 0px 的情况。此类网站应通过将 checkVisible 设为 false 来禁用所有可见性检查。