ドキュメントセレクター

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

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

すべてのテキストドキュメントがディスク上に保存されているわけではありません（例：新規作成されたドキュメント）。特に指定がない限り、ドキュメントセレクターはすべてのドキュメントタイプに適用されます。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 拡張機能モデルの詳細については、次のトピックを参照してください。

拡張機能マニフェストファイル - VS Code package.json 拡張機能マニフェストファイルの参照
貢献ポイント - VS Code 貢献ポイントのリファレンス。

4/8/2026