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 strumento in stile WYSIWYG (quello che vedi è quello che è), consulta prima le guide di Watch Face Studio.

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

Iniziare a utilizzare Android Studio

Il modo più semplice per iniziare a sviluppare manualmente quadranti è utilizzare Android Studio. Il supporto dei quadranti è disponibile nel canale canary.

1. Fai clic su File > Nuovo progetto.
2. Nella sezione Wear OS, seleziona Quadrante di base.

In questo modo viene creata la struttura necessaria per un quadrante completamente funzionante.

Struttura del progetto

Quando crei un quadrante personalizzato che utilizza Watch Face Format, 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 Wear OS. Alcuni store di app, tra cui Google Play, impediscono di caricare un Android App Bundle che includa sia la logica di Wear OS sia un quadrante personalizzato.

Dichiarare la versione di Watch Face Format

Nel file manifest della nuova app (AndroidManifest.xml), esamina la proprietà dell'applicazione che indica l'utilizzo di Watch Face Format.

Alcune funzionalità di Watch Face Format sono disponibili solo nelle versioni successive. Imposta questa proprietà sul valore più basso che supporta le funzionalità che ti servono, per massimizzare la compatibilità del dispositivo, e imposta anche minSdkVersion in modo che corrisponda. Scopri di più su come configurare le versioni della tua app.

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

Dichiarare i metadati del quadrante

Nella directory delle risorse res/xml della tua app, è presente un 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 set di categorie di quadranti.

Valore predefinito: empty_category_meta, che raggruppa questo quadrante con altri quadranti della "categoria vuota" nella parte inferiore della visualizzazione del selettore di 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

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

Valore predefinito: false

Editable

Indica se il quadrante è modificabile, ovvero se 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

Dichiarare 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 di base del quadrante WFF è la seguente:

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

Il modello di Android Studio fornisce un documento di base in res/raw/watchface.xml. Per supportare diverse forme e dimensioni dello schermo, dichiara il supporto di più forme e dimensioni.

L'elemento principale è sempre WatchFace. height e width definiscono l'estensione dello spazio delle coordinate da utilizzare nel quadrante e il quadrante viene scalato per adattarsi al dispositivo su cui viene utilizzato; height e width non rappresentano pixel effettivi.

Il formato del quadrante organizza diversi dettagli del quadrante:

• Metadati, come l'ora e il conteggio dei passi visualizzati nell'immagine di anteprima del quadrante orologio.
• Configurazioni utente, come diversi temi cromatici per il quadrante, elementi attivabili/disattivabili dall'utente e una scelta tra diversi elementi. La versione 2 del formato del quadrante introduce i gusti, che possono essere visualizzati all'interno di una configurazione utente. Ogni variante specifica una configurazione utente preimpostata, che specifica il tipo e lo stile degli elementi che vengono visualizzati con l'ora nel quadrante. Questi preset ti consentono di creare più facilmente gruppi di elementi visivamente gradevoli. 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 appaiono più vicini alla fine della scena vengono visualizzati sopra gli altri elementi, quindi l'ordine tipico è il seguente:
  • Le lancette di un orologio analogico o il testo di un orologio digitale
  • Complicazioni che mostrano informazioni aggiuntive, come il giorno della settimana o il numero di passi di un utente
  • Altre grafiche che forniscono interesse visivo o decorazioni per il quadrante dell'orologio, come l'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 selettivamente i contenuti quando il sistema entra in modalità Ambient a risparmio energetico.

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

<WatchFaces>
    <WatchFace shape="CIRCLE" width="300" height="300"
               file="@raw/watchface"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
               file="@raw/watchface_large_circle"/>
<WatchFaces>

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