عرض التحديثات الدورية في المربّعات

إنشاء مربّعات تتضمّن محتوًى يتغيّر بمرور الوقت

العمل باستخدام المخططات الزمنية

يتألف المخطّط الزمني من مثيل واحد أو أكثر TimelineEntry يحتوي كل منها على تخطيط يتم عرضه خلال فترة زمنية معيّنة. يجب أن تتضمّن جميع المربّعات مخططًا زمنيًا.

مربّعات إدخال لمرة واحدة

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

في ما يلي مثال على مربّع يتضمّن TimelineEntry واحدًا:

override fun onTileRequest(
    requestParams: RequestBuilders.TileRequest
): ListenableFuture<Tile?> {
    val tile =
        Tile.Builder()
            .setResourcesVersion(RESOURCES_VERSION)
            // We add a single timeline entry when our layout is fixed, and
            // we don't know in advance when its contents might change.
            .setTileTimeline(Timeline.fromLayoutElement(simpleLayout(this)))
            .build()
    return Futures.immediateFuture(tile)
}
Tile.kt

إدخالات المخطط الزمني المرتبطة بوقت

يمكن TimelineEntry تحديد فترة صلاحية اختياريًا، ما يتيح للّوحة تغيير تصميمها في وقت محدّد بدون أن يطلب التطبيق عرض لوحة جديدة.

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

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

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

override fun onTileRequest(
    requestParams: RequestBuilders.TileRequest
): ListenableFuture<Tile?> {
    val timeline = Timeline.Builder()

    // Add fallback "no meetings" entry
    // Use the version of TimelineEntry that's in androidx.wear.protolayout.
    timeline.addTimelineEntry(
        TimelineBuilders.TimelineEntry.Builder().setLayout(getNoMeetingsLayout()).build()
    )

    // Retrieve a list of scheduled meetings
    val meetings = MeetingsRepo.getMeetings()
    // Add a timeline entry for each meeting
    meetings.forEach { meeting ->
        timeline.addTimelineEntry(
            TimelineBuilders.TimelineEntry.Builder()
                .setLayout(getMeetingLayout(meeting))
                .setValidity(
                    // The tile should disappear when the meeting begins
                    // Use the version of TimeInterval that's in
                    // androidx.wear.protolayout.
                    TimelineBuilders.TimeInterval.Builder()
                        .setEndMillis(meeting.dateTimeMillis)
                        .build()
                )
                .build()
        )
    }

    val tile =
        Tile.Builder()
            .setResourcesVersion(RESOURCES_VERSION)
            .setTileTimeline(timeline.build())
            .build()
    return Futures.immediateFuture(tile)
}
Tile.kt

إعادة تحميل مربّع

قد تنتهي صلاحية المعلومات المعروضة على لوحة بعد مرور بعض الوقت. على سبيل المثال، لا تكون دقيقة إذا كانت تعرض درجة الحرارة نفسها طوال اليوم.

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

override fun onTileRequest(
    requestParams: RequestBuilders.TileRequest
): ListenableFuture<Tile?> =
    Futures.immediateFuture(
        Tile.Builder()
            .setResourcesVersion(RESOURCES_VERSION)
            .setFreshnessIntervalMillis(60 * 60 * 1000) // 60 minutes
            .setTileTimeline(Timeline.fromLayoutElement(getWeatherLayout()))
            .build()
    )
Tile.kt

عند ضبط فاصل زمني للتحديث، يستدعي النظام onTileRequest() بعد انتهاء الفاصل الزمني بفترة قصيرة. في حال عدم ضبط فاصل زمني للتحديث، لن يستدعي النظام onTileRequest().

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

fun eventDeletedCallback() {
     TileService.getUpdater(context)
             .requestUpdate(MyTileService::class.java)
}

اختيار سير عمل للتعديل

استخدِم أفضل الممارسات التالية لتحديد كيفية ضبط تحديثات المربّعات:

• إذا كان التحديث متوقعًا، مثلاً إذا كان مخصصًا للحدث التالي في تقويم المستخدم، استخدِم مخططًا زمنيًا.
• عند جلب بيانات المنصة، استخدِم ربط البيانات لكي يحدّث النظام البيانات تلقائيًا.

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

  ويكون ذلك مفيدًا بشكل خاص عندما تحتاج إلى إنشاء جميع الصور مسبقًا. إذا كنت بحاجة إلى إنشاء صورة جديدة في وقت لاحق، اتّصِل بالرقم setFreshnessIntervalMillis().

• إذا كنت تجري بشكل متكرّر عمليات مكثّفة في الخلفية، مثل طلب بيانات الطقس، استخدِم WorkManager، وأرسِل التحديثات إلى البلاطة.

• إذا كان التحديث استجابةً لحدث خارجي، مثل تشغيل الأضواء أو تلقّي رسالة إلكترونية أو تعديل ملاحظة، أرسِل رسالة المراسلة عبر السحابة الإلكترونية من Firebase (FCM) لإعادة تنشيط تطبيقك، ثم أرسِل التحديثات إلى اللوحة.

• إذا كانت عملية مزامنة بيانات اللوحة قد تكون مكلفة، اتّبِع الخطوات التالية:

  1. جدولة مزامنة البيانات
  2. ابدأ مؤقتًا لمدة ثانية أو ثانيتين.
  3. إذا تلقّيت تحديثًا من مصدر بيانات بعيد قبل انتهاء الوقت، اعرض القيمة المعدَّلة من مزامنة البيانات. بخلاف ذلك، اعرض قيمة محلية مخزّنة مؤقتًا.