عرض البيانات للإضافات

تعرض مصادر بيانات الإضافات معلومات للإضافات على خلفية شاشة الساعة، وتوفّر نصوصًا وصورًا وأرقامًا يمكن أن تعرضها خلفية شاشة الساعة.

توسّع خدمة مصدر البيانات SuspendingComplicationDataSourceService لتقديم معلومات مفيدة مباشرةً إلى خلفية شاشة الساعة.

الخطوات الأولى

أضِف التبعية التالية إلى وحدة تطبيقك:

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

إنشاء خدمة مصدر البيانات

عند الحاجة إلى بيانات الإضافة، يرسل نظام Wear OS طلبات تحديث إلى مصدر البيانات. للردّ على طلبات التحديث، يجب أن ينفّذ مصدر البيانات onComplicationRequest() طريقة SuspendingComplicationDataSourceService في فئة.

يستدعي نظام Wear OS طريقة onComplicationRequest() عندما يحتاج إلى بيانات من مصدرك، مثلاً عندما تصبح إضافة تستخدم مصدر بياناتك نشطة أو عند انقضاء فترة زمنية محدّدة.

ملاحظة: عندما يقدّم مصدر البيانات بيانات، تتلقّى خلفية شاشة الساعة القيم الأولية. تكون خلفية شاشة الساعة مسؤولة عن تنسيق البيانات لعرضها.

يعرض مقتطف الرمز البرمجي التالي نموذجًا للتنفيذ:

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

بيانات البيان والأذونات

يجب أن تتضمّن مصادر البيانات بيانات محدّدة في بيان التطبيق لكي يعاملها نظام Android كمصدر بيانات. يوضّح هذا القسم الإعدادات المطلوبة لـ مصادر البيانات.

في بيان تطبيقك، عليك الإعلان عن الخدمة وإضافة intent filter لإجراء طلب التحديث. يجب أن يحمي البيان أيضًا الخدمة عن طريق إضافة إذن BIND_COMPLICATION_PROVIDER لضمان إمكانية ربط نظام Wear OS فقط بخدمات مقدّمي الخدمات.

عليك أيضًا تضمين سمة android:icon في عنصر service الذي يوفّر رمزًا أبيض أحادي اللون. ننصح باستخدام الرسومات المتجهة للرموز. يمثّل الرمز مصدر البيانات ويظهر في أداة اختيار الإضافات.

وفي ما يلي مثال لذلك:

<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

عناصر البيانات الوصفية

في ملف البيان، لاحظ عناصر البيانات الوصفية التالية:

android:name="android.support.wearable.complications.SUPPORTED_TYPES": تحدّد أنواع بيانات الإضافات التي يتيحها مصدر البيانات.
android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS": تحدّد عدد المرات التي يجب أن يتحقّق فيها النظام من توفّر تحديثات للبيانات.

عندما يكون مصدر بيانات الإضافات نشطًا، UPDATE_PERIOD_SECONDS تحدّد عدد المرات التي تريد أن يتحقّق فيها النظام من توفّر تحديثات للبيانات. إذا لم تكن المعلومات المعروضة في الـ إضافة بحاجة إلى التحديث بانتظام، مثلاً عند استخدام التحديثات الفورية، اضبط هذه القيمة على 0.

إذا لم تضبط UPDATE_PERIOD_SECONDS على 0، عليك استخدام قيمة لا تقل عن 300 (5 دقائق)، وهي الحد الأدنى لفترة التحديث التي يفرضها النظام للحفاظ على عمر بطارية الجهاز. بالإضافة إلى ذلك، ضَع في اعتبارك أنّ طلبات التحديث تصل بوتيرة أقل عندما يكون الجهاز في الوضع المحيط أو لا يتم ارتداؤه.

إضافة شاشة إعدادات

إذا لزم الأمر، يمكن أن يتضمّن مصدر البيانات شاشة إعدادات تظهر للمستخدم عندما يختار مصدر البيانات هذا من أداة اختيار الإضافات. على سبيل المثال، قد يتضمّن مصدر بيانات ساعة عالمية شاشة إعدادات تتيح للمستخدم اختيار المدينة أو المنطقة الزمنية لعرضها.

يتضمّن بيان المثال عنصر meta-data مع المفتاح PROVIDER_CONFIG_ACTION. وقيمة هذا العنصر هي الإجراء المستخدَم لتشغيل شاشة الإعدادات.

أنشئ نشاط التكوين وأضِف intent filter يطابق الإجراء الخاص به في ملف البيان.

<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

يمكن أن تحصل الشاشة على تفاصيل فتحة الإضافة التي يتم إعدادها من الهدف ضِمن طريقة onCreate() في الشاشة:

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

يجب أن تكون شاشة الإعدادات في الحزمة نفسها التي يتضمّنها مقدّم الخدمة. يجب أن تعرض شاشة الإعدادات RESULT_OK أو RESULT_CANCELED لإعلام النظام ما إذا كان يجب ضبط مصدر البيانات:

setResult(RESULT_OK) // Or RESULT_CANCELED to cancel configuration
finish()ConfigurationActivity.kt

استخدام التحديثات الفورية

كبديل لتحديد فترة التحديث في بيان تطبيقك، يمكنك استخدام مثيل من ComplicationDataSourceUpdateRequester لبدء التحديثات ديناميكيًا. لطلب تحديث، استخدِم طريقة requestUpdate().

تنبيه: للحفاظ على عمر بطارية الجهاز، لا تستدعِ طريقة requestUpdate() من مثيل ComplicationDataSourceUpdateRequester أكثر من مرّة كل 5 دقائق في المتوسط.

توفير قيم تعتمد على الوقت

تحتاج بعض الإضافات إلى عرض قيمة مرتبطة بالوقت الحالي وتشمل الأمثلة التاريخ الحالي أو الوقت المتبقي حتى الاجتماع التالي، أو الوقت في منطقة زمنية أخرى.

لا تحدِّث الإضافة كل ثانية أو دقيقة لإبقاء هذه القيم محدّثة. بدلاً من ذلك، حدِّد القيم بالنسبة إلى التاريخ أو الوقت الحالي باستخدام نص يعتمد على الوقت. تتيح لك الفئات التالية إنشاء هذه القيم التي تعتمد على الوقت:

TimeFormatComplicationText : تنسِّق قيمة التاريخ أو الوقت.
TimeDifferenceComplicationText - تحسب الوقت تصاعديًا أو تنازليًا حتى وقت محدّد.

بيانات "المخطّط الزمني"

بالنسبة إلى مصادر بيانات الإضافات التي توفّر سلسلة من القيم في أوقات محدّدة مسبقًا، استخدِم SuspendingTimelineComplicationDataSourceService.

مثال على ذلك هو مصدر بيانات "الحدث التالي" من تطبيق تقويم: بدلاً من أن يضطر النظام إلى إجراء استطلاع بانتظام لمصدر البيانات لمعرفة الحدث التالي، يمكن أن يقدّم مصدر البيانات مخططًا زمنيًا للأحداث مرّة واحدة، ثم يمكن أن يبدأ مصدر البيانات التحديثات إذا تغيّر التقويم. يقلّل ذلك من الحمل على النظام ويسمح للإضافة بعرض الحدث الصحيح في الوقت المناسب:

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

يكون سلوك SuspendingTimelineComplicationDataSourceService على النحو التالي:

عندما يقع الوقت الحالي ضِمن وقتَي البدء ووقت الانتهاء لإدخال في المخطّط الزمني، تستخدم خلفية شاشة الساعة هذه القيمة.
عندما لا يقع الوقت الحالي ضِمن أي إدخال في المخطّط الزمني، يتم استخدام القيمة التلقائية. على سبيل المثال، في تطبيق التقويم، يمكن أن تكون هذه القيمة "لا يوجد حدث".
إذا كان الوقت الحالي يقع ضِمن أحداث متعدّدة، يتم استخدام أقصر حدث.

توفير قيم ديناميكية

بدءًا من Wear OS 4، يمكن لبعض الإضافات عرض قيم يتم تعديلها بشكل أكثر تكرارًا استنادًا إلى القيم المتاحة مباشرةً للمنصة. لتوفير هذه الإمكانية في إضافاتك، استخدِم ComplicationData الحقول التي تقبل القيم الديناميكية. تقيِّم المنصة هذه القيم وتعدّلها بشكل متكرّر، بدون الحاجة إلى تشغيل مقدّم الإضافة.

تشمل حقول المثال GoalProgressComplicationData حقل القيمة الديناميكية، و DynamicComplicationText، الذي يمكن استخدامه في أي ComplicationText حقل. تستند هذه القيم الديناميكية إلى مكتبة androidx.wear.protolayout.expression.

في حالات معيّنة، لا يمكن للمنصة تقييم القيم الديناميكية:

القيمة الديناميكية غير متاحة أحيانًا: يحدث ذلك، مثلاً، عندما يكون الجهاز غير مرتدى. في هذه الحالات، تستخدم المنصة قيمة حقل dynamic value invalidation fallback بدلاً من ذلك، في حقل العنصر النائب في NoDataComplicationData's.
القيمة الديناميكية غير متاحة مطلقًا: يحدث ذلك على جهاز يعمل بإصدار أقدم من Wear OS 4. في هذه الحالة، تستخدم المنصة حقل احتياطيًا مصاحبًا، مثل getFallbackValue().

الأنواع والحقول

مستودع نماذج Wear OS

عرض البيانات للإضافات تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.