Mevcut bir uygulamada Compose'u kullanmaya başladığınızda, Compose bileşenlerinde MaterialTheme kullanmak için Material XML temalarınızı taşımanız gerekir. Bu, uygulamanızın temalandırmasının iki doğruluk kaynağı olacağı anlamına gelir: View tabanlı tema ve Compose teması. Stilinizde yapacağınız değişikliklerin birden fazla yerde yapılması gerekir. Uygulamanız Compose'a tamamen taşındıktan sonra XML temalandırmanızı kaldırın.
Renkleri taşımak için Material Theme Builder aracını kullanabilirsiniz.
XML'den Compose'a taşıma işlemine 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şlevi. |
Shape |
MaterialTheme için özel bileşen şekillerini tanımlamak üzere kullanılan bir Compose nesnesi. |
Typography |
Bir MaterialTheme için özel metin stillerini (yazı tipi aileleri, boyutlar, ağırlıklar) tanımlamak üzere kullanılan bir Compose nesnesi. |
Color |
MaterialTheme için özel renk şemalarını tanımlamak üzere 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şlemine başlamadan önce aşağıdaki sınırlamalara dikkat edin:
- Bu kılavuz yalnızca Material 3'e geçişe odaklanmaktadı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 temalandırmanın kaldırılmasını sağlamaktır. Bu kılavuzda nasıl taşıma yapılacağı açıklanmaktadır ancak XML temalandırmanın nasıl tamamen kaldırılacağı açıklanmamaktadır.
1. adım: Tasarım sistemini değerlendirin
XML Görünümü projesinde hangi tasarım sisteminin kullanıldığını belirleyin. Mevcut tasarım sistemini Compose'da Material 3'e taşımak için gereken adımları ve taşıma yolunu 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:
Temalandırma için gerekli tüm XML kaynaklarını ve dosyalarını (açık ve koyu renk şemaları ile niteleyiciler, temalar, şekiller, boyutlar, tipografi, stiller ve diğer alakalı dosyalar) belirleyin ve bulun.
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 renkleri kullanır.
Material 3, anlamsal roller (ör. primary, onPrimary, surface) kullanır.
Renkleri onaltılık kodlarına göre değil, rollerine göre 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şıyın
Uygulamanızda özel şekiller kullanılıyorsa:
- Compose kodunuzda, XML şekil tanımlarınızı kopyalamak için bir
Shapenesnesi tanımlayın. ShapenesnesiniMaterialThemeöğenize ekleyin.Daha fazla bilgi için şekiller bölümüne bakın.
- Compose kodunuzda, XML şekil tanımlarınızı kopyalamak için bir
Uygulamanızda özel tipografi kullanılıyorsa:
- Oluşturma kodunuzda, XML metin stillerinizi ve yazı tipi tanımlarınızı kopyalamak için
Typographynesnesi tanımlayın. TypographynesnesiniMaterialThemeöğenize ekleyin.Daha fazla bilgi için tipografi bölümüne bakın.
- Oluşturma kodunuzda, XML metin stillerinizi ve yazı tipi tanımlarınızı kopyalamak için
| Rol oluşturma | 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şıyın (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, stil oluşturmak için birden fazla özelliği birleştirir. Stillerini styles.xml dosyasından iki farklı şekilde ayarlarlar: 1. "style="@style/..." öğesini doğrudan ve açıkça XML görünümünde ayarlama 2. Daha büyük bir temanın (theme.xml) parçası olarak bir bileşenin stilini dolaylı ve örtülü olarak ayarlama
Stillerin Compose'da doğrudan bir karşılığı yoktur. Bunun yerine stiller şu şekilde iletilir: AppTheme'de tanımlanan veya tanımlı stille katmanlı, yeniden kullanılabilir composable varyasyonları oluşturarak composable'lara parametreler olarak.
Stil ve temel bileşene göre adlandırılmış ayrı @Composable işlevler sağlayarak bu bileşenlerin stil ve kullanım alanlarındaki farkı belirtin.
- Desen: Bir XML öğesi özel bir stil kullanıyorsa (ör.
style="@style/MyPrimaryButton"), stili satır içinde kopyalamaya çalışmayın. Bunun yerine, belirli bir composable oluşturulmasını önerin. - Örnek:
- XML:
<Button style="@style/MyPrimaryButton" ... /> - Oluştur:
MyPrimaryButton(onClick = { ... })
- XML:
- Ortak Özellik Grupları: Bir stil, ortak değiştiriciler (ör. dolgu + yükseklik) ayarlarsa bunları okunabilir bir uzantı özelliğine veya paylaşılan bir Değiştirici değişkenine ayırın.
Sık karşılaşılan örnekler
| XML | Oluştur |
|---|---|
Theme.MaterialComponents.* |
MaterialTheme(colorScheme, typography, shapes) { } |
TextAppearance.Material3.BodyMedium |
TextStyle(...), Typography(bodyMedium = ...) içinde tanımlanır. |
ShapeAppearance.*.SmallComponent |
Shapes(small = RoundedCornerShape(X.dp)) |
Widget.MaterialComponents.Button |
Button(colors = ButtonDefaults.buttonColors(...)) |
Widget.MaterialComponents.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 |
containerColor ComponentDefaults.ComponentColors() içinde başlıyor |
android:textColor |
contentColor ComponentDefaults.ComponentColors() içinde başlıyor |
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 |
fontSize = X.sp TextStyle içinde başlıyor |
6. adım: Tema taşıma işlemini doğrulayın
Compose'daki yeni Material teması için her zaman orijinal XML temasındaki mevcut tema değerlerini doğru kaynak 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 teması değerlerinin mevcut XML değerleriyle eşleştiğini doğrulayın. Taşınan değerleri sabit kodlamayın.