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 i temi della tua app avranno 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 eseguita la migrazione completa dell'app a Compose, rimuovi i temi XML.

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

Quando avvii la migrazione da XML a Compose, esegui la migrazione dei temi al tema Material 3 Compose.

Glossario

Termine Definizione
MaterialTheme La funzione componibile che fornisce i temi (colori, tipografia, forme) ai componenti UI di Compose.
Shape Un oggetto Compose utilizzato per definire forme di componenti personalizzati per un MaterialTheme.
Typography Un oggetto Compose utilizzato per definire stili di testo personalizzati (famiglie di caratteri, dimensioni, pesi) 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 di visualizzazione.

Limitazioni

Prima della migrazione, tieni presente le seguenti limitazioni:

  • Questa guida si concentra solo sulla migrazione a Material 3. Per la migrazione da sistemi di progettazione alternativi, vedi Material 2 o Sistemi di progettazione personalizzati in Compose.
  • L'obiettivo finale è una migrazione completa a Compose, che consente la rimozione dei temi XML. Questa guida spiega come eseguire la migrazione, ma non spiega come rimuovere definitivamente i temi 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, puoi accedere ai valori del tema con MaterialTheme.*:

Identifica e individua tutte le risorse e tutti i file XML necessari per la creazione di temi: schemi e qualificatori di colori 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 devono essere migrate.

Passaggio 3: esegui la migrazione dei colori

Principio chiave: XML utilizza colori esadecimali denominati. Material 3 utilizza ruoli semantici (ad es. primary, onPrimary, surface). Smetti di denominare i colori in base al codice esadecimale; denominarli in base al ruolo.

Esempi:

Nome 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 degli schemi 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, vedi 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 ulteriori dettagli, consulta la sezione Tipografia.

Componi ruolo 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 dialoghi 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. Impostazione di "style="@style/..." direttamente ed esplicitamente nella visualizzazione XML 2. Impostazione dello stile indirettamente e implicitamente per un componente nell'ambito di un tema più grande (theme.xml)

Gli stili non hanno un equivalente diretto in Compose. Vengono invece passati come: parametri ai composable, definiti in AppTheme o creando variazioni di composable a più livelli e riutilizzabili 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 tentare di replicare lo stile in linea. Suggerisci invece di creare un composable 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 modificatore condivisa.

Esempi comuni

XML Scrivi
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 origine di riferimento per il nuovo tema Material in Compose. Non inventare mai 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 in modo permanente i valori migrati.