navigationevent

  
Thư viện Navigation Event cung cấp một API ưu tiên KMP để xử lý thao tác quay lại hệ thống cũng như tính năng Xem trước thao tác quay lại.
Bản cập nhật mới nhất Bản phát hành ổn định Bản phát hành dùng thử Bản phát hành beta Bản phát hành alpha
Ngày 24 tháng 9 năm 2025 - - - 1.0.0-alpha09

Khai báo phần phụ thuộc

Để thêm một phần phụ thuộc vào navigationevent, bạn phải thêm kho lưu trữ Google Maven vào dự án. Đọc nội dung Kho lưu trữ Maven của Google để biết thêm thông tin.

Thêm các phần phụ thuộc cho cấu phần phần mềm bạn cần trong tệp build.gradle cho ứng dụng hoặc mô-đun:

Groovy

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

Kotlin

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

Để biết thêm thông tin về các phần phụ thuộc, hãy xem bài viết Thêm phần phụ thuộc vào bản dựng.

Ý kiến phản hồi

Ý kiến phản hồi của bạn có thể giúp chúng tôi cải thiện Jetpack. Hãy cho chúng tôi biết nếu bạn phát hiện lỗi mới hoặc có ý tưởng cải thiện thư viện này. Vui lòng xem các lỗi hiện có trong thư viện này trước khi báo một lỗi mới. Bạn có thể thêm lượt bình chọn cho lỗi hiện có bằng cách nhấp vào nút dấu sao.

Báo lỗi mới

Xem tài liệu về Công cụ theo dõi lỗi để biết thêm thông tin.

Không có ghi chú phát hành cho cấu phần phần mềm này.

Phiên bản 1.0

Phiên bản 1.0.0-alpha09

Ngày 24 tháng 9 năm 2025

Phát hành androidx.navigationevent:navigationevent-*:1.0.0-alpha09. Phiên bản 1.0.0-alpha09 bao gồm các thay đổi sau.

Thay đổi về API

  • Sử dụng trực tiếp đối tượng singleton NavigationEventTransitionState.Idle thay vì khởi tạo Idle(). (Ic7d9e, b/444734264)
  • Đặt hàm khởi tạo tiện lợi ở chế độ nội bộ; lấy các thực thể thông qua NavigationEventDispatcher.history công khai thay vì tạo trực tiếp. (I3b7e0, b/444734264)
  • Yêu cầu tạo NavigationEventState thông qua rememberNavigationEventState; hàm khởi tạo hiện là nội bộ. (Ie143c, b/444734264)
  • Áp dụng onBackCompletedFallback thay thế các cách dùng fallbackOnBackPressed và tham số hàm khởi tạo. Hành vi không thay đổi; chỉ được gọi khi các sự kiện quay lại đã hoàn tất và chưa được xử lý. (Idabe9, b/444734264)
  • Hàm khởi tạo chính của NavigationEventHistory(mergedHistory, currentIndex) hiện là internal. Người dùng bên ngoài phải sử dụng các hàm khởi tạo công khai (hàm khởi tạo trống hoặc hàm khởi tạo dựa trên phân vùng) để tạo các thực thể. (I1c047, b/444734264)
  • Cho phép View.setViewTreeNavigationEventDispatcherOwner chấp nhận đối tượng sở hữu có giá trị rỗng (Ic9eb6, b/444436762)
  • NavigationEventInfo hiện là abstract class thay vì interface. Cập nhật tất cả các triển khai tuỳ chỉnh để kế thừa từ lớp (ví dụ: data class MyInfo : NavigationEventInfo()). (I1e59c, b/444734264)
  • Thuộc tính NavigationEventDispatcher.state và hàm getState<T>() cũ đã bị xoá. Sử dụng các luồng dispatcher.transitionState (để xem tiến trình cử chỉ) và dispatcher.history (để xem ngăn xếp điều hướng) mới, riêng biệt. (Ic2ceb, b/444734264)
  • Lệnh gọi lại NavigationEventInput.onInfoChanged(...) sẽ được thay thế. Triển khai lệnh gọi lại onHistoryChanged(history: NavigationEventHistory) mới để nhận nội dung cập nhật dưới dạng một đối tượng NavigationEventHistory duy nhất. (I23e0b, b/444734264)
  • Giới thiệu NavigationEventDispatcher.history StateFlow mới trên toàn cầu. Luồng không chung chung này cho phép các đối tượng theo dõi chỉ đăng ký nhận thông báo về những thay đổi đối với ngăn xếp điều hướng và vẫn ổn định trong quá trình thực hiện cử chỉ. Đây là đối tượng tương ứng với transitionState. (I1db10, b/444734264)
  • Giới thiệu NavigationEventDispatcher.transitionState StateFlow mới trên toàn cầu. Luồng không chung chung này cho phép các đối tượng theo dõi chỉ đăng ký trạng thái cử chỉ thực (Idle/InProgress), tách biệt với nhật ký. (I171fa, b/444734264)
  • Giới thiệu lớp NavigationEventHistoryState. Đây sẽ là API cốt lõi để theo dõi nhật ký thông tin điều hướng, tách biệt với trạng thái cử chỉ. (I81ca5, b/444734264)
  • NavigationEvent hiện được đánh dấu là @Immutable, cho phép Trình biên dịch Compose tối ưu hoá các thành phần kết hợp lại. (If78c7, b/444734264)
  • Các API trình xử lý navigationevent-compose được cập nhật. NavigationEventHandler và NavigationBackHandler (cùng các biến thể) hiện hỗ trợ một phương thức nạp chồng mới chấp nhận NavigationEventState được nâng lên. Các phương thức nạp chồng đơn giản (lấy currentInfo) được giữ lại và hiện sử dụng mô hình trạng thái mới này ở bên trong. (Ic3251, b/444734264)
  • Thêm trình giữ trạng thái @Stable NavigationEventState<T> mới vào thư viện navigationevent-compose. Đối tượng này kết hợp nhật ký cục bộ với trạng thái cử chỉ cục bộ và sẽ là mối liên kết chính giữa rememberNavigationEventState và NavigationEventHandler. (Ifb69f, b/444734264)
  • Thêm một thuộc tính transitionState: TransitionState chỉ đọc, công khai mới vào NavigationEventHandler. Giờ đây, các trình xử lý sẽ duy trì trạng thái chuyển đổi riêng mà các hệ thống bên ngoài có thể quan sát. (I9acd2, b/444734264)
  • Giới thiệu lớp TransitionState mới được niêm phong. Đây sẽ là API cốt lõi để theo dõi trạng thái cử chỉ, tách biệt với nhật ký điều hướng. (Id4beb, b/444734264)
  • Hiển thị currentInfo, backInfo và forwardInfo dưới dạng các thuộc tính công khai, chỉ có thể đọc trên NavigationEventHandler. (Ia7636, b/444734264)
  • Giờ đây, các hoạt động triển khai NavigationEventHandler phải cung cấp giá trị initialInfo: T cho hàm khởi tạo cơ sở. (Idcfea, b/444734264)
  • Thay thế OnBackInvokedInput bằng OnBackInvokedOverlayInput hoặc OnBackInvokedDefaultInput. (I5323f, b/428948766)
  • Đánh dấu NavigationEventState là @Immutable. Điều này giúp cải thiện hiệu suất của Compose bằng cách đảm bảo các thành phần kết hợp quan sát trạng thái này có thể bỏ qua quá trình kết hợp lại một cách chính xác. (I399c8)
  • Đổi tên NavigationEventInfo.NotProvided thành NavigationEventInfo.None; và cập nhật các tham chiếu. Cách thức hoạt động sẽ không thay đổi. (I5e2d4)
  • NavigationEventInfo hiện được đánh dấu là @Immutable, cho phép Trình biên dịch Compose tối ưu hoá các thành phần kết hợp lại. (I7c112)
  • Cải thiện khả năng tương tác của Java bằng giao diện thú vị cho tính năng dự phòng hoàn tất thao tác quay lại. (I8a860)
  • Đổi tên onHasEnabledHandlerChanged thành onHasEnabledHandlersChanged. Điều này làm rõ rằng lệnh gọi lại báo cáo về trạng thái kích hoạt chung của tất cả các trình xử lý, chứ không chỉ một trình xử lý. (I1af61, b/443711297)
  • Xoá hasEnabledHandler() khỏi NavigationEventDispatcher;, thay vào đó hãy dùng NavigationEventInput.onHasEnabledHandlersChanged. (Idef72, b/443711297)
  • Thêm lệnh gọi lại onInfoChanged vào NavigationEventInput để thông báo cho các trình nghe về những thay đổi đối với nhật ký điều hướng. Điều này cung cấp ngữ cảnh đầy đủ của ngăn xếp hiện tại, ngăn xếp lui và ngăn xếp tiến, cho phép các Input phản ứng với thông tin theo bối cảnh. (I69a8b, b/443282983)
  • Biến NavigationEvent thành swipeEdge @IntDef (Icee54, b/443950342)
  • Thêm tham số priority vào NavigationEventDispatcher.addInput để giới hạn một trình điều phối ở một mức độ ưu tiên; các sự kiện như onHasEnabledCallbacksChanged hiện chỉ kích hoạt khi các lệnh gọi lại ở mức độ ưu tiên đó thay đổi. (I3e488, b/443711297)
  • Đổi tên tham số NavigationEventDispatcher từ parentDispatcher thành parent để rõ ràng hơn. (Id4f1f, b/443801782)
  • Xoá NavigationEventPriority để chuyển sang dùng @IntDef cho người dùng Java (I10a9f, b/440514265)
  • Thực thi hợp đồng trình xử lý hoạt động điều hướng. Nếu NavigationEventHandler đặt isBackEnabled hoặc isForwardEnabled thành true, thì giờ đây, bạn phải ghi đè onBackCompleted hoặc onForwardCompleted tương ứng. Giờ đây, các hoạt động triển khai mặc định sẽ ném một ngoại lệ để ngăn chặn lỗi âm thầm. (I17c62)
  • Thực thi các giá trị ưu tiên hợp lệ khi thêm trình xử lý sự kiện điều hướng. Giờ đây, việc gọi addHandler với mức độ ưu tiên không được hỗ trợ sẽ gửi IllegalArgumentException, cung cấp thông tin phản hồi ngay lập tức về việc sử dụng không chính xác trên tất cả các nền tảng mục tiêu. (I3c474)

Sửa lỗi

  • Tạo addHandler có tính chất luỹ đẳng; bỏ qua các lượt đăng ký trùng lặp. (I052aa, b/444734264)
  • Đồng bộ hoá các thuộc tính NavigationEventState trong quá trình kết hợp lại. (Ib3b4d, b/444734264)
  • Đảm bảo NavigationEventInputs nhận được thông tin theo bối cảnh hiện tại (hiện tại, quay lại, chuyển tiếp) ngay khi đăng ký. (Ie65bf, b/443282983)

Phiên bản 1.0.0-alpha08

Ngày 10 tháng 9 năm 2025

Phát hành androidx.navigationevent:navigationevent-*:1.0.0-alpha08. Phiên bản 1.0.0-alpha08 bao gồm các thay đổi sau.

Tính năng mới

  • Giới thiệu API NavigationEventHandler dựa trên lambda để thay thế trình xử lý dựa trên Flow. Xử lý cử chỉ quay lại và tiến bằng các lệnh gọi lại đơn giản thay vì thu thập các luồng, giảm mã nguyên mẫu và tránh các vấn đề về việc huỷ. Cung cấp NavigationBackHandler và NavigationForwardHandler dưới dạng các API tiện lợi được nhắm đến. Xoá NavigationEventHandler dựa trên Flow; di chuyển sang các lệnh gọi lại mới. (I23bac, b/436248277)
  • Cho phép người nghe thụ động truy cập vào toàn bộ ngăn xếp điều hướng trước đó thông qua thông tin kết hợp về thao tác quay lại. Cho phép giao diện người dùng kết xuất bản xem trước và nhật ký điều hướng lồng nhau thay vì chỉ giới hạn ở lệnh gọi lại trên cùng. (I7a510, b/436248277)
  • Giới thiệu một mô hình rõ ràng về trạng thái quay lại/hiện tại/tiến để làm rõ trạng thái điều hướng và hỗ trợ điều hướng tiến bằng các trình xử lý lồng nhau. (Ib86da, b/420443609)
  • Thêm các phương thức onForward* và isForwardEnabled vào NavigationEventCallback. (Ic100f, b/436248290)
  • Thêm tính năng hỗ trợ điều hướng tiến vào NavigationEventInput. (I5734b)

