Melihat pratinjau UI dengan pratinjau composable

Composable ditentukan oleh fungsi dan dianotasi dengan @Composable:

@Composable
fun SimpleComposable() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

Untuk mengaktifkan pratinjau composable ini, buat composable lain, yang dianotasi dengan @Composable dan @Preview. Composable baru yang dianotasi ini sekarang berisi composable yang Anda buat di awal, SimpleComposable:

@Preview
@Composable
fun SimpleComposablePreview() {
    SimpleComposable()
}
AndroidStudioComposeSnippets.kt

Anotasi @Preview memberi tahu Android Studio bahwa composable harus ditampilkan dalam tampilan desain file ini. Anda dapat melihat live pembaruan pratinjau composable saat melakukan pengeditan.

Anda dapat menambahkan parameter secara manual dalam kode untuk menyesuaikan cara Android Studio merender @Preview. Anda bahkan dapat menambahkan anotasi @Preview ke beberapa kali untuk melihat pratinjau composable dengan properti yang berbeda.

Salah satu manfaat utama menggunakan composable @Preview adalah menghindari ketergantungan pada emulator di Android Studio. Anda dapat menyimpan proses memulai {i>startup<i} yang sarat memori emulator untuk perubahan tampilan dan nuansa akhir lainnya, serta kemampuan @Preview untuk melakukan dan menguji perubahan kode kecil dengan mudah.

Untuk memanfaatkan anotasi @Preview secara efektif, pastikan untuk menentukan layar dalam hal status yang diterima sebagai input output.

Tentukan @Preview Anda

Android Studio menawarkan beberapa fitur untuk memperluas pratinjau composable. Anda dapat mengubah desain penampung, berinteraksi dengan mereka, atau menerapkannya langsung ke emulator atau perangkat.

Dimensi

Secara default, dimensi @Preview dipilih secara otomatis untuk menggabungkan kontennya. Untuk menetapkan dimensi secara manual, tambahkan parameter heightDp dan widthDp. Mereka nilai sudah ditafsirkan sebagai dp, sehingga Anda tidak perlu menambahkan .dp mereka:

@Preview(widthDp = 50, heightDp = 50)
@Composable
fun SquareComposablePreview() {
    Box(Modifier.background(Color.Yellow)) {
        Text("Hello World")
    }
}
AndroidStudioComposeSnippets.kt

Pratinjau warna dinamis

Jika Anda telah mengaktifkan filter dinamis warna di aplikasi Anda, gunakan atribut wallpaper untuk beralih wallpaper dan melihat reaksi UI Anda terhadap pengguna yang berbeda wallpaper yang dipilih. Pilih dari berbagai tema wallpaper ditawarkan oleh Wallpaper . Fitur ini memerlukan Compose 1.4.0 atau yang lebih tinggi.

Gunakan dengan perangkat yang berbeda

Di Android Studio Flamingo, Anda dapat mengedit parameter device Pratinjau anotasi untuk menentukan konfigurasi composable Anda di perangkat yang berbeda.

Jika parameter perangkat memiliki string kosong (@Preview(device = "")), Anda dapat panggil pelengkapan otomatis dengan menekan Ctrl + Space. Kemudian, Anda dapat menetapkan nilai setiap parameter.

Dari pelengkapan otomatis, Anda dapat memilih opsi perangkat apa pun dari daftar, misalnya, @Preview(device = "id:pixel_4"). Atau, Anda dapat memasukkan perangkat kustom dengan memilih spec:width=px,height=px,dpi=int… untuk menyetel nilai individual setiap parameter.

Untuk menerapkan, tekan Enter, atau batalkan dengan Esc.

