Memigrasikan tema XML ke Material 3 di Compose

Saat memperkenalkan Compose di aplikasi yang ada, Anda perlu memigrasikan tema XML Material untuk menggunakan MaterialTheme bagi komponen Compose. Artinya, penerapan tema aplikasi Anda akan memiliki dua sumber tepercaya: 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.

Anda dapat menggunakan alat Material Theme Builder untuk memigrasikan warna.

Saat Anda 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 Compose UI.
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 bermigrasi, perhatikan batasan berikut:

• Panduan ini hanya berfokus pada migrasi ke Material 3. Untuk bermigrasi 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 sepenuhnya.

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

Dalam XML, Anda menulis ?attr/colorPrimary. Di Compose, Anda mengakses nilai tema dengan MaterialTheme.*:

Identifikasi dan temukan semua file dan resource XML yang diperlukan untuk penerapan tema: skema dan penentu warna terang dan gelap, tema, bentuk, dimensi, tipografi, gaya, dan file relevan lainnya.

Resource seperti string dapat digunakan kembali apa adanya dan tidak perlu dimigrasikan.

Langkah 3: Migrasikan warna

Prinsip utama: XML menggunakan warna hex bernama. Material 3 menggunakan peran semantik (misalnya, 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 padanannya di Material 3 Compose.

Langkah 4: Migrasikan bentuk dan tipografi kustom

• Jika aplikasi Anda menggunakan bentuk kustom:

  1. Dalam kode Compose, tentukan objek Shape untuk mereplikasi definisi bentuk XML Anda.

  2. Berikan objek Shape ini ke MaterialTheme Anda.

     Untuk mengetahui detail selengkapnya, lihat bentuk.

• Jika aplikasi Anda menggunakan tipografi kustom:

  1. Dalam kode Compose, tentukan objek Typography dalam kode Compose untuk mereplikasi gaya teks dan definisi font XML Anda.

  2. Berikan objek Typography ini ke MaterialTheme Anda.

     Untuk mengetahui detail selengkapnya, lihat tipografi.

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

Tampilan dan komponen XML menggabungkan beberapa atribut untuk membuat gaya. Mereka menetapkan gaya dari styles.xml dengan dua cara yang berbeda: 1. Menetapkan "style="@style/..." secara langsung dan eksplisit di Tampilan XML 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, 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 (misalnya, style="@style/MyPrimaryButton"), jangan mencoba mereplikasi gaya sebaris. Sebagai gantinya, sarankan pembuatan composable tertentu.
• Contoh:
  • XML: <Button style="@style/MyPrimaryButton" ... />
  • Tulis: MyPrimaryButton(onClick = { ... })
• 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(...) 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 dalam ComponentDefaults.ComponentColors()
android:textColor	contentColor dalam 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 dalam 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.

Pastikan semua nilai tema Compose baru cocok dengan nilai XML yang ada. Jangan meng-hardcode nilai yang dimigrasikan.