Mengekspos data ke detail

Sumber data detail menampilkan informasi ke detail tampilan jam, yang menyediakan teks, gambar, dan angka yang dapat dirender oleh tampilan jam.

Layanan sumber data memperluas SuspendingComplicationDataSourceService untuk menayangkan informasi yang berguna ke tampilan jam secara langsung.

Memulai

Tambahkan dependensi berikut ke modul aplikasi Anda: 

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

Membuat layanan sumber data

Ketika data detail diperlukan, sistem Wear OS akan mengirimkan permintaan update ke sumber data Anda. Untuk merespons permintaan update, sumber data Anda harus mengimplementasikan metode onComplicationRequest() dari class SuspendingComplicationDataSourceService.

Sistem Wear OS memanggil onComplicationRequest() saat memerlukan data dari sumber Anda—misalnya, saat detail yang menggunakan sumber data Anda menjadi aktif atau saat jumlah waktu yang ditentukan telah berlalu.

Catatan: Saat sumber data Anda menyediakan data, tampilan jam akan menerima nilai mentah. Tampilan jam bertanggung jawab untuk memformat data agar dapat ditampilkan.

Cuplikan kode berikut menunjukkan contoh implementasi:

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

    // ...
}

Izin dan deklarasi manifes

Sumber data harus menyertakan deklarasi spesifik dalam manifes aplikasinya agar diperlakukan sebagai sumber data oleh sistem Android. Bagian ini menjelaskan setelan yang diperlukan untuk sumber data.

Dalam manifes aplikasi Anda, deklarasikan layanan dan tambahkan filter intent tindakan permintaan update. Manifes juga harus melindungi layanan dengan menambahkan izin BIND_COMPLICATION_PROVIDER untuk memastikan bahwa hanya sistem Wear OS yang dapat terikat ke layanan penyedia.

Selain itu, sertakan atribut android:icon dalam elemen service yang menyediakan ikon putih satu warna. Sebaiknya gunakan vektor drawable untuk ikon. Ikon merepresentasikan sumber data dan ditampilkan di pemilih detail.

Berikut contohnya: 

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

Elemen metadata

Dalam file manifes Anda, perhatikan elemen metadata berikut:

  • android:name="android.support.wearable.complications.SUPPORTED_TYPES": Menentukan jenis data detail yang didukung oleh sumber data.
  • android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS": Menentukan seberapa sering sistem harus memeriksa update data.

Ketika sumber data detail Anda aktif, UPDATE_PERIOD_SECONDS akan menentukan seberapa sering sistem perlu memeriksa update untuk data. Jika informasi yang ditampilkan dalam detail tidak perlu diupdate secara rutin, seperti ketika Anda menggunakan update push, tetapkan nilai ini ke 0.

Jika UPDATE_PERIOD_SECONDS tidak ditetapkan ke 0, Anda harus menggunakan nilai minimal 300 (5 menit), yaitu periode update minimal yang diberlakukan sistem, untuk menghemat masa pakai baterai di perangkat. Selain itu, perlu diingat bahwa permintaan update muncul lebih jarang ketika perangkat berada dalam mode standby atau sedang tidak dipakai.

Menambahkan aktivitas konfigurasi

Jika diperlukan, sumber data dapat menyertakan aktivitas konfigurasi yang ditampilkan kepada pengguna saat pengguna memilih sumber data tersebut dari pemilih detail. Misalnya, sumber data jam dunia mungkin memiliki aktivitas konfigurasi yang memungkinkan pengguna memilih kota atau zona waktu yang akan ditampilkan.

Contoh manifes menyertakan elemen meta-data dengan kunci PROVIDER_CONFIG_ACTION. Nilai elemen ini adalah tindakan yang digunakan untuk meluncurkan aktivitas konfigurasi.

Buat aktivitas konfigurasi, dan tambahkan filter intent yang cocok dengan tindakan untuknya di file manifes Anda. 

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

Aktivitas dapat memperoleh detail slot kartu jam yang dikonfigurasi dari intent dalam metode onCreate() aktivitas: 

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

Aktivitas konfigurasi harus berada dalam paket yang sama dengan penyedia. Aktivitas konfigurasi harus menampilkan RESULT_OK atau RESULT_CANCELED untuk memberi tahu sistem apakah sumber data harus ditetapkan: 

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

Menggunakan update push

Selain menentukan interval update dalam manifes aplikasi, Anda dapat menggunakan instance ComplicationDataSourceUpdateRequester untuk memulai update secara dinamis. Untuk meminta update, panggil requestUpdate().

Perhatian: Untuk menghemat masa pakai baterai perangkat, jangan panggil requestUpdate() dari instance ComplicationDataSourceUpdateRequester lebih sering daripada rata-rata 5 menit sekali.

Menyediakan nilai-nilai yang bergantung pada waktu

Beberapa detail perlu menampilkan nilai yang berhubungan dengan waktu saat ini. Contohnya termasuk tanggal saat ini, waktu hingga pertemuan berikutnya, atau waktu di zona waktu lain.

Jangan mengupdate detail setiap detik atau menit agar nilai tersebut selalu terbaru. Sebagai gantinya, tetapkan nilai sebagai nilai yang relatif terhadap tanggal atau waktu saat ini menggunakan teks yang bergantung pada waktu. Class berikut memungkinkan Anda membuat nilai-nilai yang bergantung pada waktu ini:

Data linimasa

Untuk sumber data widget yang menyediakan urutan nilai pada waktu yang telah ditentukan sebelumnya, gunakan SuspendingTimelineComplicationDataSourceService.

Contohnya adalah sumber data "acara berikutnya" dari aplikasi kalender: Daripada sistem harus melakukan polling sumber data secara rutin untuk acara berikutnya, sumber data dapat memberikan linimasa acara satu kali, lalu sumber data dapat memulai update jika kalender berubah. Hal ini meminimalkan beban pada sistem dan memungkinkan tampilan jam menampilkan peristiwa yang benar secara tepat waktu: 

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

    // ...
}

Perilaku SuspendingTimelineComplicationDataSourceService adalah sebagai berikut:

  • Jika waktu saat ini berada dalam waktu mulai dan waktu berakhir entri di linimasa, tampilan jam akan menggunakan nilai tersebut.
  • Jika waktu saat ini tidak termasuk dalam entri apa pun di linimasa, nilai default akan digunakan. Misalnya, di aplikasi kalender, ini bisa berupa "Tidak ada acara".
  • Jika waktu saat ini berada dalam beberapa peristiwa, peristiwa terpendek akan digunakan.

Menyediakan nilai dinamis

Mulai di Wear OS 4, beberapa detail dapat menampilkan nilai yang lebih sering diperbarui berdasarkan nilai yang tersedia langsung di platform. Untuk menyediakan kemampuan ini dalam detail, gunakan kolom ComplicationData yang menerima nilai dinamis. Platform mengevaluasi dan memperbarui nilai ini secara berkala, tanpa mengharuskan penyedia detail berjalan.

Contoh kolom mencakup Kolom nilai dinamis GoalProgressComplicationData, dan DynamicComplicationText, yang dapat digunakan di kolom ComplicationText mana pun. Nilai dinamis ini didasarkan pada library androidx.wear.protolayout.expression.

Dalam situasi tertentu, platform tidak dapat mengevaluasi nilai dinamis: