XML temalarını Compose'da Material 3'e taşıma

Compose'u mevcut bir uygulamaya eklediğinizde, Compose bileşenleri için MaterialTheme kullanmak üzere Material XML temalarınızı taşımanız gerekir. Bu, uygulamanızın temasının iki kaynağı olacağı anlamına gelir: Görünüm tabanlı tema ve Compose teması. Stilinizde yapılacak değişikliklerin birden fazla yerde yapılması gerekir. Uygulamanız tamamen Compose'a taşındıktan sonra XML temalarınızı kaldırın.

Renkleri taşımak için Material Theme Builder aracını kullanabilirsiniz.

XML'den Compose'a geçişe başladığınızda temayı Material 3 Compose temasına taşıyın.

Sözlük

Terim Tanım
MaterialTheme Compose kullanıcı arayüzü bileşenlerine tema (renkler, tipografi, şekiller) sağlayan composable işlev.
Shapes MaterialTheme için özel bileşen şekillerini tanımlamak üzere kullanılan bir Compose nesnesi.
Typography MaterialTheme için özel metin stillerini (yazı tipi aileleri, boyutlar, kalınlıklar) tanımlamak amacıyla kullanılan bir Compose nesnesi.
ColorScheme MaterialTheme için özel renk şemaları tanımlamak amacıyla kullanılan bir Compose nesnesi.
XML Teması XML dosyalarında tanımlanan ve View sistemi tarafından kullanılan Android tema sistemi.

Sınırlamalar

Taşıma işleminden önce aşağıdaki sınırlamalara dikkat edin:

  • Bu kılavuzda yalnızca Material 3'e geçiş ele alınmaktadır. Alternatif tasarım sistemlerinden geçiş yapmak için Material 2 veya Compose'da özel tasarım sistemleri başlıklı makaleyi inceleyin.
  • Nihai hedef, Compose'a tam geçiş yaparak XML temalarını kaldırmaktır. Bu kılavuzda, taşıma işleminin nasıl yapılacağı açıklanmaktadır ancak XML temalarının nasıl kaldırılacağı açıklanmamaktadır.

1. adım: Tasarım sistemini değerlendirin

XML View projesinde hangi tasarım sisteminin kullanıldığını belirleme Mevcut tasarım sistemini Compose'da Material 3'e taşımak için taşıma yolunu ve gerekli adımları analiz edin.

2. adım: Tema kaynak dosyalarını belirleyin

XML'de ?attr/colorPrimary yazarsınız. Compose'da tema değerlerine MaterialTheme.* ile erişirsiniz:

Tema oluşturmak için gereken tüm XML kaynaklarını ve dosyalarını belirleyip bulun: açık ve koyu renk şemaları ve niteleyiciler, temalar, şekiller, boyutlar, tipografi, stiller ve diğer alakalı dosyalar.

Dizeler gibi kaynaklar olduğu gibi yeniden kullanılabilir ve taşınması gerekmez.

3. adım: Renkleri taşıyın

Temel ilke: XML, adlandırılmış onaltılık renkler kullanır. Material 3, anlamsal roller (ör. primary, onPrimary, surface) kullanır. Renkleri onaltılık kodlarıyla değil, rolleriyle adlandırın.

Örnekler:

XML renk adı Material 3 rolü
colorPrimary primary
colorPrimaryDark/colorPrimaryVariant primaryContainer veya secondary
colorAccent secondary veya tertiary
colorOnPrimary onPrimary
android:colorBackground background
colorSurface surface
colorOnSurface onSurface
colorError error
colorOnError onError
colorOutline outline
colorSurfaceVariant surfaceVariant
colorOnSurfaceVariant onSurfaceVariant

Koyu ve açık renk şemalarını XML'den Material 3 Compose'daki eşdeğerlerine taşıyın.

4. adım: Özel şekilleri ve tipografiyi taşıma

  • Uygulamanız özel şekiller kullanıyorsa:

    1. Compose kodunuzda, XML şekil tanımlarınızı kopyalamak için bir Shapes nesnesi tanımlayın.

    2. Bu Shapes nesnesini MaterialTheme uygulamanıza sağlayın.

      Daha fazla bilgi için şekiller bölümüne bakın.

  • Uygulamanızda özel tipografi kullanılıyorsa:

    1. Compose kodunuzda, XML metin stillerinizi ve yazı tipi tanımlarınızı kopyalamak için bir Typography nesnesi tanımlayın.

    2. Bu Typography nesnesini MaterialTheme uygulamanıza sağlayın.

      Daha fazla bilgi için yazı biçimi bölümünü inceleyin.

