הרכיב 'פרטי המקום'

הרכיב 'פרטי מקום' בערכת ממשק המשתמש של Places מאפשר לכם להוסיף רכיב UI נפרד שמוצגים בו פרטי המקום באפליקציה.

התג PlaceDetailsCompactFragment מציג פרטים על מקום שנבחר בשטח מינימלי. התכונה הזו עשויה להיות שימושית בחלון מידע שמדגיש מקום במפה, בחוויית שימוש ברשתות חברתיות כמו שיתוף מיקום בצ'אט, כהצעה לבחירת המיקום הנוכחי או בתוך מאמר במדיה כדי להפנות למקום במפות Google. ב-PlaceDetailsCompactFragment אפשר להציג שם, כתובת, דירוג, סוג, מחיר, סמל נגישות, סטטוס פתיחה ותמונה אחת.

אפשר להשתמש ברכיב 'פרטי המקום' בנפרד או בשילוב עם שירותים וממשקי API אחרים של הפלטפורמה של מפות Google. הרכיב מקבל מזהה מקום או קואורדינטות של קו רוחב/אורך ומחזיר מידע מעוצב של פרטי המקום.

חיוב

כשמשתמשים ב-Place Details UI Kit, אתם מחויבים בכל פעם שמתבצעת קריאה ל-method‏ .loadWithPlaceId() או ל-method‏ .loadWithResourceName(). אם תטעינו את אותו מקום כמה פעמים, תחויבו על כל בקשה.

כדי להימנע מחיובים מרובים, אל תוסיפו את .loadWithPlaceId() או את .loadWithResourceName() ישירות לשיטות מחזור החיים של Android. לדוגמה, אין לבצע קריאה ישירה ל-.loadWithPlaceId() או ל-.loadWithResourceName() בשיטה onResume().

הוספת פרטי מקום לאפליקציה

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

יש שתי שיטות זמינות ב-Kotlin וב-Java: אחת לטעינה של החלק עם מזהה מקום (loadWithPlaceId()) ואחת לטעינה של החלק עם שם משאב (loadWithResourceName()). אפשר לבחור באחת מהשיטות, או בשתיהן אם משתמשים גם במזהי מקומות וגם בשמות משאבים.

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

Kotlin

val fragment = PlaceDetailsCompactFragment.newInstance(
  orientation,
  listOf(Content.ADDRESS, Content.TYPE, Content.RATING, Content.ACCESSIBLE_ENTRANCE_ICON),
  R.style.CustomizedPlaceDetailsTheme
)
      
fragment.setPlaceLoadListener(object : PlaceLoadListener {
  override fun onSuccess(place: Place) { ... }
      
  override fun onFailure(e: Exception) { ... }
})
      
supportFragmentManager
  .beginTransaction()
  .add(R.id.fragment_container, fragment)
  .commitNow()
      
// Load the fragment with a Place ID.
fragment.loadWithPlaceId(placeId)
// Load the fragment with a resource name.
//fragment.loadWithResourceName(resourceName)

Java

      
PlaceDetailsCompactFragment fragment =
  PlaceDetailsCompactFragment.newInstance(
        Orientation.HORIZONTAL,
        Arrays.asList(Content.ADDRESS, Content.TYPE, Content.RATING, Content.ACCESSIBLE_ENTRANCE_ICON),
        R.style.CustomizedPlaceDetailsTheme);
    
fragment.setPlaceLoadListener(
  new PlaceLoadListener() {
        @Override public void onSuccess(Place place) { ... }
    
        @Override public void onFailure(Exception e) { ... }
});
    
getSupportFragmentManager()
      .beginTransaction()
      .add(R.id.fragment_container, fragment)
      .commitNow();
    
// Load the fragment with a Place ID.
fragment.loadWithPlaceId(placeId);
      
// Load the fragment with a resource name.
// fragment.loadWithResourceName(resourceName);

הצגת הקוד המלא לטעינה של הווידג'ט 'פרטי מקום'

