🚀 VS Code で で入手しましょう!

Notebook API

Notebook API を使用すると、Visual Studio Code 拡張機能は、ファイルをノートブックとして開き、ノートブックコードセルを実行し、さまざまなリッチでインタラクティブな形式でノートブック出力をレンダリングできます。 Jupyter Notebook や Google Colab のような一般的なノートブックインターフェースをご存知かもしれません。Notebook 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 は、ノートブックのシリアル化されたバイトを受け取り、それらのバイトを Markdown セルとコードセルのリストを含む NotebookData にデシリアライズする役割を担います。また、逆の変換、つまり NotebookData を受け取り、データを保存されるシリアル化されたバイトに変換する責任も負います。

サンプル

  • JSON Notebook Serializer: カスタム NotebookRenderer で JSON 入力を受け取り、プリティプリントされた JSON を出力する簡単なノートブックの例。
  • Markdown Serializer: Markdown ファイルをノートブックとして開き、編集します。

例

この例では、Jupyter Notebook 形式のファイルを、従来のファイル拡張子 .ipynb の代わりに .notebook 拡張子で表示するための簡略化されたノートブックプロバイダー拡張機能を構築します。

ノートブックシリアライザーは、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 キーワードを追加する必要があります。これにより、Visual Studio Code 内から <ViewTypeUpperCamelCased> タイプのノートブックを開くときの拡張機能の検出可能性が向上します。

サンプル

出力タイプ

出力は、テキスト出力、エラー出力、またはリッチ出力の 3 つの形式のいずれかである必要があります。カーネルは、セルの 1 回の実行に対して複数の出力を提供する場合があります。その場合、それらはリストとして表示されます。

テキスト出力、エラー出力、またはリッチ出力の「単純な」バリアント（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 フィールド。
  • NotebookRenderer が問題の完全にインタラクティブなビューを作成するために使用できる application/github-issue フィールド。

この場合、text/html ビューと text/x-json ビューは VS Code によってネイティブにレンダリングされますが、application/github-issue ビューは、その mimetype に登録された NotebookRenderer がない場合、エラーを表示します。

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) を選択します。

このテンプレートを使用しない場合は、拡張機能の package.json の keywords に notebookRenderer を追加し、拡張機能の名前または説明のどこかにその 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 などのバンドラーを使用して作成できます。

ロードされると、VS Code がレンダラーのレンダリング準備ができたときに UI をレンダリングするために、エントリポイントスクリプトは vscode-notebook-renderer から ActivationFunction をエクスポートする必要があります。たとえば、これにより、すべての 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 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>
  );
};

これにより、すぐにいくつかのフラグが立ちます。1 つは、ボタンをクリックする前でも、すべての問題の完全なコメントデータをロードしていることです。さらに、もう少しデータ​​を表示したいだけなのに、まったく異なる 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 issue 出力を作成する可能性があるためです。この場合、グローバルが利用可能な場合にのみ コメントをロード ボタンを表示します。

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

最後に、コントローラーへの通信を設定します。NotebookController.onDidReceiveMessage メソッドは、レンダラーがグローバル postKernelMessage 関数を使用してメッセージを投稿したときに呼び出されます。このメソッドを実装するには、メッセージをリッスンするために 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
        );
      }
    });
  }
}

インタラクティブノートブック (拡張機能ホストとの通信)

出力項目を別のエディター内で開く機能を追加したいと想像してください。これを可能にするには、レンダラーが拡張機能ホストにメッセージを送信できる必要があり、拡張機能ホストがエディターを起動します。

これは、レンダラーとコントローラーが 2 つの別々の拡張機能であるシナリオで役立ちます。

レンダラー拡張機能の 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: レンダラーはメッセージングを必要としません。

最後の 2 つのオプションが推奨されます。これにより、拡張機能ホストが必ずしも利用可能ではない他のコンテキストへのレンダラー拡張機能の移植性が確保されます。

レンダラースクリプトファイルは、次のように通信を設定できます。

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」サンプルで行われているように)。はるかに簡単なアプローチは、既存の変更されていないデバッグ拡張機能を使用し、「vscode-nodebook」で行われているように、ノートブックのニーズに合わせて DAP をその場で変換することです。

サンプル

  • vscode-nodebook: VS Code の組み込み JavaScript デバッガーといくつかの単純なプロトコル変換によって提供されるデバッグサポートを備えた Node.js ノートブック
  • vscode-simple-jupyter-notebook: 既存の Xeus デバッガーによって提供されるデバッグサポートを備えた Jupyter ノートブック
04/03/2025