navigation3

  
Navigation 3 là một thư viện điều hướng mới được thiết kế để hoạt động với Compose.
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 8 tháng 10 năm 2025 - - - 1.0.0-alpha11

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

Để thêm một phần phụ thuộc vào navigation3, 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.navigation3:navigation3-runtime:1.0.0-alpha11"
    implementation "androidx.navigation3:navigation3-ui:1.0.0-alpha11"
}

Kotlin

dependencies {
    implementation("androidx.navigation3:navigation3-runtime:1.0.0-alpha11")
    implementation("androidx.navigation3:navigation3-ui:1.0.0-alpha11")
}

Để 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-alpha11

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

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

Thay đổi về API

  • Phương thức calculateScene trên SceneStrategy không còn là @Composable nữa. Thay vào đó, hãy cân nhắc chuyển công việc này sang quá trình tạo phương thức SceneStrategy (tức là trong phương thức rememberMySceneStrategy()) cho phép bạn xác định hoàn toàn thời gian tồn tại của mọi giá trị rememberSaveable hoặc câu lệnh khoá remember dựa trên các giá trị chính xác. (If1733, b/448709506)
  • Tham số onBack cho SceneStrategy.calculateScene đã được chuyển vào phạm vi đối tượng nhận mới của SceneStrategyScope để giúp rõ ràng hơn rằng đây là một tham số không bắt buộc và cung cấp một điểm mở rộng cho các tính năng Navigation3 trong tương lai. (I3aea3, b/448460407)
  • Lambda onBack được truyền vào NavDisplay và SceneStrategy của bạn không còn cung cấp tham số count: Int để cho biết thời điểm cần bật nhiều mục nữa. Thay vào đó, lambda () -> Unit sẽ được gọi nhiều lần liên tiếp trong trường hợp hiếm gặp khi Cảnh của bạn yêu cầu bật nhiều mục. (Idedb5, b/446989346)
  • Xoá lớp NavEntryWrapper và thay thế chức năng của lớp này bằng một lớp NavEntry cuối cùng có một hàm khởi tạo thứ cấp mới nhận NavEntry có nội dung mới. Điều này sẽ cho phép tiếp tục hỗ trợ việc bao bọc một mục bằng nội dung mới. (I7da2a, b/444447130)
  • Hàm navEntryDecorator tạo và trả về NavEntryDecorator đã bị xoá và thay thế bằng lớp NavEntryDecorator. Lớp này hiện được công khai và có thể phân lớp con. (If81f8, b/444447434, b/447381176)
  • SavedStateNavEntryDecorator đã được đổi tên thành SaveableStateHolderNavEntryDecorator vì nó trang trí các mục bằng một SaveableStateHolder. Trình trang trí cũng được tái cấu trúc từ một hàm thành một lớp vì về chức năng, đây là một nhà máy cho NavEntryDecorator. (Ie6013, b/447381176)
  • Các màn hình tuỳ chỉnh sử dụng SceneState làm lựa chọn thay thế cho việc sử dụng NavDisplay không còn cần phải sử dụng thành phần cục bộ LocalEntriesToRenderInCurrentScene nữa (hiện là thành phần nội bộ). (Ic40ef, b/414668196)
  • Xoá SceneSetupNavEntryDecorator và rememberSceneSetupNavEntryDecorator() khỏi giao diện API công khai. Chức năng này hiện được đưa vào theo mặc định mà bạn không cần phải đưa vào theo cách thủ công. (Ieae42, b/444479133)
  • NavEntry, DialogScene, SinglePaneScene và SceneState hiện đều triển khai phương thức equals. (I96121)
  • Giao diện cảnh có một trường siêu dữ liệu mới để đính kèm siêu dữ liệu dành riêng cho cảnh cho NavDisplay. Điều này cho phép một Cảnh ghi đè siêu dữ liệu trên NavDisplay, chẳng hạn như với các hiệu ứng chuyển đổi. (I1fd96, b/443955625)
  • Đơn giản hoá chữ ký rememberNavBackStack bằng cách xoá tham số kiểu dữ liệu chung dư thừa. Giờ đây, hàm này chấp nhận vararg elements: NavKey. (I03e45)
  • Ảnh động mặc định cho NavDisplay hiện là một phần của API chung, cho phép gọi ảnh động từ mọi nền tảng. (I71af9, b/447147159)
  • Đổi tên EntryProviderBuilder thành EntryProviderScope để phản ánh chính xác rằng lớp này là một DSL Kotlin cung cấp phạm vi để tạo NavEntries. (Ia7465)

Sửa lỗi

  • rememberNavBackStack() hiện thực thi quá trình chuyển đổi tuần tự đa hình cho NavKey và yêu cầu một SavedStateConfiguration tuỳ chỉnh được định cấu hình để đảm bảo khôi phục trạng thái chính xác. KDoc đã được cập nhật để phản ánh yêu cầu rằng tất cả các kiểu phụ NavKey phải được đăng ký trong SerializersModule được cung cấp. (I6de37,I782f2, b/446664383)

Phiên bản 1.0.0-alpha10

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

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

Thay đổi về API

  • Thêm phương thức nạp chồng NavDisplay mới nhận danh sách NavEntry<T> đã được trang trí bằng rememberDecoratedNavEntries. (I4025b, b/441940314)
  • Đã di chuyển DialogScene sang một gói mới. (Ia5840)
  • Xoá API công khai DecorateNavEntry. Thay vào đó, hãy dùng rememberDecoratedNavEntries để bao bọc một NavEntry bằng danh sách các đối tượng trang trí. (Id8c09)
  • Giao diện người dùng Navigation3 hiện cung cấp các thuộc tính transitionSpec mặc định mới. (Ibcabd)
  • Đã thêm một đối tượng SceneState mới để giúp quản lý các cảnh. Thao tác này cũng cung cấp một phương thức nạp chồng NavDisplay mới nhận SceneState và NavigationEventState. (Idfb46, b/444479133)
  • NavDisplay hiện cho phép bạn tuỳ chỉnh các hiệu ứng chuyển đổi dựa trên Scene mà bạn sẽ chuyển đến và chuyển đi bằng cách xem currentState và targetState của Transition. (I906cc, b/443872322)
  • 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)
  • 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)
  • Tất cả Scene API đều đã được di chuyển ra khỏi navigation3-ui sang navigation3-runtime. Điều này có nghĩa là các thành phần này hiện có trên tất cả các nền tảng được navigation3-runtime hỗ trợ. (I431d0, b/444449993)
  • Thêm phương thức nạp chồng rememberDecoratedNavEntries mới nhận một danh sách NavEntry để trang trí. Các mục nhập đầu vào có thể đã được trang trí bằng các trình trang trí mục nhập khác. (I5a034, b/444230270)
  • Xoá các tham số loại ký tự đại diện navigation3 (I02540)
  • Cải thiện khả năng xử lý các thành phần chung cho DSL entryProvider. Nếu trước đây bạn đã nhập androidx.navigation3.runtime.entry, thì bạn không cần làm việc này nữa. (I299fc)
  • Hạn chế việc nạp chồng NavBackStackSerializer dựa trên phản chiếu đối với Android. Điều này ngăn chặn các lỗi tuần tự hoá thời gian chạy ngầm trên các nền tảng không phải Android bằng cách thực thi việc sử dụng phương thức nạp chồng SavedStateConfiguration rõ ràng trong mã đa nền tảng. (I73313, b/420443609)
  • Biến NavigationEvent thành swipeEdge @IntDef (Icee54, b/443950342)
  • Hạn chế việc chuyển đổi tuần tự NavBackStack sang Android. Điều này giúp ngăn chặn lỗi thời gian chạy trên các nền tảng không phải Android. Để lưu trạng thái trên nhiều nền tảng, hãy sử dụng phương thức nạp chồng rememberNavBackStack với SavedStateConfiguration rõ ràng. (I1e418, b/420443609)

Sửa lỗi

  • Khắc phục sự cố trong thao tác xem trước khi quay lại khi NavDisplay lồng có một mục nhập con duy nhất. (I2cdc0, b/441933162)

Phiên bản 1.0.0-alpha09

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

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

