Konfiguracja formatu tarczy zegarka

Uwaga: ta strona pokazuje jeden z etapów procesu ręcznego zarządzania konfiguracją tarczy zegarka. Jeśli chcesz zaprojektować tarczę zegarka za pomocą narzędzia WYSIWYG (ang. what you see is what you get), najpierw zapoznaj się z przewodnikami Watch Face Studio.

Ten przewodnik zawiera informacje o narzędziach, których potrzebujesz do skonfigurowania tarczy zegarka za pomocą Formatu tarczy zegarka, sugestie dotyczące struktury projektu oraz szczegółowe instrukcje korzystania z narzędzi do tworzenia tej struktury.

Wymagania wstępne

Aby przygotować środowisko programistyczne do korzystania z Formatu tarczy zegarka, wykonaj te czynności:

  1. Zainstaluj pakiet SDK na Androida 14 (poziom interfejsu API 34) lub nowszego. Jeśli tarcza zegarka nie korzysta z funkcji ani zachowań specyficznych dla wersji 2, możesz zainstalować pakiet SDK przeznaczony na Androida 13 (poziom API 33).

    Pakiet SDK zawiera też inne wymagane narzędzia, w tym aapt2 i android.jar.

  2. Alternatywnie możesz zainstalować Android Studio, w którym również znajdziesz te narzędzia.

Struktura projektu

Gdy tworzysz niestandardową tarczę zegarka, która korzysta z Formatu tarczy zegarka, pakiet Android App Bundle zawierający niestandardowy plik tarczy zegarka musi być całkowicie oddzielony od pakietu Android App Bundle, który zawiera logikę aplikacji na Wear OS. Niektóre sklepy z aplikacjami, w tym Google Play, nie pozwalają na przesyłanie pakietu Android App Bundle, który zawiera logikę Wear OS i niestandardową tarczę zegarka.

Tworzenie pakietu tarczy zegarka

Aby utworzyć pakiet aplikacji na Androida, który zawiera plik tarczy zegarka, wykonaj czynności opisane w poniższych sekcjach.

Oświadczenie o używaniu Formatu tarczy zegarka

W pliku manifestu nowej aplikacji (AndroidManifest.xml) dodaj właściwość aplikacji, która wskazuje na użycie Formatu tarczy zegarka. Jeśli nie chcesz ograniczać dostępu do tarczy zegarka na urządzeniach z Wear OS 5 lub nowszym, utwórz 2 różne pliki APK tarczy zegarka: jeden obsługujący wersję 2, a drugi – wersję 1. Dowiedz się więcej o konfigurowaniu wersji aplikacji.

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

Deklarowanie metadanych tarczy zegarka

W katalogu zasobów res/xml aplikacji utwórz nowy plik o nazwie watch_face_info.xml. Tutaj definiujesz metadane tarczy zegarka:

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

Pola w tym pliku odpowiadają tym informacjom:

Preview
Odwołuje się do pliku drawable zawierającego obraz podglądu tarczy zegarka.
Category

Definiuje kategorię tarczy zegarka. Musi to być ciąg znaków lub odwołanie do ciągu znaków, np. @string/ref_name. Każdy producent urządzenia może zdefiniować własny zbiór kategorii tarcz zegarka.

Wartość domyślna: empty_category_meta, która grupuje tę tarczę zegarka z innymi tarczami z „pustej kategorii” u dołu widoku selektora tarczy.

AvailableInRetail

Czy tarcza zegarka jest dostępna w trybie demo dla sklepów na urządzeniu. Musi być wartością logiczną lub odwołaniem do wartości logicznej, np. @bool/watch_face_available_in_retail.

Wartość domyślna: false

MultipleInstancesAllowed

czy tarcza może mieć wiele ulubionych; Musi być wartością logiczną lub odwołaniem do wartości logicznej, np. @bool/watch_face_multiple_instances_allowed.

Wartość domyślna: false

Editable

czy tarczę zegarka można edytować, co oznacza, że ma ona ustawienie lub co najmniej 1 widżet, który nie jest ustalony. Służy do wyświetlania lub ukrywania przycisku Edytuj na liście ulubionych.

Wartość domyślna: false

Zadeklaruj nazwę tarczy zegarka

W pliku manifestu aplikacji (AndroidManifest.xml) ustaw atrybut android:label na nazwę tarczy zegarka:

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

Deklarowanie szczegółów tarczy zegarka

Struktura podstawowego dokumentu tarczy zegarka w formacie WFF:

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

Podczas tworzenia tarczy zegarka (jeśli pracujesz z jedną tarczą) utwórz ten plik XML jako res/raw/watchface.xml. Aby obsługiwać różne kształty i rozmiary ekranu, opublikuj deklarację obsługi wielu kształtów i rozmiarów.

Element ROOT to zawsze WatchFace. Wartości height i width określają zakres przestrzeni współrzędnych do użycia na tarczy zegarka. Tarcza zegarka jest skalowana do rozmiaru urządzenia, na którym jest używana. Wartości height i width nie reprezentują rzeczywistych pikseli.

Format tarczy zegarka zawiera kilka informacji o niej:

  • Metadane, takie jak czas i liczba kroków wyświetlana na obrazie podglądu tarczy zegarka.
  • Konfiguracje użytkownika, takie jak różne motywy kolorystyczne tarczy zegarka, elementy, które użytkownik może włączać i wyłączać, oraz wybór spośród kilku elementów. W wersji 2 formatu tarczy zegarka wprowadzono wariacje, które mogą pojawiać się w konfiguracji użytkownika. Każda wersja określa wstępnie konfigurację użytkownika, określając typ i styl elementów, które wyświetlają się razem z czasem na tarczy zegarka. Te wstępnie zaprojektowane układy ułatwiają tworzenie estetycznych grup elementów. W aplikacji towarzyszącej Wear OS użytkownicy widzą różne wersje tarczy zegarka w kolumnie, którą można przewijać.
  • Scena zawierająca elementy wizualne tarczy zegarka. Elementy, które pojawiają się bliżej końca sceny, są nakładane na inne elementy, dlatego typowa kolejność jest następująca:
    • wskazówki w przypadku zegara analogowego lub tekst w przypadku zegara cyfrowego;
    • widżety, które wyświetlają dodatkowe informacje, takie jak dzień tygodnia lub liczba kroków użytkownika;
    • inne grafiki, które stanowią element dekoracyjny tarczy zegarka, np. obraz przedstawiający pole namiotowe;
  • Grupy elementów, które umożliwiają modyfikowanie wielu elementów jednocześnie. W ramach sceny możesz tworzyć warianty tych grup, co umożliwia selektywnie ukrywanie lub modyfikowanie treści, gdy system przechodzi w tryb oszczędzania energii.

Atrybuty mają ściśle określony typ i są objęte wskazówkami dotyczącymi częstotliwości i prawidłowych wartości, aby uniknąć większości źródeł błędów podczas tworzenia tarczy zegarka.

Deklarowanie obsługi kształtów tarcz zegarka (opcjonalnie)

Ten krok jest konieczny tylko wtedy, gdy chcesz obsługiwać różne rozmiary tarcz zegarka. Możesz pominąć ten krok, jeśli chcesz, aby tarcza zegarka dostosowywała się do rozmiaru zegarka.

W katalogu zasobów res/xml aplikacji zadeklaruj zestaw kształtów tarczy zegarka, które obsługujesz w komponencie 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>

Następnie określ wygląd i zachowanie tarczy zegarka dla każdego kształtu tarczy. Jeśli nie zdefiniujesz pliku kształtów, musisz utworzyć tylko 1 plik: watchface.xml.

W przykładzie z tej sekcji nieprzetworzone pliki XML wyglądają tak:

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

Identyfikacja wydawcy tarczy zegarka (opcjonalnie)

Opcjonalnie w pliku manifestu aplikacji możesz zadeklarować dowolny ciąg znaków, który posłuży do zidentyfikowania wydawcy tarczy zegarka lub nazwy i wersji narzędzia, którego używasz:

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

Sprawdzanie poprawności i wydajności tarczy zegarka

Podczas tworzenia i przed przesłaniem tarczy zegarka do Google Play użyj narzędzi weryfikujących, aby sprawdzić, czy tarcza zegarka nie zawiera błędów i czy jest zgodna z zaleceniami dotyczącymi wykorzystania pamięci.

Tworzenie pakietu aplikacji tarczy zegarka

Aby skompilować pakiet aplikacji na Androida zawierający tarczę zegarka, użyj systemu kompilacji Gradle. Dowiedz się więcej o tworzeniu aplikacji za pomocą Gradle.

Jest to pokazane w przykładach na GitHubie.