Trang này được dịch bởi Cloud Translation API.

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

Thành phần điều hướng hỗ trợ các ứng dụng sử dụng công cụ Jetpack Compose. Bạn có thể di chuyển giữa các thành phần kết hợp trong khi tận dụng cơ sở hạ tầng và các tính năng của thành phần Điều hướng.

Thiết lập

Để hỗ trợ Compose, hãy sử dụng phần phụ thuộc sau trong tệp build.gradle của mô-đun ứng dụng:

Groovy

dependencies {
    def nav_version = "2.8.4"

    implementation "androidx.navigation:navigation-compose:$nav_version"
}

Kotlin

dependencies {
    val nav_version = "2.8.4"

    implementation("androidx.navigation:navigation-compose:$nav_version")
}

Bắt đầu

Khi triển khai tính năng điều hướng trong một ứng dụng, hãy triển khai máy chủ điều hướng, biểu đồ và bộ điều khiển. Để biết thêm thông tin, hãy xem phần tổng quan về Điều hướng.

Tạo NavController

Để biết thông tin về cách tạo NavController trong Compose, hãy xem phần Compose trong bài viết Tạo trình điều khiển điều hướng.

Tạo NavHost

Để biết thông tin về cách tạo NavHost trong Compose, hãy xem phần Compose trong bài viết Thiết kế biểu đồ điều hướng.

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

Để biết thông tin về cách điều hướng đến một Thành phần kết hợp, hãy xem phần Điều hướng đến một đích đến trong tài liệu về cấu trúc.

Điều hướng bằng đối số

Để biết thông tin về cách truyền đối số giữa các đích đến có thể kết hợp, hãy xem phần Compose trong bài viết Thiết kế biểu đồ điều hướng.

Truy xuất dữ liệu phức tạp khi điều hướng

Bạn không nên truyền các đối tượng dữ liệu phức tạp khi điều hướng, mà thay vào đó hãy truyền thông tin tối thiểu cần thiết, chẳng hạn như giá trị nhận dạng duy nhất hoặc hình thức mã nhận dạng khác, làm đối số khi thực hiện các thao tác điều hướng:

// Pass only the user ID when navigating to a new destination as argument
navController.navigate(Profile(id = "user1234"))

Các đối tượng phức tạp phải được lưu trữ dưới dạng dữ liệu trong một nguồn đáng tin cậy, chẳng hạn như lớp dữ liệu. Khi đã tới đích đến sau khi điều hướng, bạn có thể tải thông tin cần thiết từ một nguồn đáng tin cậy thông qua mã nhận dạng được truyền. Để truy xuất các đối số trong ViewModel chịu trách nhiệm truy cập vào lớp dữ liệu, hãy sử dụng SavedStateHandle của ViewModel:

class UserViewModel(
    savedStateHandle: SavedStateHandle,
    private val userInfoRepository: UserInfoRepository
) : ViewModel() {

    private val profile = savedStateHandle.toRoute<Profile>()

    // Fetch the relevant user information from the data layer,
    // ie. userInfoRepository, based on the passed userId argument
    private val userInfo: Flow<UserInfo> = userInfoRepository.getUserInfo(profile.id)

// …

}

Cách này giúp ngăn chặn tình trạng mất dữ liệu trong quá trình thay đổi cấu hình và mọi sự không nhất quán khi đối tượng được đề cập đang được cập nhật hoặc thay đổi.

Để hiểu rõ hơn về lý do bạn nên tránh truyền dữ liệu phức tạp làm đối số, cũng như danh sách các loại đối số được hỗ trợ, hãy xem bài viết Truyền dữ liệu giữa các đích đến.

Liên kết sâu

Thành phần Điều hướng trong Compose hỗ trợ các đường liên kết sâu cũng có thể được xác định dưới dạng một phần của hàm composable(). Tham số deepLinks của thành phần Điều hướng chấp nhận danh sách các đối tượng NavDeepLink có thể được tạo nhanh bằng cách sử dụng phương thức navDeepLink():

