Applicare stili di contenuti

Dopo aver utilizzato elementi sfogliabili o riproducibili per creare la gerarchia dei contenuti, applica gli stili dei contenuti per determinare la modalità di visualizzazione di questi elementi nell'auto. Utilizza questi stili di contenuti:

Voci dell'elenco

Figura 1. Gli elementi dell'elenco danno la priorità a titoli e metadati rispetto alle immagini.

Elementi della griglia

Figura 2. Gli elementi della griglia danno la priorità alle immagini rispetto ai titoli e ai metadati.

Impostare gli stili dei contenuti predefiniti

Puoi impostare valori predefiniti globali per la visualizzazione degli elementi multimediali. Per farlo, includi costanti specifiche nel bundle di extra BrowserRoot restituito dall'implementazione onGetRoot del tuo servizio e cerca queste costanti per determinare lo stile appropriato.

Questi componenti aggiuntivi possono essere utilizzati come chiavi nel bundle:

Queste chiavi possono essere mappate a questi valori costanti interi per influenzare la presentazione di questi elementi:

  • DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM: elementi corrispondenti presentati come voci di elenco.

  • DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM: elementi corrispondenti presentati come elementi della griglia.

  • DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_LIST_ITEM: Elementi corrispondenti presentati come elementi di elenco "categoria", simili ai normali elementi di elenco, ma i margini vengono applicati intorno alle icone degli elementi. In questo modo migliora l'aspetto delle icone piccole. Le icone devono essere risorse grafiche vettoriali colorabili. Questo suggerimento deve essere fornito solo per gli elementi sfogliabili.

  • DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_GRID_ITEM: Gli elementi corrispondenti vengono presentati come elementi della griglia "categoria" e sono simili ai normali elementi della griglia, ma vengono applicati margini intorno alle icone degli elementi. In questo modo migliora l'aspetto delle icone piccole. Le icone devono essere risorse vettoriali colorabili. Questo suggerimento deve essere fornito solo per gli elementi sfogliabili.

Questo snippet di codice mostra come impostare lo stile dei contenuti predefinito per gli elementi sfogliabili in modo che vengano visualizzati in griglie e per gli elementi riproducibili in modo che vengano visualizzati in elenchi:

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);
}

Impostare gli stili dei contenuti per elemento

Puoi eseguire l'override dello stile dei contenuti predefinito per i discendenti di qualsiasi elemento multimediale sfogliabile, nonché per qualsiasi elemento multimediale. Per ignorare il valore predefinito per i discendenti di un elemento multimediale sfogliabile, crea un bundle di contenuti aggiuntivi nel MediaDescription dell'elemento multimediale e aggiungi gli stessi suggerimenti menzionati in precedenza:

  • DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE si applica ai discendenti riproducibili dell'elemento.

  • DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE si applica ai discendenti navigabili dell'elemento.

Per ignorare il valore predefinito per una risorsa multimediale specifica (non i relativi elementi secondari), crea un bundle di contenuti aggiuntivi nel MediaDescription della risorsa multimediale. Poi, aggiungi un suggerimento con la chiave DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM. Utilizza gli stessi valori descritti in precedenza per specificare la presentazione dell'articolo.

Questo snippet di codice mostra come creare un MediaItem sfogliabile che esegue l'override dello stile dei contenuti predefinito per se stesso e i suoi discendenti. Si presenta come un elemento dell'elenco delle categorie, i suoi discendenti esplorabili come elementi dell'elenco e i suoi discendenti riproducibili come elementi della griglia.

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);
}

Raggruppare gli elementi utilizzando i suggerimenti per i titoli

Per raggruppare gli elementi multimediali correlati, utilizza un suggerimento per elemento. Ogni elemento multimediale di un gruppo deve dichiarare un bundle di contenuti aggiuntivi nel relativo MediaDescription. Questo bundle deve includere una mappatura con la chiave DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE e un valore stringa identico. Localizza questa stringa, in quanto viene utilizzata per il titolo del gruppo.

Questo snippet di codice mostra come creare un MediaItem con un'intestazione di sottogruppo 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*/);
}

