O Material Design 3 Expressivo é 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 do Wear Compose Material 2.5 (androidx.wear.compose) para a biblioteca Jetpack do Wear Compose Material 3 (androidx.wear.compose.material3) para apps.

Abordagens

Para migrar o código do app da M2.5 para a M3, siga a mesma abordagem descrita nas orientações de migração de telefones do Compose Material, em particular:

• Não use M2.5 e M3 em um único app de longo prazo.
• Adotar uma abordagem por etapas

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.5.0-beta01")

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

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

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

Temas

No M2.5 e no M3, o elemento combinável do tema é 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 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 = AppColorScheme,
        typography = AppTypography,
        shapes = AppShapes,
        motionScheme = AppMotionScheme,
        content = content
)

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
)

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

Temas de cores dinâmicas

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

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

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

Tipografia

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

• Nove novos estilos de texto
• Fontes flexíveis, que permitem a personalização das escalas de tipo 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
)

Fontes flex

As fontes flexíveis permitem que os designers especifiquem a largura e o peso do tipo para tamanhos específicos.

Estilos de texto

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

Forma

O sistema de formas (link em inglês) no M3 é diferente do M2. 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
• Pequeno
• Médio
• Grande
• Extragrande

No Compose, isso se aplica à classe Shapes do M2 e à classe 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
)

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

Transformação de forma

O M3 apresenta o Morphing de forma: agora as formas mudam em resposta às interações.

O comportamento de transformação de forma está disponível como uma variação em vários botões redondos. Confira abaixo:

Componentes e layout

A maioria dos componentes e layouts do M2.5 estão disponíveis 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:

E, por fim, uma lista de alguns componentes relevantes da biblioteca Wear Compose Foundation versão 1.5.0-beta01:

Botões

Os botões no M3 são diferentes do M2.5. O ícone M2.5 foi substituído pelo botão. A implementação de 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(...)

import androidx.wear.compose.material3.Button

//M3 Buttons
Button(...)
CompactButton(...)
IconButton(...)
TextButton(...)

O M3 também inclui novas variações de botões mostradas na Visão geral de referência da API do 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 de EdgeButton oferece um valor padrão para maxLines, dependendo do tamanho que pode ser personalizado.

Se você estiver usando TransformingLazyColumn e ScalingLazyColumn, transmita o EdgeButton para o ScreenScaffold para que ele se transforme, mudando a forma com a rolagem. Consulte o código abaixo para saber como usar EdgeButton com ScreenScaffold e TransformingLazyColumn.

import androidx.wear.compose.material3.EdgeButton
import androidx.wear.compose.material3.ScreenScaffold

ScreenScaffold(
   scrollState = state,
   contentPadding = contentPadding,
   edgeButton = {
      EdgeButton(...)
   }
){ contentPadding ->
   TransformingLazyColumn(state = state, contentPadding = contentPadding,){
   // additional code here
   }
}

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 a 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, permaneçam visíveis durante transições no app, como o gesto de deslizar para descartar. 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 atividade e usa um ScreenScaffold para cada tela.

import androidx.wear.compose.material.Scaffold

Scaffold {...}

import androidx.wear.compose.material3.AppScaffold
import androidx.wear.compose.material3.ScreenScaffold

AppScaffold {
   // Define the navigation hierarchy within the AppScaffold,
   // such as using SwipeDismissableNavHost.
   SwipeDismissableNavHost(...) {
      composable("home") {
         HomeScreen()
      }
      //other screens
   }
}
fun HomeScreen() {
    val scrollState = rememberScrollState()
    ScreenScaffold(scrollState = scrollState) {
    //rest of the screen code
    }
}

Se você estiver usando um HorizontalPager com HorizontalPagerIndicator, poderá migrar para HorizontalPagerScaffold. HorizontalPagerScaffold é colocado dentro de um AppScaffold. AppScaffold e HorizontalPagerScaffold definem a estrutura de um Pager e coordenam as transições dos componentes HorizontalPageIndicator e vTimeText.

Por padrão, HorizontalPagerScaffold exibe o HorizontalPageIndicator no centro da tela e coordena a exibição/ocultação de TimeText e HorizontalPageIndicator de acordo com a paginação do Pager, determinada pelo PagerState.

Também há um novo componente AnimatedPage, que anima uma página em um Pager com um efeito de dimensionamento e scrim com base na posição.

import androidx.wear.compose.material3.AppScaffold
import androidx.wear.compose.material3.HorizontalPagerScaffold
import androidx.wear.compose.material3.ScreenScaffold
import androidx.wear.compose.foundation.pager.HorizontalPager
import androidx.wear.compose.foundation.pager.rememberPagerState

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

    HorizontalPagerScaffold(pagerState = pagerState) {
       HorizontalPager(
          state = pagerState,
        ) { page ->
            AnimatedPage(pageIndex = page, pagerState = pagerState) {
                ScreenScaffold {
…
   }
}

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

import androidx.wear.compose.material3.AppScaffold
import androidx.wear.compose.material3.HorizontalPagerScaffold
import androidx.wear.compose.material3.ScreenScaffold
import androidx.wear.compose.foundation.pager.VerticalPager
import androidx.wear.compose.foundation.pager.rememberPagerState

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

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

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 executado em um loop de animação enquanto aguarda o carregamento dos dados.

Confira abaixo 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 LocalSwipeToDismissContentScrimColor.

TransformingLazyColumn

TransformingLazyColumn faz parte de wear.compose.lazy.foundation e adiciona suporte para dimensionamento e transformação de animações em itens de lista durante a rolagem, melhorando a experiência do usuário.

Da mesma forma que 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. Você pode usar rememberTransformationSpec(), a menos que precise de mais personalização.
• Um SurfaceTransformation

import androidx.wear.compose.material3.AppScaffold
import androidx.wear.compose.material3.ScreenScaffold
import androidx.wear.compose.material3.SurfaceTransformation
import androidx.wear.compose.material3.lazy.rememberTransformationSpec
import androidx.wear.compose.material3.lazy.transformedHeight
import androidx.wear.compose.foundation.lazy.rememberTransformingLazyColumnState
import androidx.wear.compose.foundation.lazy.TransformingLazyColumn

val state = rememberTransformingLazyColumnState()
val transformationSpec = rememberTransformationSpec()
AppScaffold {
   ScreenScaffold(state) { contentPadding ->
      TransformingLazyColumn(state = state, contentPadding = contentPadding) {
         items(count = 50) {
            Button(
               onClick = {},
               modifier =
                        Modifier.fillMaxWidth().transformedHeight(this, transformationSpec),
                        transformation = SurfaceTransformation(transformationSpec),
                    ) {
                        Text("Item $it")
                    }
                }
            }
        }
    }

Links úteis

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

Amostras

Amostras do Wear OS na ramificação do Material3 no GitHub

Codelab sobre o Compose para Wear OS

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