笔记本 API

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

笔记本的组成部分

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

笔记本中的单元格由 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 文件。

示例

在这个示例中，我们为查看具有 .notebook 扩展名（而不是其传统文件扩展名 .ipynb）的 Jupyter 笔记本格式中的文件构建了一个简化的笔记本提供者扩展。

笔记本序列化器在 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 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 的扩展与它的序列化器分开发布，请将 notebookKernel<ViewTypeUpperCamelCased> 这样的条目添加到其 package.json 中的 keywords 中。例如，如果您发布了 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 字段上多个属性的丰富输出

包含 Issue 的格式化视图的 text/html 字段。
包含机器可读视图的 text/x-json 字段。
NotebookRenderer 可以使用它来创建 Issue 的完全交互式视图的 application/github-issue 字段。

在这种情况下，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 可以呈现以下 mimetype

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

VS Code 将在内置编辑器中将这些 mimetype 呈现为代码

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"
        ]
      }
    ]
  }
}

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

加载后，您的入口点脚本应从 vscode-notebook-renderer 导出 ActivationFunction，以便在 VS Code 准备好渲染您的渲染器时渲染您的 UI。例如，这将把您所有 GitHub Issue 数据作为 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 媒体类型下提供带有评论的问题数据，我们可以尝试预先检索所有评论并按如下方式实现

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>
  );
};

这立即引发了一些问题。首先，我们在点击按钮之前就加载了所有问题的完整评论数据。此外，即使我们只是想显示更多数据，我们也需要对完全不同的媒体类型进行控制器支持。

相反，控制器可以通过包含一个预加载脚本，让 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);
      }
    });
  }
};

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

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`
  }
});

注意

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

支持调试

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

示例

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

10/29/2024