ドキュメントセレクター
拡張機能は、言語、ファイルの種類、場所に基づいてドキュメントセレクターで機能をフィルタリングできます。このトピックでは、ドキュメントセレクター、ドキュメントスキーム、および拡張機能の作成者が注意すべき点について説明します。
ディスク上にないテキストドキュメント
新しく作成されたドキュメントなど、すべてのテキストドキュメントがディスクに保存されているわけではありません。特に指定しない限り、ドキュメントセレクターはすべてのドキュメントタイプに適用されます。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 パス glob-パターンによるファイルの位置に基づいてフィルタリングできます。
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 貢献ポイントのリファレンス