# HarmonyOS-Skill

**Repository Path**: dered/harmony-os-skill

## Basic Information

- **Project Name**: HarmonyOS-Skill
- **Description**: 鸿蒙应用实际开发实践总结出来的 skill
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HarmonyOS NEXT 开发 Skill 库（AI Coding 友好）

> 一套从实战项目沉淀的 **HarmonyOS NEXT 开发 skill 集合**，覆盖 ArkUI 状态管理坑 / 桌面服务卡片 / IAP / 测试 / 应用市场上架等核心场景。每个 skill 都是「**问题场景 + 反模式 + 正确代码模板 + 验证方法**」的完整知识包。
>
> **用 AI 写鸿蒙 App？把本仓库 clone 到你项目根目录的 `.claude/skills/` 或类似位置，Claude Code / 其他 AI 助手能直接消费这些知识 — 帮你少走 N 次试错弯路。**

## 已实践的应用

- **潮玩展柜**（潮玩手办数字展柜 App）— 鸿蒙应用市场已上架
  - 用户拍照 → AI 端侧抠图 → 数字展柜展示 → 桌面服务卡片
  - 8 款展柜风格 / 4 套主题 / 5 级等级系统 / IAP 买断付费
  - **欢迎在鸿蒙应用市场搜索「潮玩展柜」下载体验**，给作者一些反馈或好评

## Skill 索引（24 个）

### ArkUI 状态管理（4）— 状态追踪断链的常见坑

| Skill | 适用场景 |
|-------|---------|
| [arkui-observed-objectlink-chain](skills/arkui-observed-objectlink-chain/SKILL.md) | 对象数组元素属性变化必须 @Observed + @ObjectLink 全链路；@Prop 会断链 |
| [arkui-builder-param-trap](skills/arkui-builder-param-trap/SKILL.md) | @Builder 字符串参数中转切断 @State / @LocalStorageProp 追踪 |
| [arkui-foreach-key](skills/arkui-foreach-key/SKILL.md) | ForEach key 拼对象自身字段 vs 绝不拼全局状态（整列闪烁） |
| [arkui-toggle-ison-oneway](skills/arkui-toggle-ison-oneway/SKILL.md) | Toggle isOn 单向输入，onChange 必须显式赋值才能持久化 |

### ArkUI UI 模式（5）

| Skill | 适用场景 |
|-------|---------|
| [arkui-bindsheet-multi-content](skills/arkui-bindsheet-multi-content/SKILL.md) | bindSheet 多内容必须拆多节点（单 bindSheet 切多组件状态机错配） |
| [arkui-immersive-statusbar](skills/arkui-immersive-statusbar/SKILL.md) | 沉浸式状态栏完整方案（背景延伸 + 内容避让 + 真·物理沉浸 W12 演进） |
| [arkui-bindcontextmenu-preview](skills/arkui-bindcontextmenu-preview/SKILL.md) | 长按菜单 + 大图预览 4 坑（预览卡顿 / Image 吞长按 / onClick / 双层框） |
| [arkui-svg-hollow-icon](skills/arkui-svg-hollow-icon/SKILL.md) | 单色 SVG 染色 fillColor 会填实空心，须 evenodd 双同心圆几何镂空 |
| [arkui-scroll-short-content](skills/arkui-scroll-short-content/SKILL.md) | Scroll 把短内容下推致间距不一致，constraintSize minHeight 100% 根治 |

### ArkUI 设计令牌（2）— 全 App 视觉一致性

| Skill | 适用场景 |
|-------|---------|
| [arkui-font-token-system](skills/arkui-font-token-system/SKILL.md) | 字体令牌库（8 档语义令牌），禁裸 fontSize + 长文档层级治理 |
| [arkui-cta-color-tokens-agc-contrast](skills/arkui-cta-color-tokens-agc-contrast/SKILL.md) | CTA 配色令牌（浅彩底+同色系深字）+ AGC 审核不硬卡对比度实证 |

### 桌面服务卡片（3）

| Skill | 适用场景 |
|-------|---------|
| [harmonyos-form-transparent](skills/harmonyos-form-transparent/SKILL.md) | 透明背板卡片 5 件套（form_config / 根容器 / textColor / AGC 申请 / 手动签名） |
| [harmonyos-form-image-passing](skills/harmonyos-form-image-passing/SKILL.md) | 跨进程图片 fd + memory:// 协议（沙箱隔离的官方做法） |
| [harmonyos-form-refresh-strategy](skills/harmonyos-form-refresh-strategy/SKILL.md) | 卡片刷新整体范式（主动 push + 被动 onUpdate + 点击交互） |

### 系统能力 + 商业化（5）

