笔记本 API

笔记本 API 允许 Visual Studio Code 扩展将文件作为笔记本打开、执行笔记本代码单元，并以各种丰富且交互式的格式呈现笔记本输出。您可能知道流行的笔记本界面，如 Jupyter Notebook 或 Google Colab - 笔记本 API 允许在 Visual Studio Code 中获得类似的体验。

笔记本的组成部分

一个笔记本由一系列单元及其输出组成。笔记本的单元可以是 Markdown 单元 或 代码单元，并在 VS Code 的核心中呈现。输出可以是多种格式。一些输出格式，如纯文本、JSON、图像和 HTML 由 VS Code 核心呈现。其他格式，如应用程序特定的数据或交互式小程序，则由扩展呈现。

笔记本中的单元通过 NotebookSerializer 读取和写入文件系统，该 NotebookSerializer 负责从文件系统读取数据并将其转换为单元的描述，以及将对笔记本的修改持久保存回文件系统。笔记本的 代码单元 可以由 NotebookController 执行，它获取单元的内容，并从中生成零个或多个各种格式的输出，范围从纯文本到格式化文档或交互式小程序。应用程序特定的输出格式和交互式小程序输出由 NotebookRenderer 呈现。

可视化

Overview of 3 components of notebooks: NotebookSerializer, NotebookController, and NotebookRenderer, and how they interact. Described textually above and in following sections.

序列化器

NotebookSerializer API 参考

NotebookSerializer 负责获取笔记本的序列化字节，并将这些字节反序列化为 NotebookData，其中包含 Markdown 和代码单元的列表。它也负责相反的转换：获取 NotebookData 并将数据转换为要保存的序列化字节。

示例

JSON 笔记本序列化器: 简单的笔记本示例，它接收 JSON 输入并在自定义的 NotebookRenderer 中输出美化的 JSON。
Markdown 序列化器: 将 Markdown 文件作为笔记本打开和编辑。

示例

在此示例中，我们构建一个简化的笔记本提供程序扩展，用于查看 Jupyter Notebook 格式的文件，其文件扩展名为 .notebook（而不是传统的 .ipynb）。

笔记本序列化器在 package.json 中的 contributes.notebooks 部分下声明，如下所示

{
    ...
    "contributes": {
        ...
        "notebooks": [
            {
                "type": "my-notebook",
                "displayName": "My Notebook",
                "selector": [
                    {
                        "filenamePattern": "*.notebook"
                    }
                ]
            }
        ]
    }
}

然后，笔记本序列化器在扩展的激活事件中注册

import { TextDecoder, TextEncoder } from 'util';
import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  context.subscriptions.push(
    vscode.workspace.registerNotebookSerializer('my-notebook', new SampleSerializer())
  );
}

interface RawNotebook {
  cells: RawNotebookCell[];
}

interface RawNotebookCell {
  source: string[];
  cell_type: 'code' | 'markdown';
}

class SampleSerializer implements vscode.NotebookSerializer {
  async deserializeNotebook(
    content: Uint8Array,
    _token: vscode.CancellationToken
  ): Promise<vscode.NotebookData> {
    var contents = new TextDecoder().decode(content);

    let raw: RawNotebookCell[];
    try {
      raw = (<RawNotebook>JSON.parse(contents)).cells;
    } catch {
      raw = [];
    }

    const cells = raw.map(
      item =>
        new vscode.NotebookCellData(
          item.cell_type === 'code'
            ? vscode.NotebookCellKind.Code
            : vscode.NotebookCellKind.Markup,
          item.source.join('\n'),
          item.cell_type === 'code' ? 'python' : 'markdown'
        )
    );

    return new vscode.NotebookData(cells);
  }

