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 będą pobierane dane podstawowe. Dzięki temu tarcze zegarka mogą wyświetlać informacje inne niż godzina bez konieczności używania kodu do pobierania danych.

Używanie formatu tarczy zegarka

Element Complication umożliwia zdefiniowanie maksymalnie 8 widżetów na jednej tarczy zegarka. Ten element umożliwia też określenie, w którym miejscu tarczy zegarka ma się wyświetlać każdy widżet.

Więcej informacji znajdziesz w przykładzie formatu tarczy zegarka w GitHubie.

Typy i pola

W tabeli poniżej opisujemy typy i pola obiektu ComplicationData. Jeśli tarcza zegarka zażąda pola, które jest nieprawidłowe dla typu komplikacji, zwracana jest domyślna wartość tego pola. Jeśli na przykład tarcza zegarka próbuje uzyskać dostęp do pola LONG_TEXT w typie SHORT_TEXT, zwracana jest wartość domyślna pola LONG_TEXT, czyli null. Pamiętaj, że wyświetlanie pól opcjonalnych nie jest gwarantowane.





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 jedno z nich lub oba.
MONOCHROMATIC_IMAGE Obraz monochromatyczny
 Ikona ochrony przed wypaleniem pikseli
Opis treści

 Używane, gdy tekst nie jest potrzebny. Ikona powinna być jednokolorowa i może być przyciemniona przez tarczę zegarka.
RANGED_VALUE Wartość
Wartość minimalna
Wartość maksymalna
 Obraz monochromatyczny
Ikona ochrony przed wypaleniem
Krótki tekst
Krótki tytuł
Rampa 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 ComplicationDrawable.
GOAL_PROGRESS Wartość
Wartość docelowa
 Obraz monochromatyczny
Ikona ochrony przed wypaleniem
Krótki tekst
Krótki tytuł
Rampa kolorów
Wartość dynamiczna
Opis treści

 GOAL_PROGRESS jest przeznaczony do takich danych jak liczba kroków, w przypadku których wartość zaczyna się od zera i może przekroczyć wartość docelową.
LONG_TEXT Długi tekst
 Długi tytuł
Obraz monochromatyczny
Ikona ochrony przed wypaleniem
Mały obraz
Opis treści
 Wyświetla długi tytuł, jeśli jest 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ć przestrzeń i może zostać przycięte. Styl ikony oznacza, że nie można jej przyciąć, ale można dodać do niej dopełnienie. Zmienność obrazu może powodować, że obraz nie będzie odpowiedni do wyświetlania w trybie otoczenia na urządzeniach z ochroną przed wypaleniem lub z trybem otoczenia o niskiej liczbie bitów. Gdy ochrona przed wypaleniem lub tryb otoczenia o niskiej liczbie bitów jest włączony, tarcza zegarka może używać małego obrazu ochrony przed wypaleniem, ponieważ jest bezpieczny. W przeciwnym razie obraz nie jest wyświetlany, ponieważ zegarek nie jest w stanie określić, czy jest on odpowiedni.
LARGE_IMAGE Duży obraz
 Opis treści
 Obraz powinien być wystarczająco duży, aby wypełnić tarczę zegarka. Zmienność obrazu może powodować, że obraz nie będzie odpowiedni do wyświetlania w trybie otoczenia na urządzeniach z ochroną przed wypaleniem lub z trybem otoczenia o niskiej liczbie bitów. Ponieważ tarcza zegarka nie może określić, czy obraz nadaje się do wyświetlania, nie wyświetla go w trybie nieaktywnym, jeśli włączona jest ochrona przed wypaleniem pikseli lub tryb nieaktywny o niskiej liczbie bitów.
WEIGHTED_ELEMENTS Lista elementów
 Obraz monochromatyczny
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 wyrenderowaniu powinien być proporcjonalny do jego wagi. Suma wag nie musi wynosić określonej wartości. Pamiętaj, że tarcze zegarka mogą zmieniać kolor elementów WEIGHTED_ELEMENTS.

W tabeli poniżej znajdziesz opis typów danych dodatkowych dla pustych danych, które można wysyłać w przypadku dowolnego miejsca na dane dodatkowe. Te typy nie mają pól i nie muszą być uwzględniane na liście obsługiwanych typów. Te typy umożliwiają tarczom zegarka rozróżnianie tych 3 przypadków:

  • Nie wybrano źródła
  • Użytkownik wybrał „pusty” dla miejsca
  • Ź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ę. Wyślij TYPE_NO_DATA.

Typ widżetu Opis
TYPE_NOT_CONFIGURED Wysyłany przez system, gdy widżet się aktywuje, ale użytkownik nie wybrał źródła i nie ustawiono wartości domyślnej.

Nie można wysyłać z źródeł.

TYPE_EMPTY Wysyłany przez system, gdy widżet się aktywuje, a użytkownik wybierze opcję „pusty” zamiast źródła lub gdy tarcza zegarka nie wybierze źródła i ustawi ten typ widżetu jako domyślny.

Nie można wysyłać z źródeł.

TYPE_NO_DATA Wysyłany przez system, gdy widżet, który ma źródło, aktywuje się, aby wyczyścić widżet przed otrzymaniem rzeczywistych danych ze źródła.

Może być wysyłany przez źródła, jeśli nie mają one do wysłania żadnych rzeczywistych danych.

Na niektórych urządzeniach tarcze zegarka i widżety muszą korzystać z Formatu tarczy zegarka

Jeśli Twoja obecna tarcza zegarka korzysta z biblioteki tarcz 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 Twoja obecna tarcza zegarka korzysta z biblioteki Jetpack Watch Face lub Biblioteki pomocy dla urządzeń do noszenia i jest zainstalowana na jednym z tych urządzeń, może nadal otrzymywać aktualizacje.

Na nowych zegarkach z Wear OS 5 tarcze zegarka muszą jednak korzystać z Formatu tarczy zegarka. Z tego powodu zalecamy przejście na format tarczy zegarka.