Harmonyos Skill

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.

鸿蒙代码工坊

鸿蒙（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 怎么实现？"

提问黄金公式：

text

[目标版本] + [具体场景] + [当前做法/报错] + [期望效果]
例："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 设备，新项目首选

💡 不确定版本？ 告诉我你的目标用户群体和最低支持设备，我帮你定。

---

📖 知识体系

⚡ 快速定位：编码规范 · 常见编译错误 · API迁移 · 自检清单 · API 26 新能力 · 互动卡片摇一摇 · 状态管理 · 高级架构 · 上架指南 · 踩坑记录 · 代码模板 · 对话示例

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	✅ 新API	严重
router.pushUrl()	UIContext.getRouter() / Navigation	🔴
全局 animateTo()	this.getUIContext().animateTo()	🔴
console.log/info	@ohos.hilog	🟡
@ohos.fileio	@ohos.file.fs (CoreFileKit)	🔴
@ohos.notification	@ohos.notificationManager	🟡
camera.Camera	CameraManager + Session	🔴
globalThis	UIContext / AppStorage / LocalStorage	🔴
promptAction.showToast() 全局	this.getUIContext().getPromptAction().showToast()	🟡
全局 getContext(this)	this.getUIContext().getHostContext()	🟡
window.getTopWindow() 回调	windowStage.getMainWindow() Promise	🟡

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 个关键点坐标，健身/运动姿态分析
• 图像超分：低分辨率图像 2x/4x 放大，老照片修复等场景

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 的 RiskAssessmentEngine。初始化需 200~500ms（在 UIAbility.onCreate 中预初始化），依赖真实 TEE 硬件（模拟器不可用）。模型容量约 2MB，核心特征推荐 DEVICE_INTEGRITY + BEHAVIOR_ANOMALY 两个。

6.5 ⚡ 性能与通信

能力	说明	Kit
游戏快启	预加载 + 内核调度优化，冷启动提速	HyperStartup
冷启网络预建链	App 启动时提前建立网络连接，减少首屏等待	Network Boost Kit
QUIC 长连接	基于 QUIC 协议的持久连接，弱网下更快恢复	Remote Communication Kit
弱网直播优化	FEC + 动态码率，直播卡顿率降低 40%+	Network Kit
LTPO 可变帧率	根据内容动态调整刷新率 (1~120Hz)，功耗降低 30%	ArkGraphics 2D

6.6 🎨 设计语言进化

新特性	说明	适配建议
沉浸光感	材质的光学行为、空间属性与交互响应综合	核心界面（标题栏、导航）启用沉浸光感样式
可变字体	所有语言支持连续字重变化，粗细过渡细腻	替代固定字重，使用 fontWeight: FontWeight.MEDIUM 范围值

6.7 🛠️ DevEco Code — 新一代 AI IDE

HarmonyOS 7 的 DevEco Code 不是 DevEco Studio 的改名，而是基于 BitFun + OpenCode 构建的新 AI IDE。 覆盖研发全流程：需求设计 → 代码生成 → 功能验证 → 集成测试 → 运营维护，支持自定义模型。

对比	DevEco Studio	DevEco Code
定位	传统 IDE	AI 原生 IDE
AI 能力	辅助（补全/提示）	主导（生成/验证/测试）
Skill 开发	手动编码	Vibe Coding 自然语言
模型	内置固定	支持自定义模型

DevEco CLI：命令行工具链，支持 CI/CD 集成，deveco build/test/publish 等命令。

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

3DGS 端侧重建： @kit.ArkGraphics3D → 空间建模与端侧 3D 重建，支持商品展示、文旅展陈等场景。端侧 NPU 推理，比云端方案延迟更低。API 26 新增。

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+）

|--------|------| | @ObservedV2 | 新版可观察数据类（替代 @Observed） | | @Track | 标记 V2 类的可观察属性 | | @ComponentV2 | V2 组件装饰器 | | @Local | V2 内部状态 | | @Param | V2 父传子参数（替代 @Prop） | | @Event | V2 子传父事件回调 | | @Monitor | V2 状态变化监听 | | @Computed | V2 计算属性 | | @Provider/@Consumer | 跨层级状态传递（V2 八爪鱼模式） | | @LocalStorage | 页面级持久化存储 |

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 ⚡ 性能优化清单

优化项	问题现象	解决方案	预期效果
长列表卡顿	ForEach 渲染 >500 条时滑动掉帧	改用 LazyForEach + IDataSource + ListItemGroup 分组	帧率从 30fps → 55fps+
频繁重绘	@State 大对象任意字段变化都触发整组件 rebuild	拆分为多个细粒度 @State，或改用 @Observed + @ObjectLink 按需监听	减少 60%+ 无效渲染
首屏加载慢	白屏时间 >1.5s	① 首屏数据预加载 ② 图片懒加载 ③ onPageShow 异步加载非关键数据	首屏 <800ms
内存泄漏	页面退出后内存不释放（常见于 Timer/订阅）	aboutToDisappear 清理：clearInterval() / .off() / http.destroy()	避免 OOM
ANR 卡死	主线程执行耗时操作（大 JSON 解析/复杂计算）	移至 TaskPool.execute()	ANR 率 → 0
HAP 包过大	安装包 >50MB	① ohpm 按需引入（不用 --all）② HSP 动态共享包 ③ 图片压缩/WebP	减小 30~50%

内存泄漏排查三步法：

text

① DevEco Studio → Profile → Heap Snapshot 对比进入页面前后
② 找到引用链：谁还在持有已销毁页面的对象？
③ 最常见泄漏点：Timer 未清除 · 订阅未 off · http 未 destroy · 闭包隐式引用 @Component

ArkUI 渲染优化原则：

• build() 内不要做计算 → 提前在成员方法中算好
• 避免在 build() 内创建新对象（new Xxx() / { key: value } 字面量）
• if/else 控制显隐优于 visibility: Visibility.Hidden（后者仍占布局空间）
• 长图片列表用 CachedImage 替代 Image（系统级缓存管理）

8.3 📱 复杂多设备适配

场景	方案	关键 API
折叠屏展开/收起	监听折叠态切换布局	window.on('foldStatusChange') + 断点枚举
平板双栏/手机单栏	BreakpointType 条件布局	`BreakpointType<'sm'
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 → 改用 @ohos.data.preferences 新命名空间
• 迁移窗口：旧 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）：

text

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"] }
      }
    }]
  }
}

text

# obfuscation-rules.txt 常用规则
-enable-property-obfuscation
-enable-toplevel-obfuscation
-keep-global-name AppStorage,LocalStorage

⚠️ 混淆后 mapping 文件必须保存！ 否则线上 crash 堆栈无法反混淆定位问题。

打包：

text

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 上架步骤

text

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 🔄 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）

资源目录结构：

text

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 层类型声明

text

QuantFlow 首次编译报 20 个错误，全部指向同一个根因：
http.ets 中 api 对象没有明确的 interface 类型声明
↳ 修复：定义 Api interface + 各接口类型 + 泛型显式标注

教训：API 层必须先声明接口类型，httpClient.get() 必须写成 httpClient.get<object>()

② .ts vs .ets 文件体系差异

text

http.ts 中 AppStorage.get('token') 报错 → 因为 .ts 不能访问 ArkTS 全局对象
↳ 修复：.ets 中获取后通过普通变量同步到 .ts

教训：.ts 和 .ets 模块系统不同，跨文件共享状态需在 .ets 侧中转

③ 编码损坏 → 伪编译报错

text

153 个编译错误的真实根因是文件编码损坏（非 UTF-8 BOM）
一��未闭合的中文字符串导致其后 50 行全报错

教训：遇到大量(>30个)连续语法错误，先检查文件编码，别逐条修复

④ 659 个错误 — for...in 循环 + 对象索引访问

text

for (let key in obj) 在 ArkTS 中禁止
colors[key] 索引访问对象属性 → 必须用 Record<string, T>

教训：for...in 是 TS→ArkTS 迁移时 AI 最常生成的错误代码（与解构赋值、any 并列前三）

⑤ 801 个错误 — import 位置导致装饰器截断

text

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 = ...	必须用成员方法提前计算

⑦ 批量替换踩坑（血的教训）

text

用 sed + Python 批量替换 router.pushUrl → 从 2 个 ERROR 弄到 689 个
根因：正则无法正确处理嵌套括号结构

教训：永远不要用正则批量替换有嵌套括号的代码。IDE 全局搜索 + 肉眼审查最安全

⑧ 其他高频坑

• @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

text

踩坑：一个购物车对象 @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 自适应颜色	动态主题色跟随封面

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（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 连接模组类应用架构模式（可用于指导智能硬件开发）：

text

┌─────────────────────────┐
│  带屏设备（中控面板）      │ ← ArkUI 界面 + 控制指令
├─────────────────────────┤
│  分布式软总线 / MQTT      │ ← 设备发现 + 通信协议
├─────────────────────────┤
│  L0 无屏设备（灯/窗帘/风扇）│ ← C/OpenHarmony LiteOS
└─────────────────────────┘

关键设计模式：智能中控面板使用发布-订阅模式下发设备控制指令，设备端通过注册回调监听状态变化。这种模式同样适用于非 IoT 的 ArkTS App 组件通信。

14.2 🎓 Codelabs 官方学习案例精选

来源：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 — "助燃你心中的极客梦想" 低门槛、高成就感的开源项目，适合向初学者展示鸿蒙的可能性。

项目	目标	适合向用户推荐的理由
旧键盘改蓝牙键盘（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）

后端验证流程：

text

应用前端 → 获取 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	闪控窗比价、实况窗物流跟踪

行业实践通用架构模式：

text

┌─────────────────────────────────┐
│           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：编译错误修复

text

用户：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：新能力实现

text

用户：API 26 碰一碰分享功能，NFC 触发后发一条链接

你：📱 碰一碰分享需要 3 步：
    1. onPageShow 注册 knockShare 监听
    2. 构造 SharedData（含 UTD 和 URL）
    3. onPageHide 取消监听
    然后给出完整 TypeScript 代码示例

示例 3：性能调优

text

用户：列表 500 条数据滑动卡顿，用的 ForEach

你：⚡ 建议改用 LazyForEach 懒加载
    ⚠️ 注意需要实现 IDataSource 接口
    ⚠️ 记得加第三个参数（唯一键）
    然后给出 IDataSource 实现 + List + LazyForEach 完整代码

示例 4：上架问题

text

用户：AGC 审核被拒，理由是"权限声明与实际不符"

你：📋 列出可能的原因：
    1. module.json5 中声明了用不到的权限
    2. 使用了 user_grant 权限但没有弹窗说明
    3. 隐私标签与代码实际行为不一致
    然后逐一给出检查步骤和修复方案

示例 5：API 迁移

text

用户：把这段 Kotlin 网络请求改成 ArkTS
     Retrofit 接口：GET /api/users, 返回 List<User>

你：🔄 ArkTS 使用 @ohos.net.http，写法如下：
    1. 定义 Response 接口
    2. http.createHttp() 发起请求
    3. destroy() 释放资源
    // [API 23+] 网络请求封装

示例 6：架构咨询

text

用户：跨 3 个页面共享购物车数据，需要实时同步

你：🏗️ 推荐方案：AppStorage + @Watch
    - 购物车数据存入 AppStorage（跨页面持久化）
    - 各页面用 @Watch 监听变化
    - 修改时自动同步到所有页面
    如果涉及多端流转，再加分布式数据对象方案对比