คอมโพเนนต์รายละเอียดสถานที่ขั้นสูง

คอมโพเนนต์รายละเอียดสถานที่เวอร์ชัน Advanced มีฟีเจอร์เหมือนกับรายละเอียดสถานที่แบบ Essentials นอกจากนี้ยังช่วยให้คุณกำหนดค่าปุ่มดำเนินการของคอมโพเนนต์ รวมถึงใช้ตัวเลือกการค้นหาและการกรองกับรีวิวและสื่อที่แสดงได้ด้วย

การรองรับ Jetpack Compose ในตัว

Places UI Kit มีฟังก์ชัน Jetpack Compose @Composable สำหรับ AdvancedPlaceDetailsCompact และ AdvancedPlaceDetails Composable เหล่านี้ใช้สถานะที่ยกขึ้น, การรองรับตัวแก้ไขในตัว และ DSL ของช่องที่มาพร้อมกับ Compose ดูตัวอย่าง

โทเค็นสำหรับแอป Agentic

โทเค็นการแสดงข้อมูลเป็นภาพแบบ Agentic ช่วยให้แอป Agentic แสดงองค์ประกอบ Places UI Kit สำหรับสถานที่ในการตอบกลับของเครื่องมือ Agent สำหรับ Maps Experience (เดิมชื่อ Maps Grounding Lite) ได้โดยไม่มีค่าใช้จ่ายเพิ่มเติม ดูข้อมูลเพิ่มเติมได้ที่โทเค็นการแสดงข้อมูลผ่านภาพแบบ Agentic

การกำหนดค่ารายละเอียดสถานที่ขั้นสูง

ใช้ AdvancedPlaceDetailsFragment, AdvancedPlaceDetailsCompactFragment, Composable AdvancedPlaceDetails หรือ Composable AdvancedPlaceDetailsCompact เพื่อเข้าถึงฟีเจอร์ขั้นสูง

ตัวเลือกการแสดงเนื้อหา

คุณระบุเนื้อหาที่จะแสดงได้โดยใช้ enum ใน AdvancedPlaceDetailsFragment คุณสามารถกำหนดค่าเนื้อหาทั้งหมดได้เหมือนกับ รายละเอียดสถานที่ Essentials หากใช้ฟังก์ชันที่ประกอบกันได้ คุณยังเลือกได้ว่าจะแสดงชื่อสถานที่หรือไม่

กำหนดค่าปุ่มดำเนินการ

ใช้อินเทอร์เฟซ PlaceActionProvider ของ AdvancedPlaceDetailsFragment หรือ AdvancedPlaceDetailsCompactFragment เพื่อกำหนดและปรับแต่งปุ่มดำเนินการ

หากใช้ฟังก์ชัน @Composable ให้ใช้ Lambda mainActions และ cornerActions เพื่อกำหนดค่าปุ่มดำเนินการ

ข้อกำหนดในการระบุแหล่งที่มาแบบภาพ

มุมมองรายละเอียดสถานที่แบบกะทัดรัดพร้อมปุ่มที่ปรับแต่งได้
มุมมองแบบกะทัดรัดของรายละเอียดสถานที่ขั้นสูงพร้อมปุ่มที่ปรับแต่งได้

สำคัญ: คุณต้องแจ้งให้ผู้ใช้ปลายทางทราบอย่างชัดเจนเมื่อปุ่มดำเนินการที่กำหนดเองจะแชร์ข้อมูลผู้ใช้กับบุคคลที่สามที่ไม่ใช่ Google ดูข้อกำหนดการระบุแหล่งที่มาแบบภาพ

ตัวอย่างทางด้านขวาแสดงรูปภาพที่กำหนดเองซึ่งระบุอย่างชัดเจนว่าจะมีการส่งข้อมูลผู้ใช้ไปยัง "Altostrat"

ใช้ตัวเลือกการค้นหาและการกรอง

ใช้คลาส SearchMediaOptions และ SearchReviewsOptions ของ AdvancedPlaceDetailsFragment หรือ AdvancedPlaceDetailsCompactFragment เพื่อเปิดใช้การค้นหาและการกรองสื่อหรือรีวิว

หากใช้ฟังก์ชัน @Composable ให้ใช้ com.google.android.libraries.places.compose.search.SearchMediaOptions เพื่อเปิดใช้การค้นหาและการกรองสื่อ และใช้ com.google.android.libraries.places.compose.search.SearchReviewsOptions เพื่อเปิดใช้การค้นหาและการกรองรีวิว

สร้างช่องเนื้อหาที่กำหนดเอง

