Daten für Zusatzfunktionen bereitstellen

Zusatzfunktionsdatenquellen stellen Informationen für Zusatzfunktionen auf dem Zifferblatt bereit. Sie liefern Text, Bilder und Zahlen, die auf dem Zifferblatt gerendert werden können.

Ein Datenquellendienst erweitert SuspendingComplicationDataSourceService, um nützliche Informationen direkt auf einem Zifferblatt bereitzustellen.

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. Um auf die Aktualisierungsanfragen zu reagieren, muss in Ihrer Datenquelle die Methode onComplicationRequest() der Klasse SuspendingComplicationDataSourceService implementiert sein.

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

Hinweis:Wenn Ihre 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 Aktualisierungsanfrageaktion 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ügen Sie außerdem dem service-Element ein android:icon-Attribut hinzu, das ein einfarbig weißes Symbol enthält. Wir empfehlen Vektordrawables für die Symbole. Das Symbol steht für die Datenquelle und wird in der Komplikationsauswahl 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

Beachten Sie in Ihrer Manifestdatei die folgenden Metadatenelemente:

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

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

Wenn Sie UPDATE_PERIOD_SECONDS nicht auf 0 festlegen, müssen Sie einen Wert von mindestens 300 (5 Minuten) verwenden. Dies ist der Mindestaktualisierungszeitraum, den das System erzwingt, um die Akkulaufzeit 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 Komplikationen auswählt. Eine Weltuhr-Datenquelle kann 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, die zum Starten der Konfigurationsaktivität verwendet wird.

Erstellen Sie die Konfigurationsaktivität und fügen Sie einen Intent-Filter hinzu, der der Aktion dafür in Ihrer Manifestdatei 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 zu konfigurierenden Zifferblatttyp 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 zum Angeben eines Aktualisierungsintervalls im Manifest Ihrer App können Sie eine Instanz von ComplicationDataSourceUpdateRequester verwenden, um Aktualisierungen dynamisch zu starten. Wenn Sie ein Update anfordern möchten, rufen Sie requestUpdate() an.

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

Zeitabhängige Werte angeben

Einige Komplikationen müssen einen Wert anzeigen, der sich auf die aktuelle Uhrzeit bezieht. Beispiele sind das aktuelle Datum, die Zeit bis zur nächsten Besprechung oder die Uhrzeit in einer anderen Zeitzone.

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

Zeitachsendaten

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

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 Systemlast 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 wie folgt:

  • Wenn die aktuelle Zeit in den Start- und Endzeitpunkt eines Eintrags auf der Zeitachse fällt, verwendet das Zifferblatt diesen Wert.
  • Wenn die aktuelle Zeit nicht in einen Eintrag auf der Zeitachse fällt, wird der Standardwert verwendet. In der Kalender App könnte das 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 in einigen Komplikationen Werte angezeigt werden, die häufiger aktualisiert werden. Die Aktualisierung basiert auf Werten, die direkt auf der Plattform verfügbar sind. Wenn Sie diese Funktion in Ihren Komplikationen anbieten möchten, verwenden Sie ComplicationData-Felder, die dynamische Werte akzeptieren. Die Plattform wertet diese Werte häufig aus und aktualisiert sie, ohne dass der Komplikationsanbieter ausgeführt werden muss.

Beispielfelder sind das GoalProgressComplicationData-Feld für dynamische Werte 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: