Narażenie danych na widżety

Źródła danych widżetów udostępniają informacje widżetom na tarczy zegarka, dostarczając tekst, obrazy i liczby, które tarcza może renderować.

Usługa źródła danych rozszerza SuspendingComplicationDataSourceService, aby dostarczać przydatne informacje bezpośrednio na tarczę zegarka.

Pierwsze kroki

Dodaj do modułu aplikacji tę zależność: 

dependencies {
  implementiation("androidx.wear.watchface:watchface-complications-data-source-ktx:1.2.1")
}

Tworzenie usługi źródła danych

Gdy potrzebne są dane widżetu, system Wear OS wysyła prośby o aktualizację do źródła danych. Aby odpowiadać na żądania aktualizacji, źródło danych musi implementować metodę onComplicationRequest() klasy SuspendingComplicationDataSourceService.

System Wear OS wywołuje metodę onComplicationRequest(), gdy potrzebuje danych ze źródła – na przykład gdy widżet korzystający z Twojego źródła danych staje się aktywny lub gdy upłynie określony czas.

Uwaga: gdy źródło danych dostarcza dane, tarcza zegarka otrzymuje nieprzetworzone wartości. Tarcza zegarka odpowiada za formatowanie danych do wyświetlenia.

Poniższy fragment kodu pokazuje przykładową implementację:

class MyComplicationDataSourceService : SuspendingComplicationDataSourceService() {
    override suspend fun onComplicationRequest(request: ComplicationRequest): ComplicationData? {
        // Retrieve the latest info for inclusion in the data.
        val text = getLatestData()
        return shortTextComplicationData(text)
    }

    override fun getPreviewData(type: ComplicationType): ComplicationData? {
        return shortTextComplicationData("Event 1")
    }

    private fun shortTextComplicationData(text: String) =
        ShortTextComplicationData.Builder(
            text = PlainComplicationText.Builder(text).build(),
            contentDescription = PlainComplicationText.Builder(text).build()
        )
            // Add further optional details here such as icon, tap action, and title.
            .build()

    // ...
}

Deklaracje i uprawnienia w pliku manifestu

Źródła danych muszą zawierać w pliku manifestu aplikacji określone deklaracje, aby system Android traktował je jako źródła danych. W tej sekcji opisujemy wymagane ustawienia źródeł danych.

W pliku manifestu aplikacji zadeklaruj usługę i dodaj filtr intencji działania żądania aktualizacji. Plik manifestu musi też chronić usługę, dodając uprawnienie BIND_COMPLICATION_PROVIDER, aby tylko system Wear OS mógł wiązać się z usługami dostawcy.

Dodaj też atrybut android:icon w elemencie service, który zawiera jednokolorową białą ikonę. W przypadku ikon zalecamy obiekty rysowalne wektorowo. Ikona reprezentuje źródło danych i jest wyświetlana w selektorze widżetów.

Oto przykład: 

<service
    android:name=".snippets.complication.MyComplicationDataSourceService"
    android:exported="true"
    android:label="@string/my_complication_service_label"
    android:icon="@drawable/complication_icon"
    android:permission="com.google.android.wearable.permission.BIND_COMPLICATION_PROVIDER">
    <intent-filter>
        <action android:name="android.support.wearable.complications.ACTION_COMPLICATION_UPDATE_REQUEST" />
    </intent-filter>

    <!-- Supported types should be comma-separated, for example: "SHORT_TEXT,SMALL_IMAGE" -->
    <meta-data
        android:name="android.support.wearable.complications.SUPPORTED_TYPES"
        android:value="SHORT_TEXT" />
    <meta-data
        android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS"
        android:value="300" />

    <!-- Optionally, specify a configuration activity, where the user can configure your complication. -->
    <meta-data
        android:name="android.support.wearable.complications.PROVIDER_CONFIG_ACTION"
        android:value="MY_CONFIG_ACTION" />

</service>

Elementy metadanych

W pliku manifestu zwróć uwagę na te elementy metadanych:

  • android:name="android.support.wearable.complications.SUPPORTED_TYPES": określa typy danych widżetu obsługiwane przez źródło danych.
  • android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS": określa, jak często system powinien sprawdzać dostępność aktualizacji danych.

Gdy źródło danych widżetu jest aktywne, UPDATE_PERIOD_SECONDS określa, jak często system ma sprawdzać dostępność aktualizacji danych. Jeśli informacje wyświetlane w widżecie nie muszą być regularnie aktualizowane, np. gdy używasz aktualizacji push, ustaw tę wartość na 0.

Jeśli nie ustawisz parametru UPDATE_PERIOD_SECONDS na 0, musisz użyć wartości co najmniej 300 (5 minut), która jest minimalnym okresem aktualizacji wymaganym przez system w celu oszczędzania baterii urządzenia. Pamiętaj też, że prośby o aktualizację są wysyłane rzadziej, gdy urządzenie jest w trybie nieaktywnym lub nie jest noszone.

Dodawanie aktywności związanej z konfiguracją

W razie potrzeby źródło danych może zawierać aktywność konfiguracyjną, która jest wyświetlana użytkownikowi, gdy wybierze on to źródło danych w selektorze widżetów. Na przykład źródło danych zegara światowego może mieć aktywność konfiguracji, która pozwala użytkownikowi wybrać miasto lub strefę czasową do wyświetlenia.

Przykładowy plik manifestu zawiera element meta-data z kluczem PROVIDER_CONFIG_ACTION. Wartością tego elementu jest działanie, które służy do uruchamiania aktywności konfiguracyjnej.

Utwórz aktywność konfiguracji i dodaj filtr intencji, który pasuje do działania w pliku manifestu. 

<intent-filter>
    <action android:name="MY_CONFIG_ACTION" />
    <category android:name="android.support.wearable.complications.category.PROVIDER_CONFIG" />
    <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

Aktywność może uzyskać szczegółowe informacje o konfigurowanym miejscu na widżet z intencji w metodzie onCreate() aktywności: 

// Keys defined on ComplicationDataSourceService
val id = intent.getIntExtra(EXTRA_CONFIG_COMPLICATION_ID, -1)
val type = intent.getIntExtra(EXTRA_CONFIG_COMPLICATION_TYPE, -1)
val source = intent.getStringExtra(EXTRA_CONFIG_DATA_SOURCE_COMPONENT)

Aktywność konfiguracji musi znajdować się w tym samym pakiecie co dostawca. Aktywność konfiguracji musi zwracać RESULT_OK lub RESULT_CANCELED, aby poinformować system, czy źródło danych powinno być ustawione: 

setResult(RESULT_OK) // Or RESULT_CANCELED to cancel configuration
finish()

Używanie aktualizacji push

Zamiast określać interwał aktualizacji w pliku manifestu aplikacji, możesz użyć instancji ComplicationDataSourceUpdateRequester, aby dynamicznie inicjować aktualizacje. Aby poprosić o aktualizację, zadzwoń pod numer requestUpdate().

Uwaga: aby wydłużyć czas pracy baterii urządzenia, nie wywołuj requestUpdate() z instancji ComplicationDataSourceUpdateRequester częściej niż średnio co 5 minut.

Podawanie wartości zależnych od czasu

Niektóre widżety muszą wyświetlać wartość związaną z bieżącym czasem. Może to być na przykład bieżąca data, czas do następnego spotkania lub godzina w innej strefie czasowej.

Nie aktualizuj widżetu co sekundę ani co minutę, aby zachować aktualność tych wartości. Zamiast tego określ wartości względem bieżącej daty lub godziny, używając tekstu zależnego od czasu. Te klasy umożliwiają tworzenie wartości zależnych od czasu:

dane z osi czasu;

W przypadku źródeł danych widżetów, które dostarczają sekwencję wartości w określonych godzinach, użyj SuspendingTimelineComplicationDataSourceService.

Przykładem może być źródło danych „następne wydarzenie” z aplikacji kalendarza: zamiast regularnego odpytywania źródła danych przez system o następne wydarzenie, źródło danych może jednorazowo podać oś czasu wydarzeń, a następnie zainicjować aktualizacje, jeśli kalendarz się zmieni. Minimalizuje to obciążenie systemu i pozwala widżetowi wyświetlać właściwe wydarzenie we właściwym czasie: 

class MyTimelineComplicationDataSourceService : SuspendingTimelineComplicationDataSourceService() {
    override suspend fun onComplicationRequest(request: ComplicationRequest): ComplicationDataTimeline? {
        if (request.complicationType != ComplicationType.SHORT_TEXT) {
            return ComplicationDataTimeline(
                defaultComplicationData = NoDataComplicationData(),
                timelineEntries = emptyList()
            )
        }
        // Retrieve list of events from your own datasource / database.
        val events = getCalendarEvents()
        return ComplicationDataTimeline(
            defaultComplicationData = shortTextComplicationData("No event"),
            timelineEntries = events.map {
                TimelineEntry(
                    validity = TimeInterval(it.start, it.end),
                    complicationData = shortTextComplicationData(it.name)
                )
            }
        )
    }

    override fun getPreviewData(type: ComplicationType): ComplicationData? {
        return shortTextComplicationData("Event 1")
    }

    private fun shortTextComplicationData(text: String) =
        ShortTextComplicationData.Builder(
            text = PlainComplicationText.Builder(text).build(),
            contentDescription = PlainComplicationText.Builder(text).build()
        )
            // Add further optional details here such as icon, tap action, title etc
            .build()

    // ...
}

Działanie SuspendingTimelineComplicationDataSourceService wygląda następująco:

  • Gdy bieżący czas mieści się w zakresie czasu rozpoczęcia i zakończenia wpisu na osi czasu, tarcza zegarka używa tej wartości.
  • Jeśli bieżący czas nie mieści się w żadnym wpisie na osi czasu, używana jest wartość domyślna. Na przykład w aplikacji kalendarza może to być „Brak wydarzenia”.
  • Jeśli bieżący czas przypada na kilka wydarzeń, używane jest najkrótsze wydarzenie.

Podawanie wartości dynamicznych

Począwszy od Wear OS 4, niektóre widżety mogą wyświetlać wartości, które odświeżają się częściej na podstawie wartości dostępnych bezpośrednio na platformie. Aby zapewnić tę funkcję w widżetach, użyj pól ComplicationData, które akceptują wartości dynamiczne. Platforma często ocenia i aktualizuje te wartości bez konieczności uruchamiania dostawcy widżetu.

Przykładowe pola to pole wartości dynamicznej GoalProgressComplicationData i DynamicComplicationText, którego można użyć w dowolnym polu ComplicationText. Te wartości dynamiczne są oparte na bibliotece androidx.wear.protolayout.expression.

W niektórych sytuacjach platforma nie może ocenić wartości dynamicznych: