尝试以扩展 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 中数千个问题的笔记本。通过这个笔记本,我们可以一次检查多个仓库,使用“查找所有标记为 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 笔记本:深入探讨。自视频发布以来,一些笔记本 API 已有所更改,但原理仍然相同。

当您准备构建自己的笔记本扩展时,如需获取最新和详细的信息,可以参考笔记本扩展作者指南

与社区分享您的想法

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

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

编码愉快!

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