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
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
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.
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.
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.
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.
Przeciwwskazania
Nie umieszczaj w kontenerach niestandardowych miejsc 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." ) } } }