Komponent Zaawansowane informacje o miejscu

Wersja Zaawansowana komponentu informacje o miejscu oferuje te same funkcje co informacje o miejscu Essentials. Umożliwia też konfigurowanie przycisków poleceń komponentu oraz stosowanie opcji wyszukiwania i filtrowania do wyświetlanych opinii i multimediów.

Wbudowana obsługa Jetpack Compose

Places UI Kit udostępnia funkcje @Composable Jetpack Compose dla AdvancedPlaceDetailsCompact i AdvancedPlaceDetails. Te elementy kompozycyjne korzystają z podniesionego stanu, wbudowanej obsługi modyfikatorów i natywnych dla Compose slotów DSL. Zobacz przykład.

Tokeny dla aplikacji agentowych

Token wizualizacji danych agentowych umożliwia aplikacji agentowej wyświetlanie elementów interfejsu Places UI Kit dla miejsc w odpowiedzi narzędzi agentowych Maps Experience (dawniej Grounding Lite w Mapach) bez dodatkowych opłat. Więcej informacji znajdziesz w artykule Token wizualizacji danych agentowych.

Zaawansowana konfiguracja informacji o miejscu

Aby uzyskać dostęp do funkcji zaawansowanych, użyj funkcji kompozycyjnej AdvancedPlaceDetailsFragment, AdvancedPlaceDetailsCompactFragment, AdvancedPlaceDetails lub AdvancedPlaceDetailsCompact.

Opcje wyświetlania treści

Możesz określić, które treści mają być wyświetlane, używając typów wyliczeniowych w AdvancedPlaceDetailsFragment. Możesz skonfigurować wszystkie te same treści co w przypadku podstawowych informacji o miejscu. Jeśli używasz funkcji typu „composable”, możesz też wybrać, czy nazwa miejsca ma być wyświetlana.

Konfigurowanie przycisków poleceń

Aby zdefiniować i dostosować przyciski poleceń, użyj interfejsu PlaceActionProvider w AdvancedPlaceDetailsFragment lub AdvancedPlaceDetailsCompactFragment.

Jeśli używasz funkcji @Composable, do konfigurowania przycisków poleceń używaj funkcji lambda mainActions i cornerActions.

Wymagania dotyczące podania źródła wizualnego

Kompaktowy widok informacji o miejscu z przyciskami konfigurowalnymi
Zaawansowany widok kompaktowy szczegółowych informacji o miejscu z przyciskiem konfigurowalnym

Ważne: musisz wyraźnie poinformować użytkowników, kiedy przycisk działania niestandardowego będzie udostępniać informacje o użytkowniku firmie innej niż Google. Zobacz wymagania dotyczące podania źródła wizualnego.

Przykład po prawej stronie pokazuje niestandardowy obraz, który wyraźnie wskazuje, że informacje o użytkowniku zostaną wysłane do „Altostrat”.

Stosowanie opcji wyszukiwania i filtrowania

Użyj klas SearchMediaOptions i SearchReviewsOptions w AdvancedPlaceDetailsFragment lub AdvancedPlaceDetailsCompactFragment, aby umożliwić wyszukiwanie i filtrowanie multimediów lub opinii.

Jeśli używasz funkcji @Composable, użyj com.google.android.libraries.places.compose.search.SearchMediaOptions, aby włączyć wyszukiwanie i filtrowanie multimediów, oraz com.google.android.libraries.places.compose.search.SearchReviewsOptions, aby włączyć wyszukiwanie i filtrowanie opinii.

Tworzenie niestandardowych boksów treści

Opcje umieszczania niestandardowych boksów na treści

Niestandardowe boksy na treści umożliwiają dodawanie własnych treści (takich jak podsumowania wygenerowane przez AI, sygnatury czasowe planu podróży lub niestandardowe plakietki) bezpośrednio do wstępnie zdefiniowanych stref układu.

Wymagania dotyczące podania źródła i sugestie dotyczące treści w boksach treści

Po zamontowaniu niestandardowego boksu na treści komunikat jest automatycznie aktualizowany, aby wyjaśnić, które treści są dostarczane przez Google, a które przez osoby trzecie.

