参加你附近的 ,了解 VS Code 中的 AI 辅助开发。

Visual Studio Code 风格的 Notebook

2021年11月8日,作者:Tanha Kabir, @_tanhakabir

Notebook 是一种文档,它包含了丰富的 Markdown、可执行的代码片段以及相应的富文本输出。这些内容被分离到不同的单元格中,并可以按任意顺序穿插排列。

An example notebook showing code cells, Markdown, and a rich graph output

如果你对 Notebook 不太熟悉,你可能熟悉 REPL(读取-求值-打印循环)吧?REPL 是一个交互式应用程序,你可以在其中编写几行代码并立即执行,然后查看输出。Notebook 是 REPL 的典范,能让你快速创建一个环境,在其中迭代和处理小块代码。

Notebook 不仅是出色的 REPL,它们也是绝佳的叙事工具,允许你将 Markdown 元素(如图片、数学公式和解释性文本)与代码交织在一起。Notebook 可以是与同事或社区分享和解释你想法的完美方式。

当今最流行的 Notebook 形式是 Jupyter Notebook,它在数据科学界被广泛使用,并提供了丰富的 Python 支持。Jupyter Notebook 也通过 Jupyter 内核支持其他语言,如 Julia 或 R。Jupyter 内核是遵循特定协议的可执行文件,用于在 Notebook 中运行代码。Visual Studio Code 支持 Jupyter Notebook 已有数年,但最近已将原生 Notebook 支持添加到 VS Code 核心中。

VS Code 中的 Notebook 支持

没错,Notebook 现在已成为 VS Code 核心功能的一部分!这意味着 VS Code 中现在提供了Notebook API,让扩展开发者可以创建自己的 Notebook 体验。任何人都可以制作一个支持自定义语言和富文本输出的 VS Code Notebook 扩展,其创建过程与创建任何其他扩展并无不同。

在 Notebook API 出现之前,VS Code 中的 Jupyter Notebook 支持完全由 Jupyter 扩展提供。该扩展在一个隔离的 webview 中创建其 Notebook 体验,有点像 VS Code 内部的一个独立网页,无法与你安装的任何其他扩展进行通信。

然而,现在有了核心的 Notebook API,Notebook 支持来自 VS Code 本身,而不是在一个隔离的 webview 中。这意味着 Notebook 扩展可以与 VS Code 的其余部分以及其他扩展进行交互。例如,像 Rainbow Indent 这样的编辑器扩展将可以在你的 Notebook 代码单元格中工作。

Notebook API 并不局限于 Jupyter Notebook,因为我们相信还有许多其他领域可以从拥有一个帮助你迭代和叙述代码的工具中受益。我们已将新的Notebook API公开,供任何扩展开发者打造自己的自定义 Notebook。

Notebook 扩展生态系统的开端

下一节将介绍我们在审查 Notebook API 时开发的两个自定义 Notebook。

GitHub Issues Notebook

VS Code 团队创建的第一个 Notebook 体验是 GitHub Issues Notebook。这是一个帮助我们分类和整理 GitHub 上成千上万个 Issue 的 Notebook。通过这个 Notebook,我们可以一次性检查多个仓库,使用诸如“查找所有标记为 bug 并分配给我的 Issue”之类的查询来查找问题。VS Code 团队每天都使用这个 Notebook 来处理团队所工作的多个仓库中的 Issue。

A preview of the GitHub Issues Notebook we use on the team that's available in the vscode repo

你可以在 VS Code 仓库的 .vscode/notebooks 目录下找到我们用于分类的具体 Notebook。其中有一个名为 inbox.github-issues 的文件,用于将新的 Issue 分类到合适的领域和负责人。

GitHub Issues Notebook 已在 VS Code Marketplace 上架,任何人都可以使用。你可以通过安装该扩展来试用它,为你的 Notebook 创建一个以 .github-issues 为文件扩展名的文件(例如 my-notebook.github-issues),然后创建查询,例如:

$repo=repo:microsoft/vscode-github-issue-notebooks
$repo is:open no:assignee

用于创建查询的 Notebook 语言 github-issues 与 GitHub.com 上使用的语法几乎相同。GitHub Issues Notebook 语言的一个新增功能是它允许你创建变量,并在任何其他单元格中使用它们。

你可以在 GitHub.com 上查看 GitHub Issues Notebook 的源代码

REST Book

受到 GitHub Issues Notebook 中查询体验的启发,我刚加入 VS Code 团队时,创建了 REST Book 作为一个学习练习。REST Book 允许你在 Notebook 中进行 HTTP 调用。我发现 REST Book 在迭代带有服务器的项目时非常有用,因为它能够随时间进行多次调用,并在一页上轻松比较结果。我还使用 REST Book Notebook 为我的项目设置了一些手动测试,并将文档与测试用例穿插在一起。

A preview of the REST Book being used in a project with an Express App

这个 REST Book 扩展今天也已在 Marketplace 上架。你可以安装 REST Book 扩展,创建一个以 .restbook 结尾的文件,然后执行任何 HTTP 查询,如 GET github.com

开发 REST Book 最初对我来说似乎很复杂,但有了大量可用的 VS Code API,编程和创建 REST Book 比我预期的要容易得多。最值得注意的是,我大量使用了语言 API 来为我的自定义 REST 查询语言提供语法高亮和自动补全功能。然后,借助 Notebook API,我只需要填写当用户想要运行查询时应该执行的操作即可。

你可以在这里查看 REST Book 的源代码

对于这两个 Notebook 来说,能够使用 VS Code Notebook UI 来创建这些类似 REPL 的体验真是太棒了。你无需担心创建和维护自己的 UI,只需专注于功能本身。

制作你自己的自定义 Notebook 扩展

观看编程教程

几个月前,VS Code 团队录制了一场关于自定义 Notebook 的直播,在直播中,我通过现场编程演示,展示了创建一个自定义 Notebook 扩展的过程。你可以在 YouTube 上观看:VS Code Notebooks: A Deep Dive。自视频发布以来,一些 Notebook API 已经发生了变化,但基本原理仍然相同。

当你准备构建自己的 Notebook 扩展时,可以参考Notebook 扩展开发者指南,以获取最新、最详细的信息。

与社区分享你的想法

如果你对创建自己的 Notebook 扩展不感兴趣,但对有用的应用有想法,我们鼓励你在 VS Code 的 Twitter 账号 @code 上发布你的 Notebook 想法,或者在 VS Code 的 GitHub 仓库中创建 Issue。这将让 VS Code 社区能够阅读和讨论你的 Notebook 想法,并希望能激励人们将你的 Notebook 变为现实!

我们在这篇博客中介绍的几个自定义 Notebook 仅仅是一个开始!我们很期待看到你将激发和创造出什么样的自定义 Notebook 体验!

编码愉快!

Tanha Kabir (@_tanhakabir) 及 VS Code 团队 (@code)