在 VS Code 中试试

笔记本,Visual Studio Code 风格

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

笔记本是包含富 Markdown、可执行代码片段和相应富输出混合的文档。这些内容都被分成不同的单元格,可以以任何顺序交错排列。

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

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

笔记本不仅是出色的 REPL,它们还是出色的叙事工具,允许你将图像、数学公式和解释性文本等 Markdown 元素与你的代码交错排列。笔记本是与同事或公众社区分享和解释你的想法的完美方式。

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

VS Code 中的笔记本支持

没错,笔记本现在是 VS Code 核心功能的一部分!这意味着 VS Code 中现在有笔记本 API 可用,允许扩展作者创建自己的笔记本体验。任何人都可以制作一个支持自定义语言和富输出的 VS Code 笔记本扩展,创建笔记本与创建任何其他扩展并无不同。

在笔记本 API 之前,VS Code 中的 Jupyter Notebook 支持完全由 Jupyter 扩展贡献。该扩展在隔离的 webview 中创建其笔记本体验,这有点像 VS Code 中的独立网页,无法与你安装的任何其他扩展通信。

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

笔记本 API 不限于 Jupyter Notebooks,因为我们相信许多其他领域可以受益于拥有一个帮助你迭代和叙述代码的工具。我们向所有扩展作者公开了新的笔记本 API,以制作他们自己的自定义笔记本。

笔记本扩展生态系统的开端

下一节描述了我们在验证笔记本 API 时开发的两个自定义笔记本。

GitHub Issues 笔记本

VS Code 团队创建的第一个笔记本体验是 GitHub Issues 笔记本。它是一个笔记本,旨在帮助我们分类和组织 GitHub 中的数千个问题。通过这个笔记本,我们可以同时检查多个仓库,使用“查找所有标记为 bug 并分配给我的问题”等查询来查找问题。VS Code 团队每天使用这个笔记本处理团队工作的许多仓库中的问题。

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

你可以在 VS Code 仓库的 .vscode/notebooks 目录下找到我们用于分类的具体笔记本。其中有一个名为 inbox.github-issues 的,用于将新问题分类到适当的区域和经办人。

GitHub Issues 笔记本可在 VS Code Marketplace 上供所有人使用。你可以通过安装扩展,为你的笔记本创建一个文件,文件扩展名为 .github-issues,例如 my-notebook.github-issues,然后创建查询,例如

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

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

你可以在 GitHub.com 上查看 GitHub Issues 笔记本的源代码

REST Book

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

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 查询语言提供语法高亮和自动完成。然后,使用笔记本 API,我只需要填入用户想要运行查询时应该执行什么操作。

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

对于这两个笔记本,拥有 VS Code 笔记本 UI 来创建这些类似 REPL 的体验真是太棒了。你无需担心创建和维护自己的 UI,只需专注于功能即可。

制作你自己的自定义笔记本扩展

观看编码教程

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

当你准备构建自己的笔记本扩展时,有关最新和最详细的信息,你可以参考笔记本扩展作者指南

与社区分享你的想法

如果你对创建自己的笔记本扩展不感兴趣,但有实用应用程序的想法,我们鼓励你向 VS Code Twitter 账号 @code 发送笔记本想法的推文,或在 VS Code GitHub 仓库中创建问题。这将让 VS Code 社区阅读和讨论你的笔记本想法,并希望激励人们将你的笔记本变为现实!

我们在本博客中介绍的几个自定义笔记本只是一个开始!我们很高兴能看到你将启发并创造出什么样的自定义笔记本体验!

编程愉快!

Tanha Kabir (@_tanhakabir) , 和 VS Code 团队 (@code)