檔案圖示主題

Visual Studio Code 在其 UI 各處的檔案名稱旁顯示圖示，擴充功能可以貢獻新的檔案圖示集，供使用者選擇。

新增檔案圖示主題

您可以從圖示（最好是 SVG）和圖示字型建立自己的檔案圖示主題。例如，查看兩個內建主題：Minimal 和 Seti。

首先，建立一個 VS Code 擴充功能並新增 iconTheme 貢獻點。

{
  "contributes": {
    "iconThemes": [
      {
        "id": "turtles",
        "label": "Turtles",
        "path": "./fileicons/turtles-icon-theme.json"
      }
    ]
  }
}

id 是圖示主題的識別碼。它在設定中用作識別碼，因此請使其獨特且易於閱讀。label 顯示在檔案圖示主題選擇器下拉式選單中。path 指向擴充功能中定義圖示集的檔案。如果您的圖示集名稱遵循 *icon-theme.json 命名方案，您將在 VS Code 中獲得完成支援和懸停提示。

檔案圖示集檔案

檔案圖示集檔案是一個 JSON 檔案，包含檔案圖示關聯和圖示定義。

圖示關聯將檔案類型（'file'、'folder'、'json-file' ...）對應到圖示定義。圖示定義定義圖示的位置：可以是影像檔案或字型中的字形。

圖示定義

iconDefinitions 區段包含所有定義。每個定義都有一個 ID，將用於引用該定義。一個定義也可以被多個檔案關聯引用。

{
  "iconDefinitions": {
    "_folder_dark": {
      "iconPath": "./images/Folder_16x_inverse.svg"
    }
  }
}

上面的圖示定義包含一個識別碼為 _folder_dark 的定義。

支援以下屬性

iconPath：當使用 svg/png 時：影像的路徑。
fontCharacter：當使用字形字型時：要使用的字型中的字元。
fontColor：當使用字形字型時：用於字形的顏色。
fontSize：當使用字型時：字型大小。預設情況下，使用字型規格中指定的大小。應該是相對於父字型大小的相對大小（例如 150%）。
fontId：當使用字型時：字型的 ID。如果未指定，將選取字型規格區段中指定的第一個字型。

檔案關聯

圖示可以關聯到資料夾、資料夾名稱、檔案、檔案副檔名、檔案名稱和語言 ID。

此外，每個關聯都可以針對 'light' 和 'highContrast' 色彩佈景主題進行細化。

每個檔案關聯都指向一個圖示定義。

{
  "file": "_file_dark",
  "folder": "_folder_dark",
  "folderExpanded": "_folder_open_dark",
  "folderNames": {
    ".vscode": "_vscode_folder"
  },
  "fileExtensions": {
    "ini": "_ini_file"
  },
  "fileNames": {
    "win.ini": "_win_ini_file"
  },
  "languageIds": {
    "ini": "_ini_file"
  },
  "light": {
    "folderExpanded": "_folder_open_light",
    "folder": "_folder_light",
    "file": "_file_light",
    "fileExtensions": {
      "ini": "_ini_file_light"
    }
  },
  "highContrast": {}
}

file 是預設檔案圖示，適用於所有不符合任何副檔名、檔案名稱或語言 ID 的檔案。目前，檔案圖示定義定義的所有屬性都將被繼承（僅與字型字形相關，對 fontSize 有用）。
folder 是摺疊資料夾的資料夾圖示，如果未設定 folderExpanded，也適用於展開的資料夾。可以使用 folderNames 屬性關聯特定資料夾名稱的圖示。資料夾圖示是選填的。如果未設定，則不會顯示資料夾的圖示。
folderExpanded 是展開資料夾的資料夾圖示。展開的資料夾圖示是選填的。如果未設定，將顯示為 folder 定義的圖示。
folderNames 將資料夾名稱關聯到圖示。集合的鍵是資料夾名稱，可以選擇性地以單個父路徑段 (*) 作為前綴。不支援模式或萬用字元。資料夾名稱比對不區分大小寫。
folderNamesExpanded 將展開資料夾的資料夾名稱關聯到圖示。集合的鍵是資料夾名稱，可以選擇性地以單個父路徑段 (*) 作為前綴。不支援模式或萬用字元。資料夾名稱比對不區分大小寫。
rootFolder 是摺疊工作區根資料夾的資料夾圖示，如果未設定 rootFolderExpanded，也適用於展開的工作區根資料夾。如果未設定，則將為工作區根資料夾顯示為 folder 定義的圖示。
rootFolderExpanded 是展開工作區根資料夾的資料夾圖示。如果未設定，則將為展開的工作區根資料夾顯示為 rootFolder 定義的圖示。
rootFolderNames 將根資料夾名稱關聯到圖示。集合的鍵是資料夾名稱。不支援模式或萬用字元。根資料夾名稱比對不區分大小寫。
rootFolderNamesExpanded 將展開資料夾的根資料夾名稱關聯到圖示。集合的鍵是資料夾名稱。不支援模式或萬用字元。根資料夾名稱比對不區分大小寫。
languageIds 將語言關聯到圖示。集合中的鍵是在語言貢獻點中定義的語言 ID。檔案的語言是根據語言貢獻中定義的檔案副檔名和檔案名稱評估的。請注意，不考慮語言貢獻的「第一行比對」。
fileExtensions 將檔案副檔名關聯到圖示。集合中的鍵是檔案副檔名。副檔名是點後的檔案名稱段（不包含點）。具有多個點的檔案名稱（例如 lib.d.ts）可以比對多個副檔名；「d.ts」和「ts」。可以選擇性地在檔案副檔名名稱前加上單個父路徑段 (*)。副檔名比較不區分大小寫。
fileNames 將檔案名稱關聯到圖示。集合中的鍵是完整檔案名稱，不包含任何路徑段。可以選擇性地在檔案副檔名名稱前加上單個父路徑段 (*)。不支援模式或萬用字元。檔案名稱比對不區分大小寫。「fileName」比對是最強的比對，並且與檔案名稱關聯的圖示將優先於比對的 fileExtension 和比對的語言 ID 的圖示。

