Migra de mosaicos a widgets

Si bien tanto las tarjetas como los widgets muestran tu contenido en una superficie del sistema remota, su creación requiere enfoques distintos. Migrar tu tarjeta existente a un widget significa pasar de una generación de diseño rígida a una IU declarativa y dinámica, lo que desbloquea nuevas capacidades y un modelo de desarrollo simplificado.

Elige tu estrategia de implementación

Si migras una app que mantiene una tarjeta heredada, debes decidir cómo tu app proporciona contenido al sistema. Si bien los widgets nuevos deben usar un solo servicio de widgets, las apps con tarjetas existentes deben elegir entre mantener ambos servicios o consolidar un solo servicio de widgets.

Recomendación: Servicio doble (mosaico y widget)

Mantener tanto una tarjeta como un widget es la opción recomendada para todas las apps que ya tienen una tarjeta. Proporcionar dos servicios distintos ofrece la mejor experiencia del usuario posible en diferentes dispositivos.

Comportamiento del sistema para la configuración de doble servicio:

Capacidad del SO o del dispositivo Experiencia resultante
Wear OS 3 Se usa tarjeta.
Wear OS 4, 5 y 6 Se usa tarjeta.
Wear OS 7 (sin compatibilidad con altura parcial, p.ej., Pixel Watch) Se usa tarjeta.
Wear OS 7 (admite altura parcial, p.ej., Galaxy Watch) Se usa el widget

Alternativa: Servicio único (solo widget)

Un solo servicio controla ambos protocolos. Si bien este enfoque es más rápido de implementar, se basa en un modo de compatibilidad para "adaptar" tu widget a una tarjeta en dispositivos que ejecutan versiones anteriores de Wear OS.

Si eliges este enfoque, haz lo siguiente:

  1. Especifica ambos filtros de intents: Tu servicio debe incluir filtros de intents para androidx.wear.tiles.action.BIND_TILE_PROVIDER y androidx.glance.wear.action.BIND_WIDGET_PROVIDER. Esto garantiza que tu widget se muestre en las plataformas de tarjetas de Wear 4, 5, 6 y 7 (cuando sea necesario).
  2. Conserva el nombre del servicio existente (para actualizaciones sin problemas): Si reemplazas una tarjeta activa, mantener el mismo nombre de clase de servicio garantiza que los usuarios que tengan tu tarjeta en su carrusel verán que se actualiza automáticamente al nuevo widget. Si bien Wear OS 7 usa el atributo group en el XML de configuración del widget para vincular lógicamente diferentes componentes, las versiones de Wear OS anteriores a la 7 dependen del nombre del servicio para identificarlos como el "mismo" componente. Si prefieres usar un nombre de servicio nuevo, tu app seguirá funcionando perfectamente. Sin embargo, los usuarios de dispositivos con Wear OS 6 o versiones anteriores deberán volver a agregar manualmente el widget a su carrusel.

Comportamiento del sistema para la configuración de un solo servicio:

Capacidad del SO o del dispositivo Experiencia resultante
Wear OS 3 No compatible
Wear OS 4, 5 y 6 El widget se muestra como una tarjeta de pantalla completa
Wear OS 7 (sin compatibilidad con altura parcial) El widget se traduce a una tarjeta
Wear OS 7 (compatibilidad con altura parcial) Se usa el widget

*Se requiere el renderizador 1.6 o versiones posteriores.

Sugerencias para la traducción de la IU

Cuando traduces tu IU de ProtoLayout (Tiles) a Remote Compose (Widgets), el modelo mental cambia de compiladores de diseño imperativos a una arquitectura basada en Compose y controlada por el estado, en la que las actualizaciones de la IU se controlan a través de la recomposición. Ten en cuenta los siguientes principios:

  • Adopta la IU declarativa: Reemplaza los compiladores imperativos de ProtoLayout (LayoutElementBuilders) por equivalentes declarativos de Remote Compose, como RemoteText, RemoteColumn y RemoteBox.
  • Enfócate en el contenido principal (mainSlot): Los widgets de altura parcial (p.ej., los tipos de contenedores SMALL y LARGE) proporcionan una superficie enfocada y de un vistazo. En lugar de trasladar un diseño de mosaico denso y de pantalla completa de forma literal, optimiza tu diseño para enfatizar la información principal dentro del área de contenido principal.
  • Rediseño de las acciones alineadas con los bordes: En la arquitectura de tarjetas, los componentes que se ajustan a la pantalla, como EdgeButton, se anclaban a un bottomSlot dedicado. Dado que los widgets de altura parcial se integran directamente en una superficie de desplazamiento vertical, este paradigma fijo de bottomSlot ya no existe. Dado que los botones alineados con el borde a menudo servían como acciones principales muy destacadas, la migración requiere un rediseño deliberado de la IU en lugar de un intercambio directo de componentes. Evalúa estrategias de UX alternativas para tus acciones principales:
    • Acciones intercaladas: Integra un RemoteButton intercalado directamente en tu diseño de mainSlot.
    • Contenedores con toques: Consolida la interacción haciendo que se pueda tocar todo el contenedor del widget con un PendingIntentAction.
    • Reorientación del contenido: Vuelve a evaluar el enfoque del widget. Sin una ranura de acción dedicada, considera mostrar datos más enriquecidos de un vistazo y depender de un solo toque para abrir la aplicación completa en lugar de aislar acciones específicas en la superficie del widget.
  • Migrar el control de eventos (acciones vs. lambdas): Las tarjetas dependen de las interacciones (como LoadAction) que activan devoluciones de llamada de servicio completas para actualizar la IU. Los widgets para Wear se controlan del lado del cliente. Las lambdas de Compose estándar no se pueden ejecutar de forma remota. En su lugar, proporciona acciones declarativas serializables (como ValueChange o PendingIntentAction). Combínalas con un estado declarativo (p. ej., rememberMutableRemoteInt) para admitir actualizaciones instantáneas de la IU sin viajes de ida y vuelta de la app.
  • Adapta las dimensiones y los tipos: Cuando migres dimensiones de diseño, prefiere la resolución de diseño diferida con RemoteDp (p.ej., 10.rdp) en lugar de Dp estándar. Esto garantiza que el renderizador del sistema calcule correctamente los valores de píxeles en el momento de la visualización. Del mismo modo, usa las funciones de extensión de Remote Compose (.rc para Color, .rs para String y .rdp para Dp) para convertir sin problemas los tipos estándar de Kotlin y Remote Compose.
  • Revisa el código de muestra: Para ver ejemplos integrales de cómo compilar diseños, aplicar tipografía semántica y administrar el estado en Remote Compose, explora el código de muestra oficial disponible en el repositorio de muestras de Wear OS.