La tua app deve trasmettere tutti gli elementi multimediali che vuoi raggruppare come un blocco contiguo. Ad esempio, prendi in considerazione la visualizzazione di due gruppi di elementi multimediali, "Canzoni" e "Album", in quest'ordine. Se la tua app passa cinque elementi multimediali in questo ordine, Android Auto e AAOS li interpretano come quattro gruppi separati:

  • Elemento multimediale A con extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  • Elemento multimediale B con extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums")
  • Elemento multimediale C con extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  • Elemento multimediale D con extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  • Elemento multimediale E con extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums")

Ciò comporta la creazione di questi quattro gruppi:

  • Il gruppo 1, chiamato "Canzoni", contenente l'elemento multimediale A
  • Gruppo 2, denominato "Album", contenente l'elemento multimediale B
  • Il gruppo 3, chiamato "Canzoni", contenente gli elementi multimediali C e D
  • Gruppo 4, denominato "Album", contenente l'elemento multimediale E

Per visualizzare questi elementi in due gruppi, l'app deve passare gli elementi multimediali in questo ordine:

  • Elemento multimediale A con extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  • Elemento multimediale C con extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  • Elemento multimediale D con extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Songs")
  • Elemento multimediale B con extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums")
  • Elemento multimediale E con extras.putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, "Albums")

Visualizzare indicatori di metadati aggiuntivi

Puoi includere indicatori di metadati aggiuntivi per fornire informazioni a colpo d'occhio per i contenuti nell'albero del browser dei media e durante la riproduzione.

Nell'albero di navigazione, Android Auto e AAOS leggono gli extra associati a un elemento e visualizzano gli indicatori. Durante la riproduzione dei contenuti multimediali, Android Auto e AAOS leggono i metadati della sessione multimediale e cercano costanti specifiche per determinare quali indicatori visualizzare.

Visualizzazione della riproduzione con i metadati

Figura 3. Visualizzazione della riproduzione con i metadati.

Visualizzazione Sfoglia per i contenuti non riprodotti.

Figura 4. Visualizzazione Sfoglia per i contenuti non riprodotti.

Queste costanti possono essere utilizzate sia negli extra delle descrizioni MediaItem sia negli extra MediaMetadata:

Queste costanti possono essere utilizzate solo nelle estensioni di descrizione MediaItem:

Per visualizzare gli indicatori che vengono visualizzati mentre l'utente naviga nella struttura di esplorazione dei contenuti multimediali, crea un bundle di contenuti aggiuntivi che includa una o più di queste costanti. Quindi, passa il bundle al metodo MediaDescription.Builder.setExtras.

Questo snippet mostra come visualizzare gli indicatori per un elemento multimediale esplicito completato al 70%:

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 */);

Per visualizzare gli indicatori di un elemento multimediale attualmente in riproduzione, dichiara i valori per METADATA_KEY_IS_EXPLICIT o EXTRA_DOWNLOAD_STATUS in MediaMetadataCompat di mediaSession.

Questo snippet di codice mostra come indicare che il brano nella visualizzazione di riproduzione è esplicito e scaricato:

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());

Aggiornare la barra di avanzamento nella visualizzazione Sfoglia durante la riproduzione dei contenuti

Come accennato in precedenza, puoi utilizzare l'extra DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE per mostrare una barra di avanzamento per i contenuti riprodotti parzialmente nella visualizzazione Sfoglia. Tuttavia, se un utente continua a riprodurre i contenuti riprodotti parzialmente, l'indicatore diventa impreciso nel tempo.

Affinché Android Auto e AAOS mantengano aggiornata la barra di avanzamento, fornisci informazioni aggiuntive in MediaMetadataCompat e PlaybackStateCompat per collegare i contenuti in corso agli elementi multimediali nella visualizzazione Sfoglia.

Affinché un elemento multimediale abbia una barra di avanzamento che si aggiorna automaticamente, devono essere soddisfatti i seguenti requisiti:

Questo snippet di codice mostra come indicare che l'elemento in riproduzione è collegato a un elemento nella visualizzazione Sfoglia:

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 Anche i contenuti non riprodotti o riprodotti completamente possono mostrare una barra di avanzamento che si aggiorna automaticamente. Ciò si verifica se gli elementi multimediali corrispondenti includono l'extra DESCRIPTION_EXTRAS_KEY_COMPLETION_PERCENTAGE con un valore di 0.0 (per i contenuti non riprodotti) o 1.0 (per i contenuti riprodotti completamente). Dopo che l'utente ha selezionato questi elementi multimediali, Android Auto e AAOS mostrano la barra di avanzamento sopra gli altri indicatori di avanzamento.