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

composable, bir işlevle tanımlanır ve @Composable ile not 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çı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, oluşturduğunuz kompozisyon önizlemesinde canlı güncellemeler görebilirsiniz.

Oluşturma Önizleme'yi kullanarak gerçek zamanlı güncellemeleri gösteren bir GIF

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

Üzerinde "Merhaba Dünya" yazan
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ğı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 kullanma

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.

Örnek Composable
işlev

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.

Örnek işlevi düzenlemek

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.

Özellikler listesi

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.

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

"Bonjour" kelimesini içeren ve Fransızca
bayraklı basit bir metin öğesi

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

Üzerinde "Hello World" yazan
yeşil bir dikdörtgen

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

Durum ve işlem çubuklarıyla bir etkinliği gösteren önizleme penceresi.

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.

Önizleme kullanıcı arayüzü oluşturun

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.

Önizlemenin "etkileşimli" düğmesini
tıklayan kullanıcı,

Önizlemeyle etkileşimde bulunan
kullanıcının videosu

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.

Kullanıcı fareyle bir önizlemenin üzerine gelerek Studio'nun composable'larının ana hatlarını
görüntülemesine neden olur.

Ö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 Ö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.

Önizlemenin "önizlemeyi çalıştır"
düğmesini tıklayan kullanıcı

Cihaza önizleme dağıtan kullanıcının videosu

@Preview oluşturmayı kopyala

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

Kullanıcı, bir önizlemeyi tıklayarak resmi resim olarak kopyalar.

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.

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

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

Küçük ve büyük yazı tipiyle composable'ı
gösteren Android Studio tasarım sekmesi.

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

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

Ç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:

Elise, Frank ve Julia&#39;nın bestelerini ve

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:

&quot;ViewModel&quot; mesajı örneklenemediğini gösteren Android Studio sorun bölmesi

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.