arkts-development

ArkTS 開発

ArkTS と ArkUI 宣言型 UI フレームワークを使用して、HarmonyOS アプリケーションを構築します。

クイックスタート

基本的なコンポーネントを作成します。

@Entry
@Component
struct HelloWorld {
  @State message: string = 'Hello, ArkTS!';

  build() {
    Column() {
      Text(this.message)
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
      Button('Click Me')
        .onClick(() => { this.message = 'Button Clicked!'; })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

状態管理デコレーター

V1（従来型）

デコレーター	使用方法	説明
@State	@State count: number = 0	コンポーネント内部の状態
@Prop	@Prop title: string	親 → 子（一方向）
@Link	@Link value: number	親 ↔ 子（双方向。$varName を使用）
@Provide/@Consume	階層をまたぐ	祖先 → 子孫
@Observed/@ObjectLink	ネストされたオブジェクト	オブジェクトの深い階層まで監視

V2（推奨 - API 12+）

デコレーター	使用方法	説明
@ComponentV2	@ComponentV2 struct MyComp	V2 状態管理を有効化
@Local	@Local count: number = 0	内部状態（外部からの初期化なし）
@Param	@Param title: string = ""	親 → 子（一方向、効率的）
@Event	@Event onChange: () => void	子 → 親（コールバック）
@ObservedV2	@ObservedV2 class Data	クラスの監視
@Trace	@Trace name: string	プロパティレベルの追跡
@Computed	@Computed get value()	キャッシュされた計算プロパティ
@Monitor	@Monitor('prop') onFn()	変更前後の値を監視
@Provider/@Consumer	階層をまたぐ	ツリー全体で双方向同期

V2 の完全なガイドについては、references/state-management-v2.md を参照してください。

一般的なレイアウト

// Vertical
Column({ space: 10 }) { Text('A'); Text('B'); }
  .alignItems(HorizontalAlign.Center)

// Horizontal
Row({ space: 10 }) { Text('A'); Text('B'); }
  .justifyContent(FlexAlign.SpaceBetween)

// Stack (overlay)
Stack({ alignContent: Alignment.Center }) {
  Image($r('app.media.bg'))
  Text('Overlay')
}

// List with ForEach
List({ space: 10 }) {
  ForEach(this.items, (item: string) => {
    ListItem() { Text(item) }
  }, (item: string) => item)
}

コンポーネントのライフサイクル

@Entry
@Component
struct Page {
  aboutToAppear() { /* Init data */ }
  onPageShow() { /* Page visible */ }
  onPageHide() { /* Page hidden */ }
  aboutToDisappear() { /* Cleanup */ }
  build() { Column() { Text('Page') } }
}

ナビゲーション

import { router } from '@kit.ArkUI';

// Push
router.pushUrl({ url: 'pages/Detail', params: { id: 123 } });

// Replace
router.replaceUrl({ url: 'pages/New' });

// Back
router.back();

// Get params
interface RouteParams {
  id: number;
  title?: string;
}
const params = router.getParams() as RouteParams;

ネットワークリクエスト

import { http } from '@kit.NetworkKit';

const req = http.createHttp();
const res = await req.request('https://api.example.com/data', {
  method: http.RequestMethod.GET,
  header: { 'Content-Type': 'application/json' }
});
if (res.responseCode === 200) {
  const data = JSON.parse(res.result as string);
}
req.destroy();

ローカルストレージ

import { preferences } from '@kit.ArkData';

const prefs = await preferences.getPreferences(this.context, 'store');
await prefs.put('key', 'value');
await prefs.flush();
const val = await prefs.get('key', 'default');

ArkTS 言語の制約

ArkTS は、パフォーマンスと安全性のため、TypeScript よりも厳格なルールを適用します。

使用禁止	代わりに使用
any、unknown	明示的な型、インターフェース
var	let、const
動的なプロパティアクセス obj['key']	固定されたオブジェクト構造
for...in、delete、with	for...of、配列メソッド
#privateField	private キーワード
構造的型付け	明示的な implements/extends

TypeScript から ArkTS への移行の詳細については、references/migration-guide.md を参照してください。

コマンドラインテスト（hvigorw）

ビルド、クリーン、パッケージング、デバイスへのインストールについては、harmonyos-build-deploy スキルで扱っています。これらのワークフローには同スキルを使用してください。hvigorw のフラグの完全なリファレンスは、references/hvigor-commandline.md にあります。

テストコマンド：

# Run all tests for a module
hvigorw onDeviceTest -p module=entry -p coverage=true --no-daemon   # On-device
hvigorw test -p module=entry --no-daemon                            # Local (host-side)

# Run a single test suite or single test (on-device)
hvigorw onDeviceTest -p module=entry -p testParam="{\"unittest\":\"TestClassName\"}" --no-daemon
hvigorw onDeviceTest -p module=entry -p testParam="{\"unittest\":\"TestClassName#testMethodName\"}" --no-daemon

コードリンター（codelinter）

codelinter は、ArkTS/TS ファイルのチェックと修正を行うツールです。

# Basic usage
codelinter                           # Check current project
codelinter /path/to/project          # Check specified project
codelinter -c ./code-linter.json5    # Use custom rules

# Check and auto-fix
codelinter --fix
codelinter -c ./code-linter.json5 --fix

# Output formats
codelinter -f json -o ./report.json  # JSON report
codelinter -f html -o ./report.html  # HTML report

# Incremental check (Git changes only)
codelinter -i

# CI/CD with exit codes
codelinter --exit-on error,warn      # Non-zero exit on error/warn

パラメーター	説明
-c, --config <file>	ルール設定ファイルを指定します
--fix	対応している問題を自動修正します
-f, --format	出力形式：default/json/xml/html
-o, --output <file>	結果をファイルに保存します
-i, --incremental	Git で変更されたファイルのみをチェックします
-p, --product <name>	製品を指定します
-e, --exit-on <levels>	終了コードのレベル：error,warn,suggestion

完全なリファレンスについては、references/codelinter.md を参照してください。

スタックトレースパーサー（hstack）

hstack は、Release ビルドで難読化されたクラッシュスタックを、ソースコード上の位置に復元します。

# Parse crash files directory
hstack -i crashDir -o outputDir -s sourcemapDir -n nameCacheDir

# Parse with C++ symbols
hstack -i crashDir -o outputDir -s sourcemapDir --so soDir -n nameCacheDir

# Parse single crash stack
hstack -c "at func (entry|entry|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir

パラメーター	説明
-i, --input	クラッシュファイルのディレクトリ
-c, --crash	単一のクラッシュスタック文字列
-o, --output	出力ディレクトリ（-c と併用する場合はファイル）
-s, --sourcemapDir	Sourcemap ファイルのディレクトリ
--so, --soDir	共有オブジェクト（.so）ファイルのディレクトリ
-n, --nameObfuscation	NameCache ファイルのディレクトリ

要件：

• -i または -c のいずれかを指定する必要があります（両方は指定できません）
• -s または --so のいずれかを指定する必要があります
• メソッド名を復元するには、-s と -n の両方を指定してください

完全なリファレンスについては、references/hstack.md を参照してください。

コード難読化（ArkGuard）

build-profile.json5 で有効にします。

"arkOptions": {
  "obfuscation": {
    "ruleOptions": {
      "enable": true,
      "files": ["./obfuscation-rules.txt"]
    }
  }
}

obfuscation-rules.txt の共通ルール：

-enable-property-obfuscation      # Property name obfuscation
-enable-toplevel-obfuscation      # Top-level scope obfuscation
-enable-filename-obfuscation      # Filename obfuscation
-keep-property-name apiKey        # Whitelist specific names

詳しいガイドについては、references/arkguard-obfuscation.md を参照してください。

リファレンスファイル

• State Management V2：references/state-management-v2.md - V2 の状態管理に関する完全ガイド（@ComponentV2、@Local、@Param、@Event、@ObservedV2、@Trace、@Computed、@Monitor、@Provider、@Consumer）
• V1 から V2 への移行：references/state-management-v2-migration.md - V1 から V2 デコレーターへの段階的な移行
• V2 のベストプラクティス：references/state-management-v2-practices.md - V2 のベストプラクティスとトラブルシューティング
• 移行ガイド：references/migration-guide.md - TypeScript から ArkTS への完全な移行ルールと例
• コンポーネントパターン：references/component-patterns.md - 高度なコンポーネントパターンとベストプラクティス
• API リファレンス：references/api-reference.md - HarmonyOS の一般的な API
• ArkGuard の難読化：references/arkguard-obfuscation.md - コード難読化の設定とトラブルシューティング
• Hvigor コマンドライン：references/hvigor-commandline.md - hvigorw ビルドツールの完全なリファレンス
• CodeLinter：references/codelinter.md - コードのチェックと修正を行うツール
• Hstack：references/hstack.md - Release ビルド用のクラッシュスタックトレースパーサー

開発環境

• IDE：DevEco Studio
• SDK：HarmonyOS SDK
• シミュレーター：DevEco Studio に組み込まれたエミュレーター

関連スキル

• ビルドとデプロイ：ビルド、パッケージ化、デバイスへのインストールについては、harmonyos-build-deploy スキルを参照してください