鸿蒙图标工具链 Andy-scy/harmonyos-ui-icons

harmonyos-ui-icons

DeepSeek Harness 技能包（bundle）+ 鸿蒙图标工具链装上之后，DSH 里的智能体在做 HarmonyOS / ArkTS 界面时会自动带上这套图标能力：图标素材 + 上色方案 + 动效方案 + 踩坑清单，全部在真机模拟器上验证过。

⚠️ 先做这一步：初始化（不跑就没有图标）

本仓库不含任何 SVG 文件。 Iconsax 的免费授权允许你把图标用在 App 里，但不允许把图标本体（含改过的版本）再分发出去，所以公开仓库里只放工具、不放图标。

装好之后的第一件事是跑初始化：

<skill-root> = 本技能根目录，通常长这样： <DSH_HOME>/profiles/<profile>/node_modules/harmonyos-ui-icons/skills/harmonyos-ui-icons
node <skill-root>/scripts/bootstrap.mjs

bootstrap.mjs 会：

1. 从官方 CDN https://cdn.iconsax.io 拉取 181 个精选图标 × 6 样式 = 1083 个 SVG，并现场解密
2. 基于这些静态 SVG 生成 3249 个内嵌 SMIL 的动效变体
3. 重新生成 templates/IconsaxCatalog.ets，保证目录和实际文件对得上

需要联网，大约 1 分钟。幂等——已经初始化过会直接跳过。

技能自己也知道这件事：它的 SKILL.md 把「Step 0 初始化」写成了硬性前置条件，一旦发现 assets/iconsax/ 为空，会先跑 bootstrap.mjs 再去拿图标。

| assets/iconsax/ 状态 | 要做什么 |
| 不存在 / 空目录 | 停下，先跑 scripts/bootstrap.mjs |
| 缺你需要的图标 | node scripts/fetch-icons.mjs --names <名字> --out assets/iconsax |
| 已就绪 | 直接开用 |

作为 DSH 技能包安装

这是一个标准的 DSH bundle：package.json 声明 dsh.bundle.patch， cordis.patch.yml 里只新增一行，挂载 DSH 自带的 @deepseek-ai/dsh-skill-filesystem，把本包携带的 skills/ 目录注册成技能根。

cordis.patch.yml —— 纯新增，不改写/不冒用任何已有 entry id
- insert:
- id: harmonyos-ui-icons-skill-filesystem
name: '@deepseek-ai/dsh-skill-filesystem'
config:
providerName: harmonyos-ui-icons
includeDefaultRoots: false
bundledSkillDir: !!js ... # 从安装后的包身份解析到本包的 skills/

安装方式任选：

A. 通过 DSH 的插件管理器（推荐，走 plugin_manager install_bundle）

B. 手动装进某个配置档

在配置档目录里（<DSH_HOME>/profiles/<profile>）
pnpm add harmonyos-ui-icons # 或 "harmonyos-ui-icons": "git+https://github.com/Andy-scy/harmonyos-ui-icons.git"
然后把 "harmonyos-ui-icons" 加进该配置档 package.json 的 dsh.profile.bundles

C. 只想用技能本体（不装 bundle）

把 skills/harmonyos-ui-icons/ 整个目录拷进技能的搜索路径即可，比如 <DSH_HOME>/skills/harmonyos-ui-icons/ 或项目里的 .dsh/skills/harmonyos-ui-icons/。

三种方式装完之后都要跑一次 scripts/bootstrap.mjs。

装好之后，在 DSH 里只要提到 ArkTS / ArkUI / 鸿蒙页面 / 组件 / TabBar / "加个图标" / "做个鸿蒙界面"，技能会自动加载，带着这套图标库和文档出场。

这是什么

鸿蒙 App 做界面绕不开图标。这个包解决四件事：

| 🎨 图标素材 | 181 个常用 UI 图标 × 6 种样式 = 1083 个 SVG（初始化后拉到本地，已解密），拷进 rawfile/ 就能用 |
| ✨ 动效图标 | 3249 个内嵌 SMIL 的动效变体（浮动 / 呼吸 / 摇摆），ArkUI 的 Image 组件原生就播，零依赖 |
| 🧩 ArkTS 模板 | IconsaxIcon / Tint / IconsaxCatalog 三个文件，过了真实编译 + 实机运行 |
| 📚 避坑文档 | ArkUI 的 SVG 能力边界、上色两条路线、授权红线、12 条实机踩坑清单 |

图标来自 Iconsax 的免费授权范围（7,140 个静态图标中的 181 个常用款）。
包里同时带完整的 7,140 个免费图标索引和下载脚本，需要冷门图标时一条命令就能拉。

三句话讲清怎么用

1. 拷图标：assets/iconsax//<name>.svg → 你的 entry/src/main/resources/rawfile/iconsax/
2. 必须上色：Iconsax 的 SVG 全是白色。填充型（bold/bulk/outline）用 Image.fillColor()，描边型（linear/twotone/broken）用 Image.colorFilter(乘法矩阵)
3. 要动效不用买 Lottie：bootstrap.mjs 已经生成好动效变体；想要别的效果就跑 scripts/make-animated-svg.mjs 往 SVG 里注入 SMIL

快速开始

① 初始化（拉取 + 解密 + 生成动效）
node skills/harmonyos-ui-icons/scripts/bootstrap.mjs

② 想要更多图标（总共 1101 个名字可选）
cd skills/harmonyos-ui-icons
node scripts/fetch-icons.mjs --search chat
node scripts/fetch-icons.mjs --list-categories
node scripts/fetch-icons.mjs --out <工程>/entry/src/main/resources/rawfile/iconsax \
--names home,user,setting --styles bold,linear,twotone

③ 生成别的动效变体
node scripts/make-animated-svg.mjs \
--in assets/iconsax \
--out assets/iconsax-anim \
--effects float,pulse,spin,wiggle,beat

在页面里用：

拷三个模板进工程
cp skills/harmonyos-ui-icons/templates/Tint.ets <工程>/entry/src/main/ets/common/
cp skills/harmonyos-ui-icons/templates/IconsaxIcon.ets <工程>/entry/src/main/ets/components/
cp skills/harmonyos-ui-icons/templates/IconsaxCatalog.ets <工程>/entry/src/main/ets/model/

import { IconsaxIcon } from '../components/IconsaxIcon';
import { IconsaxCatalog } from '../model/IconsaxCatalog';

