全栈攻城狮

Appearance

文件图标主题开发 ​

文件图标主题替换资源管理器中文件和文件夹的图标。Material Icon Theme、VSCode Icons 等知名扩展都基于这一机制。

文件图标主题是什么 ​

文件图标主题是一份 JSON 文件，定义图标集合，并描述哪些扩展名/文件名/文件夹名使用哪个图标：

text
iconDefinitions    图标定义（名字 → 图标路径）
fileExtensions     扩展名 → 图标
fileNames          精确文件名 → 图标
folderNames        文件夹名 → 图标
languageIds        语言 ID → 图标

注册文件图标主题 ​

package.json 中声明：

json
{
  "contributes": {
    "iconThemes": [
      {
        "id": "myicons",
        "label": "My Icons",
        "path": "./icons/my-icons.json"
      }
    ]
  }
}

用户通过命令面板 Preferences: File Icon Theme 切换。

iconDefinitions 定义图标 ​

iconDefinitions 是图标库，每条定义一个图标名与来源：

json
{
  "iconDefinitions": {
    "_file": {
      "iconPath": "./icons/file.svg"
    },
    "_folder": {
      "iconPath": "./icons/folder.svg",
      "fontCharacter": "\\E5FF"
    },
    "_root_folder": {
      "iconPath": "./icons/root-folder.svg"
    },
    "_js": {
      "iconPath": "./icons/js.svg"
    },
    "_folder_open": {
      "iconPath": "./icons/folder-open.svg"
    }
  }
}

图标定义字段 ​

字段说明
iconPathSVG/PNG 文件路径（推荐 SVG）
fontCharacter字体图标字符编码
fontColor字体图标颜色

图标名可以任意命名，但 _folder、_file、_root_folder 三个名字有特殊含义，作为兜底图标。

预定义集合 ​

名称用途
_file无匹配规则时的默认文件图标
_folder默认文件夹图标
_root_folder工作区根文件夹图标
_folder_open展开状态的文件夹图标
_root_folder_open展开状态的根文件夹图标
_file_*可自定义任意后缀

文件扩展名映射 ​

fileExtensions 把扩展名映射到图标：

json
{
  "fileExtensions": {
    "js": "_js",
    "ts": "_ts",
    "json": "_json",
    "md": "_md",
    "py": "_py",
    "java": "_java"
  }
}

扩展名匹配规则 ​

json
{
  "fileExtensions": {
    "js": "_js",
    "jsx": "_react",
    "tsx": "_react",
    "d.ts": "_types"
  }
}
写法匹配
"js"app.js
"d.ts"app.d.ts（带点的复合扩展名）
"mjs"app.mjs

匹配按最长扩展名优先：app.d.ts 优先命中 d.ts 而非 ts。

文件名映射 ​

fileNames 匹配精确文件名（不含扩展名匹配例外，需写全名）：

json
{
  "fileNames": {
    "package.json": "_json_package",
    "tsconfig.json": "_tsconfig",
    "vite.config.ts": "_vite",
    "Dockerfile": "_docker",
    ".gitignore": "_gitignore"
  }
}

fileNames 的键是完整文件名，适用于 package.json、Dockerfile 这类有特殊含义的文件。

文件夹名映射 ​

folderNames 匹配文件夹名：

json
{
  "folderNames": {
    "src": "_folder_src",
    "lib": "_folder_lib",
    "node_modules": "_folder_node",
    "dist": "_folder_dist"
  }
}

文件夹展开状态通过 _folder_open 配合：

json
{
  "iconDefinitions": {
    "_folder_src": { "iconPath": "./icons/folder-src.svg" },
    "_folder_src_open": { "iconPath": "./icons/folder-src-open.svg" }
  },
  "folderNames": {
    "src": "_folder_src"
  },
  "folderNamesExpanded": {
    "src": "_folder_src_open"
  }
}

folderNamesExpanded 定义展开态的图标，未定义时沿用折叠态图标。

语言关联图标 ​

languageIds 按编辑器语言 ID 映射（覆盖扩展名映射）：

json
{
  "languageIds": {
    "javascript": "_js",
    "typescript": "_ts",
    "json": "_json",
    "markdown": "_md",
    "python": "_py",
    "html": "_html",
    "css": "_css"
  }
}

文件被打开后，语言 ID 映射生效。未打开的文件按扩展名匹配。

映射优先级 ​

text
fileNames（精确文件名）
  → fileExtensions（扩展名）
    → languageIds（当前打开的语言）
      → _file 兜底

完整示例：简易文件图标主题 ​

json
{
  "iconDefinitions": {
    "_file": { "iconPath": "./icons/file.svg" },
    "_folder": { "iconPath": "./icons/folder.svg" },
    "_folder_open": { "iconPath": "./icons/folder-open.svg" },
    "_root_folder": { "iconPath": "./icons/root-folder.svg" },
    "_root_folder_open": { "iconPath": "./icons/root-folder-open.svg" },
    "_js": { "iconPath": "./icons/javascript.svg" },
    "_ts": { "iconPath": "./icons/typescript.svg" },
    "_json": { "iconPath": "./icons/json.svg" },
    "_md": { "iconPath": "./icons/markdown.svg" },
    "_folder_src": { "iconPath": "./icons/folder-src.svg" },
    "_folder_src_open": { "iconPath": "./icons/folder-src-open.svg" }
  },
  "fileExtensions": {
    "js": "_js",
    "ts": "_ts",
    "json": "_json",
    "md": "_md"
  },
  "fileNames": {
    "package.json": "_json",
    "tsconfig.json": "_ts"
  },
  "folderNames": {
    "src": "_folder_src"
  },
  "folderNamesExpanded": {
    "src": "_folder_src_open"
  },
  "languageIds": {
    "javascript": "_js",
    "typescript": "_ts"
  }
}

SVG 图标编写规范 ​

文件图标通常是 16x16 的 SVG，建议遵循：

svg
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16">
  <rect x="0" y="0" width="16" height="16" fill="none"/>
  <path fill="#e37933" d="M2 1h8l4 4v10H2z"/>
  <path fill="#f7b731" d="M10 1v4h4z"/>
</svg>
  • 使用单一颜色或少量颜色，便于与其他主题图标协调
  • 保持视觉重量统一（笔画粗细、留白）
  • 用 fill 而非 fill-rule 复杂路径

颜色一致性 ​

同一主题内的图标应有统一的色板。推荐先定义调色板再逐一上色：

text
JS 黄    #f7df1e
TS 蓝    #3178c6
JSON 琥珀 #e37933
MD 灰    #4e4e4e
文件夹蓝 #90a4ff

测试图标主题 ​

命令面板 → Preferences: File Icon Theme 选择你的主题，然后：

  • 创建各种扩展名的文件验证映射
  • 打开文件夹/折叠文件夹验证展开态
  • 打开文件验证语言 ID 映射
  • 检查根文件夹图标

主题开发循环：改 JSON → 重载窗口（Ctrl+Shift+P → Reload Window）→ 查看效果。

与颜色主题的配合 ​

文件图标主题独立于颜色主题，用户可自由组合。图标 SVG 建议同时测试在亮色与暗色背景下的可见度：

json
{
  "iconDefinitions": {
    "_file": {
      "iconPath": "./icons/file.svg"
    }
  }
}

如果图标在深色背景下看不清，可以设计明暗两套或使用描边效果。

文件图标主题让资源管理器有"灵魂"。下一步扩展图标覆盖到产品 UI 元素，开发产品图标主题。