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 di Material per utilizzare MaterialTheme per i componenti di Compose. Ciò significa che i temi della tua app avranno due origini dati: il tema basato su View e il tema Compose. Eventuali modifiche allo stile devono essere apportate in più posizioni. Una volta eseguita la migrazione completa dell'app a Compose, rimuovi i temi XML.

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

Quando avvii la migrazione da XML a Compose, esegui la migrazione dei temi ai temi di Compose di Material 3.

Glossario

Termine Definizione
MaterialTheme La funzione componibile che fornisce i temi (colori, tipografia, forme) ai componenti dell'interfaccia utente di Compose.
Shapes Un oggetto Compose utilizzato per definire forme di componenti personalizzate per un MaterialTheme.
Typography Un oggetto Compose utilizzato per definire stili di testo personalizzati (famiglie di caratteri, dimensioni, spessori) per un MaterialTheme.
ColorScheme 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 di visualizzazione.

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 Material 2 o Sistemi di progettazione personalizzati in Compose.
  • L'obiettivo finale è una migrazione completa a Compose, che consente di rimuovere i temi XML. Questa guida spiega come eseguire la migrazione, ma non come rimuovere definitivamente i temi XML.

Passaggio 1: valuta il sistema di progettazione

Identifica il sistema di progettazione utilizzato nel progetto XML View. Analizzare 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 i temi: 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 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 caratteri tipografici personalizzati

  • Se la tua app utilizza forme personalizzate:

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

    2. Fornisci questo oggetto Shapes 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 la sezione 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 loro stili da styles.xml in due modi diversi:

  1. Impostazione di "style="@style/…" direttamente ed esplicitamente nella visualizzazione XML
  2. Impostazione dello stile in modo indiretto e implicito per un componente come parte di un tema più ampio (theme.xml)

Gli stili non hanno un equivalente diretto in Compose. Vengono invece passati come parametri o modificatori ai componibili, utilizzando la nuova API Styles sperimentale definita in AppTheme o creando varianti componibili riutilizzabili e stratificate 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. Suggerisci invece di creare un componibile specifico.
  • Esempio:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • Scrivi: MyPrimaryButton(onClick = { ... })
  • Gruppi di attributi comuni: se uno stile imposta modificatori comuni (come spaziatura interna + altezza), estraili in una proprietà di estensione leggibile o in una variabile Modifier condivisa.

Esempi comuni

XML Scrivi
Theme.Material3.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...) definito in Typography(bodyMedium = ...)
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 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 attendibilità per il nuovo tema di Material in Compose. Non inventare mai nuovi valori dei temi durante la migrazione per mantenere la coerenza del brand ed evitare regressioni visive.

Verifica che tutti i nuovi valori del tema di Compose corrispondano ai valori XML esistenti. Non impostare come hardcoded i valori migrati.