everything-claude-code/docs/ja-JP/rules/arkts/patterns.md

paths

paths
**/*.ets **/*.ts

HarmonyOS / ArkTS パターン

このファイルは common/patterns.md を HarmonyOS および ArkTS 固有のパターンで拡張します。

状態管理: V2 のみ

ArkUI 状態管理 V2 を必ず使用すること。V1 デコレーターは非推奨であり、使用してはならない。

V2 デコレーター

デコレーター	用途
@ComponentV2	構造体を V2 コンポーネントとしてマークする
@Local	コンポーネント内のローカル状態
@Param	親から受け取るプロパティ（読み取り専用）
@Event	子から親へのコールバックイベント
@Provider	子孫コンポーネントへ状態を提供する
@Consumer	祖先の @Provider から状態を取得する
@Monitor	状態変化を監視する（V1 の @Watch を置き換え）
@Computed	派生/計算された値
@ObservedV2	V2 状態管理のためにクラスをオブザーバブルにする
@Trace	@ObservedV2 クラスのオブザーバブルプロパティをマークする

禁止されている V1 デコレーター

絶対に使用しないこと: @State、@Prop、@Link、@ObjectLink、@Observed、@Provide、@Consume、@Watch、@Component（代わりに @ComponentV2 を使用）。

V2 コンポーネントの例

@ObservedV2
class UserModel {
  @Trace name: string = ''
  @Trace age: number = 0
}

@ComponentV2
struct UserCard {
  @Param user: UserModel = new UserModel()
  @Event onDelete: () => void = () => {}

  build() {
    Column() {
      Text(this.user.name)
        .fontSize($r('app.float.font_size_title'))
      Text(`${this.user.age}`)
        .fontSize($r('app.float.font_size_body'))
      Button($r('app.string.delete'))
        .onClick(() => this.onDelete())
    }
  }
}

状態の同期

@ComponentV2
struct ParentPage {
  @Provider('userState') userModel: UserModel = new UserModel()

  build() {
    Column() {
      ChildComponent()  // @Consumer('userState') を自動的に受け取る
    }
  }
}

@ComponentV2
struct ChildComponent {
  @Consumer('userState') userModel: UserModel = new UserModel()

  build() {
    Text(this.userModel.name)
  }
}

ルーティング: Navigation のみ

NavPathStack を使用した Navigation コンポーネントを必ず使用すること。@ohos.router は絶対に使用しないこと。

Navigation のセットアップ

@ComponentV2
struct MainPage {
  @Local navPathStack: NavPathStack = new NavPathStack()

  build() {
    Navigation(this.navPathStack) {
      // ホームコンテンツ
    }
    .navDestination(this.routerMap)
  }

  @Builder
  routerMap(name: string, param: ESObject) {
    if (name === 'detail') {
      DetailPage()
    } else if (name === 'settings') {
      SettingsPage()
    }
  }
}

ページナビゲーション

// 新しいページをプッシュする
this.navPathStack.pushPath({ name: 'detail', param: { id: '123' } })

// 現在のページを置き換える
this.navPathStack.replacePath({ name: 'settings' })

// 戻る
this.navPathStack.pop()

// ルートに戻る
this.navPathStack.clear()

NavDestination サブページ

@ComponentV2
struct DetailPage {
  build() {
    NavDestination() {
      Column() {
        Text($r('app.string.detail_title'))
      }
    }
    .title($r('app.string.detail_nav_title'))
  }
}

アーキテクチャパターン: MVVM

HarmonyOS アプリケーションに推奨されるアーキテクチャ:

feature/
  |-- model/           # データモデル（@ObservedV2 クラス）
  |-- viewmodel/       # ビジネスロジック（ViewModel クラス）
  |-- view/            # UI コンポーネント（@ComponentV2 構造体）
  |-- service/         # API 呼び出し、データアクセス

• View: レンダリングロジックのみ、build() 内にビジネスロジックを含めない
• ViewModel: すべてのビジネスロジックをここにカプセル化する
• Model: @ObservedV2 と @Trace を持つ純粋なデータクラス
• Service: ネットワークリクエスト、データベース操作、ファイル I/O

ArkUI アニメーションパターン

状態駆動アニメーション

@ComponentV2
struct AnimatedCard {
  @Local isExpanded: boolean = false
  @Local cardScale: number = 0.8

  build() {
    Column() {
      // コンテンツ
    }
    .scale({ x: this.cardScale, y: this.cardScale })
    .animation({ duration: 300, curve: Curve.EaseInOut })
    .onClick(() => {
      this.isExpanded = !this.isExpanded
      this.cardScale = this.isExpanded ? 1.0 : 0.8
    })
  }
}

アニメーションのルール

• ネイティブ HarmonyOS アニメーション API と高度なテンプレートを優先する
• 状態変数の変更でアニメーションをトリガーする状態駆動アニメーションを持つ宣言的 UI を使用する
• 複雑なサブコンポーネントアニメーションのレンダリングバッチを削減するために renderGroup(true) を設定する
• アニメーション中に width、height、padding、margin を頻繁に変更しないこと — パフォーマンスに深刻な影響
• 明示的なアニメーション制御には animateTo を使用する
• パフォーマンスの高いアニメーションには transform（translate、scale、rotate）と opacity を優先する

パフォーマンスパターン

大きなリストへの LazyForEach

@ComponentV2
struct LargeList {
  @Local dataSource: MyDataSource = new MyDataSource()

  build() {
    List() {
      LazyForEach(this.dataSource, (item: ItemModel) => {
        ListItem() {
          ItemComponent({ item: item })
        }
      }, (item: ItemModel) => item.id)
    }
  }
}

コンポーネントの再利用

• 再利用可能なコンポーネントを別のファイルに抽出する
• コンポーネント内の軽量な UI フラグメントには @Builder を使用する
• 設定可能なコンポーネントには @Param を使用する

リソース参照

UI 定数は常にリソースとして定義し、$r() 経由で参照する:

// BAD: ハードコードされた値
Text('Hello')
  .fontSize(16)
  .fontColor('#333333')

// GOOD: リソース参照
Text($r('app.string.greeting'))
  .fontSize($r('app.float.font_size_body'))
  .fontColor($r('app.color.text_primary'))