Eseguire la migrazione dei temi XML a Material 3 in Compose

Quando introduci Compose in un'app esistente, devi eseguire la migrazione dei temi XML Material per utilizzare MaterialTheme per i componenti Compose. Ciò significa che il tema della tua app avrà due fonti di riferimento: il tema basato su View e il tema Compose. Eventuali modifiche allo stile devono essere apportate in più posizioni. Una volta completata la migrazione dell'app a Compose, rimuovi il tema XML.

Puoi utilizzare lo strumento Material Theme Builder per la migrazione dei colori.

Quando inizi la migrazione da XML a Compose, esegui la migrazione del tema al tema Material 3 Compose.

Glossario

Termine Definizione
MaterialTheme La funzione componibile che fornisce il tema (colori, tipografia, forme) ai componenti dell'interfaccia utente di Compose.
Shape Un oggetto Compose utilizzato per definire le forme dei componenti personalizzati per un MaterialTheme.
Typography Un oggetto Compose utilizzato per definire stili di testo personalizzati (famiglie di caratteri, dimensioni, spessori) per un MaterialTheme.
Color Un oggetto Compose utilizzato per definire combinazioni di colori personalizzate per MaterialTheme.
Tema XML Il sistema di temi Android definito nei file XML, utilizzato dal sistema View.

Limitazioni

Prima di eseguire la migrazione, tieni presenti le seguenti limitazioni:

  • Questa guida si concentra solo sulla migrazione a Material 3. Per la migrazione da sistemi di progettazione alternativi, consulta Sistemi di progettazione Material 2 o personalizzati in Compose.
  • L'obiettivo finale è una migrazione completa a Compose, che consente di rimuovere il tema XML. Questa guida spiega come eseguire la migrazione, ma non spiega come rimuovere definitivamente il tema XML.

Passaggio 1: valuta il sistema di progettazione

Identifica il sistema di progettazione utilizzato nel progetto XML View. Analizza il percorso di migrazione e i passaggi necessari per eseguire la migrazione del sistema di progettazione esistente a Material 3 in Compose.

Passaggio 2: identifica i file di origine del tema

In XML scrivi ?attr/colorPrimary. In Compose, accedi ai valori del tema con MaterialTheme.*:

Identifica e individua tutte le risorse e i file XML necessari per il tema: combinazioni di colori e qualificatori chiari e scuri, temi, forme, dimensioni, tipografia, stili e altri file pertinenti.

Le risorse come le stringhe possono essere riutilizzate così come sono e non è necessario eseguirne la migrazione.

Passaggio 3: esegui la migrazione dei colori

Principio chiave: XML utilizza colori esadecimali con nome. Material 3 utilizza ruoli semantici (ad es. primary, onPrimary, surface). Smetti di assegnare un nome ai colori in base al loro valore esadecimale; assegna loro un nome in base al loro ruolo.

Esempi:

Nome del colore XML Ruolo Material 3
colorPrimary primary
colorPrimaryDark / colorPrimaryVariant primaryContainer o secondary
colorAccent secondary o tertiary
colorOnPrimary onPrimary
android:colorBackground background
colorSurface surface
colorOnSurface onSurface
colorError error
colorOnError onError
colorOutline outline
colorSurfaceVariant surfaceVariant
colorOnSurfaceVariant onSurfaceVariant

Esegui la migrazione delle combinazioni di colori scuri e chiari da XML ai relativi equivalenti in Material 3 Compose.

Passaggio 4: esegui la migrazione di forme e tipografia personalizzate

  • Se la tua app utilizza forme personalizzate:

    1. Nel codice Compose, definisci un oggetto Shape per replicare le definizioni delle forme XML.

    2. Fornisci questo oggetto Shape al tuo MaterialTheme.

      Per maggiori dettagli, consulta Forme.

  • Se la tua app utilizza una tipografia personalizzata:

    1. Nel codice Compose, definisci un oggetto Typography per replicare gli stili di testo e le definizioni dei caratteri XML.

    2. Fornisci questo oggetto Typography al tuo MaterialTheme.

      Per maggiori dettagli, consulta Tipografia.

Ruolo Compose Nome 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

Passaggio 5: esegui la migrazione degli stili (styles.xml)

Il sistema di stili XML (styles.xml) definisce gli stili e l'aspetto di: 1. Widget, componenti, temi per finestre e finestre di dialogo 2. Tipografia 3. Temi e overlay 4. Forme

Le visualizzazioni e i componenti XML combinano più attributi per creare uno stile. Impostano i propri stili da styles.xml in due modi diversi: 1. Impostando "style="@style/..." direttamente ed esplicitamente nella visualizzazione XML 2. Impostando lo stile in modo indiretto e implicito per un componente come parte di un tema più grande (theme.xml)

Gli stili non hanno un equivalente diretto in Compose. Gli stili vengono invece passati come: parametri ai componenti componibili, definiti in AppTheme o creando variazioni di componenti componibili riutilizzabili a livelli con lo stile definito.

Fornisci funzioni @Composable separate denominate in base allo stile e al componente di base, per indicare la differenza di stile e i casi d'uso di questi componenti.

  • Pattern: se un elemento XML utilizza uno stile personalizzato (ad es. style="@style/MyPrimaryButton"), non provare a replicare lo stile in linea. Ti consigliamo invece di creare un componente componibile specifico.
  • Esempio:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • Compose: MyPrimaryButton(onClick = { ... })
  • Gruppi di attributi comuni: se uno stile imposta modificatori comuni (come padding + altezza), estraili in una proprietà di estensione leggibile o in una variabile Modifier condivisa.

Esempi comuni

XML Compose
Theme.MaterialComponents.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...) definito in 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 in ComponentDefaults.ComponentColors()
android:textColor contentColor in ComponentDefaults.ComponentColors()
cornerRadius shape = RoundedCornerShape(X.dp)
android:elevation elevation = ComponentDefaults.elevation(defaultElevation = X.dp)
android:padding contentPadding = PaddingValues(...) o Modifier.padding()
android:minHeight Modifier.heightIn(min = X.dp)
strokeColor + strokeWidth border = BorderStroke(width, color)
android:textSize fontSize = X.sp in TextStyle

Passaggio 6: convalida la migrazione del tema

Utilizza sempre i valori del tema esistenti del tema XML originale come fonte di riferimento per il nuovo tema Material in Compose. Non inventare nuovi valori del tema durante la migrazione, per mantenere la coerenza del brand ed evitare regressioni visive.

Verifica che tutti i nuovi valori del tema Compose corrispondano ai valori XML esistenti. Non codificare i valori migrati.