VS Codeのエージェントモードを拡張するには、を試してください！

ドキュメントセレクター

拡張機能は、ドキュメントセレクターを使用して、言語、ファイルの種類、および場所に基づいて機能をフィルターできます。このトピックでは、ドキュメントセレクター、ドキュメントスキーム、および拡張機能の作成者が注意すべきことについて説明します。

ディスクにないテキストドキュメント

新しく作成されたドキュメントなど、すべてのテキストドキュメントがディスクに保存されているわけではありません。特に指定しない限り、ドキュメントセレクターは**すべて**のドキュメントタイプに適用されます。DocumentFilter の scheme プロパティを使用して、特定のスキームに絞り込むことができます。たとえば、ディスクに保存されているTypeScriptファイルの場合は { scheme: 'file', language: 'typescript' } となります。

ドキュメントセレクター

Visual Studio Code 拡張機能 API は、IntelliSenseのような言語固有の機能と、DocumentSelector タイプを通じてドキュメントセレクターを組み合わせています。これらは、機能を特定の言語に絞り込む簡単なメカニズムです。

以下のスニペットは、TypeScriptファイルにHoverProviderを登録しており、ドキュメントセレクターは typescript 言語識別子文字列です。

vscode.languages.registerHoverProvider('typescript', {
  provideHover(doc: vscode.TextDocument) {
    return new vscode.Hover('For *all* TypeScript documents.');
  }
});

ドキュメントセレクターは言語識別子以上のものになることができ、より複雑なセレクターは DocumentFilter を使用して、scheme と、pattern パスグロブパターンによるファイルの位置に基づいてフィルターできます。

vscode.languages.registerHoverProvider(
  { pattern: '**/test/**' },
  {
    provideHover(doc: vscode.TextDocument) {
      return new vscode.Hover('For documents inside `test`-folders only');
    }
  }
);

次のスニペットは、scheme フィルターを言語識別子と組み合わせて使用しています。untitled スキームは、まだディスクに保存されていない新しいファイル用です。

vscode.languages.registerHoverProvider(
  { scheme: 'untitled', language: 'typescript' },
  {
    provideHover(doc: vscode.TextDocument) {
      return new vscode.Hover('For new, unsaved TypeScript documents only');
    }
  }
);

ドキュメントスキーム

ドキュメントの scheme は見過ごされがちですが、重要な情報です。ほとんどのドキュメントはディスクに保存されており、拡張機能の作成者は通常、ディスク上のファイルを扱っていると想定します。たとえば、単純な typescript セレクターの場合、想定されるのは**ディスク上のTypeScriptファイル**です。しかし、この想定が緩すぎるシナリオがあり、その場合は { scheme: 'file', language: 'typescript' } のようなより明示的なセレクターを使用する必要があります。

この重要性は、機能がディスクからのファイル読み取り/書き込みに依存する場合に発揮されます。以下のスニペットを確認してください。

// 👎 too lax
vscode.languages.registerHoverProvider('typescript', {
  provideHover(doc: vscode.TextDocument) {
    const { size } = fs.statSync(doc.uri.fsPath); // ⚠️ what about 'untitled:/Untitled1.ts' or others?
    return new vscode.Hover(`Size in bytes is ${size}`);
  }
});

上記のホバープロバイダーは、ディスク上のドキュメントのサイズを表示したいと考えていますが、ドキュメントが実際にディスクに保存されているかどうかを確認していません。たとえば、新しく作成されてまだ保存されていない可能性があります。正しい方法は、プロバイダーがディスク上のファイルでのみ動作することをVS Codeに伝えることです。

// 👍 only works with files on disk
vscode.languages.registerHoverProvider(
  { scheme: 'file', language: 'typescript' },
  {
    provideHover(doc: vscode.TextDocument) {
      const { size } = fs.statSync(doc.uri.fsPath);
      return new vscode.Hover(`Size in bytes is ${size}`);
    }
  }
);

まとめ

ドキュメントは通常ファイルシステムに保存されますが、常にそうとは限りません。無題のドキュメント、Gitが使用するキャッシュされたドキュメント、FTPのようなリモートソースからのドキュメントなどがあります。機能がディスクアクセスに依存する場合は、必ず file スキームを持つドキュメントセレクターを使用してください。

次のステップ

VS Codeの拡張性モデルについて詳しく知るには、次のトピックを参照してください。

08/07/2025