مؤلفه «جزئیات پیشرفته جا»
نسخه «پیشرفته» مؤلفه «جزئیات مکان» همان ویژگیهای مؤلفه «جزئیات مکان» نسخه 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 اشتباه گرفته شود نمایش ندهید. محتوای سفارشی باید بهطور صریح منبع خود را ذکر کند.
نبایدها
آگهی، متن بازاریابی، تخفیف تبلیغاتی، یا درخواست اشتراک را در محفظههای سفارشی مکان قرار ندهید.
برای افزودن محتوای سفارشی، از ترکیبپذیر 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." ) } } }