Configurazione del formato per il quadrante dell'orologio

Questa guida include i passaggi sugli strumenti necessari per configurare un quadrante utilizzando il formato del quadrante, alcuni suggerimenti sulla struttura del progetto e una guida passo passo all'applicazione degli strumenti per creare questa struttura.

Prerequisiti

Per preparare il tuo ambiente di sviluppo per l'utilizzo del formato del quadrante, completa i seguenti passaggi di configurazione:

  1. Installa l'SDK per Android 13 (livello API 33) o versioni successive. L'SDK contiene altri strumenti necessari, tra cui aapt2 e android.jar.
  2. Installare il programma a riga di comando bundletool.
  3. Firma la versione di debug dell'app che contiene il design del quadrante. Puoi generare un Android App Bundle firmato in Android Studio oppure firmare manualmente la build di debug.

Struttura del progetto

Quando crei un quadrante personalizzato che utilizza il formato del quadrante, l'Android App Bundle che include il file del quadrante personalizzato deve essere completamente separato dall'Android App Bundle che contiene la logica dell'app Wear OS. Alcuni app store, incluso Google Play, ti impediscono di caricare un Android App Bundle che include sia la logica di Wear OS sia un quadrante personalizzato.

Crea bundle di quadranti

Per creare un Android App Bundle che includa un file del quadrante, completa i passaggi mostrati nelle sezioni seguenti.

Dichiara l'utilizzo del formato del quadrante

Nel file manifest della nuova app (AndroidManifest.xml), aggiungi una proprietà dell'applicazione che indica che utilizzi il formato del quadrante:

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

Dichiara i metadati del quadrante

Nella directory delle risorse res/xml della tua app, crea un nuovo file denominato watch_face_info.xml. In questa sezione puoi definire i metadati del quadrante:

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

I campi di questo file rappresentano i seguenti dettagli:

Preview
Fa riferimento al disegno disegnato che contiene un'immagine di anteprima del quadrante.
Category

Definisce la categoria del quadrante. Deve essere una stringa o un riferimento a una stringa, ad esempio @string/ref_name. Ogni produttore di dispositivi può definire il proprio insieme di categorie di quadranti.

Valore predefinito: empty_category_meta, che raggruppa questo quadrante con altri quadranti "categoria vuota" nella parte inferiore della visualizzazione del selettore di quadranti.

AvailableInRetail

Se il quadrante è disponibile nella modalità demo retail del dispositivo. Deve essere un valore booleano o un riferimento a un valore booleano come @bool/watch_face_available_in_retail.

Valore predefinito: false

MultipleInstancesAllowed

Se il quadrante può avere più preferiti. Deve essere un valore booleano o un riferimento a un valore booleano come @bool/watch_face_multiple_instances_allowed.

Valore predefinito: false

Editable

Se il quadrante è modificabile, il che significa che il quadrante ha un'impostazione o almeno una complicazione non fissa. Viene utilizzato per mostrare o nascondere il pulsante Modifica per il quadrante nell'elenco dei preferiti.

Valore predefinito: false

Dichiara il nome del quadrante

Nel file manifest dell'app (AndroidManifest.xml), imposta l'attributo android:label sul nome del quadrante:

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

Dichiara il supporto per le forme dei quadranti

Nella directory delle risorse res/xml della tua app, dichiara il set di forme dei quadranti supportati:

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

Dichiara i dettagli del quadrante

Nella directory delle risorse res/raw della tua app, crea i file corrispondenti ai valori dell'attributo file utilizzati quando dichiari il supporto delle forme dei quadranti. È qui che definisci l'aspetto e il comportamento del quadrante per ogni forma.

Utilizzando l'esempio di questa pagina, i file XML non elaborati sarebbero:

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

L'elemento principale è sempre 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>

Identifica il publisher del quadrante (facoltativo)

Facoltativamente, nel file manifest dell'app, dichiara una stringa arbitraria che puoi utilizzare per identificare il publisher del quadrante o il nome e la versione dello strumento in uso:

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

Creare l'app bundle per il tuo quadrante

Per creare l'Android App Bundle contenente il tuo quadrante, usa bundletool. Scopri di più su come creare un'app utilizzando bundletool.

Consulta gli esempi di GitHub su come preparare l'app bundle per la pubblicazione, nonché gli strumenti di convalida per verificare la correttezza prima dell'invio a Google Play.