Điều hướng đến một đích đến

Thành phần Điều hướng cung cấp một cách thức chung và đơn giản để điều hướng tới một đích đến. Giao diện này hỗ trợ nhiều ngữ cảnh và khung giao diện người dùng. Ví dụ: bạn có thể sử dụng thành phần Điều hướng với Compose, Thành phần hiển thị, Mảnh, Hoạt động và thậm chí cả các khung giao diện người dùng tuỳ chỉnh.

Hướng dẫn này mô tả cách bạn có thể sử dụng thành phần Điều hướng để điều hướng tới một đích đến trong nhiều ngữ cảnh.

Sử dụng một NavController

Loại khoá bạn dùng để điều hướng giữa các đích đến là NavController. Xem nội dung Tạo trình điều khiển điều hướng để biết thêm thông tin về lớp đó và cách tạo thực thể tương ứng. Hướng dẫn này trình bày chi tiết về cách sử dụng trình điều khiển điều hướng.

Điều hướng

Bất kể đang dùng khung giao diện người dùng nào, bạn đều có thể sử dụng một hàm duy nhất để điều hướng tới một đích đến: NavController.navigate().

Có nhiều phương thức nạp chồng cho navigate(). Bạn nên chọn phương thức nạp chồng tương ứng với ngữ cảnh chính xác của mình. Ví dụ: bạn nên sử dụng một phương thức nạp chồng khi điều hướng đến một thành phần kết hợp và dùng một phương thức khác khi điều hướng đến một khung hiển thị.

Các phần sau đây trình bày một số phương thức nạp chồng navigate() chính mà bạn có thể sử dụng sử dụng.

Điều hướng đến một thành phần kết hợp

Để chuyển đến một thành phần kết hợp, bạn nên sử dụng NavController.navigate<T>. Với phương thức nạp chồng này, navigate() sẽ lấy một đối số route duy nhất mà bạn truyền một loại. Đối số này đóng vai trò như chìa khoá cho một đích đến.

@Serializable
object FriendsList

navController.navigate(route = FriendsList)

Để chuyển đến một thành phần kết hợp trong biểu đồ điều hướng, trước tiên, hãy xác định NavGraph sao cho mỗi đích đến tương ứng với một loại. Cho thành phần kết hợp, bạn có thể làm như vậy bằng hàm composable().

Hiện sự kiện từ các thành phần kết hợp

Khi một hàm có khả năng kết hợp cần chuyển đến một màn hình mới, bạn không nên truyền mục tham chiếu đến NavController để nó có thể trực tiếp gọi navigate(). Theo nguyên tắc Luồng dữ liệu một chiều (UDF), thành phần kết hợp phải hiện một sự kiện mà NavController xử lý.

Nói một cách trực tiếp hơn, thành phần kết hợp sẽ có một tham số thuộc kiểu () -> Unit. Khi bạn thêm đích đến vào NavHost bằng hàm composable(), hãy truyền cho thành phần kết hợp một lệnh gọi đến NavController.navigate().

Hãy xem tiểu mục sau đây để biết ví dụ về trường hợp này.

Cảnh báo: Đừng truyền NavController cho các thành phần kết hợp. Hiển thị sự kiện dưới dạng được mô tả ở đây.

Ví dụ

Để xem thông tin minh hoạ cho các phần trước, hãy quan sát những điểm sau trong đoạn mã sau:

1. Mỗi đích đến trong biểu đồ được tạo bằng cách sử dụng một tuyến đường, đối tượng hoặc lớp có thể chuyển đổi tuần tự mô tả dữ liệu mà công cụ đó yêu cầu đích.
2. Thành phần kết hợp MyAppNavHost chứa thực thể NavController.
3. Theo đó, các lệnh gọi đến navigate() sẽ xảy ra ở đó chứ không phải trong một thành phần kết hợp thấp hơn như ProfileScreen.
4. ProfileScreen chứa một nút điều hướng người dùng đến FriendsList khi được nhấp vào. Tuy nhiên, nút này sẽ không gọi chính navigate().
5. Thay vào đó, nút này sẽ gọi một hàm hiển thị dưới dạng tham số onNavigateToFriends.
6. Khi MyAppNavHost thêm ProfileScreen vào biểu đồ điều hướng, đối với onNavigateToFriends sẽ truyền một hàm lambda gọi navigate(route = FriendsList).
7. Điều này đảm bảo rằng khi người dùng nhấn nút ProfileScreen, họ sẽ di chuyển chính xác đến FriendsListScreen.

@Serializable
object Profile
@Serializable
object FriendsList

@Composable
fun MyAppNavHost(
    modifier: Modifier = Modifier,
    navController: NavHostController = rememberNavController(),

) {
    NavHost(
        modifier = modifier,
        navController = navController,
        startDestination = Profile
    ) {
        composable<Profile> {
            ProfileScreen(
                onNavigateToFriends = { navController.navigate(route = FriendsList) },
                /*...*/
            )
        }
        composable<FriendsList> { FriendsListScreen(/*...*/) }
    }
}

@Composable
fun ProfileScreen(
    onNavigateToFriends: () -> Unit,
    /*...*/
) {
    /*...*/
    Button(onClick = onNavigateToFriends) {
        Text(text = "See friends list")
    }
}

