مؤلفه «جزئیات پیشرفته جا»

نسخه «پیشرفته» مؤلفه «جزئیات مکان» همان ویژگی‌های اصول جزئیات مکان‌ها را ارائه می‌دهد. همچنین به شما امکان می‌دهد دکمه‌های کنش عنصر را پیکربندی کنید و گزینه‌های جستجو و فیلتر را روی مرورها و رسانه‌هایی که نمایش داده می‌شود اعمال کنید.

پشتیبانی داخلی Jetpack Compose

کیت میانای کاربر «جاها» عملکردهای Jetpack Compose@Composable را برایAdvancedPlaceDetailsCompact ارائه می‌دهد. این تابع‌های ترکیب‌پذیر از حالت بالابرده‌شده، پشتیبانی اصلاح‌گر داخلی، و DSLهای جایگاه بومی Compose استفاده می‌کنند.

نمونه کد زیر نحوه استفاده از تابع ترکیب‌پذیر برای چیدمان عمودی را نشان می‌دهد.

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)
        }
    ) {
        // --- Slot: Injected directly above the place name ---
        basicSectionTop {
            Text(
                text = "Featured in 'Top 10 Coffee Shops in SF'",
                style = MaterialTheme.typography.labelSmall,
                color = MaterialTheme.colorScheme.secondary,
                modifier = Modifier.padding(top = 4.dp, bottom = 2.dp)
            )
        }

        // --- Slot: Injected directly below the action buttons ---
        basicSectionBottom {
            Text(
                text = "Notes: Great quiet atmosphere for meetings.",
                style = MaterialTheme.typography.bodySmall,
                color = MaterialTheme.colorScheme.onSurfaceVariant
            )
        }
    }
}

پیکربندی «جزئیات پیشرفته مکان»

از AdvancedPlaceDetailsFragment یا AdvancedPlaceDetailsCompactFragment برای دسترسی به ویژگی‌های پیشرفته استفاده کنید.

پیکربندی دکمه‌های کنش

از رابط PlaceActionProvider AdvancedPlaceDetailsFragment یا AdvancedPlaceDetailsCompactFragment برای تعریف و سفارشی‌سازی دکمه‌های کنش استفاده کنید.

اگر از توابع @composable استفاده می‌کنید، از لامبداهای mainActions و cornerActions برای پیکربندی دکمه‌های کنش استفاده کنید.

الزامات ذکر منبع تصویری

نمای فشرده جزئیات مکان با دکمه‌های سفارشی‌شده
نمای فشرده «جزئیات مکان پیشرفته» با دکمه سفارشی‌سازی‌شده

مهم: باید برای کاربران نهایی روشن کنید که دکمه کنش سفارشی چه زمانی اطلاعات کاربر را با طرف سومی غیر از Google هم‌رسانی می‌کند. الزامات ارجاع تصویری را ببینید.

مثال سمت چپ تصویر سفارشی‌ای را نشان می‌دهد که به‌وضوح بیان می‌کند اطلاعات کاربر به «Altostrat» ارسال خواهد شد.

اعمال کردن گزینه‌های جستجو و فیلتر کردن

از کلاس‌های SearchMediaOptions و SearchReviewsOptions مربوط به AdvancedPlaceDetailsFragment یا AdvancedPlaceDetailsCompactFragment برای فعال کردن جستجو و فیلتر کردن رسانه‌ها یا مرورها استفاده کنید.

اگر از توابع @composable استفاده می‌کنید، از com.google.android.libraries.places.compose.search.SearchMediaOptions برای فعال کردن جستجو و فیلتر کردن رسانه یا مرورها استفاده کنید.

ایجاد جایگاه‌های محتوای سفارشی

گزینه‌های جایگاه محتوای سفارشی

جایگاه‌های محتوای سفارشی به شما امکان می‌دهند محتوای خودتان را (مانند خلاصه‌های تولیدشده با هوش مصنوعی، مُهرهای زمان برنامه سفر، یا نشان‌های سفارشی) مستقیماً به مناطق چیدمان ازپیش تعریف‌شده اضافه کنید.

الزامات ارجاع و پیشنهادهای محتوا برای جایگاه‌های محتوا

وقتی جایگاه محتوای سفارشی نصب می‌شود، شفاف‌سازی به‌طور خودکار به‌روز می‌شود تا مشخص شود کدام محتوا توسط Google ارائه شده است و اینکه برخی‌از محتواها توسط اشخاص ثالث ارائه شده است.

Do

برای جلوگیری از هرگونه ابهام درباره منبع اطلاعات، سلسله‌مراتب دیداری واضحی بین جزئیات «مکان Google» و محتوای سفارشی حفظ کنید.

جلوگیری از ابهام درباره منبع اطلاعات

Do

بینش‌های بومی‌سازی‌شده و ارزشمندی را که برای اهداف فوری کاربران شما سفارشی‌سازی شده است درنظر بگیرید. محتوای سفارشی‌سازی‌شده مثل پنجره‌های رزرو بی‌درنگ یا دردسترس بودن فعلی به کاربران کمک می‌کند سریع‌تر و آگاهانه‌تر تصمیم بگیرند.

ارائه اطلاعات آماری بسیار ارزشمند

Don't

جزئیات موجود «مکان Google» را، مثل رده‌بندی‌ها، مرورها، یا ساعت کاری، تکرار نکنید، حتی اگر محتوای ارائه‌شده توسط Google را پنهان کرده باشید. این کار می‌تواند کاربران را درباره منبع محتوا و اینکه آیا از Google یا شخص ثالثی می‌آید، گیج کند.

جزئیات موجود «مکان Google» را تکرار نکنید

Don't

ادعاها یا نشان‌های بدون انتساب (برای مثال، «توصیه برتر!») را که ممکن است با تأییدیه‌های رسمی Google اشتباه گرفته شوند نمایش ندهید. محتوای سفارشی باید منبع خود را به‌طور صریح ذکر کند.

ادعاها یا نشان‌های بدون منبع را نمایش ندهید

نبایدها

آگهی، متن بازاریابی، تخفیف تبلیغاتی، یا درخواست اشتراک را در محفظه‌های سفارشی مکان قرار ندهید.

آگهی‌ها، نوشتار بازاریابی، تخفیف‌های تبلیغاتی، یا پیام‌واره‌های اشتراک را اضافه نکنید

برای افزودن محتوای سفارشی، از 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)

ایجاد جایگاه‌های محتوا

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."
            )
        }
    }
}