רכיב מתקדם של פרטי מקום

הגרסה המתקדמת של רכיב פרטי המקום כוללת את אותן תכונות כמו גרסת Essentials של פרטי המקום. הוא גם מאפשר להגדיר את כפתורי הפעולה של הרכיב ולהחיל אפשרויות חיפוש וסינון על הביקורות והמדיה שמוצגות.

תמיכה מובנית ב-Jetpack Compose

ערכת Places UI Kit מספקת פונקציות של @Composable Jetpack Compose ל-AdvancedPlaceDetailsCompact ול-AdvancedPlaceDetails. הרכיבים הקומפוזביליים האלה משתמשים במצב מוגבה, בתמיכה מובנית ב-modifier וב-DSL של משבצות נייטיב ב-Compose. לדוגמה.

טוקנים לאפליקציות מבוססות-סוכנים

האסימון להצגה חזותית של נתונים מאפשר לאפליקציה האג'נטית להציג רכיבים של Places UI Kit בשביל המקומות בתשובה של הכלים האג'נטיים בממשק Maps (לשעבר Maps Grounding Lite) ללא עלות נוספת. מידע נוסף זמין במאמר אסימון להמחשה חזותית של נתונים מבוססי-סוכן.

הגדרה מתקדמת של Place Details

כדי לגשת לתכונות מתקדמות, משתמשים ב-AdvancedPlaceDetailsFragment, ב-AdvancedPlaceDetailsCompactFragment, בקוד הקומפוזבילי AdvancedPlaceDetails או בקוד הקומפוזבילי AdvancedPlaceDetailsCompact.

אפשרויות תצוגת התוכן

אתם יכולים לציין איזה תוכן להציג באמצעות ה-enums ב-AdvancedPlaceDetailsFragment. אפשר להגדיר את כל התוכן שמופיע ב-Places Details Essentials. אם אתם משתמשים בפונקציות הקומפוזביליות, אתם יכולים גם לבחור אם להציג את שם המקום.

הגדרת כפתורי פעולה

משתמשים בממשק PlaceActionProvider של AdvancedPlaceDetailsFragment או של AdvancedPlaceDetailsCompactFragment כדי להגדיר ולהתאים אישית את כפתורי הפעולות.

אם אתם משתמשים בפונקציות @Composable, השתמשו בפונקציות הלמבדה 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. בתוכן בהתאמה אישית צריך לציין במפורש את המקור שלו.

אל תציגו טענות או תגים ללא שיוך (Attribution)

מה לא מומלץ לעשות

אסור לכלול מודעות, תוכן שיווקי, הנחות או בקשות להירשם כמנוי בתוך קונטיינרים של מקומות בהתאמה אישית.

אל תכללו מודעות, טקסט שיווקי, הנחות או בקשות להירשם כמנויים.

כדי להוסיף תוכן מותאם אישית, משתמשים בפונקציה הקומפוזבילית 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)

שימוש בקומפוזבילי לפריסה אנכית

דוגמת הקוד הבאה ממחישה איך להשתמש בפונקציה הקומפוזבילית לפריסה אנכית של כרטיס 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."
            )
        }
    }
}