无障碍性：JupyterLab 开发人员指南#

如果您正在对 JupyterLab 源代码进行更改，并且您担心 无障碍性，此页面适合您。

寻找其他方法来 为 Jupyter 项目的无障碍性做出贡献？

从哪里开始#

感谢您对改善 JupyterLab 的无障碍性感兴趣。无论是进行特定于无障碍性的修复，还是考虑其他贡献对无障碍性的影响，您的工作都让 JupyterLab 变得对所有使用它的人来说都更好。

当有无障碍性意识的开发人员来到 JupyterLab 时，一个常见的问题是：我从哪里开始？

如果您没有太多时间沉浸在 JupyterLab 无障碍性工作的全局图景中，那么标记为 良好入门问题和无障碍性 的 GitHub 问题是一个不错的起点。

如果您想更全面地沉浸在使 JupyterLab（或其他 Jupyter 项目）更易于访问的工作中，那么一个好的起点是加入 Jupyter 无障碍性会议，该会议每两周举行一次。如果您无法参加电话会议，您可以查看会议记录并找到指向 Jupyter 无障碍性 网站上其他资源的链接。

正在寻找 面向前端开发人员的 JupyterLab 代码库导向？

开发过程中的最佳实践#

JupyterLab 是一个 Web 应用程序和创作工具。因此，以下标准适用

这些是熟悉开发网站（WCAG）和 Web 应用程序（ARIA）的无障碍性最佳实践的好地方。请注意，尽管 WCAG 主要针对静态网站创建，但这些指南仍然适用于像 JupyterLab 这样的 Web 应用程序。

对于寻找示例和最佳实践的开发人员来说，一个经常特别有用的资源是 ARIA 模式。此 Web 资源包含有关如何以更易于访问的方式实现 UI 元素（例如菜单、对话框、面包屑等）的示例。但是，请小心！仅仅因为您可以使用 div 和 aria 属性来实现按钮并不意味着您应该这样做！（您很可能应该只使用按钮标签。）作为最佳实践，您应该只在无法使用现有 HTML 元素（按钮、输入、导航、旁白等）来实现您想要的 UX 时才使用 ARIA。

最后，互联网上的无障碍性知识远比 JupyterLab 或 Project Jupyter 单独拥有的知识要多。无论您决定做什么，请考虑探索其他空间中的无障碍性资源，以了解类似或等效的努力。无障碍性社区往往乐于提供他们提供的资源来改善 Web 无障碍性。很多时候，在搜索引擎中搜索任务或问题的名称，并在后面加上 无障碍性，就会给出几个结果，并有机会立即从更广泛的社区中学习。

本节的其余部分包含特定于 JupyterLab 及其开发的最佳实践。

使用 CSS 中的颜色变量#

在修复 JupyterLab 中的对比度或其他视觉无障碍性问题时，您可能会倾向于选择一种颜色并将其应用于您正在处理的 UI 部分。但是，在不同的 CSS 文件中，颜色值散布在整个应用程序中，很快就会变得难以管理。因此，JupyterLab 代码库定义了一组 颜色变量，可用于边框、图标等。如果您要添加任何需要颜色值的 CSS，请使用定义的变量之一。

Lumino 中的上游修复#

JupyterLab 使用一个专门为其构建的前端框架，称为 Lumino。Lumino 在某些方面类似于 React、Vue 和 Angular，但它还提供了一些 UI 小部件，例如菜单栏、选项卡栏和停靠面板。因此，在 JupyterLab GitHub 仓库中报告的一些可访问性问题需要在 Lumino 仓库中修复。学习 Lumino 的一个好资源：PhosphorJS（现为 Lumino）导师课程。PhosphorJS 是 Lumino 的前身。有一个页面包含 PhosphorJS 课程笔记，其中还包含指向一些未上传到 YouTube 的其他视频的链接。

并非总是很明显何时应该在 JupyterLab 或 Lumino 中修复可访问性问题。以下是一些指导，可帮助您确定应在何处进行更改

  • 一般来说，如果可以在 Lumino 中修复问题，最好在 Lumino 中修复它，因为这样修复将在更多地方被吸收。

  • 但是，出于同样的原因，由于 Lumino 被比 JupyterLab 更多的代码库使用（特别是 JupyterLab 扩展），因此在更改 Lumino 时应谨慎，因为这些更改可能会破坏下游使用者/扩展。

  • 因此，另一个经验法则是：如果无法在不破坏依赖项的情况下在 Lumino 中进行修复，那么最好在 JupyterLab 中进行修复。在这种情况下，您可能会采用双轨方法，在 JupyterLab 中修复可访问性问题，并在 Lumino 中提交一个破坏性修复，该修复针对 Lumino 的未来主要 API 突破性发布/版本。

自动化回归测试#

如果您在源代码中修复了可访问性问题，但没有添加测试来修复它，那么您的修复很有可能在将来对代码库进行的一些更改中被意外撤消。

有时对可访问性修复进行单元测试很简单，例如 在工具栏按钮上启用键盘快捷键 时。但通常很难对可访问性修复进行单元测试。

因此，正在努力使用 Playwright 为 JupyterLab 编写用户级 可访问性测试。为了说明如何在开发过程中使用它，让我们来看一个例子。