Kotlin

        import android.os.Bundle
        import android.util.Log
        import android.view.View
        import android.widget.FrameLayout
        import androidx.appcompat.app.AppCompatActivity
        import com.google.android.gms.maps.CameraUpdateFactory
        import com.google.android.gms.maps.GoogleMap
        import com.google.android.gms.maps.OnMapReadyCallback
        import com.google.android.gms.maps.SupportMapFragment
        import com.google.android.gms.maps.model.LatLng
        import com.google.android.gms.maps.model.PointOfInterest
        import com.google.android.libraries.places.api.Places
        import com.google.android.libraries.places.api.net.PlacesClient
        import com.google.android.libraries.places.widget.PlaceDetailsCompactFragment
        import com.google.android.libraries.places.widget.PlaceDetailsCompactFragment.Companion.ALL_CONTENT
        import com.google.android.libraries.places.widget.model.Orientation
        
        class MainActivity : AppCompatActivity(), OnMapReadyCallback, GoogleMap.OnPoiClickListener {
            private var googleMap: GoogleMap? = null
            private val orientation: Orientation = Orientation.HORIZONTAL
            private lateinit var placesClient: PlacesClient
            private var placeDetailsFragment: PlaceDetailsCompactFragment? = null
        
            override fun onCreate(savedInstanceState: Bundle?) {
                super.onCreate(savedInstanceState)
                setContentView(R.layout.activity_main)
        
                // --- Initialize Places SDK ---
                val apiKey = BuildConfig.PLACES_API_KEY
                if (apiKey.isEmpty()) {
                    Log.e("Places test", "No api key")
                    finish()
                    return
                }
                Places.initializeWithNewPlacesApiEnabled(applicationContext, apiKey)
                placesClient = Places.createClient(this)
                // -----------------------------
        
                val mapFragment = supportFragmentManager.findFragmentById(R.id.map_fragment) as SupportMapFragment?
                mapFragment?.getMapAsync(this)
            }
        
            override fun onMapReady(map: GoogleMap) {
                googleMap = map
                val sydney = LatLng(-33.8688, 151.2093)
                val zoomLevel = 13f
                googleMap?.moveCamera(CameraUpdateFactory.newLatLngZoom(sydney, zoomLevel))
                googleMap?.setOnPoiClickListener(this)
            }
        
            override fun onPoiClick(poi: PointOfInterest) {
                val placeId = poi.placeId
                Log.d("POI Click", "Place ID: $placeId")
                showPlaceDetailsFragment(placeId)
            }
        
            private fun showPlaceDetailsFragment(placeId: String) {
                placeDetailsFragment = PlaceDetailsCompactFragment.newInstance(
                    ALL_CONTENT,
                    orientation,
                    R.style.CustomizedPlaceDetailsTheme
                )
                supportFragmentManager
                    .beginTransaction()
                    .replace(findViewById<FrameLayout>(R.id.place_details_fragment_host).id, placeDetailsFragment!!)
                    .commitNow()
                placeDetailsFragment?.loadWithPlaceId(placeId)
            }
        }               
        
        

התאמה אישית של פרטי המקום

ערכת ממשק המשתמש של מפות Google מציעה גישה למערכת עיצוב של התאמה אישית חזותית שמבוססת בערך על Material Design (עם כמה שינויים ספציפיים למפות Google). אפשר לעיין במאמרים בנושא צבע וטיפוגרפיה במסמכי העזרה של Material Design. כברירת מחדל, הסגנון תואם לשפת העיצוב החזותי של מפות Google.

חשוב: כשמבצעים שינויים חזותיים, צריך לפעול בהתאם לדרישות השיוך למפות Google.

כשיוצרים מופע של קטע קוד, אפשר לציין עיצוב שיבטל את כל מאפייני הסגנון שמוגדרים כברירת מחדל. מאפייני עיצוב שלא בוטלו יתבססו על סגנונות ברירת המחדל. אם רוצים לתמוך בעיצוב כהה, אפשר להוסיף רשומה של הצבע בקובץ values-night/colors.xml.

  <style name="CustomizedPlaceDetailsTheme" parent="PlacesMaterialsTheme">
    <item name="placesColorPrimary">@color/app_primary_color</item>
    <item name="placesColorOnSurface">@color/app_color_on_surface</item>
    <item name="placesColorOnSurfaceVariant">@color/app_color_on_surface</item>
  
    <item name="placesTextAppearanceBodySmall">@style/app_text_appearence_small</item>
  
    <item name="placesCornerRadius">20dp</item>
  </style>

