处理 TV 硬件

TV 硬件与其他 Android 设备截然不同。TV 不提供其他 Android 设备上提供的一些硬件功能,如触摸屏、相机和 GPS 接收器。TV 还完全依赖于辅助硬件设备: 用户必须使用遥控器或游戏手柄才能与 TV 应用进行交互。(如需了解 各种输入法,请参阅 管理 TV 控制器。)

构建 TV 应用时,请仔细考虑在 TV 硬件上运行应用的硬件限制和要求。检查您的应用是否在 TV 上运行,并处理不支持的 硬件功能。

检查 TV 设备

如果您在构建一款在 TV 设备和其他设备上都能运行的应用,可能需要 检查您的应用正在什么类型的设备上运行,并相应调整应用的工作方式。例如,如果您开发的应用可通过 Intent 启动,请检查设备属性以确定是启动面向 TV 的 Activity 还是手机 Activity。

如需确定您的应用是否正在 TV 设备上运行,推荐的做法是使用 PackageManager.hasSystemFeature() 方法来检查 该设备是否正在电视模式下运行。以下示例代码向您展示了如何检查您的应用是否正在 TV 设备上运行:

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")
}

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");
}

处理不支持的硬件功能

根据应用的设计和功能,您或许能够解决某些 硬件功能无法使用的问题。本部分介绍哪些硬件功能通常 不适用于 TV,以及如何检测缺少的硬件功能,并就这些功能的替代方案提供了建议。

不支持的 TV 硬件功能

TV 的用途不同于其他设备,因此它们没有其他 Android 设备通常具备的硬件功能。因此,Android 系统在 TV 设备上不支持以下功能:

硬件 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

注意:某些 TV 控制器具有麦克风,但与此处所述的麦克风硬件功能并不相同。控制器麦克风是完全 受支持的。

如需查看功能、子功能及其描述符的完整列表,请参阅 功能参考

声明对 TV 的硬件要求

Android 应用可以在应用清单中声明硬件功能要求,以确保用户不会将其安装在不提供这些功能的设备上。 如果您要扩展现有 应用以便在 TV 上使用,请仔细检查应用的清单中是否声明了任何可能会导致该应用无法安装在 TV 设备上的硬件要求。

如果您的应用使用 TV 上不具备的硬件功能(如触摸屏或相机),但不使用这些功能仍可运行,请修改应用的清单,以指明这些并非应用必需的功能。以下这段清单文件代码段 演示了如何声明您的应用不要求具备 TV 设备上不提供的硬件功能,尽管您的应用可能会在非 TV 设备上使用这些功能:

<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"

所有用于 TV 设备的应用都必须声明触摸屏功能并非必需功能, 如 TV 应用使用入门中所述。如果您的应用正常情况下使用 TV 设备不支持的一项或多项功能,请在清单文件中将这些功能的 android:required 属性设置更改为 false

注意:如果将硬件功能的值设为 true 来将其声明为必需功能,就会导致您的应用无法安装在 TV 设备上或出现在 Android TV 主屏幕启动器中。

注意隐含硬件功能的权限

某些 uses-permission 清单声明 隐含硬件功能。此行为意味着,在您的应用清单中请求某些 权限可能会导致您的应用无法在 TV 设备上安装和使用。下列通常请求的权限会形成隐式硬件功能 要求:

权限 隐含的硬件功能
RECORD_AUDIO android.hardware.microphone
CAMERA android.hardware.camera
android.hardware.camera.autofocus
ACCESS_COARSE_LOCATION

android.hardware.location

android.hardware.location.network(仅限目标 API 级别 20 或更低级别 )

ACCESS_FINE_LOCATION

android.hardware.location

android.hardware.location.gps(仅限目标 API 级别 20 或更低级别 )

ACCESS_WIFI_STATE
CHANGE_WIFI_STATE

android.hardware.wifi

某些 TV 设备仅具有以太网连接。

如需查看隐含硬件功能要求的权限请求的完整列表,请参阅 uses-feature 指南。如果您的应用请求上面列出的某项功能,请在清单中为这项隐含的硬件功能添加 uses-feature 声明,指明它并非 必需功能。android:required="false"

注意:如果您的应用以 Android 5.0(API 级别 21)或 更高版本为目标平台且使用 ACCESS_COARSE_LOCATIONACCESS_FINE_LOCATION 权限,那么即使 TV 设备没有网卡或 GPS 接收器,用户仍然可以在 TV 设备上安装您的 应用。

在您决定使硬件功能成为应用的可选功能后,必须在运行时检查这些功能的 可用性,然后相应调整应用的行为。下一部分介绍如何检查硬件功能,并就更改应用行为的方法提供了一些建议。

如需详细了解如何在清单中过滤和声明功能,请参阅 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.")
}

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.");
}

触摸屏

大多数 TV 设备都没有触摸屏或指针输入功能,完全依赖于 方向键遥控器进行导航。TV 应用必须始终支持方向键遥控器。

如需详细了解如何正确支持使用 TV 易用型遥控器进行导航,请参阅 TV 导航

声明触控支持

某些 TV 设备支持指针遥控器和触摸屏显示屏。您的应用可以支持点击、 悬停和滚动互动,就像在移动设备上一样,以便在支持这些功能的设备上提供更好的体验。

如果您的应用允许使用触摸模式,您可以通过在 AndroidManifest.xml 中添加 android.software.leanback.supports_touch 并将其设置为 true 来声明触控支持:

<meta-data android:name="android.software.leanback.supports_touch" android:value="true|false"/>

注意:在支持指针遥控器(如空中鼠标或触控板)的设备上,启用此功能 会启用光标和触摸模式,而不是依赖于平台兼容性模拟。省略 此元数据会默认设置为 false

相机

尽管 TV 通常不配备相机,但您仍然可以在 TV 上提供与摄影有关的 应用。例如,如果您有一款拍摄、查看和编辑照片的应用,您可以在 TV 上停用其照片拍摄功能,同时仍允许用户查看甚至编辑 照片。如果您决定让相机相关应用能够在 TV 上使用,请在应用清单中添加以下功能声明:

<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.")
}

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

TV 是位置固定的室内设备,并未内置全球定位系统 (GPS) 接收器。如果您的应用使用位置信息,您仍可允许用户搜索 位置,或者使用静态位置提供方,如在 TV 设备 设置期间配置的邮政编码。

Kotlin

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

// 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)[0]
                    .apply {
                        Log.d(TAG, postalCode)
                    }
        } catch (e: IOException) {
            Log.e(TAG, "Geocoder error", e)
            null
        }

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);
}

在低功耗模式下暂停播放

某些 TV 设备在用户关闭设备时支持低功耗模式。设备不会关闭,而是停用显示屏并使 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(), 如果您的应用是正在运行的前台应用。如需详细了解如何启动和停止 activity,请参阅 activity 生命周期