Özelliklere verileri gösterme

Özellik veri kaynakları, saat yüzü özelliklerine bilgi sunarak saat yüzünün oluşturabileceği metin, resim ve sayıları sağlar.

Veri kaynağı hizmeti, SuspendingComplicationDataSourceService'yi genişleterek faydalı bilgileri doğrudan saat yüzüne aktarır.

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

Komplikasyon verilerine ihtiyaç duyulduğunda Wear OS sistemi, 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 onComplicationRequest() işlevini çağırır. Örneğin, veri kaynağınızı kullanan bir komplikasyon etkinleştiğinde veya belirli bir süre geçtiğinde bu işlev çağrılır.

Not: Veri kaynağınız veri sağladığında kol saati yüzü, ham değerleri alır. Verilerin görüntülenmek üzere biçimlendirilmesinden saat yüzü 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 bildirimleri ve izinleri

Android sistemi tarafından veri kaynağı olarak kabul edilmek için veri kaynakları, uygulama manifest dosyalarında belirli beyanlar içermelidir. Bu bölümde, veri kaynakları için gerekli ayarlar açıklanmaktadır.

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

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

Aşağıda bununla ilgili bir örnek verilmiştir: 

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

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

Komplikasyon verileri veri kaynağınız etkin olduğunda, UPDATE_PERIOD_SECONDS sistemin verilerdeki güncellemeleri ne sıklıkta kontrol etmesini istediğinizi belirtir. Komplikasyonda gösterilen bilgilerin düzenli olarak güncellenmesi gerekmiyorsa (ör. push güncellemelerini 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 ortam modundayken veya takılmıyorken güncelleme isteklerinin daha az sıklıkta gönderildiğini unutmayın.

Yapılandırma etkinliği ekleme

Gerekirse bir veri kaynağı, kullanıcı komplikasyon seçiciden söz konusu veri kaynağını seçtiğinde kullanıcıya gösterilen bir yapılandırma etkinliği içerebilir. Örneğin, bir 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ını içeren 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ıza bu etkinliğin işlemine uygun 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 yuvasının ayrıntılarını etkinliğin onCreate() yöntemindeki amaçtan 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, veri kaynağının ayarlanıp ayarlanmayacağını sisteme 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ığı belirtmek yerine, 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 requestUpdate() işlevini ComplicationDataSourceUpdateRequester örneğinizden ortalama olarak 5 dakikada birden 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 kadar olan 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.

Buna örnek olarak bir takvim uygulamasındaki "sonraki etkinlik" veri kaynağı verilebilir: Sistemin sonraki etkinlik için veri kaynağını düzenli olarak yoklaması yerine, veri kaynağı bir kez etkinliklerin zaman çizelgesini sağlayabilir ve ardından takvim değişirse veri kaynağı güncellemeleri başlatabilir. Bu sayede sistemdeki yük en aza indirilir ve komplikasyon, doğru etkinliği zamanında gösterir: 

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 simgesinin davranışı şu şekildedir:

  • Geçerli saat, zaman çizelgesindeki bir girişin başlangıç ve bitiş zamanı aralığında olduğunda saat yüzü bu değeri kullanır.
  • Geçerli saat, zaman çizelgesindeki herhangi bir girişin içinde yer almadığında varsayılan değer kullanılır. Örneğin, takvim uygulamasında bu "Etkinlik yok" olabilir.
  • Geçerli saat birden fazla etkinliğin zaman aralığına giriyorsa en kısa etkinlik kullanılır.

Dinamik değerler sağlama

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

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

Platform, bazı durumlarda dinamik değerleri değerlendiremez: