Configuration du format de cadran

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 13 (niveau d'API 33) ou version ultérieure. Ce SDK contient d'autres outils obligatoires, y compris aapt2 et android.jar.
  2. Installez le programme de ligne de commande bundletool.
  3. Signez la version de débogage de l'application qui contient la conception de votre cadran. Vous pouvez générer un Android App Bundle signé dans Android Studio ou signer manuellement votre version de débogage.

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 :

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<manifest ...>
    <application ...>
        <property
            android:name="com.google.wear.watchface.format.version"
            android:value="1" />
    </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>
    <!-- Only "Preview" is required. -->
    <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 la prise en charge des formes de cadran

Dans le répertoire de ressources res/xml de votre application, déclarez l'ensemble des formes de cadran compatibles :

<WatchFaces>
    <!-- The default shape is "CIRCLE". -->
    <WatchFace shape="CIRCLE" width="300" height="300"
               file="@raw/watchface"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
               file="@raw/watchface_large_circle"/>
    <WatchFace shape="RECTANGLE" width="380" height="400"
               file="@raw/watchface_rectangle"/>
</WatchFaces>

Déclarer les détails du cadran

Dans le répertoire de ressources res/raw de votre application, créez les fichiers correspondant aux valeurs d'attribut file utilisées lorsque vous déclarez la prise en charge des formes de cadran. C'est là que vous définirez l'apparence et le comportement de chaque cadran.

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

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

L'élément racine est toujours WatchFace :

<WatchFace width="450" height="450" shape="CIRCLE">
    <!-- Remainder of your Watch Face Format definition here. -->
    <!-- If this file defines a watch face for a circular device shape, place
         resources used in this file in the "/res/drawable-nodpi" directory. -->
    <!-- If this file defines a watch face for a rectangular or other
         non-circular shape, place resources ued in this file in the
         "/res/drawable-notround-nodpi" directory. -->
</WatchFace>

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="{toolName}-{toolVersion}" />
</application>

Créer l'app bundle de votre cadran

Pour compiler l'Android App Bundle qui contient votre cadran, utilisez bundletool. Découvrez comment créer une application à l'aide de bundletool.

Consultez les exemples GitHub pour savoir comment préparer votre app bundle en vue de sa publication, ainsi que les outils de validation pour vérifier qu'il est correct avant de l'envoyer à Google Play.