Advanced Place Details 元件
Place Details 元件的 Advanced 版本提供與 Places Details Essentials 相同的功能,此外,您也可以設定元件的動作按鈕,並對顯示的評論和媒體套用搜尋和篩選選項。
內建 Jetpack Compose 支援
Places UI Kit 提供 AdvancedPlaceDetailsCompact 和 AdvancedPlaceDetails 的 Jetpack Compose @Composable 函式。這些可組合項使用提升狀態、內建修飾符支援,以及 Compose 原生版位 DSL。請參閱範例。
代理應用程式的權杖
有了代理資料視覺化權杖,代理應用程式就能在地圖體驗代理工具 (舊稱 Maps Grounding Lite) 回應中,顯示地點的 Places UI Kit 元素,不需額外付費。詳情請參閱「代理式資料視覺化權杖」。
進階 Place Details 設定
使用 AdvancedPlaceDetailsFragment、AdvancedPlaceDetailsCompactFragment、AdvancedPlaceDetails 可組合函式或 AdvancedPlaceDetailsCompact 可組合函式,存取進階功能。
內容顯示選項
您可以使用 AdvancedPlaceDetailsFragment 中的列舉,指定要顯示的內容。您可以設定與 Place Details Essentials 相同的所有內容。如果使用可組合函式,您也可以選擇是否要顯示地點名稱。
設定動作按鈕
使用 AdvancedPlaceDetailsFragment 或 AdvancedPlaceDetailsCompactFragment 的 PlaceActionProvider 介面,定義及自訂動作按鈕。
如果您使用 @Composable 函式,請使用 mainActions 和 cornerActions lambda 設定動作按鈕。
視覺化出處資訊規定
重要事項:如果自訂動作按鈕會將使用者資訊分享給 Google 以外的第三方,請務必向使用者清楚說明。請參閱視覺化出處註明規定。
右側範例顯示的自訂圖片,清楚說明使用者資訊將傳送至「Altostrat」。
套用搜尋和篩選選項
使用 AdvancedPlaceDetailsFragment 或 AdvancedPlaceDetailsCompactFragment 的 SearchMediaOptions 和 SearchReviewsOptions 類別,啟用媒體或評論的搜尋和篩選功能。
如果您使用 @Composable 函式,請使用 com.google.android.libraries.places.compose.search.SearchMediaOptions 啟用媒體搜尋和篩選功能,並使用 com.google.android.libraries.places.compose.search.SearchReviewsOptions 啟用評論搜尋和篩選功能。
建立自訂內容版位
自訂內容版位可讓您直接在預先定義的版面配置區域中,加入自己的內容 (例如 AI 生成的摘要、行程時間戳記或自訂徽章)。
內容版位的作者資訊相關規定和內容建議
掛接自訂內容版位後,揭露聲明會自動更新,清楚說明哪些內容由 Google 提供,哪些由第三方提供。
正確做法
Google Place details 和自訂內容之間,應維持清楚的視覺階層結構,避免資訊來源混淆。
正確做法
建議提供本地化的高價值洞察資訊,滿足使用者的即時目標。提供即時預訂時段或目前空房情況等量身打造的內容,有助於使用者更快做出更明智的決策。
錯誤做法
請勿複製現有的 Google Place Details,例如評分、評論或營業時間,即使您已隱藏 Google 提供的內容也一樣。否則使用者可能會混淆內容來源,不確定是來自 Google 還是第三方。
錯誤做法
請勿顯示未註明出處的聲明或徽章 (例如「首選推薦!」),以免使用者誤以為是 Google 官方背書。自訂內容必須明確註明來源。
錯誤做法
請勿在自訂地點容器中加入廣告、行銷文案、促銷折扣或訂閱提示。
如要新增自訂內容,請使用 AdvancedPlaceDetailsCompact 可組合函式。使用 basicSectionTop 或 basicSectionBottom 指定內容的位置。
Advanced Place Details 範例
自訂動作按鈕
使用 PlaceActionProvider 介面,控制每個地點可用的動作。
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 } }) } }
新增自訂和預先定義的動作
這個範例會新增切換鈕,讓使用者將地點加入或移出收藏。
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() }
使用預先定義的標準按鈕
建立動作按鈕,執行 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 }
篩選評論和媒體
這個程式碼範例只會顯示提及「spaghetti」和「tasty」的媒體和評論。
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)
使用可組合函式建立垂直版面配置
以下程式碼範例示範如何使用可組合函式,為 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) } ) }
以下程式碼範例示範如何使用可組合函式,為 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) } ) }
建立內容版位
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." ) } } }