參加你附近的 ，瞭解 VS Code 中的 AI 輔助開發。

文件選擇器

擴充套件可以根據語言、檔案型別和位置透過文件選擇器過濾其功能。本主題討論文件選擇器、文件方案以及擴充套件作者應注意的事項。

不在磁碟上的文字文件

並非所有文字文件都儲存在磁碟上，例如，新建立的文件。除非另有說明，否則文件選擇器適用於所有文件型別。使用 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 模式根據 scheme 和檔案位置進行過濾

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 可擴充套件性模型的更多資訊，請嘗試以下主題

09/11/2025