Thay đổi về API

  • Cho phép kiểm thử các sự kiện điều hướng tiến với TestNavigationEventCallback. Sử dụng các hook isForwardEnabled và onForward*. (I21fb5, b/420443609)
  • Đổi tên các lệnh gọi lại onEvent* thành onBack* trong NavEvent. (I228b3, b/436248290)
  • Chuyển đổi SwipeEdge thành một lớp cùng dòng. (Id5e01)
  • Giúp thư viện navigationevent tương tác được với Java. Giờ đây, bạn có thể truy cập hoàn toàn vào tất cả các API công khai từ mã Java, cho phép tích hợp liền mạch vào các dự án có nhiều ngôn ngữ hoặc chỉ có Java. (Ibc944,I5465f, I9fb1e, b/440532890b/443040294)
  • Làm rõ các vai trò của API bằng cách đổi tên NavigationEventCallback thành NavigationEventHandler. Thay đổi này phản ánh rõ hơn mục đích của lớp là xử lý các cử chỉ điều hướng nhiều giai đoạn. Phương thức addCallback tương ứng hiện là addHandler. (I2492a, b/443040331)

Sửa lỗi

  • Ngăn tính năng dự phòng quay lại chạy trên thao tác điều hướng tiến. (I74814, b/436248290)
  • Thêm tính năng hỗ trợ cho chế độ xem trước thao tác điều hướng tiến. Giờ đây, các API NavigationEvent xử lý cả thao tác quay lại và tiến, cho phép tạo ảnh động nhất quán cho cả hai hướng điều hướng. (Idc98c, b/436248290)
  • Ngăn sự cố IllegalStateException trong quá trình kết hợp lại khi một NavigationEventDispatcherOwner con bị xoá. (Iff50c, b/412629020)
  • Giờ đây, người nghe thụ động có thể truy cập vào toàn bộ ngăn xếp điều hướng trước đó thông qua thông tin kết hợp về thao tác quay lại, cho phép giao diện người dùng hiển thị bản xem trước và nhật ký điều hướng lồng nhau thay vì chỉ giới hạn ở lệnh gọi lại trên cùng. (I7a510, b/436248277)

Phiên bản 1.0.0-alpha07

Ngày 27 tháng 8 năm 2025

Phát hành androidx.navigationevent:navigationevent-*:1.0.0-alpha07. Phiên bản 1.0.0-alpha07 bao gồm các thay đổi sau.

Thay đổi về API

  • Xoá NavigationEventDispatcher.onHasEnabledCallbacksChanged. (I50e97)
  • Tạo NavigationEventCallback.onEventCompleted() trừu tượng. (I36b38)
  • Thay đổi phương thức NavigationEventCallback#on* thành protected. Cập nhật mã quốc gia để ghi đè các mã này. (I6b691)
  • Đổi tên các hàm DirectNavigationEventInput. (Iffb62)
  • Đổi tên NavigationEventInput.onAttach thành onAdded. (I2d0b8)
  • Đổi tên NavigationEventInput.onDetach thành onRemoved. (I2d0b8)
  • Đổi tên NavigationEventInputHandler thành NavigationEventInput. (I676a4)
  • Thêm @EmptySuper vào NavigationEventInput.onHasEnabledCallbacksChanged. (If9853)
  • Triển khai onAttach trong NavigationEventInputHandler. (I03648)
  • Triển khai onDetach trong NavigationEventInputHandler. (I03648)
  • NavigationEventCallback mặc định được bật khi tạo. (Ic0188)
  • Thay thế NavigationEventInput.addOnHasEnabledCallbacksChangedCallback với NavigationEventInput.onHasEnabledCallbacksChanged. (I64e93)
  • Yêu cầu luồng chính cho NavigationEventDispatcher.addInput. (Ic2930)
  • Yêu cầu luồng chính cho NavigationEventDispatcher.removeInput. (Ic2930)
  • Xoá Dispatcher.addOnHasEnabledCallbacksChangedCallback. Thay thế bằng Dispatcher.onHasEnabledCallbacksChanged. (Ida3e3, b/436530096)

