此页面由 Cloud Translation API 翻译。

向应用添加播放控件

播放媒体的应用需要使用用于显示媒体和控制播放。Media3 库包含一个界面模块，该模块包含多个界面组件如需依赖于界面模块，请添加以下内容依赖项：

Kotlin

implementation("androidx.media3:media3-ui:1.4.1")

Groovy

implementation "androidx.media3:media3-ui:1.4.1"

最重要的组件是 PlayerView，它是一个用于播放媒体的视图。 PlayerView 会在播放期间显示视频、图片、字幕和专辑封面。以及播放控件

PlayerView 具有用于附加和分离的 setPlayer 方法（通过传递 null) Player 实例。

PlayerView

PlayerView 可用于播放视频、图片和音频。它会渲染视频和字幕（如果是视频播放的话）、位图（如果是图片播放）并且可以在音频文件中显示作为元数据包含的海报图片。你可以添加它与任何其他界面组件一样。例如，PlayerView 可包含在以下 XML 中：

<androidx.media3.ui.PlayerView
    android:id="@+id/player_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:show_buffering="when_playing"
    app:show_shuffle_button="true"/>

上面的代码段说明 PlayerView 提供了属性。这些属性可用于自定义视图的行为，如以及它的外观其中大多数属性都有对应的 setter 方法，这些方法可用于在运行时自定义视图。通过 PlayerView Javadoc 列出了。

在布局文件中声明视图后，便可在 onCreate 方法：

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView = findViewById(R.id.player_view)
}

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  // ...
  playerView = findViewById(R.id.player_view);
}

播放器完成初始化后，即可通过调用 setPlayer:

Kotlin

// Instantiate the player.
val player = ExoPlayer.Builder(context).build()
// Attach player to the view.
playerView.player = player
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()

Java

// Instantiate the player.
player = new ExoPlayer.Builder(context).build();
// Attach player to the view.
playerView.setPlayer(player);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();

选择表面类型

通过 PlayerView 的 surface_type 属性，您可以设置 Surface 的类型用于视频播放。除了值spherical_gl_surface_view（是适用于球面视频播放的特殊值）和 video_decoder_gl_surface_view（用于使用扩展程序呈现视频）渲染程序），允许使用的值为 surface_view、texture_view 和 none。如果该视图仅用于音频播放，则应使用 none，以避免因为创建表面的成本可能很高

如果观看行为是常规视频播放，则 surface_view 或 texture_view 。与 TextureView相比，SurfaceView的视频播放：

功率明显下降许多设备上的消费量设备。
帧时间越准确，视频播放更顺畅。
在支持的设备上支持更高质量的 HDR 视频输出。
支持播放受 DRM 保护的内容时的安全输出。
能够以显示屏的完整分辨率呈现视频内容可提升界面层的 Android TV 设备。

因此，应尽可能优先使用 SurfaceView，而不是 TextureView。仅当 SurfaceView 无法满足您的需求时，才应使用 TextureView。一个例如，需要流畅的动画或视频滚动操作 Android 7.0（API 级别 24）之前的版本，如以下说明所述。对于在这种情况下，最好只使用 TextureView SDK_INT 高于 24 (Android 7.0)，否则为 SurfaceView。

Android TV 上的方向键导航

Android TV 的遥控器有一个方向键控制器，可发送在Activity的dispatchKeyEvent(KeyEvent)以关键事件的形式到达。这些需要委托给播放器视图：

Kotlin

override fun dispatchKeyEvent(event: KeyEvent?): Boolean{
  return playerView.dispatchKeyEvent(event!!) || super.dispatchKeyEvent(event)
}

Java

@Override
public boolean dispatchKeyEvent(KeyEvent event) {
  return playerView.dispatchKeyEvent(event) || super.dispatchKeyEvent(event);
}

为播放器视图请求焦点对于导航播放非常重要控制和跳过广告建议在以下时间的 onCreate 中请求焦点： Activity：

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView.requestFocus()
  // ...
}

Java

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...
    playerView.requestFocus();
    // ...
}

如果您在 Android TV 上使用 Compose，则需要将 AndroidView 设为可聚焦，并通过将修饰符参数传递到 AndroidView：

AndroidView(
  modifier = modifier
    .focusable()
    .onKeyEvent { playerView.dispatchKeyEvent(it.nativeKeyEvent) },
  factory = { playerView }
)

替换可绘制对象

PlayerView 使用 PlayerControlView 显示播放内容控件和进度条。PlayerControlView 使用的可绘制对象可以会被替换为应用中定义的相同名称的可绘制对象。请参阅 PlayerControlView Javadoc，获取其他属性

进一步自定义

如果还需要进行上述自定义之外的其他自定义，我们期望应用开发者会实现自己的界面组件，而不是使用提供的组件由 Media3 的界面模块生成。