建構媒體應用程式範本

使用車輛專用應用程式程式庫範本的媒體應用程式，可以自訂媒體瀏覽和播放體驗，同時確保體驗已針對車輛螢幕最佳化，並盡量減少行車時的干擾。

本指南假設您已經有媒體應用程式，可以在手機上播放音訊，且符合 Android 媒體應用程式架構。車輛應用程式程式庫可讓您使用範本取代應用程式內體驗，而非使用「打造車用媒體應用程式」MediaBrowser資料結構建構的體驗。您仍須提供 MediaSession 做為播放控制項，以及 MediaBrowserService，用於推薦內容和其他智慧功能。

設定應用程式的資訊清單

除了「使用車輛專用 Android App Library」一文所述步驟外，範本式媒體應用程式還須符合下列規定：

在資訊清單中宣告類別支援

您的應用程式必須在 CarAppService 的意圖篩選器中宣告 androidx.car.app.category.MEDIA 車用應用程式類別：

<application>
    ...
   <service
       ...
        android:name=".MyCarAppService"
        android:exported="true">
      <intent-filter>
        <action android:name="androidx.car.app.CarAppService" />
        <category android:name="androidx.car.app.category.MEDIA"/>
      </intent-filter>
    </service>
    ...
<application>

如要存取 MediaPlaybackTemplate，應用程式也需要在資訊清單檔案中宣告 androidx.car.app.MEDIA_TEMPLATES 權限：

<manifest ...>
  ...
  <uses-permission android:name="androidx.car.app.MEDIA_TEMPLATES"/>
  ...
</manifest>

設定最低車輛應用程式 API 級別

使用 MediaPlaybackTemplate 的媒體應用程式僅支援 CAL API 8，請務必將最低 Car App API level 設為 8。

<application ...>
  ...
  <meta-data
    android:name="androidx.car.app.minCarApiLevel"
    android:value="8"/>
  ...
</application>

宣告 Android Auto 支援

請確認應用程式資訊清單中包含下列項目：

<application>
  ...
  <meta-data android:name="com.google.android.gms.car.application"
      android:resource="@xml/automotive_app_desc"/>
  ...
</application>

然後在 XML 資源的 automotive_app_desc.xml 中加入範本宣告。畫面應如下所示：

<automotiveApp xmlns:android="http://schemas.android.com/apk/res/android">
 <uses name="media"/>
 <uses name="template"/>
</automotiveApp>

提供出處圖示

使用車輛應用程式程式庫建構媒體應用程式時，請務必新增出處圖示。

支援語音指令

為應用程式啟用語音功能，讓使用者不需動手即可完成常見動作。如需更詳細的實作說明，請參閱「支援媒體的語音動作」。使用範本化媒體應用程式時，如果收到語音指令，則不需要使用搜尋結果更新 MediaBrowserService。建議改為在媒體播放範本中新增動作，讓使用者根據該播放內容或搜尋查詢尋找更多內容。支援語音指令是符合VC-1品質規範的必要條件。

建立播放範本

MediaPlaybackTemplate 會在車輛專用 Cars App Library 媒體應用程式中顯示媒體播放資訊。這個範本可讓您設定含有標題和可自訂動作的標題，而主機會根據應用程式 MediaSession 的狀態填入媒體資訊和播放控制項。

音樂播放器顯示 Summer Fielding 的「Sounds of Spring」，並以方格肖像呈現彈吉他的女子。

圖 1： MediaPlaybackTemplate 頂端有開啟佇列的標題動作。

這個程式碼範例說明如何建構範例播放範本，設定標題動作，讓使用者前往歌曲佇列畫面。

val playbackTemplate = MediaPlaybackTemplate.Builder()
      .setHeader(
        Header.Builder()
          .setStartHeaderAction(Action.BACK)
          .addEndHeaderAction(
                Action.Builder()
                  .setTitle(model.context.getString(R.string.queue_button_title))
                  .setIcon(
                    CarIcon.Builder(
                        IconCompat.createWithResource(
                          model.context,
                          R.drawable.gs_queue_music_vd_theme_24,
                        ))
                      .build())
                  .setOnClickListener(showQueueScreen())
                  .build())
          .setTitle(model.context.getString(R.string.media_playback_view_title))
          .build())
      .build()

使用 MediaPlaybackTemplate 時，請使用 CarAppService 中的 MediaPlaybackManager 註冊 MediaSession 權杖。否則，系統會在將 MediaPlaybackTemplate 傳送至主機時顯示錯誤。

import androidx.car.app.media.MediaPlaybackManager
…

override fun onCreateSession(sessionInfo: SessionInfo): Session {
    return object : Session() {
        …

        init {
          lifecycle.addObserver(
            LifecycleEventObserver { _, event ->
              if (event == ON_CREATE) {
                val token = ... // MediaSessionCompat.Token
                (carContext.getCarService(CarContext.MEDIA_PLAYBACK_SERVICE) as MediaPlaybackManager)
                  .registerMediaPlaybackToken(token)
              }
              ...
            }
          )
        }
    }
}

.registerMediaPlaybackToken 可讓 Android Auto 顯示媒體播放資訊和控制項。這對主辦人建立媒體專屬通知也很重要。

使用範本整理媒體

如要整理歌曲或專輯等媒體以供瀏覽，建議使用 SectionedItemTemplate，因為這個函式可讓您同時使用 GridSection 和 RowSection，建立混合圖片和文字項目清單的版面配置。

音樂應用程式介面顯示最近播放的歌曲和專輯，包括兩列直向和三列橫向的專輯封面直向圖片。

圖 2：包含 RowSection 的 SectionedItemTemplate，後面接著 GridSection

在 TabTemplate 內使用 SectionedItemTemplate

如要輕鬆分類應用程式中的媒體，可以使用 TabTemplate 內的 SectionedItemTemplate。

val template =
      SectionedItemTemplate.Builder()...build();
val tabTemplate = 
      TabTemplate.Builder(tabCallback)
          .setTabContents(TabContents.Builder(template).build)
          .setHeaderAction(Action.APP_ICON)
          …
          .build();

如要進一步瞭解如何運用這些範本設計媒體應用程式的使用者介面，請參閱「媒體應用程式」。

使用者瀏覽媒體時，必須能夠快速前往 MediaPlaybackTemplate，且盡量不受干擾。為符合MFT-1品質規定，應用程式必須提供從所有媒體瀏覽畫面存取 MediaPlaybackTemplate 的方式。

如果您使用 SectionedItemTemplate，可以新增懸浮動作按鈕，將您導覽至媒體播放畫面，即可達成這個目標。如果是其他範本，則可透過標題動作達成這個目標。