本頁面由 Cloud Translation API 翻譯而成。

Switch to English

開始使用 TV 應用程式

TV 應用程式採用的架構與手機和平板電腦應用程式相同。此相似性意味著，您可以修改現有的應用程式，改為在 TV 裝置上執行，或是根據您所建構的 Android 應用程式知識建立新的應用程式。

重要事項：您的應用程式必須符合特定條件，才有資格成為 Google Play 的 Android TV 應用程式。詳情請參閱「TV 應用程式品質指南」中列出的規定。

本指南說明如何設定開發環境以建構 TV 應用程式，以及讓應用程式在 TV 裝置上執行所需的最低必要變更。

如要瞭解如何設計電視專用應用程式，請參閱「為電視設計」和「打造電視版面配置」。如要查看範例 TV 應用程式，請參閱 Android TV GitHub 存放區中的 Android Leanback 範例應用程式。

判斷支援的媒體格式

請參閱下列說明文件，瞭解 Android TV 支援的轉碼器、通訊協定和格式：

設定電視專案

本節說明如何設定 TV 專案，無論您是要修改現有的 Android 應用程式，以在 TV 裝置上執行，或是建立新的 TV 應用程式。如果您已有 Android 應用程式，只要新增 Android TV 支援，就可以為電視設計使用者介面，同時重複使用現有的應用程式架構。

建立在 TV 裝置上執行的應用程式時，需要使用兩個主要元件：

TV 活動：在應用程式資訊清單中，宣告預計在電視裝置上執行的活動。
「TV Library」(電視程式庫)：視需要加入一或多個適用於電視裝置的 androidx 程式庫，請參閱本指南的另一節。這些程式庫提供了用來建構使用者介面的小工具。

必要條件

在開始建構電視專用應用程式前，您必須採取下列步驟：

將 SDK 工具更新至 24.0.0 以上版本。
新版 SDK 工具可讓您建構及測試 TV 應用程式。
將 SDK 更新至 Android 5.0 (API 21) 以上版本。
更新平台版本為 TV 應用程式提供新的 API。
建立或更新應用程式專案。
如要存取電視裝置的新 API，請建立專案或修改指定 Android 5.0 (API 級別 21) 以上版本的現有專案。

宣告 TV 活動

打算在電視裝置上執行的應用程式，必須在其資訊清單中宣告電視的啟動器活動。系統會使用 CATEGORY_LEANBACK_LAUNCHER 意圖篩選器執行此操作。這個篩選器會將您的應用程式視為可透過電視使用，並可讓 Google Play 識別為電視應用程式。當使用者在電視主畫面上選取您的應用程式時，這個意圖可識別要啟動的活動。

下列程式碼片段說明如何在資訊清單中加入此意圖篩選器：

<application
  android:banner="@drawable/banner" >
  ...
  <activity
    android:name="com.example.android.MainActivity"
    android:label="@string/app_name" >

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

  <activity
    android:name="com.example.android.TvActivity"
    android:label="@string/app_name"
    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>
</application>

此範例中的第二個活動資訊清單項目會指定在電視裝置上啟動的活動。

注意：如果您沒有在應用程式中加入 CATEGORY_LEANBACK_LAUNCHER 意圖篩選器，則在 TV 裝置上執行 Google Play 的使用者不會看到。此外，如果您的應用程式在使用開發人員工具載入電視裝置上時沒有這個篩選器，該應用程式就不會顯示在 TV 使用者介面中。

TV 應用程式的使用者介面 (或現有應用程式的電視部分) 必須提供簡潔的介面，方便利用 10 英尺遠的地方使用遙控器輕鬆瀏覽。如果您修改現有的應用程式以便在電視上使用，請不要針對電視採用相同的活動版面配置。如需為電視設計應用程式的指南，請參閱為電視設計。如要進一步瞭解電視上介面版面配置的最低實作需求，請參閱「建構電視版面配置」。

宣告 Leanback 支援

宣告您的應用程式使用 Android TV 所需的 Leanback 使用者介面。如果應用程式同時在行動裝置和 Android TV 上執行，請將 required 屬性值設為 false。如果將 required 屬性值設為 true，應用程式只能在使用 Leanback UI 的裝置上執行。

<manifest>
    <uses-feature android:name="android.software.leanback"
        android:required="false" />
    ...
</manifest>

不必宣告觸控螢幕

可在電視裝置上執行的應用程式不需要透過觸控螢幕輸入。為明確起見，電視應用程式的資訊清單必須宣告 android.hardware.touchscreen 功能非必要。這項設定會將您的應用程式視為可在 TV 裝置上運作，因此您必須將應用程式視為 Google Play 的電視應用程式。以下程式碼範例說明如何加入此資訊清單宣告：

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

注意：您必須在應用程式資訊清單中宣告並非觸控螢幕，如以下程式碼範例所示。否則，您的應用程式不會顯示在 TV 裝置上的 Google Play 中。

Android TV 應用程式必須為每個本地化內容提供主畫面圖示和橫幅圖片。視 Android TV 裝置而定，系統會使用圖示或橫幅做為應用程式啟動點，顯示在應用程式和遊戲列的主畫面上。

如要在應用程式中新增這些資訊，請在資訊清單中描述圖示和橫幅，如下所示：

<application
    ...
    android:icon="@mipmap/ic_launcher"
    android:banner="@drawable/banner" >
    ...
</application>

主畫面圖示

如同所有 Android 應用程式，Android TV 應用程式都必須提供主畫面圖示。如要瞭解為應用程式找出最佳啟動點，以及詳細的素材資源規定，請參閱 Android TV 應用程式圖示和橫幅規範。

將 android:banner 屬性與 <application> 標記搭配使用，即可為所有應用程式活動提供預設橫幅，或是與 <activity> 標記搭配使用，為特定活動提供橫幅。

如果是橫幅，請使用大小為 320 x 180 像素的 xhdpi 資源。文字必須包含。如果應用程式支援多種語言，您必須針對每種支援的語言提供不同版本的橫幅，並以文字呈現。

變更啟動器顏色

注意：在 Android 12 以上版本中，使用 SplashScreen 平台 API 建構的自訂啟動畫面動畫不支援 Android TV 應用程式。

TV 應用程式啟動時，系統會顯示動畫，與展開的實心圓形類似。如要自訂動畫的顏色，請將電視應用程式或活動的 android:colorPrimary 屬性設為特定顏色。此外，請將兩個轉場重疊屬性設定為 true，如下列主題資源 XML 檔案中的程式碼片段所示：

<resources>
    <style ... >
      <item name="android:colorPrimary">@color/primary</item>
      <item name="android:windowAllowReturnTransitionOverlap">true</item>
      <item name="android:windowAllowEnterTransitionOverlap">true</item>
    </style>
</resources>

如要進一步瞭解如何使用主題和樣式，請參閱「樣式與主題」。

新增電視媒體庫

Jetpack 包含 androidx 套件程式庫，可與 TV 應用程式搭配使用。這些程式庫為電視裝置提供 API 和使用者介面小工具：

打造 TV 應用程式

完成上述步驟後，就可以開始建構適用於大螢幕的應用程式！請參閱下列其他主題，瞭解如何建構 Android TV 應用程式：

建構電視播放應用程式：電視是專為娛樂而打造，因此 Android 提供一系列使用者介面工具和小工具，可用於打造可播放影片和音樂的電視應用程式，讓使用者能瀏覽他們想看的內容。
協助使用者在 Android TV 上找到你的內容：我們提供所有內容選項，方便使用者輕鬆尋找。因此，提供這類內容非常重要。本指南說明如何在電視裝置上顯示內容。
打造電視遊戲：電視裝置是絕佳的遊戲平台。請參閱這個主題，瞭解如何打造優質的電視遊戲體驗。
打造電視輸入服務：透過節目指南和上一個/下一個頻道按鈕，讓使用者能透過節目指南和上一個頻道或下一個頻道按鈕，以線性「廣播電視」方式呈現影片內容。

執行 TV 應用程式

執行應用程式是開發程序中相當重要的一環。您可以在設定為支援 USB 偵錯的電視裝置上執行應用程式，或使用虛擬電視裝置。

在實體裝置上執行

請按照下列步驟設定電視裝置：

請使用 USB 傳輸線將電視裝置連接到開發機器。如有需要，請參閱裝置製造商提供的說明文件。
在電視上前往「設定」。
在「裝置」列中選取「關於」。
向下捲動至「Build」，然後選取「Build」數次，直到收到「You 現在是開發人員！」訊息為止。
返回「設定」。在「Preferences」列中，選取「Developer options」。
依序選取「Debugging」>「USB debugging」，然後選取「On」。
返回電視主畫面。

如何在電視裝置上測試應用程式：

在 Android Studio 中選取您的專案，然後按一下工具列中的「Run」圖示。
在「Select Deployment Target」視窗中，選取您的電視裝置，然後按一下「OK」。

在虛擬裝置上執行

Android SDK 中的 AVD Manager 提供裝置定義，可讓您建立用於執行及測試應用程式的虛擬電視裝置。

建立虛擬電視裝置的步驟如下：

啟動 AVD Manager。詳情請參閱「建立及管理虛擬裝置」。
在 AVD Manager 對話方塊中，按一下「Device Definitions」分頁標籤。
選取任一 Android TV 裝置定義，然後按一下「Create AVD」。
選取模擬器選項，然後按一下「OK」建立 AVD。
注意：為獲得最佳電視模擬器裝置效能，請使用 x86 模擬器，並啟用「Use Host GPU」選項。如有需要，也可使用虛擬裝置加速功能。如要進一步瞭解模擬器的硬體加速功能，請參閱「設定 Android Emulator 的硬體加速功能」一文。

如何在虛擬電視裝置上測試應用程式：

在 Android Studio 中選取您的專案，然後按一下工具列中的「Run」圖示。
在「Select Deployment Target」視窗中，選取虛擬電視裝置，然後按一下「OK」。

如要進一步瞭解如何使用模擬器，請參閱「在 Android Emulator 上執行應用程式」。如要進一步瞭解如何將應用程式從 Android Studio 部署至虛擬裝置，請參閱「為應用程式偵錯」一文。

允許 TV 應用程式做為免安裝體驗執行

免安裝體驗可讓使用者輕鬆試用 TV 應用程式，進而提高採用率。

如要將 TV 應用程式設定為在 Android TV 裝置或模擬器上做為免安裝應用程式執行，請先按照操作說明建立免安裝即用的應用程式套件。

接著，在電視應用程式 MainActivity 的 intent-filter 中，確認 LAUNCHER 和 LEANBACK_LAUNCHER 都在 AndroidManifest.xml 中宣告：

<activity
    android:name="com.example.android.MainActivity"
    android:label="@string/app_name" >

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

您的 TV 應用程式現已設定為免安裝體驗。

準備要發布的 TV 應用程式

請參閱「TV 應用程式檢查清單」，瞭解要發布和發行的 TV 應用程式。

AndroidX TV 媒體庫