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çıklama eklenir:

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

"Hello World" kelimelerini içeren basit bir metin öğesi

Bu composable'ın önizlemesini etkinleştirmek için @Composable ve @Preview ile ek açıklama eklenmiş başka bir composable oluşturun. Bu yeni, ek açıklamalı composable, başlangıçta oluşturduğunuz SimpleComposable composable'ını içerir:

@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 önizlemenizin canlı güncellemelerini görebilirsiniz.

Compose Preview kullanılarak gerçek zamanlı güncellemelerin gösterildiği bir GIF

Android Studio'nun @Preview öğesini oluşturma şeklini özelleştirmek için kodunuza manuel olarak parametre ekleyebilirsiniz. Farklı özelliklere sahip bir composable'ı önizlemek için @Preview ek açıklamasını aynı işleve birden çok kez ekleyebilirsiniz.

@Preview composable'larını kullanmanın başlıca avantajlarından biri, Android Studio'daki emülatöre bağımlı olmamaktır. Emülatörün yoğun bellek kullanan başlatma işlemini, görünüm ve tarzla ilgili daha kapsamlı değişiklikler için saklayabilir ve @Preview'ın küçük kod değişikliklerini kolayca yapma ve test etme özelliğinden yararlanabilirsiniz.

@Preview ek açıklamasını en etkili şekilde kullanmak için ekranlarınızı, giriş olarak aldığı durum ve çıkış olarak verdiği 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. Kapsayıcı tasarımlarını değiştirebilir, onlarla etkileşim kurabilir veya doğrudan bir emülatöre ya da cihaza dağıtabilirsiniz.

Boyutlar

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

"Hello World" yazılı sarı bir kare

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ğıtlarına nasıl tepki verdiğini görmek için wallpaper özelliğini kullanın. Wallpaper sınıfı tarafından sunulan farklı duvar kağıdı temaları arasından seçim yapın. Bu özellik için Compose 1.4.0 veya sonraki sürümler gerekir.

Farklı cihazlarla kullanma

Android Studio Flamingo'da, farklı cihazlardaki composable'larınızın yapılandırmalarını tanımlamak için Preview ek açıklamasının device parametresini düzenleyebilirsiniz.

Örnek Composable işlevi

Cihaz parametresinde boş bir dize (@Preview(device = "")) olduğunda Ctrl + Space tuşlarına basarak otomatik tamamlamayı çağırabilirsiniz. Ardından her parametrenin değerlerini ayarlayabilirsiniz.

Örnek işlevi düzenleme

Otomatik tamamlama özelliğini kullanarak listeden 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… simgesini seçerek özel bir cihaz girebilirsiniz.

Özellik listesi

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

Geçersiz bir değer ayarlarsanız bildirimin altı kırmızıyla çizilir ve bir düzeltme mevcut olabilir (Alt + Enter (macOS için ⌥ + ⏎) > Şununla değiştir: …. Denetim, girişinize en yakın düzeltmeyi sağlamaya çalışır.

Geçersiz değer örneği

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))
}

Fransız bayrağıyla birlikte "Bonjour" kelimesini içeren basit bir metin öğesi

Arka plan rengini ayarla

Varsayılan olarak, composable'ınız ş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")
}

"Hello World" yazılı yeşil bir dikdörtgen

Sistem Arayüzü

Önizlemede durum ve işlem çubuklarını göstermeniz gerekiyorsa showSystemUi parametresini ekleyin:

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

Durum ve işlem çubuklarını içeren bir etkinliğin gösterildiği önizleme penceresi.

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.

Compose önizleme kullanıcı arayüzü

LocalInspectionMode

LocalInspectionMode CompositionLocal öğesinden okuyarak composable'ın önizlemede (denetlenebilir bir bileşenin içinde) oluşturulup oluşturulmadığını görebilirsiniz. Oluşturma bir önizlemede oluşturulursa LocalInspectionMode.current, true olarak değerlendirilir. Bu bilgiler, önizlemenizi özelleştirmenize olanak tanır. Örneğin, önizleme penceresinde gerçek veriler yerine yer tutucu görsel gösterebilirsiniz.

Bu sayede sınırlamaları da aşabilirsiniz. Örneğin, ağ isteği göndermek yerine örneklenmiş veriler gösterilebilir.

@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ımladığınız önizlemelerle etkileşim kurmanı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, önizlemeyle telefon veya tablet gibi programınızı çalıştıran bir cihazda yaptığınıza benzer şekilde etkileşimde bulunmanıza olanak tanır. Etkileşimli mod, korumalı alan ortamında (yani diğer önizlemelerden izole edilmiş) izole edilir. Bu ortamda öğeleri tıklayabilir ve önizlemeye kullanıcı girişi yapabilirsiniz. Bu, composable'ınızın farklı durumlarını, hareketlerini ve hatta animasyonlarını test etmenin hızlı bir yoludur.

