Composant "Informations avancées sur le lieu"

Il s'agit d'un composant Pro, dont la facturation est différente de celle des composants Essentials. Pour en savoir plus, consultez la présentation.

La version avancée du composant "Informations sur le lieu" offre les mêmes fonctionnalités que Places Details Essentials. Elle vous permet également de configurer les boutons d'action du composant et d'appliquer des options de recherche et de filtrage aux avis et aux contenus multimédias affichés.

Compatibilité intégrée avec Jetpack Compose

Kit UI pour Places fournit des fonctions @ComposableJetpack Composepour AdvancedPlaceDetailsCompact. Ces composables utilisent un état élevé, une compatibilité intégrée avec les modificateurs et des DSL d'emplacement natifs de Compose.

L'exemple de code suivant montre comment utiliser la fonction composable pour une mise en page verticale.

Kotlin

import android.util.Log
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.painter.Painter
import androidx.compose.ui.unit.dp
import com.google.android.libraries.places.api.model.Place
import com.google.android.libraries.places.compose.AdvancedPlaceDetailsCompact
import com.google.android.libraries.places.compose.PlaceReference
import com.google.android.libraries.places.compose.action.CornerAction
import com.google.android.libraries.places.compose.action.MainAction
import com.google.android.libraries.places.compose.Orientation

@Composable
fun SampleAdvancedPlaceDetailsCompactCard(
    placeId: String,
    bookmarkIcon: Painter,
    onSavePlaceClicked: (Place) -> Unit
) {
    AdvancedPlaceDetailsCompact(
        // defines the place to be displayed
        reference = PlaceReference.PlaceId(placeId),
        // defines the orientation
        orientation = Orientation.VERTICAL,
        // defines custom styling
        modifier = Modifier
            .fillMaxWidth()
            .padding(16.dp),
        preferTruncation = true,
        enableLightbox = true,
        mainActions = { place ->
            listOf(
                MainAction.OpenDirections(),
                MainAction.OpenWebsite(),
                MainAction.Call()
            )
        },
        // action button configuration
        cornerActions = { place ->
            listOf(
                CornerAction.Custom(
                    icon = bookmarkIcon,
                    text = "Save Place",
                    onClick = { onSavePlaceClicked(place) }
                )
            )
        },
        onPlaceLoaded = { place ->
            Log.d("Places", "Successfully loaded place: ${place.id}")
        },
        onPlaceLoadFailed = { exception ->
            Log.e("Places", "Failed to load place", exception)
        }
    ) {
        // --- Slot: Injected directly above the place name ---
        basicSectionTop {
            Text(
                text = "Featured in 'Top 10 Coffee Shops in SF'",
                style = MaterialTheme.typography.labelSmall,
                color = MaterialTheme.colorScheme.secondary,
                modifier = Modifier.padding(top = 4.dp, bottom = 2.dp)
            )
        }

        // --- Slot: Injected directly below the action buttons ---
        basicSectionBottom {
            Text(
                text = "Notes: Great quiet atmosphere for meetings.",
                style = MaterialTheme.typography.bodySmall,
                color = MaterialTheme.colorScheme.onSurfaceVariant
            )
        }
    }
}

Configuration avancée des informations sur le lieu

Utilisez les AdvancedPlaceDetailsFragment ou les AdvancedPlaceDetailsCompactFragment pour accéder aux fonctionnalités avancées.

Configurer les boutons d'action

Utilisez l'interface PlaceActionProvider de AdvancedPlaceDetailsFragment ou AdvancedPlaceDetailsCompactFragment pour définir et personnaliser les boutons d'action.

Si vous utilisez @composable fonctions, utilisez mainActions et cornerActions lambdas pour configurer les boutons d'action.

Exigences d'attribution visuelle

Vue compacte des informations avancées sur le lieu avec un bouton personnalisé

Important : Vous devez indiquer clairement aux utilisateurs finaux quand un bouton d'action personnalisé partagera des informations utilisateur avec un tiers autre que Google. Consultez les exigences concernant l'attribution visuelle.

L'exemple de droite montre une image personnalisée qui indique clairement que les informations utilisateur seront envoyées à "Altostrat".

Appliquer des options de recherche et de filtrage

Utilisez les classes SearchMediaOptions et SearchReviewsOptions de AdvancedPlaceDetailsFragment ou AdvancedPlaceDetailsCompactFragment pour activer la recherche et le filtrage des contenus multimédias ou des avis.

Si vous utilisez @composable fonctions, utilisez com.google.android.libraries.places.compose.search.SearchMediaOptions pour activer la recherche et le filtrage des contenus multimédias ou des avis.

Créer des emplacements de contenu personnalisés

