Mem-build navigasi adaptif

Sebagian besar aplikasi memiliki beberapa tujuan tingkat atas yang dapat diakses melalui UI navigasi utama aplikasi Anda. Di jendela yang ringkas, seperti ponsel standar tujuan, biasanya ditampilkan dalam bilah navigasi di bagian bawah jendela. Di jendela yang diperluas, seperti aplikasi layar penuh pada tablet, kolom samping navigasi di samping aplikasi biasanya merupakan pilihan yang lebih baik karena kontrol navigasi lebih mudah dijangkau sambil menahan sisi kiri dan kanan perangkat.

NavigationSuiteScaffold menyederhanakan peralihan antar-UI navigasi dengan menampilkan composable UI navigasi yang sesuai berdasarkan WindowSizeClass. Hal ini mencakup secara dinamis mengubah UI selama perubahan ukuran jendela runtime. Perilaku defaultnya adalah menampilkan salah satu komponen UI berikut:

• Menu navigasi jika lebar atau tingginya ringkas atau jika perangkat berada dalam posisi dalam postur mode di atas meja
• Kolom samping navigasi untuk lainnya

Menambahkan dependensi

NavigationSuiteScaffold adalah bagian dari Suite navigasi adaptif Material3 library. Tambahkan dependensi untuk library di file build.gradle aplikasi Anda atau modul:

implementation("androidx.compose.material3:material3-adaptive-navigation-suite")

implementation 'androidx.compose.material3:material3-adaptive-navigation-suite'

Membuat scaffold

Dua bagian utama NavigationSuiteScaffold adalah item navigasi suite dan konten untuk tujuan yang dipilih. Anda bisa langsung menentukan item suite navigasi dalam composable, tetapi biasanya item yang ditentukan di tempat lain, misalnya dalam enum:

enum class AppDestinations(
    @StringRes val label: Int,
    val icon: ImageVector,
    @StringRes val contentDescription: Int
) {
    HOME(R.string.home, Icons.Default.Home, R.string.home),
    FAVORITES(R.string.favorites, Icons.Default.Favorite, R.string.favorites),
    SHOPPING(R.string.shopping, Icons.Default.ShoppingCart, R.string.shopping),
    PROFILE(R.string.profile, Icons.Default.AccountBox, R.string.profile),
}
SampleNavigationSuiteScaffold.kt

Untuk menggunakan NavigationSuiteScaffold, Anda harus melacak tujuan saat ini, yang Anda dapat melakukannya dengan menggunakan rememberSaveable:

var currentDestination by rememberSaveable { mutableStateOf(AppDestinations.HOME) }
SampleNavigationSuiteScaffold.kt

Dalam contoh berikut, parameter navigationSuiteItems (jenis NavigationSuiteScope menggunakan fungsi item untuk menentukan UI navigasi untuk setiap tujuan. UI tujuan adalah digunakan di seluruh bilah navigasi, kolom samping, dan panel samping. Untuk membuat item navigasi, Anda loop pada AppDestinations (ditentukan dalam cuplikan sebelumnya):

NavigationSuiteScaffold(
    navigationSuiteItems = {
        AppDestinations.entries.forEach {
            item(
                icon = {
                    Icon(
                        it.icon,
                        contentDescription = stringResource(it.contentDescription)
                    )
                },
                label = { Text(stringResource(it.label)) },
                selected = it == currentDestination,
                onClick = { currentDestination = it }
            )
        }
    }
) {
    // TODO: Destination content.
}
SampleNavigationSuiteScaffold.kt

Dalam lambda konten tujuan, gunakan nilai currentDestination untuk memutuskan UI apa yang akan ditampilkan. Jika Anda menggunakan library navigasi di aplikasi, gunakan library tersebut untuk menampilkan tujuan yang sesuai. Pernyataan when (kapan) bisa cukup:

NavigationSuiteScaffold(
    navigationSuiteItems = { /*...*/ }
) {
    // Destination content.
    when (currentDestination) {
        AppDestinations.HOME -> HomeDestination()
        AppDestinations.FAVORITES -> FavoritesDestination()
        AppDestinations.SHOPPING -> ShoppingDestination()
        AppDestinations.PROFILE -> ProfileDestination()
    }
}
SampleNavigationSuiteScaffold.kt

Ubah warna

NavigationSuiteScaffold membuat Surface di seluruh area yang menempati perancah, biasanya jendela penuh. Selain itu, scaffold menggambar UI navigasi tertentu, seperti NavigationBar. Baik platform maupun UI navigasi menggunakan nilai yang ditentukan dalam atribut tema, tetapi Anda dapat mengganti nilai tema.

Parameter containerColor menentukan warna platform. Default adalah warna latar belakang skema warna Anda. Parameter contentColor menentukan warna konten di platform tersebut. Defaultnya adalah "on" warna apa pun yang ditentukan untuk containerColor. Misalnya, jika containerColor menggunakan warna background, lalu contentColor menggunakan warna onBackground. Lihat Tema Desain Material 3 di Compose untuk detail selengkapnya tentang cara kerja sistem warna. Saat mengganti nilai-nilai ini, gunakan nilai yang ditentukan dalam tema Anda sehingga aplikasi mendukung tampilan gelap dan terang :

NavigationSuiteScaffold(
    navigationSuiteItems = { /* ... */ },
    containerColor = MaterialTheme.colorScheme.primary,
    contentColor = MaterialTheme.colorScheme.onPrimary,
) {
    // Content...
}
SampleNavigationSuiteScaffold.kt

UI navigasi digambar di depan platform NavigationSuiteScaffold. Nilai default untuk warna UI disediakan oleh NavigationSuiteDefaults.colors(), tetapi Anda juga dapat mengganti nilai-nilai ini. Misalnya, jika Anda ingin latar belakang {i>navigation bar<i} menjadi transparan tetapi nilai-nilai lainnya menjadi {i>default<i}, ganti navigationBarContainerColor:

NavigationSuiteScaffold(
    navigationSuiteItems = { /* ... */ },
    navigationSuiteColors = NavigationSuiteDefaults.colors(
        navigationBarContainerColor = Color.Transparent,
    )
) {
    // Content...
}
SampleNavigationSuiteScaffold.kt

Pada akhirnya, Anda dapat menyesuaikan setiap item di UI navigasi. Saat memanggil item, Anda dapat meneruskan instance NavigationSuiteItemColors. Class menentukan warna untuk item dalam bilah navigasi, kolom samping navigasi, dan navigasi panel samping. Itu berarti Anda dapat memiliki warna yang identik di setiap jenis UI navigasi, atau Anda dapat memvariasikan warna berdasarkan kebutuhan Anda. Tentukan warna pada Level NavigationSuiteScaffold untuk menggunakan instance objek yang sama untuk semua item dan panggil fungsi NavigationSuiteDefaults.itemColors() untuk mengganti yang ingin Anda ubah:

val myNavigationSuiteItemColors = NavigationSuiteDefaults.itemColors(
    navigationBarItemColors = NavigationBarItemDefaults.colors(
        indicatorColor = MaterialTheme.colorScheme.primaryContainer,
        selectedIconColor = MaterialTheme.colorScheme.onPrimaryContainer
    ),
)

NavigationSuiteScaffold(
    navigationSuiteItems = {
        AppDestinations.entries.forEach {
            item(
                icon = {
                    Icon(
                        it.icon,
                        contentDescription = stringResource(it.contentDescription)
                    )
                },
                label = { Text(stringResource(it.label)) },
                selected = it == currentDestination,
                onClick = { currentDestination = it },
                colors = myNavigationSuiteItemColors,
            )
        }
    },
) {
    // Content...
}
SampleNavigationSuiteScaffold.kt

Menyesuaikan jenis navigasi

Perilaku default NavigationSuiteScaffold mengubah UI navigasi berdasarkan ukuran jendela class. Namun, Anda mungkin ingin mengganti perilaku ini. Misalnya, jika aplikasi Anda menampilkan satu panel besar konten untuk feed, aplikasi bisa menggunakan navigasi permanen untuk jendela yang diperluas namun masih kembali ke perilaku default untuk class ukuran jendela rapat dan sedang:

val adaptiveInfo = currentWindowAdaptiveInfo()
val customNavSuiteType = with(adaptiveInfo) {
    if (windowSizeClass.windowWidthSizeClass == WindowWidthSizeClass.EXPANDED) {
        NavigationSuiteType.NavigationDrawer
    } else {
        NavigationSuiteScaffoldDefaults.calculateFromAdaptiveInfo(adaptiveInfo)
    }
}

NavigationSuiteScaffold(
    navigationSuiteItems = { /* ... */ },
    layoutType = customNavSuiteType,
) {
    // Content...
}
SampleNavigationSuiteScaffold.kt

Referensi lainnya

Lihat panduan Desain Material:

• Menu navigasi
• Kolom samping navigasi
• Panel navigasi

Lihat komponen library androidx.compose.material3 berikut:

• NavigationBar
• NavigationRail
• ModalNavigationDrawer
• PermanentNavigationDrawer