Place Details 元件

Places UI Kit 的 Place Details 元件可讓您新增個別 UI 元件，在應用程式中顯示地點詳細資料。

地點詳細資料精簡版元件

PlaceDetailsCompactFragment 會以最少的空間算繪所選地點的詳細資料。這項功能可用於資訊視窗，用於在地圖上醒目顯示地點，在社群媒體體驗中 (例如在即時通訊中分享地點) 提供建議，或在媒體文章中參照 Google 地圖上的地點。PlaceDetailsCompactFragment 可顯示名稱、地址、評分、類型、價格、無障礙圖示、營業狀態，以及單一相片。

您可以單獨使用 Place Details 元件，也可以搭配其他 Google 地圖平台 API 和服務使用。此元件會採用地點 ID 或經緯度座標，並傳回算繪的 Place Details 資訊。

帳單

使用 Place Details UI Kit 時，每次呼叫 .loadWithPlaceId() 或 .loadWithResourceName() 方法都會產生費用。如果您多次載入相同地點，系統會針對每項要求向您收費。

為避免多次收費，請勿在 Android 生命週期方法中直接新增 .loadWithPlaceId() 或 .loadWithResourceName()。舉例來說，請勿在 onResume() 方法中直接呼叫 .loadWithPlaceId() 或 .loadWithResourceName()。

在應用程式中新增地點詳細資料

您可以將片段新增至版面配置，為應用程式新增地點詳細資料。在將片段例項化時，您可以自訂地點詳細資料資訊的外觀和風格，以符合您的需求並與應用程式外觀相符。

在 Kotlin 和 Java 中，您可以使用兩種方法：一種是使用 Place ID 載入片段 (loadWithPlaceId())，另一種是使用資源名稱載入片段 (loadWithResourceName())。您可以選擇其中一種方法，如果同時使用 Place ID 和資源名稱，則可以選擇兩種方法。

您可以指定方向 (水平或垂直)、主題覆寫值和內容。內容選項包括媒體、地址、評分、價格、類型、無障礙入口和開放中狀態。進一步瞭解自訂功能。

Kotlin

val fragment = PlaceDetailsCompactFragment.newInstance(
  orientation,
  listOf(Content.ADDRESS, Content.TYPE, Content.RATING, Content.ACCESSIBLE_ENTRANCE_ICON),
  R.style.CustomizedPlaceDetailsTheme
)
      
fragment.setPlaceLoadListener(object : PlaceLoadListener {
  override fun onSuccess(place: Place) { ... }
      
  override fun onFailure(e: Exception) { ... }
})
      
supportFragmentManager
  .beginTransaction()
  .add(R.id.fragment_container, fragment)
  .commitNow()
      
// Load the fragment with a Place ID.
fragment.loadWithPlaceId(placeId)
// Load the fragment with a resource name.
//fragment.loadWithResourceName(resourceName)

Java

      
PlaceDetailsCompactFragment fragment =
  PlaceDetailsCompactFragment.newInstance(
        Orientation.HORIZONTAL,
        Arrays.asList(Content.ADDRESS, Content.TYPE, Content.RATING, Content.ACCESSIBLE_ENTRANCE_ICON),
        R.style.CustomizedPlaceDetailsTheme);
    
fragment.setPlaceLoadListener(
  new PlaceLoadListener() {
        @Override public void onSuccess(Place place) { ... }
    
        @Override public void onFailure(Exception e) { ... }
});
    
getSupportFragmentManager()
      .beginTransaction()
      .add(R.id.fragment_container, fragment)
      .commitNow();
    
// Load the fragment with a Place ID.
fragment.loadWithPlaceId(placeId);
      
// Load the fragment with a resource name.
// fragment.loadWithResourceName(resourceName);

查看載入 PlaceDetails 小工具的完整程式碼

Kotlin

        import android.os.Bundle
        import android.util.Log
        import android.view.View
        import android.widget.FrameLayout
        import androidx.appcompat.app.AppCompatActivity
        import com.google.android.gms.maps.CameraUpdateFactory
        import com.google.android.gms.maps.GoogleMap
        import com.google.android.gms.maps.OnMapReadyCallback
        import com.google.android.gms.maps.SupportMapFragment
        import com.google.android.gms.maps.model.LatLng
        import com.google.android.gms.maps.model.PointOfInterest
        import com.google.android.libraries.places.api.Places
        import com.google.android.libraries.places.api.net.PlacesClient
        import com.google.android.libraries.places.widget.PlaceDetailsCompactFragment
        import com.google.android.libraries.places.widget.PlaceDetailsCompactFragment.Companion.ALL_CONTENT
        import com.google.android.libraries.places.widget.model.Orientation
        
        class MainActivity : AppCompatActivity(), OnMapReadyCallback, GoogleMap.OnPoiClickListener {
            private var googleMap: GoogleMap? = null
            private val orientation: Orientation = Orientation.HORIZONTAL
            private lateinit var placesClient: PlacesClient
            private var placeDetailsFragment: PlaceDetailsCompactFragment? = null
        
            override fun onCreate(savedInstanceState: Bundle?) {
                super.onCreate(savedInstanceState)
                setContentView(R.layout.activity_main)
        
                // --- Initialize Places SDK ---
                val apiKey = BuildConfig.PLACES_API_KEY
                if (apiKey.isEmpty()) {
                    Log.e("Places test", "No api key")
                    finish()
                    return
                }
                Places.initializeWithNewPlacesApiEnabled(applicationContext, apiKey)
                placesClient = Places.createClient(this)
                // -----------------------------
        
                val mapFragment = supportFragmentManager.findFragmentById(R.id.map_fragment) as SupportMapFragment?
                mapFragment?.getMapAsync(this)
            }
        
            override fun onMapReady(map: GoogleMap) {
                googleMap = map
                val sydney = LatLng(-33.8688, 151.2093)
                val zoomLevel = 13f
                googleMap?.moveCamera(CameraUpdateFactory.newLatLngZoom(sydney, zoomLevel))
                googleMap?.setOnPoiClickListener(this)
            }
        
            override fun onPoiClick(poi: PointOfInterest) {
                val placeId = poi.placeId
                Log.d("POI Click", "Place ID: $placeId")
                showPlaceDetailsFragment(placeId)
            }
        
            private fun showPlaceDetailsFragment(placeId: String) {
                placeDetailsFragment = PlaceDetailsCompactFragment.newInstance(
                    ALL_CONTENT,
                    orientation,
                    R.style.CustomizedPlaceDetailsTheme
                )
                supportFragmentManager
                    .beginTransaction()
                    .replace(findViewById<FrameLayout>(R.id.place_details_fragment_host).id, placeDetailsFragment!!)
                    .commitNow()
                placeDetailsFragment?.loadWithPlaceId(placeId)
            }
        }

自訂地點詳細資料

Places UI 套件提供設計系統方法，可根據 Material Design 進行視覺自訂 (並進行一些 Google 地圖專屬修改)。請參閱 Material Design 的色彩和字體排版參考資料。根據預設，樣式會遵循 Google 地圖的視覺設計語言。

自訂地點詳細資料選項

在例項化片段時，您可以指定主題來覆寫任何預設樣式屬性。未覆寫的主題屬性都會使用預設樣式。如果您想支援深色主題，可以在 values-night/colors.xml 中新增顏色項目。

  <style name="CustomizedPlaceDetailsTheme" parent="PlacesMaterialsTheme">
    <item name="placesColorPrimary">@color/app_primary_color</item>
    <item name="placesColorOnSurface">@color/app_color_on_surface</item>
    <item name="placesColorOnSurfaceVariant">@color/app_color_on_surface</item>
  
    <item name="placesTextAppearanceBodySmall">@style/app_text_appearence_small</item>
  
    <item name="placesCornerRadius">20dp</item>
  </style>

您可以自訂下列樣式：

主題屬性 用量
顏色
placesColorSurface 容器和對話方塊背景
placesColorOnSurface 標題、對話內容
placesColorOnSurfaceVariant 地點資訊
placesColorPrimary 連結
placesColorOutlineDecorative 容器邊框
placesColorSecondaryContainer 按鈕背景
placesColorOnSecondaryContainer 按鈕文字和圖示
placesColorPositive 放置「營業中」標籤
placesColorNegative 放置「Closed」now 標籤
placesColorInfo 無障礙入口圖示
   
Typography
placesTextAppearanceHeadlineMedium 對話方塊標題
placesTextAppearanceTitleSmall 地點名稱
placesTextAppearanceBodyMedium 對話內容
placesTextAppearanceBodySmall 地點資訊
placesTextAppearanceLabelLarge 按鈕標籤
   
Corners
placesCornerRadius 容器角落
   
Google 地圖品牌歸屬資訊
placesColorAttributionLight 淺色主題的 Google 地圖歸屬和揭露資訊按鈕 (白色、灰色和黑色的列舉項目)
placesColorAttributionDark 深色主題的 Google 地圖歸屬和揭露資訊按鈕 (白色、灰色和黑色的列舉)

寬度和高度

對於直向檢視畫面，建議的寬度介於 180dp 和 300dp 之間。對於水平檢視畫面，建議寬度介於 180dp 和 500dp 之間。小於 160dp 的檢視畫面可能無法正確顯示。

最佳做法是不設定高度。這樣一來，視窗中的內容就能設定高度，讓所有資訊都能顯示。

歸因顏色

根據《Google 地圖服務條款》，您必須使用 Google 地圖歸屬資訊的三種品牌顏色之一。在自訂設定變更後，系統必須顯示並提供這項歸因資訊。

我們提供 3 種品牌顏色供您選擇，可分別設定為淺色和深色主題：

  • 淺色主題：placesColorAttributionLight，其中包含白色、灰色和黑色的列舉。
  • 深色主題：placesColorAttributionDark，其中包含白色、灰色和黑色的列舉。

自訂範例

這個範例會自訂標準內容。

  val fragmentStandardContent = PlaceDetailsCompactFragment.newInstance(
    orientation,
    PlaceDetailsCompactFragment.STANDARD_CONTENT,
    R.style.CustomizedPlaceDetailsTheme
  )

這個範例會自訂內容選項。

  val placeDetailsFragment = PlaceDetailsCompactFragment.newInstance(
    orientation,
    listOf(
        Content.ADDRESS,
        Content.ACCESSIBLE_ENTRANCE,Content.MEDIA
    ),
    R.style.CustomizedPlaceDetailsTheme
)

這個範例會自訂所有 Content 選項。

  val fragmentAllContent = PlaceDetailsCompactFragment.newInstance(
    orientation,
    PlaceDetailsCompactFragment.ALL_CONTENT,
    R.style.CustomizedPlaceDetailsTheme
  )