Harmony Arkts

HarmonyOS ArkTS Development

This skill covers building HarmonyOS applications with ArkTS and the declarative ArkUI framework, including component structure, state management, layout, lifecycle, resources, and accessibility.

Workflow for Building an ArkTS Component

1. Define the component — Create a struct decorated with @Component, named in PascalCase.
2. Declare state near the top — List @State, @Prop, @Link, and other state decorators first, before any methods.
3. Add lifecycle hooks — Implement aboutToAppear()/aboutToDisappear() (and others as needed) after state, before build().
4. Compose the UI in build() — Place build() last, using ArkUI primitives (Column, Row, Stack, List, etc.) to lay out child components.
5. Extract complex UI — Once build() grows large or nested, pull sections into smaller @Component structs or @Builder functions.
6. Wire events — Attach arrow-function event handlers that delegate non-trivial logic to named methods on the component.
7. Externalize resources — Move strings, colors, dimensions, and images into the resource system and reference them with $r().
8. Verify accessibility and responsiveness — Add accessibility labels, check touch target sizes, and test across representative device sizes/orientations.

Component Structure

• Use @Component to define components and PascalCase for the component struct name (e.g., struct UserProfileCard).
• Keep state declarations (@State, @Prop, @Link, @StorageLink, plain fields) near the top of the component, before methods and lifecycle hooks.
• Group lifecycle hooks (aboutToAppear, aboutToDisappear, onPageShow, onPageHide) before build() so the component's lifecycle is easy to scan.
• Place build() last and keep it focused purely on UI composition — pull data transformation and business logic out into methods called from build(), not embedded inline.
• Extract complex UI into smaller @Component structs (or @Builder functions for lightweight, reusable UI fragments) once a build() method grows past a screenful or nests more than a few levels deep.

State and Data Flow

• Use @State for state owned and mutated by the component itself.
• Use @Prop for one-way parent-to-child data — the child gets its own copy and local changes don't propagate back up.
• Use @Link only for intentional two-way binding where the child genuinely needs to mutate the parent's state (e.g., a custom form control).
• Keep derived values in computed helper methods rather than duplicating and manually syncing state (don't store both items and itemCount as separate @State fields when itemCount can be this.items.length).
• Avoid broad global state (AppStorage/LocalStorage used indiscriminately) unless the project has an established app-state pattern; prefer passing data down through props/links for anything not genuinely global.

Example: A Component with State, Props, and Lifecycle

@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)
  }
}

Layout and Styling

• Use Column, Row, Stack, List, and other ArkUI layout primitives intentionally based on the axis and stacking behavior actually needed, rather than defaulting to Stack and positioning everything absolutely.
• Group layout properties — width, height, alignment, layout weight (layoutWeight) — before visual properties (color, font, border) in the chained modifier calls, so structure reads before decoration.
• Use object notation for margin and padding when the sides differ (.margin({ top: 8, bottom: 16, left: 12, right: 12 })) rather than a single shorthand that implies uniform spacing.
• Use logical pixels (vp) consistently for sizes so layouts scale correctly across device pixel densities; avoid mixing raw pixel values.
• Use percentage strings ('100%', '50%') for sizes that should be relative to the parent container instead of hardcoded fixed values.
• Keep reusable spacing, colors, and typography values in the resource system ($r('app.color.primary'), $r('app.float.spacing_md')) when the project supports it, instead of repeating literals across components.