仮想ドキュメント

テキスト ドキュメント コンテンツ プロバイダー 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 メニューについても繰り返されます。これはデフォルトで​​すべてのコマンドを表示します。

イベントと可視性

ドキュメント プロバイダーは 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 ウィンドウで開かれている場合、これはリモート ウィンドウと同様に、左下隅のリモート インジケーターのラベルで表示されます。仮想ワークスペース ガイドで、拡張機能がそのセットアップをサポートする方法を参照してください。