Oluşturulabilir önizlemelerle kullanıcı arayüzünüzü önizleme

Bir composable, bir işlev tarafından tanımlanır ve @Composable ile ek açıklamaya sahiptir:

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

Bu derlemenin önizlemesini etkinleştirmek için @Composable ve @Preview ile ek açıklama içeren başka bir derleme oluşturun. Bu yeni, ek açıklamalı derlenebilir öğe artık başlangıçta oluşturduğunuz derlenebilir öğeyi (SimpleComposable) içerir:

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

@Preview ek açıklaması, Android Studio'ya bu derlenebilir öğenin bu dosyanın tasarım görünümünde gösterilmesi gerektiğini bildirir. Düzenlemelerinizi yaparken, derlenebilir önizlemenizde yapılan canlı güncellemeleri görebilirsiniz.

Android Studio'nun @Preview öğesini oluşturma şeklini özelleştirmek için kodunuza manuel olarak parametreler ekleyebilirsiniz. Hatta bir bileşeni farklı özelliklerle önizlemek için @Preview ek açıklamasını aynı işleve birden çok kez ekleyebilirsiniz.

@Preview bileşenlerini kullanmanın başlıca avantajlarından biri, Android Studio'daki emülatöre bağımlı olmaktan kaçınmaktır. Daha fazla son görünüm ve his değişikliği yapmak için emülatörde bellek açısından ağır olan başlatma işlemini kaydedebilir ve @Preview'ın küçük kod değişikliklerini kolayca yapıp test etme özelliğinden yararlanabilirsiniz.

@Preview ek açıklamalarından en iyi şekilde yararlanmak için ekranlarınızı, giriş olarak aldığı durum ve oluşturduğu etkinlikler açısından tanımladığınızdan emin olun.

@Preview tanımlayın

Android Studio, birleştirilebilir önizlemeleri genişletmek için bazı özellikler sunar. Container tasarımlarını değiştirebilir, onlarla etkileşime geçebilir veya doğrudan bir emülatöre ya da cihaza dağıtabilirsiniz.

Boyutlar

Varsayılan olarak, içeriğini sarmalamak için @Preview boyutları 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")
    }
}
AndroidStudioComposeSnippets.kt

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 için Compose 1.4.0 veya üzeri sürümler gereklidir.

Farklı cihazlarla kullanma

Android Studio Flamingo'da, farklı cihazlardaki bileşenlerinizin yapılandırmalarını tanımlamak için Önizleme ek açıklamaları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 tamamlama listesinden herhangi bir cihaz seçeneğini (ör. @Preview(device = "id:pixel_4")) belirleyebilirsiniz. Alternatif olarak, her parametrenin değerlerini ayrı ayrı ayarlamak için spec:width=px,height=px,dpi=int…'ü seçerek özel bir cihaz girebilirsiniz.

Uygulamak için Enter tuşuna basın veya Esc tuşuyla iptal edin.

Geçersiz bir değer belirlerseniz bildirim kırmızıyla altı çizilir ve düzeltme yapılabilir (Alt + Enter (MacOS için ⌥ + ⏎) > Şununla 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))
}
AndroidStudioComposeSnippets.kt

Arka plan rengini ayarlama

Birleştirilebilir öğeniz varsayılan olarak şeffaf bir arka planla gösterilir. 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")
}
AndroidStudioComposeSnippets.kt

Sistem Arayüzü

Bir önizlemede durum ve işlem çubuklarını görüntülemeniz gerekiyorsa showSystemUi parametresini ekleyin:

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

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

Birleştirilebilir öğenin önizlemede (denetlenebilir bir bileşenin içinde) oluşturulup oluşturulmadığını görmek için LocalInspectionMode CompositionLocal değerini okuyabilirsiniz. Beste önizlemede oluşturulursa LocalInspectionMode.current, true olarak değerlendirilir. Bu bilgiler, önizlemenizi özelleştirmenize olanak tanır. Örneğin, gerçek veriler yerine önizleme penceresinde 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!")
    }
}
AndroidStudioComposeSnippets.kt

@Preview ile etkileşim kurun

Android Studio, tanımladığınız önizlemelerle etkileşim kurmanıza olanak tanıyan özellikler sunar. Bu etkileşim, önizlemelerinizin çalışma zamanındaki davranışını anlamanıza yardımcı olur ve önizlemelerle kullanıcı arayüzünüzde daha iyi gezinmenize olanak tanır.

