Bir composable, işlev tarafından tanımlanır ve @Composable ile ek açıklama olarak belirtilir:
@Composable
fun SimpleComposable() {
Text("Hello World")
}
Bu composable'ın önizlemesini etkinleştirmek için @Composable ve @Preview öğelerini içeren başka bir composable oluşturun. Bu yeni ve ek açıklamalı composable artık başlangıçta oluşturduğunuz composable'ı (SimpleComposable) içeriyor:
@Preview
@Composable
fun SimpleComposablePreview() {
SimpleComposable()
}
@Preview ek açıklaması, Android Studio'ya bu composable'ın, bu dosyanın tasarım görünümünde gösterilmesi gerektiğini bildirir. Düzenlemelerinizi yaparken composable önizlemenizde
canlı güncellemeler görebilirsiniz.
Android Studio'nun @Preview oluşturma şeklini özelleştirmek için parametreleri kodunuza manuel olarak ekleyebilirsiniz. Farklı özelliklere sahip bir composable'ı önizlemek için @Preview ek açıklamasını aynı işleve birden çok kez ekleyebilirsiniz.
@Preview composable'ları kullanmanın temel avantajlarından biri, Android Studio'daki emülatöre bağlı kalmaktan kaçınmaktır. Daha son görünüm ve izlenim değişiklikleri yapmak ve @Preview ürününün küçük kod değişikliklerini kolayca yapıp test edebilmesi için emülatörün bellek açısından yoğun şekilde başlatılmasını kaydedebilirsiniz.
@Preview ek açıklamasından en etkili şekilde yararlanmak için ekranlarınızı giriş olarak aldığı durum ve sağladığı etkinlikler açısından tanımladığınızdan emin olun.
@Preview tanımlayın
Android Studio, composable önizlemeleri genişletmek için bazı özellikler sunar. Container tasarımlarını değiştirebilir, bunlarla etkileşime geçebilir veya doğrudan bir emülatöre ya da cihaza dağıtabilirsiniz.
Boyutlar
Varsayılan olarak @Preview boyutları, içeriğinin sarmalanması için otomatik olarak seçilir.
Boyutları manuel olarak ayarlamak için heightDp ve widthDp parametrelerini ekleyin. Bu değerler zaten dp olarak yorumlandığından bunlara .dp eklemeniz gerekmez:
@Preview(widthDp = 50, heightDp = 50)
@Composable
fun SquareComposablePreview() {
Box(Modifier.background(Color.Yellow)) {
Text("Hello World")
}
}
Dinamik renk önizlemesi
Uygulamanızda dinamik renk özelliğini etkinleştirdiyseniz wallpaper özelliğini kullanarak duvar kağıtlarını değiştirin ve kullanıcı arayüzünüzün, farklı kullanıcıların seçtiği duvar kağıtlarına nasıl tepki verdiğini görün. Wallpaper sınıfının sunduğu farklı duvar kağıdı temaları arasından seçim yapın. Bu özellik Compose 1.4.0 veya sonraki sürümünü gerektirir.
Farklı cihazlarla kullanma
Android Studio Flamingo'da, farklı cihazlardaki composable'larınıza yönelik yapılandırmaları tanımlamak için Önizleme ek açıklamasının device parametresini düzenleyebilirsiniz.
Cihaz parametresinde boş bir dize (@Preview(device = "")) olduğunda Ctrl + Space tuşlarına basarak otomatik tamamlamayı çağırabilirsiniz. Ardından, her bir parametrenin
değerlerini ayarlayabilirsiniz.
Otomatik tamamlamada, listeden herhangi bir cihaz seçeneğini belirleyebilirsiniz (ör. @Preview(device = "id:pixel_4")). Alternatif olarak, her parametrenin değerlerini ayrı ayrı ayarlamak için spec:width=px,height=px,dpi=int… seçeneğini belirleyerek özel bir cihaz girebilirsiniz.
Uygulamak için Enter tuşuna basın veya Esc ile iptal edin.
Geçersiz bir değer ayarlarsanız bildirimin altı kırmızıyla çizilir ve bir düzeltme mevcut olabilir (Alt + Enter (⌥OS için ⌥+) > Değiştir .... İnceleme, girişinize en yakın düzeltmeyi sağlamaya çalışır.
Yerel ayar
Farklı kullanıcı yerel ayarlarını test etmek için locale parametresini ekleyin:
@Preview(locale = "fr-rFR")
@Composable
fun DifferentLocaleComposablePreview() {
Text(text = stringResource(R.string.greeting))
}
Arka plan rengini ayarla
Varsayılan olarak, composable'ınız şeffaf bir arka planla görüntülenir. Arka plan eklemek için showBackground ve backgroundColor parametrelerini ekleyin. backgroundColor değerinin Color değeri değil, ARGB Long olduğunu unutmayın:
@Preview(showBackground = true, backgroundColor = 0xFF00FF00)
@Composable
fun WithGreenBackground() {
Text("Hello World")
}
Sistem Arayüzü
Bir önizlemenin içinde durumu ve işlem çubuklarını görüntülemeniz gerekiyorsa showSystemUi parametresini ekleyin:
@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
Text("Hello World")
}
kullanıcı arayüzü modu
uiMode parametresi, Configuration.UI_* sabitlerinden herhangi birini alabilir ve önizlemenin davranışını buna göre değiştirmenize olanak tanır. Örneğin, temanın nasıl tepki verdiğini görmek için önizlemeyi Gece Modu'na ayarlayabilirsiniz.
LocalInspectionMode
Bir composable'ın önizlemede (incelenemeyen bir bileşen içinde) oluşturulup oluşturulmadığını öğrenmek için LocalInspectionMode
CompositionLocal üzerinden bilgi edinebilirsiniz. Beste önizlemede oluşturulursa LocalInspectionMode.current, true olarak değerlendirilir. Bu bilgiler önizlemenizi özelleştirmenize olanak tanır. Örneğin, önizleme penceresinde gerçek verileri göstermek yerine bir yer tutucu resim gösterebilirsiniz.
Bu şekilde sınırlamaları da çözebilirsiniz. Örneğin, ağ isteğini çağırmak yerine örnek veri gösterme.
@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!")
}
}
@Preview ile etkileşim kurun
Android Studio, tanımlı önizlemelerinizle etkileşimde bulunmanıza olanak tanıyan özellikler sunar. Bu etkileşim, önizlemelerinizin çalışma zamanı davranışını anlamanıza yardımcı olur ve önizlemelerle kullanıcı arayüzünüzde daha iyi gezinmenizi sağlar.
Etkileşimli mod
Etkileşimli mod, programınızı çalıştıran bir cihazda (ör. telefon veya tablet) olduğu gibi bir önizlemeyle etkileşimde bulunmanıza olanak tanır. Etkileşimli mod, diğer önizlemelerden ayrı bir korumalı alan ortamında izole edilir. Burada, öğeleri tıklayıp önizlemede kullanıcı girişini girebilirsiniz. Bu özellik, composable'ınızın farklı durumlarını, hareketleri, hatta animasyonlarını test etmenin hızlı bir yoludur.
Kodda gezinme ve composable ana hatlar
Bir önizlemenin üzerine gelerek içindeki composable'ların ana hatlarını görebilirsiniz. Oluşturulabilir bir ana hat tıklandığında, tanımına gitmek üzere düzenleyici görünümünüz tetiklenir.
Önizlemeyi çalıştır
Bir emülatörde veya fiziksel cihazda belirli bir @Preview çalıştırabilirsiniz. Önizleme, yeni bir Activity ile aynı proje uygulaması içinde dağıtılır. Böylece aynı bağlamı ve izinleri paylaşır. Daha önce veliyse izin isteyen ortak kod yazmanıza gerek yoktur.
@Preview ek açıklamasının yanındaki veya önizlemenin üst kısmındaki Önizlemeyi Çalıştır simgesini 
tıklayın. Android Studio bu @Preview öğesini bağlı cihazınıza veya emülatörünüze dağıtır.
Oluşturulan @Preview değerini kopyala
Oluşturulan her önizleme, sağ tıklanarak resim olarak kopyalanabilir.
Aynı @Preview ek açıklamasının birden çok önizlemesi
Aynı @Preview composable'ın farklı spesifikasyonlarla veya composable'a iletilen farklı parametrelerle birden fazla versiyonunu sergileyebilirsiniz. Bu sayede, aksi halde yazmanız gereken standart kodu azaltabilirsiniz.
Çoklu önizleme şablonları
androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+ sürümünde @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark ve @PreviewDynamicColors adlı Çoklu Önizleme API şablonları kullanıma sunuldu. Böylece, sık karşılaşılan senaryolarda Compose kullanıcı arayüzünüzü tek bir ek notla önizleyebilirsiniz.
Özel çoklu önizleme ek açıklamaları oluşturma
Çoklu önizleme sayesinde, farklı yapılandırmalara sahip birden fazla @Preview ek açıklamasına sahip bir ek açıklama sınıfı tanımlayabilirsiniz. Bu ek açıklama, bir composable işleve eklendiğinde tüm farklı önizlemeler otomatik olarak aynı anda oluşturulur. Örneğin, bu tanımları her composable için tekrarlamadan aynı anda birden fazla cihazı, yazı tipi boyutunu veya temayı önizlemek için bu ek açıklamayı kullanabilirsiniz.
Kendi özel ek açıklama sınıfınızı oluşturarak başlayın:
@Preview(
name = "small font",
group = "font scales",
fontScale = 0.5f
)
@Preview(
name = "large font",
group = "font scales",
fontScale = 1.5f
)
annotation class FontScalePreviews
Önizleme composable'larınız için bu özel ek açıklamayı kullanabilirsiniz:
@FontScalePreviews
@Composable
fun HelloWorldPreview() {
Text("Hello World")
}
Daha kapsamlı bir önizleme grubu oluşturmak için çoklu önizleme ek açıklamalarını ve normal önizleme ek açıklamalarını birleştirebilirsiniz. Çoklu önizleme ek açıklamalarının birleştirilmesi, tüm farklı kombinasyonların gösterileceği anlamına gelmez. Bunun yerine, her çoklu önizleme ek açıklaması bağımsız olarak çalışır ve yalnızca kendi varyantlarını oluşturur.
@Preview(
name = "Spanish",
group = "locale",
locale = "es"
)
@FontScalePreviews
annotation class CombinedPreviews
@CombinedPreviews
@Composable
fun HelloWorldPreview2() {
MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } }
}
Çoklu önizleme (ve normal önizleme!) özellikleri, daha büyük ölçekli projelerin birçok özelliğini daha kapsamlı bir şekilde test etmenize olanak tanır.
@Preview ve büyük veri kümeleri
Genellikle, composable önizlemenize büyük bir veri kümesi aktarmanız gereken bir ihtiyaç ortaya çıkar. Bunu yapmak için @PreviewParameter ek açıklamasına sahip bir parametre ekleyerek örnek verileri bir Oluşturulabilir Önizleme işlevine aktarmanız yeterlidir.
@Preview
@Composable
fun UserProfilePreview(
@PreviewParameter(UserPreviewParameterProvider::class) user: User
) {
UserProfile(user)
}
Örnek verileri sağlamak için PreviewParameterProvider uygulayan ve örnek verileri sıralı olarak döndüren bir sınıf oluşturun.
class UserPreviewParameterProvider : PreviewParameterProvider<User> {
override val values = sequenceOf(
User("Elise"),
User("Frank"),
User("Julia")
)
}
Bu işlem, dizideki her veri öğesi için bir önizleme oluşturur:
Birden fazla önizleme için aynı sağlayıcı sınıfını kullanabilirsiniz. Gerekirse "limit" parametresini ayarlayarak önizleme sayısını sınırlandırabilirsiniz.
@Preview
@Composable
fun UserProfilePreview2(
@PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User
) {
UserProfile(user)
}
Sınırlamalar ve en iyi uygulamalar
Android Studio, önizleme kodunu doğrudan önizleme alanında yürütür. Android çerçevesinin Layoutlib adlı taşınan bir kısmından yararlandığı için emülatör veya fiziksel cihaz çalıştırmayı gerektirmez. Layoutlib, Android çerçevesinin Android cihazların dışında çalışacak şekilde tasarlanmış özel bir sürümüdür. Kitaplığın amacı, Android Studio'da, cihazlarda oluşturulmaya çok yakın olan bir düzenin önizlemesini sağlamaktır.
Önizleme sınırlamaları
Önizlemelerin Android Studio'da oluşturulma şeklinden dolayı hafiftirler ve oluşturmak için tüm Android çerçevesinin kullanılmasını gerektirmezler. Ancak, bu durum aşağıdaki sınırlamalara tabidir:
- Ağ erişimi yok
- Dosya erişimi yok
- Bazı
ContextAPI'leri tam olarak kullanılamayabilir
Önizlemeler ve ViewModels
Bir composable içinde ViewModel kullanılırken önizlemeler sınırlıdır. Önizleme sistemi, bir ViewModel öğesine iletilen parametrelerin tümünü (ör. depolar, kullanım alanları, yöneticiler vb.) oluşturamaz. Ayrıca ViewModel öğeniz bağımlılık eklemede yer alıyorsa (Hilt gibi) önizleme sistemi, ViewModel oluşturmak için bağımlılık grafiğinin tamamını derleyemez.
Bir composable'ı ViewModel ile önizlemeye çalıştığınızda, Android Studio söz konusu composable'ı oluştururken hata gösterir:
ViewModel kullanan bir composable'ı önizlemek istiyorsanız ViewModel içindeki parametrelerin, composable'ın bağımsız değişkenleri olarak iletildiği başka bir composable oluşturmanız gerekir. Bu şekilde, ViewModel öğesini kullanan composable'ı önizlemeniz gerekmez.
@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)
}
}
@Preview ek açıklama sınıfı
Önizlemenizi özelleştirirken ayarlanabilecek parametrelerin tam listesi için istediğiniz zaman Android Studio'da @Preview ek açıklamasını "ctrl veya ⌘" tuşlarına basarak tıklayabilirsiniz.
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,
)
Ek kaynaklar
Android Studio'nun @Preview kullanım kolaylığını nasıl sunduğu hakkında daha fazla bilgi edinmek ve Araç
ipuçlarını öğrenmek için Oluşturma Aracı'na göz atın.
Sizin için önerilenler
- Not: JavaScript kapalıyken bağlantı metni gösterilir
- CompositionLocal ile yerel kapsamlı veriler
- Compose'da Materyal Tasarım 2
- Compose'da Görünümleri kullanma