composable, bir işlevle tanımlanır ve @Composable ile not eklenir:
@Composable
fun SimpleComposable() {
Text("Hello World")
}
Bu composable'ın önizlemesini etkinleştirmek için @Composable ve @Preview ile ek açıklamalı 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üncellemeleri görebilirsiniz.
Android Studio'nun @Preview öğesini oluşturma şeklini özelleştirmek için kodunuza manuel olarak parametreler ekleyebilirsiniz. Hatta @Preview ek açıklamasını, bir composable'ı farklı özelliklerle önizlemek için aynı işleve birden çok kez ekleyebilirsiniz.
@Preview composable'ları kullanmanın başlıca avantajlarından biri, Android Studio'da emülatöre bağımlı kalmamaktır. Görünüm ve izlenimde daha fazla değişiklik yapmak, @Preview ürününün küçük kod değişikliklerini kolayca yapıp test edebilmesi için emülatörün belleği yoğun bir şekilde başlatılmasını kaydedebilirsiniz.
@Preview ek açıklamaları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 önizlemelerin kapsamını genişleten bazı özellikler sunar. Container tasarımlarını değiştirebilir, kullanıcılarla etkileşime geçebilir veya doğrudan bir emülatöre ya da cihaza dağıtabilirsiniz.
Boyutlar
Varsayılan olarak, @Preview boyutu içeriğini sarmalamak 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 rengi etkinleştirdiyseniz duvar kağıtlarını değiştirmek ve kullanıcı arayüzünüzün farklı kullanıcıların seçtiği duvar kağıdına nasıl tepki verdiğini görmek için wallpaper özelliğini kullanı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 daha sonraki bir sürümü gerektirir.
Farklı cihazlarla kullanın
Android Studio Flamingo'da, composable'larınızın farklı cihazlarda yapılandırmaları tanımlamak için Önizleme ek açıklamasının device parametresini düzenleyebilirsiniz.
Cihaz parametresinde boş bir dize olduğunda (@Preview(device = "")) Ctrl + Space tuşlarına basarak otomatik tamamlamayı başlatabilirsiniz. Daha sonra, her bir parametrenin
değerlerini ayarlayabilirsiniz.
Otomatik tamamlama bölümünde listeden herhangi bir cihaz seçeneğini belirleyebilirsiniz. Örneğin,
@Preview(device = "id:pixel_4"). Alternatif olarak her bir parametrenin değerini ayrı ayrı belirlemek 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 düzeltme yapılabilir (Alt + Enter (⌥ + CmdOS 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 belirle
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 bir 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 önizlemede durum ve işlem çubuklarını görüntülemeniz gerekirse showSystemUi parametresini ekleyin:
@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
Text("Hello World")
}
kullanıcı arayüzü modu
uiMode parametresi, Configuration.UI_* sabit değerlerinden 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
composable'ın önizlemede (incelenebilir bir bileşenin içinde) oluşturulup oluşturulmadığını görmek için LocalInspectionMode
CompositionLocal içindeki metni okuyabilirsiniz. Beste önizlemede oluşturulursa LocalInspectionMode.current öğesi 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 giderebilirsiniz. Örneğin, ağ isteğini çağırmak yerine örnek verileri gösterebilirsiniz.
@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 cihazınızla etkileşimde bulunun
Android Studio, tanımladığınız önizlemelerle etkileşimde bulunmanıza olanak tanıyan özellikler sağlar. Bu etkileşim, önizlemelerinizin çalışma zamanı davranışını anlamanıza yardımcı olur ve önizlemeleri kullanarak kullanıcı arayüzünüzde daha iyi gezinmenize olanak tanır.
Etkileşimli mod
Etkileşimli mod, programınızı çalıştıran cihazlarda (ör. telefon veya tablet) olduğu gibi önizlemeyle etkileşimde bulunmanıza olanak tanır. Etkileşimli mod, öğeleri tıklayabileceğiniz ve önizlemede kullanıcı girişini girebileceğiniz bir korumalı alan ortamında (diğer bir deyişle diğer önizlemelerden izoledir) yalıtılmıştır. Bu, composable'ın farklı durumlarını, hareketleri, hatta animasyonlarını test etmenin hızlı bir yoludur.
Kodda gezinme ve composable anahatlar
Önizlemenin üzerine gelerek içindeki composable'ların ana hatlarını görebilirsiniz. Oluşturulabilir bir ana hatlara tıkladığınızda düzenleyici görünümünüz bu taslağın tanımına gidebilir.
Önizlemeyi çalıştır
Belirli bir @Preview eklentisini bir emülatörde veya fiziksel bir cihazda çalıştırabilirsiniz. Önizleme, aynı proje uygulamasına yeni bir Activity ile dağıtılır. Böylece aynı bağlamı ve izinleri paylaşır. Size daha önce izin verildiyse izin isteyen standart 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.
@Preview oluşturmayı 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ı özelliklere sahip birden çok sürümünü veya composable'a iletilen farklı parametreleri sergileyebilirsiniz. Bu sayede, aksi takdirde yazmanız gereken standart kodu azaltabilirsiniz.
Çoklu önizleme şablonları
androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+, Çoklu Önizleme API şablonlarını kullanıma sunar: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark ve @PreviewDynamicColors. Böylece sık karşılaşılan senaryolarda tek bir ek açıklama ile Compose kullanıcı arayüzünüzü önizleyebilirsiniz.
Özel çoklu önizleme ek açıklamaları oluşturma
Çoklu önizlemeyle, farklı yapılandırmalara sahip birden çok @Preview ek açıklamasına sahip bir ek açıklama sınıfı tanımlayabilirsiniz. Bu ek açıklamanın bir composable işleve eklenmesi, farklı önizlemelerin tümünü aynı anda otomatik olarak oluşturur. Örneğin, her composable için bu tanımları tekrarlamadan birden çok cihazı, yazı tipi boyutunu veya temayı aynı anda ö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 birden çok çoklu önizleme ek açıklamasını ve normal önizleme ek açıklaması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 bir çoklu önizleme ek açıklaması bağımsız hareket eder 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 önizlemenin ve normal önizlemenin karıştırma ve eşleştirme yapısı, 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
Çoğu zaman, composable önizlemenize büyük bir veri kümesi iletmeniz gereken durumlar ortaya çıkar. Bunu yapmak için @PreviewParameter ek açıklamasına sahip bir parametre ekleyerek örnek verileri bir Composable Preview 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ıra 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 çok önizleme için aynı sağlayıcı sınıfını kullanabilirsiniz. Gerekirse limit parametresini ayarlayarak önizleme sayısını sınırlayın.
@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. Layoutlib adlı Android çerçevesinin taşınan bir parçasını kullandığından, emülatörün veya fiziksel cihazın çalıştırılmasını gerektirmez. Layoutlib, Android çerçevesinin, Android cihazlar dışında çalışacak şekilde tasarlanmış özel bir sürümüdür. Kitaplığın amacı, Android Studio'da, cihazlarda oluşturulmasına çok yakın bir düzenin önizlemesini sunmaktır.
Önizleme sınırlamaları
Önizlemeler, Android Studio'da oluşturulma biçiminden dolayı hafiftir ve onları oluşturmak için tüm Android çerçevesinin kullanılmasını gerektirmez. Ancak, bunun için aşağıdaki sınırlamalar geçerlidir:
- Ağ erişimi yok
- Dosya erişimi yok
- Bazı
ContextAPI'leri tam olarak kullanılamayabilir
Önizlemeler ve ViewModels
ViewModel bir composable içinde kullanıldığında önizlemeler sınırlıdır. Önizleme sistemi; depolar, kullanım alanları, yöneticiler vb. gibi bir ViewModel parametresine iletilen tüm parametreleri oluşturamaz. Ayrıca, ViewModel öğeniz bağımlılık ekleme işlemine katılırsa (Hilt ile olduğu gibi) önizleme sistemi, ViewModel öğesini oluşturmak için bağımlılık grafiğinin tamamını oluşturamazsınız.
Bir composable'ı ViewModel ile önizlemeye çalıştığınızda Android Studio belirli bir composable'ı oluştururken hata mesajı gösterir:
ViewModel kullanan bir composable'ı önizlemek isterseniz ViewModel parametresinden composable'ın bağımsız değişkenleri olarak iletilen parametrelerle başka bir composable oluşturmanız gerekir. Böylece, 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)
}
}
Ek açıklama sınıfı @Preview
Önizlemenizi özelleştirirken ayarlanabilecek parametrelerin tam listesini görmek için Android Studio'da dilediğiniz zaman "ctrl veya ⌘ tuşuna basarak" @Preview ek açıklamasını 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 desteklediğiyle ilgili daha fazla bilgi edinmek ve Araçlar hakkında daha fazla ipucu öğrenmek için Oluşturma Araçları bloguna bakın.
Sizin için önerilenler
- Not: Bağlantı metni JavaScript kapalıyken görüntülenir
- CompositionLocal ile yerel olarak kapsama alınmış veriler
- Oluşturma işleminde Materyal Tasarım 2
- Oluşturma işleminde görünümleri kullanma