Saat memperkenalkan Compose di aplikasi yang ada, Anda perlu memigrasikan tema XML Material untuk menggunakan MaterialTheme bagi komponen Compose. Artinya, tema aplikasi Anda akan memiliki dua sumber kebenaran: tema berbasis View dan tema Compose. Setiap perubahan pada gaya visual Anda harus dilakukan di beberapa tempat. Setelah aplikasi Anda dimigrasikan sepenuhnya ke Compose, hapus tema XML.
Anda dapat menggunakan alat Material Theme Builder untuk memigrasikan warna.
Saat memulai migrasi dari XML ke Compose, migrasikan tema ke tema Compose Material 3.
Glosarium
| Istilah | Definisi |
|---|---|
MaterialTheme |
Fungsi composable yang menyediakan tema (warna, tipografi, bentuk) ke komponen UI Compose. |
Shape |
Objek Compose yang digunakan untuk menentukan bentuk komponen kustom untuk MaterialTheme. |
Typography |
Objek Compose yang digunakan untuk menentukan gaya teks kustom (keluarga font, ukuran, ketebalan) untuk MaterialTheme. |
Color |
Objek Compose yang digunakan untuk menentukan skema warna kustom untuk MaterialTheme. |
| Tema XML | Sistem tema Android yang ditentukan dalam file XML, yang digunakan oleh sistem View. |
Batasan
Sebelum melakukan migrasi, perhatikan batasan berikut:
- Panduan ini hanya berfokus pada migrasi ke Material 3. Untuk melakukan migrasi dari sistem desain alternatif, lihat Material 2 atau Sistem desain kustom di Compose.
- Tujuan utamanya adalah migrasi lengkap ke Compose, yang memungkinkan penghapusan tema XML. Panduan ini menjelaskan cara melakukan migrasi, tetapi tidak menjelaskan cara menghapus tema XML.
Langkah 1: Evaluasi sistem desain
Identifikasi sistem desain yang digunakan dalam project XML View. Analisis jalur migrasi dan langkah-langkah yang diperlukan untuk memigrasikan sistem desain yang ada ke Material 3 di Compose.
Langkah 2: Identifikasi file sumber tema
Di XML, Anda menulis ?attr/colorPrimary. Di Compose, Anda mengakses nilai tema dengan MaterialTheme.*:
Identifikasi dan temukan semua resource dan file XML yang diperlukan untuk tema: skema warna terang dan gelap serta kualifikasi, tema, bentuk, dimensi, tipografi, gaya, dan file relevan lainnya.
Resource seperti string dapat digunakan kembali seperti apa adanya dan tidak perlu dimigrasikan.
Langkah 3: Migrasikan warna
Prinsip utama: XML menggunakan warna hex bernama.
Material 3 menggunakan peran semantik (mis., primary, onPrimary, surface). Berhenti memberi nama warna berdasarkan hex-nya; beri nama berdasarkan perannya.
Contoh:
| Nama warna XML | Peran Material 3 |
|---|---|
colorPrimary |
primary |
colorPrimaryDark / colorPrimaryVariant |
primaryContainer atau secondary |
colorAccent |
secondary atau tertiary |
colorOnPrimary |
onPrimary |
android:colorBackground |
background |
colorSurface |
surface |
colorOnSurface |
onSurface |
colorError |
error |
colorOnError |
onError |
colorOutline |
outline |
colorSurfaceVariant |
surfaceVariant |
colorOnSurfaceVariant |
onSurfaceVariant |
Migrasikan skema warna gelap dan terang dari XML ke skema yang setara di Compose Material 3.
Langkah 4: Migrasikan bentuk dan tipografi kustom
Jika aplikasi Anda menggunakan bentuk kustom:
- Dalam kode Compose, tentukan objek
Shapeuntuk mereplikasi definisi bentuk XML Anda. Berikan objek
Shapeini keMaterialThemeAnda.Untuk mengetahui detail selengkapnya, lihat bentuk.
- Dalam kode Compose, tentukan objek
Jika aplikasi Anda menggunakan tipografi kustom:
- Dalam kode Compose, tentukan objek
Typographydalam kode Compose untuk mereplikasi gaya teks dan definisi font XML Anda. Berikan objek
Typographyini keMaterialThemeAnda.Untuk mengetahui detail selengkapnya, lihat tipografi.
- Dalam kode Compose, tentukan objek
| Peran Compose | Nama XML |
|---|---|
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 |
Langkah 5: Migrasikan gaya (styles.xml)
Sistem gaya XML (styles.xml) menentukan gaya dan tampilan: 1. Widget, komponen, tema untuk jendela dan dialog 2. Tipografi 3. Tema dan overlay 4. Bentuk
XML View dan komponen menggabungkan beberapa atribut untuk membuat gaya. Mereka menetapkan gaya dari styles.xml dengan dua cara berbeda: 1. Menetapkan "style="@style/..." secara langsung dan eksplisit di XML View 2. Menetapkan gaya secara tidak langsung dan implisit untuk komponen sebagai bagian dari Tema yang lebih besar (theme.xml)
Gaya tidak memiliki padanan langsung di Compose. Sebagai gantinya, gaya diteruskan sebagai: parameter ke composable, yang ditentukan di AppTheme, atau dengan membuat variasi composable berlapis dan dapat digunakan kembali dengan gaya yang ditentukan.
Berikan fungsi @Composable terpisah yang diberi nama sesuai dengan gaya dan komponen dasar, untuk menunjukkan perbedaan dalam gaya dan kasus penggunaan untuk komponen tersebut.
- Pola: Jika elemen XML menggunakan gaya kustom
(mis.,
style="@style/MyPrimaryButton"), jangan mencoba mereplikasi gaya sebaris. Sebagai gantinya, sarankan untuk membuat composable tertentu. - Contoh:
- XML:
<Button style="@style/MyPrimaryButton" ... /> - Compose:
MyPrimaryButton(onClick = { ... })
- XML:
- Grup Atribut Umum: Jika gaya menetapkan pengubah umum (seperti padding + tinggi), ekstrak ke dalam properti ekstensi yang dapat dibaca atau variabel Pengubah bersama.
Contoh umum
| XML | Compose |
|---|---|
Theme.MaterialComponents.* |
MaterialTheme(colorScheme, typography, shapes) { } |
TextAppearance.Material3.BodyMedium |
TextStyle(...) yang ditentukan dalam Typography(bodyMedium = ...) |
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 di ComponentDefaults.ComponentColors() |
android:textColor |
contentColor di ComponentDefaults.ComponentColors() |
cornerRadius |
shape = RoundedCornerShape(X.dp) |
android:elevation |
elevation = ComponentDefaults.elevation(defaultElevation = X.dp) |
android:padding |
contentPadding = PaddingValues(...) atau Modifier.padding() |
android:minHeight |
Modifier.heightIn(min = X.dp) |
strokeColor + strokeWidth |
border = BorderStroke(width, color) |
android:textSize |
fontSize = X.sp di TextStyle |
Langkah 6: Validasi migrasi tema
Selalu gunakan nilai tema yang ada dari tema XML asli sebagai sumber kebenaran untuk Tema Material baru di Compose. Jangan pernah membuat nilai tema baru selama migrasi, untuk mempertahankan konsistensi merek dan menghindari regresi visual.
Verifikasi bahwa semua nilai tema Compose baru cocok dengan nilai XML yang ada. Jangan hardcode nilai yang dimigrasikan.