Composable ditentukan oleh fungsi dan dianotasi dengan @Composable
:
@Composable fun SimpleComposable() { Text("Hello World") }
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() }
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 dari
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") } }
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)) }
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") }
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") }
![Jendela pratinjau yang menampilkan aktivitas dengan status dan panel tindakan.](https://developer.android.google.cn/static/develop/ui/compose/images/tooling-decorated-preview.png?authuser=19&hl=id)
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!") } }
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
Anda dapat menggunakan anotasi kustom ini untuk composable pratinjau:
@FontScalePreviews @Composable fun HelloWorldPreview() { Text("Hello World") }
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)) } } }
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) }
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") ) }
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) }
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, )
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