مكوّن "تفاصيل المكان المتقدّمة"

يوفّر الإصدار المتقدّم من مكوّن "تفاصيل المكان" الميزات نفسها التي يوفّرها الإصدار الأساسي من "تفاصيل المكان". ويتيح لك أيضًا ضبط أزرار الإجراءات في المكوّن وتطبيق خيارات البحث والفلترة على المراجعات والوسائط المعروضة.

دعم مدمج لـ Jetpack Compose

توفّر حزمة أدوات "خرائط Google" الجاهزة للأماكن دوال @Composable في Jetpack Compose لـ 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، استخدِم دالتَي lambda‏ mainActions وcornerActions لضبط أزرار الإجراءات.

متطلبات تحديد المصدر

عرض مكثّف لتفاصيل المكان مع أزرار قابلة للتخصيص
عرض مصغّر لـ "تفاصيل المكان" المتقدّمة مع زر قابل للتخصيص

ملاحظة مهمة: يجب أن توضّح للمستخدمين النهائيين متى سيشارك زر الإجراء المخصّص معلومات المستخدم مع جهة خارجية غير Google. يُرجى الاطّلاع على متطلبات الإسناد المرئي.

يعرض المثال على اليسار صورة مخصّصة توضّح أنّه سيتم إرسال معلومات المستخدم إلى "Altostrat".

تطبيق خيارات البحث والفلترة

استخدِم الفئتَين SearchMediaOptions وSearchReviewsOptions من AdvancedPlaceDetailsFragment أو AdvancedPlaceDetailsCompactFragment لتفعيل البحث والفلترة للوسائط أو المراجعات.

إذا كنت تستخدم دوال @composable، استخدِم com.google.android.libraries.places.compose.search.SearchMediaOptions لتفعيل البحث والفلترة للوسائط أو المراجعات.

إنشاء خانات محتوى مخصّصة

خيارات مواضع خانات المحتوى المخصّصة

تتيح لك خانات المحتوى المخصّصة إضافة محتوى خاص بك (مثل الملخّصات من إنشاء الذكاء الاصطناعي أو الطوابع الزمنية لبرنامج الرحلة أو الشارات المخصّصة) مباشرةً إلى مناطق تنسيق محدّدة مسبقًا.

متطلبات تحديد المصدر واقتراحات المحتوى لخانة المحتوى

عند تثبيت خانة محتوى مخصّص، يتم تعديل بيان الإفصاح تلقائيًا لتوضيح المحتوى الذي تقدّمه Google والمحتوى الذي تقدّمه جهات خارجية.

الإجراءات المقترَحة

حافظ على تسلسل هرمي مرئي واضح بين تفاصيل المكان والمحتوى المخصّص لمنع أي غموض بشأن مصدر المعلومات.

تجنُّب الغموض بشأن مصدر المعلومات

الإجراءات المقترَحة

ننصحك بتقديم إحصاءات محلية عالية القيمة ومخصّصة لأهداف المستخدمين الفورية، مثل فترات الحجز في الوقت الفعلي أو مدى التوفّر الحالي، ما يساعد المستخدمين في اتّخاذ قرارات أسرع وأكثر دراية.

تقديم إحصاءات قيّمة

ما ننصحك بتجنّبه

لا تكرِّر تفاصيل الأماكن الحالية على 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)

إنشاء خانات المحتوى

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