Migrar temas XML para o Material 3 no Compose

Ao introduzir o Compose em um app já existente, é necessário migrar os temas XML do Material Design para usar MaterialTheme em componentes do Compose. Isso significa que os temas do seu app vão ter duas fontes da verdade: o tema baseado na visualização e o tema do Compose. Qualquer mudança no estilo precisa ser feita em vários lugares. Depois que o app for totalmente migrado para o Compose, remova o tema XML.

Você pode usar a ferramenta Material Theme Builder para migrar cores.

Ao iniciar a migração do XML para o Compose, migre o tema para o tema do Material 3.

Glossário

Termo Definição
MaterialTheme A função combinável que fornece temas (cores, tipografia, formas) para componentes da interface do Compose.
Shapes Um objeto do Compose usado para definir formas de componentes personalizados para um MaterialTheme.
Typography Um objeto do Compose usado para definir estilos de texto personalizados (famílias de fontes, tamanhos, pesos) para um MaterialTheme.
ColorScheme Um objeto do Compose usado para definir esquemas de cores personalizados para MaterialTheme.
Tema XML O sistema de temas do Android definido em arquivos XML, usado pelo sistema de visualização.

Limitações

Antes de migrar, esteja ciente das seguintes limitações:

  • Este guia se concentra apenas na migração para o Material 3. Para migrar de sistemas de design alternativos, consulte Material 2 ou Sistemas de design personalizados no Compose.
  • O objetivo final é uma migração completa para o Compose, que permite a remoção do tema XML. Este guia explica como migrar, mas não explica como remover o tema XML.

Etapa 1: avaliar o sistema de design

Identifique qual sistema de design é usado no projeto de visualização XML. Analise o caminho de migração e as etapas necessárias para migrar o sistema de design atual para o Material 3 no Compose.

Etapa 2: identificar arquivos de origem do tema

Em XML, você escreve ?attr/colorPrimary. No Compose, você acessa os valores do tema com MaterialTheme.*:

Identifique e localize todos os recursos e arquivos XML necessários para a aplicação de temas: esquemas de cores claras e escuras e qualificadores, temas, formas, dimensões, tipografia, estilos e outros arquivos relevantes.

Recursos como strings podem ser reutilizados no estado em que se encontram e não precisam ser migrados.

Etapa 3: migrar cores

Princípio fundamental:o XML usa cores hexadecimais nomeadas. O Material 3 usa funções semânticas (por exemplo, primary, onPrimary, surface). Pare de nomear as cores pelo hexadecimal e nomeie-as pela função.

Exemplos:

Nome da cor XML Função do Material 3
colorPrimary primary
colorPrimaryDark / colorPrimaryVariant primaryContainer ou secondary
colorAccent secondary ou tertiary
colorOnPrimary onPrimary
android:colorBackground background
colorSurface surface
colorOnSurface onSurface
colorError error
colorOnError onError
colorOutline outline
colorSurfaceVariant surfaceVariant
colorOnSurfaceVariant onSurfaceVariant

Migre os esquemas de cores claras e escuras do XML para os equivalentes no Material 3 do Compose.

Etapa 4: migrar formas e tipografia personalizadas

  • Se o app usa formas personalizadas:

    1. No código do Compose, defina um objeto Shapes para replicar as definições de forma XML.

    2. Forneça esse objeto Shapes ao MaterialTheme.

      Para mais detalhes, consulte Formas.

  • Se o app usa tipografia personalizada:

    1. No código do Compose, defina um objeto Typography para replicar os estilos de texto e as definições de fonte XML.

    2. Forneça esse objeto Typography ao MaterialTheme.

      Para mais detalhes, consulte Tipografia.

Função do 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

Etapa 5: migrar estilos (styles.xml)

O sistema de estilos XML (styles.xml) define estilos e aparência de:

  1. Widgets, componentes, temas para janelas e caixas de diálogo
  2. Tipografia
  3. Temas e sobreposições
  4. Formas

As visualizações e os componentes XML combinam vários atributos para criar um estilo. Eles definem os estilos de styles.xml de duas maneiras diferentes:

  1. Definir "style="@style/..." diretamente e explicitamente na visualização XML
  2. Definir o estilo indireta e implicitamente para um componente como parte de um tema maior (theme.xml)

Os estilos não têm um equivalente direto no Compose. Em vez disso, os estilos são transmitidos como: parâmetros ou modificadores para combináveis, usando a nova API Styles experimental definida no AppTheme ou criando variações combináveis reutilizáveis em camadas com o estilo definido.

Forneça funções @Composable separadas nomeadas de acordo com o estilo e o componente de base para indicar a diferença no estilo e nos casos de uso desses componentes.

  • Padrão:se um elemento XML usar um estilo personalizado (por exemplo, style="@style/MyPrimaryButton"), não tente replicar o estilo inline. Em vez disso, sugira a criação de um combinável específico.
  • Exemplo:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • Compose:MyPrimaryButton(onClick = { ... })
  • Grupos de atributos comuns:se um estilo definir modificadores comuns (como preenchimento + altura), extraia-os para uma propriedade de extensão legível ou uma variável de modificador compartilhada.

Exemplos comuns

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

Etapa 6: validar a migração do tema

Sempre use os valores de tema atuais do tema XML original como a fonte da verdade para o novo tema do Material Design no Compose. Nunca invente novos valores de tema durante a migração para manter a consistência da marca e evitar regressões visuais.

Verifique se todos os novos valores de tema do Compose correspondem aos valores XML atuais. Não codifique nenhum valor migrado.