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

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

  • المكتبات ذات الصلة بتطبيق Jetpack Tiles: يتم تضمين هذه المكتبات (بما في ذلك Wear Tiles وWear ProtoLayout) في تطبيقك، ويكون بإمكانك بصفتك المطوّر التحكّم في إصداراتها. يستخدم تطبيقك هذه المكتبات لإنشاء عنصر TileBuilder.Tile (بنية البيانات التي تمثّل مربّع معلوماتك) استجابةً لطلب onTileRequest() من النظام.
  • ProtoLayout Renderer: يُعدّ مكوّن النظام هذا مسؤولاً عن عرض العنصر Tile على الشاشة ومعالجة تفاعلات المستخدم. لا يتحكّم مطوّر التطبيقات في إصدار معالج العرض، ويمكن أن يختلف الإصدار من جهاز لآخر، حتى إذا كانت الأجهزة تتضمّن أجهزة مشابهة.

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

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

مراعاة التوافق

لإنشاء مربّع يعمل بشكل صحيح على مجموعة من الأجهزة، يجب مراعاة ما يلي:

رصد إصدار أداة التحويل

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

التعليق التوضيحي @RequiresSchemaVersion

  • يشير التعليق التوضيحي @RequiresSchemaVersion في طرق ProtoLayout إلى الحد الأدنى لإصدار مخطّط أداة العرض المطلوب لكي تعمل هذه الطريقة على النحو المُسجَّل (مثال).
    • على الرغم من أنّ استدعاء طريقة تتطلّب إصدارًا أعلى من أداة التحويل من مثبَّت على الجهاز لن يؤدي إلى تعطُّل تطبيقك، إلا أنّه قد يؤدي إلى عدم عرض المحتوى أو تجاهل الميزة.

مثال

override fun onTileRequest(
    requestParams: TileService.TileRequest
): ListenableFuture<Tile> {
    val rendererVersion =
        requestParams.deviceConfiguration.rendererSchemaVersion
    val tile = Tile.Builder()

    if (
        rendererVersion.major > 1 ||
            (rendererVersion.major == 1 && rendererVersion.minor >= 300)
    ) {
        // Use a feature supported in renderer version 1.300 or later
        tile.setTileTimeline(/* ... */ )
    } else {
        // Provide fallback content for older renderers
        tile.setTileTimeline(/* ... */ )
    }

    return Futures.immediateFuture(tile.build())
}

الاختبار باستخدام إصدارات مختلفة من مُعِدِّل العرض

لاختبار مربّعاتك على إصدارات مختلفة من أداة عرض الرسومات، يمكنك نشرها على إصدارات مختلفة من محاكي Wear OS. (على الأجهزة الفعلية، يتم من خلال "متجر Play" أو تحديثات النظام إرسال تحديثات أداة ProtoLayout Renderer. لا يمكن فرض تثبيت إصدار معيّن من أداة التحويل.)

تستخدِم ميزة "معاينة مربّعات البيانات" في Android Studio أداة عرض مضمّنة في مكتبة Jetpack ProtoLayout التي يعتمد عليها الرمز البرمجي، لذا يمكنك استخدام نهج آخر وهو الاعتماد على إصدارات مختلفة من مكتبة Jetpack عند اختبار مربّعات البيانات.

ترقية مكتبات Jetpack

يمكنك تحديث مكتبات Jetpack Tile للاستفادة من أحدث التحسينات، بما في ذلك تغييرات واجهة المستخدم لدمج وحداتك بسلاسة مع النظام.

نقل البيانات إلى الإصدار 1.2 من Tiles أو الإصدار 1.0 من ProtoLayout

اعتبارًا من الإصدار 1.2، أصبحت معظم واجهات برمجة التطبيقات لتنسيق مربّعات المعلومات متوفّرة في مساحة الاسم androidx.wear.protolayout. لاستخدام أحدث واجهات برمجة التطبيقات، أكمِل خطوات نقل البيانات التالية في الرمز البرمجي.

تعديل التبعيات

في ملف إنشاء وحدة التطبيق، أجرِ التغييرات التالية:

رائع

  // Remove
  implementation 'androidx.wear.tiles:tiles-material:version'

  // Include additional dependencies
  implementation "androidx.wear.protolayout:protolayout:1.2.1"
  implementation "androidx.wear.protolayout:protolayout-material:1.2.1"
  implementation "androidx.wear.protolayout:protolayout-expression:1.2.1"

  // Update
  implementation "androidx.wear.tiles:tiles:1.4.1"

Kotlin

  // Remove
  implementation("androidx.wear.tiles:tiles-material:version")

  // Include additional dependencies
  implementation("androidx.wear.protolayout:protolayout:1.2.1")
  implementation("androidx.wear.protolayout:protolayout-material:1.2.1")
  implementation("androidx.wear.protolayout:protolayout-expression:1.2.1")

  // Update
  implementation("androidx.wear.tiles:tiles:1.4.1")

تعديل مساحات الأسماء

في ملفات الرموز البرمجية المستندة إلى Kotlin وJava في تطبيقك، عليك إجراء التعديلات التالية. بدلاً من ذلك، يمكنك تنفيذ النص البرمجي لإعادة تسمية مساحة الاسم هذا.

  1. استبدِل كل عمليات استيراد androidx.wear.tiles.material.* بعمليات androidx.wear.protolayout.material.*. أكمِل هذه الخطوة أيضًا لإضافة مكتبة androidx.wear.tiles.material.layouts.

  2. استبدِل معظم عمليات استيراد androidx.wear.tiles.* الأخرى باستخدام androidx.wear.protolayout.*.

    من المفترض أن تظل عمليات الاستيراد في androidx.wear.tiles.EventBuilders وandroidx.wear.tiles.RequestBuilders وandroidx.wear.tiles.TileBuilders وandroidx.wear.tiles.TileService كما هي.

  3. إعادة تسمية بعض الطرق المتوقّفة نهائيًا من فئتَي TileService وTileBuilder:

    1. TileBuilders: من getTimeline() إلى getTileTimeline()، وsetTimeline() إلى setTileTimeline()
    2. TileService: من onResourcesRequest() إلى onTileResourcesRequest()
    3. RequestBuilders.TileRequest: من getDeviceParameters() إلى getDeviceConfiguration()، ومن setDeviceParameters() إلى setDeviceConfiguration()، ومن getState() إلى getCurrentState()، ومن setState() إلى setCurrentState()