@Serializable data class Profile(val id: String)
val uri = "https://www.example.com"

composable<Profile>(
  deepLinks = listOf(
    navDeepLink<Profile>(basePath = "$uri/profile")
  )
) { backStackEntry ->
  ProfileScreen(id = backStackEntry.toRoute<Profile>().id)
}

Các đường liên kết sâu này cho phép bạn liên kết một URL, hành động và/hoặc loại MIME cụ thể với một thành phần kết hợp. Theo mặc định, các đường liên kết sâu này không hiển thị với các ứng dụng bên ngoài. Để đặt các đường liên kết sâu này ở bên ngoài, bạn phải thêm các phần tử <intent-filter> thích hợp vào tệp manifest.xml của ứng dụng. Để bật đường liên kết sâu trong ví dụ trước, bạn nên thêm nội dung sau đây vào phần tử <activity> của tệp kê khai:

<activity …>
  <intent-filter>
    ...
    <data android:scheme="https" android:host="www.example.com" />
  </intent-filter>
</activity>

Thành phần điều hướng sẽ tự động liên kết sâu vào các thành phần kết hợp đó khi đường liên kết sâu được một ứng dụng khác kích hoạt.

Bạn cũng có thể sử dụng các đường liên kết sâu này để tạo PendingIntent bằng đường liên kết sâu phù hợp từ một thành phần kết hợp:

val id = "exampleId"
val context = LocalContext.current
val deepLinkIntent = Intent(
    Intent.ACTION_VIEW,
    "https://www.example.com/profile/$id".toUri(),
    context,
    MyActivity::class.java
)

val deepLinkPendingIntent: PendingIntent? = TaskStackBuilder.create(context).run {
    addNextIntentWithParentStack(deepLinkIntent)
    getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT)
}

Sau đó, bạn có thể sử dụng deepLinkPendingIntent này như bất kỳ PendingIntent nào khác để mở ứng dụng của mình tại đích đến của đường liên kết sâu.

Thành phần Điều hướng được lồng

Để biết thông tin về cách tạo biểu đồ điều hướng lồng nhau, hãy xem phần Biểu đồ lồng nhau.

Tích hợp với thanh điều hướng dưới cùng

Bằng cách xác định NavController ở cấp cao hơn trong hệ phân cấp thành phần kết hợp, bạn có thể kết nối thành phần Điều hướng với các thành phần khác như thành phần điều hướng dưới cùng. Thao tác này cho phép bạn di chuyển bằng cách chọn các biểu tượng trên thanh dưới cùng.

Để sử dụng các thành phần BottomNavigation và BottomNavigationItem, hãy thêm phần phụ thuộc androidx.compose.material vào ứng dụng Android.

Groovy

dependencies {
    implementation "androidx.compose.material:material:1.7.5"
}

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.15"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Kotlin

dependencies {
    implementation("androidx.compose.material:material:1.7.5")
}

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.15"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Để liên kết các mục trong thanh điều hướng ở dưới cùng với các tuyến đường trong biểu đồ điều hướng, bạn nên xác định một lớp, chẳng hạn như TopLevelRoute có ở đây, có một lớp tuyến đường và một biểu tượng.

data class TopLevelRoute<T : Any>(val name: String, val route: T, val icon: ImageVector)

Sau đó, hãy đặt các tuyến đó vào danh sách mà BottomNavigationItem có thể sử dụng:

val topLevelRoutes = listOf(
   TopLevelRoute("Profile", Profile, Icons.Profile),
   TopLevelRoute("Friends", Friends, Icons.Friends)
)

Trong thành phần kết hợp BottomNavigation, hãy sử dụng hàm currentBackStackEntryAsState() để nhận NavBackStackEntry hiện tại. Mục nhập này cung cấp cho bạn quyền truy cập vào NavDestination hiện tại. Sau đó, bạn có thể xác định trạng thái đã chọn của từng BottomNavigationItem bằng cách so sánh tuyến của mục với tuyến của đích đến hiện tại và đích đến gốc của mục đó để xử lý các trường hợp khi bạn đang sử dụng thành phần điều hướng được lồng bằng hệ phân cấp NavDestination.

Tuyến của mục này cũng được dùng để kết nối hàm lambda onClick với lệnh gọi đến navigate sao cho thao tác nhấn vào mục sẽ điều hướng đến mục đó. Bằng cách sử dụng cờ saveState và restoreState, trạng thái và ngăn xếp lui của mục đó sẽ được lưu và khôi phục chính xác khi bạn hoán đổi giữa các mục điều hướng dưới cùng.

val navController = rememberNavController()
Scaffold(
  bottomBar = {
    BottomNavigation {
      val navBackStackEntry by navController.currentBackStackEntryAsState()
      val currentDestination = navBackStackEntry?.destination
      topLevelRoutes.forEach { topLevelRoute ->
        BottomNavigationItem(
          icon = { Icon(topLevelRoute.icon, contentDescription = topLevelRoute.name) },
          label = { Text(topLevelRoute.name) },
          selected = currentDestination?.hierarchy?.any { it.hasRoute(topLevelRoute.route::class) } == true,
          onClick = {
            navController.navigate(topLevelRoute.route) {
              // Pop up to the start destination of the graph to
              // avoid building up a large stack of destinations
              // on the back stack as users select items
              popUpTo(navController.graph.findStartDestination().id) {
                saveState = true
              }
              // Avoid multiple copies of the same destination when
              // reselecting the same item
              launchSingleTop = true
              // Restore state when reselecting a previously selected item
              restoreState = true
            }
          }
        )
      }
    }
  }
) { innerPadding ->
  NavHost(navController, startDestination = Profile, Modifier.padding(innerPadding)) {
    composable<Profile> { ProfileScreen(...) }
    composable<Friends> { FriendsScreen(...) }
  }
}

Tại đây, bạn sẽ tận dụng phương thức NavController.currentBackStackEntryAsState() để nâng trạng thái navController khỏi hàm NavHost và chia sẻ với thành phần BottomNavigation. Điều này có nghĩa là BottomNavigation tự động có trạng thái cập nhật mới nhất.

Khả năng tương tác

Nếu muốn sử dụng thành phần Điều hướng trong Compose, bạn có 2 lựa chọn:

Xác định biểu đồ điều hướng có thành phần Điều hướng cho các mảnh.
Xác định biểu đồ điều hướng có NavHost trong Compose bằng cách sử dụng đích đến Compose. Điều này chỉ có thể xảy ra nếu tất cả các màn hình trong biểu đồ điều hướng đều có thể kết hợp.

Do đó, ứng dụng Compose và Khung hiển thị kết hợp nên sử dụng Thành phần điều hướng dựa trên Mảnh. Sau đó, Mảnh sẽ giữ lại các màn hình dựa trên Khung hiển thị, màn hình Compose và màn hình sử dụng cả Khung hiển thị và Compose. Khi nội dung của mỗi Mảnh nằm trong Compose, bước tiếp theo là liên kết tất cả màn hình với nhau bằng thành phần Điều hướng trong Compose rồi xoá mọi Mảnh.

Di chuyển từ Compose bằng thành phần Điều hướng cho mảnh

Để thay đổi điểm đến bên trong mã Compose, bạn hiển thị các sự kiện có thể chuyển tới cũng như kích hoạt bởi thành phần kết hợp bất kỳ trong hệ phân cấp:

