ReactNative/building for tv

نُفِّذ دعم التطبيقات لأجهزة التلفزيون بهدف تشغيل تطبيقات React Native الحالية على نظامَي Apple TV و Android TV مع إجراء تغييرات قليلة أو معدومة على شيفرة JavaScript لتلك التطبيقات.

Android TV

التغييرات في البنية

• الطبقة الأصيلة Native layer: تأكد من إجراء التغييرات التالية على الملف AndroidManifest.xml لتشغيل مشروع React Native على نظام Android TV:

 ‫<-- أضف صورة لافتة مخصَّصة لعرضها كأيقونة مشغّل لنظام Android TV --!>
 <application
  ...
  android:banner="@drawable/tv_banner"
  >
    ...
    <intent-filter>
      ...
      ‫<-- مطلوب لإنشاء دلالة تشغيل بصورة صحيحة عند التشغيل على Android TV --!>
      <category android:name="android.intent.category.LEANBACK_LAUNCHER"/>
    </intent-filter>
    ...
  </application>

• طبقة JavaScript: يُضاف دعم Android TV إلى ملف Platform.android.js، ويمكنك التحقق من تشغيل الشيفرة على Android TV من خلال:

var Platform = require('Platform');
var running_on_android_tv = Platform.isTV;

التغييرات في الشيفرة

• الوصول إلى عناصر التحكم القابلة للمس touchable controls: يطبّق إطار العمل أندرويد آليًا مخطط تنقّل موجّه اعتمادًا على الموضع النسبي لعناصر التركيز في عروضك views عند التشغيل على منصة Android TV. لصنف الخلط mixin الذي يُدعَى Touchable شيفرةٌ تُضاف لاكتشاف تغييرات التركيز واستخدام التوابع الحالية لإنشاء المكونات إنشاءً صحيحًا، وبدء الإجراءات الصحيحة عند اختيار العرض باستخدام جهاز التحكم الخاص بالتلفزيون، وبالتالي ستعمل المكونات TouchableWithoutFeedback و TouchableHighlight و TouchableOpacity و TouchableNativeFeedback كما هو متوقع، حيث:
  • سينفَّذ الحدث onFocus عندما يجري التركيز على العرض الملموس.
  • سينفَّذ الحدث onBlur عندما يخرج العرض الملموس عن التركيز.
  • سينفَّذ الحدث onPress عند اختيار العرض الملموس من خلال الضغط على زر اختيار "select" في جهاز تحكم التلفزيون.

• دخل جهاز التحكم / لوحة المفاتيح الخاصة بالتلفزيون: يضبط صنفٌ جديد وأصيل native هو ReactAndroidTVRootViewHelper معالجاتِ أحداث مفاتيح خاصة بأحداث جهاز تحكم التلفزيون. تنبِّه أحداثُ جهاز تحكم التلفزيون حدثَ جافاسكريبت، وستلتقط نسخ كائن جافا سكريبت TVEventHandler هذا الحدث. يمكن لشيفرة التطبيق التي تطبّق معالجة مخصصة لأحداث جهاز التحكم بالتلفزيون إنشاء نسخة من الكائن TVEventHandler والاستماع إلى هذه الأحداث كما يلي:

var TVEventHandler = require('TVEventHandler');

class Game2048 extends React.Component {
  _tvEventHandler: any;

  _enableTVEventHandler() {
    this._tvEventHandler = new TVEventHandler();
    this._tvEventHandler.enable(this, function (cmp, evt) {
      if (evt && evt.eventType === 'right') {
        cmp.setState({ board: cmp.state.board.move(2) });
      } else if (evt && evt.eventType === 'up') {
        cmp.setState({ board: cmp.state.board.move(1) });
      } else if (evt && evt.eventType === 'left') {
        cmp.setState({ board: cmp.state.board.move(0) });
      } else if (evt && evt.eventType === 'down') {
        cmp.setState({ board: cmp.state.board.move(3) });
      } else if (evt && evt.eventType === 'playPause') {
        cmp.restartGame();
      }
    });
  }

  _disableTVEventHandler() {
    if (this._tvEventHandler) {
      this._tvEventHandler.disable();
      delete this._tvEventHandler;
    }
  }

  componentDidMount() {
    this._enableTVEventHandler();
  }

  componentWillUnmount() {
    this._disableTVEventHandler();
  }
}

• دعم قائمة Dev: سيُظهر الأمر cmd-M قائمة المطور developer menu ضمن المحاكي الذي تنفَّذ عليه الشيفرة كما يحدث في نظام الأندرويد، ولكن إن أردت إظهار قائمة المطور في جهاز Android TV حقيقي، فاضغط زر قائمة menu أو اضغط مطولًا على زر التقدّم السريع fast-forward في جهاز التحكم. (لا تهز جهاز Android TV، فهذا بالتأكيد لن يعمل).

• مشاكل شائعة:
  • لا تعمل مكونات TextInput حالًا، أي لا يمكنها تلقّي التركيز آليًا.
    • لكن يمكن استخدام مرجع ref لتشغيل inputRef.current.focus()‎ يدويًا.
    • يمكنك تغليف عناصر الإدخال داخل المكون TouchableWithoutFeedback وتشغيل التركيز في حدث onFocus لهذا المكون القابل للمس، إذ يتيح ذلك فتح لوحة المفاتيح باستخدام الأسهم.
    • قد تعيد لوحة المفاتيح ضبط حالتها بعد كل ضغطة مفتاح (قد يحدث هذا داخل محاكي Android TV فقط).
  • لا يستطيع محتوى المكونات Modal تلقّي التركيز (ألقِ نظرة على هذه المشكلة بالتفصيل).

tvOS

مهملة: استعمل react-native-tvos بدلًا منها، وانظر صفحة التغييرات على الإصدار 0.62 في التوثيق الرسمي لمزيد من التفاصيل.

التغييرات في البنية

• الطبقة الأصيلة Native layer: تحتوي جميع مشاريع React Native Xcode أهدافًا لبناء أنظمة Apple TV بحيث تنتهي أسماء هذه المشاريع بالسلسلة '‎-tvOS'.
• react-native init: سيكون لمشاريع React Native الجديدة المُنشَأة باستخدام react-native init هدف Apple TV الذي ينشأ آليًا في مشاريع XCode.
• طبقة جافا سكريبت JavaScript layer: أُضيف دعم Apple TV إلى الملف Platform.ios.js. يمكنك التحقق من عمل الشيفرة على AppleTV من خلال ما يلي:

var Platform = require('Platform');
var running_on_tv = Platform.isTV;

// ‫إن أردت أن تكون أكثر تحديدًا وأن تكتشف فقط الأجهزة التي تعمل بنظام tvOS
// ‫مع عدم وجود أجهزة Android TV فيمكنك استخدام ما يلي:
var running_on_apple_tv = Platform.isTVOS;

التغييرات في الشيفرة

• دعم tvOS العام: يغلّف التعريف TARGET_OS_TV جميعَ تغييرات Apple TV المحدَّدة في شيفرة أصيلة، ويتضمن ذلك التغييرات لمنع واجهات برمجة التطبيقات غير المدعومة على نظام tvOS مثل web views و sliders و switches و status bar وما إلى ذلك، والتغييرات لدعم إدخال المستخدم من جهاز التحكم أو لوحة المفاتيح الخاصة بالتلفزيون.

• أساس الشيفرة codebase المشترك: بما أن نظامَي tvOS و iOS يشتركان في معظم الشيفرة المكتوبة بلغة Objective-C و JavaScript ، فإن معظم توثيق نظام iOS ينطبق على نظام tvOS.
• الوصول إلى عناصر التحكم القابلة للمس touchable controls: صنف العرض الأصيل هو RCTTVView عند التشغيل على Apple TV، ولهذا الصنف توابع إضافية للاستفادة من محرك تركيز نظام tvOS. لصنف الخلط mixin الذي يُدعَى Touchable شيفرةٌ تُضاف لاكتشاف تغييرات التركيز واستخدام التوابع الحالية لإنشاء المكونات إنشاءً صحيحًا، وبدء الإجراءات الصحيحة عند اختيار العرض باستخدام جهاز التحكم الخاص بالتلفزيون، وبالتالي ستعمل المكونات TouchableWithoutFeedback و TouchableHighlight و TouchableOpacity كما هو متوقع، حيث:
  • سينفَّذ الحدث onFocus عندما يجري التركيز على العرض الملموس.
  • سينفَّذ الحدث onBlur عندما يخرج العرض الملموس عن التركيز.
  • سينفَّذ الحدث onPress عند اختيار العرض الملموس من خلال الضغط على زر اختيار "select" في جهاز تحكم التلفزيون.

• دخل جهاز التحكم / لوحة المفاتيح الخاصة بالتلفزيون: يضبط صنف جديد أصيل أدوات التعرف على الإيماءات لأحداث جهاز التحكم بالتلفزيون، إذ يطلِق هذا الصنف عند ظهور أحداث جهاز التحكم بالتلفزيون إشعاراتٍ يلتقطها الصنف الفرعي RCTTVNavigationEventEmitter (وهو صنف فرعي من الصنف RCTEventEmitter )، والذي يطلق بدوره حدث JS، وتلتقط نسخٌ من كائن جافا سكريبت TVEventHandler هذا الحدث. يمكن لشيفرة التطبيق التي تطبّق معالجة مخصصة لأحداث التحكم بالتلفزيون إنشاء نسخة من الكائن TVEventHandler والاستماع إلى هذه الأحداث كما يلي:

var TVEventHandler = require('TVEventHandler');

class Game2048 extends React.Component {
  _tvEventHandler: any;

  _enableTVEventHandler() {
    this._tvEventHandler = new TVEventHandler();
    this._tvEventHandler.enable(this, function (cmp, evt) {
      if (evt && evt.eventType === 'right') {
        cmp.setState({ board: cmp.state.board.move(2) });
      } else if (evt && evt.eventType === 'up') {
        cmp.setState({ board: cmp.state.board.move(1) });
      } else if (evt && evt.eventType === 'left') {
        cmp.setState({ board: cmp.state.board.move(0) });
      } else if (evt && evt.eventType === 'down') {
        cmp.setState({ board: cmp.state.board.move(3) });
      } else if (evt && evt.eventType === 'playPause') {
        cmp.restartGame();
      }
    });
  }

  _disableTVEventHandler() {
    if (this._tvEventHandler) {
      this._tvEventHandler.disable();
      delete this._tvEventHandler;
    }
  }

  componentDidMount() {
    this._enableTVEventHandler();
  }

  componentWillUnmount() {
    this._disableTVEventHandler();
  }
}

• دعم قائمة Dev: سيُظهر الأمر cmd-D قائمة المطور developer menu ضمن المحاكي الذي تنفّذ عليه الشيفرة كما يحدث في نظام iOS، ولكن إن أردت إظهار قائمة المطور في جهاز Apple TV حقيقي، فاضغط مطوَّلًا على زر تشغيل/ توقف play/pause في جهاز التحكم عن بعد. (لا تهز جهاز Apple TV، فهذا بالتأكيد لن يعمل).
• حركات جهاز التحكم بالتلفزيون: تطبّق شيفرة RCTTVView الأصيلة حركات ذات زاوية نظر مختلفة توصي بها شركة Apple للمساعدة في توجيه العين أثناء تنقل المستخدم عبر العروض. يمكن تعطيل الحركات أو تعديلها باستخدام خصائص عرض اختيارية جديدة.
• التنقل الخلفي باستخدام زر قائمة menu في جهاز تحكم التلفزيون: يدعم المكوّن BackHandler-الذي كُتِب في الأصل لدعم زر الرجوع للخلف في نظام Android- أيضًا التنقل الخلفي على أجهزة Apple TV باستخدام زر القائمة menu على جهاز تحكم التلفزيون.
• سلوك المكوّن TabBarIOS: يغلّف المكون TabBarIOS واجهة برمجة تطبيقات UITabBar الأصيلة، والتي تعمل بصورةٍ مختلفة على أجهزة Apple TV. لا يمكن ضبط عنصر شريط علامات التبويب المحدَّد إلّا باستخدام لغة JavaScript عند التصيير render الأولي، لتجنب إعادة التصيير المتوترة (غير المستقرة) jittery re-rendering لشريط علامات التبويب في نظام tvOS، ويتحكم المستخدم بهذا الشريط بعد ذلك من خلال الشيفرة الأصيلة.
• مشاكل شائعة:
  • المكوّن ListView مع التمرير: يمكن حل المشكلة عن طريق ضبط removeClippedSubviews بالقيمة false في المكوّن ListView والمكوّنات المماثلة.

مصادر

• صفحة Building For TV Devices في توثيق React Native الرسمي.