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 przykładzie WatchFaceFormat 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 opcjonalne pola będą się wyświetlać.





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
 Obraz monochromatyczny
Ikona ochrony przed wypaleniem
Krótki tekst
Krótki tytuł
Ramka kolorów
Wartość dynamiczna
Opis treści

 Parametr GOAL_PROGRESS jest przeznaczony do takich wartości jak liczba kroków, gdzie wartość zaczyna się od 0 i może przekroczyć wartość docelową.
LONG_TEXT Długi tekst
 Długi tytuł
Obraz monochromatyczny
Ikona ochrony przed przepaleniem
Mały obraz
Opis treści
 Wyświetla długi tytuł, jeśli został podany.
SMALL_IMAGE Mały obraz
 Opis treści
 Mały obraz 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 go przyciąć i można go wypełnić. 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ż trudno jest tarczy zegarka określić, czy obraz jest odpowiedni, obraz nie jest wyświetlany.
LARGE_IMAGE Duży obraz
 Opis treści
 Ten obraz powinien być wystarczająco duży, aby wypełnić całą tarczę zegarka. Zmienność obrazu może spowodować, że obraz nie będzie odpowiedni do wyświetlenia w trybie nieaktywnym na urządzeniach z ochroną przed wypaleniem lub w niskim trybie nieaktywnym. Tarcza zegarka trudno określić, czy jest odpowiedni do wyświetlenia, dlatego nie wyświetla obrazu w trybie nieaktywnym, jeśli włączona jest ochrona przed wypaleniem pikseli lub włączenie ładunków otoczenia.
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 kolorów 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 można zmienić kolor tarczy zegarka na 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ą żadnych pól i nie muszą być uwzględnione 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ł „puste” 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 Wysłany przez system, gdy widżet aktywuje się, ale użytkownik nie wybierze źródła i nie ustawiono żadnej wartości domyślnej.

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ć ze źródeł.

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 zegarka i widżety muszą używać Formatu tarczy zegarka.

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

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