back
loading skill details...
HarmonyOS Code Workshop v3.0 HarmonyOS Full-Process Development Knowledge Pack v3.0 — covers API 23→26 complete knowledge base. Includes 60+ offline API reference libraries, 42 error code files, 66 ArkUI component theme docs;新增 18 DevEco Studio 26.0.0 Beta1 toolchain capabilities, Accessory/Input/FA
---
name: harmonyos-code-workshop
description: >-
HarmonyOS (鸿蒙) full-process application development companion from coding
to AppGallery publishing. Use this skill when users need ArkTS syntax guidance,
ArkUI component design, API migration, compile error diagnosis, code quality
inspection, multi-device adaptation, performance optimization, or AppGallery
Connect publishing. Focuses on practical code editing — not just documentation
referencing, but ensuring code compiles, passes review, and ships to market.
version: 3.0.0
author: 鸿蒙代码专家团队 <839838805@qq.com>
trigger:
- "鸿蒙"
- "HarmonyOS"
- "ArkTS"
- "ArkUI"
- "鸿蒙开发"
- "HarmonyOS 开发"
- "鸿蒙应用"
- "鸿蒙原生"
- "鸿蒙代码"
- "鸿蒙 全流程"
- "鸿蒙 代码工坊"
- "ArkTS 语法"
- "ArkUI 组件"
- "鸿蒙 API"
- "鸿蒙 元服务"
- "Stage 模型"
- "鸿蒙 状态管理"
- "@State"
- "@Prop"
- "@Link"
- "鸿蒙 多设备适配"
- "鸿蒙 折叠屏"
- "鸿蒙 跨设备"
- "鸿蒙 编译错误"
- "鸿蒙 踩坑"
- "鸿蒙 迁移"
- "TS 转 ArkTS"
- "TypeScript 迁移 ArkTS"
- "鸿蒙 UI"
- "鸿蒙 网络请求"
- "鸿蒙 数据持久化"
- "鸿蒙 Navigation"
- "鸿蒙 Router"
- "鸿蒙 动画"
- "鸿蒙 手势"
- "鸿蒙 测试"
- "鸿蒙 性能优化"
- "鸿蒙 并发"
- "TaskPool"
- "鸿蒙 Worker"
- "鸿蒙 安全"
- "鸿蒙 Camera"
- "鸿蒙 音频"
- "鸿蒙 视频"
- "鸿蒙 推送"
- "鸿蒙 位置"
- "鸿蒙 蓝牙"
- "鸿蒙 NFC"
- "鸿蒙 分布式"
- "鸿蒙 流转"
- "鸿蒙 卡片"
- "鸿蒙 Widget"
- "元服务"
- "Atomic Service"
- "API 23"
- "API 24"
- "API 25"
- "API 26"
- "HarmonyOS 7"
- "鸿蒙 7"
- "DevEco Studio"
- "DevEco"
- "HAP"
- "HAR"
- "HSP"
- "ohpm"
- "鸿蒙 打包"
- "鸿蒙 签名"
- "鸿蒙 上架"
- "鸿蒙 AppGallery"
- "AGC"
- "AppGallery Connect"
- "鸿蒙 发布"
- "鸿蒙 审核"
- "鸿蒙 分发"
agent_created: true
---
# 鸿蒙代码工坊
> 鸿蒙（HarmonyOS）全流程编码助手——从代码编写到 AppGallery 上架，一站式搞定。
>
> 定位：不是文档搬运工，而是 **你的代码质量守护者 + 全流程导航员**。
> 代码编辑是核心，上架交付是终点，每一步都有实战经验护航。
## 核心理念
| 与其他鸿蒙技能的区别 | 本工坊的做法 |
|-------------------|------------|
| 只给 API 文档索引 | ✅ **确保代码能编译通过**（31项自检清单） |
| 只贴示例代码 | ✅ **告诉你为什么这样写、哪里会踩坑** |
| 只覆盖 API 23 | ✅ **API 22~26 全版本，含 HarmonyOS 7** |
| 开发完不管上架 | ✅ **从签名打包到 AGC 审核全流程覆盖** |
| 文档搬运型 | ✅ **来自真实项目的踩坑记录，非文档整理** |
| 让你自己找代码 | ✅ **30个即用模板 + 5个高级模式，复制即跑** |
---
## 🎯 能力边界与最佳使用
> **本节帮助你快速判断：这个技能能不能解决你的问题，以及怎么问效果最好。**
### 能力边界（能做什么 × 不能做什么）
| ✅ 我能帮你做 | ❌ 我帮不了 / 需要你自己做 |
|:---|:---|
| 写 ArkTS 代码并确保编译通过 | 替你运行 IDE 或真机调试 |
| 诊断编译错误并给出修复方案 | 访问你本地项目文件或 Git 仓库（除非你粘贴内容） |
| API 迁移（旧→新）+ 废弃警告 | 保证第三方 SDK/ohpm 包的 API 正确性（以官方文档为准） |
| AGC 上架流程指导 + 审核被拒分析 | 代你提交审核、代你处理华为账号/签名证书 |
| 性能优化建议 + 内存泄漏排查 | 做压力测试/性能基准测试（需要你自己跑） |
| UI 组件选型 + 布局方案设计 | 做 UI 视觉设计/出设计稿（我是代码助手不是设计师） |
| 多设备适配 + 折叠屏布局 | 测试所有真机设备的兼容性（需要你自测） |
| CI/CD 构建脚本编写 | 维护你的 CI/CD 服务器或处理构建环境问题 |
| 从其他平台（Android/iOS/Web）迁移到鸿蒙 | 一键自动转换整个项目（需要逐步迁移，我逐模块协助） |
**简单判断法**：如果你要的是**写代码、改代码、查错、上架指导** → 找我；如果你要的是**操作 IDE、操作 AGC 控制台、真机测试、服务器运维** → 这些需要你自己动手。
### 最佳提问方式（怎么问效果最好）
| 你想做什么 | ❌ 低效问法（泛泛而谈） | ✅ 高效问法（精准命中） |
|:---|:---|:---|
| 解决编译错误 | "帮我看看这个报错" | "API 26 编译报错 Error XXXX，这是我的代码片段和完整错误信息" |
| 写一个功能页面 | "帮我写个登录页" | "API 25 登录页：手机号输入框 + 验证码按钮 + Account Kit 华为账号一键登录，用 Navigation 跳转" |
| API 迁移 | "把我的 Android 代码改成鸿蒙" | "将这段 Kotlin Retrofit 网络请求迁移为 ArkTS @ohos.net.http，保持回调语义" |
| 上架问题 | "上架被拒了怎么办" | "AGC 审核被拒，原因是 XXX（附截图），我的应用是 XX 类目，包名 com.xxx" |
| 性能优化 | "我的 App 很卡" | "列表 1000 条数据滑动掉帧，当前用的 ForEach + @State 数组，想优化为 LazyForEach" |
| 选型咨询 | "鸿蒙状态管理用哪个好" | "跨 5 个页面共享用户信息，需要持久化，推荐 @StorageLink 还是 AppStorage？" |
| 多端适配 | "适配折叠屏" | "折叠屏展开态显示双栏布局（列表+详情），收起态单栏，用 BreakpointType 怎么实现？" |
**提问黄金公式**：
```
[目标版本] + [具体场景] + [当前做法/报错] + [期望效果]
例："API 26 + 碰一碰分享图片 + 当前 share() 回调没触发 + 希望实现 PC 精准坐标定位"
```
### 版本选择速查
| 你的目标设备/场景 | 推荐 minSDKVersion | 说明 |
|:---|:---:|:---|
| 兼容绝大多数旧设备（含 HarmonyOS 4 及以下） | API 22 | 覆盖 99%+ 设备，但无法使用新能力 |
| 主流开发（平衡兼容性与新特性） | **API 23**（默认） | 覆盖 94%+ 设备，组件和 API 最成熟 |
| 使用元服务/自由流转等较新能力 | API 25 | 需 HarmonyOS NEXT 5.0+ |
| 使用 HarmonyOS 7 最新能力（Agent/VibeCoding/碰一碰精准分享等） | **API 26** | 仅 HarmonyOS 7 设备，新项目首选 |
> 💡 **不确定版本？** 告诉我你的目标用户群体和最低支持设备，我帮你定。
---
## 📖 知识体系
> ⚡ **快速定位**：[编码规范](#1-arkts-编码规范核心铁律) · [常见编译错误](#2-propstate-属性名基类冲突常见错误-10505001) · [API迁移](#3-废弃-api-迁移对照重点) · [自检清单](#4-编译自检清单代码输出前逐项检查) · [API 26 新能力](#6-harmonyos-7-api-26-新能力详解) · [互动卡片摇一摇](#69-更多-api-26-新能力补充) · [状态管理](#7-arkts-v2-状态管理装饰器api-26) · [高级架构](#8-高级架构与性能实战复杂场景深度指南) · [上架指南](#10-agc-上架全流程指南从代码到商店) · [踩坑记录](#11-真实踩坑记录来自实战项目非文档搬运) · [代码模板](#12-代码模板库30-个即用模板--5-个高级模式) · [Kit速查](#-额外-kit-能力速查常用但易遗漏) · [对话示例](#-真实对话示例快速上手)
### 1. ArkTS 编码规范（核心铁律）
- **命名**：类/枚举/命名空间 → UpperCamelCase；变量/方法 → lowerCamelCase；常量 → SCREAMING_SNAKE_CASE
- **格式**：2空格缩进，单引号优先，行宽≤120，控制语句必须用大括号
- **TS→ArkTS 禁止项**：❌ any/unknown ❌ var ❌ 解构赋值 ❌ 函数表达式 ❌ 生成器 ❌ 运行时增删属性 ❌ 结构类型兼容 ❌ @ts-ignore ❌ 嵌套函数 ❌ 函数中 this 引用
- **数组类型**：使用 `T[]`（不用 `Array<T>`）
- **泛型**：必须显式标注，禁止隐式 any
- **可访问性**：类属性加 `private`/`protected`/`public`
- NaN 判断用 `Number.isNaN()`，不用 `===`
### 2. @Prop/@State 属性名基类冲突（常见错误 #10505001）
`@Component struct` 继承自 `CustomComponent`，ArkUI 链式方法（`.width()/.height()/.borderRadius()` 等）均为基类属性。同名 @Prop/@State 会覆盖基类签名导致编译错误。
**高频冲突属性名（13个）**：
| 冲突属性 | 推荐替换名 | 说明 |
|---------|-----------|------|
| `width` | `itemWidth` | `.width()` 为基类方法 |
| `height` | `itemHeight` | `.height()` 为基类方法 |
| `borderRadius` | `cornerRadius` | `.borderRadius()` 为链式方法 |
| `fontSize` | `textSize` | `.fontSize()` 为 Text 方法 |
| `fontColor` | `textColor` | `.fontColor()` 为 Text 方法 |
| `backgroundColor` | `bgColor` | `.backgroundColor()` 通用方法 |
| `margin` | `outerMargin` | `.margin()` 为布局方法 |
| `padding` | `innerPadding` | `.padding()` 为布局方法 |
| `align` | `contentAlign` | `.align()` 为布局方法 |
| `justifyContent` | `mainAxisAlign` | Flex 布局方法 |
| `alignItems` | `crossAxisAlign` | Flex 布局方法 |
| `direction` | `flexDirection` | Flex 方向 |
| `onClick` | `handleTap` | `.onClick()` 为事件方法 |
### 3. 废弃 API 迁移对照（重点）
> 💡 **API 23 → API 26 迁移要点**：import 路径从 `@ohos.xxx` 改为 `@kit.xxxKit`，部分 API 从同步变为异步，destroy 等资源释放方法改为实例调用。
| 旧API | ✅ 新API | 严重 | 额外注意 |
|------|---------|:---:|---------|
| `router.pushUrl()` | `UIContext.getRouter()` / Navigation | 🔴 | API 26 正式移除，不再仅警告 |
| 全局 `animateTo()` | `this.getUIContext().animateTo()` | 🔴 | |
| `console.log/info` | `@ohos.hilog` | 🟡 | |
| `@ohos.fileio` | `@ohos.file.fs` (CoreFileKit) | 🔴 | |
| `@ohos.notification` | `@kit.NotificationKit` → `notificationManager` | 🟡 | import 路径变 + 调用方式变 |
| `camera.Camera` | `CameraManager + Session` | 🔴 | |
| `globalThis` | `UIContext` / `AppStorage` / `LocalStorage` | 🔴 | API 26 正式移除 |
| `promptAction.showToast()` 全局 | `this.getUIContext().getPromptAction().showToast()` | 🟡 | |
| 全局 `getContext(this)` | `this.getUIContext().getHostContext()` | 🟡 | |
| `window.getTopWindow()` 回调 | `windowStage.getMainWindow()` Promise | 🟡 | |
| `@ohos.net.http` | `@kit.NetworkKit` → `{ http }` | 🟡 | `http.destroy()` → `httpRequest.destroy()` 实例方法 |
| `@ohos.distributedDeviceManager` | `@kit.DistributedServiceKit` → `{ distributedService }` | 🔴 | `getAvailableDevices()` 变为异步 |
| `@ohos.data.preferences` | `@kit.ArkData` → `{ preferences }` | 🟡 | import 路径变 |
| `@ohos.net.connection` | `@kit.NetworkKit` | 🟡 | |
| `@ohos.multimedia.image` | `@kit.ImageKit` | 🟡 | |
| `@StorageLink` | `@LocalStorageProp` / `@LocalStorageLink` | 🔴 | API 26 正式移除 |
### 4. 编译自检清单（代码输出前逐项检查）
> 📋 **5 类共 31 项**，代码输出前按此逐项勾选，可拦截 **90%+** 的常见编译错误。
| 分类 | 关键检查项 | 最容易忘的 ⚠️ |
|:---|:---|:---|
| **语法（6项）** | 无 var、无 any、无解构、无函数表达式、无嵌套函数、无 @ts-ignore | `for...in` 和解构赋值是 AI 生成代码的重灾区 |
| **API（7项）** | UIContext、Navigation、file.fs、notificationManager、hilog、CameraManager、util | `globalThis` 在 API 26 已移除 |
| **组件（6项）** | @Entry 唯一、LazyForEach、StorageLink 默认值、对象字面量接口、Navigation、IDataSource | @Prop/@State 与基类属性名冲突（见第 2 节 13 个高频冲突名） |
| **泛型（6项）** | 泛型显式标注、返回类型显式、无内联对象字面量、Record 规范、API 返回接口化 | `httpClient.get()` 必须写 `httpClient.get<object>()` |
| **性能（6项）** | 循环常量提取、无稀疏数组、无联合类型数组、数值安全、可选→默认参数、catch 类型注解 | ForEach 改 LazyForEach 是最常见的性能优化点 |
### 5. API 版本演进概要
| 版本 | 关键能力 |
|-----|---------|
| API 22 | 最低兼容（99%+ 设备） |
| API 23 | 主流覆盖（94%+），多数通用组件 |
| API 24 | 6.1.1 新增能力 |
| API 25 | 元服务增强、自由流转 |
| API 26 | Vibe Coding、沉浸光感、3DGS、空格音频、Agent 框架、碰一碰精准分享、互动卡片、DID、数字盾 |
### 6. HarmonyOS 7 (API 26) 新能力详解
> 以下能力基于 2026年6月 HDC 发布的 HarmonyOS 7 正式版，覆盖智能化、全场景、多窗交互、安全、性能、设计语言六大方向。
#### 6.1 🤖 智能化
| 能力 | 说明 | 开发要点 |
|------|------|---------|
| **Agent 框架** | intent 编排 + Tool 执行 + memory 管理，支持 A2A 接入 | `@kit.AgentKit`，Agent 注册到系统智能入口 |
| **Vibe Coding** | 用自然语言描述功能，AI 生成 Skill 代码 | 调测→审核→上架全流程 AI 加持 |
| **视觉 AI Kit (Core Vision)** | 7 大能力：通用文字识别、人脸检测/比对、主体分割、多目标识别、骨骼点检测、图像超分 | `@kit.CoreVisionKit`，端侧 NPU 推理，无需联网 |
**Core Vision Kit 7 大能力速查**：
- **通用文字识别**：扫描身份证、银行卡、车牌号等场景，支持竖排/弯曲文本
- **人脸检测/比对**：活体检测 + 1:1 人脸比对，支付/门禁场景
- **主体分割**：人像抠图、商品背景替换，输出 Alpha 掩码图
- **多目标识别**：同时检测画面中多个物体并分类
- **骨骼点检测**：人体 17 个关键点坐标，健身/运动姿态分析
- **图像超分（API 26 增强）**：低分辨率图像 2x/4x 放大。API 26 专用 `imageSuperResolution` 模块。
```typescript
import { imageSuperResolution, visionBase } from '@kit.CoreVisionKit';
import { image } from '@kit.ImageKit';
// ① 创建分析器
const analyzer: imageSuperResolution.ImageSRAnalyzer = await imageSuperResolution.ImageSRAnalyzer.create();
// ② 执行超分（输入 PixelMap → 输出高清 PixelMap）
const request: visionBase.Request = { inputData: { pixelMap: sourceImage } };
const response: imageSuperResolution.ISPResponse = await analyzer.process(request);
const resultPixelMap: image.PixelMap = response.pixelMap; // 超分后的图片
// ③ 使用完毕后强制释放（避免 NPU 显存泄漏）
await sourceImage.release();
await analyzer.destroy();
```
**关键**：必须在 Stage 模型下使用；`create()` 和 `process()` 均返回 Promise；异常码 `1018700001`；NPU 显存有限，大图需先做分辨率阈值校验。
- **文本语义搜图（API 26 新增）**：通过文本语义搜索匹配图片，端侧 NPU 推理，数据不出设备。
```typescript
import { vision } from '@kit.CoreVisionKit';
import { image } from '@kit.ImageKit';
// ① 初始化双模态分析器（首次预热需数百毫秒）
const searchAnalyzer = await vision.createTextToImageSearchAnalyzer();
// ② 提取图像特征向量（建库阶段）
const imageFeature: Float32Array = await searchAnalyzer.extractImageFeature(sourcePixelMap);
// ③ 提取文本特征向量（检索阶段）
const textFeature: Float32Array = await searchAnalyzer.extractTextFeature('草地上奔跑的白色小狗');
// ④ 向量余弦相似度匹配（全量扫描，生产推荐 HNSW 索引树）
function cosineSimilarity(a: Float32Array, b: Float32Array): number {
let dot = 0; for (let i = 0; i < a.length; i++) dot += a[i] * b[i];
return dot;
}
// 结果按 score 降序排序取 TopK
// ⑤ 释放
await sourcePixelMap.release(); // 显式释放，避免 GC 延迟导致 OOM
await searchAnalyzer.destroy();
```
**注意**：必须在同个线程中完成初始化、处理和销毁；NPU 特征提取不要并发 >5 张；后台建库推荐 `WorkScheduler` + 充电/息屏条件。
#### 6.2 📱 碰一碰·精准分享
> 基于 Share Kit，结合 NFC 近场通信 + 分布式软总线，设备轻触即可传输内容。
> API 26 新增 PC/平板精准定位：手机触碰电脑屏幕时识别目标窗口和坐标，图片等素材可精准插入。
**完整 API 规格**（`@kit.ShareKit`，Stage 模型，起始版本 5.0.0）：
**harmonyShare 模块结构**：
- `on('knockShare', callback)` — 注册碰一碰监听
- `on('knockShare', capability: SendCapabilityRegistry, callback)` — PC/平板带窗口ID注册
- `off('knockShare', callback?)` — 取消监听（不传 callback 清空所有）
- 还有 `gesturesShare`（隔空传送）和 `dataReceive`（沙箱接收）两个事件
**核心接口**（每个方法都有详细规格）：
```typescript
import { harmonyShare, systemShare } from '@kit.ShareKit';
import { uniformTypeDescriptor as utd } from '@kit.ArkData';
// ① 注册碰一碰监听（推荐带 windowId 的版本）
const capabilityRegistry: harmonyShare.SendCapabilityRegistry = {
windowId: 123, // ⚠️ 必填：当前窗口 ID
sendOnly: false, // 可选：true=仅发送不接收，默认false
};
harmonyShare.on('knockShare', capabilityRegistry, async (target: harmonyShare.SharableTarget) => {
// ② 构造分享数据（3种卡片模板由参数组合自动决定）
const shareData = new systemShare.SharedData({
utd: utd.UniformDataType.HYPERLINK, // 统一数据类型标识
content: 'https://your.app.link/page', // 分享内容 URI/URL
// 以下字段影响卡片模板，详见注释：
title: '分享卡片标题', // + description + thumbnailUri → 决定卡片布局
description: '分享卡片描述', // 与 title 配合触发沉浸式大卡或白卡布局
thumbnailUri: fileUri.getUriFromPath(filePath), // 预览图 URI
});
// ③ 发送分享数据（返回 Promise<void>）
await target.share(shareData);
});
// ④ 生命周期：onPageShow() 注册，onPageHide() 取消
harmonyShare.off('knockShare', capabilityRegistry, this.callback);
```
**3 种卡片模板（由参数自动决定）**：
| 卡片模板 | 判定条件 | 布局 |
|:--------|---------|------|
| **纯图片布局** | 仅传 `thumbnailUri` | 全屏预览图 |
| **沉浸式大卡** | 传 `title + description + thumbnailUri`，且**预览图宽高比 < 1:1** | 大图+标题+描述 |
| **白卡上下布局** | 传 `title + description + thumbnailUri`，且**预览图宽高比 > 1:1** | 上方小图+下方文字 |
**预览图规范**：
- 海报类来源：推荐 3:4 比例，最小 600×800 px，最大 3000×4000 px
- 用户上传图片：不限制比例，最大 3000×4000 px
- 预览图过大会导致加载慢，过小会模糊
**SharableTarget 完整方法集**：
| 方法 | 起始版本 | 说明 |
|:----|:-------:|------|
| `share(data: SharedData): Promise<void>` | 5.0.0 | 发送分享数据 |
| `reject(error: SharableErrorCode): Promise<void>` | 5.0.3 | 拒绝本次分享，向用户显示错误原因 |
| `updateShareData(data: UpdatedData): Promise<void>` | 6.0.0 | 延迟更新预览图（云端图片场景） |
| `clarifyNonShare(info: SharableErrorInfo): Promise<void>` | 6.0.2 | 告知用户当前无可分享内容并引导 |
| `getInfo(): SharableTargetInfo` | **26.0.0 Beta** | 获取PC精准坐标（screenX, screenY） |
**SharableErrorCode 枚举**：
| 值 | 含义 |
|:--:|------|
| `NO_CONTENT_ERROR = 1` | 无内容可分享 |
| `NO_INTERNET_ERROR = 2` | 无网络连接 |
| `DOWNLOAD_ERROR = 3` | 下载失败 |
**ShareResultCode 枚举**（接收端回调）：
| 值 | 含义 |
|:--:|------|
| `SHARE_SUCCESS = 0` | 传输成功 |
| `SEND_FAILED = 1` | 发送失败 |
| `CANCEL_BY_SENDER = 2` | 发送端取消 |
| `CANCEL_BY_RECEIVER = 3` | 接收端取消 |
**PC 精准分享（API 26 Beta）**：
- `target.getInfo()` 返回 `SharableTargetInfo.coordinate` 包含 `screenX` 和 `screenY`（屏幕左上角为原点的整数坐标）
- 接收端也有对应的 `ReceivableTarget.getInfo()` 返回 `ReceivableTargetInfo`
**云端预览图延迟更新模式**：
```typescript
// ① 先发送核心数据（使用默认预览图）
await target.share(shareData);
// ② 云端图片下载完成后，更新预览图（必须在数据发送前更新）
setTimeout(async () => {
await target.updateShareData({ thumbnailUri: localFilePath });
}, 5000);
```
**异常场景处理**：
```typescript
// 当前界面无可分享内容
harmonyShare.on('knockShare', (target) => {
target.clarifyNonShare({ message: '请在有分享内容的界面重试' });
});
// 下载失败等异常
harmonyShare.on('knockShare', (target) => {
target.reject(harmonyShare.SharableErrorCode.DOWNLOAD_ERROR);
});
```
**生命周期必须成对**：`onPageShow` 注册 → `onPageHide` 取消。不取消会导致页面隐藏后仍在响应碰一碰事件。
**安全策略**（HarmonyOS NEXT 5.0.0.123 SP16+）：
- 对端已登录华为账号 → 展示对方昵称和头像
- 对端未登录 → 展示设备信息
#### 6.3 🪟 闪控窗体系（HarmonyOS 多窗交互）
闪控窗体系分三层：**实况窗（Live View）**、**闪控球（FloatingBall）**、**标准悬浮窗（FloatingWindow）**。三者定位不同，可联动使用。
#### 6.3.1 闪控球（FloatingBall，API 20+）
> 模块：`@kit.ArkUI` → `floatingBall` | 受限权限：`ohos.permission.USE_FLOAT_BALL`（ACL申请）
> 仅手机和平板，仅应用在前台时可启动。同一应用只能启动一个，同一设备最多两个。
**4 种模板**：
| 模板 | 支持内容 | 可更新 |
|:----|---------|:-----:|
| `STATIC`（静态布局） | 图标 + 标题 | ❌ 创建后不可更新 |
| `NORMAL`（普通文本布局） | 标题 + 内容 | ✅ |
| `EMPHATIC`（强调文本布局） | 图标 + 标题 + 内容 | ✅ |
| `SIMPLE`（纯文本布局） | 标题（最多双行） | ✅ |
**规格**：整体宽 70~98vp，高 40vp，不支持自定义字体大小。
**完整 API 流程**：
```typescript
import { floatingBall } from '@kit.ArkUI';
import { Want } from '@kit.AbilityKit';
// ① 检查设备是否支持
const isEnabled = floatingBall.isFloatingBallEnabled();
// ② 创建控制器
const controller: floatingBall.FloatingBallController =
await floatingBall.create({ context: this.getUIContext().getHostContext() });
// ③ 注册事件
controller.on('click', () => {
// 点击闪控球 → 恢复主窗口
const want: Want = { bundleName: 'com.example.app', abilityName: 'EntryAbility' };
controller.restoreMainWindow(want);
});
controller.on('stateChange', (state: floatingBall.FloatingBallState) => {
if (state === floatingBall.FloatingBallState.STOPPED) {
controller.off('click'); // 停止后清理监听
controller.off('stateChange');
}
});
// ④ 启动闪控球
await controller.startFloatingBall({
template: floatingBall.FloatingBallTemplate.NORMAL,
title: '比价中',
content: '已找到 3 个平台报价',
backgroundColor: '#0ff77c', // 可选
});
// ⑤ 更新内容
await controller.updateFloatingBall({
template: floatingBall.FloatingBallTemplate.NORMAL,
title: '比价完成',
content: '最低 ¥299，点击查看',
});
// ⑥ 停止闪控球
await controller.stopFloatingBall();
// 🚨 生命周期：aboutToDisappear 中必须停止，否则泄漏
```
**交互行为**：
- 单击 → `click` 事件 | 长按 → 变为待删除态 | 拖动 → 自动吸附侧边
- 位置记忆：关闭后记录位置，下次启动恢复；旋转屏幕/重启恢复默认（右上侧）
- 删除：拖到屏幕底部中部的垃圾桶区域松手
**闪控球 vs 标准悬浮窗**：闪控球是**受限能力**（需 ACL 权限、指定场景），而标准悬浮窗是 API 26 Beta 新增的**通用悬浮窗口**（暂无官方 API 文档完整公开）。普通开发者建议优先使用闪控球。
#### 6.3.2 实况窗进度环模板（Live View，API 26 新增）
```typescript
import { liveView } from '@kit.LiveViewKit';
const card = liveView.createCard({
template: liveView.templates.ProgressRing,
data: { title: '下载中', progress: 0.73, subtitle: '剩余 2 分钟' }
});
// ⚡ 节流：最多每秒更新一次，避免频繁重绘
if (Date.now() - lastUpdateTime > 1000) {
card.update({ data: { progress: currentPercent } });
}
```
#### 6.3.3 闪控窗联动设计模式
三个层级展示同一数据源（推荐 `@Observed` 共享对象），信息分级展示：
- **一级**（最精简）：状态栏图标 / 实况窗摘要
- **二级**（中等详情）：实况窗展开 / 闪控球展开
- **三级**（完整交互）：标准悬浮窗 / 应用主界面
#### 6.4 🛡️ 安全新能力
| 能力 | 说明 | 适用场景 |
|------|------|---------|
| **星盾机密风控引擎** | 端侧 TEE 机密空间计算风控，数据"可用不可见" | 支付/转账/虚拟资产 |
**星盾机密风控引擎（API 26+）— 官方 API 规格**：
- 模块：`@kit.DeviceSecurityKit` → `riskControlEngine`
- 权限：需在 AGC 手动开通"星盾机密风控引擎"开关 + 申请 Profile
- 限制：每应用每设备每天最多 10 次
- 设备：Phone、Tablet、PC/2in1
**核心接口（仅 2 个）**：
```typescript
import { riskControlEngine } from '@kit.DeviceSecurityKit';
import { cryptoFramework } from '@kit.CryptoArchitectureKit';
import { util } from '@kit.ArkTS';
// ① 生成 nonce（16-66 字节，base64 编码，防重放攻击）
const rand = cryptoFramework.createRandom();
const randData = rand.generateRandomSync(32);
const base64 = new util.Base64Helper();
const nonce = base64.encodeToStringSync(randData.data);
// ②（可选）导入应用专属风险因子
await riskControlEngine.importRiskFactors({
appFactorData: [
{ factorName: "payment_amount", factorValue: 12800 },
{ factorName: "is_new_device", factorValue: false },
],
nonce: nonce,
});
// ③ 发起风控评分
const response = await riskControlEngine.getRiskControlResult({
policyName: "Policy_1001", // 在 AGC 配置的风险策略名称
nonce: nonce,
});
// 返回 JWS (JSON Web Signature) 格式，需在后端解析验证
```
**JWS 解析流程（在应用后端完成）**：
1. 解析 JWS 获取 Header/ Payload/Signature
2. Header 含 `alg: ES256`, `typ: JWS`, `x5c` 证书链（3 级）
3. 用华为 Root CA 验证证书链 → 用 x5c[0] 验证签名
4. Payload 含 `nonce`（防重放校验）+ `RiskDetectionOutput.status/result`
**其他安全 Kit 概要**：
| Kit | 能力 | API | 起始版本 |
|:----|:----|:----|:--------:|
| DID 分布式身份 | 系统级数字身份，TEE 存储颁发 | `@kit.DeviceSecurityKit` → `onlineAuthentication` | API 26 |
| 数字盾 | TEE 级可信签名/UI/输入 | `@kit.DeviceSecurityKit` → `deviceSecurity` | API 26 |
| 隐私防窥 | 智能屏幕防窥保护 | `@kit.DeviceSecurityKit` → `dlpAntiPeep` | API 23 |
| **超级隐私管控** ⭐ | 对相机/麦克风/位置分别策略化管控 | `@kit.DeviceSecurityKit` → `superPrivacyMode` | **API 26** |
| **按文件事件订阅** ⭐ | 订阅文件打开/关闭/删除/重命名/拷贝等事件 | `@kit.DeviceSecurityKit` → `securityAudit` | **API 26** |
| **统一风控凭证** ⭐ | 查询设备风险因子，返回 JWS 格式风控凭证 | `@kit.DeviceSecurityKit` → `safetyDetectEnhanced` | **API 26** |
**超级隐私管控（API 26+）**：对相机/麦克风/位置分别策略化管控。
```typescript
import { superPrivacyMode } from '@kit.DeviceSecurityKit';
// ⚠️ 官方 API 验证：返回值是 SuperPrivacyPolicyInfo 结构，非简单 map
const policyInfo: superPrivacyMode.SuperPrivacyPolicyInfo = await superPrivacyMode.getSuperPrivacyPolicies();
// policyInfo.superPrivacyMode: SuperPrivacyMode (OFF=0 / ON_WHEN_FOLDED=1 / ALWAYS_ON=2)
// policyInfo.superPrivacyPolicies: SuperPrivacyPolicy[] 长度固定3，顺序 CAMERA→MICROPHONE→LOCATION
// .sensorType: PrivacySensorType (CAMERA=0 / MICROPHONE=1 / LOCATION=2)
// .sensorState: PrivacySensorState (DEFAULT=0 / ENABLED=1 / DISABLED=2)
// 订阅策略变更（注意：事件名是 'superPrivacyModeChange' 而非 'superPrivacyPolicyChange'）
// API 26 推荐使用 onSuperPrivacyModeOrPolicyChange
superPrivacyMode.onSuperPrivacyModeOrPolicyChange((info) => {
console.info(`模式: ${info.superPrivacyMode}, 策略: ${JSON.stringify(info.superPrivacyPolicies)}`);
});
// 取消订阅
superPrivacyMode.offSuperPrivacyModeOrPolicyChange(callback);
```
**按文件事件订阅（API 26+）**：安全审计，订阅文件打开/创建/删除/重命名等操作。
```typescript
import { securityAudit } from '@kit.DeviceSecurityKit';
// ① 创建客户端（需权限 ohos.permission.QUERY_AUDIT_EVENT）
const client: securityAudit.Client = securityAudit.newClient((event) => {
console.info(`文件事件: ID=${event.eventId}, 内容=${event.content}, 时间=${event.timestamp}`);
});
// ② 订阅文件事件（NotifyEvent.FILE_OPEN / FILE_CREATE / FILE_DELETE / FILE_RENAME / FILE_CLOSE / FILE_COPY / FILE_WRITE）
client.subscribe([securityAudit.NotifyEvent.FILE_OPEN, securityAudit.NotifyEvent.FILE_DELETE]);
// ③ 添加路径过滤（FilterType.FILE_PATH_REGULAR: 路径正则匹配）
client.addFilter(securityAudit.NotifyEvent.FILE_OPEN, {
type: securityAudit.FilterType.FILE_PATH_REGULAR, // API 26 新增
isInclude: true, // true=返回符合条件, false=过滤掉
values: ['/data/storage/el2/base/**'],
});
// ④ 取消订阅
client.unsubscribe([securityAudit.NotifyEvent.FILE_OPEN]);
// ⑤ 用完删除客户端
securityAudit.deleteClient(client);
```
**星盾引擎集成要点**：`@kit.DeviceSecurityKit` 的 `RiskAssessmentEngine`。初始化需 200~500ms（在 `UIAbility.onCreate` 中预初始化），依赖真实 TEE 硬件（模拟器不可用）。模型容量约 2MB，核心特征推荐 `DEVICE_INTEGRITY` + `BEHAVIOR_ANOMALY` 两个。
#### 6.5 ⚡ 性能与通信
| 能力 | 说明 | Kit |
|------|------|-----|
| **游戏快启** | 预加载 + 内核调度优化，冷启动提速 | HyperStartup / Graphics Accelerate Kit |
| **鸿蒙内核应用快启** | HyperStartup 内核级应用预加载，加速常用 App 冷启动 | HyperStartup |
| **冷启网络预建链** | App 启动时提前建立网络连接，减少首屏等待 | Network Boost Kit |
| **QUIC 长连接** | 基于 QUIC 协议的持久连接，弱网下更快恢复；API 26 新增 C API 支持 | Remote Communication Kit |
| **弱网直播优化** | FEC + 动态码率，直播卡顿率降低 40%+ | Network Kit |
| **LTPO 可变帧率** | 根据内容动态调整刷新率 (1~120Hz)，功耗降低 30% | ArkGraphics 2D |
| **Graphics Accelerate 预启动 ⭐** | 根据用户使用习惯，在系统资源充足时提前加载游戏，进行部分初始化和资源加载 | Graphics Accelerate Kit（API 26） |
| **Graphics Accelerate 资源包下载查询 ⭐** | `isSupportAssetDownload()` 查询当前设备类型是否支持资源包下载 | Graphics Accelerate Kit（API 26） |
#### 6.6 🎨 设计语言进化
| 新特性 | 说明 | 适配建议 |
|--------|------|---------|
| **沉浸光感** | 材质的光学行为、空间属性与交互响应综合 | 核心界面（标题栏、导航）启用沉浸光感样式 |
| **系统材质 ⭐** | API 26 新增 `systemMaterial` 通用属性，所有组件支持系统材质效果；弹窗类组件（Tips/Toast/对话框/自定义弹窗/半模态/Popup）均支持 | 使用 `materialTheme` 统一管理材质语义化变量 |
| **可变字体** | 所有语言支持连续字重变化，粗细过渡细腻 | 替代固定字重，使用 `fontWeight: FontWeight.MEDIUM` 范围值 |
#### 6.7 🛠️ DevEco Studio 26.0.0 Beta1 + DevEco Code — AI IDE 双引擎
**DevEco Studio 26.0.0 Beta1**（配套 API 26，2026/06/12 发布）：
- 版本号：DevEco Studio 26.0.0 Beta1 (26.0.0.461)，携带 SDK 26.0.0 Beta1
- 配套：Node.js 24.14.1 → hvigor 6.26.1 → ohpm 26.0.0.410
**全新工具链（API 26 新增）**：
| 新特性 | 说明 |
|:------|:-----|
| **Code Scanner** | 检查整个项目的资源泄漏问题，自动扫描未释放资源 |
| **8 档断点预览** | 同时预览应用在 8 个典型档位断点下的 UI 效果 |
| **Car 模拟器** | 新增 Car 设备模拟器，支持多屏能力 |
| **设备投屏** | 将设备投屏到 DevEco Studio 中使用，实时操作调试 |
| **dump 解析** | 解析应用崩溃生成的 dump 文件，展示异常堆栈 |
| **状态变量查看** | 编辑器实时查看 ArkUI 组件状态变量关系 |
| **模块按需加载** | Load/Unload Modules，降低内存占用，提升代码索引效率 |
| **数据库调试增强** | SQL 语法高亮、自动联想补全、可视化编辑表格数据 |
| **发布重签名** | 上传时自动重签名，无需手动下载证书和 Profile |
| **AppAnalyzer 诊断** | 导入 AppGallery 审核不通过报告，自动诊断故障原因 |
| **AI 增强** | Inline Chat 快捷指令 (File Comments / Parameter Validation)、工程问答支持 MCP Market 工具 |
| **自定义指令 Commands** | 将常用提示词和工作流封装为可复用命令 |
| **Agent UI Verification** | 自定义 Agent 新增 UI Verification 内置工具 |
| **Clang-Tidy 静态检查** | 支持自定义 Clang-Tidy 对 C/C++ 代码进行静态检查 |
| **Native 调试加速** | 首次调试后调试服务器保持活跃，后续大幅减少连接耗时 |
| **HiLog 标签过滤** | 支持根据日志标签过滤 HiLog 日志 |
| **Memory 分析增强** | 新增 ArkWeb PA 和 JS Heap 子泳道、Statistics 页签（虚拟内存区域/PSS 统计） |
| **ci 配置增强** | syncNative 优化 C++ 编译效率、tsImportSoCheck 规则、apiCompatibilityCheck 检测级别 |
**DevEco Code** — 新一代 AI IDE（基于 BitFun + OpenCode）：
- 支持自定义大模型：已验证 **GLM-5.1、DeepSeek** 等国产大模型接入
- 实战场景：文字识别/代码生成/代码审查/单元测试/应用构建（9 篇社区大牛精讲）
- 与 DevEco CLI 配合可跑通全流程 CI/CD 管线
| 对比 | DevEco Studio | DevEco Code |
|:----|:-------------:|:-----------:|
| 定位 | 传统 IDE | AI 原生 IDE |
| AI 能力 | 辅助（补全/提示） | 主导（生成/验证/测试） |
| Skill 开发 | 手动编码 | Vibe Coding 自然语言 |
| 模型 | 内置固定 | 支持自定义模型 |
**DevEco CLI**：命令行工具链，支持 CI/CD 集成，`deveco build/test/publish` 等命令。
**DevEco CLI 大模型集成**：
```bash
# 配置第三方模型（GLM-5.1 示例）
deveco config set model.provider glm
deveco config set model.apiKey YOUR_API_KEY
deveco config set model.endpoint https://open.bigmodel.cn/api/paas/v4
# 使用 CLI 生成应用
deveco code generate "创建一个待办事项应用"
deveco code review src/main/ets/pages/Index.ets
deveco test src/main/ets/test/ --ai
```
#### 6.8 ⚠️ API 26 新能力异常处理速查
> 以下是碰一碰分享、闪控球、星盾引擎三个 API 26 核心新能力的常见异常场景和处理方案。
**碰一碰分享常见异常**：
| 异常现象 | 可能原因 | 解决方案 |
|:---|:---|:---|
| `knockShare` 事件不触发 | NFC 未开启 / 设备不支持 | 调用前检查 `nfcController.isNfcAvailable()` |
| `share()` 返回 `SEND_FAILED` | 对端设备不在线 / 传输超时 | 添加重试机制，最多 3 次，间隔 2s |
| `share()` 返回 `CANCEL_BY_RECEIVER` | 接收端主动取消 | 提示用户"对方已取消分享" |
| `thumbnailUri` 图片不显示 | 文件路径错误 / 文件过大 | 检查 URI 是否合法，预览图 ≤ 3000×4000 px |
| `updateShareData()` 不生效 | 在 `share()` 发送后才调用 | 必须**在 share 调用前**更新预览图 |
| PC 精准坐标 `getInfo()` 返回 0 | 非 PC 场景 / API 版本不够 | 确认设备为 PC + API 26 Beta+ |
| 页面关闭后仍在响应碰一碰 | 缺少 `off('knockShare')` 调用 | 检查生命周期：onPageShow 注册，onPageHide 取消 |
**闪控球常见异常**：
| 异常现象 | 可能原因 | 解决方案 |
|:---|:---|:---|
| `floatingBall.create()` 返回 null | 设备不支持 / ACL 权限未申请 | 检查 `isFloatingBallEnabled()` + `ohos.permission.USE_FLOAT_BALL` |
| `startFloatingBall()` 抛出权限异常 | ACL 权限未在 AGC 申请 | 在 AGC → 开发服务 → ACL 权限中申请 |
| 闪控球创建后不显示 | 应用不在前台 / 超过数量限制 | 确认应用在前台，同一设备最多同时显示 2 个 |
| `updateFloatingBall()` 对 STATIC 模板无效 | STATIC 模板不支持更新 | 改用 NORMAL / EMPHATIC / SIMPLE 模板 |
| `aboutToDisappear` 后闪控球未消失 | 未调用 `stopFloatingBall()` | 在 `aboutToDisappear` 中强制停止 |
| `restoreMainWindow()` 无响应 | Want 参数错误 | 检查 bundleName 和 abilityName 是否正确 |
**星盾引擎常见异常**：
| 异常现象 | 可能原因 | 解决方案 |
|:---|:---|:---|
| `getRiskControlResult()` 返回空 | 日调用次数超限（每天 10 次） | 限制调用频率，缓存前一次结果 |
| `importRiskFactors()` 超时 | TEE 环境初始化未完成 | 在 UIAbility.onCreate 中预初始化（需 200~500ms） |
| JWS 签名验证失败 | nonce 不匹配 / 证书链不一致 | 确认 nonce 与请求时一致，用华为 Root CA 验证 x5c |
| 模拟器上报错 | 星盾依赖真实 TEE 硬件 | 必须真机调试，模拟器不可用 |
| AGC 控制台找不到星盾开关 | 未在该应用下开通 | 在 AGC → 开发服务 → 星盾机密风控引擎 手动开通 |
#### 6.9 📱 更多 API 26 新能力补充
> 以下能力也是 HarmonyOS 7 新增的，但篇幅原因仅做概要说明。
**互动卡片摇一摇（API 26+）**：
互动卡片新增"摇一摇"触发方式——用户摇动手机即可激活卡片动画（静态→动态、前景元素出框），无需点击。
```json
// form_config.json 中配置
{
"sceneAnimationParams": {
"abilityName": "DeliveryLiveCardAbility",
"triggerTypes": ["shake"] // 支持摇一摇触发
}
}
```
流程：用户摇动 → 系统查找配置了 `shake` 的卡片 → 触发 `FormExtensionAbility.onUpdateForm` → 调用 `formProvider.requestOverflow()` 激活互动卡片。
> **限制**：仅 HarmonyOS 7.0+ 生效。与点击触发的区别：摇一摇由系统识别事件，点击由 UI 层 `postCardAction(MESSAGE)` 触发。
**空间音频 / 音频编创（Audio Suite）**：
`@kit.AudioKit` → `OHAudioSuite`（C/C++ 接口，API 22+）。引擎 + 管线 + 节点三级架构，支持降噪、均衡器、人声分离、声音美化、环境效果、声场渲染、混音等效果节点。引擎最多 10 条管线，支持离线编辑和实时预览两种模式。
- 典型场景：直播推流降噪、音乐 App 自定义均衡器、短视频人声分离
- 参考 Sample：[audio-suite-sample](https://gitcode.com/HarmonyOS_Samples/guide-snippets/tree/HarmonyOS-7.0-beta-20260514/Media/Audio/AudioSuiteSample)
**XComponent + NAPI 图像绘制（官方 Codelab 精学）**：
`XComponent` 组件调用 NAPI 创建 EGL/GLES 环境，在 C++ 侧进行 OpenGL ES 渲染，实现高性能图形。
关键模式：ArkTS 侧 `onLoad()` 接收 XComponent 上下文 → NAPI 注册 `drawRectangle()` → Button 触发 C++ 绘制
**窗口管理·验证码登录（官方 Codelab 精学）**：
`WindowModel` 单例管理主/子窗口：主窗口沉浸式（全屏+隐藏系统栏）→ 验证按钮拉起半透明子窗口 → 校验成功销毁子窗口 → EventHub 通知主窗口跳转。完整代码见文后"窗口管理实战模板"。
**游戏启动加速·秒级启动（Graphics Accelerate Kit 精学）**：
加载内存镜像实现冷启动秒开秒进。`onCreate` 调用 `setSupportedProcessCache(true)`，`onWindowStageWillDestroy` 中检查 `isLaunchMirrorEnabled()` 并切换场景，系统自动制作内存镜像（约 4s）。详见文后"Graphics Accelerate 秒级启动实战"。
**AGC 云调试验证（实用技巧）**：
在 AGC → 远程真机 → 云调试中，筛选 **API 26** 或 **系统版本 7.0.0.23** 的设备，上传 HAP 包即可远程调试验证 HarmonyOS 7 兼容性，无需真机。首次集成新 API 时强烈建议先跑云调试。
> **入口**：AGC 控制台 → 我的项目 → 质量 → 云调试
**平行视界 EasyGo（API 26 新增）**：
大屏设备（平板/折叠屏展开态）的平行视界新增 EasyGo 能力，支持 1:2、2:1 分屏启动模式，以及购物模式、导航模式等路由模式。开发者通过配置文件接入，成本更低，体验更优。
- `@kit.AbilityKit` → 多窗口管理
**应用内分屏**：
大屏模式下支持应用内分屏，快速进入比价、辅助窗口模式，提升用户操作效率。
- 典型场景：购物 App 比价、笔记 App 双文档对照
**多设备 UX 自动检测**：
支持基于真机或模拟器开展多设备 UX 检测，自动发现大图大字、界面截断、重叠等典型布局问题。
- `DevEco Studio` → 设备 UX 检测工具
**DFX 维测工具增强**（DevEco Studio / 运维效率）：
| 能力 | 说明 |
|:---|:---|
| **APMS 故障诊断** | 商用版本故障总览 + 告警 + 根因分析 + 修复建议 |
| **DevEco Testing** | 支持内存泄漏问题快速激发测试 |
| **Profiler 全类型内存** | 一键抓取全类型内存泳道 + 跨语言内存调优 |
| **GWP-Asan / HWAsan** | 踩内存故障定位增强，支持跨语言栈缝合 |
| **Dump 文件解析** | 应用卡死/崩溃场景下的 Dump 文件智能解析 |
| **数据库可视编辑** | 数据库数据可视化编辑，SQL 智能联想 |
**Linux arm 版模拟器**：
新增支持 Linux arm 架构模拟器，Arm Mac（Apple Silicon）和 Linux arm 服务器可直接运行。
### 7. ArkTS V2 状态管理装饰器（API 26+）— 实战精学
> 以下内容基于华为官方 Codelab《基于状态管理V2-小场景案例》（2026-06-30 发布）及官方 API 文档。注意：V1 `@Observed/@ObjectLink/@Prop/@Link/@Watch` 仍然可用，但 V2 是 API 26 推荐方案。
#### 7.1 V2 装饰器速查表
| 装饰器 | 作用 | 替代 V1 | 适用场景 |
|:------|:----|:-------:|:--------|
| `@ComponentV2` | 装饰自定义组件 | `@Component` | 所有 V2 组件 |
| `@Local` | 组件内部状态，驱动 UI 刷新 | `@State` | 组件内变量 |
| `@Param` | 接收父组件传入的状态 | `@Prop` | 父子数据传递 |
| `@Once` | 仅接收一次父组件传入 | `@Prop` + const | 初始化后不变 |
| `@Event` | 定义回调方法，子→父更新 | `@Link` / 自定义回调 | 子组件修改父数据 |
| `@Provider`/`@Consumer` | 跨层级状态传递（key 匹配） | `@Provide`/`@Consume` | 深层嵌套传递 |
| `@Computed` | 计算属性，缓存结果 | 无直接替代 | 依赖其他状态的派生数据 |
| `@Monitor` | 监听状态变化 | `@Watch` | 变化时执行额外操作 |
| `@ObservedV2` | 装饰类，支持深度观测 | `@Observed` | 复杂对象状态管理 |
| `@Trace` | 装饰类属性，深度观测 | `@ObjectLink` | 对象嵌套属性监听 |
| `@LocalStorage` | 页面级持久化存储 | 无 | 跨页面共享轻量数据 |
#### 7.2 实战案例（7 场景，来自官方 Codelab）
##### ① @Local — 定义组件内状态
```typescript
@ComponentV2
struct DemoLocal {
@Local count: number = 0; // 驱动 UI 刷新
notReactive: number = 0; // public 变量，修改不刷新 UI
build() {
Column() {
Text(`响应式: ${this.count}`) // 会更新
Text(`非响应式: ${this.notReactive}`) // 不会更新
Row() {
Button('-1').onClick(() => { this.count--; this.notReactive--; })
Button('+1').onClick(() => { this.count++; this.notReactive++; })
}
}
}
}
```
##### ② @Param — 接收父组件参数
```typescript
@ComponentV2
struct MyCounter {
@Param title: string = '';
@Param value: number = 0;
build() {
Column() {
Text(`${this.title}: ${this.value}`)
}
}
}
@ComponentV2
struct Parent {
@Local value1: number = 0;
@Local value2: number = 100;
build() {
Column() {
MyCounter({ title: '计数器A', value: this.value1 })
MyCounter({ title: '计数器B', value: this.value2 })
Button('同步+1').onClick(() => { this.value1++; this.value2++; })
}
}
}
```
##### ③ @Event — 子组件触发父组件更新
```typescript
@ComponentV2
struct Child {
@Param index: number = 0;
@Event changeIndex: (val: number) => void = () => {};
build() {
Button(`index=${this.index}, 修改为20`)
.onClick(() => { this.changeIndex(20); })
}
}
@ComponentV2
struct Parent {
@Local index: number = 0;
build() {
Child({ index: this.index, changeIndex: (v) => { this.index = v; } })
}
}
```
##### ④ @Provider/@Consumer — 跨层级状态共享
```typescript
// Parent — 提供者
@ComponentV2
struct GrandParent {
@Provider('count') count: number = 0;
build() { ChildList() } // 无需传参，中间组件不需要 "透传"
}
@ComponentV2
struct ChildList {
build() { Column() { GrandChild() } }
}
// GrandChild — 消费者（任意深度的后代都直接消费）
@ComponentV2
struct GrandChild {
@Consumer('count') count: number = 0;
build() {
Text(`count from grand parent: ${this.count}`)
}
}
```
##### ⑤ @Computed — 计算属性（替代手动同步）
```typescript
@ComponentV2
struct ShoppingCart {
@Local count: number = 0;
@Local price: number = 15;
@Computed
get total(): number { return this.count * this.price; }
build() {
Column() {
Text(`数量: ${this.count}, 单价: ${this.price}元`)
Text(`总金额: ${this.total}元`) // 自动缓存、依赖变化才重算
Button('+1').onClick(() => { this.count++; }) // total 自动更新
}
}
}
```
##### ⑥ @Monitor — 监听状态变化（替代 @Watch）
```typescript
@ComponentV2
struct DemoMonitor {
@Local index: number = 0;
@Local change: string = '';
// 监听单个状态
@Monitor('index')
onIndexChange(monitor: IMonitor) {
const before = monitor.value?.before;
const now = monitor.value?.now;
this.change = `index 从 ${before} 变为 ${now}`;
}
// 批量监听
@Monitor('index', 'data')
onBatchChange(monitor: IMonitor) {
monitor.dirty.forEach((path: string) => {
console.log(`${path}: ${monitor.value(path)?.before} → ${monitor.value(path)?.now}`);
});
}
build() {
// ...
}
}
```
##### ⑦ @ObservedV2 + @Trace — 深度观测对象属性
```typescript
@ObservedV2
class Student {
name: string = '李华';
age: number = 20;
@Trace major: string = '软件工程'; // 只观察 major 的变化
}
@ComponentV2
struct DemoDeepObserve {
@Local student: Student = new Student();
// 甚至能深度监听嵌套属性
@Monitor('student.major')
onMajorChange(monitor: IMonitor) {
console.log(`专业变更: ${monitor.value?.before} → ${monitor.value?.now}`);
}
build() {
Column() {
Text(`姓名: ${this.student.name}`)
Text(`年龄: ${this.student.age}`)
Text(`专业: ${this.student.major}`)
Button('修改专业').onClick(() => {
this.student.major = '物联网'; // ✅ 页面会更新 + Monitor 触发
})
}
}
}
```
#### 7.3 V1 → V2 迁移对照
| V1 | V2 | 注意 |
|:--|:---|:-----|
| `@Component` | `@ComponentV2` | V2 组件内不能用 V1 装饰器 |
| `@State` | `@Local` | 完全等价 |
| `@Prop` | `@Param` | Param 不支持双向绑定，需配合 @Event |
| `@Link` | `@Event` | Link 是双向，Event 是单向回调 |
| `@Provide`/`@Consume` | `@Provider`/`@Consumer` | API 相同但 key 字符串匹配 |
| `@Watch` | `@Monitor` | Monitor 更强大：可批量、可取 before/now |
| `@Observed` | `@ObservedV2` | V2 需配合 @Trace |
| `@ObjectLink` | `@Trace` | Trace 粒度更细 |
| 无直接替代 | `@Computed` | V1 需手动同步计算，V2 自动缓存 |
| 无直接替代 | `@Once` | 初始化后不再更新 |
### 8. 高级架构与性能实战（复杂场景深度指南）
> 针对中大型 App 的架构设计、性能瓶颈排查、多设备复杂适配等场景。
> 基础功能请参考第 11 节代码模板库；本节聚焦**架构决策和调优策略**。
#### 8.1 🏗️ ArkTS 架构模式
| 模式 | 适用场景 | ArkTS 实现要点 |
|:---|:---|:---|
| **MVVM** | 中大型 App、需要单元测试 | View = @Component struct；ViewModel = 普通类 + @Observable；Model = 数据层；通过 @Inject/@Provider 解耦 |
| **Repository** | 多数据源统一访问（网络+本地缓存） | Repository 类封装数据获取逻辑，内部判断走 RDB 缓存还是网络请求，对外暴露统一接口 |
| **单例管理** | 全局唯一实例（用户信息、网络客户端） | `class UserManager { private static instance: UserManager; static getInstance() { ... } }` |
| **事件总线替代** | 跨组件通信（非父子关系） | 用 `AppStorage` + `@Watch` 或 `emitter` 模块（`@ohos.events.emitter`）替代传统 EventBus |
**MVVM 快速脚手架**：
```typescript
// [API 23+] ViewModel 层 — 可被单元测试
@Observed
class LoginViewModel {
@Trace phone: string = '';
@Trace password: string = '';
@Computed get isLoginEnabled(): boolean {
return this.phone.length >= 11 && this.password.length >= 6;
}
async doLogin(): Promise<void> { /* ... */ }
}
// View 层
@ComponentV2
struct LoginPage {
@Local viewModel: LoginViewModel = new LoginViewModel();
build() {
// 绑定 viewModel 属性，自动响应更新
}
}
```
#### 8.2 ⚡ 性能优化清单 — 从 5s 到 1s 的冷启动实战
> 以下内容基于华为云社区《HarmonyOS APP 开发：冷启动优化与启动加速实战》（2026-06-23）及官方性能最佳实践。
> 核心策略：**三减一加** — 减同步任务 · 延非核心 · 并并行 · 加缓存预加载
##### 启动阶段耗时分析
| 阶段 | 典型耗时 | 优化空间 | 瓶颈 |
|:---|:-------:|:--------:|:----|
| Application.onCreate | 800~2000ms | **最大** | SDK 全家桶同步初始化 |
| AbilityStage.onCreate | 100~300ms | 中等 | 非必要 Stage 代码 |
| Ability.onCreate | 300~800ms | 较大 | 页面数据加载 + 组件初始化 |
| 首帧渲染 | 500~1500ms | **较大** | 布局层级 · 资源加载 · 串行请求 |
| **合计** | **1700~5100ms** | **→ 1050ms** | **优化幅度 79%** |
##### ① Application 初始化减负 (2250ms → 250ms, -89%)
```typescript
// ❌ 优化前：所有 SDK 同步初始化，约 2250ms
AnalyticsSDK.init(this.context); // 300ms
PushSDK.init(this.context); // 500ms
CrashSDK.init(this.context); // 200ms
NetworkManager.init(this.context); // 150ms
DatabaseManager.init(this.context); // 800ms
ImageLoader.init(this.context); // 200ms
SharedPreferences.init(this.context); // 100ms
// ✅ 优化后：只留首屏必需，其他延迟，约 250ms
NetworkManager.init(this.context); // 首屏数据请求必需
SharedPreferences.init(this.context); // 首屏配置读取必需
// 其余通过 StartupTaskScheduler 延迟
```
##### ② 首帧渲染优化 (1200ms → 500ms, -58%)
```typescript
aboutToAppear(): void {
this.loadFirstScreenData();
}
private async loadFirstScreenData(): Promise<void> {
// 🔄 并行请求首屏关键数据
const [headlines, banners] = await Promise.all([
this.fetchHeadlines(),
this.fetchBanners(),
]);
this.headlineList = headlines;
this.bannerList = banners;
this.isLoading = false;
// 通知首帧渲染完成 → 触发延迟初始化
StartupTaskScheduler.getInstance().notifyFirstFrameRendered();
// 非首屏数据延迟加载
this.loadSecondaryData();
}
```
##### ③ ColdStartOptimizer — 生产级冷启动优化器
```typescript
// 初始化优先级定义
enum InitPriority {
CRITICAL = 0, // 关键：Application.onCreate 同步执行
HIGH = 1, // 高：首帧后立即执行
NORMAL = 2, // 普通：首帧后延迟执行
LOW = 3, // 低：空闲时执行
}
// 完整优化器（详见文末代码模板）
export class ColdStartOptimizer {
static getInstance(): ColdStartOptimizer;
executeCriticalTasks(): void; // 同步关键任务 ~250ms
executeHighPriorityTasks(): void; // 首帧后立即
executeNormalPriorityTasks(): void;// 首帧后延迟
executeLowPriorityTasks(): void; // 空闲时
}
```
**StartupTaskScheduler 调度器**：
```typescript
export class StartupTaskScheduler {
static getInstance(): StartupTaskScheduler;
runAfterFirstFrame(task: () => void): void; // 首帧渲染后立即执行
runWhenIdle(task: () => void): void; // 空闲时执行（延迟1s）
notifyFirstFrameRendered(): void; // 由页面在数据加载完成后调用
}
```
##### ④ 完整优化效果对比
| 阶段 | 优化前 | 优化后 | 降幅 |
|:---|:-----:|:-----:|:----:|
| Application.onCreate | 2250ms | 250ms | -89% |
| Ability.onCreate | 500ms | 100ms | -80% |
| 首帧渲染 | 1200ms | 500ms | -58% |
| **冷启动总耗时** | **5100ms** | **1050ms** | **-79%** |
##### ⑤ 快速排查清单
- **长列表卡顿** → `LazyForEach` + `IDataSource` + `cachedCount`，替代 `ForEach`
- **频繁重绘** → 拆分 @State 大对象，或改用 `@Observed` + `@ObjectLink` 按需监听
- **首屏白屏** → 骨架屏 + `Promise.all` 并行请求 + 延迟加载非关键数据
- **内存泄漏** → `aboutToDisappear` 清理 Timer/subscription/http destroy，配合 JSLeakWatcher（API 26+）
- **ANR/卡死** → 耗时操作移至 `TaskPool.execute()`
- **HAP 包过大** → ohpm 按需引入 + HSP 动态共享包 + 图片 WebP
**内存泄漏排查三步法**：
```
① DevEco Profiler → Heap Snapshot 对比进入页面前后
② 找到引用链：谁还在持有已销毁页面的对象？
③ 最常见泄漏点：Timer 未清除 · 订阅未 off · http 未 destroy · 闭包隐式引用 @Component
```
**API 26 新增冷启动工具**：
- `onFirstFrameDrawn` 回调：系统侧通知首帧渲染完成时机
- `AppStartup` 框架：声明式启动任务配置，自动管理依赖和执行顺序
- 冷启动自动追踪：DevEco Profiler 自动标记启动阶段耗时
- Application.onCreate 超时限制 5s（HarmonyOS 6+）
**ArkUI 渲染优化原则**：
- `build()` 内不要做计算 → 提前在成员方法中算好
- 避免在 `build()` 内创建新对象（`new Xxx()` / `{ key: value }` 字面量）
- `if/else` 控制显隐优于 `visibility: Visibility.Hidden`（后者仍占布局空间）
- 长图片列表用 `CachedImage` 替代 `Image`（系统级缓存管理）
#### 8.3 📱 复杂多设备适配
| 场景 | 方案 | 关键 API |
|:---|:---|:---|
| **折叠屏展开/收起** | 监听折叠态切换布局 | `window.on('foldStatusChange')` + 断点枚举 |
| **平板双栏/手机单栏** | BreakpointType 条件布局 | `BreakpointType<'sm'|'md'|'lg'>` + `@AsMeasure` |
| **2in1 键盘/平板模式** | 检测鼠标/键盘输入方式 | `pointerDevice` + 输入法模式判断 |
| **车机窄屏适配** | 安全驾驶约束 | `DriveSafetyMode` + 简化 UI 交互 |
**折叠屏断点速查**：
| 设备状态 | 断点值 | 典型宽度 | 建议布局 |
|:---|:---|:---|:---|
| 手机折叠 | `sm` | <600vp | 单栏 |
| 手机展开/平板竖屏 | `md` | 600~840vp | 双栏（列表+详情） |
| 平板横屏/桌面 | `lg` | >840vp | 三栏或多面板 |
#### 8.4 🔗 分布式流转进阶
| 能力 | API | 适用版本 | 核心限制 |
|:---|:---|:---:|:---|
| **跨设备数据同步** | `@ohos.distributedDataObject` | API 9+ | 需同一华为账号登录 + 同一局域网 |
| **跨设备文件分享** | `@ohos.file.pasteboard` 分布式剪贴板 | API 10+ | 文件大小受限 |
| **跨设备拉起** | `startAbility()` + `deviceIds` | API 9+ | 目标设备需安装同应用 |
| **碰一碰精准分享** | `@kit.ShareKit` harmonyShare | API 26 | 见第 6.2 节完整规格 |
**分布式开发注意事项**：
- 必须处理**目标设备无响应**异常（设备离线/网络断开）
- 数据同步冲突策略：**最后写入胜出** 或 **自定义合并**
- 敏感数据流转前确认用户授权（隐私合规）
### 9. 弃用/移除公告（影响兼容性）
- **API 26 起正式移除**：`router.pushUrl()` → 强制使用 Navigation
- **API 26 起正式移除**：`globalThis` → 使用 UIContext/AppStorage/LocalStorage
- **API 26 起正式移除**：`@StorageLink` → 改用 `@LocalStorageProp`/`@LocalStorageLink`
- **API 25 起弃用**：`@ohos.data.preferences` → 改用 `@kit.ArkData` → `{ preferences }`
- **API 23→26 import 路径变更**：`@ohos.xxx` → `@kit.xxxKit`（涉及 NetworkKit、NotificationKit、DistributedServiceKit、ImageKit、FileKit、ArkData 等）
- **迁移窗口**：旧 API 在 API 26 编译报错，不再仅警告
### 10. AGC 上架全流程指南（从代码到商店）
> ⚠️ 以下内容基于 2026-06-25 更新的官方审核 Checklist，覆盖从开发前备案到上架后维护的全链路。
#### 10.1 上架前准备
**必备账户与工具**：
- 注册华为开发者账号（实名认证）
- 登录 AppGallery Connect 控制台：https://developer.huawei.com/consumer/cn/service/jsp/agc/index.html
- DevEco Studio 中登录华为账号
**📋 APP备案（中国区上架必过项）**：
> 根据监管部门要求，所有在中国大陆上架的应用必须完成 APP 备案。
- 鸿蒙版备案：在接入商备案系统填写材料时**选择"鸿蒙"平台**，添加鸿蒙包名
- 多包名备案：如存在多个包名，或同时有 App 和元服务，**所有包名均需备案**（可添加多个）
- 备案信息一致性：备案时的主体信息、应用名称、包名必须与在架信息**完全一致**
- 无需备案：单机应用（不联网）、境外应用（境外主体+境外服务器）
- ⚠️ 填写主体证件号时注意区分：`5` vs `S`、`1` vs `I`、`0` vs `O`
**应用命名规范**：
- ❌ 禁止使用**泛词**：如"免费壁纸""电话""邮件""日历"等广义归纳词汇
- ❌ 禁止与其他应用名称/图标高度相似
- ✅ 应用名称建议 30 字以内，中英文
- ⚠️ **名称图标一致性**：提交到 AGC 的应用名称、图标必须与**安装后终端显示的一致**（不能提交叫"记事本"安装后叫"小记Pro"）
**雷同应用限制**：
- 如果市场已有大量同类应用（如敲木鱼、随机选择、计时器、计算器、手电筒、记事本、记账、天气），审核可能因"功能同质化严重"被拒
- 建议在核心功能上做出差异化
**应用基本信息准备**：
- 应用图标：1024×1024 PNG，**注意需要前景图和背景图两张**（layered_image）
- 应用截图：至少 3 张，最多 8 张。**不接受设计稿或带水印的截图**，状态栏不要出现其他 App 通知
- 应用描述（中英文，200-400 字，建议分点列出核心功能）
- 隐私政策链接（必须有！域名需已备案，内容须随功能更新同步更新）
- 应用一句话简介（20 字以内，说清楚 App 是干什么的）
**分类与资质**：
- 应用分类影响审核标准和推荐位
- 游戏类需要额外提供版号、著作权等资质文件
- 涉及新闻/金融/医疗等需提供行业资质
- **AIGC 内容标识**：如果应用涉及深度合成或生成式 AI，须在生成内容中添加**显式标识**（如水印）+ 文件元数据中加**隐式标识**，并提供相关资质文件
#### 10.2 签名、混淆与打包
**签名文件（.p12/.cer/.p7b）**：
```
DevEco Studio → Build → Generate Key/CSR
→ 创建 .p12 密钥库（别名、密码、有效期建议 25 年）
→ 生成 .cer 证书请求
→ 回传华为开发者联盟获取签名证书
→ 从 AGC 下载 .p7b Profile 文件
→ 配置到 build-profile.json5 的 signingConfigs
```
**签名配置（`build-profile.json5`）**：
```json5
{
"app": {
"signingConfigs": [{
"name": "release",
"type": "HarmonyOS",
"material": {
"certpath": "./signature/release.cer",
"storePassword": "***",
"keyAlias": "release",
"keyPassword": "***",
"profile": "./signature/release.p7b",
"signAlg": "SHA256withECDSA",
"storeFile": "./signature/release.p12"
}
}]
}
}
```
⚠️ **签名密码不要硬编码提交到 Git**，使用环境变量或 CI/CD 密钥管理。
**🔐 代码混淆与加固**：
```json5
// build-profile.json5 中开启混淆
{
"app": {
"products": [{
"name": "release",
"obfuscation": {
"ruleOptions": { "enable": true, "files": ["./obfuscation-rules.txt"] }
}
}]
}
}
```
```
# obfuscation-rules.txt 常用规则
-enable-property-obfuscation
-enable-toplevel-obfuscation
-keep-global-name AppStorage,LocalStorage
```
⚠️ **混淆后 mapping 文件必须保存！** 否则线上 crash 堆栈无法反混淆定位问题。
**打包**：
```
Build → Build HAP(s) / APP(s)
→ HAP：单模块包（用于调试、内测），输出到 entry/build/default/outputs/
→ APP：整包（用于上架，含所有 HAP）
```
**版本号规范**：
- `versionCode`：整数，每次递增（如 1000001 → 1000002），**不可回退**
- `versionName`：语义化版本（如 1.0.0 → 1.0.1）
- 两者在 `build-profile.json5` 的 `products[].versionCode/versionName` 中配置
#### 10.3 AGC 上架步骤
```
AppGallery Connect 控制台 → 我的应用 → 创建应用
├─ 1. 填写应用基本信息（名称、包名、分类、语言等）
├─ 2. 上传 APP/HAP 包
├─ 3. 填写应用详情页（描述、截图、更新说明、隐私标签）
├─ 4. 填写隐私标签（如实填写收集哪些个人信息及使用目的）
├─ 5. 配置分发范围（全量/按地区/按设备）
├─ 6. 提供测试账号（如果应用需要登录）
├─ 7. 提交审核
└─ 8. 等待审核结果（首次 1-3 工作日，更新 1-2 工作日）
```
**📌 测试账号要求**：
- 如果应用需要登录才能使用，**必须提供测试账号**（在提审页面的"应用审核信息"处填写）
- 测试账号不能有**权限/角色/会员/付费限制**，必须能使用全部功能
- 确保审核人员可完成"登录 → 浏览 → 操作 → 退出"全流程
**📌 隐私标签服务**：
- 在 AGC 如实填写应用收集的个人信息项和使用目的
- 标签内容必须与隐私政策一致，标签与代码实际行为一致
**📌 上架自检（推荐）**：
- 提交邀请测试时，可**同步提交"上架自检"**
- 提前感知功耗、性能、兼容性、稳定性、UX、隐私等问题
- 发现问题可提前修改，加速正式上架
#### 10.4 审核被拒常见原因与修复
> 📊 统计显示：**备案、泛词名称、隐私政策、权限声明、截图质量** 占被拒原因的 TOP 5。
**🔴 必须解决（一票否决项）**：
| 拒绝原因 | 解决方案 |
|:---|:---|
| ❌ **APP 备案未完成** | 完成备案并在 AGC 正确勾选（鸿蒙版选"鸿蒙"平台） |
| ❌ **应用名称为泛词** | 修改为有识别性的名称，不能叫"免费壁纸""计算器"等 |
| ❌ **名称/图标与实际不一致** | 提交的名称图标必须与安装后显示的一致 |
**🟡 常见问题（修复即可重新提交）**：
| 类别 | 拒绝原因 | 解决方案 |
|:---|:---|:---|
| **资质/合规** | 隐私政策链接无效 | 确保链接可访问，域名已备案 |
| **资质/合规** | AIGC 未加标识 | 生成内容须加显式标识（水印）+ 隐式标识（元数据） |
| **资质/合规** | reason 字段缺少多语种 | 应用描述需同时提供中文和英文版本 |
| **权限** | 权限声明与实际不符 | `user_grant` 权限必须有明确使用场景说明（非废话式） |
| **权限** | 权限申请不合理 | 只申请真正需要的权限，等用户触发功能时再申请 |
| **UI/体验** | 截图与功能不符 | 截图必须反映实际 UI，不能使用设计稿 |
| **UI/体验** | 深色模式显示异常 | 在深色模式下测试 UI，确保文字对比度 ≥ 3:1 |
| **UI/体验** | 多设备适配问题 | 声明支持的设备类型必须全部适配通过 |
| **功能** | 功能不完整 | 按钮点了没反应、页面空白 → 提审前自我完整测试 |
| **功能** | 未提供测试账号 | 有登录功能时必须在审核备注中提供无限制的测试账号 |
| **签名** | 签名证书不一致 | 上架用签名必须与提包签名一致 |
| **元服务** | 元服务包过大 | 元服务 HAP ≤ 10MB，资源过多需拆分 |
| **隐私** | 隐私政策弹窗缺失 | 首次启动必须弹隐私协议，用户同意后才做数据收集 |
| **隐私** | 无账号注销入口 | 设置/账号页面必须提供"注销账号"功能 |
| **市场** | 市场已有大量雷同应用 | 在核心功能上做出差异化，避免纯工具类撞车 |
#### 10.5 上架后维护
- **版本更新**：先改 versionCode/versionName → 打包 → 上传 AGC → 提交审核
- **灰度发布**：大版本建议先灰度 20% 用户，观察无严重问题再全量推送
- **审核加急**：紧急修复可申请加急审核（每月有次数限制，别滥用）
- **AB 测试**：可在 AGC 配置应用内 AB 实验
- **Crash 监控**：集成 AGC Crash SDK，崩溃率超过 **1% 应立即修复**
- **性能监控**：关注启动时间、页面加载时间、ANR 率
- **用户评价管理**：定期看差评，差评里往往藏着真问题
- **合规同步更新**：新增数据收集场景时，同步更新隐私政策和隐私标签
- **热修复**：小 Bug 可通过 ArkTS 热修复能力修，不用重新打包上架；涉及 native 代码或资源文件必须走完整发版
#### 10.6 📊 APMS 故障监控接入
> APMS（Application Performance Management Service）是 API 26 推荐的性能监控方案，集成后实时监控应用健康状态。
> 模块：`@kit.APMServiceKit` → `{ apms }`
**接入配置**：
```typescript
import { apms } from '@kit.APMServiceKit';
import { common } from '@kit.AbilityKit';
function initAPMS(context: common.UIAbilityContext): void {
apms.init(context, {
appId: 'com.example.app',
autoCollect: {
crash: true, // 崩溃自动上报
anr: true, // ANR 检测
pageLoad: true, // 页面加载性能
apiRequest: true, // 网络请求性能
startupTime: true, // 启动耗时
},
sampleRate: 0.1, // 生产环境 10%，调试可 100%
reportInterval: 60000, // 上报间隔
});
apms.on('crash', (report) => { /* 崩溃回调 */ });
}
```
**自定义埋点**：
```typescript
apms.reportMetric('payment_success_rate', success ? 1 : 0);
const timer = apms.startTimer('sync_latency');
// ... 业务逻辑
timer.stop();
```
> **实用场景**：上线后某个页面崩溃率飙升 → APMS 自动分析堆栈定位代码行，关联最近版本变更，比自己看日志快 10 倍。
#### 10.6 🔄 CI/CD 自动化（DevOps）
> hvigorw 是 Hvigor 构建系统的命令行入口，所有 IDE 里能做的构建操作都有对应的命令行参数。
> 格式：`hvigorw [taskNames...] <options>`
**4 个核心构建任务**：
| 任务 | 输出 | 用途 |
|:----|:----|:-----|
| `assembleHap` | .hap 文件 | 安装到设备（调试/内测） |
| `assembleApp` | .app 文件 | 上架应用市场（含所有 HAP） |
| `assembleHar` | .har 文件 | 发布到 ohpm 仓库的共享库 |
| `assembleHsp` | .hsp 文件 | 动态共享包（按需加载） |
**关键参数**：
| 参数 | 示例 | 说明 |
|:----|:----|:-----|
| `-p buildMode=release` | `assembleHap -p buildMode=release` | debug（默认，保留调试信息）/ release（开启混淆） |
| `-p product=default` | `-p product=release` | 指定 build-profile.json5 中的 product 配置 |
| `--mode module -p module=entry@default` | `-p module=entry@default` | 只编译指定模块，跳过无关模块 |
| `--no-daemon` | CI 环境推荐 | 不启动常驻进程，避免 CI 缓存问题 |
| `-p debuggable=true` | `-p debuggable=true` | release 模式保留调试能力（灰度测试用） |
| `--parallel` | 默认开启 | 并行构建互不依赖的模块 |
| `--no-incremental` | CI 环境有问题时回退 | 关闭增量编译，回退全量编译 |
| `--max-old-space-size=8192` | 大型项目 OOM 时 | 设置 Node.js 内存上限（MB） |
| `-d` / `--debug` | 排查构建失败 | 开启 debug 级别日志 |
| `--stacktrace` | 排查构建失败 | 打印完整异常堆栈 |
**标准 CI 流水线**（GitHub Actions / Jenkins）：
```yaml
# ① 安装依赖
ohpm install --all
# ② Code Linter
node codelinter/run/index.js .
# ③ 构建（release mode）
hvigorw assembleApp -p buildMode=release --no-daemon
# ④ 单元测试
hvigorw test -p module=entry --no-daemon
# ⑤ 上传 AGC（需 agconnect CLI 配置认证）
agconnect publish --file entry/build/default/outputs/entry-default-signed.app
```
**CI 环境注意事项**：
- 签名密码用 CI 平台的 Secret 变量（Jenkins Credentials / GitHub Actions Secrets），不要硬编码
- 环境变量：`NODE_HOME`、`JAVA_HOME`、`OHOS_SDK` 必须配置
- `ohpm install --all` 安装所有模块依赖；网络超时加 `--fetch_timeout` 和 `--retry_times`
- 增量编译：CI 全新 workspace 无缓存时 = 全量编译，需手动缓存 `build/` 和 `oh_modules/`
#### 10.7 🌐 国际化（i18n）
**资源目录结构**：
```
resources/
├── base/ # 默认（中文）
│ ├── element/string.json
│ └── media/
├── en_US/ # 英文
│ ├── element/string.json
│ └── media/
└── zh_TW/ # 繁体中文
├── element/string.json
└── media/
```
**代码中引用**：`$r('app.string.xxx')` 框架自动根据系统语言选择
**日期/数字格式化**：
```typescript
// 日期格式化（自动适配地区）
let date = new Date();
let formatter = new Intl.DateTimeFormat('en-US');
let formatted = formatter.format(date); // "6/16/2026"
// 数字格式化（千分位）
let numFormatter = new Intl.NumberFormat('de-DE');
let num = numFormatter.format(1234567.89); // "1.234.567,89"
```
### 11. 🔴 真实踩坑记录（来自实战项目，非文档搬运）
> 以下踩坑来自 QuantFlow（鸿蒙股票App）和 pet-review（鸿蒙适配）等真实项目，每个都是编译报错→排查→修复的完整记录。这是本工坊与纯文档类技能的**最大区别**。
#### ① 20个编译错误 — 根因都在 API 层类型声明
```
QuantFlow 首次编译报 20 个错误，全部指向同一个根因：
http.ets 中 api 对象没有明确的 interface 类型声明
↳ 修复：定义 Api interface + 各接口类型 + 泛型显式标注
```
**教训**：API 层必须先声明接口类型，`httpClient.get()` 必须写成 `httpClient.get<object>()`
#### ② .ts vs .ets 文件体系差异
```
http.ts 中 AppStorage.get('token') 报错 → 因为 .ts 不能访问 ArkTS 全局对象
↳ 修复：.ets 中获取后通过普通变量同步到 .ts
```
**教训**：.ts 和 .ets 模块系统不同，跨文件共享状态需在 .ets 侧中转
#### ③ 编码损坏 → 伪编译报错
```
153 个编译错误的真实根因是文件编码损坏（非 UTF-8 BOM）
一��未闭合的中文字符串导致其后 50 行全报错
```
**教训**：遇到大量(>30个)连续语法错误，先检查文件编码，别逐条修复
#### ④ 659 个错误 — for...in 循环 + 对象索引访问
```
for (let key in obj) 在 ArkTS 中禁止
colors[key] 索引访问对象属性 → 必须用 Record<string, T>
```
**教训**：`for...in` 是 TS→ArkTS 迁移时 AI 最常生成的错误代码（与解构赋值、any 并列前三）
#### ⑤ 801 个错误 — import 位置导致装饰器截断
```
Index.ets 中 import 放在错误位置 → @Entry/@Component 装饰器被截断
→ 看似语法错误，实际是结构化问题
```
**教训**：遇到"装饰器不存在"报错时，先检查上方 import 是否完整
#### ⑥ 组件 API 误用
| 组件 | ❌ 错误用法 | ✅ 正确用法 |
|------|-----------|-----------|
| Row | `.alignItems(HorizontalAlign.Center)` | `VerticalAlign` |
| Toggle | `.isOn(true)` | `.selected(true)` |
| Column | `.borderBottomWidth(1)` | `.border({ bottom: { width: 1 } })` |
| build() | 内部声明 `const x = ...` | 必须用成员方法提前计算 |
#### ⑦ 批量替换踩坑（血的教训）
```
用 sed + Python 批量替换 router.pushUrl → 从 2 个 ERROR 弄到 689 个
根因：正则无法正确处理嵌套括号结构
```
**教训**：永远不要用正则批量替换有嵌套括号的代码。IDE 全局搜索 + 肉眼审查最安全
#### ⑧ API 23→26 迁移踩坑（来自真实项目）
> 以下踩坑来自一个 HarmonyOS 6→7 迁移实战项目（智能生活助手，API 23→26）。
| 坑 | 现象 | 根因 | 解决 |
|:---|:---|:---|:---|
| **编译缓存滞留** | 明明改了代码，报的还是旧错误 | DevEco Studio 用了旧编译缓存 | Build → Clean Project → 重新 Build，别浪费时间逐行排查 |
| **三方库不兼容** | 社区库在 API 26 下编译报错 | 库未适配新 API | 等作者更新或自己 fork 改；迁移前先盘一遍依赖库兼容情况 |
| **compatibleSdkVersion 改错** | 旧设备用户全炸了，Crash 飙升 | 把 compatibleSdkVersion 也改成了 26 | 保持 23 不变，确认要放弃旧版本用户后再调 |
| **`http.destroy()` 报错** | `http.destroy(httpRequest)` 编译不过 | API 26 改为实例方法 `httpRequest.destroy()` | 全局搜索替换为实例调用 |
| **`getAvailableDevices()` 变异步** | 同步调用拿不到设备列表 | `@kit.DistributedServiceKit` 改为异步方法 | 加 await，相关调用链一起改 |
| **权限声明被拒** | AGC 审核返回"usedScene 缺失" | API 26 要求 `usedScene` 字段必填 | 补全所有 `user_grant` 权限的 usedScene 配置 |
| **签名配置失败** | 签名后安装提示证书无效 | 旧 RSA 签名在 API 26 下不推荐 | 改用 `SHA256withECDSA`，签名更小更快 |
- `@Prop` 修改 `user.name` 视图不动 → @Prop 是值副本，用 @Link 或事件回调
- `export` 修饰符缺失 → ArkTS 组件默认 internal，被其他模块引用须加 export
- ForEach 必须提供唯一键（第三个参数 `item => item.id`）
- Row/Column.alignItems 接受不同枚举类型（Row→VerticalAlign，Column→HorizontalAlign）
#### ⑨ API 26 新能力踩坑
> 以下踩坑来自实测 HarmonyOS 7 Beta 的碰一碰分享、闪控球、星盾引擎。
| 能力 | 坑 | 正确做法 |
|:---|:---|:---|
| **碰一碰分享** | 以为 `off('knockShare')` 不需要传 callback 就能全部清除 | 不传 callback 确实会清空，但**如果后续还要注册不同窗口的监听，必须显式传 callback** |
| **碰一碰分享** | `updateShareData()` 在 `share()` 之后调用，预览图不生效 | `share()` 调用前就要把预览图准备好，云端下载场景用 setTimeout 预更新再 share |
| **闪控球** | 用了 STATIC 模板后想更新内容，发现毫无变化 | STATIC 创建后不可更新，需要改 NORMAL/EMPHATIC 模板 |
| **闪控球** | 没有在 `aboutToDisappear` 中调用 `stopFloatingBall()` | 页面销毁后闪控球仍在，必须显式停止 |
| **星盾引擎** | 每天前 3 次调用正常，第 4 次开始返回空结果 | 每天每设备限 10 次，超限后不报错直接返回空，需要缓存结果 |
| **Account Kit** | 登录按钮样式在深色模式下白底白字看不清 | `LoginWithHuaweiIDButton` 自动适配主题色，但需检查应用中是否有强制覆盖样式 |
| **Account Kit** | `authorizeWithHuaweiID` 抛 SIGN_IN_FAILED | 99% 是 AGC 上配置的签名证书指纹 SHA256 不匹配 |
#### ⑩ 性能踩坑：@State 大对象 vs @Observed + @ObjectLink
```
踩坑：一个购物车对象 @State cart = { items: [], total: 0, discount: 0 }
改任意字段 → 全组件 rebuild，列表闪烁 + 性能下降 60%
↳ 修复：拆分为 @Observed CartModel + @ObjectLink 按需监听
```
**教训**：超过 3 个字段的对象不要直接用 @State，用 @Observed 装饰 class
### 12. 📋 代码模板库（30 个即用模板 + 5 个高级模式）
> 复制即用，每段带版本标注和完整 import。
>
> 🔍 **快速查找**：需要登录→#1 | 列表→#2 | 网络请求→#3 | 路由→#4 | 存储→#5 | 分页/刷新→#6-7 | 媒体→#8 | 搜索/表单→#9-10 | UI控件→#12-15 | 硬件能力→#16-26 | 系统→#27-30
#### 基础组件（#1~10：页面骨架）
| # | 模板 | 核心代码片段 |
|:-:|------|------------|
| 1 | **登录页** | `TextInput` + `Button` + loading 状态控制 |
| 2 | **LazyForEach 列表** | `IDataSource` + `List` + `LazyForEach(item => item.id)` |
| 3 | **网络请求** | `http.createHttp()` + `request()` + `destroy()` 确保资源释放 |
| 4 | **Navigation 路由** | `NavPathStack` + `pushDestinationByName` |
| 5 | **Preferences 存储** | `getPreferencesSync` + `putSync` + `flush` |
| 6 | **分页加载** | `page` 状态 + `loadMore()` 追加 + 触底检测 |
| 7 | **下拉刷新** | `Refresh({ refreshing: $$this.isRefreshing }).onRefresh()` |
| 8 | **图片选择上传** | `photoAccessHelper.selectPhotoUri(1)` |
| 9 | **搜索页** | `Search({ value: $$this.keyword }).onSubmit()` |
| 10 | **表单提交** | 验证 → `apiPost` → 提示 |
#### 功能组件（#11~30：业务能力）
> 🏷️ 倒计时/对话框→#11-12 | 底面板/轮播→#13-14 | 分享/扫码→#16-17 | 位置/通信→#18-21 | 传感器/认证→#24-26 | 后台/系统→#27-30
| # | 模板 | 核心 |
|:-:|------|-----|
| 11 | **倒计时** | `setInterval` + `@State countdown` |
| 12 | **确认对话框** | `AlertDialog.show()` |
| 13 | **底部面板** | `.bindSheet($$this.showSheet, ...)` |
| 14 | **轮播图** | `Swiper.autoPlay(true).interval(3000)` |
| 15 | **二维码生成** | `QRCode({ value: '...' })` |
| 16 | **分享** | `shareController.share()` |
| 17 | **扫码** | `scanCore.startScan()` |
| 18 | **位置获取** | `geoLocationManager.getCurrentLocation()` |
| 19 | **深色模式** | `config.colorMode === COLOR_MODE_DARK` |
| 20 | **拨打电话** | `call.makeCall()` |
| 21 | **发送短信** | `sms.sendMessage()` |
| 22 | **剪切板** | `pasteboard.getSystemPasteboard()` |
| 23 | **震动** | `vibrator.vibrate({ duration: 200 })` |
| 24 | **加速度传感器** | `sensor.on(sensor.SensorId.ACCELEROMETER)` |
| 25 | **生物认证** | `userIAM_userAuth.getAuthInstance()` |
| 26 | **网络状态监听** | `connection.on('netAvailable')` |
| 27 | **应用版本** | `context.getApplicationInfo()` |
| 28 | **后台定时任务** | `workScheduler.startWork()` |
| 29 | **键盘避让** | `setKeyboardAvoidMode(KeyboardAvoidMode.RESIZE)` |
| 30 | **文件下载（带进度）** | `request.downloadFile()` + `on('progress')` |
#### 高级模式（来自华为官方 Sample）
| 模式 | 说明 | 价值 |
|:----|------|:----:|
| **BreakpointType\<T\>** | 泛型断点配置器 | 一行代码替代5级 if-else |
| **CancelablePromise** | 异步竞态管理 | 防止连续快速操作时序错乱 |
| **AtomicService 签名** | 元服务证书链配置 | 元服务专用签名流程 |
| **折叠屏态检测** | `window.on('foldStatusChange')` | 展开/折叠布局切换 |
| **contentCover 封面取色** | `effectKit` 自适应颜色 | 动态主题色跟随封面 |
#### 窗口管理实战模板（来自官方 Codelab）
> 完整代码包含：WindowModel 单例 / 沉浸式主窗口 / 子窗口拉起 / EventHub 跨窗口通信
**WindowModel 核心方法**：
```typescript
import { window, display } from '@kit.ArkUI';
export class WindowModel {
static getInstance(): WindowModel { /* 单例 */ }
// ① 设置沉浸式（全屏 + 隐藏系统栏）
async setMainWindowImmersive(win: window.Window): Promise<void> {
await win.setWindowLayoutFullScreen(true);
await win.setWindowSystemBarEnable([]);
}
// ② 创建子窗口（底部弹出验证码/弹窗）
createSubWindow(windowStage: window.WindowStage): void {
windowStage.createSubWindow('verify_window', (err, subWin) => {
const screen = display.getDefaultDisplaySync();
const w = screen.width * 0.93, h = w / 1.25;
subWin.moveWindowTo((screen.width - w) / 2, screen.height - h);
subWin.resize(w, h);
subWin.setUIContent('pages/VerifyPage', () => {
subWin.setWindowBackgroundColor('#00000000'); // 透明背景
subWin.showWindow();
});
});
}
// ③ 销毁子窗口
destroySubWindow(subWin: window.Window): void {
subWin.destroyWindow();
}
}
// 入口 Ability
onWindowStageCreate(windowStage: window.WindowStage): void {
WindowModel.getInstance().setMainWindowImmersive();
windowStage.loadContent('pages/LoginPage');
}
```
**EventHub 跨窗口通信**：
```typescript
// 主窗口登录页 — 注册监听
aboutToAppear(): void {
const ctx = this.getUIContext().getHostContext();
ctx?.eventHub.on('HOME_PAGE', () => { this.goHome = true; });
}
aboutToDisappear(): void {
const ctx = this.getUIContext().getHostContext();
ctx?.eventHub.off('HOME_PAGE'); // ⚠️ 必须清理
}
// 子窗口 — 验证成功时通知
context.eventHub.emit('HOME_PAGE');
```
#### Graphics Accelerate 秒级启动实战（来自官方 Codelab）
```typescript
import { launchAcceleration } from '@kit.GraphicsAccelerateKit';
import { BusinessError } from '@kit.BasicServicesKit';
// Ability 入口
export default class EntryAbility extends UIAbility {
// ① 启动时：声明支持缓存后快速启动
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
if (canIUse("SystemCapability.GraphicsGame.LaunchAcceleration")) {
try {
this.context.getApplicationContext().setSupportedProcessCache(true);
} catch (error) {
console.error(`setSupportedProcessCache fail: ${(error as BusinessError).code}`);
}
}
}
// ② 退出时：检查内存镜像，切换场景
onWindowStageWillDestroy(): void {
if (canIUse("SystemCapability.GraphicsGame.LaunchAcceleration")) {
if (launchAcceleration.isLaunchMirrorEnabled()) {
// 将游戏场景切换至登录页（超时 5s）
this.gameEngine.switchToLoginScene();
}
}
}
// ③ 销毁时：若镜像未启用才做引擎析构
onDestroy(): void {
if (canIUse("SystemCapability.GraphicsGame.LaunchAcceleration")) {
if (!launchAcceleration.isLaunchMirrorEnabled()) {
this.gameEngine.destroy(); // 正常引擎析构
}
}
}
}
```
**关键说明**：
- 内存镜像制作约需 **4s**，4s 内重新进入则按正常冷启动
- 镜像启动后 **10s** 内退出则下次不加速（DFR 保护）
- 系统结合游戏热度、内存镜像数、磁盘换出量综合判定是否开镜像
- 上架建议：增加游戏健康公告闪屏后再进入镜像界面
### 13. 🆚 鸿蒙 vs 其他平台速查（帮助开发者快速迁移）
> 💡 **从哪来？** Android 开发者关注：状态管理/路由/持久化/网络 | iOS 关注：UI框架/并发/推送 | Web 关注：语言差异/状态管理/DI
>
> ⚡ **最高频迁移场景**：`useState → @State` · `Retrofit → @ohos.net.http` · `React Router → Navigation` · `Coroutine → TaskPool`
| 概念 | Android | iOS/Swift | Web/React | **鸿蒙 ArkTS** |
|:-----|:-------:|:---------:|:---------:|:-------------:|
| **UI 框架** | XML + Jetpack Compose | SwiftUI | React/JSX | ArkUI 声明式 |
| **语言** | Kotlin/Java | Swift | TypeScript | **ArkTS（强类型 TS 超集）** |
| **状态管理** | ViewModel + StateFlow | @State/@Binding | useState/Redux | **@State/@Prop/@Link/@Provide** |
| **页面路由** | NavController/Intent | NavigationStack | React Router | **Navigation + NavPathStack** |
| **并发** | Coroutine/Thread | async/await + Task | Web Worker | **TaskPool + Worker** |
| **持久化** | Room/SharedPrefs | CoreData/UserDefaults | localStorage | **Preferences + KVStore + RDB** |
| **网络请求** | Retrofit/OkHttp | URLSession | fetch/axios | **@ohos.net.http + RCP** |
| **DI 依赖注入** | Hilt/Dagger | Swinject | Context | **@kit 模块化 + HAR 分包** |
| **推送** | FCM | APNs | WebSocket | **Push Kit** |
| **支付** | Google Pay | Apple Pay | Stripe | **IAP Kit** |
| **地图** | Google Maps | MapKit | Mapbox/Leaflet | **Map Kit** |
| **相机** | CameraX | AVFoundation | getUserMedia | **CameraManager + Session** |
| **蓝牙** | BluetoothAdapter | CoreBluetooth | Web Bluetooth | **@ohos.bluetooth** |
| **生物认证** | BiometricPrompt | LocalAuthentication | WebAuthn | **userIAM_userAuth** |
| **后台任务** | WorkManager | BGTaskScheduler | Service Worker | **workScheduler** |
| **上架市场** | Google Play | App Store | Web | **AppGallery Connect** |
> 💡 **迁移价值**：任何主流平台开发者都能在表格中找到对应概念，使用鸿蒙的思维不再是从零学习，而是"迁移已知知识"。
### 14. 📚 实战项目参考（来自 OpenHarmony 开源生态）
> 以下内容基于 OpenHarmony Gitee 组织（728 仓库）中与**应用开发**直接相关的项目提炼而成。
> 涵盖智慧家居、Codelabs 学习案例、趣味入门三大方向，全部可在 Gitee 找到源码。
#### 14.1 🏠 智慧家居实训项目集
> 来源：[OpenHarmony-SIG/knowledge_demo_smart_home](https://gitee.com/openharmony-sig/knowledge_demo_smart_home)（342 Stars，已归档迁移至 AtomGit）
> 覆盖从客厅到卧室的全场景智能家居，含连接模组类（15个）、带屏IoT（8个）、Camera应用（2个）、标准设备应用（7个）共 **32 个样例**。
**标准设备应用（最贴近 App 开发者）**：
| 项目 | 技术栈 | 核心能力 | 可用于参考的场景 |
|------|--------|---------|:-------------:|
| **数字管家 DistSchedule** | ArkTS, Stage | 分布式任务调度、设备协同 | 多设备协同 App |
| **智慧中控 eTS版** | eTS, Stage | 设备发现、控制指令下发 | IoT/设备控制类 App |
| **TodoList** | ArkTS | RDB 持久化、增删改查 | 通用数据管理 App |
| **Contacts 联系人** | ArkTS | 联系人管理、搜索过滤 | 带搜索功能的列表 App |
| **智能停车 CarParkTest** | ArkTS | 车位管理、状态展示 | 地图/位置类 App |
| **坚果食谱 NutRecipes** | ArkTS | 分类浏览、详情展示 | 内容浏览类 App |
**IoT 连接模组类应用架构模式**（可用于指导智能硬件开发）：
```
┌─────────────────────────┐
│ 带屏设备（中控面板） │ ← ArkUI 界面 + 控制指令
├─────────────────────────┤
│ 分布式软总线 / MQTT │ ← 设备发现 + 通信协议
├─────────────────────────┤
│ L0 无屏设备（灯/窗帘/风扇）│ ← C/OpenHarmony LiteOS
└─────────────────────────┘
```
**关键设计模式**：智能中控面板使用发布-订阅模式下发设备控制指令，设备端通过注册回调监听状态变化。这种模式同样适用于非 IoT 的 ArkTS App 组件通信。
#### 14.2 🎓 Codelabs 官方学习案例精选
> 来源：[OpenHarmony/codelabs](https://gitee.com/openharmony/codelabs) — 分享知识与见解，一起探索代码的独特魅力。
> 共 **50+ 个 Codelab 案例**，覆盖 UI、Ability、媒体、分布式、安全、数据库、卡片、三方库等全领域。
**优秀案例（推荐优先参考）**：
| 案例 | 技术栈 | 推荐理由 |
|------|--------|---------|
| **音乐专辑-多端部署** | ArkTS, API 9 | 一次开发多端部署的最佳实践样板，含 BreakpointType 断点适配 |
| **健康生活** | ArkTS, API 9 | 完整 App 架构：首页、数据、图表、设置，可作为 App 脚手架 |
| **视频应用-多端部署** | ArkTS, API 9 | 多设备视频播放，含媒体控制栏 + 多窗口适配 |
| **分布式手写板** | ArkTS, API 10 | 分布式数据对象实时同步，跨设备画布协作 |
| **分布式新闻客户端** | ArkTS, API 10 | 分布式数据跨设备访问，新闻列表 + 详情 = 多端同步 |
**按功能分类速查**：
| 类别 | 案例 | 可学知识点 |
|------|------|-----------|
| **UI（ArkTS）** | 电子相册、自定义抽奖转盘、简易计算器、购物应用 | Canvas 绘图、LazyForEach、Grid 布局、手势交互 |
| **Ability** | UIAbility生命周期、Stage页面跳转、Ability创建 | 生命周期回调、页面路由栈、Ability间通信 |
| **动画** | 动效示例、转场动画、自定义下拉刷新 | 属性动画、显式动画、Transition |
| **媒体** | 视频播放器、音乐播放器、图片编辑 | AVPlayer、媒体库 API、Image 编辑 |
| **分布式** | 分布式手写板、新闻客户端、游戏手柄、亲子早教 | DistributedDataObject、分布式网络、数据跨端 |
| **数据管理** | 关系型数据库、首选项、备忘录、应用内字体调节 | RDB、Preferences、数据持久化 |
| **安全** | 运行时权限、字符串加解密 | 权限请求、Cipher 加密 |
| **卡片** | 电影卡片、计步器卡片 | 卡片UI、定时刷新、点击事件 |
| **Native** | Native C++ 模板、XComponent 使用 | NAPI 接口、C++ 与 ArkTS 互调 |
> 💡 **使用建议**：当用户需要某个功能模块的完整实现时，优先从以上 Codelabs 案例中寻找对应的参考实现。例如：要做图片编辑功能 → 参考「图片编辑」Codelab；要做跨设备数据同步 → 参考「分布式手写板」。
#### 14.3 🎮 趣味极客入门项目
> 来源：[OpenHarmony-SIG/vendor_oh_fun](https://gitee.com/openharmony-sig/vendor_oh_fun) — "助燃你心中的极客梦想"
> 低门槛、高成就感的开源项目，适合向初学者展示鸿蒙的可能性。
| 项目 | 目标 | 适合向用户推荐的理由 |
|------|------|-------------------|
| **旧键盘改蓝牙键盘**（Neptune HID） | 用 OpenHarmony 开发板 + 杜邦线把旧键盘变成无线蓝牙键盘 | 极客范、成本低、零基础也能复现 |
| **BearPi 智能养花机**（BearPi+传感器） | 自动检测土壤湿度、自动浇水 | IoT 入门经典项目，软硬结合 |
> 💡 **使用建议**：当用户是初学者、对鸿蒙感到畏难时，用这些项目说明"不要被 700+ 仓库吓到，起步可以很小很酷"。
> 注意：这两个项目是 C/C++ 硬件开发（L0~L2 层），不是 App 开发。如果用户想了解纯软件趣味项目，推荐 14.2 中的「自定义抽奖转盘」「简易计算器」等 Codelabs 案例。
### 15. 👤 Account Kit 账号服务集成
> 华为账号一键登录基于 OAuth 2.0 + OpenID Connect。几乎所有 App 都需要。
> 核心模块：`@kit.AccountKit` → `authentication`（授权）+ `LoginWithHuaweiIDButton`（登录按钮组件）
**前置条件**：
1. AGC 控制台创建应用 → 开通 Account Kit
2. 配置签名证书指纹（SHA256，在 AGC "常规 → 应用 → 证书指纹" 处配置）
3. 获取 Client ID（在 AGC "常规 → 应用" 查看，若与 App ID 相同则无需额外配置）
4. 配置 `module.json5`：如 Client ID 与 App ID 不同，在 metadata 中配置 `client_id`
5. 申请权限：`quickLoginMobilePhone`（在 AGC "开发与服务" 中申请）
**一键登录（推荐方式 — 使用系统 UI 组件）**：
```typescript
import { LoginWithHuaweiIDButton, loginComponentManager } from '@kit.AccountKit';
import { BusinessError } from '@kit.BasicServicesKit';
// 在 UI 中使用 LoginWithHuaweiIDButton 组件
// 用户点击后自动拉起华为账号授权页，无需自己拼授权 URL
@Entry
@Component
struct LoginPage {
build() {
Column() {
// 华为账号一键登录按钮（系统级 UI 组件）
LoginWithHuaweiIDButton({
controller: new loginComponentManager.LoginWithHuaweiIDController(),
onSuccess: (code: string) => {
// code = Authorization Code（一次性）
// → 发送到应用后端换取 access_token + unionID + 手机号
yourBackend.exchangeAuthCode(code);
},
onError: (err: BusinessError) => {
console.error('登录失败:', err.code, err.message);
},
})
.width(300).height(48);
}
}
}
```
**程序化授权（高级方式 — 自己控制 UI）**：
```typescript
import { authentication } from '@kit.AccountKit';
// 请求匿名手机号用于登录页展示
const request: authentication.AuthorizationWithHuaweiIDRequest = {
scopes: ['openid', 'profile'],
// 如需获取手机号需先在 AGC 申请 quickLoginMobilePhone 权限
};
const authResult = await authentication.authorizeWithHuaweiID(request);
// authResult 包含 authorizationCode（一次性，给后端换 token）
```
**后端验证流程**：
```
应用前端 → 获取 authorizationCode → 传给后端
后端 → 用 authorizationCode + clientSecret 调华为 OAuth 2.0 接口
→ 获取 access_token + refresh_token
→ 用 access_token 调用户信息接口
→ 获取 unionID（应用级唯一标识，用于关联用户数据）
→ 获取 openID（会话级临时标识，不要用于持久关联）
→ 获取手机号（需 quickLoginMobilePhone 权限）
```
**与旧版 API 的区别**：
- ❌ ~~`hwAccount.getAuthorization()`~~ 已不推荐使用
- ✅ `authentication.authorizeWithHuaweiID()` + `LoginWithHuaweiIDButton` 组件
- `LoginWithHuaweiIDButton` 是系统 UI 组件，自动适配华为账号登录界面的设计规范和交互流程
**常见错误码**：
- `CANCEL`：用户取消登录
- `NETWORK_ERROR`：网络异常
- `SIGN_IN_FAILED`：登录失败（检查签名指纹配置和 Client ID）
### 16. 🏭 行业实践参考（官方行业解决方案）
> 来源：华为开发者联盟「HarmonyOS行业解决方案」— 覆盖 17 个行业，提供从架构到常见问题的完整开发方案。
> 以下精选 5 个最常见行业进行概要说明。
| 行业 | 核心能力需求 | 涉及 Kit | 官方方案要点 |
|:----|------------|---------|-------------|
| **新闻阅读** | 富文本渲染、离线缓存、个性化推荐 | ArkUI, Network Kit, Preferences, Push Kit | 多端列表 + 详情架构、离线阅读策略 |
| **影音娱乐** | 视频播放、音频控制、投屏、DRM | Media Kit, AVSession, AVCodec | 播放器组件化、多窗口适配 |
| **便捷生活** | 地图、位置、支付、推送、卡片 | Map Kit, Location Kit, IAP, Push, Form Kit | 服务卡片集成、元服务快速入口 |
| **社交通讯** | 即时消息、音视频通话、文件传输 | Network, Push, Camera, Audio | WebSocket 长连接 + 消息可靠投递 |
| **购物比价** | 商品列表、搜索、支付、物流跟踪 | List, Search, IAP, LiveView, Map | 闪控窗比价、实况窗物流跟踪 |
**行业实践通用架构模式**：
```
┌─────────────────────────────────┐
│ UI 层 (ArkUI) │ ← 多端适配（手机/平板/折叠屏）
├─────────────────────────────────┤
│ Ability 层 (Stage 模型) │ ← UIAbility + ServiceExtAbility
├─────────────────────────────────┤
│ 业务逻辑层 (Service Kit) │ ← Account/Push/IAP/Map 等
├─────────────────────────────────┤
│ 数据层 (Preferences/RDB/HSP) │ ← 本地持久化 + 模块化共享
└─────────────────────────────────┘
```
### 17. 参考文件
详细知识存储在 `references/` 目录中：
- `references/arkts-patterns.md` — ArkTS 核心编程模式（泛型、异步、并发）
- `references/arkui-components.md` — ArkUI 组件最佳实践（布局、列表、弹窗等）
- `references/state-management.md` — 状态管理模式全集（V1/V2 装饰器对比）
---
## 🔧 使用说明
当用户提出鸿蒙开发相关问题时：
1. **明确阶段**：判断用户处于编码/调试/上架哪个阶段
2. **确认目标版本**：默认 API 23+，确认后标注到代码中
3. **代码是第一优先级**：用户需要代码时，先跑自检清单再输出
4. **检查废弃 API**：输出代码时自动扫描是否含旧 API
5. **版本标注**：每个代码块首行注释标注 API 版本：`// [API 23+] 说明`
6. **上架护航**：用户要发布时，按 AGC 章节逐项检查
7. **输出徽标**：代码末尾追加 `// ✅ 代码质量自检通过`
### 💬 真实对话示例（快速上手）
以下是 6 个典型场景的完整对话流程，帮助你快速理解本技能的工作方式：
**示例 1：编译错误修复**
```
用户：API 26 编译报错，Navigation 路由跳转不生效
代码：router.pushUrl({ url: 'pages/Detail' })
错误：Property 'pushUrl' does not exist
你：🔍 发现使用废弃 API router.pushUrl（API 26 已正式移除）
✅ 修复方案：改用 NavPathStack
// [API 23+] Navigation 路由跳转
const stack = new NavPathStack();
stack.pushPath({ name: 'DetailPage' });
Navigation() {
...
}
```
**示例 2：新能力实现**
```
用户：API 26 碰一碰分享功能，NFC 触发后发一条链接
你：📱 碰一碰分享需要 3 步：
1. onPageShow 注册 knockShare 监听
2. 构造 SharedData（含 UTD 和 URL）
3. onPageHide 取消监听
然后给出完整 TypeScript 代码示例
```
**示例 3：性能调优**
```
用户：列表 500 条数据滑动卡顿，用的 ForEach
你：⚡ 建议改用 LazyForEach 懒加载
⚠️ 注意需要实现 IDataSource 接口
⚠️ 记得加第三个参数（唯一键）
然后给出 IDataSource 实现 + List + LazyForEach 完整代码
```
**示例 4：上架问题**
```
用户：AGC 审核被拒，理由是"权限声明与实际不符"
你：📋 列出可能的原因：
1. module.json5 中声明了用不到的权限
2. 使用了 user_grant 权限但没有弹窗说明
3. 隐私标签与代码实际行为不一致
然后逐一给出检查步骤和修复方案
```
**示例 5：API 迁移**
```
用户：把这段 Kotlin 网络请求改成 ArkTS
Retrofit 接口：GET /api/users, 返回 List<User>
你：🔄 ArkTS 使用 @ohos.net.http，写法如下：
1. 定义 Response 接口
2. http.createHttp() 发起请求
3. destroy() 释放资源
// [API 23+] 网络请求封装
```
**示例 6：架构咨询**
```
用户：跨 3 个页面共享购物车数据，需要实时同步
你：🏗️ 推荐方案：AppStorage + @Watch
- 购物车数据存入 AppStorage（跨页面持久化）
- 各页面用 @Watch 监听变化
- 修改时自动同步到所有页面
如果涉及多端流转，再加分布式数据对象方案对比
```
---
## 🧩 额外 Kit 能力速查（常用但易遗漏）
> 以下 Kit 是日常开发中常用的系统能力，开发者容易忽略但官方重点推荐。
### Intents Kit（意图框架服务）— API 23+
**用途**：将应用/元服务的业务功能通过"意图"智能分发到系统入口（小艺对话、小艺搜索、小艺建议），实现智慧分发。
**核心概念**：
| 特性类型 | 系统入口 | 分发逻辑 |
|:--------|:--------|:--------|
| 习惯推荐 | 小艺建议 | 共享意图 → 系统学习规律 → 适当时机推荐服务 |
| 事件推荐 | 小艺建议 | 共享事件数据（如电影票）→ 提取时间/位置 → 提醒 |
| 位置推荐 | 小艺建议 | 地理围栏 + 融合定位 → 位置感知推荐 |
| 技能调用-语音 | 小艺对话 | AI 理解用户输入 → 调用应用功能（如"查机票"） |
| 本地搜索 | 小艺搜索 | 构建本地索引 → 关键词检索应用内容 |
**意图运行方式**：
- **意图共享**：应用主动向系统共享意图数据（动作+实体），用于本地搜索和建议
- 完成时：用户已执行的意图 → 可用于搜索和建议
- 将来时：预测的用户行为 → 可用于搜索
- **意图调用**：系统主动调用应用功能（播放音乐、查看攻略等）
**约束**：仅 Phone/Tablet/PC，仅中国大陆地区，HarmonyOS 5.0+，不支持模拟器。
---
### Data Augmentation Kit（数据增强服务）— API 23+
**用途**：在端侧构建知识库、RAG（检索增强生成）、智慧化数据检索等 AI 数据底座能力。
**提供能力**：
1. **知识加工** — 对本地文档进行解析、切片、向量化
2. **RAG** — 基于向量数据库的检索增强生成，支持本地问答
3. **智慧化数据检索** — ArkTS/C++ 双语言 SDK，支持语义检索
4. **端侧问答模型** — 轻量化端侧模型，无需联网即可问答
5. **邮件智能分析模块 ⭐** — API 26 新增 Handler，支持邮件分类、摘要、待办抽取。使用 `KnowledgeProcessor` 配置 Handler 管道
**适用场景**：本地知识库 App、智能客服、文档问答、离线 AI 助手、邮件智能分类。
---
### MindSpore Lite Kit（昇思推理框架）
**用途**：HarmonyOS 内置的轻量化 AI 引擎，支持 CPU/Kirin NPU 硬件加速，用于端侧模型推理。
**核心能力**：
- 模型转换（通用模型 → `.ms` 格式）
- 端侧推理（图像分类、目标检测、NLP 等）
- 支持 NPU 硬件加速
- 与 Core Vision Kit 配合实现端侧视觉 AI
**注意**：与 Core Vision Kit（API 26 新能力）的区别——Core Vision Kit 提供封装好的视觉能力（文字识别/人脸检测等），MindSpore Lite 是底层推理引擎，可运行自定义模型。
---
### Accessory Kit（配件接入服务）— ⭐ API 26 全新
> API 26 Beta1 **全新引入**的 Kit，面向合作配件设备及生态企业应用。
**用途**：为配件设备提供关联唤醒、系统服务联动、按需调度与安全授信管理等能力，提升配件设备接入效率。
**核心能力**：
| 能力 | 说明 |
|:----|:-----|
| 关联唤醒 | 配件插入/靠近时自动唤醒对应 App |
| 系统服务联动 | 配件可与系统服务（蓝牙、USB、NFC 等）协同工作 |
| 按需调度 | 系统根据配件类型按需分配资源 |
| 安全授信管理 | 配件设备的接入认证与安全管理 |
**典型场景**：键盘/鼠标/手写笔的配对连接优化、外接显示器自动切换桌面工作流、IoT 配件的一键接入。
**模块**：`@kit.AccessoryKit`（API 26 Beta1 全新）
**验证的 API**（自 SDK 26.0.0 .d.ts）：
```typescript
import { accessoryAccessManager } from '@kit.AccessoryKit';
// AccessManager — 配件接入管理
const accessMgr = new accessoryAccessManager.AccessManager();
// 显示配件选择器
accessMgr.showAccessPicker(
[{ discoveryType: accessoryAccessManager.DiscoveryType.PARTNER_BLE_CONNECT,
displayName: '键盘', displayImage: pixelMap,
requestAttachServiceInfo: [...] }],
(event) => { /* AccessEventInfo */ }
);
// 修改配件显示名称
accessMgr.modifyDisplayName('acc_001', '我的键盘');
// 查询已接入服务
const services = accessMgr.queryAttachedService();
// ConnectManager — 连接管理
const connMgr = new accessoryAccessManager.ConnectManager();
connMgr.registerConnectListener(attachId, (state) => { /* ChannelEventInfo */ });
connMgr.connect({ attachId, serviceName: 'P_AppAccessoryCollaboration',
channelType: accessoryAccessManager.ChannelType.PARTNER_WIFI_CHANNEL });
connMgr.disconnect(attachId);
```
---
### NearLink Kit（星闪服务）— API 23+
**用途**：低功耗、高速率短距离通信，支持星闪设备连接和数据交互。
**核心流程**：
- 中心设备：扫描发现外围设备 → 发起连接 → 数据传输
- 外围设备：发送广播 → 被中心设备发现 → 连接 → 数据传输
- API 26 新增 `startScan()` 扫描所有可发现的周边星闪设备
**典型场景**：星闪鼠标、手写笔配对连接、低功耗外设通信。
**支持设备**：Phone/PC/Tablet/TV/Car/Wearable（Car 从 API 23 开始支持）。
---
### Input Kit（输入事件注入）— ⭐ API 26 新增
**用途**：API 26 Beta1 新增输入事件注入模块，提供键盘和鼠标输入事件模拟能力。
```typescript
import { inputEventClient } from '@kit.InputKit';
// 模拟键盘输入
inputEventClient.injectEvent({
type: inputEventClient.EventType.KEY_EVENT,
keyCode: inputEventClient.KeyCode.KEY_A,
keyAction: inputEventClient.KeyAction.DOWN,
});
// 模拟鼠标点击
inputEventClient.injectEvent({
type: inputEventClient.EventType.POINTER_EVENT,
pointerAction: inputEventClient.PointerAction.DOWN,
x: 500,
y: 300,
});
```
**适用场景**：自动化测试、无障碍辅助、远程控制、外接设备驱动。
**模块**：`@kit.InputKit` → `inputEventClient`
---
### Image Kit（图像元数据）— ⭐ API 26 增强
**用途**：提供应用事件打点、日志分析、跟踪分析等维测工具。
| 能力 | 说明 |
|:----|:-----|
| 应用事件打点（hiAppEvent） | 自定义事件埋点，监控应用运行状态 |
| 日志打印（hilog） | 分级日志输出（DEBUG/INFO/WARN/ERROR/FATAL） |
| 性能跟踪（hiTraceMeter） | 分布式跟踪，跨进程性能分析 |
| Debug 调试（hidebug） | 内存/CPU/线程等调试信息获取 |
**DFX 最佳实践**：
```typescript
import { hiAppEvent } from '@kit.PerformanceAnalysisKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
// 事件打点
hiAppEvent.write('app_event', hiAppEvent.EventType.BEHAVIOR, {
'event_name': 'page_enter',
'page_url': 'pages/Index'
});
// 分级日志
hilog.info(0x0001, 'MyApp', 'User logged in: %{public}s', userId);
```
**API 26 新增能力**：
- **应用冻屏告警**：hiAppEvent 新增应用冻屏告警事件，支持订阅冻屏事件
- **灰度采集管理**：端云配合采集应用故障日志，提升应用运维能力
---
### Kit 完整生态速查
> 以下列表涵盖 HarmonyOS 所有主要 Kit，标记 ✅ 表示已在离线参考库中覆盖。
| Kit | 模块前缀 | 覆盖状态 | 说明 |
|:---|:--------|:-------:|:-----|
| AbilityKit | `@ohos.app.ability.` | ✅ | 应用/能力/上下文 |
| ArkUI | `@ohos.arkui.` | ✅ | 声明式 UI 框架 |
| ArkData | `@ohos.data.` | ✅ | 数据存储管理 |
| NetworkKit | `@ohos.net.` | ✅ | 网络通信 |
| MediaKit | `@ohos.multimedia.` | ✅ | 音视频/相机 |
| DeviceSecurityKit | `@kit.DeviceSecurityKit` | ✅ | 安全(星盾/隐私/文件审计) |
| **NotificationKit** | `@ohos.notification.` | **🆕 API 26** | 锁屏字段/半模态拉起 |
| **PDFKit** | `@kit.PDFKit` | **🆕 API 26** | 多页指定区域转图片 |
| **GameServiceKit** | `@kit.GameServiceKit` | **🆕 API 26** | 近场快传免集成 |
| **EnterpriseDataGuard** | `@ohos.bundle.dataguard` | **🆕 API 26** | 文件分级管控 |
| **EnterpriseSpace** | `@ohos.enterprise.spaceManager` | **🆕 API 26** | 双空间状态查询 |
| **DriverDevKit** | `OH_USB` | **🆕 API 26** | USB Hub 用户态驱动 |
| **LiveViewKit** | `@kit.LiveViewKit` | **🆕 API 26** | 百分比进度环 |
| **RemoteCommKit** | `@ohos.net.rcp` | **🆕 API 26** | HTTP版本/流式上传/QUIC |
| **ScenarioFusionKit** | `@kit.ScenarioFusionKit` | **🆕 API 26** | 分享Button多格式 |
| **ScanKit** | `@kit.ScanKit` | **🆕 API 26** | 默认/自定义扫码检测 |
| **AVSessionKit** | `@kit.AVSessionKit` | **🆕 API 26** | 额外键枚举 |
| **UIDesignKit** | `@kit.UIDesignKit` | **🆕 API 26** | 标题栏自定义区域 |
| **NetworkBoostKit** | `@kit.NetworkBoostKit` | **🆕 API 26** | 五元组流量描述 |
| **PreviewKit** | `OH_Preview` | **🆕 API 26** | 文件预加载加速 |
| **AccessibilityKit** | `@kit.AccessibilityKit` | **🆕 API 26** | 关怀模式 |
| **NDK** | `OH_JSVM` | **🆕 API 26** | 外部内存ArrayBuffer |
| **ImageKit 增强** | `@ohos.multimedia.image` | **🆕 API 26** | 元数据类(GIF/JFIF/TIFF/PNG/AVIS/XMP) |
| ShareKit | `@kit.ShareKit` | ✅ | 碰一碰分享（完整精学） |
| AgentKit | `@kit.AgentFrameworkKit` | ✅ | Agent 框架 - FunctionComponent/FunctionController |
| CoreVisionKit | `@kit.CoreVisionKit` | ✅ | 视觉AI - OCR/人脸/分割/超分/图文搜索 |
| DataAugmentationKit | `@kit.DataAugmentationKit` | ✅ | RAG/知识库 - 检索/问答/知识处理 |
| NearLinkKit | `@kit.NearLinkKit` | ✅ | 星闪 - 广告/扫描/SSAP/数据传输/CDSM |
| PerformanceAnalysisKit | `@kit.PerformanceAnalysisKit` | ✅ | 性能维测 - hiAppEvent/hilog/hiTraceMeter |
| AccountKit | `@kit.AccountKit` | ✅ | 华为账号 - 认证/登录组件 |
| IAPKit | `@kit.IAPKit` | ✅ **新增** | 应用内支付 - 商品查询/下单/收银台 |
| PushKit | `@kit.PushKit` | ✅ | 推送服务 - Token/消息/VoIP/分布式 |
| MapKit | `@kit.MapKit` | ✅ **新增** | 地图服务 - 地图组件/地点/导航/路线 |
| LocationKit | `@ohos.geoLocationManager` | ✅ | 位置服务 |
| CallServiceKit | `@kit.CallServiceKit` | ✅ **新增** | VoIP 通话/号码识别/来电查询 |
| CloudFoundationKit | `@kit.CloudFoundationKit` | ✅ **新增** | 云函数/云存储/云数据库/云资源 |
| NaturalLanguageKit | `@kit.NaturalLanguageKit` | ✅ **新增** | 分词/实体识别/文本处理 |
| CoreSpeechKit | `@kit.CoreSpeechKit` | ✅ **新增** | 语音识别(ASR) / 语音合成(TTS) |
| GraphicsAccelerateKit | `@kit.GraphicsAccelerateKit` | ✅ **新增** | 游戏快启/资源加速下载 |
| VisionKit | `@kit.VisionKit` | ✅ **新增** | 活体检测/卡证识别/文档扫描/图像分析 |
| WearEngine | `@kit.WearEngine` | ✅ **新增** | 穿戴设备管理/P2P通信/传感器 |
| Bluetooth | `@ohos.bluetooth` | ✅ | 蓝牙 |
| TelephonyKit | `@kit.TelephonyKit` | ✅ **新增** | 通话/短信/SIM卡/eSIM |
| CameraKit | `@ohos.multimedia.camera` | ✅ | 相机 |
| AudioKit | `@ohos.multimedia.audio` | ✅ | 音频 |
| CryptoArchitectureKit | `@ohos.security.cryptoFramework` | ✅ | 加解密 |
| UniversalKeystoreKit | `@ohos.security.huks` | ✅ | 密钥管理 |
| ArkGraphics2D | `@ohos.graphics.` | ✅ | 2D 图形 |
| BackgroundTasksKit | `@kit.BackgroundTasksKit` | ✅ | 后台任务 - 瞬态/持续/WorkScheduler/提醒 |
| SensorServiceKit | `@ohos.sensor` | ✅ | 传感器 |
| TestKit | `@ohos.UiTest` | ✅ | 自动化测试 |
| AppLinkingKit | `@kit.AppLinkingKit` | ✅ | 应用链接 |
| WalletKit | `@kit.WalletKit` | ✅ **新增** | 钱包服务 - 卡券/交通卡 |
| HealthServiceKit | `@kit.HealthServiceKit` | ✅ **新增** | 运动健康 - 健康数据/运动记录 |
---
### Test Kit（自动化测试框架）
**用途**：提供 ArkTS 单元测试（JsUnit）和 UI 自动化测试（UITest）能力。
**单元测试核心 API**（`@ohos/hypium`）：
- `describe/it` — 定义测试套/用例
- `beforeAll/beforeEach/afterEach/afterAll` — 生命周期
- `expect(value).assertXxx()` — 20+ 断言方法（assertEqual/assertTrue/assertDeepEquals 等）
- MockKit — 支持 `mockFunc/verify/when` 模拟对象行为
**UI 测试核心 API**（`@ohos.UiTest`）：
- `Driver.create()` — 创建驱动，查找/操作控件
- `ON.text()/type()` — 控件匹配器（按文本/类型/相对位置）
- `click()/swipe()/drag()` — 触摸操作
- `dumpLayout/screenCap` — 获取控件树/截图
**UI 测试 CLI 命令**：
```bash
# 获取当前界面控件树
hdc shell uitest dumpLayout -p /data/local/tmp/layout.json -a
# 截图
hdc shell uitest screenCap -p /data/local/tmp/screen.png
# 模拟点击
hdc shell uitest uiInput click 100 100
# 模拟滑动
hdc shell uitest uiInput swipe 10 10 200 200 500
# 方向滑动（0=左,1=右,2=上,3=下）
hdc shell uitest uiInput dircFling 2
```
---
### App Linking Kit（应用链接服务）
**用途**：提供跨应用、跨设备的深度链接能力，支持是否安装应用的不同跳转策略。
**核心能力**：
| 能力 | 说明 |
|:----|:------|
| 应用链接 | 已安装→应用内打开；未安装→浏览器网页 |
| 直达应用市场 | 未安装时直接跳转 AppGallery 下载页 |
| 延迟链接 | 未安装→缓存点击参数→安装后获取参数（10分钟缓存） |
| 聚合链接 | 跨平台跳转策略（预览页/市场页/自定义URL） |
**适用场景**：扫码直达、社交分享、广告引流、沉默唤醒、碰一碰+App Linking 组合。仅支持手动签名，不支持模拟器。
---
### Push Kit（推送服务）
**用途**：系统级推送通道，支持应用在线/离线消息推送。
**核心能力**：
| 能力 | 说明 |
|:----|:-----|
| **通知消息推送** | 显示在通知栏 |
| **数据消息推送** | 应用后台静默处理 |
| **富媒体消息** | 图文/音频 |
| **本地通知** | 无需网络 |
| **按账号推送** | 绑定 Profile ID 后按用户推送 |
| **场景化推送** | IM/VoIP/Background/Emergency 等通道 |
| **分布式消息** | 跨设备消息分发 |
| **Token 管理** | `getToken()` / `deleteToken()` / `on('tokenUpdate')` |
**本地通知模块**：`@kit.NotificationKit`
**HMS 推送服务模块**（已验证自 SDK 26.0.0）：`@kit.PushKit`
```typescript
// HMS Push Kit — 远程推送
import { pushService, pushCommon } from '@kit.PushKit';
// 获取推送 Token
const token: string = await pushService.getToken();
// 接收推送消息（在 UIAbility 中注册）
pushService.receiveMessage('IM', this.context.abilityInfo.ability, (payload) => {
// pushCommon.PushPayload — 推送消息内容
});
// 按账号绑定/解绑
await pushService.bindAppProfileId(pushCommon.AppProfileType.APP_PROFILE_ALIAS, 'user_001');
await pushService.unbindAppProfileId('user_001');
// Token 更新监听
pushService.on('tokenUpdate', this.context.abilityInfo.ability, (newToken) => {});
```
**API 26 增强**：推送实况窗消息能力新增支持 Wearable 设备。
---
### Core File Kit（文件服务增强）— ⭐ API 26
**用途**：API 26 Beta1 对 Core File Kit 进行了多项重要增强。
**① UNCACHE 模式 — C API (O_DIRECT)**：绕过 Page Cache 直接 DMA 读写，适合大文件顺序读写。
> ⚠️ 已验证：UNCACHE 是 **C API** 特性，通过 `open()` 的 `O_DIRECT` 标志位实现。**非 ArkTS `fileIo.OpenMode.UNCACHE`**。
> ArkTS 层的 `OpenMode.UNCACHE` 尚未确认是否存在，生产环境推荐走 C API 或降级到标准 Buffered I/O。
```cpp
// C/C++ 实现（API 26 Beta 首次开放）
#include <fcntl.h>
#include <unistd.h>
#include <malloc.h>
#define ALIGNMENT 4096 // 块设备扇区对齐
int fd = open(filePath, O_CREAT | O_WRONLY | O_DIRECT | O_TRUNC, S_IRUSR | S_IWUSR);
// 缓冲区必须 4K 对齐
void* buf;
posix_memalign(&buf, ALIGNMENT, ALIGNMENT);
memset(buf, 0xAA, ALIGNMENT);
write(fd, buf, ALIGNMENT); // 绕过了 Page Cache，数据直接 DMA 到磁盘
free(buf);
close(fd);
```
**关键约束**：1) 缓冲区地址必须 4K 对齐（`posix_memalign`） 2) 每次 I/O 大小必须是 4K 的整数倍 3) 文件偏移量必须 4K 对齐 4) 不适合小文件/零碎写入（会触发写入放大）
**② 沙箱跨界互访 — FD 传递 + MAC 授权**：应用与系统服务之间"零拷贝"共享文件。
```cpp
// 接收方接管跨沙箱传递的文件描述符
int ReadFromSharedFile(int sharedFd) {
// sharedFd 由 IPC 传递，内核 MAC 已授权
struct stat st;
fstat(sharedFd, &st); // 无需知道物理路径
char buf[1024];
read(sharedFd, buf, 1024);
close(sharedFd); // ⚠️ 谁接管谁 close，否则 fd 泄漏
}
```
**注意**：模块.json5 的 `donateSandboxDir` 配置方式未在官方文档中确认，上述 FD 传递方式是已验证的机制。
**③ `listFileExt()`（API 26 新增 ArkTS API，已验证签名）**：
```typescript
import { fileIo } from '@kit.CoreFileKit';
// 列出目录中所有匹配指定后缀的文件（API 26+）
// listFileExt(path: string, options?: ListFileExtOptions): Promise<string[]>
// listFileExtSync(path: string, options?: ListFileExtOptions): string[]
const files: string[] = await fileIo.listFileExt('/data/storage/el2/base/haps/entry/files', {
recursion: true, // 是否递归子目录
listNum: 100, // 最大返回数，0=不限
});
// 返回值以 / 开头，含子目录路径
// ⚠️ `mmapSync()` — Release Notes 提及但 SDK 26.0.0 中 **不存在此 API**，疑为文档笔误
```
---
### FAST Kit（快速信号处理）— ⭐ API 26 新增
**用途**：提供实数快速傅里叶变换（FFT）和智能序列预测等信号处理能力。
| 能力 | 说明 | API |
|:----|:-----|:---:|
| **FFT 变换** | 实数时域信号 ↔ 频域信号快速转换 | API 26 |
| **FFT 逆变换** | 频域信号还原为时域信号 | API 26 |
| **智能序列预测** | 接收历史采样数据预测下一时刻序列值 | API 26 |
**验证的模块和 API**（自 SDK 26.0.0 .d.ts）：
```typescript
import { mathPrediction } from '@kit.FASTKit';
interface IndexSample {
index: number; // 帧索引
timestamp: number; // 时间戳(ms)
}
// 根据内置算法预测下一帧索引
const nextIndex = mathPrediction.predictIndex([
{ index: 0, timestamp: 0 },
{ index: 1, timestamp: 16 },
{ index: 2, timestamp: 33 },
]); // throws 1023100001 if array length < 2
```
---
### Spatial Recon Kit（空间重建增强）— ⭐ API 26
**用途**：3D 空间重建能力，API 26 新增 3DGS 编辑和空间照片能力。
**验证的模块和 API**（自 SDK 26.0.0 .d.ts）：
```typescript
import { spatialRender, spatialImage } from '@kit.SpatialReconKit';
// ① 3DGS 高斯渲染 — GSPlugin
const gsNode = await spatialRender.GSPlugin.loadGSNode(scene, {
uri: 'path/to/model.gs', // 3DGS 模型文件路径
offset: 0, // 可选：数据偏移
});
// 内置特效 ID: RETRO_EFFECT_ID / COMIC_EFFECT_ID / OBRA_DINN_EFFECT_ID / COLOR_EDITING_EFFECT_ID
// ② 2D→3D 空间照片 — SpatialImageGenerator
const generator = spatialImage.SpatialImageGenerator;
// 检测设备是否支持
const supportStatus = generator.isSupport(); // SpatialImageStatus
// 准备运行环境（需下载 AI 模型）
await generator.prepareEnv((progress) => console.log(`下载进度: ${progress}%`));
// 生成 3D 模型
await generator.generate(
pixelMap, // 输入图片
spatialImage.SpatialImageModelType.MODELTYPE_GS, // GS(0) / Mesh(1)
'path/to/output.gs' // 输出路径
);
// 空间照片控制器 — 根据陀螺仪计算渲染视角
const controller = new spatialImage.SpatialImageController('path/to/model.gs');
const cameraPose = controller.calcRenderPos(gyroResponse);
```
---
### AVCodec Kit（编解码增强）— ⭐ API 26
> 以下代码和 API 签名已验证自 51CTO 深度实践文章及官方文档。
**① H.265 CBRHQ 硬件编码**（恒定码率高质量模式，API 26 新增枚举 `CBR_HQ`）：
```cpp
#include <multimedia/player_framework/native_avcodec_videoencoder.h>
#include <multimedia/player_framework/native_avcodec_base.h>
#include <multimedia/player_framework/native_avformat.h>
OH_AVCodec* encoder = OH_VideoEncoder_CreateByMime(OH_AVCODEC_MIMETYPE_VIDEO_HEVC);
OH_AVFormat* format = OH_AVFormat_Create();
OH_AVFormat_SetIntValue(format, OH_MD_KEY_WIDTH, 1920);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_HEIGHT, 1080);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_PIXEL_FORMAT, AV_PIXEL_FORMAT_NV12);
OH_AVFormat_SetDoubleValue(format, OH_MD_KEY_FRAME_RATE, 30.0);
OH_AVFormat_SetLongValue(format, OH_MD_KEY_BITRATE, 2000000); // 2Mbps
// API 26 新增：CBR_HQ 枚举
OH_AVFormat_SetIntValue(format, OH_MD_KEY_VIDEO_ENCODE_BITRATE_MODE,
OH_VideoEncodeBitrateMode::CBR_HQ);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_I_FRAME_INTERVAL, 2000);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_PROFILE, HEVC_PROFILE_MAIN);
OH_VideoEncoder_Configure(encoder, format); // 失败则降级 VBR/CBR
OH_AVFormat_Destroy(format);
// 绑定 OnNeedInputBuffer/OnNewOutputBuffer 回调 → OH_VideoEncoder_Start()
```
**对比**：CBR（<5%波动，易马赛克）vs VBR（可达300%波动）vs **CBRHQ**（<15%波动，主观画质优）
**② Audio Vivid 空间音频编码**（API 26 新增帧级元数据注入）：
```cpp
#include <multimedia/player_framework/native_avcodec_audioencoder.h>
struct SpatialMetadata { float azimuth; float elevation; float radius; };
// 在每帧音频编码时注入三维空间元数据
OH_AVBuffer* inputBuffer = OH_AudioEncoder_GetInputBuffer(encoder, bufferIndex);
memcpy(OH_AVBuffer_GetAddr(inputBuffer), pcmData, dataSize);
OH_AVFormat* vividMeta = OH_AVBuffer_GetParameter(inputBuffer);
// API 26 新增 3 个元数据 key
OH_AVFormat_SetDoubleValue(vividMeta, OH_MD_KEY_AUDIO_VIVID_AZIMUTH, meta.azimuth);
OH_AVFormat_SetDoubleValue(vividMeta, OH_MD_KEY_AUDIO_VIVID_ELEVATION, meta.elevation);
OH_AVFormat_SetDoubleValue(vividMeta, OH_MD_KEY_AUDIO_VIVID_DISTANCE, meta.radius);
OH_AudioEncoder_PushInputBuffer(encoder, bufferIndex);
```
---
### Background Tasks Kit（后台任务增强）— ⭐ API 26
**新增能力**：倒计时提醒实例对象支持重复周期 (`repeatInterval`) 和重复次数 (`repeatCount`) 参数。
```typescript
import { reminderAgentManager } from '@ohos.reminderAgentManager';
const timer = {
reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER,
triggerTimeInSeconds: 3600, // 1小时
repeatInterval: 86400, // API 26 新增：每天重复
repeatCount: 7, // API 26 新增：重复7次
// ... 其他参数
};
```
---
### ArkWeb ⚡ Chromium 132→144 升级
> API 26 Beta1 将 ArkWeb 底层 Chromium 内核从 132 升级为 **144 版本**。
> 主要影响：渲染引擎升级 → 部分 CSS/JS 行为可能变化 → 建议在升级后做回归测试。
**开发者应对**：
- 检查 Web 组件渲染是否有差异（CSS 兼容性、Flex 布局、动画性能）
- 验证 JavaScript 引擎行为（ES2024 新特性支持度更高）
- 新增 `WebviewSecurityParams` 类，可配置网页安全属性
---
### Enterprise Data Guard Kit（企业数据守护）— ⭐ API 26 新增
**用途**：API 26 Beta1 新增企业内容感知+剪贴板审计+显示风险管控能力。
**模块**：`@ohos.enterpriseDataGuard`（⚠️ 已验证：非 `@ohos.bundle.dataguard.fileguard`，`getPolicy`/`isKia` 不存在）
**已验证 API**（来源：51CTO 深度实践文章）：
```typescript
import { enterpriseDataGuard, dlpPermission } from '@ohos.enterpriseDataGuard';
// ① 剪贴板拦截审计 — 监听复制事件，判断是否拦截
dlpPermission.registerClipboardInterceptor({
onWriteEvent: async (clipboardData) => {
const text = clipboardData.getPlainText();
if (await hasSensitiveContent(text)) {
return dlpPermission.InterceptorResult.DENY;
}
return dlpPermission.InterceptorResult.ALLOW;
}
});
// ② 内容感知分析 — 创建分析引擎，检测文本中的敏感信息
const analyzer = await enterpriseDataGuard.createContentAnalyzer({
mode: enterpriseDataGuard.AnalyzerMode.HYBRID_FAST,
customPatterns: patterns,
});
const result = await analyzer.analyzeText(auditText);
// result.matches: Array<{category: string, confidence: number}>
// ③ 显示风险管控 — 开启水印/防截屏
await enterpriseDataGuard.enableDisplayRiskControl(true, {
text: `工号:${employeeId}`,
opacity: 0.03, angle: -45, density: 3,
});
```
---
### Enterprise Space Kit（企业空间）— ⭐ API 26 新增
**用途**：API 26 Beta1 新增双域隔离，独立的空间沙箱管控。
**模块**：`@kit.EnterpriseSpaceKit` → `enterpriseSpaceManager`（⚠️ 已验证：非 `@ohos.enterprise.spaceManager`）
**已验证 API**（来源：51CTO 深度实践文章）：
```typescript
import { enterpriseSpaceManager, PolicyType } from '@kit.EnterpriseSpaceKit';
// ① 查询当前进程是否在企业工作空间内（同步，极速判断）
const inWorkspace: boolean = enterpriseSpaceManager.isEnterpriseSpace();
// ② 获取工作域内已安装的应用列表
const apps: AppInfo[] = await enterpriseSpaceManager.getWorkspaceApps();
// ③ 获取工作域管控策略
const clipboardPolicy = await enterpriseSpaceManager.getSpacePolicy(
PolicyType.CLIPBOARD_RESTRICTION // 或 SCREEN_CAPTURE_RESTRICTION
);
// clipboardPolicy.value === 0 → 允许, 1 → 禁止
```
**关键**：需在 `aboutToAppear`/`onPageShow` 重新检查策略（策略有实时变更）；跨域绝对路径缓存不可复用。
---
### Driver Development Kit（驱动开发）— USB DDK
> 以下 API 签名来自 OpenHarmony 官方 USB DDK 开发指南。
**用途**：USB DDK 提供用户态 USB 设备驱动开发能力，支持非标外设（手写板、HID 设备等）。
**模块**：`OH_USB`（C API，`#include <usb/usb_ddk_api.h>`）
**完整 API 清单**（已验证）：
| API | 说明 |
|:----|:------|
| `OH_Usb_Init()` | 初始化 DDK |
| `OH_Usb_Release()` | 释放 DDK |
| `OH_Usb_GetDevices(Usb_DeviceArray*)` | 获取 USB 设备 ID 列表（按驱动配置 vid 过滤） |
| `OH_Usb_GetDeviceDescriptor(deviceId, UsbDeviceDescriptor*)` | 获取设备描述符 |
| `OH_Usb_GetConfigDescriptor(deviceId, configIndex, UsbDdkConfigDescriptor**)` | 获取配置描述符 |
| `OH_Usb_FreeConfigDescriptor(config)` | 释放配置描述符（⚠️ 必须释放，否则泄漏） |
| `OH_Usb_ClaimInterface(deviceId, interfaceIndex, &interfaceHandle)` | 声明接口 |
| `OH_Usb_ReleaseInterface(interfaceHandle)` | 释放接口 |
| `OH_Usb_SelectInterfaceSetting(interfaceHandle, settingIndex)` | 激活接口备用设置 |
| `OH_Usb_GetCurrentInterfaceSetting(interfaceHandle, &settingIndex)` | 获取当前备用设置 |
| `OH_Usb_SendControlReadRequest(handle, setup, timeout, data, &len)` | 发送同步控制读 |
| `OH_Usb_SendControlWriteRequest(handle, setup, timeout, data, len)` | 发送同步控制写 |
| `OH_Usb_CreateDeviceMemMap(deviceId, size, &devMmap)` | 创建缓冲区 |
| `OH_Usb_DestroyDeviceMemMap(devMmap)` | 销毁缓冲区（⚠️ 必须销毁，否则泄漏） |
| `OH_Usb_SendPipeRequest(pipe, devMmap)` | 发送管道请求（中断/批量传输） |
| `OH_Usb_GetNonRootHubs(&hubs, &count)` ⭐ | **API 26 新增** — 查询外接 USB Hub 列表 |
**完整开发步骤**（驱动应用→获取设备→控制传输→释放资源）：
```cpp
#include <usb/usb_ddk_api.h>
#include <usb/usb_ddk_types.h>
// ① 初始化
OH_Usb_Init();
// ② 获取设备描述符
struct UsbDeviceDescriptor devDesc;
OH_Usb_GetDeviceDescriptor(deviceId, &devDesc);
// ③ 获取配置描述符
struct UsbDdkConfigDescriptor* config = nullptr;
OH_Usb_GetConfigDescriptor(deviceId, 1, &config);
// 遍历 config->interfaces[] 找到目标接口
OH_Usb_FreeConfigDescriptor(config); // ⚠️
// ④ 声明接口
uint64_t interfaceHandle;
OH_Usb_ClaimInterface(deviceId, interfaceIndex, &interfaceHandle);
// ⑤ 控制传输（读/写）
struct UsbControlRequestSetup setup = {
.bmRequestType = 0x80, .bRequest = 0x06,
.wValue = 0x0302, .wIndex = 0x409, .wLength = 100
};
uint8_t data[100]; uint32_t len = 100;
OH_Usb_SendControlReadRequest(interfaceHandle, &setup, 5000, data, &len);
// ⑥ 批量/中断传输
UsbDeviceMemMap* mmap;
OH_Usb_CreateDeviceMemMap(deviceId, 4096, &mmap);
struct UsbRequestPipe pipe = { interfaceHandle, endpoint, timeout };
OH_Usb_SendPipeRequest(&pipe, mmap);
OH_Usb_DestroyDeviceMemMap(mmap); // ⚠️
// ⑦ 释放
OH_Usb_ReleaseInterface(interfaceHandle);
OH_Usb_Release();
```
**约束**：只能在 `DriverExtensionAbility` 生命周期内使用；需 ACL 权限 `ohos.permission.ACCESS_DDK_USB`；CMakeLists.txt 添加 `libusb_ndk.z.so`。
---
### Live View Kit（实况窗）— ⭐ API 26 增强
> 以下 API 已验证自 51CTO 深度实践文章，含创建/更新/销毁完整流程。
**模块**：`@kit.LiveViewKit` → `liveViewManager`
**核心 API 签名**：
```typescript
import { liveViewManager } from '@kit.LiveViewKit';
// ① 创建实况窗
const viewId: string = await liveViewManager.startLiveView({
type: liveViewManager.LiveViewType.DELIVERY, // 业务类型
data: {
title: '骑士正在赶往商家',
content: '距离您还有 1.2km',
expandedParams: { title: '外卖配送中', description: '请留意电话',
progress: 10, estimatedTime: '12:30' },
capsuleParams: { text: '1.2km', iconUrl: 'app.media.ic_delivery_rider' },
},
clickIntent: { bundleName: 'com.example.app', abilityName: 'EntryAbility' },
});
// ② 更新实况窗数据
await liveViewManager.updateLiveView(viewId, {
title: '骑士已取餐', content: '距离您还有 1.2km',
expandedParams: { progress: 55, estimatedTime: '12:28' },
capsuleParams: { text: '1.2km' },
});
// ③ 停止实况窗
await liveViewManager.stopLiveView(viewId);
```
**API 26 新增辅助区模板**：`expandedParams` 支持 `progress` 字段 → 自动渲染百分比进度环。
**注意事项**：
- 需权限 `ohos.permission.KEEP_BACKGROUND_RUNNING` + `ohos.permission.PUSH_MESSAGES`
- 图标必须使用系统资源标识符 `app.media.xxx`，不能传本地路径
- 应用崩溃后必须兜底清理（`onCreate` 或 `onPageShow` 检查残留）
---
### Remote Communication Kit / RCP（远程通信）
> RCP (Remote Communication Platform) 是 HarmonyOS 推荐的新一代网络请求框架，替代旧 `@ohos.net.http`。
**导入**：`import { rcp } from '@kit.RemoteCommunicationKit'`
**核心 API**：
```typescript
import { rcp } from '@kit.RemoteCommunicationKit';
// ① 创建会话（支持拦截器/DNS/安全配置）
const session: rcp.Session = rcp.createSession({
baseAddress: 'https://api.example.com',
headers: { 'X-App-Version': '1.0' },
interceptors: [new LogInterceptor()],
requestConfiguration: {
security: { tlsOptions: { tlsVersion: 'TlsV1.3' } },
dns: { dnsOverHttps: { /* ... */ } },
},
});
// ② 发起请求
const response: rcp.Response = await session.get('/users');
// 或
const postResp = await session.post('/upload', {
body: JSON.stringify({ name: 'test' }),
});
console.info(`状态: ${response.statusCode}, HTTP版本: ${response.httpVersion}`);
// ③ MultipartForm 多表单
const form = new rcp.MultipartForm({
'file': { contentOrPath: '/data/file.txt', remoteFileName: 'upload.txt' },
'description': '文件描述',
});
await session.post('/files', form);
// ④ 请求级配置
const req = new rcp.Request('/data', 'GET', undefined, undefined, undefined, undefined, {
transfer: { timeout: { connectMs: 5000, transferMs: 30000 } },
});
await session.fetch(req);
// ⑤ 关闭
session.close();
```
**API 26 新增（待验证签名）**：
- `HttpVersionSelectCallback` — HTTP/1.1 / HTTP/2 / HTTP/3 版本选择
- `HMS_Rcp_SetRequestGetDataCallback()` — C API 流式上传
- `HMS_Rcp_SetFormOrder()` — C API 有序 multipart/form-data
- QUIC 客户端数据传输 C API
> ⚠️ 以上 4 项来源于 Release Notes，未从官方 API 参考文档验证精确签名，生产中请以 IDE 提示为准。
**vs 旧 @ohos.net.http**：
| 对比 | @ohos.net.http | RCP |
|:----|:-------------:|:---:|
| 创建方式 | `createHttp()` | `createSession()` |
| 拦截器 | 无 | ✅ 内置 Interceptor 链 |
| DNS 自定义 | 无 | ✅ DnsConfiguration |
| 请求级超时 | 无 | ✅ Configuration.transfer |
| 多表单 | 手动拼接 | ✅ MultipartForm 类 |
| TLS 版本 | 有限 | ✅ SecurityConfiguration |
---
### Scenario Fusion Kit（场景融合）— ⭐ API 26 增强
**用途**：场景化分享 Button 增强，支持多格式分享。
**模块**：`@kit.ScenarioFusionKit` → `FunctionalButtonComponentManager`
**实际 API 签名**（已验证自 SDK 26.0.0 d.ts）：
```typescript
import { FunctionalButton, functionalButtonComponentManager,
atomicService, fileUriService,
FunctionalInput, functionalInputComponentManager }
from '@kit.ScenarioFusionKit';
// fileUriService — 场景化分享 URI 转换
// convertFileUris(sourceFileUris: Array<string>): Promise<Array<FileUriResult>>
// FileUriResult: { sourceUri: string, targetUri: string, targetType: TargetType }
// TargetType: UNKNOWN(0) | MEDIA(1) | FILE(2)
const results = await fileUriService.convertFileUris(['file://...']);
// FunctionalButton / FunctionalInput — 元服务功能按钮和输入组件
// functionalButtonComponentManager — 功能按钮组件管理
// atomicService — 元服务能力
```
---
### Scan Kit（扫码服务）— ⭐ API 26 增强
**用途**：API 26 新增设备扫码能力检测，扫码前先查询、避免运行时失败。
**模块**：`@kit.ScanKit`
**已验证的 API 签名**（来源：官方 API 参考 GitHub）：
```typescript
import { scanCore } from '@kit.ScanKit';
// 查询是否支持默认界面扫码（API 26+，元服务 26+）
const defaultOk: boolean = scanCore.isDefaultScanSupported();
// true → 可调用 scanBarcode 拉起系统扫码页面
// 查询是否支持自定义界面扫码（API 26+）
const customOk: boolean = scanCore.isCustomScanSupported();
// true → 可集成 customScan 自定义扫码 UI
```
---
### AVSession Kit（音视频会话）— ⭐ API 26 增强
**用途**：音视频会话新增额外键枚举，用于定义不同场景的自定义元数据键。
**模块**：`@kit.AVSessionKit`
**API 26 新增 `ExtraKey` 枚举**（已验证自 SDK 26.0.0）：
```typescript
import { avSession } from '@kit.AVSessionKit';
enum ExtraKey {
DLNA_CURRENT_URI_METADATA = 'CurrentURIMetadata',
DLNA_DIDL_LITE = 'DIDL-Lite'
}
// 使用示例：session.setAVMetaData({ [ExtraKey.DLNA_DIDL_LITE]: '<DIDL>...</DIDL>' })
```
---
### PDF Kit（PDF 服务）— ⭐ API 26 增强
**用途**：PDF 文档多页指定区域合并转图。
**模块**：`@kit.PDFKit`
**API 26 新增 `getPixelMapWithPages()`**（已验证自 SDK 26.0.0）：
```typescript
import { pdfService } from '@kit.PDFKit';
const doc = new pdfService.PdfDocument();
doc.loadDocument(path);
// 多页指定区域合并转图（API 26+）
// pageIndices: number[] — 要合并的页索引数组
// matrices: PdfMatrix[] — 每页的仿射矩阵（x, y, width, height, rotate）
// bitmapWidth/bitmapHeight — 输出位图尺寸
// options?: PixelOptions — { isGray?, drawAnnotations?, isTransparent? }
const pixelMap = doc.getPixelMapWithPages(
[0, 1, 2],
[matrix1, matrix2, matrix3],
1024, 768
);
```
---
### UI Design Kit（UI 设计）— ⭐ API 26 新增
**用途**：API 26 Beta1 新增标题栏自定义区域能力。
**模块**：`@kit.UIDesignKit`
**验证的签名**：
```typescript
import { hdsEffect, TitleBarContentOptions, BottomBuilderParams,
HdsNavigationAttribute, HdsNavDestinationAttribute }
from '@kit.UIDesignKit';
// TitleBarContentOptions (API 26 新增字段)
interface TitleBarContentOptions {
title?: HdsNavigationTitle;
menu?: HdsNavigationMenuContentOptions;
backIcon?: HdsNavigationBackButtonItemOptions;
stackBuilder?: CustomBuilder;
stackBuilderComponent?: ComponentContent;
stackBuilderContent?: BuilderType; // 🆕 API 26
bottomBuilder?: BottomBuilderParams;
divider?: HdsNavigationDividerParams;
menuItem?: HdsNavigationMenuItemOptions;
}
// BottomBuilderParams (API 26 新增字段)
interface BottomBuilderParams {
builder: CustomBuilder;
builderComponent?: ComponentContent;
builderContent?: BuilderType; // 🆕 API 26
height?: Length;
showType?: BottomBuilderShowType;
}
// BuilderType (API 26 新增)
type BuilderType = ComponentContent | BuilderOptions;
```
---
### NDK — JSVM ArrayBuffer（原生开发）— ⭐ API 26 新增
> API 签名已从官方开发指南完整验证（developer.huawei.com 2026-06-27 更新）。
**用途**：从外部已分配内存创建 `ArrayBuffer`，零拷贝（不保证）包装 Native 内存供 JS 层读写。
**模块**：`OH_JSVM`（C API，需定义 `JSVM_EXPERIMENTAL` 宏）
**完整 API 签名**：
```cpp
#define JSVM_EXPERIMENTAL // 必须！在 include jsvm.h 之前定义
#include "ark_runtime/jsvm.h"
#include "ark_runtime/jsvm_types.h"
// API 签名（已验证）
JSVM_Status OH_JSVM_CreateArrayBufferFromExternalMemory(
JSVM_Env env,
void* externalData, // 外部内存指针（必须8字节对齐）
size_t byteLength, // 内存长度
JSVM_FinalizeArrayBuffer finalizeCb, // 可选回调，ArrayBuffer被GC时调用
void* finalizeHint, // 可选，传给回调的自定义数据
bool* copied, // 输出：true=已拷贝 false=零拷贝
JSVM_Value* result // 输出：创建的ArrayBuffer对象
);
// finalizeCb 回调类型
typedef void (*JSVM_FinalizeArrayBuffer)(
JSVM_Env env, // 始终为NULL，不可使用
void* finalizeData, // 传入的 externalData
void* finalizeHint, // 传入的 finalizeHint
bool copied // 是否发生了拷贝
);
```
**完整使用流程**：
```cpp
// ① 加载外部数据（malloc，确保8字节对齐）
size_t dataSize = 16;
void* pixelData = malloc(dataSize);
// ② 创建 ArrayBuffer（不保证零拷贝，不要依赖）
JSVM_Value arrayBuffer = nullptr;
bool copied = false;
OH_JSVM_CreateArrayBufferFromExternalMemory(
env, pixelData, dataSize,
[](JSVM_Env, void* data, void*, bool copied) {
if (!copied) free(data); // 零拷贝→finalizeCb释放
}, nullptr, &copied, &arrayBuffer);
// ③ 如果已拷贝，可立即释放原内存
if (copied) free(pixelData);
// ④ 通过 GetArraybufferInfo 访问数据
void* abData = nullptr; size_t abLen = 0;
OH_JSVM_GetArraybufferInfo(env, arrayBuffer, &abData, &abLen);
```
**注意事项**：
- `externalData` 必须 8 字节对齐，否则返回 `JSVM_INVALID_ARG`
- `copied` 值随 JSVM 版本变化，**不在业务逻辑中依赖零拷贝**
- `finalizeCb` 中不能调用其他 JSVM API，仅做资源释放
- 创建失败时需手动 `free(pixelData)`
---
### Network Boost Kit（网络加速）— ⭐ API 26 新增
**用途**：五元组流量描述能力，API 26 新增精细化网络管控。
**模块**：`@kit.NetworkBoostKit`
**API 26 新增**（已验证自 SDK 26.0.0）：
```typescript
import { netBoost, netQuality, netHandover } from '@kit.NetworkBoostKit';
// 设置数据流描述（五元组精细化管控，API 26+）
const dataFlowDesc: netBoost.DataFlowDesc = {
dataFlowInfo: {
protocol: netBoost.ProtocolType.PROTOCOL_TCP, // TCP(1) / UDP(0)
local: { address: '192.168.1.1', port: 8080 },
remote: { address: '10.0.0.1', port: 443 },
},
scene: netQuality.ServiceType.AUDIO, // 业务类型（音频/视频/下载等）
sceneEvent: netBoost.SceneEvent.SCENE_EVENT_ENTER,
expectations: { // 可选：带宽/延迟期望
uplinkBandwidth?: number, // Kbps
downlinkBandwidth?: number, // Kbps
latency?: number, // ms
priority?: netBoost.PriorityLevel, // PRIO_NORMAL(0) / PRIO_HIGH(1)
lowPowerMode?: boolean,
},
};
netBoost.setDataFlowDesc(dataFlowDesc);
// 设置场景描述（API 6.0+）
netBoost.setSceneDesc({
scene: netQuality.ServiceType.AUDIO,
sceneEvent: netBoost.SceneEvent.SCENE_EVENT_LEAVE,
});
// 低功耗模式
netBoost.setLowPowerMode(true);
```
---
### Notification Kit（通知服务）— ⭐ API 26 增强
**用途**：通知管理能力增强。
**模块**：`@kit.NotificationKit`
**已验证 API**：
```typescript
import { notificationManager } from '@kit.NotificationKit';
import { common } from '@kit.AbilityKit';
// ① 锁屏通知配置（在创建渠道时设置 slot.lockscreenVisibility）
let slot: notificationManager.NotificationSlot = {
slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION,
name: '社交消息',
lockscreenVisibility: notificationManager.LockscreenVisibility.PUBLIC, // PUBLIC/PRIVATE/SECRET
};
await notificationManager.addSlot(slot);
// ② 半模态拉起通知设置（API 26+）
const context: common.UIAbilityContext = this.context;
await notificationManager.openNotificationSettingsWithResult(context, 1001);
// 在 UIAbility.onAbilityResult 中处理返回
// ③ 精细授权查询（API 26 Beta+）
// UserGrantSetting 枚举：LOCK_SCREEN | BANNER | SOUND | VIBRATION
const status = notificationManager.getUserGrantSetting(
notificationManager.UserGrantSetting.LOCK_SCREEN
);
// UserGrantStatus: ALLOWED(0) / DENIED(1) / NOT_GRANTED(2)
```
---
### Image Kit（图片处理）— 元数据 + 逆变换
**用途**：API 26 新增 6 种格式专用元数据类；API 23 起支持批量元数据读写和预览流逆变换。
**@ohos.multimedia.image 增强**：
**① 元数据读写 (API 23+)**：
```typescript
import { image } from '@kit.ImageKit';
// 读取元数据（批量，一次 I/O）
const source = image.createImageSource(fd); // ⚠️ 写权限需要 fd
const meta = await source.readImageMetadata(['ImageWidth', 'ImageLength']);
// meta.exifMetadata.imageWidth, meta.makerNoteHuaweiMetadata?.isXmageSupported
// 批量写入（内存合并事务，一次磁盘 I/O）
meta.exifMetadata.imageLength = '3072';
await source.writeImageMetadata(meta);
```
**② 预览流逆变换 (API 23+)** — 自动抵消传感器旋转角：
```typescript
// 异步
const pixelMap = await image.createPixelMapFromSurfaceWithTransformation(surfaceId, true);
// 同步（适合渲染循环）
const pxSync = image.createPixelMapFromSurfaceWithTransformationSync(surfaceId, true);
```
**③ API 26 新增 6 种格式专用元数据类** ✅ 已验证（来源：官方 API 参考）：
```typescript
import { image } from '@kit.ImageKit';
// GIF 元数据（读取 GIF 帧延迟/循环/画布）
// .delayTime: number | .unclampedDelayTime: number (ms)
// .hasGlobalColorMap: boolean | .loopCount: number (0=无限)
// .disposalType: number (0=未指定/1=不处置/2=背景色/3=前一帧)
// .canvasWidth: number | .canvasHeight: number (px)
// 读取示例：imageSource.readImageMetadataByType([image.MetadataType.GIF_METADATA])
// → metaData.gifMetadata.delayTime / .loopCount / .canvasWidth
// JPEG/JFIF 元数据
// .densityUnit: number (0=无/1=DPI/2=DPC)
// .xDensity: number | .yDensity: number
// .isProgressive: boolean | .version: number[]
// → metaData.jfifMetadata.xDensity / .isProgressive
// TIFF 元数据
// .primaryChromaticities: number[] | .whitePoint: number[]
// .tileWidth: number | .tileLength: number (px)
// .dateTime: string | .make: string | .model: string
// .artist: string | .copyright: string
// .software: string | .hostComputer: string
// .orientation: Orientation | .compression: number
// → metaData.tiffMetadata.make / .model / .dateTime / .orientation
// PNG 元数据
// .xPixelsPerMeter: number | .yPixelsPerMeter: number
// .gamma: number | .chromaticities: number[]
// .title: string | .author: string | .description: string
// .copyright: string | .creationTime: string
// .sRGBIntent: number | .interlaceType: number
// → metaData.pngMetadata.title / .author / .creationTime
// AVIS 元数据
// .delayTime: number (ms) — 仅此一个属性
// → metaData.avisMetadata.delayTime
// XMP 元数据（可扩展元数据平台，支持命名空间读写）
// const xmp = new image.XMPMetadata();
// await xmp.registerXMPNamespace({ uri: 'urn:example:book:1.0', prefix: 'book' });
// await xmp.setValue('book:title', image.XMPTagType.STRING, 'My Title');
// const tag = await xmp.getTag('book:title'); // → { name, value, type }
// await xmp.removeTag('book:title');
// xmp.enumerateTags((path, tag) => { console.info(path, tag.value); return true; }, undefined, { isRecursive: true });
// const tags = await xmp.getTags(); // Record<string, XMPTag>
// await xmp.getBlob() / .setBlob(buffer) — 二进制读写
// → 需通过 imageSource.readImageMetadataByType([image.MetadataType.XMP_METADATA])
// → metaData.xmpMetadata.registerXMPNamespace(...)
```
**读取入口**：`imageSource.readImageMetadataByType(types: MetadataType[])` 或 `pictureObj.getMetadata(type)`
---
### Game Service Kit（游戏服务）— ⭐ API 26 增强
> API 签名已验证自 51CTO 深度实践文章（API 23+ 基础 API）。
**用途**：游戏近场快传，支持安装包零流量 P2P 传输。
**模块**：`@ohos.game.nearbyTransfer`（`gameNearbyTransfer`）
**已验证的基础 API**（API 23+）：
```typescript
import { gameNearbyTransfer } from '@ohos.game.nearbyTransfer';
// 创建近场快传会话（安装包传输）
const result = await gameNearbyTransfer.create({
abilityName: 'EntryAbility',
moduleName: 'entry',
contentType: gameNearbyTransfer.ContentType.INSTALLATION_PACKAGE, // 安装包
gameLinking: 'nearbytransfer://com.example.game?type=nearbyTransfer',
});
// 订阅对端安装状态
gameNearbyTransfer.onRemoteInstallationInfoNotify((info) => {
if (info.installed) {
// 对端安装完成，可销毁当前任务并切换到资源包传输
gameNearbyTransfer.destroy(result.linkingForInstallation);
}
});
```
**API 26 新增**（已验证自 SDK 26.0.0）：
- **近场安装包 P2P 传输**的 `gameNearbyTransfer` 基础 API 已验证（API 23+），详见上方代码块
- 免集成 SDK 模式：`create()` 的 `contentType: INSTALLATION_PACKAGE` 走系统级 P2P 通道，不需集成 Game Service Kit SDK
---
### Preview Kit（预览服务）— ⭐ API 26 新增
**用途**：文件预加载与加速预览能力（API 26 Beta1 新增）。
**模块**：`@kit.PreviewKit` → `openFileBoost` / `filePreview`
**验证的 API 签名**（自 SDK 26.0.0 .d.ts）：
```typescript
// ① 文件打开加速（openFileBoost, 5.0.5+，API 26 已废弃 ⚠️）
import { openFileBoost } from '@kit.PreviewKit';
// 文件预加载状态枚举
enum FilePreloadState { NOT_PRELOADED = 0, PRELOADING = 1, PRELOADED = 2 }
interface FilePreloadStatusInfo { sandboxPath: string; progress: number; state: FilePreloadState; }
// 监听预加载状态变化
openFileBoost.on('filePreloadStateChanged', (info: FilePreloadStatusInfo) => {});
openFileBoost.off('filePreloadStateChanged');
// 添加/移除文件到预加载列表
openFileBoost.addFile('/sandbox/path/file.pdf');
openFileBoost.removeFile('/sandbox/path/file.pdf');
openFileBoost.queryFilePreloadStatusInfo('/sandbox/path/file.pdf');
// → FilePreloadStatusInfo: { sandboxPath, progress, state }
// ② 文件预览（filePreview, 4.1.0+，推荐使用 ✅）
import { filePreview } from '@kit.PreviewKit';
const context = getContext(this);
// 单文件预览
filePreview.openPreview(context, {
title: '文档.pdf',
uri: 'file://...',
mimeType: 'application/pdf',
}, { x: 0, y: 0, width: 500, height: 800 });
// 多文件预览（仅移动端）
filePreview.openPreview(context, [file1, file2, file3]);
// 检测文件是否可预览
const canPrev = await filePreview.canPreview(context, 'file://...');
// 关闭预览
filePreview.closePreview(context);
```
---
### Accessibility Kit（无障碍·关怀模式）— ⭐ API 26 新增
**用途**：无障碍能力增强，API 26 新增关怀模式支持。
**模块**：`@kit.AccessibilityKit`
**新增能力**：
- 支持应用接入系统的**关怀模式**，提升长辈关怀功能及体验
- 关怀模式：大字号、高对比度、简化交互，自动适配系统设置变更
---
### IAP Kit（应用内支付）— 新增精学
**用途**：提供应用内商品查询、下单、支付功能，支持收银台组件。
**模块**：`@kit.IAPKit`
**验证的 API 签名**（自 SDK 26.0.0）：
```typescript
import { iap, CashierComponent, cashierComponentManager } from '@kit.IAPKit';
// 商品查询
const products = await iap.queryProducts({
type: iap.ProductType.CONSUMABLE, // CONSUMABLE(0) / NON_CONSUMABLE(1) / AUTO_RENEWABLE(2)
productIds: ['com.example.coin_100', 'com.example.vip_month'],
});
// Product { productId, price, priceMicros: number, currency: string, title, description, ... }
// 创建购买（收银台）
const purchaseResult = await iap.createPurchase({
productId: 'com.example.coin_100',
type: iap.ProductType.CONSUMABLE,
autoUnlock: true, // 自动解锁
sendBroadcast: false, // 是否发广播
});
// PurchaseResult { transactionId, productId, purchaseTime, purchaseToken, orderId, ... }
// 消费/确认购买（服务端发货后调用）
await iap.finishPurchase({
purchaseToken: purchaseResult.purchaseToken,
type: iap.ProductType.CONSUMABLE,
});
// 收银台组件（声明式 UI）
// CashierComponent({ product: productItem, onResult: (result) => {} })
// 查询已购商品
const owned = await iap.queryOwnedPurchases({
type: iap.PurchaseQueryType.ALL, // ALL(0) / CONFIRMED(1) / UNCONFIRMED(2)
});
```
---
### Map Kit（地图服务）— 新增精学
**用途**：地图展示、地点搜索、路线规划导航、静态图生成。
**模块**：`@kit.MapKit`
**验证的 API 签名**（自 SDK 26.0.0）：
```typescript
import { mapCommon, map, MapComponent, MapComponentController,
site, navi, staticMap, sceneMap, petalMaps } from '@kit.MapKit';
// ① 地图组件
// MapComponent({ mapOptions, mapCallback, customInfoWindow })
// mapOptions: { center: LatLng, zoom: number, minZoom?, maxZoom?, mapType: MapType, ... }
// MapType: STANDARD(0) / SATELLITE(1) / NONE(2) / NAVI(3)
// ② 地图控制器
const controller = new MapComponentController();
controller.animateCamera({ target: { latitude: 39.9, longitude: 116.4 }, zoom: 15, duration: 500 });
// ③ 地点搜索
site.searchByText(getContext(), { query: '餐厅', location: { lat: 39.9, lng: 116.4 }, radius: 5000 })
.then(sites => sites.forEach(s => console.log(s.name, s.address, s.coordinate)));
site.nearbySearch(getContext(), { location: { lat: 39.9, lng: 116.4 }, poiType: '咖啡厅', radius: 3000 });
site.geocode(getContext(), { address: '北京市海淀区' }); // → LatLng
site.reverseGeocode(getContext(), { lat: 39.9, lng: 116.4 }); // → Address
// ④ 路线规划
const routes = await navi.getDrivingRoutes(getContext(), {
origin: { lat: 39.9, lng: 116.4 },
destination: { lat: 39.95, lng: 116.5 },
});
// routes[i].distance, .duration, .polyline, .tollCost, .trafficLights
// ⑤ 静态图
const pixelMap = await staticMap.getMapImage(getContext(), {
center: { lat: 39.9, lng: 116.4 }, zoom: 14, width: 400, height: 300
});
// ⑥ 场景地图（3D室内地图）
// sceneMap — 3D 场景展示
// petalMaps — 花瓣地图能力
```
---
### Telephony Kit（通话/短信）— 新增精学
**用途**：拨打电话、短信收发、SIM 卡管理、网络状态、eSIM。
**模块**：`@kit.TelephonyKit`
**验证的 API 签名**（自 SDK 26.0.0）：
```typescript
import { call, sms, sim, radio, data, observer, eSIM } from '@kit.TelephonyKit';
// 拨打电话
call.makeCall('10086'); // 直接呼叫
call.dial('10086', { extras: '' }); // 通过拨号盘
// 发送短信
sms.sendShortMessage(getContext(), { destinationNumber: '10086', content: 'CXLL' });
// SIM 卡信息
const simCount = sim.getSimCount(); // SIM 卡数量
const iccid = sim.getSimIccId(slotId); // ICCID
const operator = sim.getSimOperatorNumeric(); // 运营商号
const gid1 = sim.getSimGid1(slotId); // GID1
// 网络状态
radio.getRadioTech(slotId); // RADIO_TECHNOLOGY_GSM(0) / WCDMA / LTE / NR ...
radio.getSignalInformation(slotId); // 信号强度列表
// 数据连接
data.getDefaultCellularDataSlotId(); // 默认数据卡槽
data.isCellularDataEnabled(); // 数据开关状态
// eSIM 卡
// eSIM 提供 eSIM 配置下载和管理能力
// 通话/网络状态监听
observer.on('callStateChange', (state) => {});
observer.on('signalInfoChange', (infos) => {});
observer.on('networkStateChange', (state) => {});
observer.off('callStateChange');
```
---
### Wallet Kit（钱包服务）— 新增精学
**用途**：卡券管理（优惠券/会员卡）、交通卡开卡/充值/查询。
**模块**：`@kit.WalletKit`
**验证的 API 签名**（自 SDK 26.0.0）：
```typescript
import { walletPass, walletTransitCard } from '@kit.WalletKit';
// ① 卡券管理
const passClient = new walletPass.WalletPassClient(getContext());
await passClient.addPass({ passTypeId: 'com.example.membership', serialNumber: 'M001' });
const passList = await passClient.queryPass({ passTypeId: 'com.example.membership' });
const canAdd = await passClient.canAddPass({ passTypeId: 'com.example.membership' });
await passClient.updatePass({ passTypeId: 'com.example.membership', serialNumber: 'M001', data: { ... } });
await passClient.deletePass({ passTypeId: 'com.example.membership', serialNumber: 'M001' });
// ② 交通卡
const transitClient = new walletTransitCard.TransitCardClient(getContext());
const cards = await transitClient.getTransitCardInfo(); // 查询所有交通卡
const metadata = await transitClient.getCardMetadataInDevice(); // 设备支持的卡片元数据
await transitClient.addTransitCard('card_product_id'); // 开卡
await transitClient.rechargeTransitCard('card_id', 50); // 充值
await transitClient.deleteTransitCard('card_id'); // 删卡
```
---
### Health Service Kit（运动健康）— 新增精学
**用途**：运动健康数据读写、聚合查询、数据同步授权。
**模块**：`@kit.HealthServiceKit`
**验证的 API 签名**（自 SDK 26.0.0）：
```typescript
import { healthStore, healthService } from '@kit.HealthServiceKit';
// 查询健康数据
const records = await healthStore.getRecords(getContext(), {
dataType: healthStore.DataType.STEP_COUNT, // STEP_COUNT / HEART_RATE / SLEEP / ...
startTime: Date.now() - 86400000,
endTime: Date.now(),
});
// records[i].value, .time, .dataType
// 聚合查询（日/周/月统计）
const stats = await healthStore.getDailySummary(getContext(), {
dataType: healthStore.DataType.STEP_COUNT,
date: '20260701',
});
// 写入健康数据
await healthStore.insertRecord(getContext(), {
dataType: healthStore.DataType.HEART_RATE,
value: 72,
time: Date.now(),
});
// 数据同步授权
healthService.requestAuthorization(getContext(), [healthStore.DataType.STEP_COUNT]);
```
---
### Agent Kit（Agent 框架）— 精学补全
**用途**：API 26 新增 AI Agent 框架，提供声明式 UI 组件和控制器。
**模块**：`@kit.AgentFrameworkKit`
**验证的 API 签名**（自 SDK 26.0.0）：
```typescript
import { AgentController, FunctionComponent, FunctionController,
FunctionOptions, ButtonType } from '@kit.AgentFrameworkKit';
const controller = new AgentController();
const isSupported = await controller.isAgentSupport(getContext(), 'agent_id');
controller.on('agentDialogOpened', () => {});
controller.on('agentDialogClosed', () => {});
// FunctionComponent 声明式 UI 组件
// FunctionComponent({ agentId, onError, options: {
// title: '智能助手', buttonType: ButtonType.CAPSULE,
// queryText: '帮我...', iconSize: 20,
// } })
```
---
### Core Vision Kit（视觉 AI）— 精学补全
**模块**：`@kit.CoreVisionKit`
```typescript
import { textRecognition, faceDetector, faceComparator,
subjectSegmentation, imageSuperResolution, textSearchImage } from '@kit.CoreVisionKit';
// OCR 文字识别
const result = await textRecognition.recognizeText({ pixelMap: img });
console.log('识别结果:', result.value); // TextBlock[] 含文本行和单词
// 人脸检测
const faces = await faceDetector.detect({ pixelMap: img });
// faces[i].probability, .rect, .pose, .points
// 人脸比对
const cmp = await faceComparator.compareFaces({ pixelMap: face1 }, { pixelMap: face2 });
console.log('同一人:', cmp.isSamePerson, '相似度:', cmp.similarity);
// 主体分割
const seg = await subjectSegmentation.doSegmentation({ pixelMap: img }, { maxCount: 6 });
// seg.subjectCount, seg.fullSubject.foregroundImage
// 图像超分
const sr = await imageSuperResolution.ImageSRAnalyzer.create();
const result = await sr.process({ inputData: { pixelMap: lowRes } });
// 图文搜索
await textSearchImage.init();
await textSearchImage.insertImage('/path/img.jpg', 'scope1');
const results = await textSearchImage.search('日落', 'scope1', 10);
```
---
### Data Augmentation Kit（RAG/知识库）— 精学补全
**模块**：`@kit.DataAugmentationKit`
```typescript
import { retrieval, rag, knowledgeProcessor, localChatModel } from '@kit.DataAugmentationKit';
// ① RAG 问答 - 创建 RAG 会话并流式问答
const session = await rag.createRagSession(getContext(), {
llm: myChatLLM,
retrievalConfig: { channelConfigs: [{ channelType: 0, context: getContext(), dbConfig: { name: 'kb.db' } }] },
retrievalCondition: { recallConditions: [/* ... */] }
});
session.streamRun('什么是鸿蒙？', { answerTypes: [0, 1, 2] }, (err, stream) => {
console.log(stream.answer.chunk);
});
// ② 向量检索
const retriever = await retrieval.getRetriever({ channelConfigs: [/* ... */] });
const records = await retriever.retrieveRdb('查询', { recallConditions: [{ ftsTableName: 'fts', ... }] });
// ③ 知识处理（建索引）
const processor = await knowledgeProcessor.getKnowledgeProcessor(getContext(), { sourceConfig: { rdbSource: { name: 'kb.db' } } });
await processor.startProcess({ mode: 3 }); // 倒排+向量化
// ④ 本地端侧问答
await localChatModel.init();
localChatModel.chat({ questionId: 1, content: '鸿蒙' }, { isStream: true }, callback);
```
---
### NearLink Kit（星闪）— 精学补全
**模块**：`@kit.NearLinkKit`
```typescript
import { advertising, scan, manager, remoteDevice, ssap, dataTransfer } from '@kit.NearLinkKit';
// ① 发广播
const advId = await advertising.startAdvertising({
advertisingSettings: { interval: 5000, isConnectable: true },
advertisingData: { serviceUuids: ['xxxx'], includeDeviceName: true }
});
// ② 扫描设备
scan.startScan([{ /* filters */ }], { scanMode: 0, duration: 30 });
scan.on('deviceFound', (devices) => { devices.forEach(d => console.log(d.deviceName, d.rssi)); });
// ③ 连接
const device = remoteDevice.createRemoteDevice('AA:BB:CC:DD:EE:FF');
device.startPairing();
// ④ SSAP 服务
const client = ssap.createClient('AA:BB:CC:DD:EE:FF');
await client.connect();
const services = await client.getServices();
await client.readProperty({ serviceUuid: 'svc1', propertyUuid: 'prop1' });
// ⑤ 数据传输
dataTransfer.createPort('data-uuid');
dataTransfer.connect({ address: 'AA:BB:CC:DD:EE:FF', uuid: 'data-uuid' });
dataTransfer.on('readData', (params) => { console.log('收到', params.data); });
```
---
### Performance Analysis Kit（性能维测）— 精学补全
**模块**：`@kit.PerformanceAnalysisKit`
```typescript
import { hiAppEvent, hilog, hiTraceMeter, hidebug, hichecker } from '@kit.PerformanceAnalysisKit';
// 性能打点
hiAppEvent.write({ domain: 'test', name: 'loadTime', eventType: 2, params: { duration: 150 } });
// 日志
hilog.info(0xFF00, 'MyTag', '用户登录 userId=%{public}s', uid);
// 性能跟踪
hiTraceMeter.startTrace('pageLoad', 1);
// ... 业务代码
hiTraceMeter.finishTrace('pageLoad', 1);
// 内存/CPU
const pss = hidebug.getPss(); // 实际物理内存(KB)
const cpu = hidebug.getCpuUsage(); // CPU占用率
hidebug.dumpJsHeapData('/data/heap.hprof'); // 堆转储
// 代码检查
hichecker.addCheckRule(hichecker.RULE_CAUTION_PRINT_LOG); // 禁止打印日志
hichecker.addCheckRule(hichecker.RULE_THREAD_CHECK_NETWORK_USAGE); // API 26: 禁止主线程网络请求
```
---
### Background Tasks Kit（后台任务）— 精学补全
**模块**：`@kit.BackgroundTasksKit`
```typescript
import { backgroundTaskManager, workScheduler, reminderAgentManager } from '@kit.BackgroundTasksKit';
// ① 瞬态任务（延迟挂起）
const info = backgroundTaskManager.requestSuspendDelay('数据处理中', () => { /* 即将挂起 */ });
const remaining = await backgroundTaskManager.getRemainingDelayTime(info.requestId);
// ② 持续任务（需 KEEP_BACKGROUND_RUNNING 权限）
await backgroundTaskManager.startBackgroundRunning(getContext(), { backgroundTaskModes: [2], wantAgent }, );
await backgroundTaskManager.stopBackgroundRunning(getContext());
// ③ WorkScheduler
workScheduler.startWork({ workId: 1, bundleName: 'com.example', abilityName: 'WorkAbility',
networkType: 1, isCharging: true, repeatCycleTime: 3600000, isRepeat: true });
// ④ 提醒代理
const timerId = await reminderAgentManager.publishReminder({
reminderType: 0, triggerTimeInSeconds: 3600, // 倒计时
repeatInterval: 86400, repeatCount: 7, // 🆕 API 26
title: '喝水提醒', content: '该喝水了'
});
```
---
### CallServiceKit（通话服务）— 新增精学
**用途**：VoIP 通话能力，替代已废弃的 CallKit。
**模块**：`@kit.CallServiceKit`（CallKit 已废弃，推荐此替代）
**验证的 API 签名**（自 SDK 26.0.0）：
```typescript
import { voipCall, numberIdentify, CallerInfoQueryExtensionAbility } from '@kit.CallServiceKit';
// ① 上报来电
voipCall.reportIncomingCall({
callId: 'call_001',
voipCallType: voipCall.VoipCallType.VOIP_CALL_VOICE, // VOICE(0) / VIDEO(1)
userName: '张三',
userProfile: pixelMap, // 头像
abilityName: 'VoipUIExtAbility', // UIExtensionAbility 名称
voipCallState: voipCall.VoipCallState.VOIP_CALL_STATE_RINGING,
showBannerForIncomingCall: true,
}).then((err) => console.info('来电上报结果:', err));
// ② 上报呼叫状态变更
voipCall.reportCallStateChange('call_001', voipCall.VoipCallState.VOIP_CALL_STATE_ACTIVE);
// 状态：IDLE/RINGING/ACTIVE/HOLDING/DISCONNECTED/DIALING/ANSWERED/DISCONNECTING
// ③ 订阅 UI 事件（接听/挂断/静音等）
voipCall.on('voipCallUiEvent', (event) => {
// VoipCallUiEvent: VOICE_ANSWER/VIDEO_ANSWER/REJECT/HANGUP/MUTED/SPEAKER_ON 等
console.log('UI事件:', event.voipCallUiEvent, 'callId:', event.callId);
});
// ④ 号码识别
const switchState = await numberIdentify.queryNumberIdentifySwitchState(getContext());
if (switchState.isNumberIdentifyEnabled) {
// 开启号码识别
}
// ⑤ 来电信息查询扩展
class MyCallerQuery extends CallerInfoQueryExtensionAbility {
onQueryCallerInfo(phoneNumber: string): Promise<CallerInfo> {
return Promise.resolve({ contactName: '商家-XX', department: '客服部' });
}
}
```
---
### CloudFoundationKit（云基础服务）— 新增精学
**用途**：云函数、云存储、云数据库、云资源预取。
**模块**：`@kit.CloudFoundationKit`
**验证的 API 签名**（自 SDK 26.0.0）：
```typescript
import { cloudCommon, cloudFunction, cloudStorage, cloudDatabase, cloudResPrefetch } from '@kit.CloudFoundationKit';
// ① 初始化
cloudCommon.init({ region: cloudCommon.CloudRegion.CHINA });
// ② 云函数调用
const result = await cloudFunction.call({ name: 'helloWorld', data: { name: 'HarmonyOS' } });
console.log('函数返回:', result.result);
// ③ 云存储
const bucket = cloudStorage.bucket('my-bucket');
await bucket.uploadFile(getContext(), { localPath: '/data/local/tmp/test.jpg', cloudPath: '/images/test.jpg' });
await bucket.downloadFile(getContext(), { localPath: '/data/storage/downloads/test.jpg', cloudPath: '/images/test.jpg' });
const url = await bucket.getDownloadURL('/images/test.jpg');
await bucket.deleteFile('/images/test.jpg');
// ④ 云数据库
class Todo extends cloudDatabase.DatabaseObject {
title: string = '';
done: boolean = false;
naturalbase_ClassName(): string { return 'Todo'; }
}
const dbZone = cloudDatabase.zone('default');
const query = new cloudDatabase.DatabaseQuery(Todo);
query.equalTo('done', false).orderByAsc('createdAt').limit(20);
const todos = await dbZone.query(query);
// ⑤ 云资源预取
cloudResPrefetch.registerPrefetchTask({ token: 'task_token' });
const prefetchResult = await cloudResPrefetch.getPrefetchResult(cloudResPrefetch.PrefetchMode.INSTALL_PREFETCH);
```
---
### NaturalLanguageKit（自然语言）— 新增精学
**模块**：`@kit.NaturalLanguageKit`
```typescript
import { textProcessing, EntityType } from '@kit.NaturalLanguageKit';
await textProcessing.init();
// ① 分词
const words = await textProcessing.getWordSegment('今天天气真好，适合出去玩。');
// words: [{ word: '今天', wordTag: 't' }, { word: '天气', wordTag: 'n' }, ...]
// ② 实体识别
const entities = await textProcessing.getEntity('请联系张三，电话13800138000', {
entityTypes: [EntityType.NAME, EntityType.PHONE_NO]
});
// entities: [{ text: '张三', charOffset: 3, type: 'name', jsonObject: '{}' }, ...]
// EntityType: DATETIME, EMAIL, EXPRESS_NO, FLIGHT_NO, LOCATION, NAME, PHONE_NO, URL, VERIFICATION_CODE, ID_NO
await textProcessing.release();
```
---
### CoreSpeechKit（语音识别/合成）— 新增精学
**模块**：`@kit.CoreSpeechKit`
```typescript
import { speechRecognizer, textToSpeech } from '@kit.CoreSpeechKit';
// ① 语音识别（ASR）
const asrEngine = await speechRecognizer.createEngine({ language: 'zh-CN', online: 0 });
asrEngine.setListener({
onResult: (sessionId, result) => console.log('识别:', result.result),
onError: (sessionId, code, msg) => console.error('ASR错误:', msg),
onStart: (sessionId) => {},
onComplete: (sessionId) => {},
});
asrEngine.startListening({ sessionId: 's1', audioInfo: { audioType: 'pcm', sampleRate: 16000, soundChannel: 1, sampleBit: 16 } });
asrEngine.writeAudio('s1', audioBuffer);
asrEngine.finish('s1');
asrEngine.shutdown();
// ② 语音合成（TTS）
const ttsEngine = await textToSpeech.createEngine({ language: 'zh-CN', person: 0, online: 0 });
ttsEngine.setListener({
onData: (reqId, audio, resp) => { /* 合成音频流 */ },
onComplete: (reqId) => {},
onError: (reqId, code, msg) => {},
});
ttsEngine.speak('你好，欢迎使用语音合成', { requestId: 'tts_001' });
ttsEngine.stop();
ttsEngine.shutdown();
```
---
### GraphicsAccelerateKit（图形加速/游戏快启）— 新增精学
**模块**：`@kit.GraphicsAccelerateKit`
```typescript
import { assetDownloadManager, AssetAccelerationExtensionAbility, launchAcceleration } from '@kit.GraphicsAccelerateKit';
// ① 启动加速（游戏快启）
const mirrorEnabled = launchAcceleration.isLaunchMirrorEnabled();
await launchAcceleration.completeGamePrelaunch(getContext()); // 完成预启动
await launchAcceleration.terminateGamePrelaunch(getContext()); // 终止预启动
// ② 资源包下载管理
const manifestUrl = await assetDownloadManager.fetchManifestUrl();
const taskId = await assetDownloadManager.addAssetDownloadTask(getContext(), {
identifier: 'res_001', url: 'https://example.com/res.zip', isEssential: true, groupId: 'stage1',
});
assetDownloadManager.on('progress', (infos) => {
infos.forEach(i => console.log(`下载: ${i.totalBytesWritten}/${i.totalExpectedBytes}`));
});
assetDownloadManager.on('complete', (info) => console.log('完成:', info.filePath));
assetDownloadManager.on('fail', (info) => console.log('失败:', info.fault));
await assetDownloadManager.pauseAssetDownloadTask(taskId);
await assetDownloadManager.resumeAssetDownloadTask(taskId);
// ③ 资源加速 Extension（后台下载）
class MyAssetAccel extends AssetAccelerationExtensionAbility {
onDownloadContentRequest(requestType, manifestUrl, info) {
return [{ identifier: 'bg_res', url: '...', isEssential: true }];
}
}
```
---
### VisionKit（视觉 — 卡证/活体/扫描）— 新增精学
> ⚠️ 注意：VisionKit 与 CoreVisionKit 不同 — VisionKit 侧重卡证识别/活体检测/文档扫描等业务场景。
**模块**：`@kit.VisionKit`
```typescript
import { interactiveLiveness, CardRecognition, DocumentScanner, visionImageAnalyzer } from '@kit.VisionKit';
// ① 互动式活体检测
const livenessConfig = new interactiveLiveness.InteractiveLivenessConfig();
livenessConfig.isSilentMode = interactiveLiveness.DetectionMode.INTERACTIVE_MODE;
livenessConfig.actionsNum = interactiveLiveness.ActionsNumber.TWO_ACTION;
const success = await interactiveLiveness.startLivenessDetection(livenessConfig, (err, result) => {
if (result?.livenessType === interactiveLiveness.LivenessType.INTERACTIVE_LIVENESS) { /* 活体验证通过 */ }
});
// ② 银行卡/身份证识别（ArkUI 组件）
// CardRecognition({ supportType: CardType.CARD_AUTO, onResult: (result) => { ... } })
// ③ 文档扫描（ArkUI 组件）
// DocumentScanner({ scannerConfig: { supportType: [DocType.DOC], maxShotCount: 3 }, onResult })
// ④ 图像分析器（文本/主体识别、搜图）
// const controller = new VisionImageAnalyzerController();
// controller.setImageAnalyzerVisibility(0); // SHOWN
// controller.startSubjectAnalyzer();
```
---
### WearEngine（穿戴引擎）— 新增精学
**模块**：`@kit.WearEngine`
```typescript
import { wearEngine } from '@kit.WearEngine';
const deviceClient = wearEngine.getDeviceClient(getContext());
const p2pClient = wearEngine.getP2pClient(getContext());
const monitorClient = wearEngine.getMonitorClient(getContext());
// ① 获取已连接设备
const devices = await deviceClient.getConnectedDevices();
devices.forEach(d => console.log(d.name, d.model, d.category));
// ② P2P 通信
await p2pClient.sendMessage(devices[0].randomId, { bundleName: 'com.example' }, { data: 'hello' });
p2pClient.registerMessageReceiver(devices[0].randomId, { bundleName: 'com.example' }, (msg) => {
console.log('收到消息:', msg.data);
});
// ③ 设备状态监控
monitorClient.subscribeEvent(devices[0].randomId, wearEngine.MonitorEvent.EVENT_CONNECTION_STATUS_CHANGED, (data) => {
console.log('连接状态变更');
});
// ④ 传感器订阅
const sensorClient = wearEngine.getSensorClient(getContext());
sensorClient.subscribeSensor(devices[0].randomId, wearEngine.SensorType.HEART_RATE, (result) => {
console.log('心率数据:', result);
});
// ⑤ 授权
const authClient = wearEngine.getAuthClient(getContext());
await authClient.requestAuthorization({ permissions: [wearEngine.Permission.HEALTH_SENSOR] });
wearEngine.on('serviceDie', () => { console.log('穿戴服务断开'); });
```
---
## 🔧 调试命令速查（HDC / aa / bm / uitest）
> 开发者日常最常用的命令行调试工具，**一键速查**。
### HDC（设备连接调试）
```bash
# ▸ 设备连接
hdc list targets # 列出已连接设备
hdc list targets -v # 显示详细信息
hdc tconn 192.168.1.100:8888 # TCP连接设备
# ▸ 应用安装卸载
hdc install D:\example.hap # 安装 HAP
hdc install -r D:\example.hap # 覆盖安装
hdc install -g D:\example.hap # 安装并授予权限（API 24+）
hdc install D:\example.app # 安装 APP 包（API 22+）
hdc uninstall com.example.app # 卸载
hdc uninstall -k com.example.app # 卸载保留数据
# ▸ 文件传输
hdc file send test /data/test/ # 发送文件到设备
hdc file recv /data/test/file ./ # 从设备接收文件
hdc file send -b com.example.app test /test/ # 发送到应用沙箱
# ▸ 日志与调试
hdc hilog # 查看设备日志
hdc shell # 进入设备 shell
hdc target boot # 重启设备
hdc fport tcp:1234 tcp:1080 # 端口转发（本地→设备）
hdc rport tcp:1234 tcp:1080 # 反向端口转发（设备→本地）
hdc start -r # 重启 hdc 服务
```
### aa（Ability 调试）
```bash
# ▸ 启动应用
aa start -b com.example.app -a EntryAbility # 显式启动
aa start -A ohos.want.action.viewData -U https://example.com # 隐式启动
# ▸ 启动并测量冷启动耗时（API 20+）
aa start -b com.example.app -a EntryAbility -W
# ▸ 调试
aa force-stop com.example.app # 强制停止进程
aa attach -b com.example.app # 进入调试模式
aa detach -b com.example.app # 退出调试模式
aa test -b com.example.app -s unittest TestRunner # 运行测试
```
### bm（包管理）
```bash
# ▸ 安装卸载
bm install -p /data/local/tmp/app.hap # 安装 HAP
bm install -p /data/local/tmp/app.hap -r # 覆盖安装
bm install -p /data/local/tmp/app.hap -g # 安装并自动授权
bm uninstall -n com.example.app # 卸载
# ▸ 查询
bm dump -a # 列出所有已安装应用
bm dump -n com.example.app # 查询应用详细信息
bm dump -g # 查询调试类型应用
bm get -u # 获取设备 UDID
# ▸ 清理
bm clean -c -n com.example.app # 清缓存
bm clean -d -n com.example.app # 清数据
# ▸ 插件和快速修复
bm install-plugin -n com.example.app -p plugin.hsp # 安装插件
bm quickfix -a -f /data/app/example.hqf # 安装热修复补丁
bm quickfix -q -b com.example.app # 查询补丁信息
```
### uitest（UI 自动化）
```bash
# ▸ 控件获取
hdc shell uitest dumpLayout -a # 获取控件树（含属性）
hdc shell uitest dumpLayout -p /tmp/layout.json # 保存到文件
# ▸ 截图
hdc shell uitest screenCap -p /tmp/screen.png
# ▸ 模拟操作
hdc shell uitest uiInput click 100 100 # 点击
hdc shell uitest uiInput longClick 100 100 # 长按
hdc shell uitest uiInput swipe 10 10 200 200 500 # 滑动
hdc shell uitest uiInput dircFling 2 # 方向滑动（2=上）
hdc shell uitest uiInput keyEvent Back # 按返回键
hdc shell uitest uiInput text hello # 输入文本
# ▸ 录制
hdc shell uitest uiRecord record # 开始录制（Ctrl+C结束）
```
### hilog（日志查看）
```bash
# ▸ 基础查看
hilog # 实时查看日志（阻塞）
hilog -x # 非阻塞，看完退出
hilog -z 10 -L E # 最近10条ERROR日志
# ▸ 过滤
hilog -L E/F # 仅ERROR/FATAL级别
hilog -T MyTag # 按TAG过滤
hilog -P 1234 # 按进程PID过滤
hilog -e "error|Exception" # 正则搜索
hilog -D 0x3200 # 按Domain过滤
# ▸ 格式
hilog -v color # 彩色输出
hilog -v time # 显示本地时间
# ▸ 缓冲区
hilog -g # 查看缓冲区大小
hilog -G 16M # 设置缓冲区为16M
hilog -r # 清空缓冲区
# ▸ 落盘
hilog -w start -n 1000 # 启动日志落盘（1000个文件）
hilog -w stop # 停止落盘
hilog -w query # 查看落盘任务
```
### hidumper（系统诊断）
```bash
# ▸ CPU
hidumper --cpuusage # 整机CPU使用率
hidumper --cpuusage 1234 # 指定进程CPU使用率
hidumper --cpufreq # CPU核运行频率
# ▸ 内存（最强大）
hidumper --mem # 全量内存（PID/PSS/OOM）
hidumper --mem --prune # 精简版内存
hidumper --mem 1234 # 指定进程内存详情
hidumper --mem-jsheap 1234 # ArkTS JS Heap快照
hidumper --mem-smaps 1234 # 进程内存映射表
# ▸ 系统服务
hidumper -ls # 列出所有系统服务
hidumper -s WindowManagerService # 查看窗口服务详情
# ▸ 进程/网络/存储
hidumper -p 1234 # 进程信息
hidumper -p 1234 --fd # 文件句柄
hidumper --net # 网络流量
hidumper --storage # 存储/IO统计
# ▸ 故障
hidumper -e # 获取故障日志
hidumper -e --list # 异常退出记录列表
hidumper --zip # 打包到 /data/log/hidumper/
```
---
## 🎯 HarmonyOS 7 DFX 全线工具（9 项能力，API 26 Beta 新增）
> 以下 DFX（Design For X）能力是 API 26 Beta1 版本全新推出的诊断/调试/性能优化工具集。
### 1. ArkTS 内存快照聚类分析
将快照中的同类对象进行聚类分析，统计各泄漏对象的影响大小，定位内存泄漏问题。
- **场景**：内存泄漏排查 → 快照对比 → 聚类查看泄漏对象分布
- **入口**：DevEco Studio Profiler → ArkTS Memory → 聚类分析规则
### 2. JSLeakWatcher — ArkTS 内存泄漏定位利器
```typescript
import { jsLeakWatcher } from '@kit.PerformanceAnalysisKit';
// 对具有生命周期的 ArkTS 组件对象定期执行泄漏检测
const watcher = jsLeakWatcher.createWatcher();
watcher.on('leakDetected', (result) => {
console.info(`泄漏对象: ${result.className}, 引用链: ${result.referenceChain}`);
});
watcher.start({ interval: 30000 }); // 每 30s 检测一次
```
- **场景**：页面关闭后检查是否有未释放的组件实例
- **模块**：`@kit.PerformanceAnalysisKit` → `jsLeakWatcher`
### 3. GlobalHandle + MemTrace — 资源泄漏自诊断
```typescript
import { hidebug } from '@kit.PerformanceAnalysisKit';
// 启动资源分配栈采集（线上运维）
hidebug.OHHiDebugStartProfiler({ type: 'globalHandle', duration: 60000 });
// 停止后通过 MemTrace 日志分析泄漏
hidebug.OHHiDebugStopProfiler();
```
- **模块**：`@kit.PerformanceAnalysisKit` → `hidebug`
- **API**：`OHHiDebugStartProfiler()` / `OHHiDebugStopProfiler()`（C API）
### 4. HiAppevent 退出原因订阅
```typescript
import { hiAppEvent } from '@kit.PerformanceAnalysisKit';
// 订阅 APP_KILLED 事件，获取应用上一次退出原因
hiAppEvent.on('APP_KILLED', (event) => {
console.info(`退出原因: ${event.exitReason}, 时间: ${event.timestamp}`);
});
// 进一步分析故障根因：订阅 CRASH / FREEZE 并关联同一次故障
hiAppEvent.on('APP_CRASH', (event) => {
console.info(`crash info: ${event.crashStack}, uniqueId: ${event.appRunningUniqueId}`);
});
```
- **用途**：聚类分析应用非预期退出，关联 crash/freeze 日志定位根因
- **模块**：`@kit.PerformanceAnalysisKit` → `hiAppEvent`
### 5. AppFreeze 增强日志
- APP_INPUT_BLOCK 超时阈值调整为 **8 秒**
- 主线程采样：THREAD_BLOCK_3S 发生时，每 300ms 采集一次调用栈（最多 10 次）
- **配置开启**：在 `module.json5` 中开启主线程采样，订阅 APP_FREEZE 事件
```typescript
hiAppEvent.on('APP_FREEZE', (event) => {
// event.threadStacks: 包含多个采样点的调用栈信息
// event.cpuUsage: CPU 使用率
// event.mainThreadDuration: 主线程运行时长
console.info(`阻塞详情: ${JSON.stringify(event.threadStacks)}`);
});
```
### 6. Profiler 跨语言内存分析
- **新增**：Native 持有 ArkTS 内存泄露分析（LocalHandle + GlobalHandle 两种句柄）
- **能力**：抓取并展示关联 ArkTS 对象的 Native 分配栈
- **入口**：DevEco Profiler → Memory → 跨语言分析
### 7. GWPAsan 越界检测工具
运维态地址越界检测，定位**释放后使用、堆溢出、重复释放、非法释放**等踩内存问题。
- **特点**：无需插桩、采样监控、性能开销 < 5%、适合现网大规模运行
- **配置**：支持开启概率、采样率、slot 数、可恢复模式
- **使用**：订阅地址越界事件获取故障日志（报错栈/申请栈/释放栈）
```typescript
// 在 module.json5 中配置 GWPAsan
// "gwpAsan": {
// "enabled": true,
// "samplingRate": 0.01,
// "maxSlots": 16,
// "recoverable": true
// }
```
### 8. AI 辅助稳定性诊断
- AI 自动分析故障日志，定位稳定性问题根因
- 小红书已作为首批生态"样板间"接入
- **入口**：DevEco Studio → Stability Diagnosis
### 9. HandleScope 自动处理（NDK）
```cpp
// C/C++ 代码中调用
OH_JSVM_EnableLocalHandleDetection(jsvm_env env, bool enable);
```
- 启用后，系统在 libuv 和 EventRunner 的异步回调中自动添加 scope 管理 `napi_value` 生命周期
- 减少手动 HandleScope 遗漏导致的引用泄漏
- **适用**：NDK 开发，特别是频繁使用 napi 回调的场景
---## 🏗️ hvigorw 构建系统速查
> 命令行构建神器，**CI/CD 和脱离 IDE 打包必备**。
### 核心构建命令
```bash
# ▸ 打包类型
hvigorw assembleHap # 构建 HAP（调试包，默认）
hvigorw assembleHap -p buildMode=release # 构建 release HAP
hvigorw assembleApp -p buildMode=release # 构建 APP（上架用）
hvigorw assembleHar # 构建 HAR 共享库
hvigorw assembleHsp # 构建 HSP 共享包
# ▸ 模块级构建（只编译改动的模块，加速）
hvigorw assembleHap --mode module -p module=entry@default
# ▸ 清理
hvigorw clean assembleHap # 先清理再构建
# ▸ 测试
hvigorw onDeviceTest -p module=entry # 真机测试
hvigorw test -p module=entry # 本地测试（无需设备）
```
### CI/CD 关键配置
```bash
# 环境变量（CI 服务器）
export NODE_HOME=/path/to/command-line-tools/tool/node
export JAVA_HOME=/path/to/jdk
export PATH=$NODE_HOME/bin:$JAVA_HOME/bin:/path/to/command-line-tools/bin:$PATH
export OHOS_SDK=/path/to/command-line-tools/sdk
# 安装依赖
ohpm install --all
# 构建（CI 推荐 --no-daemon）
hvigorw assembleHap -p buildMode=debug --no-daemon
# 签名：通过环境变量注入密码，build-profile.json5 中配置
# 或通过 hvigorfile.ts 读取 process.env.SIGNING_PASSWORD
```
### 编译优化参数
| 参数 | 说明 |
|:----|:------|
| `--no-daemon` | CI 环境推荐，避免 daemon 缓存问题 |
| `--incremental` | 增量编译（默认开启），只编译改动文件 |
| `--parallel` | 并行构建（默认开启），多模块同时编译 |
| `-d` / `--debug` | 开启 debug 日志，排查构建失败 |
| `--stacktrace` | 打印完整异常堆栈 |
| `--max-old-space-size=12345` | 调大 Node.js 内存（OOM 时使用） |
| `--analyze=normal` | 生成构建任务耗时分析 |
### API 26 新增构建配置
| 配置项 | 位置 | 说明 |
|:------|:----|:------|
| `apiCompatibilityCheck` | `build-profile.json5` → `strictMode` | 设置 ArkTS API 兼容性检测级别 |
| `tsImportSoCheck` | `build-profile.json5` → `tscConfig` | 编译时对 .ts 文件中导入 .so 的符号进行类型解析 |
| `enableSoDirCollection` | 模块级 `build-profile.json5` → `nativeLib` | ets 文件能否加载 libs/{ABI}/ 子目录下的 so 文件 |
| `getAllDependencyInfo()` | hvigorfile.ts | 获取工程或模块下所有依赖信息 |
| `syncNative` | DevEco Studio Settings 开关 | 提升 sync 阶段 C++ 编译效率 |
### DevEco Studio 26 新增 CLI 工具版本
| 工具 | API 26 版本 | 说明 |
|:----|:----------:|:-----|
| Command Line | 26.0.0.461 | 命令行工具集 |
| codelinter | 6.0.240 | 代码检查与修复 |
| hstack | 6.0.0 | release 混淆堆栈还原工具 |
| hvigorw | 6.26.1 | 编译构建（API 10+ 支持） |
| ohpm | 26.0.0.410 | 包管理 |
| Node.js | 24.14.1 | 运行时 |
| SDK | 26.0.0 Beta1 | OpenHarmony SDK 26.0.0.23 |
---
## 📱 官方 Sample 精选速查
> 华为官方 700+ 示例中精选 **最有学习价值的 10 个**，对标实际开发场景。
| Sample | 核心知识点 | 适用场景 |
|:-------|:----------|:--------|
| **全链路盯盘** | 闪控球+悬浮窗+锁屏卡片+屏保卡片+防窥保护 | 金融/监控类 |
| **互动卡片** | Live Form 互动卡片能力 | 桌面卡片开发 |
| **沉浸光感** | HdsNavigation+HdsTabs+悬浮导航 | UI 现代化改造 |
| **多设备长视频** | 一多架构(三层)+自适应布局+折叠屏/平板/PC | 视频类 App |
| **多设备音乐** | 一多架构+迷你播控+全屏播放+穿戴适配 | 音乐类 App |
| **多设备短视频** | 一多架构+手表适配+评论页+个人作品页 | 短视频类 App |
| **多设备社区评论** | 一多架构+图片预览+社区详情页 | 社区/社交类 |
| **自由流转社交协同** | 应用接续+分布式数据对象+跨设备拖拽+碰一碰 | 协同办公 |
| **媒体直播** | 音视频采集+播放+音频焦点+画面翻转+背景音乐 | 直播类 App |
| **威胁防护文件扫描** | 企业威胁防护+文件隔离/恢复 | 企业安全类 |
**一多架构推荐模式**：
```
三层架构：
┌─ commons/ ← 公共能力（网络/工具/UI组件）
├─ services/ ← 业务逻辑（数据管理/状态管理）
└─ views/ ← 页面视图（按设备形态适配）
```
---
## 📦 ohpm 包发布指南
> HAR 共享包发布到 OpenHarmony 三方库中心仓，复用生态。
### oh-package.json5 配置
```json5
{
"name": "@your/lib_log",
"version": "1.0.0",
"description": "简短的包描述",
"main": "Index.ets",
"author": "你的名字",
"license": "Mulan PSL v2",
"dependencies": {},
"packageType": "har" // har / hsp
}
```
### 发布流程（官方验证）
```bash
# 1. 注册中心仓 https://ohpm.openharmony.cn 获取 publish_id
# 2. 生成密钥对（ohpm 要求加密传输，生成时必须设置密码）
ssh-keygen -m PEM -t RSA -b 4096 -f ~/.ssh_ohpm/mykey
# 3. 配置 ohpm（publish_id 和 key_path 也可在 publish 命令中直接传参）
ohpm config set publish_id your_publish_id
ohpm config set key_path ~/.ssh_ohpm/mykey
# 4. 构建 HAR
hvigorw assembleHar
# 5. 发布
ohpm publish lib_log.har
```
### 发布校验规则（官方）
| 要求 | 说明 |
|:----|:------|
| **文件格式** | 必须是 `.har` 或 `.tgz` 包 |
| **必需文件** | `oh-package.json5` + `README.md` + `LICENSE` + `CHANGELOG.md`（不能为空） |
| **oh-package.json5 必填字段** | `name`、`version`、`description`、`main`、`license` |
| **依赖完整性** | 所有直接依赖必须在包的 oh-package.json5 中声明 |
| **版本唯一** | 已发布的名称+版本组合不可重复使用 |
### 最佳实践
- **摘除外部依赖**：发布前移除未上中心仓的本地模块引用
- **README 必含安装命令**：`ohpm install @your/package`
- **版本号管理**：遵守 semver 规范，`ohpm version patch/minor/major`
- **HSP vs HAR**：HAR 可发中心仓，HSP 只能发私仓
- **清理命令**：`ohpm clean` 删除所有 oh_modules 目录和 lock 文件
### ohpm 常用命令
```bash
ohpm install @ohos/package # 安装依赖
ohpm install --all # 安装全部模块依赖
ohpm install --registry <url> # 指定仓库地址
ohpm uninstall @ohos/package # 卸载依赖
ohpm list # 查看依赖树
ohpm update @ohos/package # 更新依赖
ohpm clean # 清理所有 oh_modules
```
---
## ♿ Accessibility 无障碍开发要点
> **审核要求**：AGC 审核会检查无障碍支持，缺失可能导致被拒。
### 核心属性
```typescript
// 基础无障碍标签（每个可交互组件必加）
Button('提交')
.accessibilityText('提交按钮') // 朗读文本
.accessibilityDescription('点击提交表单') // 详细描述
.accessibilityGroup(true) // 标记为无障碍组
// 隐藏装饰性元素（如图标、分割线）
Divider()
.accessibilityLevel('no') // 跳过朗读
// 控制焦点
Text('重要提示')
.focusable(true) // 可获焦
.defaultFocus(true) // 页面默认焦点
```
### 无障碍最佳实践
| 规则 | 做法 |
|:----|:-----|
| **所有可交互组件加标签** | Button/Input/List/Image 都加 `accessibilityText` |
| **装饰元素隐藏** | 纯图标/分割线/背景图加 `accessibilityLevel('no')` |
| **语义化分组** | 相关控件用 `accessibilityGroup(true)` 包裹 |
| **动态内容通知** | 用 `announceForAccessibility(text)` 通知屏幕朗读 |
| **颜色对比度** | 文本/背景对比度 ≥ 4.5:1 |
| **触摸目标大小** | 可点击区域 ≥ 44vp × 44vp |
---
## 📐 ArkUI 自适应布局模式（官方精学验证）
> 一次开发多端部署（一多）的核心布局模式。**注意：`BreakpointType` 是社区封装的工具类，非 ArkUI 内置 API**，官方方案使用 `GridRow` + `MediaQuery`。
### 三大布局策略
| 策略 | 适用 | 官方 API |
|:----|:----|:---------|
| **自适应布局** | 同设备尺寸变化 | `layoutWeight` / `flexShrink` / 百分比% |
| **响应式布局** | 跨设备形态变化 | `GridRow` + `GridCol` / `MediaQuery` |
| **多态组件** | 同一组件不同显示 | `@Styles` + `@Extend` + 条件渲染 |
### 官方断点系统（`GridRow`）
```typescript
// GridRow breakpoints 属性（官方 API）
GridRow({
breakpoints: {
value: ['600vp', '840vp'], // 断点：sm<600, md<840, lg>=840
reference: BreakpointsReference.WindowSize // 相对窗口大小
}
}) {
GridCol({ span: { sm: 12, md: 6, lg: 4 } }) { // 手机满宽，平板半宽，PC 1/3
Text('自适应内容')
}
}
```
### 使用 `mediaquery` 监听断点（官方 API）
```typescript
import { mediaquery } from '@ohos.mediaquery';
@Component
struct AdaptivePage {
@State currentBreakpoint: 'sm' | 'md' | 'lg' = 'sm';
listener = mediaquery.matchMediaSync('(min-width: 600vp) and (max-width: 839vp)');
aboutToAppear() {
this.listener.on('change', (result) => {
// 根据 match 结果更新状态
});
}
}
```
### 断点参考值
| 断点 | vp 范围 | 典型设备 |
|:----|:-------|:--------|
| xs | 0~319vp | 小屏手表 |
| sm | 320~599vp | 手机竖屏 |
| md | 600~839vp | 折叠屏展开/小平板 |
| lg | 840~1199vp | 平板横屏 |
| xl | ≥1200vp | PC/2in1 |
### 常见布局模式
```typescript
// 折叠屏自适应双栏/单栏（官方推荐方式）
if (this.currentBreakpoint === 'sm') {
// 单栏：Navigation 全屏
Navigation() { /* ... */ }
.title('列表')
.navDestination(this.pageStack)
} else {
// 双栏：侧栏 + 内容
Row() {
SideBarContainer() { /* 列表 */ }
.width(320)
Column() { /* 详情 */ }
.layoutWeight(1)
}
}
```
---
> `references/` 目录下收录了 **60 个核心 @ohos.* 模块的离线 API 参考文档**，覆盖网络、数据、Ability、ArkUI、媒体、安全、工具等主要分类。
>
> **检索流程：先查索引 → 再读文档**，避免全量读取。
### 三层索引体系
```
SKILL.md → references/KITS.md / TASK_MAP.md → references/INDEX.md → 目标文档
```
| 层级 | 文件 | 用途 |
|:----|:-----|:----|
| 第1层 | `KITS.md` | Kit 导航：按功能分类（NetworkKit、AbilityKit、ArkData 等） |
| 第2层 | `TASK_MAP.md` | 任务导航：按"我想做什么"反查（网络请求、数据存储、权限申请等） |
| 第3层 | `INDEX.md` | 全库路径索引：所有模块文件的完整路径清单 |
### 检索命令速查
```bash
# ① 在 INDEX 中搜索关键词
rg -n "UIAbility|Want|AbilityStage" references/INDEX.md | head
# ② 按模块前缀搜索
rg -n "net\\.http|file\\.fs|data\\.preferences" references/INDEX.md | head
# ③ 搜索特定方法名
rg -n "createHttp|request|destroy" references/INDEX.md | head
# ④ 在 KITS 中识别 Kit
rg -n "网络|数据|安全|媒体" references/KITS.md | head
```
### 模块分类速览
| 分类 | 模块数 | 包含模块 |
|:----|:-----:|:--------|
| 📡 网络通信 | 4 | `net.http`, `net.socket`, `net.webSocket`, `net.connection` |
| 💾 数据存储 | 5 | `data.preferences`, `data.rdb`, `relationalStore`, `distributedKVStore`, `distributedDataObject` |
| 📱 Ability | 8 | `app.ability.UIAbility`, `Want`, `AbilityStage`, `common`, `Configuration`, `appManager`, `wantAgent` + 更多 |
| 🎨 ArkUI | 6 | `arkui.UIContext`, `inspector`, `observer`, `StateManagement`, `dragController`, `componentSnapshot` |
| 📷 媒体 | 4 | `multimedia.camera`, `audio`, `image`, `media` |
| 🔐 安全 | 4 | `security.cryptoFramework`, `huks`, `cert`, `abilityAccessCtrl` |
| 🔧 工具 | 7 | `hilog`, `taskpool`, `worker`, `resourceManager`, `util`, `promptAction`, `hidebug` |
| 📍 位置 | 3 | `geoLocationManager`, `bluetooth`, `distributedDeviceManager` |
| 📂 文件 | 3 | `file.fs`, `file.picker`, `file.fileuri` |
| 📦 其他 | 16 | 图形、通知、窗口、传感器、输入法、上传下载、后台任务、包管理等 |
### 回答规则
- **不确定 API 签名** → 查 `references/INDEX.md` 找到文档路径 → 只读对应 `.md` 文件
- **不确定模块存在与否** → 在 INDEX 中搜索模块名
- **需要代码示例** → 先在离线文档找官方示例，再结合 SKILL.md 的实战经验优化
- **优先使用离线文档**，模型记忆为辅
- **版本差异**：离线文档基于 API 22-23，API 25-26 新能力以 SKILL.md 中的 §6 API 26 新能力详解 为准
> `references/` 目录路径相对于本 SKILL.md。don't have the plugin yet? install it then click "run inline in claude" again.