Migrar do Material 2.5 para o Material 3 no Compose para Wear OS

O Material 3 Expressive (link em inglês) é a próxima evolução do Material Design. Ele inclui temas, componentes e recursos de personalização atualizados, como cores dinâmicas.

Este guia se concentra na migração da biblioteca Jetpack Wear Compose Material 2.5 (androidx.wear.compose) para a biblioteca Jetpack Wear Compose Material 3 (androidx.wear.compose.material3) para apps.

Abordagens

Para migrar o código do app do M2.5 para o M3, siga a mesma abordagem descrita no Guia de migração do Material do Compose para smartphones, em especial:

• Não use M2.5 e M3 em um único app de longo prazo.
• Não use mais as bibliotecas Horologist Composables, Compose Layout ou Compose Material. Em vez disso, use os componentes no M3.
• Adote uma abordagem gradual.

Dependências

O M3 tem um pacote e uma versão separados para o M2.5:

implementation("androidx.wear.compose:compose-material:1.4.0")

implementation("androidx.wear.compose:compose-material3:1.6.0")

Consulte as versões mais recentes do M3 na página de versões do Wear Compose Material 3.

A biblioteca Wear Compose Foundation versão 1.6.0 introduziu alguns novos componentes projetados para funcionar com componentes do Material 3. Da mesma forma, o SwipeDismissableNavHost da biblioteca Wear Compose Navigation tem uma animação atualizada ao ser executado no Wear OS 6 (nível 36 da API) ou mais recente. Ao atualizar para a versão do Wear Compose Material 3, sugerimos que você também atualize as bibliotecas Wear Compose Foundation e Navigation:

implementation("androidx.wear.compose:compose-foundation:1.6.0")
implementation("androidx.wear.compose:compose-navigation:1.6.0")

Tema

Nas versões M2.5 e M3, o tema combinável é chamado de MaterialTheme, mas os pacotes e parâmetros de importação são diferentes. No M3, o parâmetro Colors foi renomeado para ColorScheme, e o MotionScheme foi introduzido para implementar transições.

import androidx.wear.compose.material.MaterialTheme

MaterialTheme(
    colors = AppColors,
    typography = AppTypography,
    shapes = AppShapes,
    content = content
)

import androidx.wear.compose.material3.MaterialTheme
// ...
    MaterialTheme(
        colorScheme = ColorScheme(),
        typography = Typography(),
        shapes = Shapes(),
        motionScheme = MotionScheme.standard(),
        content = { /*content here*/ }
    )
Theme.kt

Cor

O sistema de cores no M3 é significativamente diferente do M2.5. O número de parâmetros de cor aumentou, eles têm nomes diferentes e são mapeados de forma diferente para os componentes do M3. No Compose, isso se aplica à classe Colors do M2.5, à classe ColorScheme do M3 e às funções relacionadas:

import androidx.wear.compose.material.Colors

val appColorScheme: Colors = Colors(
   // M2.5 Color parameters
)

import androidx.wear.compose.material3.ColorScheme
// ...
    val appColorScheme: ColorScheme = ColorScheme(
        // M3 ColorScheme parameters
    )
Color.kt

A tabela a seguir descreve as principais diferenças entre M2.5 e M3:

Temas de cores dinâmicas

Um novo recurso do M3 é a tematização de cores dinâmicas (link em inglês). Se os usuários mudarem as cores do mostrador do relógio, as cores na interface vão mudar para corresponder.

Use a função dynamicColorScheme para implementar o esquema de cores dinâmicas e forneça um defaultColorScheme como substituto caso o esquema de cores dinâmicas não esteja disponível.

@Composable
fun myApp() {
    val dynamicColorScheme = dynamicColorScheme(LocalContext.current)
    MaterialTheme(colorScheme = dynamicColorScheme ?: myBrandColors) {}
}

internal val myBrandColors: ColorScheme = ColorScheme( /* Specify colors here */)
Color.kt

