管理 TV 遙控器

電視裝置需要搭配次要硬體裝置才能與應用程式互動，例如基本遙控器、指標遙控器或遊戲控制器。為提供一致的使用者體驗，應用程式必須支援方向鍵 (D-pad) 輸入、處理控制器離線問題，以及支援多種控制器類型 (包括指標遙控器) 的輸入。

D-Pad 最少控制項

電視裝置的預設控制器是 D-Pad。一般來說，應用程式必須能透過只有上、下、左、右、選取、「返回」和「主畫面」按鈕的遙控器操作。如果您的應用程式是遊戲，通常需要使用具備額外控制項的遊戲控制器，請嘗試僅使用 D-Pad 控制項支援遊戲。否則，請警告使用者必須使用控制器，並讓他們透過 D-Pad 控制器優雅地結束遊戲。

如要進一步瞭解如何使用電視裝置的 D-pad 控制器進行導覽，請參閱「電視導覽」。

處理控制器連線中斷

電視遙控器通常是藍牙裝置，可能會嘗試節省電力，因此會定期進入休眠模式並中斷與電視裝置的連線。也就是說，如果應用程式未設定為處理這些重新連線事件，可能會中斷或重新啟動。在下列任一情況下，都可能發生這類事件：

• 播放幾分鐘的影片時，D-Pad 或遊戲控制器可能會進入休眠模式、與電視裝置中斷連線，然後稍後重新連線。
• 在遊戲過程中，新玩家可能會使用尚未連線的遊戲控制器加入遊戲。
• 在遊戲過程中，玩家可能會離開遊戲並中斷遊戲控制器連線。

凡是會受到連線中斷和重新連線事件影響的電視應用程式活動，都必須在應用程式資訊清單中設定為處理重新連線事件。下列程式碼範例示範如何讓活動處理設定變更，包括鍵盤或導覽裝置連線、中斷連線或重新連線：

<activity
  android:name="com.example.android.TvActivity"
  android:label="@string/app_name"
  android:configChanges="keyboard|keyboardHidden|navigation"
  android:theme="@style/Theme.Leanback">

  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
  </intent-filter>
  ...
</activity>

這項設定變更可讓應用程式在重新連線事件發生時繼續執行，而不是由 Android 架構重新啟動，這樣才能提供良好的使用者體驗。

處理 D-Pad 輸入變化版本

電視裝置使用者可能有多種控制器，舉例來說，使用者可能擁有基本 D-Pad 控制器、指標遙控器或遊戲控制器。遊戲控制器用於 D-Pad 功能時提供的鍵碼，可能與基本 D-Pad 傳送的鍵碼不同。

處理 D-pad 輸入的變化，讓使用者不必切換控制器即可操作應用程式。如要進一步瞭解如何處理輸入變化，請參閱「處理方向鍵輸入」。

支援指標遙控器

部分電視裝置支援指標遙控器，例如空中滑鼠或具備觸控感應方向鍵 (觸控板) 的遙控器。支援指標遙控器後，使用者就能透過點擊式、懸停、滑動和拖曳手勢與應用程式互動，在相容的硬體上享受更流暢的體驗，同時維持完整的 D-Pad 相容性。

在資訊清單中宣告指標遙控器支援

如要指出應用程式可透過指標和觸控輸入操作，請將應用程式資訊清單的 android.software.leanback.supports_touch 中繼資料設為 true：

<manifest ...>
    <!-- Signal whether the app is adaptive or built just for TV -->
    <uses-feature
        android:name="android.software.leanback"
        android:required="true|false" />
    <!-- Ensure the app can be installed on conventional TVs -->
    <uses-feature
        android:name="android.hardware.touchscreen"
        android:required="false" />
    <!-- Signal whether the app supports pointer remotes -->
    <meta-data
        android:name="android.software.leanback.supports_touch"
        android:value="true" />
    <application ...>
        ...
    </application>
</manifest>

支援點擊、懸停和捲動互動

支援指標遙控器時，請確保 UI 元件在下列互動中，能適當回應游標和觸控輸入：

• 點選和選取：所有可聚焦和選取的 UI 元素都必須可使用指標遙控器點選，且選取行為須與 D-Pad 選取 (KEYCODE_DPAD_CENTER) 相同。
  • Jetpack Compose：使用 Modifier.clickable() 或 pointerInput 修飾符。詳情請參閱「輕觸並按壓」。
  • 檢視畫面：處理檢視畫面上的點擊事件。詳情請參閱「輸入事件總覽」。
• 懸停狀態的視覺效果：提供清楚的懸停視覺效果，指出指標游標何時位於可選取的項目上。
  • Jetpack Compose：使用 Modifier.hoverable() 或使用 InteractionSource 觀察懸停狀態。詳情請參閱「處理使用者互動」。
  • 檢視畫面：使用含有 android:state_hovered="true" 的狀態清單可繪項目定義懸停狀態。
• 滑動和撥動捲動：在觸控感應式 D-Pad 中心按鈕上滑動或撥動，即可觸發水平和垂直捲動，且所有可捲動的內容都必須順暢運作。
• 拖曳捲動：使用者必須能夠拖曳，在可捲動的容器中垂直 (上下) 或水平 (左右) 捲動。
  • Jetpack Compose：標準可捲動容器預設支援指標和觸控捲動。如需自訂實作方式，請參閱「Compose 中的指標輸入」。
  • 檢視區塊：標準可捲動檢視區塊預設支援觸控捲動。如需自訂輸入處理作業，請參閱「觸控和輸入」。