@Composable
fun MyScreen(onNavigate: (Int) -> Unit) {
    Button(onClick = { onNavigate(R.id.nav_profile) } { /* ... */ }
}

Trong phân đoạn của bạn, bạn tạo cầu nối giữa Compose và thành phần Điều hướng dựa trên phân đoạn bằng cách tìm NavController và điều hướng đến đích:

override fun onCreateView( /* ... */ ) {
    setContent {
        MyScreen(onNavigate = { dest -> findNavController().navigate(dest) })
    }
}

Ngoài ra, bạn có thể chuyển NavController xuống theo hệ thống phân cấp của Compose. Tuy nhiên, việc hiển thị các hàm đơn giản sẽ giúp dễ sử dụng lại và kiểm thử hơn.

Thử nghiệm

Tách mã điều hướng khỏi các đích đến có thể kết hợp để cho phép kiểm thử riêng từng thành phần kết hợp, tách biệt với thành phần kết hợp NavHost.

Điều này có nghĩa là bạn không nên truyền navController trực tiếp vào thành phần kết hợp nào mà thay vào đó, hãy truyền lệnh gọi lại điều hướng dưới dạng tham số. Điều này cho phép kiểm thử riêng lẻ tất cả các thành phần kết hợp của bạn, vì chúng không yêu cầu thực thể của navController trong kiểm thử.

Cấp độ gián tiếp do lambda composable cung cấp là yếu tố cho phép bạn tách riêng mã Điều hướng khỏi chính thành phần kết hợp này. Cách này hoạt động theo hai hướng:

Chỉ chuyển đối số được phân tích cú pháp vào thành phần kết hợp của bạn
Truyền các lambda nên được thành phần kết hợp kích hoạt để điều hướng, thay vì chính NavController.

Ví dụ: một thành phần kết hợp ProfileScreen lấy userId làm dữ liệu đầu vào và cho phép người dùng chuyển đến trang hồ sơ của một người bạn có thể có chữ ký:

@Composable
fun ProfileScreen(
    userId: String,
    navigateToFriendProfile: (friendUserId: String) -> Unit
) {
 …
}

Theo đó, thành phần kết hợp ProfileScreen hoạt động độc lập với thành phần Điều hướng nên có thể được kiểm thử độc lập. Lambda composable sẽ đóng gói logic tối thiểu cần thiết để thu hẹp khoảng cách giữa các Navigation API (API Điều hướng) và thành phần kết hợp của bạn:

@Serializable data class Profile(id: String)

composable<Profile> { backStackEntry ->
    val profile = backStackEntry.toRoute<Profile>()
    ProfileScreen(userId = profile.id) { friendUserId ->
        navController.navigate(route = Profile(id = friendUserId))
    }
}

Bạn nên viết các kiểm thử đáp ứng các yêu cầu điều hướng trong ứng dụng bằng cách kiểm thử NavHost, các thao tác điều hướng được truyền đến thành phần kết hợp cũng như các thành phần kết hợp màn hình riêng lẻ.

Kiểm thử `NavHost`

Để bắt đầu kiểm thử NavHost , hãy thêm phần phụ thuộc kiểm thử điều hướng sau:

dependencies {
// ...
  androidTestImplementation "androidx.navigation:navigation-testing:$navigationVersion"
  // ...
}

Gói NavHost của ứng dụng trong một thành phần kết hợp chấp nhận NavHostController làm tham số.

@Composable
fun AppNavHost(navController: NavHostController){
  NavHost(navController = navController){ ... }
}

Giờ đây, bạn có thể kiểm thử AppNavHost và tất cả logic điều hướng được xác định bên trong NavHost bằng cách truyền một thực thể của cấu phần phần mềm kiểm thử điều hướng TestNavHostController. Quy trình kiểm thử giao diện người dùng xác minh đích bắt đầu của ứng dụng và NavHost sẽ có dạng như sau:

class NavigationTest {

    @get:Rule
    val composeTestRule = createComposeRule()
    lateinit var navController: TestNavHostController

    @Before
    fun setupAppNavHost() {
        composeTestRule.setContent {
            navController = TestNavHostController(LocalContext.current)
            navController.navigatorProvider.addNavigator(ComposeNavigator())
            AppNavHost(navController = navController)
        }
    }

    // Unit test
    @Test
    fun appNavHost_verifyStartDestination() {
        composeTestRule
            .onNodeWithContentDescription("Start Screen")
            .assertIsDisplayed()
    }
}

Kiểm thử thao tác điều hướng

Bạn có thể kiểm thử hoạt động triển khai tính năng điều hướng theo nhiều cách, chẳng hạn như nhấp vào thành phần trên giao diện người dùng, sau đó xác minh đích đến đã hiển thị hoặc bằng cách so sánh tuyến dự kiến với tuyến hiện tại.

Khi muốn kiểm thử việc triển khai ứng dụng cụ thể của mình, bạn nên kiểm thử theo cách nhấp vào giao diện người dùng. Để tìm hiểu cách kiểm thử một cách độc lập điều này cùng với các hàm có khả năng kết hợp riêng lẻ, hãy nhớ tham khảo lớp học lập trình Kiểm thử trong Jetpack Compose.

Bạn cũng có thể sử dụng navController để kiểm tra các câu nhận định của mình bằng cách so sánh tuyến đường hiện tại với tuyến đường dự kiến bằng cách sử dụng currentBackStackEntry của navController:

@Test
fun appNavHost_clickAllProfiles_navigateToProfiles() {
    composeTestRule.onNodeWithContentDescription("All Profiles")
        .performScrollTo()
        .performClick()

    assertTrue(navController.currentBackStackEntry?.destination?.hasRoute<Profile>() ?: false)
}

Để biết thêm hướng dẫn về các kiến thức cơ bản về kiểm thử trong Compose, hãy xem bài viết Kiểm thử bố cục Compose và lớp học lập trình Kiểm thử trong Jetpack Compose. Để tìm hiểu thêm về kiểm thử nâng cao đối với mã điều hướng, vui lòng tham khảo hướng dẫn Kiểm thử thành phần Navigation (Điều hướng).

Tìm hiểu thêm

Để tìm hiểu thêm về thành phần Điều hướng trong Jetpack, hãy xem phần Bắt đầu với thành phần Điều hướng hoặc tham gia Lớp học lập trình về thành phần Điều hướng trong Jetpack Compose.

Để tìm hiểu cách thiết kế tính năng điều hướng trong ứng dụng sao cho phù hợp với nhiều kích thước màn hình, hướng và các hệ số hình dạng, hãy xem bài viết Điều hướng trên giao diện người dùng thích ứng.

Để tìm hiểu thêm về cách triển khai nâng cao hơn cho thành phần Điều hướng trong Compose trong một ứng dụng được mô-đun hoá, bao gồm cả các khái niệm như biểu đồ lồng và tích hợp thanh điều hướng dưới cùng, hãy tham khảo ứng dụng Now in Android trên GitHub.

Mẫu

Đề xuất cho bạn

Lưu ý: văn bản có đường liên kết sẽ hiện khi JavaScript tắt
Material Design 2 trong Compose
Di chuyển thành phần Điều hướng Jetpack sang Navigation Compose
Nơi chuyển trạng thái lên trên

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

Thiết lập

Groovy

Kotlin

Bắt đầu

Tạo NavController

Tạo NavHost

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

Điều hướng bằng đối số

Truy xuất dữ liệu phức tạp khi điều hướng

Liên kết sâu

Thành phần Điều hướng được lồng

Tích hợp với thanh điều hướng dưới cùng

Groovy

Kotlin

Khả năng tương tác

Di chuyển từ Compose bằng thành phần Điều hướng cho mảnh

Thử nghiệm

Kiểm thử NavHost

Kiểm thử thao tác điều hướng

Tìm hiểu thêm

Mẫu

Đề xuất cho bạn

Kiểm thử `NavHost`