Configuration du format de cadran

Remarque: Cette page présente une étape du processus de gestion manuelle de la configuration de votre cadran. Si vous préférez concevoir votre cadran à l'aide d'un outil WYSIWYG (ce que vous voyez est ce que vous obtenez), consultez d'abord les guides Watch Face Studio.

Ce guide décrit les outils dont vous avez besoin pour configurer un cadran à l'aide du format de cadran, ainsi que des suggestions sur la structure de projet et un guide par étapes sur les outils à appliquer pour créer cette structure.

Conditions préalables

Pour préparer votre environnement de développement à l'utilisation du format de cadran, procédez comme suit :

  1. Installez le SDK pour Android 14 (niveau d'API 34) ou version ultérieure. Si votre cadran ne repose pas sur des fonctionnalités ou un comportement spécifiques à la version 2, vous pouvez installer le SDK pour Android 13 (niveau d'API 33).

    Le SDK contient d'autres outils obligatoires, y compris aapt2 et android.jar.

  2. Vous pouvez également installer Android Studio, qui peut également fournir ces outils.

Structure du projet

Lorsque vous créez un cadran personnalisé qui utilise le format de cadran, l'Android App Bundle qui inclut le fichier de cadran personnalisé doit être complètement distinct de l'Android App Bundle qui contient la logique de votre application Wear OS. Certaines plates-formes de téléchargement d'applications, y compris Google Play, vous empêchent d'importer un Android App Bundle qui inclut à la fois la logique Wear OS et un cadran personnalisé.

Créer un bundle de cadrans

Pour créer un Android App Bundle comprenant un fichier de cadran, suivez les étapes décrites dans les sections suivantes.

Déclarer l'utilisation du format de cadran

Dans le fichier manifeste de votre nouvelle application (AndroidManifest.xml), ajoutez une propriété d'application indiquant votre utilisation du format de cadran. Sauf si vous souhaitez limiter l'accès à votre cadran pour les appareils exécutant Wear OS 5 ou version ultérieure, créez deux APK de cadran différents, l'un compatible avec la version 2 et l'autre avec la version 1. Découvrez comment configurer les versions de votre application.

<manifest ...>
    <!--
        Use SDK version 34 for version 2 of WFF, and SDK version 33 for version
        1 of WFF
    -->
    <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>

Déclarer des métadonnées de cadran

Dans le répertoire de ressources res/xml de votre application, créez un fichier nommé watch_face_info.xml. C'est là que vous définirez les métadonnées du cadran :

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

Les champs de ce fichier représentent les informations suivantes :

Preview
Renvoie le drawable qui contient une image d'aperçu du cadran.
Category

Définit la catégorie du cadran. Il doit s'agir d'une chaîne ou d'une référence à une chaîne (par exemple, @string/ref_name). Chaque fabricant d'appareils peut définir son propre ensemble de catégories de cadrans.

Valeur par défaut: empty_category_meta, qui regroupe ce cadran avec d'autres cadrans de "catégorie vide" en bas de la vue de l'outil de sélection de cadran.

AvailableInRetail

Indique si le cadran est disponible en mode démonstration en magasin sur l'appareil. Doit être une valeur booléenne ou une référence à une valeur booléenne comme @bool/watch_face_available_in_retail.

Valeur par défaut : false

MultipleInstancesAllowed

Indique si le cadran peut avoir plusieurs favoris. Doit être une valeur booléenne ou une référence à une valeur booléenne comme @bool/watch_face_multiple_instances_allowed.

Valeur par défaut : false

Editable

Indique si le cadran est modifiable, ce qui signifie qu'il comporte un paramètre ou au moins une complication non fixe. Cela permet d'afficher ou de masquer le bouton Edit (Modifier) du cadran dans la liste des favoris.

Valeur par défaut : false

Déclarer le nom du cadran

Dans le fichier manifeste de votre application (AndroidManifest.xml), définissez l'attribut android:label sur le nom de votre cadran :

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

Déclarer les détails du cadran

La structure d'un document de cadran WFF de base est la suivante:

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

Créez ce fichier XML en tant que res/raw/watchface.xml lorsque vous créez votre cadran, si vous n'utilisez qu'un seul cadran. Pour prendre en charge différentes formes et tailles d'écran, déclarez la prise en charge de plusieurs formes et tailles.

L'élément racine est toujours WatchFace. height et width définissent l'étendue de l'espace de coordonnées à utiliser dans votre cadran. Le cadran est mis à l'échelle pour s'adapter à l'appareil sur lequel il est utilisé. height et width ne représentent pas de pixels réels.

Le format de cadran organise plusieurs informations sur votre cadran:

  • Métadonnées, telles que l'heure et le nombre de pas affichés dans l'image d'aperçu de votre cadran.
  • Configurations utilisateur, telles que différents thèmes de couleurs pour votre cadran, des éléments pouvant être activés par l'utilisateur et un choix parmi plusieurs éléments. La version 2 du format de cadran introduit les saveurs, qui peuvent apparaître dans une configuration utilisateur. Chaque saveur spécifie une configuration utilisateur prédéfinie, qui indique le type et le style des éléments qui s'affichent avec l'heure sur votre cadran. Ces préréglages vous permettent de créer plus facilement des groupes d'éléments visuellement attrayants. Dans l'application associée Wear OS, les utilisateurs voient les différentes variantes de votre cadran sur une ligne à faire défiler.
  • Scène contenant les éléments visuels d'un cadran. Les éléments qui apparaissent plus près de la fin de la scène se superposent aux autres éléments. L'ordre typique est donc le suivant :
    • Les aiguilles d'une horloge analogique ou le texte d'une horloge numérique
    • Complications qui affichent des informations supplémentaires, comme le jour de la semaine ou le nombre de pas d'un utilisateur
    • Autres graphiques qui apportent un intérêt visuel ou des décorations au cadran, comme une image de camping
  • Groupes d'éléments, qui vous permettent de modifier plusieurs éléments en même temps. Vous pouvez créer des variantes de ces groupes dans une scène, ce qui vous permet de masquer ou de modifier sélectivement le contenu lorsque le système passe en mode économie d'énergie.

Les attributs sont très typés et comportent des consignes relatives à la fréquence et aux valeurs valides, ce qui permet d'éviter la plupart des sources d'erreurs lors de la création d'un cadran.

Déclarer la prise en charge des formes de cadran (facultatif)

Cette étape n'est nécessaire que si vous souhaitez prendre en charge un comportement différent pour différentes tailles de cadrans. Vous pouvez ignorer cette étape si vous acceptez que le cadran soit mis à l'échelle en fonction de la taille de la montre.

Dans le répertoire de ressources res/xml de votre application, déclarez l'ensemble des formes de cadran compatibles dans 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"/>

    <!-- Remove any references to rectangular watch faces -->
    <WatchFace shape="RECTANGLE" width="380" height="400"
               file="@raw/watchface_rectangle"/>
</WatchFaces>

Définissez ensuite l'apparence et le comportement de chaque cadran. Si vous n'avez pas défini de fichier de formes, vous n'avez besoin de créer qu'un seul fichier, watchface.xml.

En reprenant l'exemple de cette section, les fichiers XML bruts seraient:

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

Identifier l'éditeur du cadran (facultatif)

Dans le fichier manifeste de votre application, vous pouvez également déclarer une chaîne arbitraire que vous pouvez utiliser pour identifier l'éditeur du cadran, ou le nom et la version de l'outil que vous utilisez :

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

Vérifier l'exactitude et les performances de votre cadran

Pendant le développement et avant d'importer votre cadran sur Google Play, utilisez les outils de validation pour vérifier qu'il ne comporte aucune erreur et qu'il respecte les recommandations d'utilisation de la mémoire.

Créer l'app bundle de votre cadran

Pour compiler l'Android App Bundle qui contient votre cadran, utilisez le système de compilation Gradle. Découvrez comment créer une application à l'aide de Gradle.

Cela est illustré dans les exemples GitHub.