仮想ドキュメント

Text Document Content Provider API を使用すると、任意のソースから Visual Studio Code で読み取り専用ドキュメントを作成できます。ソースコードを含むサンプル拡張機能は、https://github.com/microsoft/vscode-extension-samples/blob/main/virtual-document-sample/README.md で入手できます。

TextDocumentContentProvider

この API は、プロバイダーがテキストコンテンツを返す URI スキームを要求することによって機能します。スキームはプロバイダーを登録するときに指定する必要があり、後で変更することはできません。同じプロバイダーを複数のスキームに使用でき、単一のスキームに複数のプロバイダーを登録できます。

vscode.workspace.registerTextDocumentContentProvider(myScheme, myProvider);

registerTextDocumentContentProvider を呼び出すと、登録を解除できるディスポーザブルが返されます。プロバイダーは、URI とキャンセルトークンとともに呼び出される provideTextDocumentContent 関数のみを実装する必要があります。

const myProvider = new (class implements vscode.TextDocumentContentProvider {
  provideTextDocumentContent(uri: vscode.Uri): string {
    // invoke cowsay, use uri-path as text
    return cowsay.say({ text: uri.path });
  }
})();

プロバイダーが仮想ドキュメントの URI を作成しないことに注意してください。その役割は、そのような URI が与えられた場合にコンテンツを提供することです。代わりに、コンテンツプロバイダーは、プロバイダーが常に考慮されるように、ドキュメントを開くロジックに組み込まれています。

このサンプルでは、エディターに表示される URI を作成する 'cowsay' コマンドを使用しています。

vscode.commands.registerCommand('cowsay.say', async () => {
  let what = await vscode.window.showInputBox({ placeHolder: 'cow say?' });
  if (what) {
    let uri = vscode.Uri.parse('cowsay:' + what);
    let doc = await vscode.workspace.openTextDocument(uri); // calls back into the provider
    await vscode.window.showTextDocument(doc, { preview: false });
  }
});

このコマンドは入力を求め、cowsay スキームの URI を作成し、URI のドキュメントを開き、最後にそのドキュメントのエディターを開きます。ステップ 3 のドキュメントを開くとき、プロバイダーはその URI のコンテンツを提供するように求められます。

これで、完全に機能するテキストドキュメントコンテンツプロバイダーが完成しました。次のセクションでは、仮想ドキュメントを更新する方法と、仮想ドキュメントに UI コマンドを登録する方法について説明します。

仮想ドキュメントの更新

シナリオによっては、仮想ドキュメントが変更される場合があります。それをサポートするために、プロバイダーは onDidChange イベントを実装できます。

vscode.Event 型は、VS Code でのイベントのコントラクトを定義します。イベントを実装する最も簡単な方法は、次のように vscode.EventEmitter を使用することです。

const myProvider = new (class implements vscode.TextDocumentContentProvider {
  // emitter and its event
  onDidChangeEmitter = new vscode.EventEmitter<vscode.Uri>();
  onDidChange = this.onDidChangeEmitter.event;

  //...
})();

イベントエミッターには fire メソッドがあり、ドキュメントで変更が発生したときに VS Code に通知するために使用できます。変更されたドキュメントは、fire メソッドへの引数として指定された URI によって識別されます。プロバイダーは、ドキュメントがまだ開いていると仮定して、更新されたコンテンツを提供するために再度呼び出されます。

これで、VS Code が仮想ドキュメントの変更をリッスンするために必要なことはすべてです。この機能を利用したより複雑な例を見るには、https://github.com/microsoft/vscode-extension-samples/blob/main/contentprovider-sample/README.md を参照してください。

エディターコマンドの追加

エディターアクションを追加して、関連付けられたコンテンツプロバイダーによって提供されるドキュメントのみを操作できます。これは、牛が言ったことを逆にするサンプルコマンドです。

// register a command that updates the current cowsay
subscriptions.push(
  vscode.commands.registerCommand('cowsay.backwards', async () => {
    if (!vscode.window.activeTextEditor) {
      return; // no editor
    }
    let { document } = vscode.window.activeTextEditor;
    if (document.uri.scheme !== myScheme) {
      return; // not my scheme
    }
    // get path-components, reverse it, and create a new uri
    let say = document.uri.path;
    let newSay = say
      .split('')
      .reverse()
      .join('');
    let newUri = document.uri.with({ path: newSay });
    await vscode.window.showTextDocument(newUri, { preview: false });
  })
);

上記のスニペットは、アクティブなエディターがあり、そのドキュメントがスキームの 1 つであることを確認します。これらのチェックが必要なのは、コマンドが誰でも利用可能 (および実行可能) であるためです。次に、URI のパスコンポーネントが反転され、それから新しい URI が作成され、最後にエディターが開かれます。

エディターコマンドをトップにするには、package.json に宣言的な部分が必要です。contributes セクションにこの構成を追加します。

"menus": {
  "editor/title": [
    {
      "command": "cowsay.backwards",
      "group": "navigation",
      "when": "resourceScheme == cowsay"
    }
  ]
}

これは、contributes/commands セクションで定義された cowsay.backwards コマンドを参照し、エディターのタイトルメニュー (右上隅のツールバー) に表示される必要があることを示しています。さて、それだけでは、コマンドがすべてのエディターに対して常に表示されることを意味します。これは、when 句が使用される理由です。アクションを表示するために満たす必要のある条件を記述します。このサンプルでは、エディター内のドキュメントのスキームが cowsay スキームである必要があると述べています。構成は、commandPalette メニューに対しても繰り返されます。これは、デフォルトですべてのコマンドを表示します。

イベントと可視性

ドキュメントプロバイダーは VS Code の第一級市民であり、そのコンテンツは通常のテキストドキュメントに表示され、ファイルなどと同じインフラストラクチャを使用します。ただし、それはまた、「あなたの」ドキュメントは非表示にできず、onDidOpenTextDocument および onDidCloseTextDocument イベントに表示され、vscode.workspace.textDocuments の一部などになることも意味します。すべての人のルールは、ドキュメントの scheme を確認し、ドキュメントに対して何かを実行するかどうかを決定することです。

ファイルシステム API

より柔軟性とパワーが必要な場合は、FileSystemProvider API をご覧ください。これにより、ファイル、フォルダー、バイナリデータ、ファイルの削除、作成などを含む完全なファイルシステムを実装できます。

ソースコードを含むサンプル拡張機能は、https://github.com/microsoft/vscode-extension-samples/tree/main/fsprovider-sample/README.md で入手できます。

VS Code がそのようなファイルシステムのフォルダーまたはワークスペースで開かれると、それを仮想ワークスペースと呼びます。仮想ワークスペースが VS Code ウィンドウで開かれている場合、これはリモートウィンドウと同様に、左下隅のリモートインジケーターのラベルで示されます。拡張機能がそのセットアップをサポートする方法については、仮想ワークスペースガイド を参照してください。