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ı
Context
API'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