Configuration du format de cadran

Remarque : Cette page vous 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 de type WYSIWYG (What You See Is What You Get), 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 Watch Face Format, ainsi que des suggestions sur la structure de projet et un guide par étapes sur les outils à appliquer pour créer cette structure.

Premiers pas avec Android Studio

Le moyen le plus simple de commencer à développer manuellement des cadrans est d'utiliser Android Studio. La prise en charge des cadrans est disponible sur le canal Canary.

  1. Cliquez sur File > New Project (Fichier > Nouveau projet).
  2. Sous Wear OS, sélectionnez Cadran de base.

Cela crée la structure nécessaire pour un cadran fonctionnel.

Structure du projet

Lorsque vous créez un cadran personnalisé qui utilise le Watch Face Format, 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é.

Déclarer la version du Watch Face Format

Dans le fichier manifeste de votre nouvelle application (AndroidManifest.xml), inspectez la propriété d'application indiquant votre utilisation du Watch Face Format.

Certaines fonctionnalités du format de cadran ne sont disponibles que dans les versions ultérieures. Définissez cette propriété sur la valeur la plus basse qui prend en charge les fonctionnalités dont vous avez besoin, afin de maximiser la compatibilité des appareils, et définissez également minSdkVersion sur la même valeur. Découvrez comment configurer les versions de votre application.

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

Déclarer des métadonnées de cadran

Dans le répertoire de ressources res/xml de votre application, il existe 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 WFF de cadran de montre de base est la suivante :

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

Le modèle Android Studio fournit un document de base dans res/raw/watchface.xml. Pour prendre en charge différentes formes et tailles d'écran, déclarez la compatibilité avec 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 les pixels réels.

Le Watch Face Format organise plusieurs détails concernant votre cadran :

  • Les métadonnées, comme l'heure et le nombre de pas affichés dans l'image d'aperçu du cadran de votre montre.
  • Les configurations utilisateur, telles que les différents thèmes de couleurs pour votre cadran, les éléments que l'utilisateur peut activer ou désactiver, et le choix entre plusieurs éléments. La version 2 de Watch Face Format introduit les saveurs, qui peuvent apparaître dans une configuration utilisateur. Chaque saveur spécifie une configuration utilisateur prédéfinie, en indiquant 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 dans une ligne déroulante.
  • Une 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 trouvent au-dessus des autres éléments. L'ordre habituel est donc le suivant :
    • Aiguilles d'une horloge analogique ou texte d'une horloge numérique
    • Complications affichant des informations supplémentaires, comme le jour de la semaine ou le nombre de pas effectués par un utilisateur
    • Autres éléments graphiques qui apportent un intérêt visuel ou des décorations au cadran de la montre, comme une image d'un camping
  • Les groupes d'éléments 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 veille.

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 différents comportements pour différentes tailles de cadrans. Vous pouvez ignorer cette étape si vous souhaitez que votre cadran s'adapte à 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"/>
<WatchFaces>

Définissez ensuite l'apparence et le comportement de chaque forme de cadran. Si vous n'avez pas défini de fichier de formes, vous n'avez besoin que d'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

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 l'importation sur Google Play, vérifiez que votre cadran ne contient pas d'erreurs de syntaxe en utilisant la validation Watch Face Format intégrée à Android Studio. Il met automatiquement en évidence les erreurs dans votre code et tient compte des versions.

Vous devez également vérifier que votre cadran respecte les exigences d'utilisation de la mémoire en exécutant l'outil empreinte mémoire.

Créer l'app bundle de votre cadran

Le moyen le plus simple de créer et de déployer votre cadran est d'utiliser Android Studio, qui est compatible avec les configurations d'exécution de cadran. Après avoir cliqué sur le bouton Run (Exécuter), Android Studio déploie le cadran sur l'appareil ou l'émulateur, et le définit comme cadran actif.

Exemples de cadrans

D'autres exemples de projets au format Cadran de montre sont disponibles sur GitHub.