Thay đổi về API

  • DecoratedNavEntryProvider đã được thay thế bằng rememberDecoratedNavEntries. rememberDecoratedNavEntries sẽ tạo và trả về NavEntry được trang trí bằng danh sách các đối tượng trang trí đã cung cấp (I0fe1c, b/441328236)
  • NavBackStack hiện là giá trị chung trên kiểu NavKey. Điều này cho phép các ứng dụng và thư viện xác định các loại khoá tuỳ chỉnh cho ngăn xếp quay lại của chúng, thay vì bị giới hạn ở NavKey. (I4d190,Iad2f4, b/420443609)
  • NavBackStack hiện là @kotlinx.serialization.Serializable, giúp bạn có thể lưu và khôi phục trạng thái điều hướng trong quá trình bị buộc tắt và thay đổi cấu hình mà không cần thêm mã lặp lại. (I2c3cf, b/420443609)
  • RememberNavBackStack đã được chuyển sang commonMain để đảm bảo rằng thành phần này được cung cấp trên tất cả các mục tiêu nền tảng. (Id69e7, b/420443609)

Sửa lỗi

  • NavDisplay hiện di chuyển chính xác từng NavEntry riêng lẻ đến Lifecycle.State chính xác. (I30aac, b/440145700)
  • Khắc phục vấn đề NavDisplay sẽ bỏ qua mọi NavigationEventDispatcherOwner lồng nhau được đặt thông qua LocalNavigationEventDispatcherOwner của thư viện NavigationEvent. (I6224a)

Thay đổi về phần phụ thuộc

Phiên bản 1.0.0-alpha08

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

Phát hành androidx.navigation3:navigation3-*: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

  • Thêm các mục tiêu Kotlin Multiplatform (KMP) mới vào cấu phần phần mềm Navigation3 Runtime. Navigation3 Runtime hiện hỗ trợ tổng cộng các nền tảng sau: JVM (Android và Máy tính), Native (Linux, iOS, watchOS, macOS, MinGW) và Web (JavaScript, WasmJS). (I55078, b/424410398, b/419294028, b/419046226). Lưu ý: Thao tác này không cung cấp các mục tiêu KMP cho cấu phần phần mềm Navigation3 UI. Trên các nền tảng khác, bạn sẽ cần triển khai NavDisplay tuỳ chỉnh của riêng mình. Nếu bạn muốn thấy tính năng này được hỗ trợ, vui lòng bình chọn cho vấn đề này trên Jetbrains tại đây và theo dõi tiến trình để được hỗ trợ thêm.
  • Đối tượng NavDisplayInfo hiện là đối tượng công khai và có thể dùng để truy xuất danh sách các mục có thể nhìn thấy từ NavDisplay. (Ibc91f)

Thay đổi về API

  • Thêm một NavBackStackSerializer mới để dùng cùng với rememberNavBackStack nhằm thực hiện việc khôi phục trạng thái. rememberNavBackStack() hiện cũng sẽ lấy SavedStateConfiguration mà bạn có thể dùng để cung cấp cấu hình của riêng mình. (I2f4d2, I4cd58, b/420443609)

Sửa lỗi

  • Khắc phục vấn đề trong đó thao tác điều hướng sẽ khiến các sự kiện Vòng đời không chính xác kích hoạt. (I8bf6d, b/425901162, b/434109022)

Lỗi đã biết

  • Có một lỗi do I8bf6d gây ra khiến Vòng đời dựa trên các cảnh thay vì các mục riêng lẻ, điều này làm hỏng Vòng đời cho mọi trường hợp mà key được cung cấp cho NavEntry không phải là String hoặc NavEntry của bạn chưa ghi đè contentKey và đặt nó bằng key (lưu ý rằng việc này buộc khoá của bạn có thể được lưu vào Bundle). Lỗi này đã được khắc phục cho bản phát hành tiếp theo. (b/440145700)

Phiên bản 1.0.0-alpha07

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

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

Nội dung cập nhật về MinSdk

