使用傳輸控制項

使用 Compose 打造更優質的應用程式
使用 Android TV OS 適用的 Jetpack Compose，以最少的程式碼建立美觀的 UI。
為電視撰寫內容 →

Leanback UI 工具包提供播放控制項，可提升使用者體驗。如果是影片應用程式，傳輸控制項支援使用向前和向後控制項進行影片快轉。在螢幕上拖曳時，系統會顯示縮圖，方便你瀏覽影片。

這個程式庫包含抽象類別，以及預先建構的現成實作項目，可讓開發人員進行更精細的控制。使用預先建構的實作項目，您就能快速建構功能豐富的應用程式，不必編寫大量程式碼。如需更多自訂項目，您可以擴充程式庫的任何預先建構元件。

控制項和播放器

「輕鬆看」UI 工具包會將傳輸控制項 UI 與播放影片的播放器分開。這項功能由兩個元件達成：用於顯示傳輸控制項 (和影片，視需要) 的播放支援片段，以及用於封裝媒體播放器的播放器轉接程式。

播放片段

應用程式的 UI 活動應使用 PlaybackSupportFragment 或 VideoSupportFragment。兩者都包含「輕鬆看」傳輸控制項：

您可以自訂片段的 ObjectAdapter，提升使用者介面。舉例來說，使用 setAdapter() 可新增「相關影片」列。

PlayerAdapter

PlayerAdapter 是控制基礎媒體播放器的抽象類別。開發人員可以選擇預先建構的 MediaPlayerAdapter 實作項目，也可以自行編寫這個類別的實作項目。

將各個部分黏合在一起

您必須使用一些「控制膠水」，將播放片段連結至播放器。Leanback 程式庫提供兩種黏著劑：

leanback 傳輸控制項膠水

如要讓應用程式支援影片快轉功能，請務必使用 PlaybackTransportControlGlue。

您也需要指定「黏著主機」，將黏著劑繫結至播放片段、在 UI 中繪製傳輸控制項並維護其狀態，以及將傳輸控制項事件傳回黏著劑。主機必須與播放片段類型相符。使用 PlaybackSupportFragmentGlueHost 搭配 PlaybackFragment，以及 VideoSupportFragmentGlueHost 搭配 VideoFragment。

下圖說明 Leanback 遙控器控制項的各個部分如何整合運作：

leanback 傳輸控制項膠水

將應用程式黏合在一起的程式碼應位於定義 UI 的 PlaybackSupportFragment 或 VideoSupportFragment 內。

在下列範例中，應用程式會建構 PlaybackTransportControlGlue 的執行個體，並將其命名為 playerGlue，然後將其 VideoSupportFragment 連線至新建立的 MediaPlayerAdapter。由於這是 VideoSupportFragment，設定程式碼會呼叫 setHost()，將 VideoSupportFragmentGlueHost 附加至 playerGlue。程式碼包含在擴充 VideoSupportFragment 的類別中。

Kotlin

class MyVideoFragment : VideoSupportFragment() {

  fun onCreate(savedInstanceState: Bundle) {
      super.onCreate(savedInstanceState)
      val playerGlue = PlaybackTransportControlGlue(getActivity(),
          MediaPlayerAdapter(getActivity()))
      playerGlue.setHost(VideoSupportFragmentGlueHost(this))
      playerGlue.addPlayerCallback(object : PlaybackGlue.PlayerCallback() {
          override fun onPreparedStateChanged(glue: PlaybackGlue) {
              if (glue.isPrepared()) {
                  playerGlue.seekProvider = MySeekProvider()
                  playerGlue.play()
              }
          }
      })
      playerGlue.setSubtitle("Leanback artist")
      playerGlue.setTitle("Leanback team at work")
      val uriPath = "android.resource://com.example.android.leanback/raw/video"
      playerGlue.getPlayerAdapter().setDataSource(Uri.parse(uriPath))
  }
}

Java

public class MyVideoFragment extends VideoSupportFragment {

  @Override
  public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      final PlaybackTransportControlGlue<MediaPlayerAdapter> playerGlue =
              new PlaybackTransportControlGlue(getActivity(),
                      new MediaPlayerAdapter(getActivity()));
      playerGlue.setHost(new VideoSupportFragmentGlueHost(this));
      playerGlue.addPlayerCallback(new PlaybackGlue.PlayerCallback() {
          @Override
          public void onPreparedStateChanged(PlaybackGlue glue) {
              if (glue.isPrepared()) {
                  playerGlue.setSeekProvider(new MySeekProvider());
                  playerGlue.play();
              }
          }
      });
      playerGlue.setSubtitle("Leanback artist");
      playerGlue.setTitle("Leanback team at work");
      String uriPath = "android.resource://com.example.android.leanback/raw/video";
      playerGlue.getPlayerAdapter().setDataSource(Uri.parse(uriPath));
  }
}

請注意，設定程式碼也會定義 PlayerAdapter.Callback，用來處理媒體播放器的事件。

自訂 UI 膠合

您可以自訂 PlaybackBannerControlGlue 和 PlaybackTransportControlGlue，藉此變更 PlaybackControlsRow。

自訂標題和說明

如要自訂播放控制項頂端的標題和說明，請覆寫 onCreateRowPresenter()：

Kotlin

override fun onCreateRowPresenter(): PlaybackRowPresenter {
    return super.onCreateRowPresenter().apply {
        (this as? PlaybackTransportRowPresenter)
                ?.setDescriptionPresenter(MyCustomDescriptionPresenter())
    }
}

Java

