ReactNative/building for tv

بناء تطبيقات أجهزة التلفزيون

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

Android TV

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

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

 <!-- Add custom banner image to display as Android TV launcher icon -->
 <application
  ...
  android:banner="@drawable/tv_banner"
  >
    ...
    <intent-filter>
      ...
      <!-- Needed to properly create a launch intent when running on 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

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

• الطبقة الأصيلة 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 وما إلى ذلك، والتغييرات لدعم إدخال المستخدم من جهاز تحكم التلفزيون أو لوحة المفاتيح.

• أساس الشيفرة المشترك: بما أن 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 الرسمي