仮想ドキュメント

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

TextDocumentContentProvider

このAPIは、URIスキームを要求することで機能します。プロバイダーは、その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 });
  })
);

上記のコードスニペットは、アクティブなエディターがあること、およびそのドキュメントが私たちのスキームのいずれかであることを確認します。これらのチェックは、コマンドが誰にでも利用可能（および実行可能）であるため必要です。次に、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ウィンドウで仮想ワークスペースが開かれている場合、これはリモートウィンドウと同様に、左下隅のリモートインジケーターのラベルで示されます。仮想ワークスペースガイドで、拡張機能がそのセットアップをサポートする方法を参照してください。