أجهزة تلفزيون مقبض

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

عند إنشاء تطبيق للتلفزيون، يجب مراعاة قيود الأجهزة ومتطلبات التشغيل على أجهزة التلفزيون بعناية. تحقَّق مما إذا كان تطبيقك يعمل على تلفزيون، وتعامل مع ميزات الأجهزة غير المتوافقة.

التحقّق من توفّر جهاز تلفزيون

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

الطريقة المقترَحة لتحديد ما إذا كان تطبيقك يعمل على جهاز تلفزيون هي استخدام طريقة PackageManager.hasSystemFeature للتحقّق مما إذا كان الجهاز يعمل في وضع التلفزيون. يوضّح المثال التالي كيفية التحقّق مما إذا كان تطبيقك يعمل على جهاز تلفزيون:

Kotlin

const val TAG = "DeviceTypeRuntimeCheck"

val isTelevision = packageManager.hasSystemFeature(PackageManager.FEATURE_LEANBACK)
if (isTelevision) {
    Log.d(TAG, "Running on a TV Device")
} else {
    Log.d(TAG, "Running on a non-TV Device")
}
Hardware.kt

Java

public static final String TAG = "DeviceTypeRuntimeCheck";

boolean isTelevision = getPackageManager().hasSystemFeature(PackageManager.FEATURE_LEANBACK);
if (isTelevision) {
    Log.d(TAG, "Running on a TV Device");
} else {
    Log.d(TAG, "Running on a non-TV Device");
}

التعامل مع ميزات الأجهزة غير المتوافقة

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

ميزات أجهزة التلفزيون غير المتوافقة

تختلف أجهزة التلفزيون عن الأجهزة الأخرى في الغرض من استخدامها، لذا لا تتوفّر فيها ميزات الأجهزة التي غالبًا ما تتوفّر في الأجهزة الأخرى التي تعمل بنظام التشغيل Android. لهذا السبب، لا يتيح نظام Android الميزات التالية على أجهزة التلفزيون:

الأجهزة	وصف ميزة Android
شاشة تعمل باللمس	android.hardware.touchscreen
محاكي الشاشة التي تعمل باللمس	android.hardware.faketouch
الاتصالات الهاتفية	android.hardware.telephony
الكاميرا	android.hardware.camera
اتصال قصير المدى (NFC)	android.hardware.nfc
نظام تحديد المواقع العالمي (GPS)	android.hardware.location.gps
الميكروفون	android.hardware.microphone
أدوات الاستشعار	android.hardware.sensor
شاشة في الاتجاه العمودي	android.hardware.screen.portrait

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

يُرجى الاطّلاع على مرجع الميزات للحصول على قائمة كاملة بالميزات والميزات الفرعية وأوصافها.

تضمين متطلبات الأجهزة لأجهزة التلفزيون في بيان الأذونات

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

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

<uses-feature android:name="android.hardware.touchscreen"
        android:required="false"/>
<uses-feature android:name="android.hardware.faketouch"
        android:required="false"/>
<uses-feature android:name="android.hardware.telephony"
        android:required="false"/>
<uses-feature android:name="android.hardware.camera"
        android:required="false"/>
<uses-feature android:name="android.hardware.nfc"
        android:required="false"/>
<uses-feature android:name="android.hardware.location.gps"
        android:required="false"/>
<uses-feature android:name="android.hardware.microphone"
        android:required="false"/>
<uses-feature android:name="android.hardware.sensor"
        android:required="false"/>
<!-- Some TV devices have an ethernet connection only -->
<uses-feature android:name="android.hardware.wifi"
        android:required="false"/>

ملاحظة: تتضمّن بعض الميزات ميزات فرعية، مثل android.hardware.camera.front، كما هو موضّح في مرجع الميزات. احرص على وضع علامة required="false" على أي ميزات فرعية مستخدَمة أيضًا في تطبيقك.

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

تنبيه: إنّ الإعلان عن ميزة مخصَّصة للأجهزة على أنّها مطلوبة من خلال ضبط قيمتها على true يمنع تثبيت تطبيقك على أجهزة التلفزيون أو ظهوره في مشغّل الشاشة الرئيسية في Android TV.

الانتباه إلى الأذونات التي تتضمّن ميزات الأجهزة

بعض تعريفات ملف البيان uses-permission تتضمّن ميزات الأجهزة. ويعني هذا السلوك أنّ طلب بعض الأذونات في ملف بيان تطبيقك قد يؤدي إلى استبعاد تطبيقك من التثبيت والاستخدام على أجهزة التلفزيون. تؤدي الأذونات التالية المطلوبة عادةً إلى إنشاء متطلبات ضمنية لميزات الأجهزة:

الإذن	ميزة ضمنية للأجهزة
RECORD_AUDIO	android.hardware.microphone
CAMERA	‫android.hardware.camera و android.hardware.camera.autofocus
ACCESS_COARSE_LOCATION	android.hardware.location android.hardware.location.network (مستوى واجهة برمجة التطبيقات المستهدف 20 أو أقل فقط)
ACCESS_FINE_LOCATION	android.hardware.location android.hardware.location.gps (مستوى واجهة برمجة التطبيقات المستهدف 20 أو أقل فقط)
ACCESS_WIFI_STATE CHANGE_WIFI_STATE	android.hardware.wifi تتضمّن بعض أجهزة التلفزيون اتصال إيثرنت فقط.

للحصول على قائمة كاملة بطلبات الحصول على إذن التي تتضمّن متطلبات ميزة في الجهاز، يُرجى الاطّلاع على دليل uses-feature. إذا كان تطبيقك يطلب إحدى الميزات المذكورة سابقًا، يجب تضمين بيان uses-feature في ملف البيان لميزة الأجهزة الضمنية التي تشير إلى أنّها غير مطلوبة. android:required="false".

ملاحظة: إذا كان تطبيقك يستهدف الإصدار 5.0 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 21) أو الإصدارات الأحدث ويستخدم الإذن ACCESS_COARSE_LOCATION أو ACCESS_FINE_LOCATION، سيظل بإمكان المستخدمين تثبيت تطبيقك على جهاز تلفزيون، حتى إذا لم يكن جهاز التلفزيون يحتوي على بطاقة شبكة أو جهاز استقبال GPS.

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

لمزيد من المعلومات حول فلترة الميزات والإعلان عنها في ملف البيان، يُرجى الاطّلاع على دليل uses-feature.

التحقّق من ميزات الأجهزة

يمكن أن يخبرك إطار عمل Android إذا كانت ميزات الأجهزة غير متوفّرة على الجهاز الذي يتم تشغيل تطبيقك عليه. استخدِم طريقة hasSystemFeature(String) للتحقّق من ميزات معيّنة في وقت التشغيل. تتطلّب هذه الطريقة وسيطة سلسلة واحدة تحدّد الميزة التي تريد التحقّق منها.

يوضّح مثال الرمز البرمجي التالي كيفية رصد مدى توفّر ميزات الأجهزة أثناء التشغيل:

Kotlin

// Check whether the telephony hardware feature is available.
if (packageManager.hasSystemFeature(PackageManager.FEATURE_TELEPHONY)) {
    Log.d("HardwareFeatureTest", "Device can make phone calls")
}

// Check whether android.hardware.touchscreen feature is available.
if (packageManager.hasSystemFeature(PackageManager.FEATURE_TOUCHSCREEN)) {
    Log.d("HardwareFeatureTest", "Device has a touchscreen.")
}
Hardware.kt

Java

// Check whether the telephony hardware feature is available.
if (getPackageManager().hasSystemFeature(PackageManager.FEATURE_TELEPHONY)) {
    Log.d("HardwareFeatureTest", "Device can make phone calls");
}

// Check whether android.hardware.touchscreen feature is available.
if (getPackageManager().hasSystemFeature(PackageManager.FEATURE_TOUCHSCREEN)) {
    Log.d("HardwareFeatureTest", "Device has a touchscreen.");
}

شاشة تعمل باللمس

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

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

الإعلان عن إتاحة ميزة اللمس

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

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

<application ...>
    <property
        android:name="android.software.leanback.supports_touch"
        android:value="true|false" />
    ...
</application>

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

الكاميرا

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

<uses-feature android:name="android.hardware.camera" android:required="false" />

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

Kotlin

// Check whether the camera hardware feature is available.
if (packageManager.hasSystemFeature(PackageManager.FEATURE_CAMERA)) {
    Log.d("Camera test", "Camera available!")
} else {
    Log.d("Camera test", "No camera available. View and edit features only.")
}
Hardware.kt

Java

// Check whether the camera hardware feature is available.
if (getPackageManager().hasSystemFeature(PackageManager.FEATURE_CAMERA)) {
    Log.d("Camera test", "Camera available!");
} else {
    Log.d("Camera test", "No camera available. View and edit features only.");
}

نظام تحديد المواقع العالمي (GPS)

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

Kotlin

// Request a static location from the location manager.
val locationManager = this.getSystemService(Context.LOCATION_SERVICE) as LocationManager
val location = locationManager.getLastKnownLocation("static")
if (location == null) {
    Log.e(TAG, "Location is null")
    return
}

// Attempt to get postal code from the static location object.
val geocoder = Geocoder(this)
val address: Address? =
        try {
            geocoder.getFromLocation(location.latitude, location.longitude, 1)?.firstOrNull()
                    ?.apply {
                        Log.d(TAG, postalCode)
                    }
        } catch (e: IOException) {
            Log.e(TAG, "Geocoder error", e)
            null
        }
Hardware.kt

Java

// Request a static location from the location manager.
LocationManager locationManager = (LocationManager) this.getSystemService(
        Context.LOCATION_SERVICE);
Location location = locationManager.getLastKnownLocation("static");

// Attempt to get postal code from the static location object.
Geocoder geocoder = new Geocoder(this);
Address address = null;
try {
  address = geocoder.getFromLocation(location.getLatitude(),
          location.getLongitude(), 1).get(0);
  Log.d("Postal code", address.getPostalCode());

} catch (IOException e) {
  Log.e(TAG, "Geocoder error", e);
}

إيقاف التشغيل مؤقتًا أثناء "وضع توفير الطاقة"

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

لتجنُّب التشغيل أثناء وضع توفير الطاقة، يمكنك إلغاء onStop وإيقاف أي محتوى قيد التشغيل حاليًا:

Kotlin

override fun onStop() {
    // App-specific method to stop playback.
    stopPlayback()
    super.onStop()
}

Java

@Override
public void onStop() {
  // App-specific method to stop playback.
  stopPlayback();
  super.onStop();
}

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