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 30 tháng 7 năm 2025 - - - 1.0.0-alpha05

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-alpha05"
}

Kotlin

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

Để 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-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 trình điều phối và các trình điều phối 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 không báo cáo 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ử. Thao tác này 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 hoạt động 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 để khớ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 cấu trúc 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 một val để ngăn chặn quá trình đột biến trong khi điều hướng, điều này có thể làm gián đoạn quá trình gửi 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.