Etkileşimli mod

Etkileşimli mod, önizlemeyle telefon veya tablet gibi programınızı çalıştıran bir cihazda yaptığınız gibi etkileşim kurmanıza olanak tanır. Etkileşimli mod, öğeleri tıklayıp önizlemeye kullanıcı girişi yapabileceğiniz bir korumalı ortamda (yani diğer önizlemelerden izole edilmiş) bulunur. Bu, kompozisyonunuzun farklı durumlarını, hareketlerini ve hatta animasyonlarını hızlı bir şekilde test etmenin bir yoludur.

Kodda gezinme ve composable ana hatlar

Bir önizlemenin üzerine gelerek içindeki composable'ların ana hatlarını görebilirsiniz. Bir derlenebilir ana hattı tıkladığınızda düzenleyici görünümünüz, ana hattı tanımına yönlendirilir.

Önizlemeyi çalıştırma

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ızı gerektirmez.

@Preview ek açıklamanın yanındaki veya önizlemenin üst kısmındaki Önizlemeyi Çalıştır simgesini tıkladığınızda Android Studio, @Preview'ı 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çıklamanın birden fazla önizlemesi

Aynı @Preview bileşeninin farklı özellikleri veya bileşene iletilen farklı parametrelerle birden fazla sürümünü gösterebilirsiniz. Böylece, aksi takdirde yazmanız gereken standart kodu azaltabilirsiniz.

Çoklu önizleme şablonları

androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01 ve sonraki sürümlerde, @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark ve @PreviewDynamicColors olmak üzere çoklu önizleme API şablonları kullanıma sunulmuştur. Böylece tek bir ek açıklamayla, Oluştur kullanıcı arayüzünüzü yaygın senaryolarda ö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 ek açıklamayı kullanarak her bir kompozisyon için bu tanımları tekrarlamadan birden fazla cihazı, yazı tipi boyutunu veya temayı aynı anda önizleyebilirsiniz.

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
AndroidStudioComposeSnippets.kt

Önizleme kompozisyonlarınız için bu özel ek açıklamayı kullanabilirsiniz:

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

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çıklama 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)) } }
}
AndroidStudioComposeSnippets.kt

Çoklu önizlemenin ve normal önizlemenin bir arada kullanılabilmesi, daha büyük ölçekli projelerin birçok özelliğini daha kapsamlı bir şekilde test etmenizi sağlar.

@Preview ve büyük veri kümeleri

Genellikle, composable önizlemenize büyük bir veri kümesini iletmeniz 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)
}
AndroidStudioComposeSnippets.kt

Örnek verileri sağlamak için PreviewParameterProvider uygulayan ve örnek verileri dizi olarak döndüren bir sınıf oluşturun.

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

Bu işlem, dizindeki 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ırlayın.

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

Sınırlılıklar ve en iyi uygulamalar

Android Studio, önizleme kodunu doğrudan önizleme alanında yürütür. Android çerçevesinin Layoutlib adlı taşınmış bir kısmından yararlandığı için emülatör veya fiziksel cihaz çalıştırmayı gerektirmez. Layoutlib, Android cihazların dışında çalışacak şekilde tasarlanmış Android çerçevesinin özel bir sürümüdür. Kitaplığın amacı, Android Studio'da bir düzenin cihazlarda oluşturulan görünümüne çok yakın bir önizlemesini sağlamaktır.

Önizleme sınırlamaları

Android Studio'da önizlemelerin oluşturulma şekli nedeniyle, önizlemeler hafiftir ve oluşturulmaları için Android çerçevesinin tamamı gerekmez. Ancak, bu durum aşağıdaki sınırlamalara tabidir:

• Ağ erişimi yok
• Dosya erişimi yok
• Bazı Context API'leri tam olarak kullanılamayabilir

Önizlemeler ve ViewModels

ViewModel, bir bileşim içinde kullanıldığında önizlemeler sınırlıdır. Önizleme sistemi, ViewModel'e iletilen tüm parametreleri (ör. depolar, kullanım alanları, yöneticiler veya benzerleri) 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 sayede, ViewModel kullanan derlenebilir öğeyi ö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,
)
AndroidStudioComposeSnippets.kt

Ek kaynaklar

Android Studio'nun @Preview kullanım kolaylığını nasıl desteklediği hakkında daha fazla bilgi edinmek ve daha fazla araç ipucu öğrenmek için Compose Tooling bloguna göz atın.