Kullanıcı, önizlemenin "etkileşimli" düğmesini tıklar.

Kullanıcının önizlemeyle etkileşimde bulunduğu bir video

Kodda gezinme ve birleştirilebilir ana hatlar

İçerdiği composable'ların ana hatlarını görmek için imleci bir önizlemenin üzerine getirebilirsiniz. Bir composable ana hat tıklandığında düzenleyici görünümünüz, tanımına gitmek için tetiklenir.

Kullanıcı, bir önizlemenin üzerine geldiğinde Studio, composable'larının ana hatlarını gösterir.

Önizlemeyi çalıştır

Belirli bir @Preview emülatörde veya fiziksel cihazda çalıştırabilirsiniz. Önizleme, aynı proje uygulamasında yeni bir Activity olarak dağıtılır. Bu nedenle, aynı bağlamı ve izinleri paylaşır. Daha önce verilmiş bir izin için ortak metin kodu yazmanızı gerektirmez.

@Preview ek açıklamasının yanındaki veya önizlemenin üst kısmındaki Önizlemeyi Çalıştır simgesini Önizlemeyi Çalıştır simgesi tıklayın. Android Studio, bu @Preview öğesini bağlı cihazınıza veya emülatörünüze dağıtır.

Kullanıcı önizlemeyi tıkladığında

Kullanıcının cihaza önizleme dağıttığı video

@Preview oluşturmayı kopyala

Oluşturulan her önizleme, sağ tıklanarak resim olarak kopyalanabilir.

Kullanıcı, bir önizlemeyi tıklayarak resim olarak kopyalıyor.

Aynı @Preview ek açıklamasının birden fazla önizlemesi

Aynı @Preview composable'ın farklı özelliklere sahip birden fazla sürümünü veya composable'a iletilen farklı parametreleri gösterebilirsiniz. Bu sayede, aksi takdirde yazmanız gereken ortak metin kodunu azaltabilirsiniz.

Çoklu önizleme şablonları

androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+ sürümü, çoklu önizleme API şablonlarını (@PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark ve @PreviewDynamicColors) kullanıma sunar. Böylece tek bir ek açıklamayla, yaygın senaryolarda Oluşturma kullanıcı arayüzünüzü önizleyebilirsiniz.

Şablonları kullanarak farklı yazı tiplerini ve ekran boyutlarını önizleme

Özel çoklu önizleme ek açıklamaları oluşturma

Çoklu önizleme sayesinde, farklı yapılandırmalara sahip birden fazla @Preview ek açıklaması içeren bir ek açıklama sınıfı tanımlayabilirsiniz. Bu ek açıklamayı bir composable işleve eklediğinizde tüm farklı önizlemeler otomatik olarak aynı anda oluşturulur. Örneğin, bu ek açıklamayı kullanarak her bir composable için bu tanımları tekrarlamadan birden fazla cihazı, yazı tipi boyutunu veya temayı aynı anda önizleyebilirsiniz.

Kendi özel not 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

Bu özel ek açıklamayı önizleme composable'larınız için kullanabilirsiniz:

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

Android Studio tasarım sekmesinde küçük ve büyük yazı tipiyle oluşturulabilir öğe gösteriliyor.

Daha eksiksiz bir önizleme grubu oluşturmak için birden fazla çoklu önizleme ek açıklamasını ve normal önizleme ek açıklamasını birleştirebilirsiniz. Çoklu önizleme ek açıklamalarını birleştirmek, tüm farklı kombinasyonların gösterildiğ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)) } }
}

Tüm yapılandırmalarda composable'ı gösteren Android Studio tasarım sekmesi

Çoklu önizlemenin ve normal önizlemenin birleştirme özelliği, 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, oluşturulabilir önizlemenize büyük bir veri kümesi aktarmanız gerekir. Bunu yapmak için @PreviewParameter ek açıklamasıyla bir parametre ekleyerek örneklenmiş verileri bir Composable Preview işlevine iletmeniz yeterlidir.

@Preview
@Composable
fun UserProfilePreview(
    @PreviewParameter(UserPreviewParameterProvider::class) user: User
) {
    UserProfile(user)
}

Örneklenmiş verileri sağlamak için PreviewParameterProvider sınıfını uygulayan ve örneklenmiş verileri bir 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")
    )
}

Bu, dizideki her veri öğesi için bir önizleme oluşturur:

Elise, Frank ve Julia şekillendirilebilir öğelerini gösteren önizlemeler

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)
}

