从 SVG 到 icnsKarabiner-Elements 应用图标v13 版的构建与一键更新指南【免费下载链接】Karabiner-ElementsKarabiner-Elements is a powerful tool for customizing keyboards on macOS项目地址: https://gitcode.com/gh_mirrors/ka/Karabiner-Elements本篇指南以 files/icons/v13/KarabinerElements/README.md 为骨架完整拆解 Karabiner-Elements 仓库中 v13 版 KarabinerElements 应用图标icns的更新流程如何在 Icon Composer 中导出设计稿、如何用一条make命令完成 iconset 生成、压缩与产物分发。读完本文你将掌握该仓库图标模块的目录组织、构建脚本create-icns.sh/optimize-image.sh的内部原理以及图标产物最终如何被 AppIconSwitcher 在运行时切换使用。一、背景仓库中图标文件的组织方式Karabiner-Elements 的图标资源统一存放在仓库根目录的 files/icons 下按设计版本分组目前包含三类设计目录v13/本文主角对应 002 编号图标Zabriskije/另一位设计师的版本对应 001 编号图标见 files/icons/Zabriskije/KarabinerElements/MakefileTamura/早期版本。每个版本目录内结构一致以v13/KarabinerElements/为例files/icons/v13/KarabinerElements/ ├── KarabinerElements.icon/ # Icon Composer 工程Assets icon.json │ ├── Assets/icon_512x5122x.png # 1024×1024 源图 │ └── icon.json # 工程描述文件 ├── exported/ │ ├── KarabinerElements.png # 从 Icon Composer 导出的 1024×1024 PNG │ └── KarabinerElements.icns # 构建产物 ├── Makefile # 一键构建脚本入口 └── karabiner.svg # Inkscape 矢量源文件根目录的 files/icons/Makefile 会递归遍历所有子目录中的 Makefile 并依次执行all: for f in find */ -name Makefile; do make -C dirname $$f; done因此在files/icons目录下运行一次make即可重建全部版本的图标。二、标准更新流程原文档的两步操作原文档 files/icons/v13/KarabinerElements/README.md 给出了最核心的更新步骤必须严格按顺序执行用 Icon Composer 打开工程并导出 PNG打开KarabinerElements.iconIcon Composer.app 是 macOS 上编辑.icon图标工程的工具然后将图片导出为exported/KarabinerElements.png。在终端运行make进入files/icons/v13/KarabinerElements/目录或直接在该目录打开终端执行make命令。make命令会读取exported/KarabinerElements.png自动完成 icns 生成、压缩与分发详见下文第三、四、五节。需要说明的是该流程依赖 macOS 自带工具链sips、iconutil、Icon Composer以及pngquant请在 macOS 环境下执行这也是整个仓库图标流程的前提。三、make 到底做了什么Makefile 逐行解析files/icons/v13/KarabinerElements/Makefile 内容非常精简共四步all: bash ../../scripts/create-icns.sh exported/KarabinerElements.png mv app.icns exported/KarabinerElements.icns # Copy files cp exported/KarabinerElements.icns ../../../../src/apps/share/Resources/icons/002-KarabinerElements.icns sips -z 128 128 exported/KarabinerElements.png --out ../../../../src/apps/share/Resources/icons/002-KarabinerElements.png bash ../../scripts/optimize-image.sh ../../../../src/apps/share/Resources/icons/002-KarabinerElements.png调用create-icns.sh以exported/KarabinerElements.png为输入生成app.icns生成细节见第四节重命名产物把生成的app.icns移动到exported/KarabinerElements.icns作为该版本的正式产物分发 icns将 icns 复制到共享图标目录src/apps/share/Resources/icons/002-KarabinerElements.icns。文件名前缀002-是图标编号同一目录下还存放着000-*、001-*等版本EventViewer、KarabinerElements、MultitouchExtension 三个应用各有编号共享目录的完整列表见 src/apps/share/Resources/icons生成并优化 128×128 PNG先用sips -z 128 128从 1024×1024 源图缩放出 128×128 的小尺寸 PNG用于菜单栏等场景再交给optimize-image.sh压缩。四、create-icns.sh从单张 1024×1024 PNG 生成完整 iconsetfiles/icons/scripts/create-icns.sh 是核心构建脚本其关键设计如下第一步收缩并回填画布保留安全边距sips --resampleHeightWidth 824 824 $ICON1024 --out app.iconset/shrunk.png sips --padToHeightWidth 1024 1024 app.iconset/shrunk.png --out app.iconset/icon_512x5122x.pngmacOS 会对图标四周进行圆角裁切因此脚本先把 1024×1024 的源图缩小到 824×824再用--padToHeightWidth透明填充回 1024×1024 画布。这样既保留了 1024×1024 的 Retina 分辨率又为系统圆角遮罩预留了安全边距避免重要图形被裁掉。第二步由基准图派生 10 个标准尺寸sips -z 16 16 app.iconset/icon_512x5122x.png --out app.iconset/icon_16x16.png sips -z 32 32 ... icon_16x162x.png sips -z 32 32 ... icon_32x32.png sips -z 64 64 ... icon_32x322x.png sips -z 128 128 ... icon_128x128.png sips -z 256 256 ... icon_128x1282x.png sips -z 256 256 ... icon_256x256.png sips -z 512 512 ... icon_256x2562x.png sips -z 512 512 ... icon_512x512.png覆盖从 16×16 到 512×5122x即 1024×1024的全部 iconset 尺寸满足 macOS 在不同 UI 场景下的显示需求。第三步压缩并打包optimize-image.sh app.iconset/*.png iconutil -c icns app.iconset先用压缩脚本处理 iconset 内全部 PNG再由 macOS 自带的iconutil将整个 iconset 打包成单一.icns文件即app.icns。打包完成后删除临时app.iconset目录。五、optimize-image.shpngquant 无损压缩files/icons/scripts/optimize-image.sh 负责对 PNG 做量化压缩要点如下仅处理.png后缀文件使用pngquant --skip-if-larger --ext .png --force--skip-if-larger保证压缩后若体积反而变大则保留原图--force允许原地覆盖连续执行两轮for i in 0 1进一步压榨体积压缩前后用stat -f %z对比字节数并打印before - after变化便于观察压缩收益。需要注意的是脚本中通过set e/set -e临时允许pngquant命令失败例如未安装或文件无需压缩时保证流程不中断。构建make时若未安装pngquant此步骤会静默跳过但不影响 icns 的生成。六、.icon 工程文件Icon Composer 的项目描述files/icons/v13/KarabinerElements/KarabinerElements.icon/icon.json 是 Icon Composer 的工程描述核心字段包括fill.automatic-gradient系统自动渐变填充色此处为蓝色extended-srgb:0.00000,0.53333,1.00000,1.00000groups[0].layers[0]图层引用了Assets/icon_512x5122x.png即 files/icons/v13/KarabinerElements/KarabinerElements.icon/Assets/icon_512x5122x.png并设置scale: 1.3放大绘制groups[0].shadow中性阴影透明度 0.5groups[0].translucency半透明效果值为 0.5supported-platforms.squares声明该图标面向 macOS 方形图标平台。可以看出.icon不是简单图片而是一个带图层、阴影、半透明与平台声明的组合工程——这也解释了为什么更新图标时要先用 Icon Composer 打开它重新导出 PNG而非直接替换图片文件。矢量设计源文件 files/icons/v13/KarabinerElements/karabiner.svgInkscape 工程图案为圆角深色底 白色 KEY 字样则用于在编辑器中修改设计并导出到工程。七、图标在应用中的运行时切换机制构建产物被复制到src/apps/share/Resources/icons/后应用在运行时按编号选择图标。相关调用链为src/apps/AppIconSwitcher/src/app_icon_utility.cpp 中的krbn_get_app_icon_number()读取图标配置并返回编号src/share/app_icon.hpp 中krbn::app_icon类解析 JSON 中的number字段示例格式为{number: 0}解析失败时回退到0配置文件路径定义在 src/share/constants.hpp#L104-L107 的get_system_app_icon_configuration_file_path()即/Library/Application Support/org.pqrs/config/karabiner_app_icon.json。结合三个版本 Makefile 中002-、001-的命名规律可以推断number0/1/2 分别对应仓库中不同设计师版本Tamura / Zabriskije / v13AppIconSwitcher 据此在运行时切换 Dock 图标。这样图标构建与运行时选择解耦——重新构建某个版本的 icns 并覆盖src/apps/share/Resources/icons/下的对应文件即可在不改动逻辑的情况下更新应用外观。八、实操清单与注意事项完整更新一次 v13 版 KarabinerElements 图标的可复现流程可选用 Inkscape 编辑 karabiner.svg导出 PNG 并更新KarabinerElements.icon工程内的Assets/icon_512x5122x.png在 macOS 上用 Icon Composer 打开KarabinerElements.icon导出到exported/KarabinerElements.png在files/icons/v13/KarabinerElements/目录执行make验证产物exported/KarabinerElements.icns与src/apps/share/Resources/icons/002-KarabinerElements.icns均已更新002-KarabinerElements.png为 128×128 压缩版。注意事项make必须在 macOS 上运行依赖sips、iconutil与 Icon Composer随 Xcode 提供pngquant缺失不影响 icns 生成但会跳过 PNG 压缩步骤步骤 1导出 PNG是步骤 2运行 make的前置条件跳过导出直接 make 会处理旧的 PNG若在files/icons根目录执行make会通过根 Makefile 级联重建所有版本的图标v13、Zabriskije、Tamura 等若希望应用切换到其他版本图标可通过系统配置karabiner_app_icon.json中的number字段选择实现见 src/share/app_icon.hpp。本文所有脚本与产物均可直接在仓库中查阅验证构建脚本、压缩脚本、v13 版 Makefile、共享图标目录 与 AppIconSwitcher 实现。【免费下载链接】Karabiner-ElementsKarabiner-Elements is a powerful tool for customizing keyboards on macOS项目地址: https://gitcode.com/gh_mirrors/ka/Karabiner-Elements创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考