文件選擇器

擴充功能可以根據語言、檔案類型和位置，透過文件選擇器（document selectors）來篩選其功能。本主題將討論文件選擇器、文件配置（schemes），以及擴充功能開發者應注意的事項。

非磁碟上的文字文件

並非所有文字文件都儲存在磁碟上，例如新建立的文件。除非另有說明，否則文件選擇器適用於所有文件類型。請使用 DocumentFilter 的 scheme 屬性來縮小特定配置的範圍，例如使用 { scheme: 'file', language: 'typescript' } 來指定儲存在磁碟上的 TypeScript 檔案。

文件選擇器

Visual Studio Code 擴充功能 API 透過 DocumentSelector 型別，將語言專屬功能（如 IntelliSense）與文件選擇器結合。這是一種將功能限縮於特定語言的簡易機制。

下方的程式碼片段為 TypeScript 檔案註冊了一個 HoverProvider，其文件選擇器為 typescript 語言識別碼字串。

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

文件選擇器不只能夠指定語言識別碼，更複雜的選擇器可以使用 DocumentFilter，透過 scheme 以及 pattern 路徑全域樣式（glob-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');
    }
  }
);

文件配置 (Document scheme)

文件的 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}`);
  }
});

上述的懸停提供者（hover provider）想要顯示磁碟上文件的容量大小，但它未檢查該文件是否真的儲存在磁碟上。例如，它可能是剛建立且尚未儲存的文件。正確的做法是告訴 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}`);
    }
  }
);

總結

文件通常儲存在檔案系統中，但並非總是如此：例如未命名文件（untitled）、Git 使用的快取文件、來自 FTP 等遠端來源的文件等。如果您的功能依賴磁碟存取，請務必使用帶有 file 配置的文件選擇器。

後續步驟

若要進一步了解 VS Code 的擴充性模型，請嘗試閱讀這些主題：

• 擴充功能資訊清單檔案 (Extension Manifest File) - VS Code package.json 擴充功能資訊清單檔案參考
• 貢獻點 (Contribution Points) - VS Code 貢獻點參考。