Menerapkan gaya konten

Setelah menggunakan item yang dapat dijelajahi atau diputar untuk membuat hierarki konten, terapkan gaya konten untuk menentukan cara item tersebut ditampilkan di mobil. Gunakan gaya konten berikut:

Item daftar

Gambar 1. Item daftar memprioritaskan judul dan metadata daripada gambar.

Item petak

Gambar 2. Item petak lebih memprioritaskan gambar daripada judul dan metadata.

Menetapkan gaya konten default

Anda dapat menetapkan gaya default global untuk mengatur cara menampilkan item media. Untuk melakukannya, sertakan konstanta tertentu dalam paket tambahan BrowserRoot yang ditampilkan oleh implementasi onGetRoot layanan Anda dan cari konstanta ini untuk menentukan gaya yang sesuai.

Tambahan ini dapat digunakan sebagai kunci dalam paket:

Kunci ini dapat memetakan ke nilai konstanta integer berikut untuk memengaruhi presentasi item tersebut:

Cuplikan kode ini menunjukkan cara menetapkan gaya konten default untuk item yang dapat dijelajahi ke petak, dan item yang dapat diputar ke daftar:

Kotlin

import androidx.media.utils.MediaConstants

@Nullable
override fun onGetRoot(
    @NonNull clientPackageName: String,
    clientUid: Int,
    @Nullable rootHints: Bundle
): BrowserRoot {
    val extras = Bundle()
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM)
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM)
    return BrowserRoot(ROOT_ID, extras)
}

Java

import androidx.media.utils.MediaConstants;

@Nullable
@Override
public BrowserRoot onGetRoot(
    @NonNull String clientPackageName,
    int clientUid,
    @Nullable Bundle rootHints) {
    Bundle extras = new Bundle();
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM);
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM);
    return new BrowserRoot(ROOT_ID, extras);
}

Menetapkan gaya konten per item

Anda dapat mengganti gaya konten default untuk turunan item media yang dapat dijelajahi, serta untuk item media itu sendiri. Untuk mengganti default keturunan item media yang dapat dijelajahi, buat paket tambahan di MediaDescription item media dan tambahkan petunjuk yang sama seperti yang disebutkan sebelumnya:

  • DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE berlaku untuk turunan item yang dapat diputar.

  • DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE berlaku untuk turunan item yang dapat dijelajahi.

Untuk mengganti gaya default item media tertentu (bukan turunannya), buat paket tambahan di MediaDescription item media. Kemudian, tambahkan petunjuk dengan kunci DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM. Gunakan nilai yang sama seperti yang dijelaskan di atas untuk menentukan presentasi item tersebut.

Cuplikan kode ini menunjukkan cara membuat MediaItem yang dapat dijelajahi dan akan mengganti gaya konten default untuk dirinya sendiri dan turunannya. Item media ini menata gayanya sendiri sebagai item daftar kategori, turunannya yang dapat dijelajahi sebagai item daftar, dan turunannya yang dapat diputar sebagai item petak.

Kotlin

import androidx.media.utils.MediaConstants

private fun createBrowsableMediaItem(
    mediaId: String,
    folderName: String,
    iconUri: Uri
): MediaBrowser.MediaItem {
    val mediaDescriptionBuilder = MediaDescription.Builder()
    mediaDescriptionBuilder.setMediaId(mediaId)
    mediaDescriptionBuilder.setTitle(folderName)
    mediaDescriptionBuilder.setIconUri(iconUri)
    val extras = Bundle()
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_LIST_ITEM)
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM)
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM)
    mediaDescriptionBuilder.setExtras(extras)
    return MediaBrowser.MediaItem(
        mediaDescriptionBuilder.build(), MediaBrowser.MediaItem.FLAG_BROWSABLE)
}

Java

import androidx.media.utils.MediaConstants;

