予測型「戻る」ジェスチャーのサポートを追加する

図 1. スマートフォンでの予測型「戻る」ジェスチャーのデザインを示すモックアップ

予測型「戻る」は、ユーザーが「戻る」スワイプで移動する場所をプレビューできるジェスチャー ナビゲーション機能です。

たとえば図 1 のモックアップに示すように、「戻る」ジェスチャーによって、アプリの背後にあるホーム画面のアニメーション プレビューを表示できます。

Android 15 以降では、予測型「戻る」アニメーションのデベロッパー オプションは利用できなくなります。「ホームに戻る」、タスク間、アクティビティ間などのシステム アニメーションが、予測型「戻る」ジェスチャーを完全に、またはアクティビティ レベルで有効にしているアプリに表示されるようになりました。

このホームに戻るアニメーションをテストできます（このページの次のセクションを参照）。

予測型「戻る」ジェスチャーをサポートするには、下位互換性がある AndroidX Activity 1.6.0 以上の API の OnBackPressedCallback、または新しい OnBackInvokedCallback プラットフォーム API を使用して、アプリを更新する必要があります。ほとんどのアプリでは、下位互換性のある AndroidX API を使用します。

この更新は、「戻る」ナビゲーションを正しくインターセプトするための移行パスを提供するもので、KeyEvent.KEYCODE_BACK からの「戻る」インターセプトや、onBackPressed メソッドを含むクラス（Activity、Dialog など）を、新しいシステムの「戻る」API で置き換えるためのものです。

Codelab と Google I/O の動画

ドキュメントのこのページの内容に加えて、Codelab もお試しください。AndroidX のアクティビティ API を使用して予測型「戻る」ジェスチャーを処理する WebView の一般的なユースケース実装を参照できます。

AndroidX とプラットフォームの API を実装する例については、Google I/O の動画もご覧ください。

Compose でカスタムの「戻る」ジェスチャーを処理する

Compose には、カスタムの戻るジェスチャーを処理するための PredictiveBackHandler コンポーザブルが用意されています。この API を使用すると、戻る操作に応答し、ユーザーがスワイプしたときにカスタム アニメーションやトランジションを実装するために使用できる BackEventCompat オブジェクトの Flow を提供できます。

PredictiveBackHandler を使用するには、アプリに androidx.activity:activity-compose 依存関係（バージョン 1.8.0 以降）が含まれていることを確認します。

// In your build.gradle.kts file:
dependencies {
    implementation("androidx.activity:activity-compose:1.8.0")
}


PredictiveBackHandler(enabled = isBackHandlerEnabled) { progress: Flow<BackEventCompat> ->
    try {
        progress.collect { backEvent ->
            // Update your UI or animation based on backEvent.progress.
        }
        // Handle the final back action (e.g., navigate back).
    } catch (e: CancellationException) {
        // Back gesture was cancelled, reset your UI.
    }
}

進行状況をトラッキングせずに戻るジェスチャーをインターセプトするだけでよい場合は、BackHandler を使用します。

デフォルトの「戻る」ナビゲーションを使用するアプリを更新する

予測型「戻る」はデフォルトで有効になっています。

アプリでフラグメントや Navigation コンポーネントを使用している場合は、AndroidX Activity 1.6.0 以降へのアップグレードも行ってください。

カスタムの「戻る」ナビゲーションを使用するアプリを更新する

アプリにカスタム「戻る」動作が実装されている場合は、AndroidX 使用の有無や「戻る」ナビゲーションの処理方法に応じて移行パスが異なります。

アプリでの「戻る」ナビゲーションの処理方法 おすすめの移行パス（このページのリンク）
AndroidX API AndroidX の既存の「戻る」動作を移行する
サポートされていないプラットフォーム API サポート対象外の「戻る」ナビゲーション API を含む AndroidX アプリを AndroidX API に移行する

AndroidX の「戻る」ナビゲーションの実装を移行する

このユースケースが最も一般的なおすすめの方法です。これは、OnBackPressedDispatcher によってカスタム ジェスチャー ナビゲーションを処理する、新規と既存両方のアプリに当てはまります（適切な「戻る」ナビゲーションを提供するを参照）。

すでに OnBackPressedDispatcher を使用している API（フラグメントや Navigation コンポーネントなど）が、予測型「戻る」ジェスチャーとシームレスに連携するように、AndroidX Activity 1.6.0 以降にアップグレードします。

// In your build.gradle file:
dependencies {
    // Add this in addition to your other dependencies
    implementation "androidx.activity:activity:1.6.0"
}

サポート対象外の「戻る」ナビゲーション API を含む AndroidX アプリを AndroidX API に移行する

アプリで AndroidX ライブラリを使用しながら、サポートされていない「戻る」ナビゲーション API を実装または参照している場合は、AndroidX API に移行して新しい動作をサポートする必要があります。

サポートされていない API を AndroidX API に移行する手順は次のとおりです。

  1. OnBackPressedCallback の実装を使用して、システムの「戻る」ナビゲーション処理ロジックを AndroidX の OnBackPressedDispatcher に移行します。詳細なガイダンスについては、適切な「戻る」ナビゲーションを提供するをご覧ください。

  2. 「戻る」ジェスチャーのインターセプトを停止する準備ができたら、OnBackPressedCallback を無効にします。

  3. OnBackPressed または KeyEvent.KEYCODE_BACK を使用した「戻る」イベントのインターセプトを停止します。

  4. 必ず AndroidX Activity 1.6.0 以降にアップグレードしてください。

    // In your build.gradle file:
dependencies {
    // Add this in addition to your other dependencies
    implementation "androidx.activity:activity:1.6.0"
}

予測型「戻る」をオプトアウトする

オプトアウトするには、AndroidManifest.xml の <application> タグ内で、android:enableOnBackInvokedCallback フラグを false に設定します。

<application
    ...
    android:enableOnBackInvokedCallback="false"
    ... >
...
</application>

これを false に設定すると、次のようになります。

  • 予測型「戻る」ジェスチャーのシステム アニメーションが無効になります。
  • OnBackInvokedCallback は無視されますが、OnBackPressedCallback 呼び出しは引き続き機能します。

アクティビティ レベルでオプトアウトする

android:enableOnBackInvokedCallback フラグを使用すると、アクティビティ レベルで予測型システム アニメーションを無効にできます。この動作により、大規模なマルチアクティビティ アプリを予測型「戻る」ジェスチャーに移行しやすくなります。

次のコードは、enableOnBackInvokedCallback を設定して MainActivity からホームに戻るシステム アニメーションを有効にする例を示しています。

<manifest ...>
    <application . . .

        android:enableOnBackInvokedCallback="false">

        <activity
            android:name=".MainActivity"
            android:enableOnBackInvokedCallback="true"
            ...
        </activity>
        <activity
            android:name=".SecondActivity"
            android:enableOnBackInvokedCallback="false"
            ...
        </activity>
    </application>
</manifest>

android:enableOnBackInvokedCallback フラグを使用する場合は、次の点にご注意ください。

  • android:enableOnBackInvokedCallback=false と設定すると、タグを設定した場所に応じて、アクティビティ レベルまたはアプリレベルで予測型「戻る」アニメーションがオフになります。また、システムに対して、OnBackInvokedCallback プラットフォーム API の呼び出しを無視するよう指示します。ただし、OnBackPressedCallback には下位互換性があり、Android 13 より前でサポートされていない onBackPressed API が呼び出されるため、OnBackPressedCallback の呼び出しは引き続き実行されます。
  • アプリレベルで enableOnBackInvokedCallback フラグを設定すると、アプリ内のすべてのアクティビティのデフォルト値が設定されます。アクティビティごとにデフォルトをオーバーライドするには、上記のコード例に示すように、アクティビティ レベルでフラグを設定します。

コールバックのガイドライン

サポートされているシステムの「戻る」コールバック（PredictiveBackHandler または BackHandler（Compose の場合）、OnBackPressedCallback、OnBackInvokedCallback）を使用する際は、次のガイドラインに沿ってください。

各コールバックを有効または無効にする UI 状態を特定する

UI 状態は、UI を表すプロパティです。この手順の概要に沿って行うことをおすすめします。

  1. 各コールバックを有効または無効にする UI 状態を特定します。

  2. 観測可能なデータホルダーの型（StateFlow や Compose の状態など）を使用してその状態を定義し、状態が変化したときにコールバックを有効または無効にします。

アプリで以前に「戻る」ロジックを条件ステートメントと関連付けていた場合、「戻る」イベントがすでに発生した後で対応している可能性があります。新しいコールバックではこのパターンを避けてください。可能であれば、コールバックを条件ステートメントの外側に移動して、代わりにコールバックを観測可能なデータホルダーの型に関連付けます。

UI ロジックにシステムの「戻る」コールバックを使用する

UI ロジックは、UI の表示方法を決定します。システムの「戻る」コールバックを使用して、ダイアログの表示やアニメーションの実行などの UI ロジックを実行します。

アプリが PRIORITY_DEFAULT または PRIORITY_OVERLAY を伴う OnBackPressedCallback または OnBackInvokedCallback を有効にしている場合、予測型「戻る」アニメーションは実行されず、「戻る」イベントを処理する必要があります。ビジネス ロジックの実行やロギングのためにこれらのコールバックを作成しないでください。

ユーザーがスワイプして戻ったときにアプリでビジネス ロジックを実行したり、ログを記録したりする必要がある場合は、次のアプローチを使用します。

  • Compose の場合: Compose のデスティネーションに関連付けられた ViewModel の onCleared() コールバック内でログに記録します。これは、Compose のデスティネーションがバックスタックからポップされて破棄されたことを知るための最適なシグナルです。
  • Android 16 以降の場合: PRIORITY_SYSTEM_NAVIGATION_OBSERVER で OnBackInvokedCallback を使用します。これにより、戻るイベントを使用しないオブザーバー コールバックが作成されます。たとえば、ユーザーがルート アクティビティから戻る（アプリを離れる）ときにこのコールバックを登録して、戻るイベントをログに記録したり、ビジネス ロジックを実行したりしながら、ホームに戻るアニメーションを再生できます。
  • ビューベースのアプリの場合: バック イベントを使用するのではなく、ライフサイクルまたはバックスタックのコールバック内でログを記録します。
    • アクティビティの切り替えについては、isFinishing が Activity.onDestroy() 内の true であるかどうかを確認します。
    • フラグメントのトランジションについては、フラグメントのビュー ライフサイクル onDestroy() 内で isRemoving が true かどうかを確認するか、FragmentManager.OnBackStackChangedListener（onBackStackChangeStarted / onBackStackChangeCommitted）を使用します。

役割が 1 つのみのコールバックを作成する

ディスパッチャに複数のコールバックを追加できます。コールバックはスタックに追加され、最後に追加された有効なコールバックが、「戻る」操作ごとに 1 つのコールバックで次の「戻る」操作を処理します。

コールバックに単一の責任がある場合、コールバックの有効状態を管理しやすくなります。次に例を示します。

Compose のスタック内のコールバックの順序。
図 2. Compose のコールバック スタック図。

図 2 は、スタックに複数のコールバックがあり、それぞれが 1 つの処理を担当している様子を示しています。Compose では、コールバックは最も内側のコンポーザブルから最も外側のコンポーザブルへと評価され、コールバックはスタック内の前のコールバックが無効になっている場合にのみ実行されます。

  • 「よろしいですか？」PredictiveBackHandler は、ユーザーがフォームにデータを入力すると有効になり、それ以外の場合は無効になります。有効にすると、戻る操作をインターセプトして、確認ダイアログまたはカスタムのアプリ内アニメーションを表示します。
  • 前のコールバックが無効になっている場合、画面レベルの BackHandler が実行されます。この例では無効になっています。
  • NavHost コールバックは、前のカスタム コールバックが無効になっている場合に、「戻る」ナビゲーションを処理してバックスタックからデスティネーションをポップします。
  • 最後に、前のコールバックがすべて無効になっている場合、システムは「戻る」ジェスチャーを処理します。バックスタックがルートの宛先にある場合、システムは「ホームに戻る」、アクティビティ間、タスク間などのシステムレベルのアニメーションをトリガーします。

View ベースのアプリでも同じスタック動作が適用されます。最後に追加された有効な OnBackPressedCallback が優先され、FragmentManager にフォールバックし、最終的にはシステムの「戻る」処理にフォールバックします。

予測型「戻る」ジェスチャーのアニメーションをテストする

Android 15 以降では、予測型「戻る」ナビゲーションをサポートするアプリで、ホームに戻る、タスク間、アクティビティ間などのシステム アニメーションがデフォルトで有効になります。デベロッパー オプションの背後に隠れていません。

Android 13 または Android 14 を搭載したデバイスでは、開発者向けオプションを有効にして、図 1 のようなホームに戻るアニメーションをテストできます。

  1. デバイスで、[設定] > [システム] > [開発者向けオプション] に移動します。

  2. [予測型「戻る」アニメーション] を選択します。

  3. 更新したアプリを起動し、「戻る」ジェスチャーを使用して実際の動作を確認します。