  async serializeNotebook(
    data: vscode.NotebookData,
    _token: vscode.CancellationToken
  ): Promise<Uint8Array> {
    let contents: RawNotebookCell[] = [];

    for (const cell of data.cells) {
      contents.push({
        cell_type: cell.kind === vscode.NotebookCellKind.Code ? 'code' : 'markdown',
        source: cell.value.split(/\r?\n/g)
      });
    }

    return new TextEncoder().encode(JSON.stringify(contents));
  }
}

现在，尝试运行您的扩展并打开一个以 .notebook 扩展名保存的 Jupyter Notebook 格式的文件

Notebook showing contents of a Jupyter Notebook formatted file

您应该能够打开 Jupyter 格式的笔记本，并将它们的单元格查看为纯文本和渲染的 Markdown，以及编辑单元格。但是，输出不会持久保存到磁盘；要保存输出，您还需要从 NotebookData 中序列化和反序列化单元格的输出。

要运行单元格，您需要实现一个 NotebookController。

控制器

NotebookController API 参考

NotebookController 负责获取一个 代码单元 并执行代码以生成一些或不生成任何输出。

通过在创建控制器时设置 NotebookController#notebookType 属性，控制器直接与笔记本序列化器和笔记本类型相关联。然后，通过在扩展激活时将控制器推送到扩展订阅上来全局注册控制器。

export function activate(context: vscode.ExtensionContext) {
  context.subscriptions.push(new Controller());
}

class Controller {
  readonly controllerId = 'my-notebook-controller-id';
  readonly notebookType = 'my-notebook';
  readonly label = 'My Notebook';
  readonly supportedLanguages = ['python'];

  private readonly _controller: vscode.NotebookController;
  private _executionOrder = 0;

  constructor() {
    this._controller = vscode.notebooks.createNotebookController(
      this.controllerId,
      this.notebookType,
      this.label
    );

    this._controller.supportedLanguages = this.supportedLanguages;
    this._controller.supportsExecutionOrder = true;
    this._controller.executeHandler = this._execute.bind(this);
  }

  private _execute(
    cells: vscode.NotebookCell[],
    _notebook: vscode.NotebookDocument,
    _controller: vscode.NotebookController
  ): void {
    for (let cell of cells) {
      this._doExecution(cell);
    }
  }

  private async _doExecution(cell: vscode.NotebookCell): Promise<void> {
    const execution = this._controller.createNotebookCellExecution(cell);
    execution.executionOrder = ++this._executionOrder;
    execution.start(Date.now()); // Keep track of elapsed time to execute cell.

    /* Do some execution here; not implemented */

    execution.replaceOutput([
      new vscode.NotebookCellOutput([
        vscode.NotebookCellOutputItem.text('Dummy output text!')
      ])
    ]);
    execution.end(true, Date.now());
  }
}

如果您正在单独发布一个提供 NotebookController 的扩展，而不是它的序列化器，那么请在其 package.json 中的 keywords 中添加类似于 notebookKernel<ViewTypeUpperCamelCased> 的条目。例如，如果您发布了 github-issues 笔记本类型的替代内核，则应将关键字 notebookKernelGithubIssues 添加到您的扩展中。

示例

GitHub Issues 笔记本: 用于执行 GitHub Issues 查询的控制器
REST Book: 用于运行 REST 查询的控制器。
Regexper 笔记本: 用于可视化正则表达式的控制器。

输出类型

输出必须是以下三种格式之一：文本输出、错误输出或富输出。一个内核可以为单个单元格的执行提供多个输出，在这种情况下，它们将显示为一个列表。

简单格式，如文本输出、错误输出或富输出的“简单”变体（HTML、Markdown、JSON 等）由 VS Code 核心呈现，而应用程序特定的富输出类型则由 NotebookRenderer 呈现。扩展可以选择自己呈现“简单”的富输出，例如，在 Markdown 输出中添加 LaTeX 支持。

Diagram of the different output types described above

文本输出

文本输出是最简单的输出格式，并且与您可能熟悉的许多 REPL 非常相似。它们仅由一个 text 字段组成，该字段在单元格的输出元素中呈现为纯文本