Cảnh báo: Bạn chỉ nên gọi navigate() trong lệnh gọi lại chứ không phải như một phần của chính thành phần kết hợp. Điều này giúp tránh gọi navigate() trên mỗi tái cấu trúc.

Điều hướng bằng mã nhận dạng số nguyên

Để điều hướng một đích đến bằng mã nhận dạng số nguyên, hãy gọi phương thức nạp chồng navigate(int). Phương thức này lấy mã nhận dạng tài nguyên của một tác vụ hoặc một đích đến. Đoạn mã sau đây cho biết cách bạn có thể sử dụng phương thức nạp chồng này để điều hướng đến ViewTransactionsFragment:

Kotlin

viewTransactionsButton.setOnClickListener { view ->
  view.findNavController().navigate(R.id.viewTransactionsAction)
}

Java

viewTransactionsButton.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View view) {
      Navigation.findNavController(view).navigate(R.id.viewTransactionsAction);
  }
});

Khi điều hướng bằng mã nhận dạng, bạn nên sử dụng các thao tác nếu có thể. Các thao tác cung cấp thêm thông tin trong biểu đồ điều hướng, cho thấy cách các đích đến của bạn kết nối với nhau.

Lưu ý: Có 3 biến thể Navigation.createNavigateOnClickListener() của các nút. Các biến thể này sẽ giúp ích nếu bạn dùng ngôn ngữ lập trình Java. Nếu bạn dùng Kotlin, OnClickListener là một giao diện SAM, vì vậy bạn có thể sử dụng hàm lambda tạo vệt. Cách này có thể ngắn hơn và dễ đọc hơn so với việc gọi trực tiếp createNavigateOnClickListener().

Lưu ý: Để xử lý các thành phần thường gặp khác trên giao diện người dùng, chẳng hạn như thanh ứng dụng trên cùng và thanh điều hướng dưới cùng, hãy xem hướng dẫn Cập nhật thành phần giao diện người dùng bằng NavigationUI.

Điều hướng bằng NavDeepLinkRequest

Để điều hướng tới một đích đến của đường liên kết sâu ngầm ẩn, hãy sử dụng phương thức nạp chồng navigate(NavDeepLinkRequest). Đoạn mã sau đây cung cấp cách triển khai phương thức này:

Kotlin

val request = NavDeepLinkRequest.Builder
  .fromUri("android-app://androidx.navigation.app/profile".toUri())
  .build()
findNavController().navigate(request)

Java

NavDeepLinkRequest request = NavDeepLinkRequest.Builder
  .fromUri(Uri.parse("android-app://androidx.navigation.app/profile"))
  .build()
NavHostFragment.findNavController(this).navigate(request)

Không giống như cách điều hướng bằng mã thao tác hoặc mã đích đến, bạn có thể chuyển đến bất kỳ đường liên kết sâu nào trong biểu đồ, cho dù đích đến đó có hiển thị hay không. Bạn có thể điều hướng đến một đích đến trên biểu đồ hiện tại hoặc trên một biểu đồ hoàn toàn khác.

Thận trọng: Khi điều hướng bằng NavDeepLinkRequest, ngăn xếp lui sẽ không đặt lại. Hành vi này không giống như các hình thức điều hướng liên kết sâu khác. Tuy nhiên, popUpTo() và popUpToInclusive() vẫn xoá đích đến khỏi ngăn xếp lui như thể bạn đã điều hướng bằng mã nhận dạng.

Lưu ý: Để thuận tiện, bạn cũng có thể sử dụng navigate(Uri) có gói một Uri trong DeepLinkRequest.

Thao tác và loại MIME

Ngoài Uri, NavDeepLinkRequest cũng hỗ trợ các đường liên kết sâu với thao tác và loại MIME. Để thêm một thao tác vào yêu cầu, hãy sử dụng fromAction() hoặc setAction(). Để thêm một loại MIME vào yêu cầu, hãy sử dụng fromMimeType() hoặc setMimeType().

Để NavDeepLinkRequest khớp với đích đến của đường liên kết sâu ngầm ẩn thì URI, thao tác và loại MIME phải khớp với NavDeepLink trong đích đến. URI phải khớp với mẫu, các thao tác phải khớp chính xác và loại MIME phải liên quan với nhau. Ví dụ: image/jpg khớp với image/\*

Ngữ cảnh khác

Tài liệu này trình bày cách sử dụng NavController.navigate() trong các trường hợp sử dụng phổ biến nhất. Tuy nhiên, hàm này có một loạt các phương thức nạp chồng mà bạn có thể sử dụng trong nhiều ngữ cảnh và kết hợp với bất kỳ khung giao diện người dùng nào. Hãy xem tài liệu tham khảo để biết thêm thông tin chi tiết về các phương thức nạp chồng này.

Tài liệu đọc thêm

Để biết thêm thông tin chi tiết, vui lòng xem các trang dưới đây:

• Tạo một trình điều khiển điều hướng
• Thành phần Điều hướng và ngăn xếp lui
• Điều hướng bằng các lựa chọn
• An toàn về kiểu trong Kotlin DSL và Navigation Compose