Jika Anda menetapkan nilai yang tidak valid, deklarasi akan digarisbawahi dengan warna merah dan perbaikan mungkin tersedia (Alt + Enter (⌥ + ⏎ untuk macOS) > Ganti dengan .... Inspeksi mencoba memberikan perbaikan yang paling mendekati tampilan input Anda.

Lokal

Untuk menguji berbagai lokal pengguna, tambahkan parameter locale:

@Preview(locale = "fr-rFR")
@Composable
fun DifferentLocaleComposablePreview() {
    Text(text = stringResource(R.string.greeting))
}
AndroidStudioComposeSnippets.kt

Menetapkan warna latar belakang

Secara default, composable Anda ditampilkan dengan latar belakang transparan. Untuk menambahkan latar belakang, tambahkan parameter showBackground dan backgroundColor. Tetap di Perlu diingat bahwa backgroundColor adalah Long ARGB, bukan Color nilai:

@Preview(showBackground = true, backgroundColor = 0xFF00FF00)
@Composable
fun WithGreenBackground() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

UI Sistem

Jika Anda perlu menampilkan status dan panel tindakan di dalam pratinjau, tambahkan parameter showSystemUi:

@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

Mode UI

Parameter uiMode dapat menggunakan Configuration.UI_* dan memungkinkan Anda mengubah perilaku pratinjau yang sesuai. Misalnya, Anda dapat menyetel pratinjau ke Mode Malam untuk melihat reaksi tema.

LocalInspectionMode

Anda dapat membaca dari LocalInspectionMode CompositionLocal untuk melihat apakah composable dirender dalam pratinjau (di dalam komponen yang dapat diperiksa). Jika komposisi dirender dalam pratinjau, LocalInspectionMode.current bernilai true. Ini informasi memungkinkan Anda menyesuaikan pratinjau; misalnya, Anda dapat menampilkan gambar {i>placeholder<i} di jendela pratinjau alih-alih menampilkan data aktual.

Dengan cara ini, Anda juga dapat mengatasi batasan. Sebagai contoh, menampilkan data sampel, bukan memanggil permintaan jaringan.

@Composable
fun GreetingScreen(name: String) {
    if (LocalInspectionMode.current) {
        // Show this text in a preview window:
        Text("Hello preview user!")
    } else {
        // Show this text in the app:
        Text("Hello $name!")
    }
}
AndroidStudioComposeSnippets.kt

Berinteraksi dengan @Preview

Android Studio menyediakan fitur yang memungkinkan Anda berinteraksi dengan pratinjau. Interaksi ini membantu Anda memahami pratinjau perilaku runtime dan memungkinkan Anda menavigasi UI dengan lebih baik menggunakan pratinjau.

Mode interaktif

Mode interaktif memungkinkan Anda berinteraksi dengan pratinjau dengan cara yang sama seperti yang Anda lakukan pada perangkat yang menjalankan program Anda, seperti ponsel atau tablet. Mode interaktif diisolasi di lingkungan sandbox (artinya, diisolasi dari pratinjau lain), di mana Anda dapat mengklik elemen dan memasukkan input pengguna dalam pratinjau. Ini adalah untuk menguji berbagai status, gestur, dan bahkan animasi composable.

Navigasi kode dan kerangka composable

Anda dapat mengarahkan kursor ke pratinjau untuk melihat garis besar dari composable yang ada di dalamnya. Mengklik outline composable akan memicu tampilan editor Anda untuk menuju ke definisinya.

Jalankan pratinjau

Anda dapat menjalankan @Preview tertentu di emulator atau perangkat fisik. Tujuan pratinjau di-deploy dalam aplikasi project yang sama dengan Activity baru, sehingga memiliki konteks dan izin yang sama. Anda tidak perlu menulis kode boilerplate yang meminta izin jika sudah diberikan.

Klik ikon Run Preview di samping anotasi @Preview atau di bagian atas pratinjau, dan Android Studio akan men-deploy @Preview tersebut ke emulator atau perangkat yang terhubung.

Salin render @Preview

Setiap pratinjau yang dirender dapat disalin sebagai image dengan mengklik kanan pada image.

Beberapa pratinjau anotasi @Preview yang sama

Anda dapat menampilkan beberapa versi composable @Preview yang sama dengan spesifikasi yang berbeda, atau parameter berbeda yang diteruskan ke composable. Ini Anda dapat mengurangi kode {i>boilerplate<i} yang perlu Anda tulis sebaliknya.

Template multipratinjau

androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+ memperkenalkan Multipratinjau Template API: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark, dan @PreviewDynamicColors, sehingga dengan satu anotasi, Anda dapat melihat pratinjau UI Compose dalam skenario umum.

Membuat anotasi multipratinjau kustom

Dengan multipratinjau, Anda dapat menentukan class anotasi yang sudah memiliki beberapa anotasi @Preview dengan konfigurasi berbeda. Menambahkan anotasi ini ke fungsi composable secara otomatis merender semua pratinjau yang berbeda dengan sekali. Misalnya, Anda dapat menggunakan anotasi ini untuk melihat pratinjau beberapa perangkat, ukuran font, atau tema secara bersamaan tanpa perlu mengulangi definisi tersebut untuk setiap satu composable.

Mulai dengan membuat class anotasi kustom Anda sendiri:

@Preview(
    name = "small font",
    group = "font scales",
    fontScale = 0.5f
)
@Preview(
    name = "large font",
    group = "font scales",
    fontScale = 1.5f
)
annotation class FontScalePreviews
AndroidStudioComposeSnippets.kt

Anda dapat menggunakan anotasi kustom ini untuk composable pratinjau:

@FontScalePreviews
@Composable
fun HelloWorldPreview() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

Anda dapat menggabungkan beberapa anotasi multipratinjau dan anotasi pratinjau normal untuk membuat kumpulan pratinjau yang lebih lengkap. Menggabungkan anotasi multipratinjau bukan berarti semua kombinasi yang berbeda akan ditampilkan. Sebaliknya, setiap anotasi multipratinjau bertindak secara independen dan hanya merender variannya sendiri.

@Preview(
    name = "Spanish",
    group = "locale",
    locale = "es"
)
@FontScalePreviews
annotation class CombinedPreviews

@CombinedPreviews
@Composable
fun HelloWorldPreview2() {
    MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } }
}
AndroidStudioComposeSnippets.kt

Sifat campuran dan pencocokan multipratinjau-- dan pratinjau normal!-- memungkinkan Anda membuat secara komprehensif menguji banyak properti dari proyek berskala lebih besar.

