檔案圖示主題

Visual Studio Code 會在其整個使用者介面中於檔名旁顯示圖示，而擴充功能可以提供使用者能選擇的新檔案圖示集。

新增檔案圖示佈景主題

您可以使用圖示 (建議使用 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'...) 對應至圖示定義。圖示定義指定圖示的位置：這可以是一個影像檔案，或者是字型中的字符 (glyph)。

圖示定義

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。檔案的語言是根據語言貢獻中所定義的副檔名與檔名來評估。請注意，不考慮語言貢獻的「第一行比對 (first line match)」。
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 屬性值定義於此處。
大小應相對於使用圖示時的字型大小。因此，請一律使用百分比。

{
  "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

7/29/2026