處理 TV 硬體

電視硬體與其他 Android 裝置大不相同,電視不包含其他 Android 裝置上的部分硬體功能,例如觸控螢幕、攝影機和 GPS 接收器。電視也完全依賴次要硬體裝置: 使用者必須使用遙控器或遊戲手把,才能與電視應用程式互動。(如要瞭解各種輸入方式,請參閱「管理電視遙控器」。)

為 TV 打造應用程式時,請仔細考量在 TV 硬體上運作的硬體限制和需求。檢查應用程式是否在電視上執行,並處理不支援的硬體功能。

檢查是否有電視裝置

如果您要建構可在電視裝置和其他裝置上運作的應用程式,可能需要檢查應用程式執行的裝置類型,並調整應用程式的運作方式。舉例來說,如果您有一個可透過 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")
}

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

注意:部分電視遙控器內建麥克風,但這與本文所述的麥克風硬體功能不同。完整支援遙控器麥克風。

如需功能、子功能及其描述元的完整清單,請參閱「 功能參考資料」。

宣告 TV 的硬體需求

Android 應用程式可以在應用程式資訊清單中宣告硬體功能需求,確保應用程式不會安裝在未提供這些功能的裝置上。如果您要擴充現有應用程式,以便在 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 裝置的應用程式都必須宣告不需要觸控螢幕功能。如果應用程式通常會使用電視裝置不支援的一或多項功能,請在資訊清單中,將這些功能的 android:required 屬性設定變更為 false

注意:如果將硬體功能的值設為 true,聲明應用程式需要這項功能,使用者就無法在 TV 裝置上安裝應用程式,應用程式也不會顯示在 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 (僅限目標 API 級別為 20 以下)

ACCESS_FINE_LOCATION

android.hardware.location

android.hardware.location.gps (僅限目標 API 級別為 20 以下)

ACCESS_WIFI_STATE
CHANGE_WIFI_STATE

android.hardware.wifi

部分電視裝置僅支援乙太網路連線。

如需隱含硬體功能需求的權限要求完整清單,請參閱 uses-feature 指南。如果應用程式要求使用先前列出的其中一項功能,請在資訊清單中加入uses-feature聲明,指出隱含的硬體功能並非必要。android:required="false"

注意:如果應用程式指定的是 Android 5.0 (API 級別 21) 以上版本,並使用 ACCESS_COARSE_LOCATIONACCESS_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.")
}

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

觸控螢幕

大多數電視裝置沒有觸控螢幕或指標輸入功能,完全依賴方向鍵 (D-pad) 遙控器進行導覽。電視應用程式一律須支援方向鍵遙控器控制。

如要進一步瞭解如何使用適合電視的控制項正確支援導覽功能,請參閱「電視導覽」。

宣告觸控支援

部分電視裝置支援指標遙控器和觸控螢幕。您的應用程式可以支援點選、懸停和捲動等互動操作,就像在行動裝置上一樣,在支援這些操作的裝置上提供更優質的體驗。

如果應用程式允許觸控模式,您可以在 AndroidManifest.xml 中新增 android.software.leanback.supports_touch 並設為 true,宣告支援觸控功能:

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

注意:在支援指標遙控器 (例如空中滑鼠或觸控板) 的裝置上,啟用這項設定會啟用游標和觸控模式,而非依賴平台相容性模擬。如果省略這項中繼資料,預設值為 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.")
}

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

在低耗電模式下暫停播放

部分電視裝置支援低功耗模式,使用者關閉裝置時會啟動這項模式。裝置不會關機,而是停用螢幕,並在背景執行 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()。如要進一步瞭解如何啟動及停止活動,請參閱「 活動生命週期」。