android-native-ui

Android Native UI

Android インターフェースをプラットフォームの契約に沿って構築、レビューします。Compose のセマンティクス、ライフサイクルを考慮した状態管理、ウィンドウへの適応、Material／システムとの統合、戻るナビゲーション、アクセシビリティを重視し、Web ARIA やピクセル単位の一致には依存しません。

UI の境界を特定する

Android Views と Compose の使い分け、Material 3／カスタムデザインシステム、最小 SDK、ナビゲーションライブラリ、状態ホルダー、プロジェクトが Android 専用か Compose Multiplatform かを確認します。

Compose Multiplatform では、移植可能な UI を commonMain に配置し、Context、権限、戻る操作の処理、ウィンドウ API などの Android API はプラットフォーム境界に分離します。リリース対象の各プラットフォームを個別に検証してください。

最新のプラットフォームガイダンス

API、動作、Material の規約、ツール、検証方法が Android／Compose／Kotlin のリリースによって変わる可能性がある場合は、API の推奨や実装の前に、現在の Android 公式情報（developer.android.com、AndroidX のリリースノート、必要に応じて Kotlin ドキュメント）を検索してください。API を推奨する前に、プロジェクトの SDK、Compose BOM／ライブラリのバージョン、リリース対象の Compose Multiplatform プラットフォームを確認します。ここでの例は長期にわたって有効な契約を示すものであり、リリース固有のドキュメントに代わるものではありません。

状態、エフェクト、コンポーネント API

状態は、それを制御する必要がある呼び出し元までに限って引き上げます。永続的な画面状態と単発イベントは分けてモデル化します。Android ではフローをライフサイクル対応で収集し、命令的な処理にはコンポーザブル本体ではなく、LaunchedEffect、DisposableEffect などの明示的なエフェクトを使います。

@Composable
fun SaveButton(
    enabled: Boolean,
    onSave: () -> Unit,
    modifier: Modifier = Modifier,
) {
    Button(
        onClick = onSave,
        enabled = enabled,
        modifier = modifier,
    ) {
        Text("Save")
    }
}

再利用可能なコンポーザブルでは、外側の境界に Modifier を公開し、ネイティブコントロールのセマンティクスを保ちます。状態モデルやスロットの方が明確な場合は、真偽値やプリミティブ型のパラメーターを増やさないようにします。修飾子の順序は慎重に確認してください。タッチ領域、クリッピング、パディング、インジケーション、セマンティクスは、順序によって変わることがあります。

Compose のパフォーマンスとモーション

コンポジション、レイアウト、描画はそれぞれ異なるフェーズです。フィードバックループが安全であることを証明できない限り、レイアウトから導出した状態を、コンポジション中に兄弟が読み取るようにしないでください。頻繁に実行されるコンポーザブル本体で、コストの高い割り当てやコレクション処理を避け、遅延コレクションでは安定したキーを使います。アニメーション、スクロール、ジェスチャーの状態は、意図した効果を得られる範囲で最も遅いフェーズで読み取ります。

アニメーションは状態に基づかせ、操作時にはキャンセルできるようにし、Android のアニメーター再生時間倍率が低く設定されている場合や無効な場合でも利用できるようにします。アニメーションの計測や最終状態の読み取りは、表示上またはセマンティクス上の完了条件を満たすまで待ってください。

アクセシビリティと適応

Compose は ARIA ではなく、セマンティクスツリーを使用します。コンテンツの説明、ロール、状態の説明、カスタムアクション、トラバーサル順序、統合されたセマンティクス、フォーカス、TalkBack、タッチ領域、無効状態をテストしてください。contentDescription = null が適切なのは、装飾目的のコンテンツに限られます。

デバイスの種類ではなく、ウィンドウサイズクラスと利用可能なスペースに応じて適応させます。必要に応じて、コンパクトなウィンドウと拡張されたウィンドウ、大きなフォントスケール、ダークテーマ、ディスプレイの切り欠き／インセット、キーボード、レイアウト方向、予測型／システムの戻る操作をテストしてください。

Icon(
    imageVector = Icons.Default.Star,
    contentDescription = null, // decorative beside visible text
)

Android のレンダリングに関する主張をする前に、references/android-verification.md を確認してください。ここには、最低限必要な検証手順とセマンティクスに基づく例が記載されています。

推奨／非推奨

推奨	非推奨
意図的なテーマ設定を施した Material／ネイティブコントロールのセマンティクス	ロール、状態、キーボード／アクセシビリティの動作が失われるクリック可能なレイアウト
不変の UI 状態とライフサイクル対応の収集	コンポジション内の副作用や可変なイベント処理
安定した遅延キーとフェーズに適した読み取り	インデックスキーやコンポジション／レイアウトのフィードバックループ
セマンティクステストとレンダリングの検証	スクリーンショットだけに基づくアクセシビリティや状態に関する主張
ウィンドウサイズへの適応	スマートフォン専用のレイアウトをタブレット、折りたたみ式デバイス、デスクトップに引き伸ばすこと