Skip to content

Commit 3a77595

Browse files
linhaylinhay
committed
docs: add guides for multi-device, continuation, NDK, and publishing (v1.0.5)
1 parent 432518d commit 3a77595

10 files changed

Lines changed: 194 additions & 9 deletions

File tree

‎README.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,21 @@
11
# HarmonyOS NEXT 开发者专家技能包 (Reference Skill)
22

33
`harmony-next.skills` 是为 AI 编程助手（如 Gemini CLI, Claude Code, Codex）设计的参考技能库。
4-
它为 HarmonyOS NEXT (API 12+) 提供本地化的离线知识源，包含超过 3,403 份涵盖 ArkTS、ArkUI 和 NDK 的 Markdown 格式参考文档。
4+
它为 HarmonyOS NEXT (API 12+) 提供本地化的离线知识源，包含超过 3,408 份涵盖 ArkTS、ArkUI 和 NDK 的 Markdown 格式参考文档。
55

66
[English Version](./README_en.md)
77

8-
## 核心特性 (v1.0.4+)
8+
## 核心特性 (v1.0.5+)
99

1010
除了详尽的 API 参考外，本项目现已包含以下**专家级实战指南**：
11-
- 🛠 **IDE 实操**：应用签名、断点调试、模拟器与真机配置全流程。
11+
- 🛠 **IDE 实操**：应用签名、断点调试、模拟器与真机配置、**AI 智能辅助编程 (CodeGenie)**。
12+
- 📱 **多端适配**：**一次开发多端部署**（自适应/响应式布局）、折叠屏与平板专项适配。
13+
- 🔄 **自由流转**：跨端迁移、多端协同的核心逻辑与开发步骤。
14+
- ⚙️ **NDK 开发**：**Node-API (napi)** 基础、C++ 与 ArkTS 跨语言互调。
15+
- 🚀 **应用发布**：AppGallery Connect 配置、发布证书申请、上架审核流程。
1216
- 📈 **性能调优**：深入使用 DevEco Profiler 进行 CPU、内存、帧率及启动耗时分析。
13-
- 🏗 **架构设计**：HAP/HAR/HSP 包结构深度解析、Stage 模型并发机制与 Actor 模型。
17+
- 🏗 **架构设计**：HAP/HAR/HSP 包结构深度解析、Stage 模型并发机制。
1418
- 🧪 **自动化测试**：基于 Hypium 的单元测试与 UI 测试，以及 CI/CD 命令行集成。
15-
- 🤖 **命令行工具**：`hdc`、`ohpm`、`hvigorw` 及 `emulator` 完整命令手册。
1619

1720
## 工作原理
1821

‎README_en.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,19 @@
11
# HarmonyOS NEXT Reference Skill
22

33
`harmony-next.skills` is a reference skill for coding agents.
4-
It provides a local source of truth for HarmonyOS NEXT (API 12+), with 3,403 Markdown references across ArkTS, ArkUI, and NDK topics.
4+
It provides a local source of truth for HarmonyOS NEXT (API 12+), with 3,408 Markdown references across ArkTS, ArkUI, and NDK topics.
55

6-
## Key Features (v1.0.4+)
6+
## Key Features (v1.0.5+)
77

88
Beyond API references, this skill now includes **expert guides** for:
9-
- 🛠 **IDE Operations**: Signing, Debugging, Emulator/Real Device setup.
9+
- 🛠 **IDE Operations**: Signing, Debugging, Emulator/Real Device setup, and **AI Assistant (CodeGenie)**.
10+
- 📱 **Multi-device Adaptation**: Strategies for phone, foldable, and tablet (Adaptive/Responsive Layout).
11+
- 🔄 **Continuation**: Cross-device migration and multi-device collaboration logic.
12+
- ⚙️ **NDK Development**: Node-API (napi) basics and ArkTS/C++ interoperability.
13+
- 🚀 **App Publishing**: AGC configuration, certificates, and release process.
1014
- 📈 **Performance Tuning**: CPU, Memory, Frame Rate, and Launch Analysis via DevEco Profiler.
1115
- 🏗 **Architecture**: Deep dive into HAP/HAR/HSP structures and Stage Model concurrency.
1216
- 🧪 **Automation Testing**: Unit and UI testing with Hypium, including CI/CD integration.
13-
- 🤖 **CLI Tools**: Full reference for `hdc`, `ohpm`, `hvigorw`, and `emulator` commands.
1417

1518
## How It Works
1619

‎harmony-next/SKILL.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,10 @@ Due to the massive size of this knowledge base (3,300+ files), you MUST follow t
3232
- `ideGuides/`: Comprehensive IDE guides (Signing, Running, Debugging, CLI Tools).
3333
- `performanceAndStandards/`: Performance optimization and UX best practices (Profiler, Latency, Memory).
3434
- `appBasics/`: Core architecture guides (HAP/HAR/HSP, Stage Model, Concurrency).
35+
- `multiDevice/`: Multi-device adaptation strategies (Adaptive/Responsive Layout).
36+
- `continuation/`: Cross-device migration and multi-device collaboration.
37+
- `ndkGuides/`: Native development guides (Node-API, C++ integration).
38+
- `publishing/`: AppGallery Connect release and publishing process.
3539
- `testing/`: Automation testing guides using Hypium.
3640
- `KITS.md`: The primary navigation hub organized by @kit.
3741
- `INDEX.md`: The full file list for surgical lookups.

‎harmony-next/references/INDEX.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3399,3 +3399,8 @@ performanceAndStandards/应用体验与性能规范.md
33993399
testing/应用测试与Hypium指南.md
34003400
appBasics/应用基础与包结构.md
34013401
appBasics/应用模型与并发.md
3402+
multiDevice/一次开发多端部署指南.md
3403+
continuation/自由流转与跨端协同指南.md
3404+
ndkGuides/NDK开发与Node-API指南.md
3405+
publishing/应用上架与发布指南.md
3406+
ideGuides/AI辅助编程指南.md

‎harmony-next/references/TASK_MAP.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,17 @@
4949
- Keywords: HAP, HAR, HSP, 包结构, 共享包
5050
- Keywords: Stage模型, FA模型, UIAbility, ExtensionAbility
5151
- Keywords: 并发模型, TaskPool, Worker, Event Loop
52+
- Keywords: 一次开发多端部署, 一多, 自适应布局, 响应式布局, 断点, 栅格
53+
- Keywords: 自由流转, 跨端迁移, 多端协同, Continuation
54+
55+
## NDK & Native
56+
- Keywords: NDK, Node-API, napi, C++, CMake, 跨语言互调
57+
58+
## Publishing
59+
- Keywords: 上架, 发布, AGC, AppGallery Connect, 审核, Profile
5260

5361
## Testing
5462
- Keywords: 测试, Hypium, 单元测试, UI测试
5563
- Keywords: 自动化测试, 断言, Mock, By定位
64+
- Keywords: AI辅助编程, CodeGenie, 代码生成
5665

‎harmony-next/references/continuation/自由流转与跨端协同指南.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# 自由流转与跨端协同指南 (Continuation)
2+
3+
自由流转打破了设备边界，使应用和数据在不同 HarmonyOS 设备间无缝流转。
4+
5+
## 1. 核心逻辑
6+
* **跨端迁移 (Cross-device Migration)**：将当前业务整体搬移。源端保存状态，对端恢复。
7+
* **多端协同 (Multi-device Collaboration)**：多个设备共同参与一个业务。实时同步数据流或指令流。
8+
9+
## 2. 开发步骤
10+
11+
### 第一步：权限与声明
12+
* 在 `module.json5` 声明 `ohos.permission.DISTRIBUTED_DATASYNC`。
13+
* 在 `abilities` 中配置 `continuable: true`。
14+
15+
### 第二步：跨端迁移实现
16+
应用需实现 `onContinue` 接口：
17+
1. **保存状态**：在源端 `onContinue()` 回调中，将数据存入 `wantParam`。
18+
2. **恢复状态**：在对端 `onCreate()` 或 `onNewWant()` 中，读取 `want` 参数并恢复 UI。
19+
20+
### 第三步：多端协同管理
21+
1. **设备发现**：使用系统 `Device Selector` 或分布式软总线。
22+
2. **远程启动**：调用 `startAbility` 并指定 `deviceId`。
23+
3. **实时同步**：利用 **分布式数据对象 (Distributed Data Object)** 保持多端数据强一致。
24+
25+
## 3. 典型场景
26+
* **接续播放**：手机看视频，流转到电视。
27+
* **硬件扩展**：手机作为手写板，平板作为画布。
28+
* **应用流转**：手机打车信息流转到手表查看。

‎harmony-next/references/ideGuides/AI辅助编程指南.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# AI 辅助编程指南 (CodeGenie)
2+
3+
DevEco Studio 集成了 **DevEco CodeGenie**，利用大模型辅助开发者提升代码编写效率。
4+
5+
## 1. 核心功能
6+
7+
### 代码生成与补全
8+
* **实时补全**：输入代码时自动预测后续逻辑。
9+
* **对话生成**：在侧边栏输入指令（如“创建网络请求类”），生成完整代码块。
10+
* **注释生成代码**：使用 `//gen [描述]` 触发。
11+
12+
### 代码解释与重构
13+
* **代码解读**：选中一段代码，AI 会解析其逻辑并添加详细注释。
14+
* **行内编辑 (Inline Edit)**：按 `Alt+I` 指令式修改代码（如“将此循环改为 map 实现”）。
15+
16+
### 单元测试生成
17+
* **一键生成**：为 ArkTS 函数自动创建 `unittest` 用例，覆盖正常与边界场景。
18+
19+
### 故障排查
20+
* **报错分析**：捕获编译错误日志，提供针对性的修复建议。
21+
22+
## 2. 常用快捷键 (macOS)
23+
* **侧边栏面板**：`Option+U`
24+
* **行内编辑**：`Option+I`
25+
* **多行生成**：`Option+C`
26+
* **单行补全**：`Option+X`
27+
* **采纳/拒绝**：`Tab` / `Esc`
28+
29+
## 3. 使用场景
30+
* **快速原型开发**：通过自然语言快速搭建 UI 骨架。
31+
* **遗留代码接手**：利用“代码解释”快速理解复杂逻辑。
32+
* **质量保证**：自动补齐繁琐的单元测试代码。

‎harmony-next/references/multiDevice/一次开发多端部署指南.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# 一次开发，多端部署指南 (Multi-device)
2+
3+
HarmonyOS NEXT 的“一次开发，多端部署”（简称“一多”）架构是实现跨手机、折叠屏、平板、PC 等多设备形态 UI 适配的核心技术。
4+
5+
## 1. 核心布局理念
6+
7+
### 自适应布局 (Adaptive Layout)
8+
侧重于**组件内部**或**局部**的调整。当容器尺寸微调时，组件自动填充空间，不改变整体结构。
9+
* **拉伸能力 (Stretching)**：利用 `flexGrow` 和 `flexShrink`。
10+
* **均分能力 (Equal Space)**：利用 `justifyContent: FlexAlign.SpaceEvenly`。
11+
* **占比能力 (Proportion)**：使用百分比宽度或 `layoutWeight`。
12+
* **隐藏能力 (Hidden)**：根据尺寸动态隐藏非核心组件。
13+
* **折行能力 (Wrap)**：利用 `Flex` 的 `FlexWrap.Wrap` 实现自动换行。
14+
* **缩放能力 (Scaling)**：利用 `aspectRatio` 保持组件宽高比。
15+
* **延伸能力 (Extension)**：利用 `List`、`Grid` 通过滚动承载内容。
16+
17+
### 响应式布局 (Responsive Layout)
18+
侧重于**页面整体架构**的改变。当屏幕跨越断点时，布局发生质变。
19+
* **断点 (Breakpoints)**：系统预设 `xs`, `sm`, `md`, `lg` 等阈值。
20+
* **媒体查询 (Media Query)**：监听窗口宽度、横竖屏、深浅色、设备类型。
21+
* **栅格系统 (Grid System)**：使用 `GridRow` 和 `GridCol`，支持 12 或 24 栅格。
22+
23+
## 2. 典型场景适配
24+
25+
### 折叠屏适配
26+
* **折叠态/展开态**：利用断点判断当前屏幕状态，实现从单列到双列的切换。
27+
* **悬停态**：适配半折叠状态下的交互逻辑。
28+
29+
### 平板适配
30+
* **分栏布局**：优先使用 `Navigation` 组件，自动处理手机侧边栏收起和平板侧边栏展开。
31+
* **内容延伸**：在大屏下展示更多并列内容，而非单纯拉大组件。
32+
33+
## 3. 最佳实践
34+
1. **移动优先**：先设计手机端体验，再向大屏扩展。
35+
2. **内容连续性**：跨设备切换时任务不中断。
36+
3. **使用一多组件**：优先选择 `Navigation`、`Tabs`、`Swiper` 等内置适配能力的组件。
37+
4. **三层架构**：
38+
* **Common**：公共能力（基础库）。
39+
* **Feature**：基础特性（可复用 UI 模块）。
40+
* **Product**：产品层（针对不同设备形态的 HAP）。

‎harmony-next/references/ndkGuides/NDK开发与Node-API指南.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# NDK 开发与 Node-API 指南
2+
3+
HarmonyOS NDK 基于 Node-API (napi) 提供 C++/ArkTS 跨语言交互能力。
4+
5+
## 1. 核心概念
6+
* **napi_env**：JS 引擎实例上下文。
7+
* **napi_value**：JS 对象在 C++ 侧的抽象表示。
8+
* **HandleScope**：管理 `napi_value` 生命周期，防止泄露。
9+
10+
## 2. ArkTS 与 C++ 互调流程
11+
12+
### C++ 侧实现
13+
1. **定义逻辑**：编写函数，使用 `napi_get_cb_info` 解析参数。
14+
2. **模块注册**：
15+
* 定义 `napi_module`。
16+
* 在 `Init` 中使用 `napi_define_properties` 导出接口。
17+
* 使用 `napi_module_register` 注册模块。
18+
19+
### 工程配置
20+
* **CMakeLists.txt**：
21+
* 使用 `add_library` 定义 SO。
22+
* `target_link_libraries` 链接 `libace_napi.z.so`。
23+
* **build-profile.json5**：在 `externalNativeBuild` 中关联 CMake 路径。
24+
25+
### ArkTS 侧调用
26+
```typescript
27+
import nativeModule from 'libentry.so';
28+
nativeModule.add(1, 2);
29+
```
30+
31+
## 3. 常用接口参考
32+
* `napi_create_function`：创建 JS 函数。
33+
* `napi_get_cb_info`：获取 ArkTS 传入参数。
34+
* `napi_create_double` / `napi_create_string_utf8`：创建 JS 基础类型。
35+
* `napi_wrap`：将 C++ 对象绑定到 JS 对象。

‎harmony-next/references/publishing/应用上架与发布指南.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# 应用上架与发布指南
2+
3+
将应用分发至 AppGallery 的核心流程与要求。
4+
5+
## 1. 发布准备
6+
* **发布证书 (.cer)**：由 AGC 颁发，标识开发者身份。
7+
* **发布 Profile (.p7b)**：包含包名、证书、受限权限列表。
8+
* **签名配置**：在 DevEco Studio `Signing Configs` 填入发布用的 `.p12`、`.cer`、`.p7b`。
9+
* **打包产物**：执行 `Build App(s)` 生成 `.app` 软件包。
10+
11+
## 2. AGC 后台操作
12+
1. **创建应用**：在 AGC “我的应用”中填写名称、默认语言等。
13+
2. **设置分发信息**：
14+
* **素材**：上传高清 Icon、各屏幕比例截图、视频说明。
15+
* **详情**：应用简介（一句话简介 + 详细描述）。
16+
* **隐私与安全**：填写隐私政策链接、收集权限说明、分级证明。
17+
3. **上架设置**：选择付费模式、目标地区、发布时间（立即或定时）。
18+
19+
## 3. 提交审核
20+
* **软件包上传**：将 `.app` 文件上传至版本管理。
21+
* **确认规范**：确保应用不包含任何违规内容（如广告混淆、非法权限请求）。
22+
* **审核周期**：通常需要 1-3 个工作日。
23+
24+
## 4. 最佳实践
25+
* **云测试验证**：正式发布前利用 AGC 提供的 **CloudTest** 确认各机型兼容性。
26+
* **灰度发布**：对于重大更新，建议使用分阶段发布模式。

0 commit comments

Comments
 (0)