Tipografia

O sistema de tipografia (link em inglês) no M3 é diferente do M2.5 e inclui os seguintes recursos:

• Nove novos estilos de texto
• Fontes flexíveis, que permitem a personalização das escalas tipográficas para diferentes pesos, larguras e arredondamentos

• AnimatedText, que usa fontes flexíveis

import androidx.wear.compose.material.Typography

val Typography = Typography(
   // M2.5 TextStyle parameters
)

import androidx.wear.compose.material3.Typography

val Typography = Typography(
    // M3 TextStyle parameters
)
Typography.kt

Fontes flexíveis

Com as fontes flexíveis, os designers podem especificar a largura e o peso do tipo para tamanhos específicos.

Estilos de texto

Os seguintes TextStyles estão disponíveis no M3. Eles são usados por padrão por vários componentes do M3.

Forma

O sistema de formas (link em inglês) no M3 é diferente do M2.5. O número de parâmetros de forma aumentou, eles são nomeados de forma diferente e são mapeados de forma diferente para os componentes do M3. Os seguintes tamanhos de forma estão disponíveis:

• Extrapequena
• Pequenas
• Médio
• Grande
• Extragrande

No Compose, isso se aplica às classes Shapes do M2 e Shapes do M3:

import androidx.wear.compose.material.Shapes

val Shapes = Shapes(
   // M2.5 Shapes parameters
)

import androidx.wear.compose.material3.Shapes

val Shapes = Shapes(
    // M3 Shapes parameters
)
Shape.kt

Use o mapeamento de parâmetros de formas em Migrar do Material 2 para o Material 3 no Compose como ponto de partida.

Transformação de forma

O M3 apresenta a transformação de formas: agora elas se transformam em resposta às interações.

O comportamento de transformação de forma está disponível como uma variação em vários botões circulares. Consulte a lista a seguir de botões que oferecem suporte a essa transformação:

Componentes e layout

A maioria dos componentes e layouts do M2.5 está disponível no M3. No entanto, alguns componentes e layouts do M3 não existiam no M2.5. Além disso, alguns componentes do M3 têm mais variações do que os equivalentes no M2.5.

Embora alguns componentes exijam considerações especiais, os mapeamentos de funções abaixo são recomendados como ponto de partida:

Confira uma lista completa de todos os componentes do Material 3:

Por fim, uma lista de alguns componentes relevantes da biblioteca Wear Compose Foundation:

Botões

Os botões no M3 são diferentes do M2.5. O ícone M2.5 foi substituído por Button. A implementação Button oferece valores padrão para Text maxLines e textAlign. Esses valores padrão podem ser substituídos no elemento Text.

import androidx.wear.compose.material.Chip

//M2.5 Buttons
Chip(...)
CompactChip(...)
Button(...)

//M3 Buttons
Button(onClick = { }){}
CompactButton(onClick = { }){}
IconButton(onClick = { }){}
TextButton(onClick = { }){}
Button.kt

O M3 também inclui novas variações de botões. Confira na Visão geral da referência da API Compose Material 3.

O M3 apresenta um novo botão: EdgeButton. O EdgeButton está disponível em quatro tamanhos diferentes: extrapequeno, pequeno, médio e grande. A implementação EdgeButton fornece um valor padrão para maxLines dependendo do tamanho, que pode ser personalizado.

Se você estiver usando TransformingLazyColumn ou ScalingLazyColumn, transmita o EdgeButton para o ScreenScaffold para que ele se transforme, mudando de forma com a rolagem, em vez de adicionar um EdgeButton como o último item da lista. Confira o código a seguir para verificar como usar EdgeButton com ScreenScaffold e TransformingLazyColumn.

val state = rememberTransformingLazyColumnState()
ScreenScaffold(
    scrollState = state,
    contentPadding =
        rememberResponsiveColumnPadding(
            first = ColumnItemType.ListHeader
        ),
    edgeButton = {
        EdgeButton(
            onClick = { }
        ) {
            Text(stringResource(R.string.show))
        }
    }
){ contentPadding ->
    TransformingLazyColumn(state = state, contentPadding = contentPadding,){
        // additional code here
    }
}
Button.kt

