navigationevent

  
Navigation Event ライブラリは、システム バックと予測型「戻る」を処理するための KMP ファースト API を提供します。
最新の更新 安定版リリース リリース候補版 ベータ版リリース アルファ版リリース
2025 年 7 月 30 日 - - - 1.0.0-alpha05

依存関係の宣言

navigationevent への依存関係を追加するには、Google の Maven リポジトリをプロジェクトに追加する必要があります。詳しくは、Google の Maven リポジトリをご覧ください。

アプリまたはモジュールの build.gradle ファイルに、必要なアーティファクトの依存関係を追加します。

Groovy

dependencies {
    implementation "androidx.navigationevent:navigationevent:1.0.0-alpha05"
}

Kotlin

dependencies {
    implementation("androidx.navigationevent:navigationevent:1.0.0-alpha05")
}

依存関係について詳しくは、ビルド依存関係の追加をご覧ください。

フィードバック

お寄せいただいたフィードバックは Jetpack 改善の参考にさせていただきます。新しい問題が見つかった場合や、このライブラリを改善するアイデアをお持ちの場合は、お知らせください。新しい問題を報告していただく前に、このライブラリの既存の問題をご確認ください。スターボタンをクリックすると、既存の問題に投票できます。

新しい問題を報告する

詳細については、Issue Tracker のドキュメントをご覧ください。

このアーティファクトのリリースノートはありません。

バージョン 1.0

バージョン 1.0.0-alpha05

2025 年 7 月 30 日

androidx.navigationevent:navigationevent-*:1.0.0-alpha05 がリリースされました。バージョン 1.0.0-alpha05 には、これらの commit が含まれています。

親子階層のサポート:

NavigationEventDispatcher に親ディスパッチャーと子ディスパッチャーを設定して、階層ツリー構造を形成できるようになりました。これにより、UI の構造階層をチェーンされたディスパッチャーで反映することで、複雑な Compose UI コンポーネント間でナビゲーション イベントをより柔軟に伝播して管理できるようになります。（I194ac）

  // Create a parent dispatcher that will manage navigation events at a higher level.
  val parentDispatcher = NavigationEventDispatcher()

  // Create a child dispatcher linked to the parent, forming a hierarchy.
  val childDispatcher = NavigationEventDispatcher(parentDispatcher)

階層型 isEnabled プロパティを使用すると、ディスパッチャをトップダウンで制御できます。ディスパッチャで isEnabled が false に設定されている場合、そのすべての子孫ディスパッチャが自動的に無効になります。この機能により、ナビゲーション イベント システムのブランチ全体を効率的にオフにできます。（I9e985）

  // Disabling the child dispatcher disables all its callbacks and any of its children recursively.
  childDispatcher.isEnabled = false

また、NavigationEventCallback の isEnabled プロパティは、関連付けられたディスパッチャーの有効状態を尊重するようになりました。つまり、コールバック自体とそのディスパッチャー（その祖先を含む）の両方が有効になっている場合にのみ、コールバックが有効と見なされます。これにより、コールバックの有効化に対する階層的な制御の一貫性が確保されます。（I1799a）

  // Create a test callback and add it to the child dispatcher.
  val callback1 = TestNavigationEventCallback(isEnabled = true)
  childDispatcher.addCallback(callback1)

  // Since the childDispatcher is disabled, the callback is effectively disabled as well.
  assertThat(callback1.isEnabled).isFalse()

ディスパッチャーとその子を適切にクリーンアップするための新しい dispose() メソッドが導入されました。dispose() を呼び出すと、メモリリークを防ぐためにリスナーが停止し、すべての子ディスパッチャーが再帰的に破棄され、ディスパッチャーに登録されているすべてのコールバックが削除され、親とのリンクが解除されます。これにより、ディスパッチャーが不要になったときにリソースが正しく解放されることが保証されます。（I9e985）

  // Dispose the child dispatcher to clean up resources.
  childDispatcher.dispose()

破棄されたディスパッチャーでパブリック メソッドが呼び出されると、IllegalStateException がすぐにスローされます。これにより、サイレント障害を防ぎ、開発中にデベロッパーが不適切な使用を特定できるようになります。（Ic2dc3）

  val callback2 = TestNavigationEventCallback()

  // Attempting to use a disposed dispatcher will throw an exception.
  assertThrows<IllegalStateException> {
      childDispatcher.addCallback(callback2)
  }

注: aosp/3692572 で、Compose UI 内の子ディスパッチャを自動的に管理する新しい NavigationEventDispatcherOwner コンポーザブルを導入します。ただし、この変更は現在のリリース カットには含まれておらず、次のリリース カットで予定されています。

Navigation テスト ライブラリ

  • navigationevent ライブラリ専用のテスト ユーティリティを提供する navigationevent-testing モジュールを追加しました。（0e50b6）
  • テスト用の TestNavigationEventCallback 偽ユーティリティ クラスを追加します。コールバック メソッドの呼び出しを記録し、受け取った NavigationEvent アイテムを保存して検証をサポートします。（4a0246）
  • TestNavigationEvent フェイク ユーティリティ関数を追加して、デフォルト値で NavigationEvent インスタンスを作成し、ナビゲーション イベント処理の単体テストを簡素化します。（3b63f5）
  • テスト用の TestNavigationEventDispatcherOwner 偽ユーティリティ クラスを追加します。フォールバックと有効状態変更イベントの数を追跡し、テストでのインタラクション検証をサポートします。（c8753e）

API の変更

  • NavigationEventInputHandler を androidMain から commonMain に移動して、KMP 共通コードで使用できるようにしました。イベントをディスパッチするための新しい public send* メソッドを追加しました。NavigationEventDispatcher のディスパッチ関数を public から internal に変更しました。ユーザーはイベントを送信する際に NavigationEventInputHandler を使用する必要があります。（Ia7114）
  • NavigationInputHandler を OnBackInvokedInputHandler に変更しました。（I63405）

バグの修正

  • 中間リストの割り当てを回避し、コールバック ディスパッチのパフォーマンスを改善することで、オーバーヘッドを削減するように NavigationEventDispatcher をリファクタリングしました。（I82702、I1a9d9）
  • NavigationEvent の touchX、touchY、progress フィールドに @FloatRange アノテーションを追加して、コンパイル時に有効な値の範囲を適用し、API の安全性を向上させます。（Iac0ec）

バージョン 1.0.0-alpha04

2025 年 7 月 2 日

androidx.navigationevent:navigationevent-*:1.0.0-alpha04 がリリースされました。バージョン 1.0.0-alpha04 にはこれらの commit が含まれています。

バグの修正

  • implementedInJetBrainsFork を navigationevent-compose に使用し、Compose の慣例に合わせるために commonStubs ターゲットを追加しました。JetBrains からリクエストされた変更。（f60c79）
  • Kotlin/Native への Compose コンパイラ プラグインの適用を修正し、スタブが正しく生成されるようにしました。公開 API や動作には影響しません。（1890c9）

バージョン 1.0.0-alpha03

2025 年 6 月 18 日

androidx.navigationevent:navigationevent-*:1.0.0-alpha03 がリリースされました。バージョン 1.0.0-alpha03 にはこれらの commit が含まれています。

新機能

  • navigationevent ライブラリで Jetpack Compose の機能をサポートする新しい navigationevent-compose モジュールを導入しました。（980d78）
  • NavigationEvent Compose に新しい LocalNavigationEventDispatcherOwner ローカル コンポジションが追加されました。現在の合成中に使用可能かどうかを判断しやすくするための null 許容値を返します。NavigationEventHandler は、基になるオーナーが見つからない場合、エラーをスローするようになりました。（62ffda）
  • NavigationEvent Compose に、（予測型「戻る」ジェスチャー）イベントを処理するための新しい NavigationEventHandler コンポーザブルが追加されました。c42ba6 で提供する一時停止ラムダで収集する必要がある NavigationEvent オブジェクトの Flow を提供します。
NavigationEventHandler { progress: Flow<NavigationEvent> ->
  // This block is executed when the back gesture begins.
  try {
    progress.collect { backEvent ->
      // Handle gesture progress updates here.
    }
    // This block is executed if the gesture completes successfully.
  } catch (e: CancellationException) {
    // This block is executed if the gesture is cancelled
    throw e
  } finally {
    // This block is executed either the gesture is completed or cancelled
  }
}

API の変更

  • 各 NavigationEventCallback は一度に 1 つの NavigationEventDispatcher にのみ登録できるようになりました。複数のディスパッチャーに追加すると、IllegalStateException がスローされます。この動作は、複数のディスパッチャを許可する OnBackPressedDispatcher とは異なります。（e82c19）
  • isPassThrough を val にして、ナビゲーション中のミューテーションを防ぎました。これにより、NavigationEvent のディスパッチが中断される可能性があります。（I0b287）

バージョン 1.0.0-alpha02

2025 年 6 月 4 日

androidx.navigationevent:navigationevent-*:1.0.0-alpha02 がリリースされました。バージョン 1.0.0-alpha02 にはこれらの commit が含まれています。

API の変更

  • NavigationEventDispatcher のセカンダリ コンストラクタをデフォルトの引数に置き換えます。（I716a0）
  • NavigationEventCallback から優先度プロパティを削除します。代わりに、優先度を NavigationEventDispatcher.addCallback() に渡します。（I13cae）

バグの修正

  • closeable の内部リストを同時に変更したために NavigationEventCallback.remove() が呼び出された場合に発生する可能性のある ConcurrentModificationException を修正しました。（b/420919815）

バージョン 1.0.0-alpha01

2025 年 5 月 20 日

androidx.navigationevent:navigationevent-*:1.0.0-alpha01 がリリースされました。バージョン 1.0.0-alpha01 にはこれらの commit が含まれています。

新機能

  • androidx.navigationevent ライブラリは、システムバックと予測型「戻る」を処理するための KMP ファースト API を提供します。NavigationEventDispatcher は、システム [戻る] イベントを受け取るために 1 つ以上の NavigationEventCallback インスタンスを登録するための共通 API として機能します。
  • このレイヤは、androidx.activity で以前にリリースされた API の下に位置し、上位レベルのコンポーネントで Activity API を使用したり、Android フレームワークの OnBackInvokedDispatcher API を直接使用したりする際の、より制約の少ない代替手段となることを目指しています。androidx.activity API は、Activity 1.12.0-alpha01 の一部として、Navigation Event API の上に書き直されました。