אפשר להתאים אישית את הסגנונות הבאים:

מאפיין העיצוב	שימוש
צבע
placesColorSurface	רקע של המכל ושל תיבת הדו-שיח
placesColorOnSurface	כותרות, תוכן של תיבת דו-שיח
placesColorOnSurfaceVariant	מידע על מקום
placesColorPrimary	קישורים
placesColorOutlineDecorative	גבול הקונטיינר
placesColorSecondaryContainer	רקע כפתור
placesColorOnSecondaryContainer	טקסט וסמל של כפתור
placesColorPositive	הצבת התווית 'פתיחה'
placesColorNegative	התווית 'סגור' מוצגת עכשיו במקום
placesColorInfo	סמל הכניסה הנגישה
טיפוגרפיה
placesTextAppearanceHeadlineMedium	כותרות של תיבות דו-שיח
placesTextAppearanceTitleSmall	שם המקום
placesTextAppearanceBodyMedium	התוכן של תיבת הדו-שיח
placesTextAppearanceBodySmall	מידע על מקום
placesTextAppearanceLabelLarge	תווית הכפתור
פינות
placesCornerRadius	פינות של קונטיינרים
שיוך מותגים במפות Google
placesColorAttributionLight	לחצן שיוך וחשיפת מידע של מפות Google בעיצוב בהיר (רשימות של ערכים קבועים לבן, אפור ושחור)
placesColorAttributionDark	כפתור שיוך וחשיפת מידע במפות Google בעיצוב כהה (רשימות של ערכים קבועים לבן, אפור ושחור)

רוחב וגובה

בתצוגה אנכית, הרוחב המומלץ הוא בין 180dp ל-300dp. בתצוגות אופקיות, הרוחב המומלץ הוא בין 180dp ל-500dp. יכול להיות שהתצוגה בגודל קטן מ-160dp לא תוצג בצורה תקינה.

השיטה המומלצת היא לא להגדיר גובה. כך התוכן בחלון יוכל להגדיר את הגובה, וכך כל המידע יוצג.

הערה: התמונה הממוזערת של המקום לא תופיע בתצוגות ברוחב של פחות מ-350dp.

צבעים של שיוך (Attribution)

התנאים וההגבלות של מפות Google מחייבים להשתמש באחד משלושת צבעי המותג לצורך שיוך למפות Google. השיוך הזה צריך להיות גלוי ונגיש אחרי ביצוע השינויים בהתאמה האישית.

יש לנו 3 צבעי מותג לבחירה, שאפשר להגדיר בנפרד לעיצוב בהיר ולעיצוב כהה:

• עיצוב בהיר: placesColorAttributionLight עם ערכים מוגדרים מראש (enums) לבן, אפור ושחור.
• עיצוב כהה: placesColorAttributionDark עם ערכים מוגדרים מראש (enums) לבן, אפור ושחור.

דוגמאות להתאמה אישית

הערה: אם לא מציינים התאמה אישית חזותית, הערך יישאר כערך ברירת המחדל.

בדוגמה הזו מתבצעת התאמה אישית של התוכן הרגיל.

  val fragmentStandardContent = PlaceDetailsCompactFragment.newInstance(
    orientation,
    PlaceDetailsCompactFragment.STANDARD_CONTENT,
    R.style.CustomizedPlaceDetailsTheme
  )

בדוגמה הזו מתבצעת התאמה אישית של אפשרויות התוכן.

  val placeDetailsFragment = PlaceDetailsCompactFragment.newInstance(
    orientation,
    listOf(
        Content.ADDRESS,
        Content.ACCESSIBLE_ENTRANCE,Content.MEDIA
    ),
    R.style.CustomizedPlaceDetailsTheme
)
  

בדוגמה הזו מתבצעת התאמה אישית של כל האפשרויות של Content.

  val fragmentAllContent = PlaceDetailsCompactFragment.newInstance(
    orientation,
    PlaceDetailsCompactFragment.ALL_CONTENT,
    R.style.CustomizedPlaceDetailsTheme
  )