Configuración del Formato de Caras de Relojes

Nota: En esta página, se muestra un paso del proceso para administrar manualmente la configuración de la cara del reloj. Si prefieres diseñar tu cara de reloj con una herramienta de estilo WYSIWYG (lo que ves es lo que obtienes), consulta primero las guías de Watch Face Studio.

En esta guía, se incluyen pasos sobre las herramientas que necesitas para configurar una cara de reloj con el Formato de Caras de Relojes, algunas sugerencias sobre la estructura de los proyectos y una guía paso a paso para usar las herramientas que permiten crear esa estructura.

Cómo comenzar a usar Android Studio

La forma más fácil de comenzar a desarrollar caras de reloj de forma manual es usar Android Studio. La compatibilidad con caras de reloj está disponible en el canal canary.

  1. Haz clic en File > New Project.
  2. En Wear OS, selecciona Cara de reloj básica.

Esto crea la estructura necesaria para una cara de reloj que funcione correctamente.

Estructura del proyecto

Cuando creas una cara de reloj personalizada que usa el Formato de Caras de Relojes, el Android App Bundle que incluye el archivo en cuestión debe estar completamente separado del Android App Bundle que contiene la lógica de tu app para Wear OS. Algunas tiendas de aplicaciones, como Google Play, evitan que subas un Android App Bundle que incluya una lógica de Wear OS y una cara de reloj personalizada.

Cómo declarar la versión del Formato de Caras de Relojes

En el archivo de manifiesto de tu nueva app (AndroidManifest.xml), inspecciona la propiedad de aplicación que indica el uso del Formato de Caras de Relojes.

Algunas funciones de Watch Face Format solo están disponibles en versiones posteriores. Establece esta propiedad en el valor más bajo que admita las funciones que necesitas para maximizar la compatibilidad del dispositivo y, además, establece el valor de minSdkVersion para que coincida. Obtén más información para configurar las versiones de tu app.

<manifest ...>
    <!--
        Use SDK version 33 to support Watch Face Format (WFF) version 1 and
        higher, SDK version 34 to support WFF version 2 and higher, and so on.
    -->
    <uses-sdk
        android:minSdkVersion="34"
        android:targetSdkVersion="34" />

    <!--
        WFF is a resource-only format, so the hasCode attribute should be set to
        false to reflect this.
    -->
    <application
        android:label="@string/watch_face_name"
        android:hasCode="false"
        ...>
        <meta-data android:name="com.google.android.wearable.standalone"
            android:value="true" />
        <property
            android:name="com.google.wear.watchface.format.version"
            android:value="2" />
    </application>
</manifest>

Cómo declarar metadatos de una cara de reloj

En el directorio de recursos res/xml de tu app, hay un archivo llamado watch_face_info.xml. Aquí es donde defines los metadatos de tu cara de reloj:

<?xml version="1.0" encoding="utf-8"?>
<WatchFaceInfo>

    <Preview value="@drawable/watch_face_preview" />
    <Category value="CATEGORY_EMPTY" />
    <AvailableInRetail value="true" />
    <MultipleInstancesAllowed value="true" />
    <Editable value="true" />
</WatchFaceInfo>

Los campos de este archivo representan los siguientes detalles:

Preview
Hace referencia al elemento de diseño que contiene una imagen de vista previa de la cara de reloj.
Category

Define la categoría de la cara de reloj. Debe ser una cadena o una referencia a una cadena, como @string/ref_name. Cada fabricante de dispositivos puede definir su propio conjunto de categorías de cara de reloj.

Valor predeterminado: empty_category_meta, que agrupa esta cara de reloj con otras de "categoría vacía" en la parte inferior de la vista del selector de caras de reloj.

AvailableInRetail

Si la cara de reloj está disponible en el modo de demo para punto de venta del dispositivo. Debe ser un valor booleano o una referencia a un valor booleano, como @bool/watch_face_available_in_retail.

Valor predeterminado: false

MultipleInstancesAllowed

Si la cara de reloj puede tener varios favoritos. Debe ser un valor booleano o una referencia a un valor booleano, como @bool/watch_face_multiple_instances_allowed.

Valor predeterminado: false

Editable

Si la cara de reloj es editable, lo que significa que tiene una configuración o al menos una complicación no fija. Se usa para mostrar u ocultar el botón Editar de la cara de reloj en la lista de favoritos.

Valor predeterminado: falso

Cómo declarar el nombre de una cara de reloj

En el archivo de manifiesto de tu app (AndroidManifest.xml), configura el atributo android:label según el nombre de tu cara de reloj:

<application android:label="@string/watch_face_name" >

Cómo declarar los detalles de una cara de reloj

La estructura de un documento básico de cara de reloj de WFF es la siguiente:

<WatchFace width="450" height="450">
  <Scene>
    <!-- Content to be rendered -->
  </Scene>
</WatchFace>

La plantilla de Android Studio proporciona un documento básico en res/raw/watchface.xml. Para admitir diferentes formas y tamaños de pantalla, declara la compatibilidad con varias formas y tamaños.

El elemento raíz siempre es WatchFace. Los elementos height y width definen la extensión del espacio de coordenadas para usar en la cara de reloj, y la cara de reloj se ajusta para que quepa en el dispositivo en el que se usa. height y width no representan píxeles reales.

El Formato de Caras de Relojes organiza varios detalles sobre tu cara de reloj:

  • Metadatos, como la hora y el recuento de pasos que se muestran en la imagen de vista previa de la cara del reloj
  • Configuraciones del usuario, como diferentes temas de color para la cara del reloj, elementos que el usuario puede activar o desactivar, y una selección entre varios elementos La versión 2 del Formato de Caras de Relojes introduce los sabores, que pueden aparecer dentro de una configuración del usuario. Cada variante especifica una configuración de usuario predeterminada, que indica el tipo y el estilo de los elementos que aparecen con la hora en la cara del reloj. Estos ajustes predeterminados te permiten crear grupos de elementos visualmente atractivos con mayor facilidad. En la app complementaria de Wear OS, los usuarios ven las diferentes versiones de tu cara de reloj en una fila desplazable.
  • Una escena que contiene los elementos visuales de una cara de reloj. Los elementos que aparecen más cerca del final de la escena se superponen a otros elementos, por lo que el orden típico es el siguiente:
    • Las manecillas de un reloj analógico o el texto de un reloj digital
    • Complicaciones que muestran información adicional, como el día de la semana o el recuento de pasos de un usuario
    • Otros gráficos que proporcionan interés visual o decoraciones para la carátula del reloj, como una imagen de un campamento
  • Grupos de elementos, que te permiten modificar varios elementos al mismo tiempo Puedes crear variantes de estos grupos dentro de una escena, lo que te permite ocultar o modificar contenido de forma selectiva cuando el sistema entra en un modo ambiente de ahorro de energía.

Los atributos están bien escritos y tienen lineamientos sobre la frecuencia y valores válidos para evitar la mayoría de las fuentes de errores cuando se crea una cara de reloj.

Cómo declarar la compatibilidad con formas de caras de reloj (opcional)

Este paso solo es necesario si deseas admitir un comportamiento diferente para los distintos tamaños de carátulas de reloj. Puedes omitir este paso si no te importa que la cara del reloj se ajuste al tamaño del reloj.

En el directorio de recursos res/xml de tu app, declara el conjunto de formas de cara de reloj que admites en watch_face_shapes.xml:

<WatchFaces>
    <WatchFace shape="CIRCLE" width="300" height="300"
               file="@raw/watchface"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
               file="@raw/watchface_large_circle"/>
<WatchFaces>

Luego, define la apariencia y el comportamiento de la cara de reloj para cada forma de cara de reloj. Si no definiste un archivo de formas, solo necesitas un archivo, watchface.xml.

Con el ejemplo de esta sección, los archivos en formato XML sin procesar serían los siguientes:

  • res/raw/watchface.xml
  • res/raw/watchface_large_circle.xml

Cómo identificar al publicador de una cara de reloj (opcional)

De manera opcional, en el archivo de manifiesto de tu app, declara una cadena arbitraria que puedes usar para identificar al publicador de la cara de reloj o el nombre y la versión de la herramienta que usas:

<application ...>
    ...
    <property
        android:name="com.google.wear.watchface.format.publisher"
        android:value="<var>{toolName}-{toolVersion}</var>" />
</application>

Verifica la precisión y el rendimiento de tu cara de reloj

Durante el desarrollo y antes de subir la cara de reloj a Google Play, verifica que no tenga errores de sintaxis con la validación integrada del formato de caras de reloj en Android Studio. Esto destaca automáticamente los errores en tu código y tiene en cuenta la versión.

También debes verificar que tu cara de reloj cumpla con los requisitos de uso de memoria ejecutando la herramienta de espacio en memoria.

Cómo compilar el paquete de aplicación de tu cara de reloj

La forma más fácil de compilar e implementar tu cara de reloj es a través de Android Studio, que tiene compatibilidad integrada con las configuraciones de ejecución de caras de reloj. Después de hacer clic en el botón Run, Android Studio implementa la cara de reloj en el dispositivo o emulador y la establece como la cara de reloj activa.

Ejemplos de caras de reloj

En GitHub, hay más muestras de proyectos de formato de cara de reloj disponibles.