Les emplacements de contenu personnalisés vous permettent d'ajouter votre propre contenu (par exemple, des résumés générés par IA, des codes temporels d'itinéraire ou des badges personnalisés) directement dans des zones de mise en page prédéfinies.

Remarque : Les emplacements de contenu personnalisés ne sont compatibles qu'avec le composable AdvancedPlaceDetailsCompact.

Exigences d'attribution et suggestions de contenu pour les emplacements de contenu

Lorsqu'un emplacement de contenu personnalisé est monté, la clause de non-responsabilité est automatiquement mise à jour pour indiquer clairement quel contenu est fourni par Google et quel contenu est fourni par des tiers.

À faire

Maintenez une hiérarchie visuelle claire entre les informations sur le lieu Google et le contenu personnalisé pour éviter toute ambiguïté quant à la source des informations.

À faire

Envisagez des insights localisés et à forte valeur ajoutée, adaptés aux objectifs immédiats de vos utilisateurs. Un contenu personnalisé, tel que des fenêtres de réservation en temps réel ou les disponibilités actuelles, aide les utilisateurs à prendre des décisions plus rapides et plus éclairées.

À éviter

Ne dupliquez pas les informations sur le lieu Google existantes, telles que les notes, les avis ou les horaires d'ouverture, même si vous avez masqué le contenu fourni par Google. Cela peut induire les utilisateurs en erreur quant à la source du contenu et à son origine (Google ou un tiers).

À éviter

N'affichez pas de revendications ni de badges sans attribution (par exemple, "Meilleure recommandation !") qui pourraient être confondus avec des recommandations officielles de Google. Le contenu personnalisé doit explicitement attribuer sa source.

À éviter

N'incluez pas d'annonces, de textes marketing, de remises promotionnelles ni d'invites à s'abonner dans les conteneurs de lieux personnalisés.

Pour ajouter du contenu personnalisé, utilisez le composable AdvancedPlaceDetailsCompact. Utilisez basicSectionTop ou basicSectionBottom pour spécifier la position du contenu.

Exemples d'informations avancées sur le lieu

Personnaliser les boutons d'action

Utilisez l'interface PlaceActionProvider pour contrôler les actions disponibles pour chaque lieu.

Kotlin

class PlaceDetailsWidgetTestActivity : BaseActivity() {

// simplified example of starting the fragment
fun setupPPDFragment() {
   fullWidgetSelectedContent = AdvancedPlaceDetailsFragment.ALL_CONTENT.toMutableList()
   AdvancedPlaceDetailsFragment.newInstance(fullWidgetSelectedContent, Orientation.VERTICAL)
   supportFragmentManager
      .beginTransaction()
      .replace(R.id.fragment_container, fragment!!)
      .commitNow()
}

// you can set the callback elsewhere, but this is the ideal callback spot
override fun onAttachFragment(fragment: Fragment) {
    super.onAttachFragment(fragment)
    when (fragment) {
      is PlaceActionController -> setPlaceActionProvider(fragment)
    }
}

// have this callback return an empty list to hide all buttons
// if this callback isn't set, default buttons appear
 private fun setPlaceActionProvider(fragment: PlaceActionController) {
    fragment.setPlaceActionProvider(
        object : PlaceActionProvider {
        override fun getMainPlaceActions(place: Place): List<PlaceAction> = buildList {
            // predefined actions can be mixed in with custom ones
            add(PlaceAction.OPEN_IN_MAPS)

            // example of button with both text label and icon
            add(
              PlaceAction.builder()
                .setLabelTextResId(R.string.custom_action)
                .setIconResId(R.drawable.gs_custom_action_icon)
                .setContentDescriptionResId(R.string.custom_action_description)
                .setOnClickListener { /* todo perform action */ }
                .build()
            )

            // icon only button
            add(
              PlaceAction.builder()
                .setIconResId(R.drawable.custom_action_icon_2)
                .setContentDescriptionResId(R.string.custom_action_description_2)
                .setOnClickListener { /* todo perform action */}
                .build()
            )

            // text label only button
            add(
              PlaceAction.builder()
                .setLabelTextResId(R.string.custom_action_3)
                .setContentDescriptionResId(R.string.custom_action_description_2)
                .setOnClickListener {/* todo perform action */ }
                .build()
            )
          }

         /**
         You can also specify whether corner buttons should appear.  
         For either callback, returning an empty list results in no buttons appearing
         */
         override fun getCornerPlaceActions(place: Place): List<PlaceAction> {
           return emptyList()
         }

        override fun addPlaceActionsChangedListener(
          listener: PlaceActionProvider.OnChangedListener
        ) {
          // in this example, just one listener and widget
          [e-mail] = listener
        }

        override fun removePlaceActionsChangedListener(
          listener: PlaceActionProvider.OnChangedListener
        ) {
          // if there are multiple listeners, remove only the provided listener
          [e-mail] = null
        }
      })
  }
}