@Preview dan set data besar

Sangat sering, kebutuhan muncul karena Anda harus meneruskan set data besar ke composable pratinjau. Untuk melakukannya, cukup teruskan data sampel ke fungsi Pratinjau Composable dengan menambahkan parameter dengan elemen @PreviewParameter anotasi.

@Preview
@Composable
fun UserProfilePreview(
    @PreviewParameter(UserPreviewParameterProvider::class) user: User
) {
    UserProfile(user)
}
AndroidStudioComposeSnippets.kt

Untuk menyediakan data contoh, buat class yang mengimplementasikan PreviewParameterProvider dan menampilkan data sampel sebagai urutan.

class UserPreviewParameterProvider : PreviewParameterProvider<User> {
    override val values = sequenceOf(
        User("Elise"),
        User("Frank"),
        User("Julia")
    )
}
AndroidStudioComposeSnippets.kt

Tindakan ini merender satu pratinjau per elemen data dalam urutan:

Anda dapat menggunakan class penyedia yang sama untuk beberapa pratinjau. Jika perlu, batasi jumlah pratinjau dengan menyetel parameter batas.

@Preview
@Composable
fun UserProfilePreview2(
    @PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User
) {
    UserProfile(user)
}
AndroidStudioComposeSnippets.kt

Batasan dan praktik terbaik

Android Studio menjalankan kode pratinjau langsung di area pratinjau. Tidak perlu menjalankan emulator atau perangkat fisik karena memanfaatkan bagian dari framework Android yang disebut Layoutlib. Layoutlib adalah kustom kerangka kerja Android yang dirancang untuk berjalan di luar perangkat Android. Tujuan tujuan library ini adalah untuk menyediakan pratinjau tata letak di Android Studio yang sangat dekat dengan proses rendering pada perangkat.

Pratinjau batasan

Karena cara pratinjau dirender dalam Android Studio, pratinjau ringan dan tidak membutuhkan seluruh kerangka kerja Android untuk merendernya. Namun, hal ini memiliki batasan berikut:

• Tidak ada akses jaringan
• Tidak ada akses file
• Beberapa API Context mungkin tidak sepenuhnya tersedia

Pratinjau dan ViewModels

Pratinjau dibatasi saat menggunakan ViewModel dalam composable. Sistem pratinjau tidak mampu menyusun semua yang diteruskan ke ViewModel, seperti repositori, kasus penggunaan, pengelola, atau yang serupa. Selain itu, jika ViewModel Anda berpartisipasi dalam injeksi dependensi (seperti seperti halnya Hilt), sistem pratinjau tidak dapat mem-build seluruh dependensi untuk menyusun ViewModel.

Saat Anda mencoba melihat pratinjau composable dengan ViewModel, Android Studio akan menampilkan error saat merender composable tertentu:

Jika ingin melihat pratinjau composable yang menggunakan ViewModel, Anda harus membuat composable lain dengan parameter dari ViewModel yang diteruskan sebagai argumen composable. Dengan cara ini, Anda tidak perlu melihat pratinjau composable yang menggunakan ViewModel.

@Composable
fun AuthorColumn(viewModel: AuthorViewModel = viewModel()) {
  AuthorColumn(
    name = viewModel.authorName,
    // ViewModel sends the network requests and makes posts available as a state
    posts = viewModel.posts
  )
}

@Preview
@Composable
fun AuthorScreenPreview(
  // You can use some sample data to preview your composable without the need to construct the ViewModel
  name: String = sampleAuthor.name,
  posts: List<Post> = samplePosts[sampleAuthor]
) {
  AuthorColumn(...) {
    name = NameLabel(name),
    posts = PostsList(posts)
  }
}

Class anotasi @Preview

Anda dapat menekan 'ctrl atau ⌘ + klik' kapan saja anotasi @Preview di Android Studio untuk daftar lengkap parameter yang dapat disesuaikan saat menyesuaikan pratinjau.

annotation class Preview(
    val name: String = "",
    val group: String = "",
    @IntRange(from = 1) val apiLevel: Int = -1,
    val widthDp: Int = -1,
    val heightDp: Int = -1,
    val locale: String = "",
    @FloatRange(from = 0.01) val fontScale: Float = 1f,
    val showSystemUi: Boolean = false,
    val showBackground: Boolean = false,
    val backgroundColor: Long = 0,
    @UiMode val uiMode: Int = 0,
    @Device val device: String = Devices.DEFAULT,
    @Wallpaper val wallpaper: Int = Wallpapers.NONE,
)
AndroidStudioComposeSnippets.kt

Referensi lainnya

Untuk membaca lebih lanjut cara Android Studio mempromosikan kemudahan penggunaan @Preview, serta pelajari Tips Alat lainnya, lihat blog Compose Alat.

Direkomendasikan untuk Anda

• Catatan: teks link ditampilkan saat JavaScript nonaktif
• Data yang dicakup secara lokal dengan CompositionLocal
• Desain Material 2 di Compose
• Menggunakan View di Compose