Daten für Zusatzfunktionen bereitstellen

Zusatzfunktionsdatenquellen stellen Informationen für Zusatzfunktionen auf dem Zifferblatt bereit und 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. Damit auf die Aktualisierungsanfragen reagiert werden kann, muss in der 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 Auswahl für Komplikationen 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 Aktualisierungen der Daten 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, der vom System erzwungen wird, um die Akkulaufzeit des Geräts zu schonen. Außerdem werden Aktualisierungsanfragen seltener gesendet, wenn sich das Gerät im Ambient-Modus 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 Complication-Slot 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 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.

Aktualisiere eine Komplikation 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 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 wie folgt:

  • Wenn die aktuelle Zeit zwischen der Start- und Endzeit eines Eintrags auf der Zeitachse liegt, 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 Werte sind direkt auf der Plattform verfügbar. 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 Anbieter der Komplikation ausgeführt werden muss.

Beispielfelder sind GoalProgressComplicationData und DynamicComplicationText, die in jedem ComplicationText-Feld verwendet werden können. Diese dynamischen Werte basieren auf der androidx.wear.protolayout.expression-Bibliothek.

In bestimmten Situationen kann die Plattform dynamische Werte nicht auswerten:

  • Dynamischer Wert ist manchmal nicht verfügbar : Das passiert beispielsweise, wenn das Gerät nicht am Handgelenk getragen wird. In diesen Fällen verwendet die Plattform stattdessen den Wert des -Felds für den Fallback bei ungültigen dynamischen Werten in einem -Platzhalterfeld von NoDataComplicationData.
  • Dynamischer Wert ist nie verfügbar : Dies geschieht auf einem Gerät, auf dem eine ältere Version von Wear OS 4 ausgeführt wird. In diesem Fall verwendet die Plattform ein Companion-Fallback-Feld, z. B. getFallbackValue().