private MediaBrowser.MediaItem createBrowsableMediaItem(
    String mediaId,
    String folderName,
    Uri iconUri) {
    MediaDescription.Builder mediaDescriptionBuilder = new MediaDescription.Builder();
    mediaDescriptionBuilder.setMediaId(mediaId);
    mediaDescriptionBuilder.setTitle(folderName);
    mediaDescriptionBuilder.setIconUri(iconUri);
    Bundle extras = new Bundle();
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_LIST_ITEM);
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM);
    extras.putInt(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE,
        MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM);
    mediaDescriptionBuilder.setExtras(extras);
    return new MediaBrowser.MediaItem(
        mediaDescriptionBuilder.build(), MediaBrowser.MediaItem.FLAG_BROWSABLE);
}

Mengelompokkan item menggunakan petunjuk judul

Untuk mengelompokkan item media terkait, gunakan petunjuk per item. Setiap item media dalam grup harus mendeklarasikan paket tambahan dalam MediaDescription-nya. Paket ini harus menyertakan pemetaan dengan kunci DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE dan nilai string yang identik. Lokalkan string ini, karena digunakan untuk judul grup.

Cuplikan kode ini menunjukkan cara membuat MediaItem dengan judul subgrup Songs:

Kotlin

import androidx.media.utils.MediaConstants

private fun createMediaItem(
    mediaId: String,
    folderName: String,
    iconUri: Uri
): MediaBrowser.MediaItem {
    val mediaDescriptionBuilder = MediaDescription.Builder()
    mediaDescriptionBuilder.setMediaId(mediaId)
    mediaDescriptionBuilder.setTitle(folderName)
    mediaDescriptionBuilder.setIconUri(iconUri)
    val extras = Bundle()
    extras.putString(
        MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE,
        "Songs")
    mediaDescriptionBuilder.setExtras(extras)
    return MediaBrowser.MediaItem(
        mediaDescriptionBuilder.build(), /* playable or browsable flag*/)
}

Java

import androidx.media.utils.MediaConstants;

private MediaBrowser.MediaItem createMediaItem(String mediaId, String folderName, Uri iconUri) {
   MediaDescription.Builder mediaDescriptionBuilder = new MediaDescription.Builder();
   mediaDescriptionBuilder.setMediaId(mediaId);
   mediaDescriptionBuilder.setTitle(folderName);
   mediaDescriptionBuilder.setIconUri(iconUri);
   Bundle extras = new Bundle();
   extras.putString(
       MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE,
       "Songs");
   mediaDescriptionBuilder.setExtras(extras);
   return new MediaBrowser.MediaItem(
       mediaDescriptionBuilder.build(), /* playable or browsable flag*/);
}

Aplikasi Anda harus meneruskan semua item media yang ingin dikelompokkan bersama sebagai blok yang berdekatan. Misalnya, pertimbangkan untuk menampilkan dua grup item media, "Songs" dan "Albums", dalam urutan tersebut. Jika aplikasi Anda meneruskan lima item media dalam urutan ini, Android Auto dan AAOS akan menafsirkannya sebagai empat grup terpisah:

  • Item media A dengan extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  • Item media B dengan extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums")
  • Item media C dengan extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  • Item media D dengan extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  • Item media E dengan extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums")

Hal ini menghasilkan empat grup berikut:

  • Grup 1, yang disebut "Songs", berisi item media A
  • Grup 2, yang disebut "Albums", berisi item media B
  • Grup 3, yang disebut "Songs", berisi item media C dan D
  • Grup 4, yang disebut "Albums", berisi item media E

Untuk menampilkan item ini dalam dua grup, aplikasi Anda harus meneruskan item media dalam urutan ini:

  • Item media A dengan extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  • Item media C dengan extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  • Item media D dengan extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  • Item media B dengan extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums")
  • Item media E dengan extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums")

Menampilkan indikator metadata tambahan

Anda dapat menyertakan indikator metadata tambahan untuk menambahkan informasi sekilas bagi konten dalam hierarki browser media dan selama pemutaran.

Dalam hierarki penjelajahan, Android Auto dan AAOS membaca tambahan yang terkait dengan item dan menampilkan indikator. Selama pemutaran media, Android Auto dan AAOS membaca metadata untuk sesi media dan mencari konstanta tertentu untuk menentukan indikator yang akan ditampilkan.

Tampilan pemutaran dengan metadata

Gambar 3. Tampilan pemutaran dengan metadata.

Tampilan penjelajahan untuk konten yang belum diputar.

Gambar 4. Tampilan penjelajahan untuk konten yang belum diputar.

Konstanta ini dapat digunakan dalam kedua tambahan deskripsi MediaItem dan tambahan MediaMetadata:

Konstanta ini hanya dapat digunakan dalam tambahan deskripsi MediaItem:

Agar indikator ditampilkan saat pengguna menjelajahi hierarki penjelajahan media, buat paket tambahan yang menyertakan satu atau beberapa konstanta tersebut. Kemudian, teruskan paket tersebut ke metode MediaDescription.Builder.setExtras.

Cuplikan ini menunjukkan cara menampilkan indikator untuk item media vulgar yang sudah 70% selesai:

Kotlin

import androidx.media.utils.MediaConstants

val extras = Bundle()
extras.putLong(
    MediaConstants.METADATA_KEY_IS_EXPLICIT,
    MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT)
extras.putInt(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_STATUS,
    MediaConstants.DESCRIPTION_EXTRAS_VALUE_COMPLETION_STATUS_PARTIALLY_PLAYED)
extras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.7)
val description =
    MediaDescriptionCompat.Builder()
        .setMediaId(/*...*/)
        .setTitle(resources.getString(/*...*/))
        .setExtras(extras)
        .build()
return MediaBrowserCompat.MediaItem(description, /* flags */)

Java

import androidx.media.utils.MediaConstants;

Bundle extras = new Bundle();
extras.putLong(
    MediaConstants.METADATA_KEY_IS_EXPLICIT,
    MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT);
extras.putInt(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_STATUS,
    MediaConstants.DESCRIPTION_EXTRAS_VALUE_COMPLETION_STATUS_PARTIALLY_PLAYED);
extras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.7);
MediaDescriptionCompat description =
    new MediaDescriptionCompat.Builder()
        .setMediaId(/*...*/)
        .setTitle(resources.getString(/*...*/))
        .setExtras(extras)
        .build();
return new MediaBrowserCompat.MediaItem(description, /* flags */);

Untuk menampilkan indikator item media yang sedang diputar, deklarasikan nilai untuk METADATA_KEY_IS_EXPLICIT atau EXTRA_DOWNLOAD_STATUS di MediaMetadataCompat mediaSession Anda.

Cuplikan kode ini menunjukkan cara menunjukkan bahwa lagu di tampilan pemutaran bersifat vulgar dan telah didownload:

Kotlin

import androidx.media.utils.MediaConstants

mediaSession.setMetadata(
    MediaMetadataCompat.Builder()
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_TITLE, "Song Name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_SUBTITLE, "Artist name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_ALBUM_ART_URI,
            albumArtUri.toString())
        .putLong(
            MediaConstants.METADATA_KEY_IS_EXPLICIT,
            MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT)
        .putLong(
            MediaDescriptionCompat.EXTRA_DOWNLOAD_STATUS,
            MediaDescriptionCompat.STATUS_DOWNLOADED)
        .build())

Java

import androidx.media.utils.MediaConstants;

mediaSession.setMetadata(
    new MediaMetadataCompat.Builder()
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_TITLE, "Song Name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_DISPLAY_SUBTITLE, "Artist name")
        .putString(
            MediaMetadataCompat.METADATA_KEY_ALBUM_ART_URI,
            albumArtUri.toString())
        .putLong(
            MediaConstants.METADATA_KEY_IS_EXPLICIT,
            MediaConstants.METADATA_VALUE_ATTRIBUTE_PRESENT)
        .putLong(
            MediaDescriptionCompat.EXTRA_DOWNLOAD_STATUS,
            MediaDescriptionCompat.STATUS_DOWNLOADED)
        .build());

Memperbarui status progres di tampilan jelajah saat konten diputar

Seperti yang telah dijelaskan sebelumnya, Anda dapat menggunakan tambahan DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE untuk menampilkan status progres dari konten yang diputar sebagian di tampilan jelajah. Namun, jika pengguna terus memutar konten yang diputar sebagian, indikator tersebut akan menjadi tidak akurat seiring berjalannya waktu.

Agar Android Auto dan AAOS terus memperbarui status progres, berikan informasi tambahan di MediaMetadataCompat dan PlaybackStateCompat untuk menautkan konten yang sedang berlangsung ke item media di tampilan penjelajahan.

Agar item media memiliki status progres yang otomatis diperbarui, persyaratan berikut harus dipenuhi:

Cuplikan kode ini menunjukkan cara menunjukkan bahwa item yang sedang diputar ditautkan ke item dalam tampilan jelajah:

Kotlin

import androidx.media.utils.MediaConstants

// When the MediaItem is constructed to show in the browse view.
// Suppose the item was 25% complete when the user launched the browse view.
val mediaItemExtras = Bundle()
mediaItemExtras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.25)
val description =
    MediaDescriptionCompat.Builder()
        .setMediaId("my-media-id")
        .setExtras(mediaItemExtras)
        // ...and any other setters.
        .build()
return MediaBrowserCompat.MediaItem(description, /* flags */)

// Elsewhere, when the user has selected MediaItem for playback.
mediaSession.setMetadata(
    MediaMetadataCompat.Builder()
        .putString(MediaMetadata.METADATA_KEY_MEDIA_ID, "my-media-id")
        // ...and any other setters.
        .build())

val playbackStateExtras = Bundle()
playbackStateExtras.putString(
    MediaConstants.PLAYBACK_STATE_EXTRAS_KEY_MEDIA_ID, "my-media-id")
mediaSession.setPlaybackState(
    PlaybackStateCompat.Builder()
        .setExtras(playbackStateExtras)
        // ...and any other setters.
        .build())

Java

import androidx.media.utils.MediaConstants;

// When the MediaItem is constructed to show in the browse view.
// Suppose the item was 25% complete when the user launched the browse view.
Bundle mediaItemExtras = new Bundle();
mediaItemExtras.putDouble(
    MediaConstants.DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE, 0.25);
MediaDescriptionCompat description =
    new MediaDescriptionCompat.Builder()
        .setMediaId("my-media-id")
        .setExtras(mediaItemExtras)
        // ...and any other setters.
        .build();
return new MediaBrowserCompat.MediaItem(description, /* flags */);

// Elsewhere, when the user has selected MediaItem for playback.
mediaSession.setMetadata(
    new MediaMetadataCompat.Builder()
        .putString(MediaMetadata.METADATA_KEY_MEDIA_ID, "my-media-id")
        // ...and any other setters.
        .build());

Bundle playbackStateExtras = new Bundle();
playbackStateExtras.putString(
    MediaConstants.PLAYBACK_STATE_EXTRAS_KEY_MEDIA_ID, "my-media-id");
mediaSession.setPlaybackState(
    new PlaybackStateCompat.Builder()
        .setExtras(playbackStateExtras)
        // ...and any other setters.
        .build());

P Bahkan konten yang belum diputar atau telah diputar sepenuhnya dapat menampilkan status progres pembaruan otomatis. Hal ini terjadi jika item media yang sesuai menyertakan tambahan DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE dengan nilai 0.0 (untuk belum diputar) atau 1.0 (untuk diputar sepenuhnya). Setelah pengguna memilih item media ini, Android Auto dan AAOS akan menampilkan status progres daripada indikator progres lainnya.