可访问性：JupyterLab开发者指南#

如果您正在对JupyterLab源代码进行更改，并且您关心可访问性，那么此页面适合您。

寻找其他方式为Jupyter项目的可访问性做出贡献？

从哪里开始#

感谢您对提升JupyterLab可访问性的兴趣。无论是进行专门的可访问性修复，还是考虑其他贡献对可访问性的影响，您的工作都使JupyterLab对所有使用者更加友好。

当关注无障碍的开发者来到JupyterLab时，一个常见的问题是：我从哪里开始？

如果你没有太多时间深入了解JupyterLab无障碍工作的全貌，那么GitHub上标记为good first issue和accessibility的问题是一个很好的起点。

如果你想更深入地参与到使JupyterLab（或其他Jupyter项目）更易于访问的工作中，那么一个很好的起点是加入每两周举行一次的Jupyter无障碍会议。如果你无法参加电话会议，你可以浏览会议记录，并在Jupyter无障碍网站上找到其他资源的链接。

寻找前端开发者对JupyterLab代码库的指南？

开发时的最佳实践#

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

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

对于寻找示例和最佳实践的开发者来说，一个特别有用的资源是ARIA Patterns。这个网络资源包含了如何以更易访问的方式实现UI元素的示例——比如菜单、对话框、面包屑导航等。然而，要小心！仅仅因为你可以使用div和aria属性来实现一个按钮，并不意味着你应该这样做！（很可能你应该只使用button标签。）作为最佳实践，你应该只在无法使用现有的HTML元素（button、input、nav、aside等）来实现你想要的用户体验时，才使用ARIA。

最后，互联网上的可访问性知识比JupyterLab或Project Jupyter单独提供的要多得多。无论你决定做什么，考虑在其他领域探索可访问性资源，以寻找类似或等效的努力。可访问性社区通常对他们提供的资源非常慷慨，以改善网络可访问性。很多时候，在搜索引擎中搜索任务或问题的名称加上accessibility会给你带来几个结果，并有机会立即从更广泛的社区中学习。

本节其余部分包含特定于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中提交一个针对未来主要API破坏性版本/版本的破坏性修复。

自动化回归测试#

如果你在源代码中修复了一个可访问性问题，但没有为你的修复添加测试，那么你的修复很可能会因为未来对代码库的某些更改而被意外撤销。

有时候，单元测试一个无障碍修复是直接的，比如当在工具栏按钮上启用键盘快捷键时。但通常，单元测试无障碍修复是困难的。

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

这个例子将涉及三个独立的GitHub仓库：

  1. Quansight-Labs/jupyter-a11y-testing

  2. jupyterlab/lumino

  3. jupyterlab/jupyterlab

这是一个真实世界的例子，取自过去的实际工作。

假设你对JupyterLab用户界面的起始页面进行了一次可访问性审计，并在顶部菜单栏中发现了一个标签陷阱，这意味着用户可以通过按下Tab键进入菜单栏，但仅使用键盘很难越过它。

你进一步挖掘并发现tab trap bug 在 jupyterlab/lumino 仓库中，因此你 fork 了 jupyterlab/lumino 仓库，创建了一个名为 fix-tab-trap 的新分支，并打开了一个 pull request。

你决定要编写一个测试。这是那些编写单元测试会是一个直接任务的情况之一。然而，单元测试只会检查顶部菜单栏，因此它不会防止你决定要一劳永逸解决的问题再次出现，即：你不希望在JupyterLab启动页面的任何地方出现标签陷阱。

所以你决定要在Quansight-Labs/jupyter-a11y-testing仓库中添加一个回归测试。 这个测试通过使用Playwright打开JupyterLab并反复按下Tab键来检查JupyterLab启动页面上是否存在Tab陷阱。因此，就像之前的Lumino仓库一样，你fork了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上，转到您分叉的测试仓库，a11ydev/jupyter-a11y-testing。 确保您在test-tab-trap分支上，该分支包含您添加的 .test.ts文件。然后转到Actions并点击标题为“在JupyterLab上运行可访问性测试”的工作流。 点击“运行工作流”。这将打开一个表单来配置工作流。

以下是您应如何填写表格：

  1. 使用工作流来自: test-tab-trap

  2. JupyterLab 仓库: jupyterlab/jupyterlab

  3. 分支/标签/SHA: main

  4. 测试套件：留空

  5. 外部包仓库: a11ydev/lumino

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

然后按下“运行工作流程”按钮。GitHub 操作应该会从源代码构建 JupyterLab，链接你的 Lumino 分支和分支，然后运行测试套件，包括你的测试，最后显示测试结果，希望你的测试能够通过。

请注意，在这个例子中，您没有分叉 jupyterlab/jupyterlab 仓库，也没有在工作流配置表单中将分支名称更改为“main”以外的名称。这是因为您不需要修改 JupyterLab 代码库来解决这个问题。但如果您正在处理一个需要您修改 JupyterLab 代码库的问题，您会像之前对 Lumino 所做的那样：分叉仓库，创建一个包含您修复的分支，然后在运行工作流之前在工作流配置表单中输入您的分叉和分支。这应该会导致它基于您的更改构建一个 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中进行无障碍工作时发现有用的应用程序列表：