Özelliklere verileri gösterme

Özellik veri kaynakları, kadranın oluşturabileceği metin, resim ve sayıları sağlayarak kadran özelliklerine bilgi sunar.

Veri kaynağı hizmeti, doğrudan kadrana faydalı bilgiler sunmak için SuspendingComplicationDataSourceService sınıfını genişletir.

Başlarken

Uygulama modülünüze aşağıdaki bağımlılığı ekleyin: 

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

Veri kaynağı hizmetini oluşturma

Wear OS sistemi, komplikasyon verilerine ihtiyaç duyulduğunda veri kaynağınıza güncelleme istekleri gönderir. Güncelleme isteklerine yanıt vermek için veri kaynağınızın SuspendingComplicationDataSourceService sınıfının onComplicationRequest() yöntemini uygulaması gerekir.

Wear OS sistemi, kaynağınızdan veri gerektiğinde (ör. veri kaynağınızı kullanan bir komplikasyon etkinleştiğinde veya belirli bir süre geçtiğinde) onComplicationRequest() yöntemini çağırır.

Not: Veri kaynağınız veri sağladığında kadran ham değerleri alır. Kadran, verileri görüntülemek için biçimlendirmekten sorumludur.

Aşağıdaki kod snippet'inde örnek bir uygulama gösterilmektedir:

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

    // ...
}

Manifest beyanları ve izinler

Veri kaynaklarının, Android sistemi tarafından veri kaynağı olarak kabul edilmesi için uygulama manifestlerinde belirli beyanlar bulunmalıdır. Bu bölümde, veri kaynakları için gerekli ayarlar açıklanmaktadır.

Uygulamanızın manifest dosyasında hizmeti beyan edin ve güncelleme isteği işlemi intent filtresi ekleyin. Manifest, sağlayıcı hizmetlerine yalnızca Wear OS sisteminin bağlanabilmesi için BIND_COMPLICATION_PROVIDER iznini ekleyerek hizmeti korumalıdır.

Ayrıca, service öğesine tek renkli beyaz simge sağlayan bir android:icon özelliği ekleyin. Simgeler için drawable vektörleri kullanmanızı öneririz. Simge, veri kaynağını temsil eder ve komplikasyon seçicide gösterilir.

Örneğin: 

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

Meta veri öğeleri

Manifest dosyanızda aşağıdaki meta veri öğelerini göreceksiniz:

  • android:name="android.support.wearable.complications.SUPPORTED_TYPES": Veri kaynağının desteklediği komplikasyon verilerinin türlerini belirtir.
  • android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS": Sistemin, verilerle ilgili güncellemeleri ne sıklıkta kontrol etmesi gerektiğini belirtir.

Karmaşık veri kaynağınız etkin olduğunda UPDATE_PERIOD_SECONDS, sistemin verilerle ilgili güncellemeleri ne sıklıkta kontrol etmesini istediğinizi belirtir. Karmaşıkta gösterilen bilgilerin düzenli bir programa göre güncellenmesi gerekmiyorsa (ör. push güncellemeleri kullanırken) bu değeri 0 olarak ayarlayın.

UPDATE_PERIOD_SECONDS değerini 0 olarak ayarlamazsanız cihazın pil ömrünü korumak için sistemin zorunlu kıldığı minimum güncelleme süresi olan en az 300 (5 dakika) değerini kullanmanız gerekir. Ayrıca, cihaz ambiyans modundayken veya takılı değilken güncelleme isteklerinin daha seyrek geldiğini unutmayın.

Yapılandırma etkinliği ekleme

Gerekirse veri kaynağı, kullanıcı komplikasyon seçiciden ilgili veri kaynağını seçtiğinde kullanıcıya gösterilen bir yapılandırma etkinliği içerebilir. Örneğin, dünya saati veri kaynağında, kullanıcının görüntülenecek şehri veya saat dilimini seçmesine olanak tanıyan bir yapılandırma etkinliği olabilir.

