尝试以扩展 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 Notebook 还通过 Jupyter 内核支持其他语言,如 Julia 或 R,这些内核是遵循特定协议以在你的笔记本中运行代码的可执行文件。Visual Studio Code 支持 Jupyter Notebook 已有数年,但最近在 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 Notebook,因为我们相信还有许多其他领域可以从拥有一个帮助你迭代和叙述代码的工具中受益。我们公开了新的笔记本 API,供任何扩展作者打造自己的自定义笔记本。

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

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

GitHub Issues 笔记本

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

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 的笔记本用于将新的 issue 分配到合适的领域和负责人。

GitHub Issues 笔记本已在 VS Code 市场中上架,供任何人使用。你可以通过安装该扩展来尝试它,为你的笔记本创建一个带有 .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 扩展如今也已在市场上架。你可以安装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 笔记本:深度解析。自视频发布以来,一些笔记本 API 已有变化,但基本原理仍然相同。

当你准备好构建自己的笔记本扩展时,可以参考笔记本扩展作者指南,以获取最新、最详细的信息。

与社区分享你的想法

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

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

编码愉快!

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