Thay đổi về API

  • Giờ đây, SavedStateNavEntryDecorator sử dụng SaveableStateRegistry được tích hợp trong SaveableStateProvider để lưu và khôi phục trạng thái. (If8d9a)
  • Giờ đây, predictivePopTransitionSpec được cung cấp cạnh vuốt dưới dạng một tham số, cho phép bạn tuỳ chỉnh hiệu ứng chuyển đổi dựa trên cạnh mà người dùng bắt đầu cử chỉ Xem trước thao tác quay lại. (I753a8)

Sửa lỗi

  • Khắc phục vấn đề khiến các cảnh tuỳ chỉnh được tính toán lại vô hạn vì hệ thống không ghi nhớ cảnh gần đây nhất. (I7ba84, b/418153031)

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

Phiên bản 1.0.0-alpha06

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

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

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

Phiên bản 1.0.0-alpha05

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

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

Thay đổi về hành vi

  • Giờ đây, trạng thái của NavEntry hoàn toàn dựa trên danh sách hiện tại của các đối tượng trang trí được truyền đến NavDisplay. Điều này có nghĩa là bạn nên hoán đổi các đối tượng trang trí dọc theo ngăn xếp lui trong trường hợp có nhiều ngăn xếp lui để duy trì trạng thái của NavEntry trên ngăn xếp lui. Nếu không, các trạng thái sẽ bị xoá như thể các mục đã được bật lên (thay vì hoán đổi). (I7a759, b/428033667)

Phiên bản 1.0.0-alpha04

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

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

Thay đổi về API

  • NavEntry.content hiện ở chế độ riêng tư. Để gọi nội dung NavEntry, hãy gọi API NavEntry.Content() mới. API này không còn yêu cầu tham số key để gọi nữa. (Icd0fd, b/420991203)
  • NavEntry.key hiện là một trường riêng tư. NavEntry và các trạng thái có liên quan phải được xác định bằng trường contentKey mới được tạo từ lambda contentKeyFactory mới và mặc định là một hàm băm có thể lưu được tạo từ NavEntry.key (I81a6c, b/422001357, b/420991203 I2d7d4, b/420991203, b/422841812)

Thay đổi về phần phụ thuộc

  • Navigation3 hiện phụ thuộc vào cấu phần phần mềm androidx.navigationevent.compose mới.

Phiên bản 1.0.0-alpha03

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

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

Sửa lỗi

  • Navigation3 sẽ không còn xoá các trạng thái của đối tượng trang trí cho backStacks đã được thay thế bằng một thực thể backStack khác. (I28a42, b/415076044)

Phiên bản 1.0.0-alpha02

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

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

Sửa lỗi

  • Đã khắc phục một vấn đề với SavedStateNavEntryDecorator gây ra xung đột cho các lớp dữ liệu khác nhau có cùng giá trị thuộc tính. (b/418070648, Iff4775)
  • Khắc phục vấn đề thiếu lớp gây ra sự cố khi chạy mà không khai báo các phần phụ thuộc rõ ràng. (b/419049149, I4b4ed)

Phiên bản 1.0.0-alpha01

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

Phát hành androidx.navigation3:navigation3-*: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

Navigation3 là một thư viện điều hướng mới được xây dựng dành riêng cho việc xử lý hoạt động điều hướng trong ứng dụng Jetpack Compose. Cấu phần phần mềm androidx.navigation3.runtime cung cấp các khối dựng, trong khi cấu phần phần mềm androidx.navigation3.ui cung cấp lớp giao diện người dùng thông qua API NavDisplay. Nhà phát triển có thể cung cấp trạng thái riêng của họ trực tiếp cho hàm có khả năng kết hợp NavDisplay. Hàm này sẽ thay đổi nội dung dựa trên các thay đổi về trạng thái của nhà phát triển.

@Serialiable object Home : NavKey
@Serialiable object Chat : NavKey

val backStack = rememberNavBackStack(Home)

NavDisplay(backStack, entryProvider = entryProvider {
  entry<Home> {
    Column {
      Text(“Home”)
      Button(onClick = { backStack.add(Chat) } ) {
        Text(“Go to Chat”)
      } 
    }
  }
  entry<Chat> { /* My Composable Content */ }
})

Để biết thêm thông tin, hãy xem hướng dẫn về Navigation3.