vscode.NotebookCellOutputItem.text('This is the output...');

Cell with simple text output

错误输出

错误输出有助于以一致且易于理解的方式显示运行时错误。它们支持标准的 Error 对象。

try {
  /* Some code */
} catch (error) {
  vscode.NotebookCellOutputItem.error(error);
}

Cell with error output showing error name and message, as well as a stack trace with magenta text

富输出

富输出是显示单元格输出的最先进形式。它们允许提供输出数据的多种不同表示形式，这些表示形式通过 mimetype 键控。例如，如果要表示 GitHub Issue 的单元格输出，则内核可能会在其 data 字段上生成具有多个属性的富输出

一个 text/html 字段，其中包含问题的格式化视图。
一个 text/x-json 字段，其中包含机器可读的视图。
一个 application/github-issue 字段，NotebookRenderer 可以使用该字段来创建问题的完全交互式视图。

在这种情况下，text/html 和 text/x-json 视图将由 VS Code 原生呈现，但是如果未为该 mimetype 注册 NotebookRenderer，则 application/github-issue 视图将显示错误。

execution.replaceOutput([new vscode.NotebookCellOutput([
                            vscode.NotebookCellOutputItem.text('<b>Hello</b> World', 'text/html'),
                            vscode.NotebookCellOutputItem.json({ hello: 'world' }),
                            vscode.NotebookCellOutputItem.json({ custom-data-for-custom-renderer: 'data' }, 'application/custom'),
                        ])]);

Cell with rich output showing switching between formatted HTML, a JSON editor, and an error message showing no renderer is available (application/hello-world)

默认情况下，VS Code 可以呈现以下 mimetypes

application/javascript
text/html
image/svg+xml
text/markdown
image/png
image/jpeg
text/plain

VS Code 将在内置编辑器中将这些 mimetypes 渲染为代码

text/x-json
text/x-javascript
text/x-html
text/x-rust
... 适用于任何其他内置或已安装语言的 text/x-LANGUAGE_ID。

此笔记本正在使用内置编辑器来显示一些 Rust 代码：在内置 Monaco 编辑器中显示 Rust 代码的笔记本

要呈现替代的 mimetype，必须为该 mimetype 注册 NotebookRenderer。

笔记本渲染器

笔记本渲染器负责获取特定 mimetype 的输出数据，并提供该数据的渲染视图。由输出单元格共享的渲染器可以维护这些单元格之间的全局状态。渲染视图的复杂性范围可以从简单的静态 HTML 到动态的完全交互式小程序。在本节中，我们将探讨用于呈现代表 GitHub Issue 的输出的各种技术。

您可以使用我们 Yeoman 生成器中的样板快速入门。为此，请先使用以下命令安装 Yeoman 和 VS Code 生成器

npm install -g yo generator-code

然后，运行 yo code 并选择 New Notebook Renderer (TypeScript)。

如果您不使用此模板，则只需确保将 notebookRenderer 添加到扩展的 package.json 中的 keywords 中，并在扩展名称或描述中提及它的 mimetype，以便用户可以找到您的渲染器。

一个简单的、非交互式渲染器

通过贡献到扩展的 package.json 的 contributes.notebookRenderer 属性，可以为一组 mimetype 声明渲染器。此渲染器将使用 ms-vscode.github-issue-notebook/github-issue 格式的输入，我们假设某些已安装的控制器能够提供这种格式。

{
  "activationEvents": ["...."],
  "contributes": {
    ...
    "notebookRenderer": [
      {
        "id": "github-issue-renderer",
        "displayName": "GitHub Issue Renderer",
        "entrypoint": "./out/renderer.js",
        "mimeTypes": [
          "ms-vscode.github-issue-notebook/github-issue"
        ]
      }
    ]
  }
}

