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 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 a estilização XML.

Use a ferramenta Material Theme Builder para migrar cores.

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

Glossário

Termo Definição
MaterialTheme A função combinável que fornece temas (cores, tipografia, formas) aos componentes da interface do Compose.
Shape 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, tamanhos e espessuras de fontes) para um MaterialTheme.
Color 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 da inclusão de temas 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 XML View. Analise o caminho de migração e as etapas necessárias para migrar o sistema de design existente para o Material 3 no Compose.

Etapa 2: identificar os arquivos de origem do tema

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

Identifique e localize todos os recursos e arquivos XML necessários para a estilização: esquemas de cores claro e escuro 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 Compose.

Etapa 4: migrar formas e tipografia personalizadas

  • Se o app usa formas personalizadas:

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

    2. Forneça esse objeto Shape ao seu MaterialTheme.

      Para mais detalhes, consulte formas.

  • Se o app usa tipografia personalizada:

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

    2. Forneça esse objeto Typography ao seu MaterialTheme.

      Para mais detalhes, consulte tipografia.

Função de composição 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, eles são transmitidos como: parâmetros para elementos combináveis, definidos 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 elemento combinável específico.
  • Exemplo:
    • XML:<Button style="@style/MyPrimaryButton" ... />
    • Escrever: MyPrimaryButton(onClick = { ... })
  • Grupos de atributos comuns:se um estilo definir modificadores comuns (como padding + altura), extraia-os para uma propriedade de extensão legível ou uma variável de modificador compartilhada.

Exemplos comuns

XML Escrever
Theme.MaterialComponents.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...) definido em 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 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 de verdade para o novo tema Material 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 valores migrados.