@Entry
@Component
struct Index {
private style: string = 'linear';
@State tint: string = '#182431';

build() {
Row({ space: 16 }) {
IconsaxIcon({
rawfile: IconsaxCatalog.rawfilePath('home', this.style),
icSize: 24,
icTint: this.tint,
strokeArtwork: IconsaxCatalog.isStrokeStyle(this.style) // ← 关键，别写死 })
IconsaxIcon({
rawfile: IconsaxCatalog.rawfilePath('user', this.style),
icSize: 24,
icTint: this.tint,
strokeArtwork: IconsaxCatalog.isStrokeStyle(this.style)
})
}
}
}

效果

在 HarmonyOS 6.0.1 (API 21) 模拟器上实机运行：

| 填充型 bold → fillColor | 描边型 twotone → colorFilter |
| bold | twotone |

| SMIL 动效帧差（确实在动） | Lottie 播放 |
| smil | lottie |

关键结论（都是实测出来的）

1. ArkUI 原生支持 SVG，也原生支持 SVG 内嵌动画

Image 从 API 7 起就支持 svg，支持范围是 SVG 1.1 的子集。
动画方面，官方明确支持 <animate> 和 <animateTransform>：

当前仅支持单个元素的属性动画或者变形动画，不支持元素间动画嵌套。

这就意味着：「会动的图标」根本不需要引入 Lottie 之类的库，往免费静态 SVG 里塞 SMIL 就完事。单次动效播完还会触发 Image.onFinish()。

2. 上色必须分两条路（最容易翻车的地方）

| 接口 | 文档原文 | 适用 |
| fillColor(color) | 「替换SVG图片中所有可绘制元素的填充颜色」 | 填充型图稿 |
| colorFilter(矩阵) | 「SVG 类型的图源只有设置了 stroke 属性（无论是否有值）才会生效」 | 描边型图稿 |

而 Iconsax 的 6 种样式正好分成两派，所以要靠 IconsaxCatalog.isStrokeStyle() 分流。
详见 references/arkui-svg-capability.md。

3. 关于 Iconsax 的「动效图标」

Iconsax 官网那 983 个动效图标是 Pro 付费专属（Lottie 格式），免费授权里没有，而且授权也不允许再分发。所以：

- ❌ 本包没有任何 Iconsax 官方动效文件
- ✅ 本包的 3249 个动效 SVG 是用 make-animated-svg.mjs 给免费静态图标注入 SMIL 生成的

五条必须记住的规则

| # | 规则 |
| 1 | 图标是白色的，必须运行时上色，否则浅色主题下完全看不见 |
| 2 | 填充型用 fillColor，描边型用 colorFilter，一套代码打不了天下 |
| 3 | 自定义组件的 @Prop 不能叫 scale/size/rotate/translate，会撞 CustomComponent；本库统一 ic 前缀 |
| 4 | 工程路径不能含中文，hvigor 会直接拒绝构建 |
| 5 | ArkUI 的 SVG 解析器不认 CSS（/class）和 <text> |

完整 12 条见 references/pitfalls.md。

目录结构

harmonyos-ui-icons/ ← npm 包 = DSH bundle ├─ package.json dsh.bundle.patch + dsh.compatibility.dshReleases ├─ cordis.patch.yml 一行 insert，挂载 dsh-skill-filesystem ├─ lib/index.js resolveSkillRoot() ├─ icon.svg 插件管理器显示的图标 ├─ locale/{en,zh}.json 插件管理器显示的标题与描述 ├─ skills/ │ └─ harmonyos-ui-icons/ ← 技能本体 │ ├─ SKILL.md │ ├─ assets/ ⚠️ 全部由 bootstrap.mjs 生成，不进版本库 │ │ └─ README.md 说明为什么图标不在仓库里 │ ├─ templates/ ArkTS 模板（Tint / IconsaxIcon / IconsaxCatalog） │ ├─ catalog/ │ │ ├─ iconsax-free-index.json 全部 7,140 个免费图标索引（1101 名字 / 34 类目） │ │ └─ curated-names.json 精选的 181 个图标名 │ ├─ scripts/ │ │ ├─ bootstrap.mjs ★ 首次使用必跑 │ │ ├─ fetch-icons.mjs 从官方 CDN 按需拉取 + 解密 │ │ └─ make-animated-svg.mjs 给静态 SVG 批量注入 SMIL │ └─ references/ │ ├─ arkui-svg-capability.md ArkUI 对 SVG / 动效 / Lottie 的能力边界 │ ├─ license.md 授权要点与红线 │ └─ pitfalls.md 12 条实机踩坑清单 ├─ examples/ 契约校验 + ArkTS 模板编译验证脚本 └─ docs/ ├─ COMPATIBILITY.md 兼容性声明与验证依据 ├─ feasibility-report.md 完整可行性调查报告 └─ screenshots/ 实机截图

6 种样式：bold bulk broken linear outline twotone 5 种内置动效：float（浮动） pulse（呼吸） spin（转一圈·单次） wiggle（摇摆） beat（心跳）

验证记录

不是只写文档 —— 契约和模板代码都过了真实校验：

Bundle 契约（node examples/validate-bundle.mjs，38/38 通过）：

| 验证项 | 结果 |
| manifest 字段（含 exports["./package.json"]、icon 体积、兼容性声明） | ✅ |
| patch 形状：单个 insert、无改写行、entry id 为插件自有 | ✅ |
| !!js 表达式按 loader 的真实作用域求值并解析出目录 | ✅ |
| resolveSkillRoot() 找到自带技能、SKILL.md frontmatter 合规 | ✅ |

ArkTS 模板（examples/verify-templates.ps1）：

| 验证项 | 结果 |
| 三个模板塞进真实工程编译 | ✅ BUILD SUCCESSFUL |
| 填充型分支（fillColor） | ✅ 蓝色实心图标正确渲染 |
| 描边型分支（colorFilter） | ✅ 蓝色线框图标正确渲染，双色调保留 |
| SMIL 动效 SVG | ✅ 帧间像素差 4.56%，确实在动 |
| 单次动效 + onPlayed 回调 | ✅ 实机日志显示回调真的触发 |
| @Prop icSize: number \| string 联合类型 | ✅ '36vp' 正常渲染 |
| @ohos/lottie 播放 Bodymovin JSON | ✅ 25 fps 正常播放 |

环境：DevEco Studio 26.0.0 · HarmonyOS 6.0.1 (API 21) 模拟器 · DSH 0.2.0-rc.2 · 编译目标 compatibleSdkVersion 5.0.0(12)

兼容性声明与依据见 docs/COMPATIBILITY.md。

授权（重要，用之前扫一眼）

本包的代码（lib/ scripts/ templates/ references/ SKILL.md 等）：MIT，随便用。

图标来自 Iconsax，适用其 Free License。安装后由 bootstrap.mjs 从官方 CDN 拉取，不随包分发——这正是因为授权要求：

- ✅ 个人 + 商用，不限量，可修改，不需要署名
- ✅ 明确允许「嵌入你开发的移动 App」
- ❌ 禁止把图标本体（或改过的版本）当素材再分发 / 转售 / 传素材站
- ❌ 从其它非官方站点拿图标是不被允许的，必须从 iconsax.io 或官方渠道获取
- ❌ 交付 App 二进制没问题，别把图标源文件打包给客户
- ⚠️ 官网那 983 个动效图标是 Pro 付费资产，免费授权不含，也不允许再分发

也就是说：把图标用在你自己的 App 里完全合规；把图标打包成「图标库」再公开分发是不合规的。
本包刻意不带图标，就是这个原因 —— 请让使用者自己从官方源初始化。

详见 skills/harmonyos-ui-icons/references/license.md 与 NOTICE.md。

如果你 fork 了这个仓库

不要把 assets/iconsax/ 或 assets/iconsax-anim/ 提交上去。
它们已经写进 .gitignore（用的是跨层级匹配 */assets/iconsax/），正常操作不会被误传。

致谢

- 图标：Iconsax by Manuel Rovira
- Lottie 运行时：OpenHarmony-TPC/lottie（MIT）
- ArkUI 能力边界参考 OpenHarmony 官方文档仓 openharmony/docs