输出渲染器始终在与 VS Code 的其余 UI 分开的单个 iframe 中呈现，以确保它们不会意外干扰或导致 VS Code 速度变慢。此贡献指向一个“入口点”脚本，该脚本在需要呈现任何输出之前会被加载到笔记本的 iframe 中。您的入口点需要是一个单独的文件，您可以自己编写，也可以使用 Webpack、Rollup 或 Parcel 等打包器来创建。

加载时，您的入口点脚本应从 vscode-notebook-renderer 导出 ActivationFunction，以便在 VS Code 准备好渲染您的渲染器时渲染您的 UI。例如，这会将您的所有 GitHub 问题数据以 JSON 格式放入单元格输出中

import type { ActivationFunction } from 'vscode-notebook-renderer';

export const activate: ActivationFunction = context => ({
  renderOutputItem(data, element) {
    element.innerText = JSON.stringify(data.json());
  }
});

您可以在此处参考完整的 API 定义。如果您使用的是 TypeScript，您可以安装 @types/vscode-notebook-renderer，然后在 tsconfig.json 中的 types 数组中添加 vscode-notebook-renderer，以使这些类型在您的代码中可用。

为了创建更丰富的内容，您可以手动创建 DOM 元素，或者使用像 Preact 这样的框架并将其渲染到输出元素中，例如

import type { ActivationFunction } from 'vscode-notebook-renderer';
import { h, render } from 'preact';