@Override
protected PlaybackRowPresenter onCreateRowPresenter() {
  PlaybackTransportRowPresenter presenter = (PlaybackTransportRowPresenter) super.onCreateRowPresenter();
  presenter.setDescriptionPresenter(new MyCustomDescriptionPresenter());
  return presenter;
}

新增控制項

控制項膠合會顯示 PlaybackControlsRow 中動作的控制項。

PlaybackControlsRow 中的動作會指派給兩組：主要動作和次要動作。主要群組的控制項會顯示在搜尋列上方，次要群組的控制項則會顯示在搜尋列下方。一開始，播放/暫停按鈕只有一個主要動作，沒有次要動作。

您可以覆寫 onCreatePrimaryActions() 和 onCreateSecondaryActions()，將動作新增至主要和次要群組。

Kotlin

private lateinit var repeatAction: PlaybackControlsRow.RepeatAction
private lateinit var pipAction: PlaybackControlsRow.PictureInPictureAction
private lateinit var thumbsUpAction: PlaybackControlsRow.ThumbsUpAction
private lateinit var thumbsDownAction: PlaybackControlsRow.ThumbsDownAction
private lateinit var skipPreviousAction: PlaybackControlsRow.SkipPreviousAction
private lateinit var skipNextAction: PlaybackControlsRow.SkipNextAction
private lateinit var fastForwardAction: PlaybackControlsRow.FastForwardAction
private lateinit var rewindAction: PlaybackControlsRow.RewindAction

override fun onCreatePrimaryActions(primaryActionsAdapter: ArrayObjectAdapter) {
    // Order matters, super.onCreatePrimaryActions() will create the play / pause action.
    // Will display as follows:
    // play/pause, previous, rewind, fast forward, next
    //   > /||      |<        <<        >>         >|
    super.onCreatePrimaryActions(primaryActionsAdapter)
    primaryActionsAdapter.apply {
        add(skipPreviousAction)
        add(rewindAction)
        add(fastForwardAction)
        add(skipNextAction)
    }
}

override fun onCreateSecondaryActions(adapter: ArrayObjectAdapter?) {
    super.onCreateSecondaryActions(adapter)
    adapter?.apply {
        add(thumbsDownAction)
        add(thumbsUpAction)
    }
}

Java

private PlaybackControlsRow.RepeatAction repeatAction;
private PlaybackControlsRow.PictureInPictureAction pipAction;
private PlaybackControlsRow.ThumbsUpAction thumbsUpAction;
private PlaybackControlsRow.ThumbsDownAction thumbsDownAction;
private PlaybackControlsRow.SkipPreviousAction skipPreviousAction;
private PlaybackControlsRow.SkipNextAction skipNextAction;
private PlaybackControlsRow.FastForwardAction fastForwardAction;
private PlaybackControlsRow.RewindAction rewindAction;

@Override
protected void onCreatePrimaryActions(ArrayObjectAdapter primaryActionsAdapter) {
    // Order matters, super.onCreatePrimaryActions() will create the play / pause action.
    // Will display as follows:
    // play/pause, previous, rewind, fast forward, next
    //   > /||      |<        <<        >>         >|
    super.onCreatePrimaryActions(primaryActionsAdapter);
    primaryActionsAdapter.add(skipPreviousAction);
    primaryActionsAdapter.add(rewindAction);
    primaryActionsAdapter.add(fastForwardAction);
    primaryActionsAdapter.add(skipNextAction);
}

@Override
protected void onCreateSecondaryActions(ArrayObjectAdapter adapter) {
    super.onCreateSecondaryActions(adapter);
    adapter.add(thumbsDownAction);
    adapter.add(thumbsUpAction);
}

您必須覆寫 onActionClicked() 才能處理新動作。

Kotlin

override fun onActionClicked(action: Action) {
    when(action) {
        rewindAction -> {
            // Handle Rewind
        }
        fastForwardAction -> {
            // Handle FastForward
        }
        thumbsDownAction -> {
            // Handle ThumbsDown
        }
        thumbsUpAction -> {
            // Handle ThumbsUp
        }
        else ->
            // The superclass handles play/pause and delegates next/previous actions to abstract methods,
            // so those two methods should be overridden rather than handling the actions here.
            super.onActionClicked(action)
    }
}

override fun next() {
    // Skip to next item in playlist.
}

override fun previous() {
    // Skip to previous item in playlist.
}

Java

@Override
public void onActionClicked(Action action) {
    if (action == rewindAction) {
        // Handle Rewind
    } else if (action == fastForwardAction ) {
        // Handle FastForward
    } else if (action == thumbsDownAction) {
        // Handle ThumbsDown
    } else if (action == thumbsUpAction) {
        // Handle ThumbsUp
    } else {
        // The superclass handles play/pause and delegates next/previous actions to abstract methods,
        // so those two methods should be overridden rather than handling the actions here.
        super.onActionClicked(action);
    }
}

@Override
public void next() {
    // Skip to next item in playlist.
}

@Override
public void previous() {
    // Skip to previous item in playlist.
}

在特殊情況下，您可能想實作自己的 PlaybackTransportRowPresenter，使用 PlaybackSeekUi 算繪自訂控制項並回應搜尋動作。

影片時間拖曳

如果您的應用程式使用 VideoSupportFragment，且您想支援影片快轉/倒轉功能。

刷洗

您需要提供 PlaybackSeekDataProvider 的實作項目。這個元件提供捲動時使用的影片縮圖。您必須擴充 PlaybackSeekDataProvider，自行實作供應商。請參閱 Leanback Showcase 應用程式中的範例。 。

上一頁
打造詳細資料檢視畫面
下一頁
為初次接觸的使用者介紹您的應用程式