harmony-arkts

HarmonyOS ArkTS 开发

此技能涵盖使用 ArkTS 和声明式 ArkUI 框架构建 HarmonyOS 应用，包括组件结构、状态管理、布局、生命周期、资源和无障碍功能。

构建 ArkTS 组件的工作流

1. 定义组件 — 创建一个使用 @Component 装饰、以 PascalCase 命名的 struct。
2. 在顶部附近声明状态 — 先列出 @State、@Prop、@Link 和其他状态装饰器，再编写任何方法。
3. 添加生命周期钩子 — 在状态声明之后、build() 之前实现 aboutToAppear()/aboutToDisappear()（以及其他需要的钩子）。
4. 在 build() 中组合 UI — 将 build() 放在最后，使用 ArkUI 基元（Column、Row、Stack、List 等）布局子组件。
5. 提取复杂 UI — 当 build() 变得很长或嵌套较深时，将其中的部分提取为更小的 @Component struct 或 @Builder 函数。
6. 连接事件 — 附加箭头函数事件处理程序，并将复杂逻辑委托给组件中命名的方法。
7. 外置资源 — 将字符串、颜色、尺寸和图像移至资源系统，并通过 $r() 引用。
8. 验证无障碍功能和响应式布局 — 添加无障碍标签，检查触摸目标尺寸，并在具有代表性的设备尺寸和方向上进行测试。

组件结构

• 使用 @Component 定义组件，并使用 PascalCase 命名组件 struct（例如，struct UserProfileCard）。
• 将状态声明（@State、@Prop、@Link、@StorageLink、普通字段）放在组件顶部附近，置于方法和生命周期钩子之前。
• 将生命周期钩子（aboutToAppear、aboutToDisappear、onPageShow、onPageHide）放在 build() 之前，方便查看组件的生命周期。
• 将 build() 放在最后，并让它专注于 UI 组合——将数据转换和业务逻辑移出 build()，改为在其中调用方法，而不是内联编写。
• 当 build() 方法内容超过一屏，或嵌套超过几层时，将复杂 UI 提取为更小的 @Component struct（或用于轻量级可复用 UI 片段的 @Builder 函数）。

状态和数据流

• 对由组件自身拥有并修改的状态使用 @State。
• 对单向的父级到子级数据使用 @Prop——子级会获得自己的副本，局部修改不会向上回传。
• 仅在确实需要子级修改父级状态的双向绑定场景中使用 @Link（例如自定义表单控件）。
• 将派生值放在计算型辅助方法中，而不是重复存储并手动同步状态（当 itemCount 可以通过 this.items.length 得到时，不要将 items 和 itemCount 分别存储为 @State 字段）。
• 除非项目已有成熟的应用状态模式，否则避免宽泛地使用全局状态（不加区分地使用 AppStorage/LocalStorage）；对于并非真正全局的数据，优先通过 props/links 向下传递。

示例：具有状态、Props 和生命周期的组件

@Component
export struct CounterCard {
  @Prop label: string = 'Counter';
  @State private count: number = 0;
  private maxCount: number = 99;

  aboutToAppear(): void {
    console.info(`CounterCard mounted with label=${this.label}`);
  }

  private increment = (): void => {
    if (this.count >= this.maxCount) {
      return;
    }
    this.count += 1;
  };

  private reset = (): void => {
    this.count = 0;
  };

  build() {
    Column({ space: 12 }) {
      Text(this.label)
        .fontSize(18)
        .fontWeight(FontWeight.Medium)

      Text(`${this.count}`)
        .fontSize(32)
        .fontColor($r('app.color.primary'))
        .accessibilityText(`Current count is ${this.count}`)

      Row({ space: 8 }) {
        Button('Increment')
          .onClick(this.increment)
          .accessibilityText('Increment counter')

        Button('Reset')
          .onClick(this.reset)
          .accessibilityText('Reset counter')
      }
    }
    .width('100%')
    .padding(16)
    .alignItems(HorizontalAlign.Center)
  }
}

布局与样式

• 根据实际需要的轴向和堆叠行为，有意识地使用 Column、Row、Stack、List 和其他 ArkUI 布局原语，而不是默认使用 Stack 并将所有内容绝对定位。
• 在链式修饰符调用中，先设置布局属性——宽度、高度、对齐方式、布局权重（layoutWeight）——再设置视觉属性（颜色、字体、边框），让结构先于装饰呈现。
• 当各边的值不同时，使用对象表示法设置边距和内边距（.margin({ top: 8, bottom: 16, left: 12, right: 12 })），而不是使用暗示间距一致的简写。
• 尺寸统一使用逻辑像素（vp），确保布局能够适应不同设备像素密度；避免混用原始像素值。
• 对于应相对于父容器而非使用硬编码固定值的尺寸，使用百分比字符串（'100%'、'50%'）。
• 如果项目支持资源系统，请将可复用的间距、颜色和排版值保存在其中（$r('app.color.primary')、$r('app.float.spacing_md')），而不是在各组件中重复使用字面值。

事件与生命周期

• 使用箭头函数作为事件处理程序（.onClick(() => this.handleTap())，或使用绑定的类字段，如 private handleTap = () => {...}），确保 this 正确绑定，无需额外样板代码。
• 事件处理程序本身应简短——读取事件后，将任何非简单逻辑交给命名方法，以便独立测试和理解。
• 明确处理异步失败（在 await 外围使用 try/catch），并向用户显示错误（Toast、内联错误状态），不要让被拒绝的 Promise 悄然消失。
• 仅在确实需要依赖组件或页面生命周期进行设置或清理时，才使用生命周期钩子（aboutToAppear、aboutToDisappear、onPageShow、onPageHide、onBackPress）；不要将本可放在常规方法中的逻辑都塞进生命周期钩子。

资源与无障碍

• 使用 $r() 引用应用资源（字符串、颜色、媒体、浮点值），而不是在组件代码中直接嵌入字面值。
• 以一致的方式组织资源引用——按功能或屏幕整理 resources/base/element/string.json、color.json、float.json，让应用扩展后仍便于查找。
• 为每个交互元素添加描述性无障碍标签（.accessibilityText()、.accessibilityDescription()），并正确处理焦点（.focusable(true)、.tabIndex()）。
• 确保文本与背景之间有足够的颜色对比度，并使所有可点击元素的触控目标至少达到平台建议的最小尺寸（通常为 40vp 或更大）。
• 在有代表性的设备尺寸和方向上进行测试（手机、折叠屏、平板、横屏／竖屏），因为在一种设备形态上显示正常的 ArkUI 布局，在另一种设备上可能会出现问题。

常见错误

• 将业务逻辑（数据获取、验证、复杂分支）直接塞进 build()，而不是放在专用方法中——build() 应该像 UI 树，而不是程序。
• 在简单的单向 @Prop 足以满足需求时使用 @Link 双向绑定，这会让数据流更难追踪，也容易导致子组件意外修改数据。
• 将本应放在资源系统中的重复字符串、颜色和尺寸硬编码，导致本地化和主题修改都需要在组件代码中逐一查找。
• 在生产代码路径中保留调试用的 console.log／console.info 调用，造成冗余，还可能将内部状态泄露到日志中。