Sửa lỗi

  • Khắc phục lỗi khi thêm một trình xử lý đã được đính kèm hoặc xoá một trình xử lý chưa được đính kèm sẽ kích hoạt logic vòng đời không chính xác. (I9e47b)

Phiên bản 1.0.0-alpha06

Ngày 13 tháng 8 năm 2025

Phát hành androidx.navigationevent:navigationevent-*:1.0.0-alpha06. Phiên bản 1.0.0-alpha06 bao gồm các thay đổi sau.

Tính năng mới

Passive Listeners API

Giờ đây, bạn có thể truyền thông tin theo bối cảnh tuỳ chỉnh từ mọi thành phần lưu trữ điều hướng và thụ động theo dõi các thay đổi về trạng thái cử chỉ ở mọi nơi trong giao diện người dùng. Điều này cho phép sử dụng ảnh động theo ngữ cảnh cho tính năng xem trước thao tác quay lại và các thao tác điều hướng khác bằng cử chỉ.

Tính năng này có 2 phần:

  1. Cung cấp thông tin – Sử dụng NavigationEventInfo để truyền dữ liệu tuỳ chỉnh.
  2. Sử dụng trạng thái – Sử dụng dispatcher.state (NavigationEventState) để quan sát tiến trình và bối cảnh của cử chỉ.
  • NavigationEventCallback hiện cung cấp phương thức setInfo(currentInfo, previousInfo) để đặt ngữ cảnh cử chỉ trong một lệnh gọi (I1d5e7, b/424470518).
  • NavigationEventHandler thêm một phương thức nạp chồng mới chấp nhận currentInfo và previousInfo, biến phương thức này thành API chính để cung cấp ngữ cảnh trong các ứng dụng Compose (I6ecd3, b/424470518).

Ví dụ:

  data class MyScreenInfo(val screenName: String) : NavigationEventInfo

  NavigationEventHandler(
      enabled = true,
      currentInfo = MyScreenInfo("Details Screen"),
      previousInfo = MyScreenInfo("Home Screen")
  ) { /* Handle back completion */ }
  • NavigationEventDispatcher hiện hiển thị dispatcher.state và dispatcher.getState<T>() (If7fae, Ia90ca, b/424470518). Các API dựa trên StateFlow này cho phép mọi giao diện người dùng quan sát tiến trình cử chỉ và dữ liệu theo bối cảnh mà không cần xử lý trực tiếp sự kiện.

Ví dụ:

  val gestureState by LocalNavigationEventDispatcherOwner.current!!
      .navigationEventDispatcher
      .state
      .collectAsState()

  val progress = gestureState.progress // Returns latestEvent.progress or 0F

  when (val state = gestureState) {
      is InProgress -> {
          val toScreen = state.currentInfo as MyScreenInfo
          val fromScreen = state.previousInfo as MyScreenInfo
          println("Navigating from ${fromScreen.screenName} to ${toScreen.screenName}")
      }
      is Idle -> { /* Idle state */ }
  }

  • Thêm thuộc tính progress vào NavigationEventState (I7b196) trả về latestEvent.progress khi đang diễn ra hoặc 0F trong trường hợp khác:

    val progress = state.progress

  • Thêm thành phần kết hợp NavigationEventDispatcherOwner để tạo, liên kết và loại bỏ các thực thể NavigationEventDispatcher theo hệ phân cấp. Bật chế độ kiểm soát động đối với trạng thái đã bật của trình điều phối và tính năng dọn dẹp tự động.

    @Composable
fun Sample() {
    NavigationEventDispatcherOwner(enabled = true) {
        val localDispatcherOwner = LocalNavigationEventDispatcherOwner.current
    }
}

Thay đổi về API

  • Tham số isPassthrough đã bị xoá khỏi NavigationEventCallback. (I99028, b/424470518)
  • Hàm khởi tạo NavigationEventState hiện là nội bộ. Để kiểm thử, hãy cập nhật trạng thái (mặc định là Idle) thông qua DirectNavigationEventInputHandler. Gọi handleOnStarted hoặc handleOnProgressed để đặt trạng thái thành InProgress và handleOnCompleted hoặc handleOnCancelled để trả về Idle. Để cập nhật NavigationEventInfo, hãy sử dụng NavigationEventCallback.setInfo. (I93dca, b/424470518)
  • Thêm các tham số mặc định vào NavigationEvent để cho phép khởi tạo dễ dàng hơn và đơn giản hoá việc kiểm thử. Bạn nên sử dụng tham số này thay cho TestNavigationEvent. (I5dc49, I232f4)
  • Đã thêm một TestNavigationEventCallback để kiểm thử các sự kiện điều hướng với trạng thái hiện tại/trước đó cụ thể. (Idd22e, b/424470518)
  • NavigationEventInputHandler đã được chuyển thành một lớp trừu tượng để thay thế AbstractNavigationEventInputHandler trước đó bằng một phương thức triển khai trong DirectNavigationEventInputHandler (Iadde5, Ifed40I3897c, b/432616296, b/435416924)
  • Các hàm send* trong NavigationEventInputHandler đã đổi tên tiền tố thành handle*. (Iffcaf)
  • OnBackInvokedInputHandler hiện mở rộng abstract NavigationInputHandler mới. (Ib45aa)
  • Thay đổi NavigationEventDispatcherOwner để yêu cầu một trình điều phối chính, trong đó bạn phải truyền null một cách rõ ràng để tạo trình điều phối gốc. (Ia6f64, b/431534103)

Sửa lỗi

  • Cải thiện hiệu suất bằng cách tránh sao chép tập hợp trong NavigationEventDispatcher.dispose(). (I4ab09)
  • Khắc phục vấn đề khiến NavigationEventHandler không phản hồi chính xác các thay đổi về trạng thái đã bật. (Ia5268,I19bec, I5be5c, b/431534103)

Nội dung cập nhật về Tài liệu

  • KDocs cho NavigationEvent được mở rộng để làm rõ vai trò của lớp này là một trình bao bọc sự kiện hợp nhất và hành vi thuộc tính chi tiết trên nhiều loại thao tác điều hướng (cử chỉ, lượt nhấp). (I91e8d)
  • Cập nhật tài liệu cho các API Compose xử lý thao tác quay lại hệ thống (BackHandler, PredictiveBackHandler, NavigationEventHandler) để nêu rõ hành vi, đặc biệt là về thứ tự gọi lại. (I7ab94, )

Cập nhật về phần phụ thuộc

  • NavigationEvent hiện phụ thuộc vào Compose Runtime 1.9.0-beta03, cho phép cấu phần phần mềm navigationevent-compose hỗ trợ tất cả các mục tiêu KMP. (Ia1b87)

Phiên bản 1.0.0-alpha05

Ngày 30 tháng 7 năm 2025

Phát hành androidx.navigationevent:navigationevent-*:1.0.0-alpha05. Phiên bản 1.0.0-alpha05 bao gồm các thay đổi sau.

Hỗ trợ hệ phân cấp Mẹ – Con:

Giờ đây, NavigationEventDispatcher có thể có các trình điều phối gốc và con, tạo thành một cấu trúc cây phân cấp. Điều này cho phép các sự kiện điều hướng lan truyền và được quản lý linh hoạt hơn trên các thành phần giao diện người dùng Compose phức tạp bằng cách phản ánh hệ thống phân cấp cấu trúc của giao diện người dùng thông qua các trình điều phối được liên kết. (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)

Thuộc tính phân cấp isEnabled cho phép kiểm soát từ trên xuống của một trình điều phối. Khi isEnabled được đặt thành false trên một bộ điều phối, nó sẽ tự động vô hiệu hoá tất cả các bộ điều phối cấp dưới. Tính năng này cho phép tắt toàn bộ các nhánh của hệ thống sự kiện điều hướng một cách hiệu quả. (I9e985)

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