Örnek manifest, PROVIDER_CONFIG_ACTION anahtarına sahip bir meta-data öğesi içerir. Bu öğenin değeri, yapılandırma etkinliğini başlatmak için kullanılan işlemdir.

Yapılandırma etkinliğini oluşturun ve manifest dosyanızda bu etkinliğin işlemiyle eşleşen bir intent filtresi ekleyin. 

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

Etkinlik, yapılandırdığı komplikasyon alanının ayrıntılarını, etkinliğin onCreate() yöntemindeki intent'ten alabilir: 

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

Yapılandırma etkinliği, sağlayıcıyla aynı pakette bulunmalıdır. Yapılandırma etkinliği, sisteme veri kaynağının ayarlanıp ayarlanmayacağını bildirmek için RESULT_OK veya RESULT_CANCELED döndürmelidir: 

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

Push güncellemelerini kullanma

Uygulamanızın manifest dosyasında güncelleme aralığı belirtmeye alternatif olarak, güncellemeleri dinamik olarak başlatmak için ComplicationDataSourceUpdateRequester örneğini kullanabilirsiniz. Güncelleme isteğinde bulunmak için requestUpdate() numaralı telefonu arayın.

Dikkat: Cihazın pil ömrünü korumak için ComplicationDataSourceUpdateRequester örneğinizden requestUpdate() yöntemini ortalama 5 dakikada bir kereden daha sık çağırmayın.

Zamana bağlı değerler sağlama

Bazı komplikasyonların geçerli saatle ilgili bir değer göstermesi gerekir. Örnek olarak geçerli tarih, bir sonraki toplantıya kalan süre veya başka bir saat dilimindeki saat verilebilir.

Bu değerleri güncel tutmak için komplikasyonları her saniye veya dakikada bir güncellemeyin. Bunun yerine, zamana bağlı metin kullanarak değerleri geçerli tarih veya saate göre belirtin. Aşağıdaki sınıflar, zamana bağlı bu değerleri oluşturmanıza olanak tanır:

Zaman Çizelgesi verileri

Önceden tanımlanmış zamanlarda bir değer dizisi sağlayan komplikasyon veri kaynakları için SuspendingTimelineComplicationDataSourceService kullanın.

Takvim uygulamasındaki "sonraki etkinlik" veri kaynağı buna örnek gösterilebilir: Sistemin, sonraki etkinlik için veri kaynağını düzenli olarak sorgulaması gerekmez. Veri kaynağı, etkinliklerin zaman çizelgesini bir kez sağlayabilir ve takvim değişirse güncellemeleri başlatabilir. Bu sayede sistemdeki yük en aza indirilir ve komplikasyonun doğru etkinliği zamanında göstermesi sağlanır: 

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

    // ...
}

SuspendingTimelineComplicationDataSourceService davranışları aşağıdaki gibidir:

  • Geçerli saat, zaman çizelgesindeki bir girişin başlangıç ve bitiş saati aralığına denk geldiğinde kadran bu değeri kullanır.
  • Geçerli zaman, zaman çizelgesindeki herhangi bir girişle eşleşmediğinde varsayılan değer kullanılır. Örneğin, takvim uygulamasında bu "Etkinlik yok" olabilir.
  • Geçerli saat birden fazla etkinliğe denk geliyorsa en kısa etkinlik kullanılır.

Dinamik değerler sağlama

Wear OS 4'ten itibaren bazı komplikasyonlar, doğrudan platformda bulunan değerlere göre daha sık yenilenen değerleri gösterebilir. Bu özelliği komplikasyonlarınızda sunmak için dinamik değerleri kabul eden ComplicationData alanlarını kullanın. Platform, komplikasyon sağlayıcının çalışmasına gerek kalmadan bu değerleri sık sık değerlendirir ve günceller.

Örnek alanlar arasında GoalProgressComplicationData'ın dinamik değer alanı ve herhangi bir ComplicationText alanında kullanılabilen DynamicComplicationText yer alır. Bu dinamik değerler, androidx.wear.protolayout.expression kitaplığını temel alır.

Bazı durumlarda platform, dinamik değerleri değerlendiremez: