仮想ドキュメント

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 を呼び出すと、登録を元に戻すことができる disposable が返されます。プロバイダーは、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 });
  })
);

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

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

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

これは contributes/commands セクションで定義された cowsay.backwards コマンドを参照し、エディターのタイトルメニュー（右上のツールバー）に表示されるべきだと指定しています。これだけでは、コマンドが常にすべてのエディターに表示されることになります。そのために when 句が使用されます。これは、アクションを表示するために満たされるべき条件を記述します。このサンプルでは、エディター内のドキュメントのスキームが cowsay スキームでなければならないと指定しています。この設定は commandPalette メニューでも繰り返されます。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ウィンドウで開かれている場合、リモートウィンドウと同様に、左下のリモートインジケーターにラベルで表示されます。拡張機能がこの設定をサポートする方法については、仮想ワークスペースガイドを参照してください。