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

تعرض تطبيقات مزوِّد البيانات المعلومات لخلفية شاشة الساعة. المضاعفات تقديم الحقول التي تحتوي على نص وسلاسل وصور وأرقام.

تمتد خدمة مزود البيانات ComplicationProviderService لتقديم معلومات مفيدة المعلومات مباشرةً في خلفية شاشة الساعة.

إنشاء مشروع لمزود البيانات

لإنشاء مشروعك في "استوديو Android" لتطبيق مزوِّد البيانات، أكمِل الخطوات التالية:

  1. انقر على ملف >. جديد > مشروع جديد:
  2. في نافذة نموذج المشروع، انقر على علامة التبويب Wear OS، واختَر ليس هناك أي نشاط، وانقر على التالي.
  3. في نافذة إعداد مشروعك، أدخِل اسمًا لمشروعك، واملأ معلومات المشروع العادية، وانقر على إنهاء.
  4. ينشئ "استوديو Android" مشروعًا باستخدام وحدة تطبيق لمزوّد البيانات. لمزيد من المعلومات، معلومات حول المشاريع في "استوديو Android"، اطّلِع على أنشئ مشروعًا.
  5. بدء تطبيق مزوِّد البيانات بإنشاء فئة جديدة BroadcastReceiver الغرض من هذا الفصل هو الاستماع طلبات تحديث الإضافات من نظام Wear OS. بالإضافة إلى ذلك، أنشئ فئة جديدة تمتد ComplicationProviderService لتوفير البيانات كما هو مطلوب من خلال الإضافات المناسبة. لمزيد من المعلومات، يُرجى الاطّلاع على ما يلي:

    ملاحظة: تتمثل إضافة نشاط لمزوِّد البيانات في اختيارية. على سبيل المثال، قد ترغب في تشغيل نشاط فقط عندما ينقر المستخدم على البيانات.

تنفيذ طريقة لطلبات التحديث

عند الحاجة إلى بيانات عن الإضافات، يرسِل نظام Wear OS طلبات التحديث إلى بياناتك. المستخدم. يتم استلام الطلبات بواسطة BroadcastReceiver للرد على طلبات التحديث، يجب على مزود البيانات تنفيذ طريقة onComplicationUpdate() من ComplicationProviderService الصف.

يتصل نظام Wear OS بـ onComplicationUpdate() عند الحاجة إلى بيانات من جهازك. مزوّد الخدمة — على سبيل المثال، عندما تصبح إضافة تستخدم موفّر الخدمة نشطة أو عند مرور فترة زمنية ثابتة. يجتاز ComplicationManager كمعلمة إلى onComplicationUpdate، والذي يُستخدم لإرسال البيانات مرة أخرى إلى النظام.

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

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

Kotlin

override fun onComplicationUpdate(
    complicationId: Int, dataType: Int, complicationManager: ComplicationManager) {

    Log.d(TAG, "onComplicationUpdate() id: $complicationId")

    // Used to create a unique key to use with SharedPreferences for this complication.
    val thisProvider = ComponentName(this, javaClass)

    // Retrieves your data; in this case, grabs an incrementing number from SharedPrefs.
    val preferences = getSharedPreferences(ComplicationTapBroadcastReceiver.COMPLICATION_PROVIDER_PREFERENCES_FILE_KEY, 0)

    val number = preferences.getInt(
            ComplicationTapBroadcastReceiver.getPreferenceKey(
                    thisProvider, complicationId),
                    0)
    val numberText = String.format(Locale.getDefault(), "%d!", number)

    var complicationData: ComplicationData? = null

    when (dataType) {
        ComplicationData.TYPE_SHORT_TEXT -> complicationData = ComplicationData.Builder(ComplicationData.TYPE_SHORT_TEXT)
                .setShortText(ComplicationText.plainText(numberText))
                .build()
        else -> if (Log.isLoggable(TAG, Log.WARN)) {
                    Log.w(TAG, "Unexpected complication type $dataType")
                }
    }

    if (complicationData != null) {
        complicationManager.updateComplicationData(complicationId, complicationData)
    } else {
        // If no data is sent, we still need to inform the ComplicationManager, so
        // the update job can finish and the wake lock isn't held any longer.
        complicationManager.noUpdateRequired(complicationId)
    }
}

Java

@Override
public void onComplicationUpdate(
       int complicationId, int dataType, ComplicationManager complicationManager) {

   Log.d(TAG, "onComplicationUpdate() id: " + complicationId);

   // Used to create a unique key to use with SharedPreferences for this complication.
   ComponentName thisProvider = new ComponentName(this, getClass());

   // Retrieves your data; in this case, grabs an incrementing number from SharedPrefs.
   SharedPreferences preferences =
     getSharedPreferences( ComplicationTapBroadcastReceiver.COMPLICATION_PROVIDER_PREFERENCES_FILE_KEY, 0);

   int number =
           preferences.getInt(
                   ComplicationTapBroadcastReceiver.getPreferenceKey(
                           thisProvider, complicationId),
                   0);
   String numberText = String.format(Locale.getDefault(), "%d!", number);

   ComplicationData complicationData = null;

   switch (dataType) {
       case ComplicationData.TYPE_SHORT_TEXT:
           complicationData =
                   new ComplicationData.Builder(ComplicationData.TYPE_SHORT_TEXT)
                           .setShortText(ComplicationText.plainText(numberText))
                           .build();
           break;
       default:
           if (Log.isLoggable(TAG, Log.WARN)) {
               Log.w(TAG, "Unexpected complication type " + dataType);
           }
   }

   if (complicationData != null) {
       complicationManager.updateComplicationData(complicationId, complicationData);

   } else {
       // If no data is sent, we still need to inform the ComplicationManager, so
       // the update job can finish and the wake lock isn't held any longer.
       complicationManager.noUpdateRequired(complicationId);
   }
}

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

يجب أن تتضمّن تطبيقات مزوِّد البيانات تعريفات محدَّدة في بيان التطبيق ليتم التعامل معها على أنّها مزود البيانات من قبل نظام Android. يوضح هذا القسم الإعدادات المطلوبة تطبيقات موفر البيانات.

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

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

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

<service
    android:name=".provider.IncrementingNumberComplicationProviderService"
    android:icon="@drawable/icn_complications"
    android:label="@string/complications_provider_incrementing_number"
    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>
</service>

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

في ملف البيان، ضمِّن بيانات وصفية لتحديد الأنواع المتوافقة ومدة التحديث وإجراء الضبط، كما هو موضَّح في ما يلي مثال: 

<meta-data
    android:name="android.support.wearable.complications.SUPPORTED_TYPES"
    android:value="RANGED_VALUE,SHORT_TEXT,LONG_TEXT" />

<meta-data
    android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS"
    android:value="300" />

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

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

لمزيد من التفاصيل حول إرسال التحديثات، يمكنك الاطلاع على المفاتيح المدرجة ComplicationProviderService الصف في واجهة برمجة تطبيقات Wear OS مرجع

إضافة نشاط ضبط

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

<meta-data
    android:name="android.support.wearable.complications.PROVIDER_CONFIG_ACTION"
    android:value="PROVIDER_CONFIG_ACTION"/>

يمكن أن تكون القيمة أي إجراء.

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

خلفيات شاشة آمنة يحدّدها مقدّم الخدمة

يمكن لمقدّمي الخدمات ضبط خلفيات معيّنة لشاشة الساعة على أنّها "آمنة" على استلام البيانات. ولا يتم استخدامه إلا عندما تحاول خلفية شاشة الساعة استخدام مقدّم الخدمة كمقدّم تلقائي ويثق مقدّم الخدمة بتطبيق خلفية شاشة الساعة.

للإشارة إلى أنّ خلفيات شاشة الساعة آمنة، يضيف مقدّم الخدمة بيانات وصفية تتضمن مفتاحًا android.support.wearable.complications.SAFE_WATCH_FACES تشير رسالة الأشكال البيانية بيانات التعريف عبارة عن قائمة مفصولة بفواصل لأي مما يلي أسماء المكوّنات WatchFaceService، تُعرَف كما لو أو اسم ComponentName.flattenToString() هو أسماء حزم التطبيقات، وفي هذه الحالة كل خلفية شاشة داخل التطبيق المحدد يعتبر آمنًا. يتم تجاهل المسافة البيضاء في قائمة القيم. مثلاً: 

<meta-data
       android:name="android.support.wearable.complications.SAFE_WATCH_FACES"
       android:value="
          com.app.watchface/com.app.watchface.MyWatchFaceService,
          com.anotherapp.anotherwatchface/com.something.WatchFaceService,
          com.something.text"/>

تقديم صور آمنة عند حرقها

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

عندما تقوم بتقديم أيقونة باستخدام ComplicationData.Builder#setIcon، عليك تضمين نسخة آمنة من النسخ الأصلية استخدام ComplicationData.Builder#setBurnInProtectionIcon

عند تقديم صورة باستخدام ComplicationData.Builder#setSmallImage، عليك تضمين نسخة آمنة من النسخ الأصلية استخدام ComplicationData.Builder#setBurnInProtectionSmallImage

استخدام الإشعارات الفورية

كبديل لتحديد فاصل تحديث ثابت وغير صفري في بيان التطبيق، فيمكنك استخدام مثيل ComplicationDataSourceUpdateRequester لطلب التعديلات بشكل ديناميكي. لطلب تعديل المحتوى المرئي للمستخدم للإضافة، يُرجى استدعاء requestUpdate()

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

تقديم قيم ديناميكية

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

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

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

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

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

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

معدّل التعديلات على الإضافات

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