• 媒體播放時間軸調整：播放媒體 (例如電視節目和電影) 時，使用者必須能夠透過指向並點選播放進度列 (時間軸)，跳至過去或未來的時間戳記，以及沿著進度列拖曳 (調整) 來尋找特定時間。

處理按鈕事件

當使用者點選控制器上的按鈕時，應用程式會收到含有 KeyEvent 的事件。按鈕的預期行為可能是媒體事件 (例如播放、暫停或停止)，也可能是電視類型事件 (例如選取或瀏覽)。為提供良好的使用者體驗，請為控制器按鈕指派一致的行為。

TV UI 事件

將電視 UI 行為指派給產生 KeyEvent 類型的按鈕，如下表所示：

媒體活動

使用者觀看媒體時，請為按鈕指派行為，產生 KeyEvent 型別，如下表所示。如果應用程式控制 MediaSession，請使用 MediaControllerAdapter 呼叫表格中顯示的 MediaControllerCompat.TransportControls 方法。請注意，選取按鈕在此情境中會做為「播放」或「暫停」按鈕。

提供適當的返回按鈕行為

返回按鈕絕不能做為切換鍵。舉例來說，請勿使用這個手勢開啟及關閉選單。只能用來以麵包屑樣式返回播放器先前顯示的畫面。

由於「返回」按鈕只會執行線性向後導覽，因此你可以使用這個按鈕離開由其他按鈕開啟的應用程式內選單，並返回應用程式。連續按下「返回」按鈕最終必須返回 Android TV 主畫面。例如：遊戲畫面 > 遊戲暫停畫面 > 遊戲主畫面 > Android TV 主畫面；或電視節目播放畫面 > 電視應用程式主畫面

Android TV 主畫面。

如要進一步瞭解如何設計導覽功能，請參閱「設計『返回』和『向上』導覽功能」。如要瞭解如何實作，請參閱「提供適當的返回瀏覽功能」。

處理遊戲的控制器

為 Android TV 建構遊戲時，請設計控制配置，讓標準電視遙控器和專用遊戲控制器都能操作。

支援方向鍵控制

規劃控制配置時，請以 D-pad 控制項為中心，因為這是 Android TV 裝置的預設控制項。玩家必須能使用 D-Pad 控制遊戲的各個環節，包括控制核心遊戲體驗，以及瀏覽選單和廣告。因此，請確保 Android TV 遊戲不會使用「輕觸這裡繼續」這類語言，參照觸控介面。

如何塑造玩家與控制器的互動方式，是打造優質使用者體驗的關鍵。建議你採取下列最佳做法：

• 預先說明控制器需求：在 Google Play 說明中向玩家說明控制器相關規定。如果遊戲更適合使用含搖桿的遊戲手把，而非只有 D-Pad 的遊戲手把，請明確指出。如果玩家使用不適合遊戲的控制器，可能會導致體驗不佳，並給予遊戲負評。
• 使用一致的按鈕對應：直覺的按鈕對應是良好使用者體驗的關鍵。舉例來說，請遵守公認的習慣，使用 A 鍵「接受」，使用 B 鍵「取消」。您也可以允許使用者重新對應按鈕，提供彈性。如要進一步瞭解按鈕對應，請參閱「處理控制器動作」。
• 偵測控制器功能並據以調整：查詢控制器的功能，盡量讓控制器與遊戲相容。舉例來說，您可能希望玩家揮動控制器來操控物體，但如果玩家的控制器沒有加速度計和陀螺儀硬體，揮動控制器就無法操控物體。查詢控制器，如果系統不支援動作偵測，請切換至可用的替代控制配置。如要進一步瞭解如何查詢控制器功能，請參閱「支援在各種 Android 版本上執行控制器」。

使用適當的按鈕

並非所有遊戲控制器都提供「開始」、「搜尋」或「選單」按鈕。請確保 UI 不會依賴這些按鈕的使用。

處理多個控制器

如果有多位玩家使用各自的控制器玩遊戲，請務必對應每位玩家和控制器。如要瞭解如何實作控制器編號識別，請參閱 getControllerNumber()。

處理控制器連線中斷

如果控制器在遊戲過程中中斷連線，請暫停遊戲，並顯示對話方塊，提示中斷連線的玩家重新連線控制器。

此外，對話方塊也會提供疑難排解提示。例如，請播放器「檢查藍牙連線」。如要進一步瞭解如何實作輸入裝置支援功能，請參閱「處理控制器動作」和「藍牙總覽」。

顯示控制器操作說明

如果遊戲提供遊戲控制器操作說明圖片，請使用不含品牌宣傳內容的控制器圖片，且只包含與 Android 相容的按鈕。

如需與 Android 相容的遙控器範例圖片，請下載 Android TV 遊戲手把範本 (ZIP)。包括黑色背景上的白色遙控器，以及白色背景上的黑色遙控器 (如圖 1 所示)，格式為 PNG 檔案和 Adobe® Illustrator® 檔案。