首页上的频道

Android TV 主屏幕，或简称为主屏幕，提供了一个 UI，该 UI 将推荐内容显示为频道和节目的表格。每一行都是一个频道。一个频道包含该频道上每个节目的卡片

TV home screen

本文档演示了如何向主屏幕添加频道和节目、更新内容、处理用户操作以及为您的用户提供最佳体验。（如果您想深入了解 API，请尝试主屏幕代码实验室并观看I/O 2017 Android TV 会议。）

注意：推荐频道仅在 Android 8.0（API 级别 26）及更高版本中可用。您必须使用它们来提供在 Android 8.0（API 级别 26）及更高版本中运行的应用的推荐。要为在早期版本的 Android 上运行的应用提供推荐，您的应用必须改为使用推荐行。

主屏幕 UI

应用可以创建新频道，添加、删除和更新频道中的节目，以及控制频道中节目的顺序。例如，应用可以创建一个名为“最新内容”的频道，并显示新可用节目的卡片。

应用无法控制频道在主屏幕中显示的顺序。当您的应用创建新频道时，主屏幕会将其添加到频道列表的底部。用户可以重新排序、隐藏和显示频道。

“接下来观看”频道

“接下来观看”频道是主屏幕中显示的第二行，位于应用行之后。系统创建并维护此频道。您的应用可以向“接下来观看”频道添加节目。有关更多信息，请参阅向“接下来观看”频道添加节目。

应用频道

您的应用创建的所有频道都遵循此生命周期

用户在您的应用中发现一个频道并请求将其添加到主屏幕。
应用创建频道并将其添加到TvProvider（此时频道不可见）。
应用请求系统显示频道。
系统要求用户批准新频道。
新频道出现在主屏幕的最后一行。

默认频道

您的应用可以为用户提供任意数量的频道以添加到主屏幕。用户通常必须先选择并批准每个频道，然后才能在主屏幕中显示。每个应用都有选择创建一个默认频道的选项。默认频道很特殊，因为它会自动出现在主屏幕中；用户无需显式请求它。

先决条件

Android TV 主屏幕使用 Android 的TvProvider API 来管理您的应用创建的频道和节目。要访问提供程序的数据，请将以下权限添加到应用清单中

<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />

TvProvider支持库使使用提供程序变得更加容易。将其添加到build.gradle文件中的依赖项中

Groovy

implementation 'androidx.tvprovider:tvprovider:1.0.0'

Kotlin

implementation("androidx.tvprovider:tvprovider:1.0.0")

要使用频道和节目，请确保在程序中包含这些支持库导入

Kotlin

import android.support.media.tv.Channel
import android.support.media.tv.TvContractCompat
import android.support.media.tv.ChannelLogoUtils
import android.support.media.tv.PreviewProgram
import android.support.media.tv.WatchNextProgram

Java

import android.support.media.tv.Channel;
import android.support.media.tv.TvContractCompat;
import android.support.media.tv.ChannelLogoUtils;
import android.support.media.tv.PreviewProgram;
import android.support.media.tv.WatchNextProgram;

频道

您的应用创建的第一个频道将成为其默认频道。默认频道会自动出现在主屏幕中。您创建的所有其他频道都必须由用户选择并接受，然后才能出现在主屏幕中。

创建频道

您的应用应仅在运行在前台时才请求系统显示新添加的频道。这可以防止您的应用在用户运行其他应用时显示一个对话框，请求批准添加您的频道。如果您尝试在后台运行时添加频道，则活动的onActivityResult()方法将返回状态代码RESULT_CANCELED。

要创建频道，请执行以下步骤

创建一个频道构建器并设置其属性。请注意，频道类型必须为TYPE_PREVIEW。根据需要添加更多属性。

Kotlin

val builder = Channel.Builder()
// Every channel you create must have the type TYPE_PREVIEW
builder.setType(TvContractCompat.Channels.TYPE_PREVIEW)
        .setDisplayName("Channel Name")
        .setAppLinkIntentUri(uri)

Java

Channel.Builder builder = new Channel.Builder();
// Every channel you create must have the type TYPE_PREVIEW
builder.setType(TvContractCompat.Channels.TYPE_PREVIEW)
        .setDisplayName("Channel Name")
        .setAppLinkIntentUri(uri);

将频道插入提供程序

Kotlin

var channelUri = context.contentResolver.insert(
        TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues())

Java

Uri channelUri = context.getContentResolver().insert(
        TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues());

您需要保存频道 ID 以便稍后向频道添加节目。从返回的 URI 中提取频道 ID
Kotlin
var channelId = ContentUris.parseId(channelUri)
Java
long channelId = ContentUris.parseId(channelUri);

您必须为您的频道添加徽标。使用Uri或Bitmap。徽标图标应为 80dp x 80dp，并且必须是不透明的。它在圆形蒙版下显示

Kotlin

// Choose one or the other
storeChannelLogo(context: Context, channelId: Long, logoUri: Uri) // also works if logoUri is a URL
storeChannelLogo(context: Context, channelId: Long, logo: Bitmap)

Java

// Choose one or the other
storeChannelLogo(Context context, long channelId, Uri logoUri); // also works if logoUri is a URL
storeChannelLogo(Context context, long channelId, Bitmap logo);

创建默认频道（可选）：当您的应用创建其第一个频道时，您可以将其设为默认频道，以便它立即出现在主屏幕中，无需任何用户操作。您创建的任何其他频道在用户显式选择它们之前都不可见。
Kotlin
TvContractCompat.requestChannelBrowsable(context, channelId)
Java
TvContractCompat.requestChannelBrowsable(context, channelId);
在打开您的应用之前显示您的默认频道。您可以通过添加一个BroadcastReceiver来实现此行为，该BroadcastReceiver侦听android.media.tv.action.INITIALIZE_PROGRAMS操作，该操作是在安装应用后由主屏幕发送的
```
<receiver
  android:name=".RunOnInstallReceiver"
  android:exported="true">
    <intent-filter>
      <action android:name="android.media.tv.action.INITIALIZE_PROGRAMS" />
      <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</receiver>
```
在开发期间通过 sideload 应用时，您可以通过 adb 触发意图来测试此步骤，其中your.package.name/.YourReceiverName是您的应用的BroadcastReceiver
```
adb shell am broadcast -a android.media.tv.action.INITIALIZE_PROGRAMS -n \
    your.package.name/.YourReceiverName
```
在极少数情况下，您的应用可能会在用户启动您的应用的同时收到广播。确保您的代码不会尝试多次添加默认频道。

更新频道

更新频道与创建频道非常相似。

使用另一个Channel.Builder设置需要更改的属性。

使用ContentResolver更新频道。使用您在最初添加频道时保存的频道 ID

Kotlin

context.contentResolver.update(
        TvContractCompat.buildChannelUri(channelId),
        builder.build().toContentValues(),
        null,
        null
)

Java

context.getContentResolver().update(TvContractCompat.buildChannelUri(channelId),
    builder.build().toContentValues(), null, null);

要更新频道的徽标，请使用storeChannelLogo()。

删除频道

Kotlin

context.contentResolver.delete(TvContractCompat.buildChannelUri(channelId), null, null)

Java

context.getContentResolver().delete(TvContractCompat.buildChannelUri(channelId), null, null);

节目

向应用频道添加节目

创建一个PreviewProgram.Builder并设置其属性

Kotlin

val builder = PreviewProgram.Builder()
builder.setChannelId(channelId)
        .setType(TvContractCompat.PreviewPrograms.TYPE_CLIP)
        .setTitle("Title")
        .setDescription("Program description")
        .setPosterArtUri(uri)
        .setIntentUri(uri)
        .setInternalProviderId(appProgramId)

Java

PreviewProgram.Builder builder = new PreviewProgram.Builder();
builder.setChannelId(channelId)
        .setType(TvContractCompat.PreviewPrograms.TYPE_CLIP)
        .setTitle("Title")
        .setDescription("Program description")
        .setPosterArtUri(uri)
        .setIntentUri(uri)
        .setInternalProviderId(appProgramId);

根据节目的类型添加更多属性。（要查看每种类型的节目可用的属性，请参阅下面的表格。）

将节目插入提供程序

Kotlin

var programUri = context.contentResolver.insert(TvContractCompat.PreviewPrograms.CONTENT_URI,
        builder.build().toContentValues())

Java

Uri programUri = context.getContentResolver().insert(TvContractCompat.PreviewPrograms.CONTENT_URI,
      builder.build().toContentValues());

检索节目 ID 以供日后参考

Kotlin

val programId = ContentUris.parseId(programUri)

Java

long programId = ContentUris.parseId(programUri);

向“接下来观看”频道添加节目

要将节目插入“接下来观看”频道，请参阅向“接下来观看”频道添加节目。

更新节目

您可以更改节目的信息。例如，您可能希望更新电影的租赁价格，或更新一个进度条，显示用户已观看的节目有多少。

使用 PreviewProgram.Builder 设置需要更改的属性，然后调用 getContentResolver().update 更新程序。指定程序最初添加时保存的程序 ID。

Kotlin

context.contentResolver.update(
        TvContractCompat.buildPreviewProgramUri(programId),
                builder.build().toContentValues(), null, null
)

Java

context.getContentResolver().update(TvContractCompat.buildPreviewProgramUri(programId),
    builder.build().toContentValues(), null, null);

删除程序

Kotlin

context.contentResolver
        .delete(TvContractCompat.buildPreviewProgramUri(programId), null, null)

Java

context.getContentResolver().delete(TvContractCompat.buildPreviewProgramUri(programId), null, null);

处理用户操作

您的应用可以通过提供 UI 来显示和添加频道来帮助用户发现内容。您的应用还应在频道出现在主屏幕后处理与频道的交互。

发现和添加频道

您的应用可以提供一个 UI 元素，允许用户选择并添加其频道（例如，一个请求添加频道的按钮）。

在用户请求特定频道后，执行此代码以获取用户将其添加到主屏幕 UI 的权限

Kotlin

val intent = Intent(TvContractCompat.ACTION_REQUEST_CHANNEL_BROWSABLE)
intent.putExtra(TvContractCompat.EXTRA_CHANNEL_ID, channelId)
try {
  activity.startActivityForResult(intent, 0)
} catch (e: ActivityNotFoundException) {
  // handle error
}

Java

Intent intent = new Intent(TvContractCompat.ACTION_REQUEST_CHANNEL_BROWSABLE);
intent.putExtra(TvContractCompat.EXTRA_CHANNEL_ID, channelId);
try {
   activity.startActivityForResult(intent, 0);
} catch (ActivityNotFoundException e) {
  // handle error
}

系统会显示一个对话框，要求用户批准该频道。在活动的 onActivityResult 方法中处理请求的结果（Activity.RESULT_CANCELED 或 Activity.RESULT_OK）。

Android TV 主屏幕事件

当用户与应用发布的程序/频道交互时，主屏幕会向应用发送意图。

当用户选择频道的徽标时，主屏幕会将存储在频道 APP_LINK_INTENT_URI 属性中的 Uri 发送到应用。应用应启动其主 UI 或与所选频道相关的视图。
当用户选择程序时，主屏幕会将存储在程序 INTENT_URI 属性中的 Uri 发送到应用。应用应播放所选内容。
用户可以表明他们不再对某个程序感兴趣，并希望将其从主屏幕的 UI 中移除。系统会将程序从 UI 中移除，并向拥有该程序的应用发送一个意图（android.media.tv.ACTION_PREVIEW_PROGRAM_BROWSABLE_DISABLED 或 android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED），其中包含程序的 ID。应用应从提供程序中移除该程序，并且不应重新插入它。

确保为主屏幕发送的所有用户交互 Uris 创建意图过滤器；例如

<receiver
   android:name=".WatchNextProgramRemoved"
   android:enabled="true"
   android:exported="true">
   <intent-filter>
       <action android:name="android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED" />
   </intent-filter>
</receiver>

最佳实践

许多电视应用要求用户登录。在这种情况下，侦听 android.media.tv.action.INITIALIZE_PROGRAMS 的 BroadcastReceiver 应为未经身份验证的用户建议频道内容。例如，您的应用可以最初显示最佳内容或当前热门内容。用户登录后，它可以显示个性化内容。这是应用在用户登录前进行加价销售的绝佳机会。
当您的应用不在前台并且您需要更新频道或程序时，请使用 JobScheduler 安排工作（请参阅：JobScheduler 和 JobService）。
如果您的应用行为不当（例如：持续向提供程序发送大量数据），系统可能会撤销您的应用的提供程序权限。确保将访问提供程序的代码包装在 try-catch 子句中以处理安全异常。

在更新程序和频道之前，查询提供程序以获取需要更新的数据并协调数据。例如，无需更新用户希望从 UI 中移除的程序。使用后台作业，在查询现有数据并请求批准频道后，将您的数据插入/更新到提供程序。您可以在应用启动时以及应用需要更新其数据时运行此作业。

Kotlin

context.contentResolver
  .query(
      TvContractCompat.buildChannelUri(channelId),
          null, null, null, null).use({
              cursor-> if (cursor != null and cursor.moveToNext()) {
                           val channel = Channel.fromCursor(cursor)
                           if (channel.isBrowsable()) {
                               //update channel's programs
                           }
                       }
          })

Java

try (Cursor cursor = context.getContentResolver()
      .query(
          TvContractCompat.buildChannelUri(channelId),
          null,
          null,
          null,
          null)) {
              if (cursor != null && cursor.moveToNext()) {
                  Channel channel = Channel.fromCursor(cursor);
                  if (channel.isBrowsable()) {
                      //update channel's programs
                  }
              }
          }

对所有图像（徽标、图标、内容图像）使用唯一的 Uris。更改图像时，请确保使用不同的 Uri。所有图像都已缓存。如果在更改图像时未更改 Uri，则旧图像将继续显示。
请记住，不允许使用 WHERE 子句，并且对使用 WHERE 子句的提供程序的调用将引发安全异常。

属性

本节分别描述了频道和程序属性。

频道属性

您必须为每个频道指定这些属性

属性	说明
TYPE	设置为 `TYPE_PREVIEW`。
DISPLAY_NAME	设置为频道的名称。
APP_LINK_INTENT_URI	当用户选择频道的徽标时，系统会发送一个意图以启动一个活动，该活动显示与该频道相关的内容。将此属性设置为该活动意图过滤器中使用的 Uri。

此外，频道还有六个保留用于内部应用使用的字段。这些字段可用于存储密钥或其他值，这些值可以帮助应用将频道映射到其内部数据结构

INTERNAL_PROVIDER_ID
INTERNAL_PROVIDER_DATA
INTERNAL_PROVIDER_FLAG1
INTERNAL_PROVIDER_FLAG2
INTERNAL_PROVIDER_FLAG3
INTERNAL_PROVIDER_FLAG4

程序属性

请参阅各个页面以了解每种类型的程序的属性

示例代码

要了解有关构建与主屏幕交互以及将频道和程序添加到 Android TV 主屏幕的应用的更多信息，请参阅我们的主屏幕 codelab。

关于推荐电视内容

视频程序属性