const Issue: FunctionComponent<{ issue: GithubIssue }> = ({ issue }) => (
  <div key={issue.number}>
    <h2>
      {issue.title}
      (<a href={`https://github.com/${issue.repo}/issues/${issue.number}`}>#{issue.number}</a>)
    </h2>
    <img src={issue.user.avatar_url} style={{ float: 'left', width: 32, borderRadius: '50%', marginRight: 20 }} />
    <i>@{issue.user.login}</i> Opened: <div style="margin-top: 10px">{issue.body}</div>
  </div>
);

const GithubIssues: FunctionComponent<{ issues: GithubIssue[]; }> = ({ issues }) => (
  <div>{issues.map(issue => <Issue key={issue.number} issue={issue} />)}</div>
);

export const activate: ActivationFunction = (context) => ({
    renderOutputItem(data, element) {
        render(<GithubIssues issues={data.json()} />, element);
    }
});

在具有 ms-vscode.github-issue-notebook/github-issue 数据字段的输出单元格上运行此渲染器会得到以下静态 HTML 视图

Cell output showing rendered HTML view of issue

如果您有容器外部的元素或其他异步进程，可以使用 disposeOutputItem 来销毁它们。当输出被清除、单元格被删除以及在为现有单元格渲染新输出之前，会触发此事件。例如

const intervals = new Map();

export const activate: ActivationFunction = (context) => ({
    renderOutputItem(data, element) {
        render(<GithubIssues issues={data.json()} />, element);

        intervals.set(data.mime, setInterval(() => {
            if(element.querySelector('h2')) {
                element.querySelector('h2')!.style.color = `hsl(${Math.random() * 360}, 100%, 50%)`;
            }
        }, 1000));
    },
    disposeOutputItem(id) {
        clearInterval(intervals.get(id));
        intervals.delete(id);
    }
});

重要的是要记住，笔记本的所有输出都呈现在同一 iframe 中的不同元素中。如果您使用像 document.querySelector 这样的函数，请确保将其范围限定为您感兴趣的特定输出，以避免与其他输出冲突。在此示例中，我们使用 element.querySelector 来避免该问题。

交互式笔记本（与控制器通信）

假设我们想在单击渲染输出中的按钮后添加查看问题的评论的功能。假设控制器可以在 ms-vscode.github-issue-notebook/github-issue-with-comments mimetype 下提供带有评论的问题数据，我们可能会尝试预先检索所有评论并按如下方式实现它

const Issue: FunctionComponent<{ issue: GithubIssueWithComments }> = ({ issue }) => {
  const [showComments, setShowComments] = useState(false);

  return (
    <div key={issue.number}>
      <h2>
        {issue.title}
        (<a href={`https://github.com/${issue.repo}/issues/${issue.number}`}>#{issue.number}</a>)
      </h2>
      <img src={issue.user.avatar_url} style={{ float: 'left', width: 32, borderRadius: '50%', marginRight: 20 }} />
      <i>@{issue.user.login}</i> Opened: <div style="margin-top: 10px">{issue.body}</div>
      <button onClick={() => setShowComments(true)}>Show Comments</button>
      {showComments && issue.comments.map(comment => <div>{comment.text}</div>)}
    </div>
  );
};

这立即提出了一些警告。首先，即使在我们单击按钮之前，我们也在加载所有问题的完整评论数据。此外，即使我们只想显示更多数据，我们也需要控制器支持完全不同的 mimetype。

相反，控制器可以通过包含 VS Code 也将在 iframe 中加载的预加载脚本来为渲染器提供额外的功能。此脚本可以访问全局函数 postKernelMessage 和 onDidReceiveKernelMessage，这些函数可用于与控制器通信。

Diagram showing how controllers interact with renderers through the NotebookRendererScript

例如，您可以修改您的控制器 rendererScripts 以引用一个新文件，您可以在其中创建返回到扩展主机的连接，并公开一个供渲染器使用的全局通信脚本。

在您的控制器中

class Controller {
  // ...

  readonly rendererScriptId = 'my-renderer-script';

  constructor() {
    // ...

    this._controller.rendererScripts.push(
      new vscode.NotebookRendererScript(
        vscode.Uri.file(/* path to script */),
        rendererScriptId
      )
    );
  }
}

在您的 package.json 中，将您的脚本指定为渲染器的依赖项

{
  "activationEvents": ["...."],
  "contributes": {
    ...
    "notebookRenderer": [
      {
        "id": "github-issue-renderer",
        "displayName": "GitHub Issue Renderer",
        "entrypoint": "./out/renderer.js",
        "mimeTypes": [...],
        "dependencies": [
            "my-renderer-script"
        ]
      }
    ]
  }
}

在您的脚本文件中，您可以声明与控制器通信的通信函数

import 'vscode-notebook-renderer/preload';

globalThis.githubIssueCommentProvider = {
  loadComments(issueId: string, callback: (comments: GithubComment[]) => void) {
    postKernelMessage({ command: 'comments', issueId });

    onDidReceiveKernelMessage(event => {
      if (event.data.type === 'comments' && event.data.issueId === issueId) {
        callback(event.data.comments);
      }
    });
  }
};

然后您可以在渲染器中使用它。您需要确保检查控制器渲染脚本公开的全局变量是否可用，因为其他开发人员可能会在其他不实现 githubIssueCommentProvider 的笔记本和控制器中创建 github 问题输出。在这种情况下，我们仅在全局变量可用时显示 **加载评论** 按钮

const canLoadComments = globalThis.githubIssueCommentProvider !== undefined;
const Issue: FunctionComponent<{ issue: GithubIssue }> = ({ issue }) => {
  const [comments, setComments] = useState([]);
  const loadComments = () =>
    globalThis.githubIssueCommentProvider.loadComments(issue.id, setComments);

  return (
    <div key={issue.number}>
      <h2>
        {issue.title}
        (<a href={`https://github.com/${issue.repo}/issues/${issue.number}`}>#{issue.number}</a>)
      </h2>
      <img src={issue.user.avatar_url} style={{ float: 'left', width: 32, borderRadius: '50%', marginRight: 20 }} />
      <i>@{issue.user.login}</i> Opened: <div style="margin-top: 10px">{issue.body}</div>
      {canLoadComments && <button onClick={loadComments}>Load Comments</button>}
      {comments.map(comment => <div>{comment.text}</div>)}
    </div>
  );
};

最后，我们要设置与控制器的通信。当渲染器使用全局 postKernelMessage 函数发布消息时，将调用 NotebookController.onDidReceiveMessage 方法。要实现此方法，请附加到 onDidReceiveMessage 以侦听消息

class Controller {
  // ...

  constructor() {
    // ...

    this._controller.onDidReceiveMessage(event => {
      if (event.message.command === 'comments') {
        _getCommentsForIssue(event.message.issueId).then(
          comments =>
            this._controller.postMessage({
              type: 'comments',
              issueId: event.message.issueId,
              comments
            }),
          event.editor
        );
      }
    });
  }
}

交互式笔记本（与扩展主机通信）

假设我们想添加在单独的编辑器中打开输出项的功能。为了实现这一点，渲染器需要能够向扩展主机发送消息，然后扩展主机将启动编辑器。

在渲染器和控制器是两个单独的扩展的情况下，这将很有用。

在渲染器扩展的 package.json 中，将 requiresMessaging 的值指定为 optional，这允许您的渲染器在它可以访问和无法访问扩展主机的情况下工作。

{
  "activationEvents": ["...."],
  "contributes": {
    ...
    "notebookRenderer": [
      {
        "id": "output-editor-renderer",
        "displayName": "Output Editor Renderer",
        "entrypoint": "./out/renderer.js",
        "mimeTypes": [...],
        "requiresMessaging": "optional"
      }
    ]
  }
}

requiresMessaging 的可能值包括

always：需要消息传递。仅当渲染器是可以在扩展主机中运行的扩展的一部分时才使用它。
optional：当扩展主机可用时，渲染器使用消息传递会更好，但安装和运行渲染器不是必需的。
never：渲染器不需要消息传递。

首选后两个选项，因为这可以确保渲染器扩展可以移植到其他可能不一定有扩展主机的上下文中。

渲染器脚本文件可以按如下方式设置通信

import { ActivationFunction } from 'vscode-notebook-renderer';

export const activate: ActivationFunction = (context) => ({
  renderOutputItem(data, element) {
    // Render the output using the output `data`
    ....
    // The availability of messaging depends on the value in `requiresMessaging`
    if (!context.postMessage){
      return;
    }

    // Upon some user action in the output (such as clicking a button),
    // send a message to the extension host requesting the launch of the editor.
    document.querySelector('#openEditor').addEventListener('click', () => {
      context.postMessage({
        request: 'showEditor',
        data: '<custom data>'
      })
    });
  }
});

然后您可以在扩展主机中按如下方式使用该消息

const messageChannel = notebooks.createRendererMessaging('output-editor-renderer');
messageChannel.onDidReceiveMessage(e => {
  if (e.message.request === 'showEditor') {
    // Launch the editor for the output identified by `e.message.data`
  }
});

注意

为了确保您的扩展在传递消息之前在扩展主机中运行，请将 onRenderer:<您的渲染器 ID> 添加到您的 activationEvents，并在您的扩展的 activate 函数中设置通信。
并非所有渲染器扩展发送到扩展主机的消息都保证会传递。用户可能会在传递渲染器消息之前关闭笔记本。

支持调试

对于某些控制器（例如那些实现编程语言的控制器），允许调试单元格的执行可能是可取的。要添加调试支持，笔记本内核可以实现一个调试适配器，可以通过直接实现调试适配器协议（DAP），或者通过将协议委派和转换为现有的笔记本调试器（如“vscode-simple-jupyter-notebook”示例中所做的那样）。一个更简单的方法是使用现有的未修改的调试扩展，并在运行时转换 DAP 以满足笔记本的需求（如“vscode-nodebook”中所做的那样）。

示例

vscode-nodebook：由 VS Code 内置的 JavaScript 调试器和一些简单的协议转换提供的具有调试支持的 Node.js 笔记本
vscode-simple-jupyter-notebook：由现有的 Xeus 调试器提供的具有调试支持的 Jupyter 笔记本

12/11/2024