Ajouter des actions personnalisées et prédéfinies

Cet exemple ajoute un bouton à bascule permettant à un utilisateur d'ajouter un lieu à ses favoris ou de le supprimer.

Kotlin

private var listener: PlaceActionProvider.OnChangedListener? = null

private fun setPlaceActionProvider(fragment: PlaceActionController) {
    fragment.setPlaceActionProvider(
      object : PlaceActionProvider {
        private var placeFavorited = false

        override fun getMainPlaceActions(place: Place): List<PlaceAction> {
          val buttonList = mutableListOf<PlaceAction>()

          if (placeFavorited) {
            buttonList.add(
              PlaceAction.builder()
                .setLabelTextResId(R.string.place_details_button_config_favorite)
                .setIconResId(R.drawable.gs_web_vd_theme_24)
                .setOnClickListener {
                  placeFavorited = !placeFavorited
                  refreshButtonConfigs()
                }
                .build()
            )
          } else {
            buttonList.add(
              PlaceAction.builder()
                .setLabelTextResId(R.string.place_details_button_config_unfavorite)
                .setIconResId(R.drawable.gs_web_vd_theme_24)
                .setOnClickListener {
                  placeFavorited = !placeFavorited
                  refreshButtonConfigs()
                }
                .build()
            )
          }

          return buttonList
        }

        override fun addPlaceActionsChangedListener(
          listener: PlaceActionProvider.OnChangedListener
        ) {
          [e-mail] = listener
        }

        override fun removePlaceActionsChangedListener(
          listener: PlaceActionProvider.OnChangedListener
        ) {
          // if there are multiple listeners, remove only the provided listener
          [e-mail] = null
        }
      }
    )
  }

private fun refreshButtonConfigs() {
    listener?.onPlaceActionsChanged()
}

Utiliser des boutons standards prédéfinis

Créez des boutons d'action qui effectuent des actions standards définies par Google.

Kotlin

  override fun getMainPlaceActions(place: Place): List<PlaceAction> {
    val buttonList = mutableListOf<PlaceAction>()
// these buttons will have different background and text color than user-created buttons.  
    // Text and icon button
    buttonList.add(PlaceAction.OPEN_IN_MAPS)
    // Icon-only buttons not enabled for main action buttons
    // Use of kotlin extension to do the same.  see
    PlaceAction.OPEN_IN_MAPS {
       setIconResId(0)
     }

    return buttonList
  }

Filtrer les avis et les contenus multimédias

Cet exemple de code n'affiche que les contenus multimédias et les avis qui mentionnent "spaghetti" et "délicieux".

Kotlin

    import com.google.android.libraries.places.widget.AdvancedPlaceDetailsFragment
    import com.google.android.libraries.places.widget.model.SearchMediaOptions
    import com.google.android.libraries.places.widget.model.SearchReviewsOptions
    import com.google.android.libraries.places.widget.model.Orientation
    import com.google.android.libraries.places.R
  
     // 1. Create options using the Java builders (called from Kotlin)
    val mediaOptions = SearchMediaOptions.builder()
        .setQuery("spaghetti")
        .setRankPreference(SearchMediaOptions.RankPreference.MOST_RELEVANT)
        .build()

    val reviewOptions = SearchReviewsOptions.builder()
        .setQuery("tasty")
        .setRankPreference(SearchReviewsOptions.RankPreference.NEWEST)
        .build()

    // 2. Create the fragment
    val fragment = AdvancedPlaceDetailsFragment.newInstance(
        AdvancedPlaceDetailsFragment.STANDARD_CONTENT,
        Orientation.VERTICAL,
        R.style.PlacesMaterialTheme
    )

    // 3. Apply options to the fragment
    fragment.applySearchMediaOptions(mediaOptions)
    fragment.applySearchReviewsOptions(reviewOptions)

Créer des emplacements de contenu

Kotlin

import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import com.google.android.libraries.places.compose.AdvancedPlaceDetailsCompact
import com.google.android.libraries.places.compose.PlaceReference

@Composable
fun ItineraryPlaceCard(placeId: String) {
    AdvancedPlaceDetailsCompact(
        reference = PlaceReference.PlaceId(placeId)
    ) {
        // Slot: Injected directly above the place name
        basicSectionTop {
            Text(
                text = "Day 2 • 2:30 PM",
                style = MaterialTheme.typography.labelSmall,
                color = MaterialTheme.colorScheme.primary
            )
        }
        
        // Slot: Injected directly below the main action buttons
        basicSectionBottom {
            NotesCard(
                notes = "Great quiet atmosphere for morning meetings. Famous for house-roasted pour-overs."
            )
        }
    }
}