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 設定動作按鈕。

視覺化出處資訊規定

地點詳細資料精簡檢視畫面,含自訂按鈕
進階 Place Details 精簡檢視畫面,含自訂按鈕

重要事項:如果自訂動作按鈕會將使用者資訊分享給 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 地點詳細資料

錯誤做法

請勿顯示未註明出處的聲明或徽章 (例如「首選推薦!」),以免使用者誤以為是 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."
            )
        }
    }
}