🚀 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.');
  }
});

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

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 の拡張機能モデルの詳細については、以下のトピックをお試しください。

04/03/2025