| Skill | 适用场景 |
|-------|---------|
| [harmonyos-iap-integration](skills/harmonyos-iap-integration/SKILL.md) | IAP Kit 应用内购买（双协议 / 三命名 / Profile 重生成 / 沙盒） |
| [harmonyos-motion-kit-reachability](skills/harmonyos-motion-kit-reachability/SKILL.md) | 智感握姿（holdingHand + operatingHand 双 API 接入） |
| [harmonyos-core-vision-segmentation](skills/harmonyos-core-vision-segmentation/SKILL.md) | Core Vision Kit 端侧 AI 抠图（完全离线零成本） |
| [harmonyos-sharekit-sandbox](skills/harmonyos-sharekit-sandbox/SKILL.md) | ShareKit 系统分享沙箱图片（show 必须传 context 授权 URI） |
| [harmonyos-zlib-dir-backup](skills/harmonyos-zlib-dir-backup/SKILL.md) | @ohos.zlib 直接压缩目录（一行打包整个文件树） |

### 工程实践（3）

| Skill | 适用场景 |
|-------|---------|
| [arkts-strict-mode-rules](skills/arkts-strict-mode-rules/SKILL.md) | ArkTS 严格模式编码红线（11 条高频踩坑） |
| [harmonyos-real-device-build](skills/harmonyos-real-device-build/SKILL.md) | 真机打包 SOP（手动签名 + release hap + assembleApp） |
| [harmonyos-hypium-integration-test](skills/harmonyos-hypium-integration-test/SKILL.md) | hypium 测试体系（4 个核心陷阱） |

### 应用上架（2）

| Skill | 适用场景 |
|-------|---------|
| [huawei-appgallery-submission](skills/huawei-appgallery-submission/SKILL.md) | 华为应用市场提审完整清单 |
| [huawei-app-filing-vs-icp](skills/huawei-app-filing-vs-icp/SKILL.md) | APP 备案 vs ICP 备案 + 软著「非必选」权威结论 |

## 怎么用

### 方式 1：让 AI 助手直接消费

把仓库 clone / 拷贝到你的鸿蒙项目，让 AI 在写代码时主动检索：

```bash
git clone https://gitee.com/chen_jeff/harmony-os-skill.git
# 或
cd your-harmonyos-project
git submodule add https://gitee.com/chen_jeff/harmony-os-skill.git .skills
```

然后告诉 AI（如 Claude Code）：

> 我在写鸿蒙桌面服务卡片，刷新失败但 build() 跑了，参考 `.skills/skills/` 找找有没有相关 skill。

AI 会自动加载 `arkui-builder-param-trap` 等相关 skill 给你正确方案。

### 方式 2：人肉查阅

每个 skill 是独立的 markdown 文档，遇到问题时直接搜对应主题。所有 skill 结构一致：

```
何时使用此 skill → 核心结论 → 反例 ❌ → 正确做法 ✅ → 验证方法 → 相关 skill → 参考资料
```

## Skill 编写规范

每个 skill 文件用 frontmatter 标记，AI 能用 description 字段判断何时触发：

```markdown
---
name: <skill-slug>
description: <一句话描述场景与价值>
---
```

欢迎社区贡献新的 skill 或修正现有内容。

## 为什么需要这套 skill

HarmonyOS NEXT 处于快速迭代期，**官方文档与 AI 训练库经常不同步**：
- 训练库截止时间之前的旧 API 行为，AI 经常推测错（如 `consumeOwnedPurchase` 已改名 `finishPurchase`）
- 官方文档关键约束藏在末尾一句话（如"必须手动签名"），AI 不读到容易遗漏
- 主流社区资料质量参差（CSDN 旧贴 / 商业推广 / 一手实测 混在一起）

直接让 AI 在没有参考资料时写鸿蒙代码，常见以下症状：
- 状态追踪断链问题（@Builder 参数中转 / @Prop 剥离代理）反复试错 6-12 次都找不到根因
- 桌面卡片 5 件套缺手动签名那一件，5 次失败定位不到
- IAP 接入卡在协议没签 / Profile 没重生成几天
- 提审材料以为软著必备，去申请 30+ 工作日

**本仓库的目的**：把这些已经踩过的坑、查过的官方文档、试过的方案沉淀成 AI 可直接消费的 skill，让你 / 你团队的下一个鸿蒙项目少走弯路。

## 项目背景

skill 集合主要来自一个独立开发者从 0 到 1 做的鸿蒙原生 App（潮玩展柜）的 12 周开发实战（上架后持续迭代）：
- 472 个测试用例真机全绿
- 20 条开发铁律 / 60+ bug 记录原始材料
- 横跨 ArkUI / 桌面卡片 / Core Vision Kit / IAP / Motion Kit / ShareKit / Account Kit 等多模块
- v1.0.0 上架后的 W12 大版本（UI / 动画 / 设计令牌 / 交互打磨）经验持续沉淀回本库

## 许可

MIT — 自由使用、修改、传播。如果对你有帮助，欢迎：
- 给本仓库 star
- 提 issue / PR 贡献新 skill 或修正
- 在鸿蒙应用市场搜「**潮玩展柜**」下载体验作者实战项目

## 反馈

- Gitee Issues：https://gitee.com/chen_jeff/harmony-os-skill/issues
- 应用反馈：在「潮玩展柜」App 内「设置 → 反馈与帮助」