تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

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

توسّع خدمة مصدر البيانات 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 كمصدر بيانات. يشرح هذا القسم الإعدادات المطلوبة لمصادر البيانات.

في ملف بيان تطبيقك، عليك تعريف الخدمة وإضافة فلتر أهداف لإجراء طلب التحديث. يجب أن يحمي ملف البيان أيضًا الخدمة من خلال إضافة الإذن 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.

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

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

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

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

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