Daten für Zusatzfunktionen bereitstellen

Datenquellen für Zusatzfunktionen stellen Informationen für Zifferblatt Zusatzfunktionen 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 Daten für Zusatzfunktionen benötigt werden, sendet das Wear OS-System Aktualisierungsanfragen an Ihre Datenquelle. Um auf die Aktualisierungsanfragen zu antworten, muss Ihre Datenquelle die onComplicationRequest() Methode der SuspendingComplicationDataSourceService Klasse implementieren.

Das Wear OS-System ruft onComplicationRequest() auf, wenn Daten aus Ihrer Datenquelle benötigt werden, z. B. wenn eine Zusatzfunktion, 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 zur Anzeige verantwortlich.

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

    // ...
}
MyComplicationDataSourceService.kt

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 BIND_COMPLICATION_PROVIDER Berechtigung hinzugefügt wird, damit nur das Wear OS-System eine Verbindung zu Anbieterdiensten herstellen kann.

Fügen Sie außerdem ein android:icon Attribut im service Element hinzu, das ein einfarbiges weißes Symbol bereitstellt. Wir empfehlen Vektorgrafiken 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>
AndroidManifest.xml

Metadatenelemente

Beachten Sie in Ihrer Manifestdatei die folgenden Metadatenelemente:

  • android:name="android.support.wearable.complications.SUPPORTED_TYPES": Gibt die Arten von Daten für Zusatzfunktionen 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 Ihre Datenquelle für Daten für Zusatzfunktionen aktiv ist, UPDATE_PERIOD_SECONDS gibt 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 Sie Push-Aktualisierungen 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 verlängern. Außerdem werden Aktualisierungsanfragen seltener gesendet, wenn sich das Gerät im Umgebungsmodus 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 kann beispielsweise eine Konfiguration Aktivität haben, mit der der Nutzer die anzuzeigende Stadt oder Zeitzone auswählen kann.

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

Erstellen Sie die Konfigurationsaktivität und fügen Sie einen Intent-Filter hinzu, der der Aktion 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>
AndroidManifest.xml

Die Aktivität kann Details zum konfigurierten Zusatzfunktionsplatz aus dem Intent innerhalb der onCreate() Methode 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)
ConfigurationActivity.kt

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()
ConfigurationActivity.kt

Push-Aktualisierungen verwenden

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

Achtung: Um die Akkulaufzeit des Geräts zu verlängern, rufen Sie requestUpdate() nicht häufiger als durchschnittlich alle 5 Minuten aus Ihrer Instanz von ComplicationDataSourceUpdateRequester auf.

Zeitabhängige Werte bereitstellen

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

Aktualisieren Sie eine Zusatzfunktion nicht jede Sekunde oder Minute, um diese Werte auf dem neuesten Stand zu halten. Geben Sie stattdessen die Werte 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

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

Ein Beispiel hierfür ist eine Datenquelle für den nächsten Termin aus einer Kalender-App: Anstatt dass das System die Datenquelle regelmäßig nach dem nächsten Termin abfragen muss, kann die Datenquelle einmal eine Zeitachse von Terminen bereitstellen und dann die Datenquelle Aktualisierungen initiieren, wenn sich der Kalender ändert. Dadurch wird die Last auf dem System minimiert und die Zusatzfunktion kann den richtigen Termin 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()

    // ...
}
MyTimelineComplicationDataSourceService.kt

Das Verhalten von SuspendingTimelineComplicationDataSourceService ist wie folgt:

  • Wenn die aktuelle Zeit zwischen der Start- und Endzeit eines Eintrags in der Zeitachse liegt, verwendet das Zifferblatt diesen Wert.
  • Wenn die aktuelle Zeit nicht in einem Eintrag in der Zeitachse liegt, wird der Standardwert verwendet. In der Kalender-App könnte dies beispielsweise „Kein Termin“ sein.
  • Wenn die aktuelle Zeit in mehreren Terminen liegt, wird der kürzeste Termin verwendet.

Dynamische Werte bereitstellen

Ab Wear OS 4 können einige Zusatzfunktionen Werte anzeigen, die häufiger aktualisiert werden basierend auf Werten, die direkt auf der Plattform verfügbar sind. Wenn Sie diese Funktion in Ihren Zusatzfunktionen bereitstellen 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 Zusatzfunktion ausgeführt werden muss.

Beispiele für Felder sind das Feld für dynamische Werte von GoalProgressComplicationData's und DynamicComplicationText, das in jedem ComplicationText-Feld verwendet werden kann. Diese dynamischen Werte basieren auf der androidx.wear.protolayout.expression Bibliothek.

In bestimmten Situationen kann die Plattform dynamische Werte nicht auswerten: