إدارة وحدات التحكّم في التلفزيون

تتطلّب أجهزة التلفزيون جهازًا ثانويًا للتفاعل مع التطبيقات، مثل جهاز تحكّم عن بُعد أساسي أو جهاز تحكّم عن بُعد بمؤشر أو ذراع تحكّم في الألعاب. لتقديم تجربة مستخدم متّسقة، يجب أن يتيح تطبيقك الإدخال باستخدام لوحة التحكم (D-pad)، والتعامل مع وحدات التحكّم التي تعمل بلا إنترنت، وإتاحة الإدخال من أنواع متعددة من وحدات التحكّم، بما في ذلك أجهزة التحكّم عن بُعد التي تعمل بالمؤشر.

الحد الأدنى من عناصر التحكّم في لوحة التحكّم

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

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

التعامل مع حالات انقطاع اتصال وحدة التحكّم

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

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

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

<activity
  android:name="com.example.android.TvActivity"
  android:label="@string/app_name"
  android:configChanges="keyboard|keyboardHidden|navigation"
  android:theme="@style/Theme.Leanback">

  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
  </intent-filter>
  ...
</activity>

يتيح هذا التغيير في الإعدادات للتطبيق مواصلة العمل من خلال حدث إعادة الاتصال، بدلاً من إعادة تشغيله من خلال إطار عمل Android، وهو ما لا يمثّل تجربة جيدة للمستخدم.

التعامل مع الاختلافات في إدخال لوحة التحكّم

قد يكون لدى مستخدمي أجهزة التلفزيون أكثر من نوع واحد من وحدات التحكّم التي يستخدمونها مع أجهزة التلفزيون. على سبيل المثال، قد يكون لدى المستخدم لوحة تحكّم أساسية أو جهاز تحكّم عن بُعد بمؤشر أو ذراع تحكّم في الألعاب. قد تختلف رموز المفاتيح التي يوفّرها ذراع التحكّم في الألعاب عند استخدامه لوظائف لوحة التحكّم عن رموز المفاتيح التي ترسلها لوحة التحكّم الأساسية.

يجب التعامل مع الاختلافات في إدخال لوحة التحكّم حتى لا يضطر المستخدم إلى تبديل وحدات التحكّم لتشغيل تطبيقك. لمزيد من المعلومات حول التعامل مع الاختلافات في الإدخال، يُرجى الاطّلاع على معالجة إدخال لوحة التحكّم.

التوافق مع أجهزة التحكّم عن بُعد المزوّدة بمؤشر

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

الإشارة إلى الدعم عن بُعد لأجهزة المؤشر في ملف البيان

للإشارة إلى أنّه يمكن التنقّل في تطبيقك باستخدام المؤشر والإدخال باللمس، اضبط ملف بيان تطبيقك على android.software.leanback.supports_touch <property> على true داخل عنصر <application> (أو داخل عناصر <activity> الفردية لضبط الدعم لكل نشاط):

<manifest ...>
    <!-- Signal whether the app is adaptive or built just for TV -->
    <uses-feature
        android:name="android.software.leanback"
        android:required="true|false" />
    <!-- Ensure the app can be installed on conventional TVs -->
    <uses-feature
        android:name="android.hardware.touchscreen"
        android:required="false" />
    <application ...>
        <!-- Signal whether the app supports pointer remotes -->
        <property
            android:name="android.software.leanback.supports_touch"
            android:value="true" />
        ...
    </application>
</manifest>

إتاحة تفاعلات النقر والتمرير فوق العناصر والتمرير في الصفحة

عند إتاحة أجهزة التحكّم عن بُعد التي تتضمّن مؤشرًا، تأكَّد من أنّ عناصر واجهة المستخدم تستجيب بشكل مناسب لإدخال المؤشر واللمس في التفاعلات التالية:

  • النقر والاختيار: يجب أن تكون جميع عناصر واجهة المستخدم القابلة للتركيز والاختيار قابلة للنقر باستخدام جهاز التحكّم عن بُعد الذي يتضمّن مؤشرًا، بما يتوافق مع سلوك الاختيار باستخدام لوحة التحكّم (KEYCODE_DPAD_CENTER).
    • ‫Jetpack Compose: استخدِم المُعدِّلات Modifier.clickable() أو pointerInput. لمزيد من التفاصيل، يُرجى الاطّلاع على النقر والضغط.
    • طرق العرض: يمكنك معالجة الأحداث الناتجة عن النقر على طرق العرض. لمزيد من التفاصيل، يُرجى الاطّلاع على نظرة عامة على أحداث الإدخال.
  • حالات التمرير المرئية: توفّر تأثير تمرير مرئي واضح للإشارة إلى عندما يتم وضع مؤشر المؤشر فوق عنصر قابل للتحديد.
  • التمرير السريع والتمرير السريع جدًا: يجب أن يعمل التمرير الأفقي والعمودي الذي يتم تفعيله من خلال إيماءة التمرير السريع أو التمرير السريع جدًا على زر لوحة التحكم الأوسط الحسّاس للمس بسلاسة في جميع المحتوى القابل للتمرير.
  • التمرير بالسحب: يجب أن يتمكّن المستخدمون من السحب للتمرير عموديًا (للأعلى والأسفل) أو أفقيًا (لليمين واليسار) في الحاويات القابلة للتمرير.
    • ‫Jetpack Compose: تتيح الحاويات العادية القابلة للتمرير استخدام المؤشر والتمرير باللمس تلقائيًا. للاطّلاع على عمليات التنفيذ المخصّصة، يُرجى مراجعة إدخال المؤشر في Compose.
    • طرق العرض: تتيح طرق العرض العادية القابلة للتمرير إمكانية التمرير باللمس تلقائيًا. لمعالجة الإدخال المخصّص، يُرجى الاطّلاع على اللمس والإدخال.
  • التقديم والترجيع في تشغيل الوسائط: أثناء تشغيل الوسائط (مثل البرامج التلفزيونية والأفلام)، يجب أن يتمكّن المستخدمون من التفاعل مع شريط تقدّم التشغيل (شريط التقديم والترجيع) من خلال الإشارة والنقر للانتقال إلى طابع زمني سابق أو مستقبلي، بالإضافة إلى السحب (التقديم والترجيع) على طول شريط التقدم للانتقال إلى وقت محدّد.

التعامل مع أحداث الأزرار

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

أحداث واجهة مستخدم التلفزيون

يمكنك تخصيص سلوك واجهة مستخدم التلفزيون للأزرار التي تنشئ أنواع KeyEvent كما هو موضّح في الجدول التالي:

KeyEvent السلوك
KEYCODE_BUTTON_B، KEYCODE_BACK رجوع
‫KEYCODE_BUTTON_SELECT،‏ KEYCODE_BUTTON_A،‏ KEYCODE_ENTER،‏ KEYCODE_DPAD_CENTER،‏ KEYCODE_NUMPAD_ENTER خيارات
KEYCODE_DPAD_UP وKEYCODE_DPAD_DOWN وKEYCODE_DPAD_LEFT وKEYCODE_DPAD_RIGHT التنقل

أحداث تشغيل الوسائط

عندما يشاهد المستخدم الوسائط، يمكنك تخصيص سلوك للأزرار التي تنشئ أنواع KeyEvent كما هو موضّح في الجدول التالي. إذا كان تطبيقك يتحكّم في MediaSession، استخدِم MediaControllerAdapter لاستدعاء إحدى طُرق MediaControllerCompat.TransportControls الموضّحة في الجدول. لاحظ أن أزرار الاختيار تعمل كأزرار تشغيل أو إيقاف مؤقت في هذا السياق.

KeyEvent استدعاء TransportControls السلوك
‫BUTTON_SELECT،‏ BUTTON_A،‏ ENTER،‏ DPAD_CENTER،‏ KEYCODE_NUMPAD_ENTER play() تشغيل
BUTTON_START، BUTTON_SELECT، BUTTON_A، ENTER، DPAD_CENTER، KEYCODE_NUMPAD_ENTER pause() إيقاف مؤقت
BUTTON_R1 skipToNext() التخطي إلى التالي
BUTTON_L1 skipToPrevious() التخطي إلى السابق
DPAD_RIGHT وBUTTON_R2 وAXIS_RTRIGGER وAXIS_THROTTLE fastForward() تقديم سريع
DPAD_LEFT وBUTTON_L2 وAXIS_LTRIGGER وAXIS_BRAKE rewind() ترجيع
لا ينطبق stop() إيقاف

توفير سلوك مناسب لزر الرجوع

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

بما أنّ زر "الرجوع" لا يؤدي إلا إلى التنقّل الخطي للخلف، يمكنك استخدامه لمغادرة قائمة داخل التطبيق تم فتحها باستخدام زر مختلف والعودة إلى التطبيق. يجب أن يؤدي الضغط المتتالي على زر "الرجوع" في النهاية إلى الشاشة الرئيسية في Android TV. على سبيل المثال: تشغيل اللعبة > شاشة إيقاف اللعبة مؤقتًا > الشاشة الرئيسية للعبة > الشاشة الرئيسية في Android TV أو تشغيل برنامج تلفزيوني > الشاشة الرئيسية لتطبيق البث التلفزيوني

شاشة Android TV الرئيسية

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

التعامل مع وحدات التحكّم في الألعاب

عند إنشاء ألعاب لأجهزة Android TV، يجب تصميم نظام التحكّم ليعمل مع كلّ من أجهزة التحكّم عن بعد للتلفزيون وأذرع التحكّم في الألعاب المخصّصة.

التوافق مع عناصر التحكّم في لوحة التحكّم

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

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

  • وضِّح متطلبات وحدة التحكّم مسبقًا: استخدِم وصف Google Play لإعلام اللاعب بأي توقعات بشأن وحدات التحكّم. إذا كانت اللعبة تناسب جهاز تحكّم في الألعاب مزوّدًا بذراع تحكّم أكثر من جهاز تحكّم في الألعاب مزوّدًا بلوحة تحكّم فقط، يجب توضيح ذلك. قد يحصل اللاعب الذي يستخدم وحدة تحكّم غير مناسبة للعبة على تجربة سيئة ويمنح لعبتك تقييمًا سيئًا.
  • استخدام تعيين أزرار متسق: يُعدّ تعيين الأزرار بشكل بديهي أمرًا أساسيًا لتوفير تجربة مستخدم جيدة. على سبيل المثال، يجب الالتزام بالمعايير المقبولة من خلال استخدام الزر "أ" للقبول والزر "ب" للإلغاء. يمكنك أيضًا توفير المرونة من خلال السماح للمستخدم بإعادة تعيين الأزرار. لمزيد من المعلومات حول ربط الأزرار، يُرجى الاطّلاع على التعامل مع إجراءات وحدة التحكّم.
  • رصد إمكانات وحدة التحكّم وضبطها وفقًا لذلك: يمكنك الاستعلام عن وحدة التحكّم لمعرفة إمكاناتها وتحسين التوافق بين وحدة التحكّم واللعبة. على سبيل المثال، قد تهدف إلى أن يوجّه اللاعب عنصرًا من خلال تحريك وحدة التحكّم في الهواء، ولكن إذا كانت وحدة التحكّم الخاصة باللاعب تفتقر إلى مقياس التسارع وجهاز الجيروسكوب، فلن يعمل التلويح. استعلم عن وحدة التحكّم، وإذا لم تكن ميزة كشف الحركة متاحة، يمكنك التبديل إلى نظام تحكّم بديل متاح. لمزيد من المعلومات حول الاستعلام عن إمكانات وحدة التحكّم، يُرجى الاطّلاع على دعم وحدات التحكّم في جميع إصدارات Android.

استخدام الأزرار المناسبة

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

التعامل مع وحدات تحكّم متعددة

عندما يلعب عدة لاعبين لعبة، ولكل منهم وحدة تحكّم خاصة به، من المهم ربط كل لاعب بوحدة التحكّم الخاصة به. للحصول على معلومات حول كيفية تنفيذ عملية تحديد رقم وحدة التحكّم، يُرجى الاطّلاع على getControllerNumber().

التعامل مع حالات انقطاع اتصال وحدة التحكّم

عند انقطاع اتصال وحدة التحكّم في منتصف اللعبة، يجب إيقاف اللعبة مؤقتًا وعرض مربّع حوار يطلب من اللاعب إعادة توصيل وحدة التحكّم.

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

عرض تعليمات وحدة التحكّم

إذا كانت لعبتك توفّر تعليمات مرئية للتحكّم في الألعاب، استخدِم صورة لذراع التحكّم في الألعاب خالية من العلامات التجارية ولا تتضمّن سوى الأزرار المتوافقة مع Android.

للحصول على نماذج صور لجهاز تحكّم متوافق مع Android، يمكنك تنزيل نموذج جهاز التحكّم في الألعاب على Android TV (ملف ZIP). ويتضمّن وحدة تحكّم بيضاء على خلفية سوداء ووحدة تحكّم سوداء على خلفية بيضاء، كما هو موضّح في الشكل 1، كملف PNG وملف Adobe® Illustrator®‎.

**الشكل 1** مثال على تعليمات وحدة التحكّم باستخدام نموذج جهاز التحكّم في الألعاب على Android TV
السابق
أجهزة تلفزيون مقبض
التالي
لوحة مفاتيح على الشاشة