Ngoài ra, thuộc tính isEnabled trên NavigationEventCallback hiện tuân theo trạng thái đã bật của trình điều phối được liên kết. Điều này có nghĩa là một lệnh gọi lại chỉ được coi là đã bật nếu cả lệnh gọi lại đó và trình điều phối của lệnh gọi lại (bao gồm cả các lệnh gọi lại cấp trên) đều được bật, đảm bảo khả năng kiểm soát nhất quán theo hệ phân cấp đối với việc kích hoạt lệnh gọi lại. (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()

Một phương thức dispose() mới đã được ra mắt để dọn dẹp đúng cách các dispatcher và dispatcher con. Việc gọi dispose() sẽ dừng các trình nghe để ngăn tình trạng rò rỉ bộ nhớ, đệ quy loại bỏ tất cả trình điều phối con, xoá tất cả lệnh gọi lại đã đăng ký với trình điều phối và huỷ liên kết trình điều phối đó với trình điều phối mẹ. Điều này đảm bảo các tài nguyên được giải phóng đúng cách khi không còn cần đến các trình điều phối. (I9e985)

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

Nếu có phương thức công khai nào được gọi trên một trình điều phối đã bị loại bỏ, thì IllegalStateException sẽ được truyền ngay lập tức. Điều này giúp ngăn chặn các lỗi âm thầm và giúp nhà phát triển xác định việc sử dụng không đúng cách trong quá trình phát triển. (Ic2dc3)

  val callback2 = TestNavigationEventCallback()

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

Lưu ý: Chúng tôi sẽ giới thiệu một thành phần kết hợp NavigationEventDispatcherOwner mới, tự động quản lý một trình điều phối con trong giao diện người dùng Compose trong aosp/3692572. Tuy nhiên, thay đổi này không có trong bản phát hành hiện tại và dự kiến sẽ có trong bản phát hành tiếp theo.

Thư viện kiểm thử điều hướng

  • Thêm mô-đun navigationevent-testing để cung cấp các tiện ích kiểm thử chuyên dụng cho thư viện navigationevent. (0e50b6)
  • Thêm lớp tiện ích giả TestNavigationEventCallback để kiểm thử. Nó ghi lại các lệnh gọi phương thức gọi lại và lưu trữ các mục NavigationEvent đã nhận được để hỗ trợ quy trình xác minh. (4a0246)
  • Thêm hàm tiện ích giả TestNavigationEvent để tạo các thực thể NavigationEvent có giá trị mặc định, đơn giản hoá các kiểm thử đơn vị để xử lý sự kiện điều hướng. (3b63f5)
  • Thêm lớp tiện ích giả TestNavigationEventDispatcherOwner để kiểm thử. Thao tác này theo dõi số lượng sự kiện dự phòng và sự kiện thay đổi trạng thái đã bật để hỗ trợ xác minh tương tác trong các thử nghiệm. (c8753e)

Thay đổi về API

  • Di chuyển NavigationEventInputHandler từ androidMain sang commonMain để cung cấp trong mã chung KMP. Thêm các phương thức public send* mới để gửi sự kiện. Thay đổi các hàm điều phối trên NavigationEventDispatcher từ public thành internal; giờ đây, người dùng phải sử dụng NavigationEventInputHandler để gửi sự kiện. (Ia7114)
  • Đổi tên NavigationInputHandler thành OnBackInvokedInputHandler. (I63405)

Sửa lỗi

  • Tái cấu trúc NavigationEventDispatcher để giảm mức hao tổn bằng cách tránh phân bổ danh sách trung gian và cải thiện hiệu suất gửi lệnh gọi lại. (I82702, I1a9d9)
  • Thêm chú giải @FloatRange vào các trường touchX, touchY và progress trong NavigationEvent để thực thi các dải giá trị hợp lệ tại thời gian biên dịch và cải thiện độ an toàn của API. (Iac0ec)

Phiên bản 1.0.0-alpha04

Ngày 2 tháng 7 năm 2025

Phát hành androidx.navigationevent:navigationevent-*:1.0.0-alpha04. Phiên bản 1.0.0-alpha04 bao gồm các thay đổi sau.

Sửa lỗi

  • Đã dùng implementedInJetBrainsFork để navigationevent-compose và thêm mục tiêu commonStubs để phù hợp với các quy ước của Compose. Thay đổi do JetBrains yêu cầu. (f60c79)
  • Đã khắc phục việc áp dụng trình bổ trợ trình biên dịch Compose cho Kotlin/Native để đảm bảo tạo đúng phần giữ chỗ. Không ảnh hưởng đến các API công khai hoặc hành vi. (1890c9)

Phiên bản 1.0.0-alpha03

Ngày 18 tháng 6 năm 2025

Phát hành androidx.navigationevent:navigationevent-*:1.0.0-alpha03. Phiên bản 1.0.0-alpha03 bao gồm các thay đổi sau.

Tính năng mới

  • Giới thiệu một mô-đun navigationevent-compose mới để hỗ trợ các tính năng của Jetpack Compose trong thư viện navigationevent. (980d78)
  • NavigationEvent Compose đã thêm một thành phần kết hợp cục bộ LocalNavigationEventDispatcherOwner mới. Hàm này trả về một giá trị rỗng để xác định rõ hơn liệu giá trị đó có trong thành phần hiện tại hay không. NavigationEventHandler hiện sẽ hiển thị lỗi nếu không tìm thấy chủ sở hữu cơ sở. (62ffda)
  • NavigationEvent Compose đã thêm một thành phần kết hợp NavigationEventHandler mới để xử lý các sự kiện (cử chỉ xem trước thao tác quay lại). Thư viện này cung cấp Flow của các đối tượng NavigationEvent mà bạn phải thu thập trong lambda tạm ngưng mà bạn cung cấp c42ba6:
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
  }
}

Thay đổi về API

  • Giờ đây, mỗi NavigationEventCallback chỉ có thể được đăng ký với một NavigationEventDispatcher tại một thời điểm; việc thêm NavigationEventCallback vào nhiều điều phối viên sẽ tạo ra một IllegalStateException. Xin lưu ý rằng hành vi này khác với OnBackPressedDispatcher, cho phép nhiều trình điều phối. (e82c19)
  • Tạo isPassThrough val để ngăn chặn đột biến trong quá trình điều hướng, điều này có thể làm gián đoạn quá trình gửi của NavigationEvent. (I0b287)

Phiên bản 1.0.0-alpha02

Ngày 4 tháng 6 năm 2025

Phát hành androidx.navigationevent:navigationevent-*:1.0.0-alpha02. Phiên bản 1.0.0-alpha02 bao gồm các thay đổi sau.

Thay đổi về API

  • Thay thế hàm khởi tạo phụ của NavigationEventDispatcher bằng các đối số mặc định. (I716a0)
  • Xoá thuộc tính ưu tiên khỏi NavigationEventCallback. Thay vào đó, hãy truyền mức độ ưu tiên đến NavigationEventDispatcher.addCallback(). (I13cae)

Sửa lỗi

  • Khắc phục ConcurrentModificationException có thể xảy ra khi NavigationEventCallback.remove() được gọi do đồng thời sửa đổi danh sách nội bộ các đối tượng có thể đóng. (b/420919815)

Phiên bản 1.0.0-alpha01

Ngày 20 tháng 5 năm 2025

Phát hành androidx.navigationevent:navigationevent-*:1.0.0-alpha01. Phiên bản 1.0.0-alpha01 bao gồm các thay đổi sau.

Tính năng mới

  • Thư viện androidx.navigationevent cung cấp một API ưu tiên KMP để xử lý thao tác quay lại hệ thống cũng như tính năng Xem trước thao tác quay lại. NavigationEventDispatcher đóng vai trò là một API chung để đăng ký một hoặc nhiều thực thể NavigationEventCallback để nhận các sự kiện quay lại hệ thống.
  • Lớp này nằm bên dưới các API đã phát hành trước đó trong androidx.activity và nhằm mục đích thay thế ít ý kiến hơn cho việc sử dụng API Hoạt động trong các thành phần cấp cao hơn hoặc trực tiếp sử dụng API OnBackInvokedDispatcher của khung Android. Các API androidx.activity đã được viết lại dựa trên Navigation Event API trong Activity 1.12.0-alpha01.