Scaffold

O Scaffold no M3 é diferente do M2.5. No M3, AppScaffold e o novo elemento combinável ScreenScaffold substituíram o Scaffold. AppScaffold e ScreenScaffold definem o layout da estrutura de uma tela e coordenam as transições dos componentes ScrollIndicator e TimeText.

O AppScaffold permite que elementos estáticos da tela, como TimeText, fiquem visíveis durante transições no app, como o gesto de deslizar para fechar. ​​Ele fornece um slot para o conteúdo principal do aplicativo, que geralmente é fornecido por um componente de navegação, como SwipeDismissableNavHost

Você declara um AppScaffold para a Activity e usa um ScreenScaffold para cada tela. O AppScaffold adiciona um TimeTextcomponent padrão às telas. É possível substituir isso se quiser personalizar usando o parâmetro timeText.

import androidx.wear.compose.material.Scaffold

Scaffold {...}

    AppScaffold {
        val navController = rememberSwipeDismissableNavController()
        SwipeDismissableNavHost(
            navController = navController,
            startDestination = "message_list"
        ) {
            composable("message_list") {
                MessageList(onMessageClick = { id ->
                    navController.navigate("message_detail/$id")
                })
            }
            composable("message_detail/{id}") {
                MessageDetail(id = it.arguments?.getString("id")!!)
            }
        }
    }
}