Należy

Zachowaj wyraźną hierarchię wizualną między informacjami o miejscu w Google a treściami niestandardowymi, aby uniknąć niejasności co do źródła informacji.

Zapobieganie niejednoznaczności dotyczącej źródła informacji

Należy

Rozważ dostarczanie zlokalizowanych, wartościowych informacji dostosowanych do bezpośrednich celów użytkowników. Dostosowane treści, takie jak okna rezerwacji w czasie rzeczywistym lub aktualna dostępność, pomagają użytkownikom podejmować szybsze i bardziej świadome decyzje.

Dostarczanie cennych statystyk

Przeciwwskazania

Nie powielaj istniejących informacji o miejscu w Google, takich jak oceny, opinie czy godziny otwarcia, nawet jeśli treści dostarczone przez Google zostały ukryte. Może to wprowadzać użytkowników w błąd co do źródła treści i tego, czy pochodzą one od Google czy od innej firmy.

Nie duplikuj istniejących informacji o miejscu w Google.

Przeciwwskazania

Nie wyświetlaj nieprzypisanych twierdzeń ani plakietek (np. „Najlepsza rekomendacja!”), które mogą być mylone z oficjalnymi rekomendacjami Google. Treści niestandardowe muszą wyraźnie wskazywać źródło.

Nie wyświetlaj twierdzeń ani odznak bez podania źródła

Przeciwwskazania

Nie umieszczaj w kontenerach niestandardowych miejsc reklam, tekstów marketingowych, rabatów promocyjnych ani próśb o subskrypcję.

Nie dodawaj reklam, tekstów marketingowych, rabatów promocyjnych ani próśb o subskrypcję.

Aby dodać treści niestandardowe, użyj funkcji kompozycyjnej AdvancedPlaceDetailsCompact. Aby określić pozycję treści, użyj właściwości basicSectionTop lub basicSectionBottom.

Przykłady zaawansowanych informacji o miejscu

Dostosowywanie przycisków poleceń

Użyj interfejsu PlaceActionProvider, aby kontrolować, które działania są dostępne w poszczególnych miejscach.

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
          this@HostAppActivity.listener = listener
        }

        override fun removePlaceActionsChangedListener(
          listener: PlaceActionProvider.OnChangedListener
        ) {
          // if there are multiple listeners, remove only the provided listener
          this@HostAppActivity.listener = null
        }
      })
  }
}

Dodawanie działań niestandardowych i wstępnie zdefiniowanych

Ten przykład dodaje przycisk przełączania, który pozwala użytkownikowi dodać miejsce do ulubionych lub je z nich usunąć.

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
        ) {
          this@PlaceDetailsWidgetTestActivity.listener = listener
        }

        override fun removePlaceActionsChangedListener(
          listener: PlaceActionProvider.OnChangedListener
        ) {
          // if there are multiple listeners, remove only the provided listener
          this@PlaceDetailsWidgetTestActivity.listener = null
        }
      }
    )
  }

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

Używanie wstępnie zdefiniowanych przycisków standardowych

tworzyć przyciski poleceń, które wykonują standardowe działania zdefiniowane przez 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
  }

Filtrowanie opinii i multimediów

Ten przykładowy kod pokazuje tylko multimedia i opinie, które zawierają słowa „spaghetti” i „smaczne”.

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)

Używanie funkcji kompozycyjnej do tworzenia układu pionowego

Poniższy przykładowy kod pokazuje, jak używać funkcji typu „composable” w przypadku układu pionowego karty AdvancedPlaceDetailsCompact.

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

Poniższy przykładowy kod pokazuje, jak używać funkcji typu „composable” w przypadku układu pionowego karty AdvancedPlaceDetails.

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.AdvancedPlaceDetails
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 SampleAdvancedPlaceDetailsCard(
    placeId: String,
    bookmarkIcon: Painter,
    onSavePlaceClicked: (Place) -> Unit
) {
    AdvancedPlaceDetails(
        // 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),
        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)
        }
    )
}

Tworzenie boksów treści

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."
            )
        }
    }
}