開始使用 TV 應用程式

TV 應用程式使用的結構與手機和平板電腦應用程式相同。這種相似性意味著您可以修改現有應用程式，使其也在 TV 裝置上執行，或是根據已掌握為 Android 建構應用程式的既有知識來建立新的應用程式。

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

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

如要進一步瞭解如何設計 TV 應用程式，請參閱專為 TV 設計。另請參閱 Android TV GitHub 存放區中的範例應用程式。

判斷媒體格式支援情形

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

設定 TV 專案

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

如要建立在電視裝置上執行的應用程式，您必須使用兩個主要元件：

  • 電視活動：在應用程式資訊清單中，宣告要在 TV 裝置上執行的活動。
  • 電視程式庫：您可以視需要加入一或多個適用於電視裝置的 Androidx 程式庫，詳情請參閱本指南的其他章節。這些程式庫提供小工具，可用於建構使用者介面。

必要條件

開始建構電視專用應用程式之前，您必須完成下列步驟：

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

宣告 TV 活動

要在電視裝置上執行的應用程式，必須在資訊清單中宣告電視的啟動器活動。方法是使用 CATEGORY_LEANBACK_LAUNCHER 意圖篩選器。這個篩選器會將應用程式識別為已啟用 TV，並且讓 Google Play 將其視為 TV 應用程式。當使用者在電視主畫面上選取您的應用程式時，這項意圖即可識別要啟動哪個活動。

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

<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 英呎的遙控的情況下輕鬆瀏覽應用程式。如要修改現有的應用程式以便在電視上使用，請勿針對手機和平板電腦的電視使用相同的活動版面配置。如需為電視設計應用程式的相關指南，請參閱專為 TV 設計。如要進一步瞭解電視介面版面配置的最低實作要求，請參閱「建構電視版面配置」一文。

宣告 TV 裝置支援

宣告 android.software.leanback 功能，宣告您的應用程式是專為 Android TV 建構。

如果應用程式同時在行動裝置和電視上執行，請將 required 屬性值設為 false。如果將 required 屬性值設為 true，Google Play 就只會在 Android TV OS 上提供您的應用程式。

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

無須宣告觸控螢幕

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

<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 以上版本中，Android TV 應用程式不支援使用 SplashScreen 平台 API 建構的自訂啟動畫面動畫。

當電視應用程式啟動時，系統會顯示動畫，類似展開的填滿圓圈。如要自訂這個動畫的顏色，請將電視應用程式或活動的 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>

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

建構適用於 Android TV OS 的應用程式

Jetpack 包含 androidx 套件程式庫，可與 TV 應用程式搭配使用。

Compose for TV

建議您使用 Compose 建構適用於 Android TV OS 的應用程式。除了核心 Compose 程式庫之外，Compose for TV 程式庫也提供專為大螢幕設計的專屬元件：

如要瞭解如何使用 Compose for TV 建構 TV 應用程式，請參閱「在 Android TV 上使用 Jetpack Compose」。

Leanback UI 工具包

Leanback UI 工具包提供電視裝置的 API 和使用者介面小工具：

瞭解如何使用 建構電視播放應用程式中的 Leanback UI 工具包建構 TV 應用程式。

執行 TV 應用程式

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

在實體裝置上執行

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

  1. 使用 USB 傳輸線將電視裝置連接至開發機器。如有需要，請參閱裝置製造商提供的說明文件。
  2. 在電視裝置上前往「設定」。
  3. 在「裝置」列中選取「關於」。
  4. 捲動至「Build」並選取「Build」數次，直到系統顯示「開發人員設定已啟用！」的訊息為止。
  5. 返回「設定」。在「Preferences」列中，選取「Developer options」。
  6. 依序選取「Debugging」>「USB debugging」，然後選取「On」。
  7. 返回電視主畫面。

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

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

在虛擬裝置上執行

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

如要建立虛擬電視裝置，請按照下列步驟操作：

  1. 啟動 AVD Manager。詳情請參閱「建立及管理虛擬裝置」。
  2. 在 AVD Manager 對話方塊中，按一下「Device Definitions」分頁標籤。
  3. 選取其中一項 Android TV 裝置定義，然後按一下「Create AVD」。
  4. 選取模擬器選項，然後按一下「OK」建立 AVD。

    注意：為獲得最佳電視模擬器裝置效能，請使用 x86 模擬器並啟用「Use Host GPU」選項。如果可用，也能使用虛擬裝置加速功能。如要進一步瞭解模擬器硬體加速功能，請參閱「設定 Android Emulator 的硬體加速功能」一文。

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

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

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

讓電視應用程式以免安裝體驗形式執行

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

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

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

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