ตัวเลือกตำแหน่งช่องเนื้อหาที่กำหนดเอง

ช่องเนื้อหาที่กำหนดเองช่วยให้คุณเพิ่มเนื้อหาของคุณเอง (เช่น ข้อมูลสรุปที่ AI สร้างขึ้น การประทับเวลาของแผนการเดินทาง หรือป้ายที่กำหนดเอง) ลงในโซนเลย์เอาต์ที่กำหนดไว้ล่วงหน้าได้โดยตรง

ข้อกำหนดการระบุแหล่งที่มาและคำแนะนำด้านเนื้อหาสำหรับช่องเนื้อหา

เมื่อติดตั้งช่องเนื้อหาที่กำหนดเอง การเปิดเผยข้อมูลจะอัปเดตโดยอัตโนมัติเพื่อชี้แจงว่าเนื้อหาใดที่ Google เป็นผู้ให้บริการ และเนื้อหาใดที่บุคคลที่สามเป็นผู้ให้บริการ

สิ่งที่ควรทำ

รักษาลำดับชั้นภาพที่ชัดเจนระหว่างรายละเอียดสถานที่ของ Google กับเนื้อหาที่กำหนดเองเพื่อป้องกันความคลุมเครือเกี่ยวกับแหล่งที่มาของข้อมูล

ป้องกันความคลุมเครือเกี่ยวกับแหล่งที่มาของข้อมูล

สิ่งที่ควรทำ

พิจารณาข้อมูลเชิงลึกที่มีคุณค่าสูงและมีการแปลเป็นภาษาท้องถิ่นซึ่งปรับให้เหมาะกับเป้าหมายเร่งด่วนของผู้ใช้ เนื้อหาที่ปรับให้เหมาะสม เช่น กรอบเวลาการจองแบบเรียลไทม์หรือห้องว่างในปัจจุบัน จะช่วยให้ผู้ใช้ตัดสินใจได้เร็วขึ้นและมีข้อมูลประกอบมากขึ้น

ให้ข้อมูลเชิงลึกที่มีคุณค่าสูง

สิ่งที่ไม่ควรทำ

อย่าทำซ้ำรายละเอียดสถานที่ที่มีอยู่แล้วใน Google เช่น คะแนน รีวิว หรือเวลาทำการ แม้ว่าคุณจะซ่อนเนื้อหาที่ Google มีให้ก็ตาม การดำเนินการดังกล่าวอาจทำให้ผู้ใช้สับสนเกี่ยวกับแหล่งที่มาของเนื้อหา และไม่แน่ใจว่าเนื้อหามาจาก Google หรือบุคคลที่สาม

อย่าทำซ้ำรายละเอียดสถานที่ที่มีอยู่แล้วใน Google

สิ่งที่ไม่ควรทำ

อย่าแสดงคำกล่าวอ้างหรือป้ายที่ไม่มีการระบุแหล่งที่มา (เช่น "คำแนะนำยอดนิยม") ซึ่งอาจทำให้เข้าใจผิดว่าเป็นการรับรองอย่างเป็นทางการจาก Google เนื้อหาที่กำหนดเองต้องระบุแหล่งที่มาอย่างชัดเจน

ไม่แสดงการกล่าวอ้างหรือป้ายที่ไม่มีการระบุแหล่งที่มา

สิ่งที่ไม่ควรทำ

อย่าใส่โฆษณา ข้อความทางการตลาด ส่วนลดโปรโมชัน หรือข้อความแจ้งให้สมัครใช้บริการภายในคอนเทนเนอร์สถานที่ที่กำหนดเอง

อย่าใส่โฆษณา ข้อความทางการตลาด ส่วนลดโปรโมชัน หรือข้อความแจ้งให้สมัครใช้บริการ

หากต้องการเพิ่มเนื้อหาที่กำหนดเอง ให้ใช้ Composable AdvancedPlaceDetailsCompact ใช้ basicSectionTop หรือ basicSectionBottom เพื่อระบุตำแหน่งของเนื้อหา

ตัวอย่างรายละเอียดสถานที่ขั้นสูง

ปรับแต่งปุ่มดำเนินการ

ใช้อินเทอร์เฟซ 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
  }

กรองรีวิวและสื่อ

ตัวอย่างโค้ดนี้แสดงเฉพาะสื่อและรีวิวที่พูดถึง "สปาเกตตี" และ "อร่อย"

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)

ใช้ Composable สำหรับเลย์เอาต์แนวตั้ง

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีใช้ฟังก์ชันที่ประกอบกันได้สำหรับเลย์เอาต์แนวตั้งของการ์ด 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."
            )
        }
    }
}