@PreviewParameter kullanan önizlemeler, varsayılan olarak parametre dizini ve özellik adı (kullanıcı 0, kullanıcı 1, kullanıcı 2 vb.) kullanılarak adlandırılır. Bu durum, önizlemeleri birbirinden ayırt etmeyi zorlaştırabilir. Önizleme netliğini artırmak için PreviewParameterProvider dosyanızda getDisplayName() değerini geçersiz kılarak her önizleme için özel görünen adlar sağlayabilirsiniz. Bu sayede farklı veri varyasyonları veya kullanıcı arayüzü durumları arasında ayrım yapılabilir. Örneğin, önizlemeleri giriş verilerine göre etiketleyebilirsiniz:

class UserAgePreviewParameterProvider : PreviewParameterProvider<User> {
    // Using a List internally for efficient index-based access
    private val userList = listOf(
        User(name = "Elise", age = 30),
        User(name = "Frank", age = 31),
        User(name = "Julia", age = 40)
    )

    override val values = userList.asSequence()

    override fun getDisplayName(index: Int): String? {
        // Return null or an empty string to use the default index-based name
        val user = userList.getOrNull(index) ?: return null
        return "${user.name} - ${user.age}"
    }
}

Elise - 30, Frank - 31 ve Julia - 40 composable'larını gösteren özel görünen adlara sahip önizlemeler

Yapay zeka destekli önizleme oluşturma

Android Studio'daki yapay zeka ajanı, composable'larınız için otomatik olarak Compose önizlemeleri oluşturabilir. Bir composable işlevi sağ tıklayıp Yapay Zeka > [Composable adı]için Önizleme Oluştur'u seçin. Temsilci, doğru parametrelerle gerekli @Preview şablonunu oluşturmak için composable'ınızı analiz eder. Böylece, kullanıcı arayüzünüzün beklendiği gibi oluşturulduğunu hızlıca doğrulayabilirsiniz.

Yapay zekayı kullanarak Compose önizlemesi oluşturun.

Ek açıklama sınıfı @Preview

Önizlemenizi özelleştirirken ayarlanabilecek parametrelerin tam listesi için Android Studio'da @Preview ek açıklamasına her zaman "Ctrl veya ⌘ + tıklama" yapabilirsiniz.

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,
)

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şınmış bir bölümünden yararlandığı için emülatör veya fiziksel cihaz çalıştırmayı gerektirmez. Layoutlib, Android cihazlar dışında çalışacak şekilde tasarlanmış özel bir Android çerçevesi sürümüdür. Kitaplığın amacı, Android Studio'da cihazlardaki oluşturma işlemine çok yakın bir düzen önizlemesi sunmaktır.

Önizleme sınırlamaları

Önizlemeler, Android Studio'da oluşturulma şekilleri nedeniyle hafiftir ve oluşturulmaları için tüm Android çerçevesi gerekmez. Ancak bu durumda aşağıdaki sınırlamalar geçerli olur:

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

Önizlemeler ve ViewModels

Bir composable içinde ViewModel kullanılırken önizlemeler sınırlıdır. Önizleme sistemi, ViewModel öğesine iletilen tüm parametreleri (ör. depolar, kullanım alanları, yöneticiler veya benzerleri) oluşturamaz. Ayrıca, ViewModel öğeniz bağımlılık yerleştirmeye (ör. Hilt ile) katılıyorsa önizleme sistemi, ViewModel öğesini oluşturmak için bağımlılık grafiğinin tamamını oluşturamaz.

ViewModel ile bir composable'ı önizlemeye çalıştığınızda Android Studio, ilgili composable'ı oluştururken bir hata gösterir:

&quot;Failed to instantiate a `ViewModel`&quot; mesajını içeren Android Studio sorunlar bölmesi

ViewModel kullanan bir composable'ı önizlemek istiyorsanız ViewModel parametreleri composable'ın bağımsız değişkenleri olarak iletilen başka bir composable oluşturmanız gerekir. Bu sayede, ViewModel kullanan composable'ı önizlemeniz gerekmez.

@Composable
fun AuthorScreen(viewModel: AuthorViewModel = viewModel()) {
  AuthorScreen(
    name = viewModel.authorName,
    // ViewModel sends the network requests and makes posts available as a state
    posts = viewModel.posts
  )
}

@Composable
fun AuthorScreen(
  name: NameLabel,
  posts: PostsList
) {
  // ...
}

@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]
) {
  AuthorScreen(
      name = NameLabel(name),
      posts = PostsList(posts)
  )
}

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.
  • Eski Görünümler kılavuzu için Görünümler ile düzen geliştirme başlıklı makaleyi inceleyin.
Sonraki
Animasyonları önizleme ve hata ayıklama