Daten für Zusatzfunktionen bereitstellen

Datenquellen für Zusatzfunktionen stellen Informationen für Zusatzfunktionen auf dem Zifferblatt bereit, z. B. Text, Bilder und Zahlen, die auf dem Zifferblatt gerendert werden können.

Ein Datenquellendienst erweitert SuspendingComplicationDataSourceService, um nützliche Informationen direkt an ein Zifferblatt zu senden.

Erste Schritte

Fügen Sie Ihrem App-Modul die folgende Abhängigkeit hinzu: 

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

Datenquellendienst erstellen

Wenn Komplikationsdaten benötigt werden, sendet das Wear OS-System Aktualisierungsanfragen an Ihre Datenquelle. Damit Ihre Datenquelle auf die Aktualisierungsanfragen reagieren kann, muss sie die Methode onComplicationRequest() der Klasse SuspendingComplicationDataSourceService implementieren.

Das Wear OS-System ruft onComplicationRequest() auf, wenn es Daten aus deiner Quelle benötigt, z. B. wenn eine Komplikation, die deine Datenquelle verwendet, aktiv wird oder wenn eine bestimmte Zeitspanne verstrichen ist.

Hinweis:Wenn deine Datenquelle Daten bereitstellt, erhält das Zifferblatt die Rohwerte. Das Zifferblatt ist für die Formatierung der Daten für die Anzeige verantwortlich.

Das folgende Code-Snippet zeigt eine Beispielimplementierung:

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

    // ...
}

Manifestdeklarationen und Berechtigungen

Datenquellen müssen bestimmte Deklarationen in ihrem App-Manifest enthalten, damit sie vom Android-System als Datenquelle behandelt werden. In diesem Abschnitt werden die erforderlichen Einstellungen für Datenquellen erläutert.

Deklarieren Sie den Dienst im Manifest Ihrer App und fügen Sie einen Intent-Filter für die Aktualisierungsanfrage hinzu. Das Manifest muss den Dienst auch schützen, indem die Berechtigung BIND_COMPLICATION_PROVIDER hinzugefügt wird, damit nur das Wear OS-System eine Bindung an Anbieterdienste vornehmen kann.

Füge außerdem ein android:icon-Attribut in das service-Element ein, das ein einfarbiges weißes Symbol bereitstellt. Wir empfehlen Vektor-Drawables für die Symbole. Das Symbol stellt die Datenquelle dar und wird in der Auswahl für Zusatzfunktionen angezeigt.

Beispiel: 

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

Metadatenelemente

In Ihrer Manifestdatei finden Sie die folgenden Metadatenelemente:

  • android:name="android.support.wearable.complications.SUPPORTED_TYPES": Gibt die Arten von Zusatzfunktionsdaten an, die von der Datenquelle unterstützt werden.
  • android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS": Gibt an, wie oft das System nach Aktualisierungen der Daten suchen soll.

Wenn die Datenquelle für die Komplikationsdaten aktiv ist, gibt UPDATE_PERIOD_SECONDS an, wie oft das System nach Aktualisierungen der Daten suchen soll. Wenn die in der Zusatzfunktion angezeigten Informationen nicht regelmäßig aktualisiert werden müssen, z. B. wenn du Push-Updates verwendest, setze diesen Wert auf 0.

Wenn du UPDATE_PERIOD_SECONDS nicht auf 0 setzt, musst du einen Wert von mindestens 300 (5 Minuten) verwenden. Das ist der Mindestaktualisierungszeitraum, den das System erzwingt, um den Akku des Geräts zu schonen. Außerdem werden Aktualisierungsanfragen seltener gesendet, wenn sich das Gerät im Inaktivmodus befindet oder nicht getragen wird.

Konfigurationsaktivität hinzufügen

Bei Bedarf kann eine Datenquelle eine Konfigurationsaktivität enthalten, die dem Nutzer angezeigt wird, wenn er diese Datenquelle in der Auswahl für Zusatzfunktionen auswählt. Eine Datenquelle für eine Weltzeituhr könnte beispielsweise eine Konfigurationsaktivität haben, mit der der Nutzer die anzuzeigende Stadt oder Zeitzone auswählen kann.

Das Beispielmanifest enthält ein meta-data-Element mit dem Schlüssel PROVIDER_CONFIG_ACTION. Der Wert dieses Elements ist die Aktion, mit der die Konfigurationsaktivität gestartet wird.

Erstelle die Konfigurationsaktivität und füge in deiner Manifestdatei einen Intent-Filter hinzu, der der Aktion für die Aktivität entspricht. 

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

Die Aktivität kann Details zum Bereich für die Zusatzfunktion, den sie konfiguriert, aus dem Intent in der Methode onCreate() der Aktivität abrufen: 

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

Die Konfigurationsaktivität muss sich im selben Paket wie der Anbieter befinden. Die Konfigurationsaktivität muss RESULT_OK oder RESULT_CANCELED zurückgeben, um dem System mitzuteilen, ob die Datenquelle festgelegt werden soll: 

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

Push-Updates verwenden

Alternativ zur Angabe eines Aktualisierungsintervalls im Manifest Ihrer App können Sie eine Instanz von ComplicationDataSourceUpdateRequester verwenden, um Aktualisierungen dynamisch zu initiieren. Wenn Sie eine Aktualisierung anfordern möchten, rufen Sie requestUpdate() auf.

Achtung:Um die Akkulaufzeit des Geräts zu verlängern, solltest du requestUpdate() nicht öfter als alle 5 Minuten im Durchschnitt von deiner Instanz von ComplicationDataSourceUpdateRequester aufrufen.

Zeitabhängige Werte angeben

Bei einigen Zusatzfunktionen muss ein Wert angezeigt werden, der sich auf die aktuelle Uhrzeit bezieht. Beispiele sind das aktuelle Datum, die Zeit bis zum nächsten Termin oder die Uhrzeit in einer anderen Zeitzone.

Aktualisiere eine Komplikation nicht jede Sekunde oder Minute, um diese Werte auf dem neuesten Stand zu halten. Geben Sie die Werte stattdessen relativ zum aktuellen Datum oder zur aktuellen Uhrzeit an, indem Sie zeitabhängigen Text verwenden. Mit den folgenden Klassen können Sie diese zeitabhängigen Werte erstellen:

Zeitachsendaten

Verwende für Datenquellen für Zusatzfunktionen, die eine Sequenz von Werten zu vordefinierten Zeiten bereitstellen, SuspendingTimelineComplicationDataSourceService.

Ein Beispiel hierfür wäre eine Datenquelle für das „nächste Ereignis“ aus einer Kalender-App: Anstatt dass das System die Datenquelle regelmäßig nach dem nächsten Ereignis abfragen muss, kann die Datenquelle einmal eine Zeitachse mit Ereignissen bereitstellen und dann Aktualisierungen initiieren, wenn sich der Kalender ändert. Dadurch wird die Belastung des Systems minimiert und die Komplikation kann das richtige Ereignis rechtzeitig anzeigen: 

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

    // ...
}

Das Verhalten von SuspendingTimelineComplicationDataSourceService ist so:

  • Wenn die aktuelle Zeit zwischen der Start- und Endzeit eines Eintrags in der Zeitachse liegt, verwendet das Zifferblatt diesen Wert.
  • Wenn die aktuelle Zeit in keinen Eintrag der Zeitachse fällt, wird der Standardwert verwendet. In der Kalender-App könnte dies beispielsweise „Kein Termin“ sein.
  • Wenn die aktuelle Zeit in mehrere Ereignisse fällt, wird das kürzeste Ereignis verwendet.

Dynamische Werte angeben

Ab Wear OS 4 können einige Komplikationen Werte anzeigen, die häufiger aktualisiert werden, basierend auf Werten, die direkt auf der Plattform verfügbar sind. Wenn du diese Funktion in deinen Zusatzfunktionen anbieten möchtest, verwende ComplicationData-Felder, die dynamische Werte akzeptieren. Die Plattform wertet diese Werte häufig aus und aktualisiert sie, ohne dass der Anbieter der Zusatzfunktion ausgeführt werden muss.

Beispielfelder sind das dynamische Wertfeld von GoalProgressComplicationData und DynamicComplicationText, das in jedem ComplicationText-Feld verwendet werden kann. Diese dynamischen Werte basieren auf der Bibliothek androidx.wear.protolayout.expression.

In bestimmten Situationen kann die Plattform dynamische Werte nicht auswerten: