baidu-maps/harmony-sdk-skills/harmony-arkts-dev-assistant

HarmonyOS ArkTS 开发规范编程助手 Skill

触发场景

当满足以下任意条件时，应启用本 Skill 作为 ArkTS 代码生成与审查的规范依据：

• 用户正在编辑或新建 .ets 文件，并提到“规范”“最佳实践”“代码风格”“代码审查”等关键词。
• 对话中出现 ArkTS / ArkUI / HarmonyOS NEXT 相关问题，特别是组件写法、生命周期、样式布局、事件处理、状态管理、错误处理与测试实践。
• 用户要求“按照官方/行业最佳实践写 ArkTS 代码”或“帮我按规范检查/重构 ArkTS 页面/组件/模块”。

在这些场景下，代理生成或修改的 ArkTS 代码必须参考本 Skill 中的规范内容。

Skill 主目标

• 统一状态管理版本：统一工程中的状态管理，优先使用V2版本实现ViewModel。常用的状态管理装饰器包括@Local、@Param、@Event、@ObservedV2、@Trace等等。
• 统一组件装饰器与状态管理用法：确保入口组件、页面组件、自定义组件使用正确装饰器，@State / @Prop / @Link / @Provide / @Consume 等按数据流语义选用。
• 规范生命周期使用：在 aboutToAppear / aboutToDisappear / onPageShow / onPageHide 中正确初始化与清理资源，避免内存泄漏。
• 统一样式与布局风格：使用链式调用、合理属性顺序与响应式单位（vp / fp / 百分比）构建 UI，保持 ArkUI 风格一致。
• 约束事件处理方式：使用箭头函数与私有方法封装复杂逻辑，避免在 build() 中直接堆叠复杂业务代码。
• 强化类型安全：通过接口与泛型明确组件间数据结构、回调签名，避免隐式 any unknown 与弱类型代码。
• 关注性能与资源管理：避免不必要渲染，合理使用 @Reusable、@Builder、LazyForEach，并在生命周期正确释放资源。
• 规范错误处理与日志：为异步流程补充 try/catch 与 Promise.catch，使用 hilog 标准化日志输出。
• 强调测试与代码自检：引导为组件编写 @ohos/hypium 单元测试，并使用附带的代码审查清单进行提交前自查。

Skill 使用要求与输出风格

在使用本 Skill 回答 ArkTS 相关问题或生成代码时，代理应：

1. 对照规范自动修正代码

• 若发现组件缺少或误用装饰器（如 @Entry、@Component、@State 等），应按照规范自动补全或更正。
• 若生命周期中存在资源泄漏风险（如定时器未清理），应在 aboutToDisappear() 中补充清理逻辑。
• 若样式链式调用顺序混乱或混搭不同类别属性，应按“尺寸 → 布局 → 背景 → 边框 → 文本 → 对齐 → 交互”的顺序重排。

1. 优先输出符合规范的示例代码

• 在讲解组件设计、状态管理、列表渲染、事件处理等场景时，示例代码必须遵循本 Skill 约定的写法。
• 对用户给出的“不规范示例”，先指出与本规范不符的点，再给出“✅ 推荐写法”。

1. 显式引用相关章节指导

• 在回答中可提及“参考本 Skill 的 组件装饰器规范 / 生命周期规范 / 样式和布局规范 / 事件处理规范 / 类型安全规范 / 性能优化规范 / 错误处理规范 / 测试规范 章节”。
• 在代码审查类回答中，可根据文末“代码审查清单”逐项给出建议。

1. 保持解释适度、以实践为导向

• 回答时以“如何写出正确 ArkTS 代码”为核心，适当引用规范要点，但避免长篇理论堆砌。
• 对关键规范（如生命周期清理、状态装饰器选择、错误处理等）给出简要原因解释，帮助用户理解而非死记。

⚠️ 强制要求（必须严格遵守）

在使用本 Skill 进行开发时，必须严格遵守以下规范：

1. 构建与编译验证规范（Auto Run）：

• ✅ 当涉及 ArkTS 语法结构调整（包括但不限于组件装饰器、生命周期函数签名、状态管理装饰器、接口/类型声明等）或 依赖相关改动（如 oh-package.json5、module.json5、三方 SDK 引入或移除）时，完成主要修改后应触发一次自动化“auto run”构建流程，而不是只在少数节点手动编译。
• ✅ 推荐在工程根目录配置脚本、IDE Task 或 CI 流水线，使每次提交前自动执行：

1. ohpm install
2. hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon

确保 ArkTSCheck 与打包流程均能通过。

• ✅ 在连续多轮 ArkTS 重构或大规模重命名后，应在合适的里程碑节点手动或自动重复执行上述 auto run 流程，以尽早暴露类型 / 语法 / 依赖问题。
• ❌ 禁止仅依赖本地 Lint 或静态分析结果，而在存在 ArkTS 语法或依赖改动时跳过 hvigor 真机 / 模拟器编译验证或约定的 auto run 流程。

1. 日志输出规范：

• ✅ 必须使用 Logger 工具类封装原生 console
• ✅ 第一个参数必须固定使用场景名 "SportHealthMap"
• ✅ 第二个参数统一使用 string | object，推荐直接传入对象，由 Logger 负责 JSON 序列化
• ✅ Logger 工具类会自动对非字符串参数执行 JSON.stringify 序列化
• ❌ 禁止直接使用 console.info/error/warn/debug
• 示例（推荐用法）：Logger.info('SportHealthMap', JSON.stringify({ action: 'mapReady' }))

1. 代码注释规范：

• ✅ 必须为关键方法添加注释，说明用途、参数、返回值
• ❌ 禁止无意义的注释

1. 模块化规范：

• ✅ 必须将通用工具类、组件、同类Interface等类型定义独立为文件
• ❌ 禁止在页面组件内联定义通用类

1. 性能优化规范：

5.1 对象缓存与复用

• ✅ 必须高频 UI 更新场景必须缓存复用对象，通过成员变量持有引用而非每次重建
• ✅ 必须重型对象（自定义绘制组件、动画控制器、数据适配器等）采用对象池（Object Pool）模式管理，预分配并按需取用归还
• ❌ 禁止同一功能重复创建对象、移除对象（如在定时回调 / 数据刷新中反复 new 再 remove）
• ❌ 禁止在 build() 方法或 @Builder 函数内 new 任何非轻量值对象

5.2 渲染性能

• ✅ 必须列表场景超过 20 项时使用 LazyForEach + IDataSource 实现按需加载，禁止一次性渲染全量数据
• ✅ 必须使用 @Builder 抽取重复 UI 描述片段，避免 build() 内大量重复代码
• ✅ 推荐条件渲染优先使用 if/else 控制组件树分支，而非通过 .visibility(Visibility.None) 隐藏（后者仍参与布局计算）
• ❌ 禁止在 build() 中执行耗时计算、网络请求或文件 I/O

5.3 状态管理精细化

• ✅ 必须将高频变化的状态与低频状态拆分到不同的 @State / @Observed 属性中，避免无关属性变化引发整棵组件树重渲染
• ✅ 推荐使用 @Watch 装饰器监听特定状态变化并执行副作用，替代在 build() 中做差异判断
• ✅ 推荐跨层级数据传递优先使用 @Provide / @Consume 或 AppStorage，而非逐层 @Prop 透传
• ❌ 禁止将大型数组或深层嵌套对象整体赋值给 @State，应使用 @Observed + @ObjectLink 实现属性级精准刷新

5.4 异步与并发

• ✅ 必须耗时操作（网络请求、数据库查询、文件读写、大规模计算）放入 TaskPool 或 Worker 线程执行，禁止阻塞 UI 线程
• ✅ 必须TaskPool.execute() 返回的 Promise 添加 .catch() 兜底，避免静默丢弃异常
• ✅ 推荐批量并发请求使用 Promise.all() / Promise.allSettled() 合并，减少线程调度开销
• ❌ 禁止在定时器回调 (setInterval / setTimeout) 中直接执行重型业务逻辑，应通过消息派发或 TaskPool 转移到后台

5.5 内存管理

• ✅ 必须在 aboutToDisappear() 中清理所有定时器（clearInterval / clearTimeout）、事件订阅（emitter.off）、传感器监听、回调注册等
• ✅ 必须大图片 / Bitmap 资源使用完毕后显式调用 release() 或置空引用，配合 GC 及时回收
• ✅ 推荐使用 WeakRef 持有仅观察但不阻止回收的对象引用，避免闭包意外延长生命周期
• ❌ 禁止组件内持有对其他组件实例的强引用导致交叉引用无法回收
• ❌ 禁止在全局单例（AppStorage / 静态变量）中无限累积数据而不设置上限或淘汰策略

5.6 启动与加载优化

• ✅ 推荐非首屏模块使用动态 import() 延迟加载，减少主包体积与冷启动耗时
• ✅ 推荐首屏数据预取与 UI 构建并行：在 aboutToAppear() 发起请求的同时展示骨架屏 / Loading 占位
• ❌ 禁止在 Ability onCreate() 中执行阻塞性同步调用（如同步读取大文件、同步网络请求）

5.7 包体积与构建产物

• ✅ 推荐定期执行 hvigorw analyzeBundle 分析包体积，识别并移除未使用的资源和依赖
• ✅ 推荐三方 SDK 按需引入子模块，避免全量导入（如 import { SpecificApi } from '@third/sdk' 而非 import * as sdk from '@third/sdk'）
• ❌ 禁止在发布构建中保留 console / hilog.debug 级别日志输出，应通过构建配置或日志等级开关屏蔽

1. 类型声明：

• ✅ 必须自定义的Object对象必须先通过Interface定义类型，然后引用类型定义数据，再使用
• ❌ 禁止使用any unknown 类型标记
• 示例（推荐用法）：export interface Out{ xx: string} function getBaseLocation():Out{let m = {xx:'XXX'};return m}

代理在生成或审查 ArkTS 代码时应优先参考下面内容。

0. ArkTS 类型与空值安全规范

本节在原有“类型安全规范”基础上，补充 ArkTSCheck 相关的强制规则与空值安全约定，用于统一 ArkTS 代码的类型设计、空值处理和语法约束。

1. 类型安全强制规则

• 参数与返回值必须显式类型化：禁止隐式 any unknown。所有函数、方法、回调的参数与返回值都要写明类型。
• 接口驱动的数据结构设计：对于组件 @State / @Prop / @Link、服务入参/出参、全局配置等，优先通过 interface / 类型别名定义结构，再在代码中引用。
• 禁止访问未声明字段：不允许通过字符串索引访问未在类型中声明的属性；确需“字典”结构时，使用索引签名：

interface StringNumberMap {
  [key: string]: number;
}

2. 空值安全策略

• 显式处理 `null` / `undefined`：对类型为 T | null | undefined 或带 ?: 的可选属性，访问前必须通过可选链或显式判空。
• 推荐写法：
• 可选链：user?.name、config?.options?.timeout ?? 3000；
• 显式判空：if (user !== null && user !== undefined) { ... }。
• 避免滥用非空断言 `!`：只有在前面已通过逻辑分支、早返回、抛错等方式完全覆盖空值分支时，才允许使用 !，并建议配合注释说明原因。

3. 函数声明与结构约束（ArkTSCheck 语法规则）

• 禁止解构变量声明：ArkTS 不支持 const { a, b } = obj 形式的解构变量声明（arkts-no-destruct-decls），必须改写为逐一赋值：

// ❌ 不允许
const { lat, lng } = coord;
// ✅ 推荐
const lat = coord.lat;
const lng = coord.lng;

• 业务函数避免参数解构：推荐为参数定义接口或独立参数，而不是 function draw({ text, location }) { ... } 这类难以追踪类型的写法。
• 组件内部优先使用箭头函数：在 build() 中定义事件回调或内部小函数时，推荐 const handler = (): void => { ... }，有利于类型推断与闭包语义清晰。

4. ArkUI 组件属性约束补充

• `TextInput` 不支持 `placeholder` 属性：TextInputAttribute 中无 placeholder，不能调用 .placeholder() 或通过构造参数设置占位符。
• 占位符需求推荐替代方案：
• 使用上方标签文本提示输入含义；
• 使用 Stack 条件渲染一个灰色 Text 叠加在 TextInput 上，在输入内容为空时显示；
• 如当前 HarmonyOS 版本支持，可使用 .placeholderFont() / .placeholderColor() 等 API，而非自定义 .placeholder()。

5. 类型系统约束与接口设计

• 避免依赖纯结构等价赋值：不要仅因为两个类字段“长得一样”就在它们之间互相赋值，应通过接口或基类统一约束：

interface WithNumber {
  n: number;
}
class X implements WithNumber {
  n: number = 0;
}
class Y implements WithNumber {
  n: number = 0;
}
let value: WithNumber = new X(); // ✅ 通过公共接口约束

• 在建模与重构时，优先：
• 定义领域接口 / 抽象基类；
• 让具体实现 implements / extends 这些公共类型，而不是在不同类之间直接赋值。

6. 综合示例：类型安全 + 空值安全的路由跳转

在涉及路由表的场景中，必须为路由配置定义接口，并对 find 结果与可选 path 做空值处理：

interface RouteConfig {
  id: string;
  path?: string;
}
const routes: RouteConfig[] = [
  { id: 'home', path: 'pages/Home' },
  { id: 'detail', path: 'pages/Detail' }
];
function navigateToPage(pageId: string): void {
  const targetRoute: RouteConfig | undefined = routes.find(
    (route: RouteConfig) => route.id === pageId
  );
  if (targetRoute?.path) {
    router.push({ url: targetRoute.path });
    return;
  }
  if (!targetRoute || !targetRoute.path) {
    // 记录日志或给出兜底处理
    return;
  }
  router.push({ url: targetRoute.path });
}

在回答类似问题时，应通过上述模式同时保证：

• 所有参数 / 返回值有显式类型；
• 通过接口约束配置结构；
• 对可能为空的字段和查找结果做完备校验。

1. 组件装饰器规范

1.1 组件必须使用装饰器

• 入口组件必须使用 @Entry 装饰器
• 页面组件必须使用 @Component 装饰器
• 自定义组件必须使用 @Component 装饰器

// ✅ 正确示例
@Entry
@Component
struct Index {
  // 组件实现
}
@Component
struct ChildChip {
  // 组件实现
}

1.2 状态管理装饰器

根据数据流动方向选择合适的装饰器：

• @State：组件内部的状态，变化会触发UI更新
• @Prop：从父组件传递到子组件的只读数据
• @Link：父子组件双向绑定的数据
• @Provide / @Consume：跨层级组件数据共享
• @Observed / @ObjectLink：对象属性级别的响应式更新
• @StorageProp / @StorageLink：持久化存储

@Component
struct ParentComponent {
  @State count: number = 0;          // 内部状态
  @State message: string = "Hello";
  build() {
    Column() {
      ChildComponent({ count: this.count, message: this.message })
    }
  }
}
@Component
struct ChildComponent {
  @Prop count: number;               // 只读属性
  @Link message: string;             // 双向绑定
  build() {
    // ...
  }
}

2. 组件生命周期规范

2.1 生命周期装饰器

必须按照规范的顺序定义生命周期方法：

• aboutToAppear()：组件即将显示时调用
• aboutToDisappear()：组件即将消失时调用
• onPageShow()：页面显示时调用（仅Page组件）
• onPageHide()：页面隐藏时调用（仅Page组件）

@Component
struct MyComponent {
  private timerId: number | undefined = undefined;
  aboutToAppear() {
    // 初始化数据
    this.timerId = setInterval(() => {
      // 定时任务
    }, 1000);
  }
  aboutToDisappear() {
    // 清理资源
    if (this.timerId) {
      clearInterval(this.timerId);
    }
  }
}

3. 样式和布局规范

3.1 链式调用

样式属性必须使用链式调用，按以下顺序组织：

1. 尺寸属性：.width(), .height(), .size()
2. 布局属性：.margin(), .padding()
3. 背景属性：.backgroundColor(), .backgroundImage()
4. 边框属性：.borderRadius(), .borderWidth(), .borderColor()
5. 文本属性：.fontSize(), .fontColor(), .fontWeight()
6. 对齐属性：.justifyContent(), .alignItems()
7. 交互属性：.onClick(), .onTouch()

// ✅ 最佳实践
Text('Hello ArkTS')
  .fontSize(20)
  .fontColor(Color.White)
  .fontWeight(FontWeight.Bold)
  .backgroundColor('#4F8DFF')
  .padding({ left: 16, right: 16, top: 8, bottom: 8 })
  .borderRadius(8)
  .onClick(() => {
    // 点击事件
  })
// ❌ 避免：混合编码风格
Text('Hello ArkTS')
  .fontSize(20).backgroundColor('#4F8DFF')  // 不应该混合不同类型的属性

3.2 响应式单位

• 优先使用百分比：'100%' 而不是固定值
• 推荐使用 vp（虚拟像素）适配不同分辨率
• 文本使用 fp（字体像素）保证字体大小一致性

// ✅ 响应式设计
Column()
  .width('100%')
  .height('100%')
  .padding(10)
Text('标题')
  .fontSize(16)
  .margin({ top: 10 })

4. 事件处理规范

4.1 事件回调函数

• 使用箭头函数避免this绑定的问题
• 复杂逻辑封装到私有方法中
• 避免在build方法中直接写复杂逻辑

@Component
struct MyComponent {
  @State count: number = 0;
  private handleClick() {
    this.count++;
    // 复杂逻辑处理
  }
  build() {
    Column() {
      Button('点击')
        .onClick(() => {
          this.handleClick();  // ✅ 调用封装的方法
        })
      // ❌ 避免：直接在事件中写复杂逻辑
      Button('不推荐')
        .onClick(() => {
          this.count++;
          fetchData().then(() => {
            // 复杂异步逻辑
          });
        })
    }
  }
}

5. 类型安全规范

5.1 接口定义

组件之间的数据传递必须定义明确的接口：

// ✅ 明确的接口定义
interface ChildInfo {
  id: string;
  name: string;
  avatarColor: string;
}
@Component
struct ChildChip {
  @Prop child: ChildInfo;  // 明确指定类型
  @Prop selected: boolean;
  @Prop onSelect: (id: string) => void;  // 明确的函数签名
  build() {
    // ...
  }
}

5.2 泛型使用

对于可复用的组件，使用泛型提高类型安全性：

@Component
struct ListItem<T> {
  @Prop item: T;
  @Prop renderItem: (item: T) => void;
  build() {
    // 渲染逻辑
  }
}

6. 性能优化规范

6.1 对象缓存与复用

• 高频更新场景（如实时数据刷新、动画帧更新）必须缓存对象引用，仅更新属性而非销毁重建
• 使用对象池模式管理重型对象的分配与回收

// ✅ 通用对象池模式示例
class ObjectPool<T> {
  private pool: Array<T> = [];
  private activeMap: Map<string, T> = new Map();
  private factory: (options: object) => T;
  private resetter: (item: T, options: object) => void;
  constructor(factory: (options: object) => T, resetter: (item: T, options: object) => void) {
    this.factory = factory;
    this.resetter = resetter;
  }