Dodaj widżety do tarczy zegarka

Widżet tarczy zegarka wyświetla dane ze źródła danych. Za pomocą Formatu tarczy zegarka możesz wybrać źródła danych, z których mają pochodzić dane. Dzięki temu tarcze zegarka mogą wyświetlać informacje inne niż godzina, bez konieczności korzystania z kodu do pobierania danych.

Używanie formatu tarczy zegarka

Element Complication umożliwia zdefiniowanie maksymalnie 8 widżetów na jednej tarczy zegarka. Pozwala też określić, gdzie na tarczy zegarka ma się wyświetlać dany widżet.

Więcej informacji znajdziesz w pliku WatchFaceFormat sample na GitHubie.

Typy i pola

W tabeli poniżej opisano typy i pola obiektu ComplicationData. Jeśli tarcza zegarka zażąda pola, które jest nieprawidłowe dla danego typu widżetu, zwrócona zostanie domyślna wartość tego pola. Jeśli na przykład tarcza zegarka próbuje uzyskać dostęp do pola LONG_TEXT typu SHORT_TEXT, zwracana jest domyślna wartość pola LONG_TEXT, czyli null. Pamiętaj, że nie ma gwarancji, że pola opcjonalne będą wyświetlane.





Typ Pola wymagane Pola opcjonalne Uwagi
SHORT_TEXT Krótki tekst Ikona
Ikona ochrony przed wypaleniem
Krótki tytuł
Opis treści

 Wyświetla tylko jedną ikonę lub krótki tytuł, jeśli podano jedną lub obie te opcje.
MONOCHROMATIC_IMAGE Monochromatyczny obraz
 Ikona ochrony przed wypaleniem pikseli
Opis treści

 Używana, gdy tekst nie jest potrzebny. Ikona powinna być jednokolorowa. Może być zabarwiona przez tarczę zegarka.
RANGED_VALUE Wartość
Wartość minimalna
Wartość maksymalna
 Monochromatyczne zdjęcie
Ikona ochrony przed wypaleniem
Krótki tekst
Krótki tytuł
Gradient kolorów
Wartość dynamiczna
Opis treści

 Jeśli chcesz narysować własny pasek postępu, możesz użyć metody isRangedValueProgressHidden(), aby ukryć pasek postępu udostępniany przez klasę ComplicationDrawable.
GOAL_PROGRESS Wartość
Wartość docelowa
 Monochromatyczne zdjęcie
Ikona ochrony przed wypaleniem
Krótki tekst
Krótki tytuł
Gradient kolorów
Wartość dynamiczna
Opis treści

 Wartość GOAL_PROGRESS jest przeznaczona do takich danych jak liczba kroków, gdzie wartość zaczyna się od 0 i może przekroczyć wartość docelową.
LONG_TEXT Długi tekst
 Długi tytuł
Jednobarwna grafika
ikona ochrony przed wypaleniem
Mała grafika
Opis treści
 Wyświetla długi tytuł, jeśli został podany.
SMALL_IMAGE Mały obraz
 Opis treści
 Małe zdjęcie może mieć jeden z 2 stylów: styl zdjęcia lub styl ikony. Styl zdjęcia oznacza, że ma ono wypełniać całą przestrzeń i można je przyciąć. Styl ikony oznacza, że nie można jej przyciąć, ale można dodać do niej obramowanie. Zmienne obrazy mogą być nieodpowiednie do wyświetlania w trybie nieaktywnym na urządzeniach z ochroną przed wypaleniem lub w trybie nieaktywnym o niskiej rozdzielczości. Gdy włączona jest ochrona przed wypaleniem lub tryb ambient z niskim bitem, tarcza zegarka może używać małego obrazu chroniącego przed wypaleniem, ponieważ jest to bezpieczne. W przeciwnym razie, ponieważ tarcza zegarka nie może określić, czy obraz jest odpowiedni, nie jest on wyświetlany.
LARGE_IMAGE Duży obraz
 Opis treści
 Obraz powinien być wystarczająco duży, aby wypełnić tarczę zegarka. Zmienne obrazy mogą być nieodpowiednie do wyświetlania w trybie nieaktywnym na urządzeniach z ochroną przed wypaleniem lub w trybie nieaktywnym o niskiej rozdzielczości. Zegarek nie może określić, czy wyświetlacz jest odpowiedni do wyświetlania. Dlatego nie wyświetla on obrazu w trybie nieaktywnym, jeśli włączona jest ochrona przed wypaleniem pikseli lub tryb nieaktywny o niskiej rozdzielczości.
WEIGHTED_ELEMENTS Lista elementów
 Monochromatyczne zdjęcie
Ikona ochrony przed wypaleniem
Krótki tekst
Krótki tytuł
Opis treści
 Każdy element składa się z koloru i wagi (większej niż zero). Rozmiar elementu po renderowaniu powinien być proporcjonalny do jego wagi. Wagi nie muszą się sumować do żadnej konkretnej wartości. Pamiętaj, że tarcze zegarka mogą zmieniać kolor elementów WEIGHTED_ELEMENTS.

W tabeli poniżej opisano typy pustych danych, które można wysyłać w dowolnym miejscu na komplikacje. Te typy nie mają pól i nie muszą być uwzględniane na liście obsługiwanych typów. Te typy umożliwiają tarczom zegarków rozróżnianie 3 sytuacji:

  • Nie wybrano źródła
  • Użytkownik wybrał „pusty” dla danego slotu.
  • Źródło nie ma danych do wysłania

Źródła nie mogą wysyłać TYPE_EMPTY w odpowiedzi na prośby o aktualizację. Zamiast tego wyślij TYPE_NO_DATA.

Typ widżetu Opis
TYPE_NOT_CONFIGURED Wysyłane przez system, gdy funkcja komplikacji jest aktywna, ale użytkownik nie wybrał źródła ani nie ustawił domyślnego.

Nie można wysyłać przez źródła.

TYPE_EMPTY Jest wysyłany przez system, gdy widżet jest aktywny, a użytkownik zamiast źródła wybierze „puste”, lub gdy tarcza zegarka nie wybierze źródła i typu widżetu jako domyślnego.

Nie można wysyłać przez źródła.

TYPE_NO_DATA Wysyłane przez system, gdy komplikacja z źródłem aktywuje się, aby ją wyczyścić, zanim otrzymane zostaną rzeczywiste dane ze źródła.

Mogą być wysyłane przez źródła, jeśli nie mają żadnych danych do wysłania.

Na niektórych urządzeniach tarcze i widżety muszą być zgodne z Formatem tarczy zegarka.

Jeśli Twoja dotychczasowa tarcza zegarka korzysta z biblioteki tarczy zegarka Jetpack lub biblioteki pomocy dla urządzeń do noszenia, użytkownicy nadal będą widzieć dane ze wszystkich źródeł danych w widżetach tarczy zegarka na tych urządzeniach:

  • Urządzenia z Wear OS 4 lub starszym.
  • Urządzenia, które otrzymają aktualizację OTA do Wear OS 5.

Jeśli istniejąca tarcza zegarka korzysta z biblioteki tarcz zegarka Jetpack lub Biblioteki pomocy dla urządzeń do noszenia i jest zainstalowana na jednym z tych urządzeń, nadal będzie otrzymywać aktualizacje.

Jednak na nowych zegarkach z Wear OS 5 tarcze muszą być zgodne z Formatem tarczy zegarka. Z tego powodu zalecamy przejście na format tarczy zegarka.