(*) 某些屬性鍵 (folderNames、folderNamesExpanded、fileExtensions、fileNames) 可以以單個父路徑段作為前綴。僅當資源的直接父資料夾與父路徑資料夾比對時，才會使用該圖示。這可用於為特定資料夾（例如 system）中的資源提供不同的外觀

  "fileNames": {
    "system/win.ini": "_win_ini_file"
  },

system/win.ini 表示關聯比對直接位於 system 資料夾中的名為 win.ini 的檔案

  "fileExtensions": {
    "system/ini": "_ini_file"
  },

system/ini 表示關聯比對直接位於 system 資料夾中的名為 *.ini 的檔案

檔案副檔名比對優先於語言比對，但弱於檔案名稱比對。具有父路徑段的比對優先於沒有相同種類段的比對。

帶有父路徑的檔案名稱比對 > 檔案名稱比對 > 帶有父路徑的檔案副檔名比對 > 檔案副檔名比對 > 語言比對 ...

light 和 highContrast 區段具有與剛才列出的相同的檔案關聯屬性。它們允許覆寫相應佈景主題的圖示。

字型定義

fonts 區段可讓您宣告要使用的任意數量的字形字型。您可以稍後在圖示定義中引用這些字型。如果圖示定義未指定字型 ID，則將使用第一個宣告的字型作為預設字型。

將字型檔案複製到您的擴充功能中並相應地設定路徑。建議使用 WOFF 字型。

將 'woff' 設定為格式。
weight 屬性值在此處定義。
style 屬性值在此處定義。
size 應相對於使用圖示的字型大小。因此，請始終使用百分比。

{
  "fonts": [
    {
      "id": "turtles-font",
      "src": [
        {
          "path": "./turtles.woff",
          "format": "woff"
        }
      ],
      "weight": "normal",
      "style": "normal",
      "size": "150%"
    }
  ],
  "iconDefinitions": {
    "_file": {
      "fontCharacter": "\\E002",
      "fontColor": "#5f8b3b",
      "fontId": "turtles-font"
    }
  }
}

檔案圖示主題中的資料夾圖示

當資料夾圖示足以指示資料夾的展開狀態時，檔案圖示主題可以指示檔案總管不要顯示預設資料夾圖示（旋轉三角形或「twisties」）。此模式透過在檔案圖示主題定義檔案中設定 "hidesExplorerArrows":true 來啟用。

語言預設圖示

語言貢獻者可以為語言定義圖示。

{
  "contributes": {
    "languages": [
      {
        "id": "latex",
        // ...
        "icon": {
          "light": "./icons/latex-light.png",
          "dark": "./icons/latex-dark.png"
        }
      }
    ]
  }
}

如果檔案圖示主題僅具有語言的通用檔案圖示，則會使用該圖示。

僅在以下情況下才會顯示語言預設圖示

檔案圖示主題具有特定的檔案圖示。例如，Minimal 沒有特定的檔案圖示，因此不使用語言預設圖示
檔案圖示主題不包含給定語言、檔案副檔名或檔案名稱的圖示。
檔案圖示主題未定義 "showLanguageModeIcons":false

在以下情況下始終顯示語言預設圖示

檔案圖示主題確實定義了 "showLanguageModeIcons":true

04/03/2025