Material 3 expresivo es la siguiente evolución de Material Design. Incluye temas y componentes actualizados, y funciones de personalización de Material You, como el color dinámico.

Esta guía se enfoca en la migración de la biblioteca de Jetpack Wear Compose Material 2.5 (androidx.wear.compose) a la biblioteca de Jetpack Wear Compose Material 3 (androidx.wear.compose.material3) para apps.

Enfoques

Para migrar el código de tu app de M2.5 a M3, sigue el mismo enfoque que se describe en la guía de migración de teléfonos de Material de Compose, en particular:

• No debes usar M2.5 y M3 en una sola app a largo plazo.
• Adopta un enfoque por fases.

Dependencias

M3 tiene un paquete y una versión diferentes a M2.5:

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

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

Consulta las versiones más recientes de M3 en la página de versiones de Wear Compose Material 3.

La versión 1.5.0-beta01 de la biblioteca de Wear Compose Foundation presenta algunos componentes nuevos diseñados para funcionar con componentes de Material 3. Del mismo modo, SwipeDismissableNavHost de la biblioteca de navegación de Wear Compose tiene una animación actualizada cuando se ejecuta en Wear OS 6 (nivel de API 36) o versiones posteriores. Cuando actualices a la versión de Material 3 de Wear Compose, te recomendamos que también actualices las bibliotecas de Navigation y Foundation de Wear Compose:

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

Temas

En M2.5 y M3, el tema que admite composición se denomina MaterialTheme, pero los paquetes de importación y los parámetros difieren. En M3, el parámetro Colors se renombró a ColorScheme y se introdujo MotionScheme para implementar transiciones.

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
)

Color

El sistema de colores de M3 es significativamente diferente al de M2.5. La cantidad de parámetros de color aumentó, tienen nombres diferentes y se asignan de forma distinta a los componentes de M3. En Compose, esto se aplica a la clase Colors de M2.5, la clase ColorScheme de M3 y las funciones 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
)

En la siguiente tabla, se describen las diferencias clave entre M2.5 y M3:

Temas de colores dinámicos

Una nueva función de M3 es el tema de colores dinámicos. Si los usuarios cambian los colores de la cara de reloj, los colores de la IU cambian para que coincidan.

Usa la función dynamicColorScheme para implementar el esquema de colores dinámico y proporcionar un defaultColorScheme como resguardo en caso de que el esquema de colores dinámico no esté disponible.

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

Tipografía

El sistema de tipografía en M3 es diferente al de M2 y, además, incluye las siguientes funciones:

• Nueve estilos de texto nuevos
• Fuentes Flex, que permiten personalizar las escalas de tipo para diferentes grosores, anchos y redondeces

• AnimatedText, que usa fuentes flexibles

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
)

Fuentes Flex

Las fuentes Flex permiten a los diseñadores especificar el ancho y el grosor del tipo para tamaños específicos.

Estilos de texto

Los siguientes TextStyles están disponibles en M3. Varios componentes de M3 los usan de forma predeterminada.

Forma

El sistema de forma en M3 es diferente al de M2. La cantidad de parámetros de forma aumentó, tienen nombres diferentes y se asignan, de forma distinta, a los componentes de M3. Los siguientes tamaños de formas están disponibles:

• Extrapequeño
• Pequeño
• Mediano
• Grande
• Extragrande

En Compose, esto se aplica a la clase Shapes de M2 y a la clase Shapes de 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
)

Usa la asignación de parámetros de formas de Cómo migrar de Material 2 a Material 3 en Compose como punto de partida.

Transformación de formas

M3 presenta la transformación de formas: las formas ahora se transforman en respuesta a las interacciones.

El comportamiento de transformación de forma está disponible como una variación en varios botones redondos. Consulta a continuación:

Componentes y diseño

La mayoría de los componentes y diseños de M2.5 están disponibles en M3. Sin embargo, algunos componentes y diseños de M3 no existían en M2.5. Además, algunos componentes de M3 tienen más variaciones que sus equivalentes en M2.5.

Si bien algunos componentes requieren consideraciones especiales, se recomiendan las siguientes asignaciones de funciones como punto de partida:

Esta es una lista completa de todos los componentes de Material 3:

Por último, una lista de algunos componentes relevantes de la biblioteca de Wear Compose Foundation versión 1.5.0-beta01:

Botones

