🚀 在

文件選取器

擴充功能可以根據文件選取器，依語言、檔案類型和位置篩選其功能。本主題討論文件選取器、文件結構描述，以及擴充功能作者應注意的事項。

不在磁碟上的文字文件

並非所有文字文件都儲存在磁碟上，例如，新建立的文件。除非另有指定，否則文件選取器會套用至所有文件類型。使用 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，透過 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');
    }
  }
);

文件結構描述

文件的結構描述經常被忽略，但它是一項重要的資訊。大多數文件都儲存在磁碟上，擴充功能作者通常假設他們正在處理磁碟上的檔案。例如，使用簡單的 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 提供者想要顯示磁碟上文件的大小，但它未能檢查文件是否實際儲存在磁碟上。例如，它可能是新建立的且尚未儲存。正確的方法是告訴 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 擴充性模型，請嘗試以下主題

02/06/2025