O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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 o 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 os temas XML.

Use a ferramenta Material Theme Builder para migrar cores.

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

Glossário

Termo	Definição
`MaterialTheme`	A função combinável que fornece temas (cores, tipografia, formas) para os componentes de IU do Compose.
`Shapes`	Um objeto do Compose usado para definir formas de componentes personalizadas para um `MaterialTheme`.
`Typography`	Um objeto do Compose usado para definir estilos de texto personalizados (famílias de fontes, tamanhos, espessuras) 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 de temas XML. Este guia explica como migrar, mas não como remover definitivamente os temas XML.

Etapa 1: avaliar o sistema de design

Identificar qual sistema de design é usado no projeto de visualização XML. Analisar 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 os 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 e qualificadores claros e escuros, temas, formas, dimensões, tipografia, estilos e outros arquivos relevantes.

Recursos como strings podem ser reutilizados como estão e não precisam ser migrados.

Etapa 3: migrar cores

Princípio fundamental:o XML usa cores hexadecimais nomeadas. O Material 3 usa papéis semânticos (por exemplo, primary, onPrimary, surface). Pare de nomear as cores pelo hexadecimal. Nomeie-as pelo papel.

Exemplos:

Nome da cor XML	Papel 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 Shapes para replicar as definições de forma do 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 do XML.
2. Forneça esse objeto Typography ao MaterialTheme.
  
  Para mais detalhes, consulte Tipografia.

Papel 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 os estilos e a aparência de:

Widgets, componentes, temas para janelas e caixas de diálogo
Tipografia
Temas e sobreposições
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:

Definir "style="@style/..." de forma direta e explícita na visualização XML.
Definir o estilo de forma indireta e implícita 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 ou modificadores para elementos combináveis, usando a nova API Styles experimental definida no AppTheme, ou criando variações de elementos combináveis em camadas e reutilizáveis com o estilo definido.

Forneça funções combináveis @Composable separadas, nomeadas de acordo com o estilo e o componente de base, para indicar a diferença de estilo e os 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" ... />
- Compose:MyPrimaryButton(onClick = { ... })
Grupos de atributos comuns:se um estilo definir modificadores comuns (como padding + height), extraia-os para uma propriedade de extensão legível ou uma variável Modifier compartilhada.

Exemplos comuns

XML	Escrever
`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 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 fixe no código nenhum valor migrado.