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

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

توسّع خدمة مصدر البيانات نطاق 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()

    // ...
}

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

يجب أن تتضمّن مصادر البيانات إفصاحات محدّدة في بيان التطبيق ليتم التعامل معها كمصدر بيانات من قِبل نظام التشغيل 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>

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

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

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

يمكن للنشاط الحصول على تفاصيل عن خانة التطبيق المصغّر التي يتم ضبطها من خلال الغرض ضمن طريقة 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)

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

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

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

كبديل لتحديد فاصل زمني للتحديث في ملف البيان الخاص بتطبيقك، يمكنك استخدام مثيل من 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()

    // ...
}

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

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

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

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

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

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

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

مراجع ذات صلة