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 ```typescript @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. ## Events and Lifecycle - Use arrow functions for event handlers (`.onClick(() => this.handleTap())` or a bound class field like `private handleTap = () => {...}`) so `this` binds correctly without extra boilerplate. - Keep event handlers themselves short — read the event, then delegate any non-trivial logic to a named method that can be tested and reasoned about independently. - Handle async failures explicitly (`try`/`catch` around `await`) and surface user-facing errors (a toast, an inline error state) instead of letting a rejected promise disappear silently. - Use lifecycle hooks (`aboutToAppear`, `aboutToDisappear`, `onPageShow`, `onPageHide`, `onBackPress`) only for setup/teardown that genuinely depends on the component or page's lifecycle — don't use them as a dumping ground for logic that could live in a regular method. ## Resources and Accessibility - Use `$r()` to reference app resources (strings, colors, media, floats) instead of embedding literal values directly in component code. - Group resource references consistently — organize `resources/base/element/string.json`, `color.json`, `float.json` by feature or screen so they stay navigable as the app grows. - Add descriptive accessibility labels (`.accessibilityText()`, `.accessibilityDescription()`) and correct focus handling (`.focusable(true)`, `.tabIndex()`) for every interactive element. - Maintain sufficient color contrast between text and background, and keep touch targets at least the platform-recommended minimum size (generally 40vp or larger) for anything tappable. - Test on representative device sizes and orientations (phone, foldable, tablet, landscape/portrait) since ArkUI layouts that look correct on one form factor can break on another. ## Common Mistakes - Burying business logic (data fetching, validation, complex branching) directly inside `build()` instead of in dedicated methods — `build()` should read like a UI tree, not a program. - Using `@Link` two-way binding when a simple one-way `@Prop` would do, which makes data flow harder to trace and invites accidental mutation from child components. - Hardcoding repeated strings, colors, and dimensions that belong in the resource system, making localization and theming changes require hunting through component code. - Leaving debug `console.log`/`console.info` calls in production code paths, which adds noise and can leak internal state into logs.