// Implementation of one of the screens in the navigation
@Composable
fun MessageDetail(id: String) {
    // .. Screen level content goes here
    val scrollState = rememberTransformingLazyColumnState()

    val padding = rememberResponsiveColumnPadding(
        first = ColumnItemType.BodyText
    )

    ScreenScaffold(
        scrollState = scrollState,
        contentPadding = padding
    ) { scaffoldPaddingValues ->
        // Screen content goes here
        // ...
Navigation.kt

Se você estiver usando um HorizontalPager com HorizontalPagerIndicator, poderá migrar para HorizontalPagerScaffold. O HorizontalPagerScaffold é colocado em um AppScaffold. AppScaffold e HorizontalPagerScaffold definem o layout da estrutura de um Pager e coordenam as transições dos componentes HorizontalPageIndicator e TimeText.

O HorizontalPagerScaffold mostra o HorizontalPageIndicator no centro da tela por padrão e coordena a exibição e ocultação de TimeText e HorizontalPageIndicator de acordo com o Pager. Isso é determinado pelo PagerState.

Há também um novo componente AnimatedPage, que anima uma página em um Pager com um efeito de escalonamento e tela escura com base na posição dela.

AppScaffold {
    val pagerState = rememberPagerState(pageCount = { 10 })
    val columnState = rememberTransformingLazyColumnState()
    val contentPadding = rememberResponsiveColumnPadding(
        first = ColumnItemType.ListHeader,
        last = ColumnItemType.BodyText,
    )
    HorizontalPagerScaffold(pagerState = pagerState) {
        HorizontalPager(
            state = pagerState,
        ) { page ->
            AnimatedPage(pageIndex = page, pagerState = pagerState) {
                ScreenScaffold(
                    scrollState = columnState,
                    contentPadding = contentPadding
                ) { contentPadding ->
                    TransformingLazyColumn(
                        state = columnState,
                        contentPadding = contentPadding
                    ) {
                        item {
                            ListHeader(
                                modifier = Modifier.fillMaxWidth()
                            ) {
                                Text(text = "Pager sample")
                            }
                        }
                        item {
                            if (page == 0) {
                                Text(text = "Page #$page. Swipe right")
                            }
                            else{
                                Text(text = "Page #$page. Swipe left and right")
                            }
                        }
                    }
                }

            }
        }
    }
}
Pager.kt

Por fim, o M3 apresenta um VerticalPagerScaffold que segue o mesmo padrão do HorizontalPagerScaffold:

AppScaffold {
    val pagerState = rememberPagerState(pageCount = { 10 })

    VerticalPagerScaffold(pagerState = pagerState) {
        VerticalPager(
            state = pagerState
        ) { page ->
            AnimatedPage(pageIndex = page, pagerState = pagerState) {
                ScreenScaffold {
                    ///…
                }
            }
        }
    }
}
Pager.kt

Marcador de posição

Há algumas mudanças na API entre o M2.5 e o M3. O Placeholder.PlaceholderDefaults agora oferece dois modificadores:

• Modifier.placeholder, que é desenhado em vez de conteúdo que ainda não foi carregado.
• Um efeito de brilho de marcador de posição Modifier.placeholderShimmer que fornece um efeito de brilho de marcador de posição que é executado em um loop de animação enquanto aguarda o carregamento dos dados.

Confira na tabela a seguir outras mudanças no componente Placeholder.

SwipeDismissableNavHost

SwipeDismissableNavHost faz parte de wear.compose.navigation. Quando esse componente é usado com o M3, o MaterialTheme do M3 atualiza o LocalSwipeToDismissBackgroundScrimColor e o LocalSwipeToDismissContentScrimColor.

TransformingLazyColumn

O TransformingLazyColumn faz parte do wear.compose.lazy.foundation e adiciona suporte para animações de escalonamento e transformação em itens de lista durante a rolagem, melhorando a experiência do usuário. É altamente recomendável que os apps migrem de ScalingLazyColumn para TransformingLazyColumn

Assim como ScalingLazyColumn, ele fornece rememberTransformingLazyColumnState() para criar um TransformingLazyColumnState que é lembrado em todas as composições.

Para adicionar animações de escalonamento e transformação, adicione o seguinte a cada item da lista:

• Modifier.transformedHeight, que permite calcular a altura transformada dos itens usando um TransformationSpec, é possível usar rememberTransformationSpec(), a menos que você precise de mais personalização.
• Um SurfaceTransformation

Para verificar se o padding está correto na parte de cima e de baixo da lista, use o modificador minimumVerticalContentPadding.

val columnState = rememberTransformingLazyColumnState()
val transformationSpec = rememberTransformationSpec()
ScreenScaffold(
    scrollState = columnState
) { contentPadding ->
    TransformingLazyColumn(
        state = columnState,
        contentPadding = contentPadding
    ) {
        item {
            ListHeader(
                modifier = Modifier
                    .fillMaxWidth()
                    .transformedHeight(this, transformationSpec)
                    .minimumVerticalContentPadding(ListHeaderDefaults.minimumTopListContentPadding),
                transformation = SurfaceTransformation(transformationSpec)
            ) {
                Text(text = "Header")
            }
        }
        // ... other items
        item {
            Button(
                modifier = Modifier
                    .fillMaxWidth()
                    .transformedHeight(this, transformationSpec)
                    .minimumVerticalContentPadding(ButtonDefaults.minimumVerticalListContentPadding),
                transformation = SurfaceTransformation(transformationSpec),
                onClick = { /* ... */ },
                icon = {
                    Icon(
                        imageVector = Icons.Default.Build,
                        contentDescription = "build",
                    )
                },
            ) {
                Text(
                    text = "Build",
                    maxLines = 1,
                    overflow = TextOverflow.Ellipsis,
                )
            }
        }
    }
}
List.kt

Links úteis

Para saber mais sobre a migração do M2.5 para o M3 no Compose, consulte os recursos abaixo.

Amostras

• Exemplos do Wear OS no GitHub (link em inglês)
• Codelab sobre o Compose para Wear OS
• Amostra do Jetcaster

Referência da API e código-fonte

• Referência da API Compose Material 3
• Exemplos do Material 3 do Compose no código-fonte

Design

• Orientações de design