此示例将涉及三个独立的 GitHub 仓库

  1. Quansight-Labs/jupyter-a11y-testing

  2. jupyterlab/lumino

  3. jupyterlab/jupyterlab

这是一个来自实际过去工作的真实示例。

假设您对 JupyterLab UI 的起始页进行了可访问性审计，并在顶部菜单栏中发现了一个选项卡陷阱，这意味着用户可以使用 Tab 键进入菜单栏，但无法轻松地使用键盘通过它。

您进一步深入研究，发现 选项卡陷阱错误位于 jupyterlab/lumino 仓库中，因此您分叉了 jupyterlab/lumino 仓库，创建了一个名为 fix-tab-trap 的新分支，并打开了一个拉取请求。

您决定要编写一个测试。这是编写单元测试很简单的情况之一。但是，单元测试只会检查顶部菜单栏，因此它不会阻止您决定要一劳永逸地修复的问题再次出现，即：您不希望在 JupyterLab 起始页的任何地方出现选项卡陷阱。

因此，您决定要 在 Quansight-Labs/jupyter-a11y-testing 仓库中添加一个回归测试。此测试通过使用 Playwright 打开 JupyterLab 并反复按 Tab 键来检查 JupyterLab 起始页上是否存在选项卡陷阱。因此，与之前的 Lumino 仓库一样，您分叉了 Quansight-Labs/jupyter-a11y-testing 仓库，创建了一个名为 test-tab-trap 的分支，并打开了一个拉取请求。此步骤中的重要一点是，您将测试文件保存在其他回归测试文件旁边的 .test.ts 扩展名中。

现在您要运行测试。具体来说，您要针对包含 Lumino 修复的 JupyterLab 版本运行测试。以下是执行此操作的方法。

假设您的 GitHub 用户名是 a11ydev，并且您已分叉了 Lumino 和测试仓库，并在这些分叉上创建了以下分支，一个包含您的错误修复，另一个包含您的测试

  1. a11ydev/lumino:fix-tab-trap

  2. a11ydev/jupyter-a11y-testing:test-tab-trap

在 GitHub 上，进入你对测试仓库的 fork，即 *a11ydev/jupyter-a11y-testing*。确保你处于你的 *test-tab-trap* 分支上，该分支包含你添加的 * .test.ts* 文件。然后进入 Actions 并点击名为“Run accessibility tests on JupyterLab” 的工作流。点击“Run workflow”。这将打开一个配置工作流的表单。

以下是填写表单的方式：

  1. 使用来自：*test-tab-trap* 的工作流

  2. JupyterLab 仓库：*jupyterlab/jupyterlab*

  3. 分支/标签/SHA：*main*

  4. 测试套件：留空

  5. 外部包仓库：*a11ydev/lumino*

  6. 外部包引用：*fix-tab-trap*

然后按下“Run workflow”按钮。一个 GitHub action 应该会从源代码构建 JupyterLab，链接你的 Lumino fork 和分支，然后运行测试套件，包括你的测试，最后显示测试结果，希望你的测试通过。

请注意，在这个例子中，你没有 fork jupyterlab/jupyterlab 仓库，也没有在工作流配置表单中将分支名称更改为除“main”以外的名称。这是因为你不需要修改 JupyterLab 代码库来解决这个问题。但是，如果你正在处理一个需要修改 JupyterLab 代码库的问题，你将执行与之前处理 Lumino 相同的操作：fork 仓库，创建一个包含你的修复的分支，然后在运行工作流之前在工作流配置表单中输入你的 fork 和分支。这应该会导致它基于你的更改构建一个 JupyterLab 版本，然后针对它运行测试套件。该工作流足够灵活，允许你根据需要同时测试 JupyterLab 或 Lumino 或两者的更改。

注意

在测试仓库中，有更多关于如何使用 GitHub 工作流的 详细说明。

PR 审查和手动测试#

在审查代码、文档或其他贡献时，可以使用手动测试来帮助防止可访问性错误。通常，你会尝试使用可访问性辅助功能或设置来完成与你的修复或贡献相关的任务。常见选项包括

  • 使用 屏幕阅读器。

  • 通过浏览器将页面放大到 400%。

  • 拔掉或不使用鼠标。只用键盘导航。

  • 模拟视觉缺陷（Chrome、Edge 和 Firefox 都提供了内置工具来执行此操作。）

在测试时，请注意发生了什么，并将其与你在没有选择的可访问性辅助功能的情况下完成任务时可以做的事情进行比较。如果你无法完成任何事情，那么你遇到了一个阻止可访问性的问题。即使你使用辅助技术或可访问性辅助功能的方式可能与经常使用它们的人不同，但了解结果有助于判断 JupyterLab 是否按预期运行。

GitPod#

如果你有 GitPod 帐户，并且你已向 JupyterLab 提交了 PR，你可以通过将 GitHub URL 复制到你的 PR 并将其与 *gitpod.io/#* 连接起来来手动测试它，如下所示

*https://gitpod.io/#https://github.com/jupyterlab/jupyterlab/pull/* *your-pr-number*

GitPod 将从源代码构建 JupyterLab，应用你的 PR，并设置一个隧道，以便你可以在 localhost:8888 的浏览器中加载 UI。

开发中有用的工具#

以下是一些开发人员在 JupyterLab 中进行可访问性工作时发现有用的应用程序列表

本页内容
在 GitHub 上编辑
显示源代码