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

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

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

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

کدها برای برنامه‌های عامل‌گرا

بااستفاده از کد دیداری‌سازی داده‌های عامل، برنامه عامل شما می‌تواند عناصر «کیت میانای کاربر جاها» را برای مکان‌های موجود در پاسخ ابزارهای عامل Maps Experience (‏Maps Grounding Lite سابق) بدون هزینه اضافی نمایش دهد. برای اطلاعات بیشتر، به نشان داده‌نمایی عاملی مراجعه کنید.

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

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

گزینه‌های نمایش محتوا

می‌توانید بااستفاده از شمارش‌ها در 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 برای فعال کردن جستجو و فیلتر کردن مرورها استفاده کنید.

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

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

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

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

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

Do

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

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

Do

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

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

نبایدها

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

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

نبایدها

ادعاها یا نشان‌های بدون منبع (برای مثال، «توصیه برتر!») را که ممکن است با تأیید رسمی 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)

استفاده از 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."
            )
        }
    }
}