Konfiguracja formatu tarczy zegarka

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 tych 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 na Androida 13 (poziom API 33).

    Pakiet SDK zawiera też inne wymagane narzędzia, m.in. 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 aplikacji na Androida, który zawiera logikę Wear OS i niestandardową tarczę zegarka.

Tworzenie pakietu tarczy zegarka

Aby utworzyć pakiet Android App Bundle zawierający plik tarczy zegarka, wykonaj czynności opisane w sekcjach poniżej.

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.

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<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"
        ...>
        <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 możesz określić metadane tarczy zegarka:

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

Pola w tym pliku reprezentują te informacje:

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 określić własny zestaw kategorii tarcz zegarka.

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

AvailableInRetail

Czy tarcza zegarka jest dostępna w trybie demo dla sklepów. 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 pokazywania lub ukrywania przycisku Edytuj przy tarczy zegarka 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 obsługi kształtów tarczy 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 aplikacji res/xml zadeklaruj zestaw tarcz zegarka, które obsługujesz w zasadzie watch_face_shapes.xml:

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

Deklarowanie szczegółów tarczy zegarka

W katalogu zasobów res/raw aplikacji utwórz pliki odpowiadające wartościom atrybutów file używanych podczas deklarowania obsługi kształtów tarczy zegarka.

Tutaj definiujesz 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 przypadku przykładu na tej stronie pliki XML w postaci surowych danych wyglądałyby tak:

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

Element główny to zawsze WatchFace:

<WatchFace width="450" height="450" clipShape="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>

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

Sprawdzanie poprawności i wydajności tarczy zegarka

Podczas tworzenia tarczy zegarka i przed przesłaniem jej do Google Play użyj narzędzi weryfikacyjnych, aby sprawdzić, czy tarcza 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, który zawiera tarczę zegarka, użyj systemu kompilacji Gradle. Dowiedz się więcej o tworzeniu aplikacji za pomocą Gradle.

Przykłady takiego działania znajdziesz w przykładach kodu na GitHubie.