Configurazione del formato per il quadrante dell'orologio

Nota: questa pagina mostra un passaggio della procedura per gestire manualmente la configurazione del quadrante. Se invece vuoi progettare il quadrante utilizzando uno stile WYSIWYG (what you see is what you get), consulta prima le guide di Watch Face Studio.

Questa guida include i passaggi relativi agli strumenti necessari per configurare un quadrante utilizzando il formato Watch Face, alcuni suggerimenti sulla struttura del progetto e una guida passo passo per applicare gli strumenti per creare questa struttura.

Prerequisiti

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

  1. Installa l'SDK per Android 14 (livello API 34) o versioni successive. Se il quadrante non si basa su funzionalità o comportamenti specifici della versione 2, puoi installare l'SDK per Android 13 (livello API 33).

    L'SDK contiene altri strumenti necessari, tra cui aapt2 e android.jar.

  2. In alternativa, installa Android Studio, che può fornire anche questi strumenti.

Struttura del progetto

Quando crei un quadrante personalizzato che utilizza il formato Watch Face, l'Android App Bundle che include il file del quadrante personalizzato deve essere completamente separato dall'Android App Bundle che contiene la logica della tua app per Wear OS. Alcuni store di app, tra cui Google Play, impediscono di caricare un Android App Bundle che includa sia la logica Wear OS sia un quadrante personalizzato.

Creare un cofanetto di quadranti

Per creare un app bundle per Android che includa un file del quadrante, completa i passaggi descritti nelle sezioni seguenti.

Dichiarare l'utilizzo di Watch Face Format

Nel file manifest della nuova app (AndroidManifest.xml), aggiungi una proprietà dell'applicazione che indichi l'utilizzo del formato del quadrante. A meno che tu non voglia limitare l'accesso al quadrante per i dispositivi con Wear OS 5 o versioni successive, crea due APK del quadrante diversi, uno che supporta la versione 2 e uno che supporta la versione 1. Scopri di più su come configurare le versioni della tua app.

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

Dichiarare i metadati del quadrante

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

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

I campi di questo file rappresentano i seguenti dettagli:

Preview
Fa riferimento al drawable 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 insieme ad altri quadranti di "categoria vuota" nella parte inferiore della visualizzazione del selettore dei quadranti.

AvailableInRetail

Indica 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

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

Dichiarare i dettagli del quadrante

La struttura di un documento del quadrante WFF di base è la seguente:

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

Crea questo file XML come res/raw/watchface.xml durante la creazione del quadrante, se utilizzi un singolo quadrante. Per supportare forme e dimensioni dello schermo diverse, dichiara il supporto di più forme e dimensioni.

L'elemento principale è sempre WatchFace. height e width definiscono l'ampiezza dello spazio delle coordinate da utilizzare nel quadrante, che viene scalato in base al dispositivo su cui viene utilizzato. height e width non rappresentano i pixel effettivi.

Il formato del quadrante organizza diversi dettagli del quadrante:

  • Metadati, ad esempio l'ora e il numero di passi visualizzati nell'immagine di anteprima del quadrante.
  • Configurazioni utente, ad esempio diversi temi a colori per il quadrante, elementi attivabili dall'utente e una scelta tra diversi elementi. La versione 2 di Watch Face Format introduce i flavor, che possono essere visualizzati all'interno di una configurazione dell'utente. Ogni versione specifica una configurazione utente preimpostata, che indica il tipo e lo stile degli elementi visualizzati con l'ora nel quadrante. Queste preimpostazioni ti consentono di creare più facilmente gruppi di elementi piacevoli alla vista. Nell'app complementare Wear OS, gli utenti vedono le diverse varianti del quadrante in una riga scorrevole.
  • Una scena che contiene gli elementi visivi di un quadrante. Gli elementi che compaiono più vicino alla fine della scena vengono visualizzati sopra gli altri elementi, quindi l'ordine tipico è il seguente:
    • Le lancette per un orologio analogico o il testo per un orologio digitale
    • Complicazioni che mostrano informazioni aggiuntive, ad esempio il giorno della settimana o il numero di passi di un utente
    • Altre immagini che offrono un'esperienza visiva interessante o decorazioni per il quadrante, ad esempio un'immagine di un campeggio
  • Gruppi di elementi, che ti consentono di modificare più elementi contemporaneamente. Puoi creare varianti di questi gruppi all'interno di una scena, il che ti consente di nascondere o modificare in modo selettivo i contenuti quando il sistema entra in modalità Ambient per risparmiare energia.

Gli attributi sono fortemente tipizzati e hanno linee guida per la frequenza e i valori validi per evitare la maggior parte delle sorgenti di errori durante la creazione di un quadrante.

Dichiarare il supporto per le forme dei quadranti (facoltativo)

Questo passaggio è necessario solo se vuoi supportare un comportamento diverso per le diverse dimensioni dei quadranti. Puoi saltare questo passaggio se non ti dispiace che il quadrante venga ridimensionato in base alle dimensioni dello smartwatch.

Nella directory delle risorse res/xml della tua app, dichiara l'insieme di forme del quadrante supportate in 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>

Poi, definisci l'aspetto e il comportamento del quadrante per ogni forma. Se non hai definito un file di forme, devi creare un solo file,watchface.xml.

Se utilizzi l'esempio di questa sezione, i file XML non elaborati saranno:

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

(Facoltativo) Identificare l'editore del quadrante

Se vuoi, nel file manifest dell'app puoi dichiarare una stringa arbitraria che puoi utilizzare per identificare il publisher del quadrante o il nome e la versione dello strumento che stai utilizzando:

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

Controllare la correttezza e il rendimento del quadrante

Durante lo sviluppo e prima del caricamento su Google Play, utilizza gli strumenti di convalida per verificare che il quadrante sia privo di errori e che sia conforme ai consigli per l'utilizzo della memoria.

Creare l'app bundle del quadrante

Per compilare l'Android App Bundle contenente il quadrante, utilizza il sistema di compilazione Gradle. Scopri di più su come creare un'app utilizzando Gradle.

Questo è dimostrato negli esempi GitHub.