Los botones de M3 son diferentes a los de M2.5. El chip M2.5 se reemplazó por el botón. La implementación de Button proporciona valores predeterminados para Text, maxLines y textAlign. Esos valores predeterminados se pueden anular en el 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(...)

M3 también incluye nuevas variaciones de botones. Consulta la descripción general de la referencia de la API de Compose Material 3.

M3 presenta un nuevo botón: EdgeButton. EdgeButton está disponible en 4 tamaños diferentes: extrapequeño, pequeño, mediano y grande. La implementación de EdgeButton proporciona un valor predeterminado para maxLines según el tamaño que se puede personalizar.

Si usas TransformingLazyColumn y ScalingLazyColumn, pasa el EdgeButton a ScreenScaffold para que se transforme y cambie de forma con el desplazamiento. Consulta el siguiente código para ver cómo usar EdgeButton con ScreenScaffold y 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

El andamiaje en M3 es diferente al de M2.5. En M3, AppScaffold y el nuevo elemento componible ScreenScaffold reemplazaron a Scaffold. AppScaffold y ScreenScaffold diseñan la estructura de una pantalla y coordinan las transiciones de los componentes ScrollIndicator y TimeText.

AppScaffold permite que los elementos de pantalla estáticos, como TimeText, permanezcan visibles durante las transiciones en la app, como el deslizamiento para descartar. ​​Proporciona un espacio para el contenido principal de la aplicación, que suele proporcionar un componente de navegación, como SwipeDismissableNavHost.

Declaras un AppScaffold para la actividad y usas un ScreenScaffold para cada pantalla.

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
    }
}

Si usas un HorizontalPager con HorizontalPagerIndicator, puedes migrar a HorizontalPagerScaffold. HorizontalPagerScaffold se coloca dentro de un AppScaffold. AppScaffold y HorizontalPagerScaffold diseñan la estructura de un objeto Pager y coordinan las transiciones de los componentes HorizontalPageIndicator y TimeText.

HorizontalPagerScaffold muestra el HorizontalPageIndicator en el centro de la pantalla de forma predeterminada y coordina la ocultación o visualización de TimeText y HorizontalPageIndicator según si se pagina Pager, lo que determina PagerState.

También hay un nuevo componente AnimatedPage, que anima una página dentro de un objeto Pager con un efecto de escalamiento y pantalla en función de su posición.

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 último, M3 presenta un VerticalPagerScaffold que sigue el mismo patrón que 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 posición

Hay algunos cambios en la API entre la versión 2.5 y la 3. Placeholder.PlaceholderDefaults ahora proporciona dos modificadores:

• Modifier.placeholder, que se dibuja en lugar del contenido que aún no se cargó
• Un efecto de brillo del marcador de posición Modifier.placeholderShimmer que proporciona un efecto de brillo del marcador de posición que se ejecuta en un bucle de animación mientras se espera que se carguen los datos.

Consulta a continuación los cambios adicionales en el componente Placeholder.

SwipeDismissableNavHost

SwipeDismissableNavHost es parte de wear.compose.navigation. Cuando se usa este componente con M3, MaterialTheme de M3 actualiza LocalSwipeToDismissBackgroundScrimColor y LocalSwipeToDismissContentScrimColor.

TransformingLazyColumn

TransformingLazyColumn forma parte de wear.compose.lazy.foundation y agrega compatibilidad con animaciones de escalamiento y transformación en elementos de lista durante el desplazamiento, lo que mejora la experiencia del usuario.

Al igual que ScalingLazyColumn, proporciona rememberTransformingLazyColumnState() para crear un TransformingLazyColumnState que se recuerda en todas las composiciones.

Para agregar animaciones de escalamiento y transformación, agrega lo siguiente a cada elemento de la lista:

• Modifier.transformedHeight, que te permite calcular la altura transformada de los elementos con un TransformationSpec, puedes usar rememberTransformationSpec(), a menos que necesites más personalización.
• Un 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")
                    }
                }
            }
        }
    }

Vínculos útiles

Para obtener más información sobre la migración de M2.5 a M3 en Compose, consulta los siguientes recursos adicionales.

Ejemplos

Ejemplos de Wear OS en la rama Material3 en GitHub

Codelab de Compose para Wear OS

Referencia de la API y código fuente

• Referencia de la API de Compose Material 3
• Muestras de Compose Material 3 en código fuente

Diseño

• Orientación de diseño