Oluşturma rolü XML adı
displayLarge TextAppearance.Material3.DisplayLarge
displayMedium TextAppearance.Material3.DisplayMedium
displaySmall TextAppearance.Material3.DisplaySmall
headlineLarge TextAppearance.Material3.HeadlineLarge
headlineMedium TextAppearance.Material3.HeadlineMedium
headlineSmall TextAppearance.Material3.HeadlineSmall
titleLarge TextAppearance.Material3.TitleLarge
titleMedium TextAppearance.Material3.TitleMedium
titleSmall TextAppearance.Material3.TitleSmall
bodyLarge TextAppearance.Material3.BodyLarge
bodyMedium TextAppearance.Material3.BodyMedium
bodySmall TextAppearance.Material3.BodySmall
labelLarge TextAppearance.Material3.LabelLarge
labelMedium TextAppearance.Material3.LabelMedium
labelSmall TextAppearance.Material3.LabelSmall

5. adım: Stilleri taşıma (styles.xml)

XML stilleri (styles.xml) sistemi, aşağıdakilerin stillerini ve görünümünü tanımlar:

  1. Pencereler ve iletişim kutuları için widget'lar, bileşenler, temalar
  2. Yazı biçimi
  3. Temalar ve yer paylaşımları
  4. Şekiller

XML görünümleri ve bileşenleri, bir stil oluşturmak için birden fazla özelliği birleştirir. Stillerini styles.xml dosyasından iki farklı şekilde ayarlarlar:

  1. XML görünümünde doğrudan ve açıkça "style="@style/..." ayarını yapma
  2. Daha büyük bir temanın (theme.xml) parçası olarak bir bileşenin stilini dolaylı ve dolaylı olarak ayarlama

Stillerin, Compose'da doğrudan bir karşılığı yoktur. Bunun yerine stiller, AppTheme'de tanımlanan yeni, deneysel Styles API kullanılarak veya tanımlanan stille katmanlı, yeniden kullanılabilir composable varyasyonları oluşturularak composable'lara parametre ya da değiştirici olarak iletilir.

Bu bileşenlerin stil ve kullanım alanlarındaki farkı belirtmek için stile ve temel bileşene göre adlandırılmış ayrı @Composable işlevleri sağlayın.

  • Kalıp: Bir XML öğesi özel stil kullanıyorsa (ör. style="@style/MyPrimaryButton") stili satır içi olarak kopyalamaya çalışmayın. Bunun yerine, belirli bir composable oluşturmasını önerin.
  • Örnek:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • Oluşturma: MyPrimaryButton(onClick = { ... })
  • Ortak Özellik Grupları: Bir stil, ortak değiştiriciler (ör. dolgu + yükseklik) ayarlıyorsa bunları okunabilir bir uzantı özelliğine veya paylaşılan bir değiştirici değişkenine ayırın.

Yaygın örnekler

XML Oluştur
Theme.Material3.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium Typography(bodyMedium = ...) içinde tanımlanan TextStyle(...)
ShapeAppearance.*.SmallComponent Shapes(small = RoundedCornerShape(X.dp))
Widget.Material3.Button Button(colors = ButtonDefaults.buttonColors(...))
Widget.Material3.CardView Card(shape=..., elevation=..., colors=...)
Widget.*.TextInputLayout.OutlinedBox OutlinedTextField(colors = OutlinedTextFieldDefaults.colors(...))
Widget.*.Chip.Filter FilterChip(colors = FilterChipDefaults.filterChipColors(...))
Widget.*.Toolbar.Primary TopAppBar(colors = TopAppBarDefaults.topAppBarColors(...))
Widget.*.FloatingActionButton FloatingActionButton(containerColor = ...)
backgroundTint ComponentDefaults.ComponentColors() liginde containerColor. sırada
android:textColor ComponentDefaults.ComponentColors() liginde contentColor. sırada
cornerRadius shape = RoundedCornerShape(X.dp)
android:elevation elevation = ComponentDefaults.elevation(defaultElevation = X.dp)
android:padding contentPadding = PaddingValues(...) veya Modifier.padding()
android:minHeight Modifier.heightIn(min = X.dp)
strokeColor + strokeWidth border = BorderStroke(width, color)
android:textSize TextStyle liginde fontSize = X.sp. sırada

6. adım: Tema taşıma işlemini doğrulayın

Compose'daki yeni Materyal Teması Oluşturma için her zaman orijinal XML temasındaki mevcut tema değerlerini doğruluk kaynağı olarak kullanın. Marka tutarlılığını korumak ve görsel gerilemeleri önlemek için taşıma sırasında asla yeni tema değerleri oluşturmayın.

Tüm yeni Compose tema değerlerinin mevcut XML değerleriyle eşleştiğini doğrulayın. Taşınan değerleri sabit kodlamayın.