סמנים

בחירת פלטפורמה: Android iOS JavaScript

מפה עם כמה סמנים

סמנים מזהים מיקומים במפה. סמן ברירת המחדל משתמש בסמל סטנדרטי, שמתאים למראה ולתחושה של מפות Google. אפשר לשנות את הצבע, התמונה או נקודת העיגון של הסמל באמצעות ה-API. סמנים הם אובייקטים מסוג Marker, והם מתווספים למפה באמצעות השיטה GoogleMap.addMarker(markerOptions).

הסמנים נועדו להיות אינטראקטיביים. הם מקבלים אירועי click כברירת מחדל, ולעיתים קרובות משתמשים בהם עם רכיבי event listener כדי להציג חלונות מידע. הגדרת המאפיין draggable של סמן לערך true מאפשרת למשתמש לשנות את המיקום של הסמן. לוחצים לחיצה ארוכה כדי להפעיל את האפשרות להזיז את הסמן.

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

הוסף סמן

בדוגמה הבאה מוסבר איך להוסיף סמן למפה. הסמן נוצר בקואורדינטות -33.852,151.211 (סידני, אוסטרליה), וכשלוחצים עליו מוצגת המחרוזת "Marker in Sydney" בחלון מידע.

Kotlin

// Add a marker in Sydney, Australia,
// and move the map's camera to the same location.
val sydney = LatLng(-33.852, 151.211)
map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney"),
)
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

Java

// Add a marker in Sydney, Australia,
// and move the map's camera to the same location.
LatLng sydney = new LatLng(-33.852, 151.211);
map.addMarker(new MarkerOptions().position(sydney).title("Marker in Sydney"));
map.moveCamera(CameraUpdateFactory.newLatLng(sydney));

הצגת מידע נוסף על סמן

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

שיוך נתונים לסמן

אפשר לאחסן אובייקט נתונים שרירותי עם סמן באמצעות Marker.setTag(), ולאחזר את אובייקט הנתונים באמצעות Marker.getTag(). הדוגמה הבאה ממחישה איך אפשר לספור את מספר הפעמים שבהן משתמשים לחצו על סמן באמצעות תגים:

Kotlin

val PERTH = LatLng(-31.952854, 115.857342)
val SYDNEY = LatLng(-33.87365, 151.20689)
val BRISBANE = LatLng(-27.47093, 153.0235)

val markerPerth = map.addMarker(
    MarkerOptions()
        .position(PERTH)
        .title("Perth"),
)
markerPerth?.tag = 0

val markerSydney = map.addMarker(
    MarkerOptions()
        .position(SYDNEY)
        .title("Sydney"),
)
markerSydney?.tag = 0

val markerBrisbane = map.addMarker(
    MarkerOptions()
        .position(BRISBANE)
        .title("Brisbane"),
)
markerBrisbane?.tag = 0

// Set a listener for marker click.
map.setOnMarkerClickListener { marker ->
    // Retrieve the data from the marker.
    val clickCount = marker.tag as? Int

    // Check if a click count was set, then display the click count.
    clickCount?.let {
        val newClickCount = it + 1
        marker.tag = newClickCount
        Toast.makeText(
            context,
            "${marker.title} has been clicked $newClickCount times.",
            Toast.LENGTH_SHORT,
        ).show()
    }

    // Return false to indicate default behavior.
    false
}

Java

final LatLng PERTH = new LatLng(-31.952854, 115.857342);
final LatLng SYDNEY = new LatLng(-33.87365, 151.20689);
final LatLng BRISBANE = new LatLng(-27.47093, 153.0235);

Marker markerPerth = map.addMarker(new MarkerOptions().position(PERTH).title("Perth"));
markerPerth.setTag(0);

Marker markerSydney = map.addMarker(new MarkerOptions().position(SYDNEY).title("Sydney"));
markerSydney.setTag(0);

Marker markerBrisbane =
        map.addMarker(new MarkerOptions().position(BRISBANE).title("Brisbane"));
markerBrisbane.setTag(0);

// Set a listener for marker click.
map.setOnMarkerClickListener(
        new GoogleMap.OnMarkerClickListener() {
            @Override
            public boolean onMarkerClick(final Marker marker) {
                // Retrieve the data from the marker.
                Integer clickCount = (Integer) marker.getTag();

                // Check if a click count was set, then display the click count.
                if (clickCount != null) {
                    clickCount = clickCount + 1;
                    marker.setTag(clickCount);
                    Toast.makeText(
                                    context,
                                    marker.getTitle()
                                            + " has been clicked "
                                            + clickCount
                                            + " times.",
                                    Toast.LENGTH_SHORT)
                            .show();
                }

                // Return false to indicate default behavior should occur.
                return false;
            }
        });

ריכזנו כאן כמה דוגמאות לתרחישים שבהם כדאי לאחסן ולאחזר נתונים באמצעות סמנים:

  • יכול להיות שהאפליקציה שלכם תומכת בסוגים שונים של סמנים, ואתם רוצים להתייחס אליהם באופן שונה כשהמשתמש לוחץ עליהם. כדי לעשות את זה, אתם יכולים לאחסן String עם הסמן שמציין את הסוג.
  • יכול להיות שאתם משתמשים במערכת עם מזהי רשומות ייחודיים, שבהם הסמנים מייצגים רשומות ספציפיות במערכת הזו.
  • נתוני הסמן עשויים לציין עדיפות שבה צריך להשתמש כשמחליטים על ה-z-index של סמן.

הפיכת סמן לניתן לגרירה

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

כברירת מחדל, אי אפשר לגרור סמנים. צריך להגדיר במפורש שהסמן ניתן לגרירה, באמצעות MarkerOptions.draggable(boolean) לפני שמוסיפים אותו למפה, או באמצעות Marker.setDraggable(boolean) אחרי שמוסיפים אותו למפה. אפשר להאזין לאירועי גרירה בסמן, כפי שמתואר בקטע אירועי גרירה של סמנים.

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

Kotlin

val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
    MarkerOptions()
        .position(perthLocation)
        .draggable(true),
)

Java

final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth = map.addMarker(new MarkerOptions().position(perthLocation).draggable(true));

התאמה אישית של סמן

בסרטון הזה מוצגות דרכים להשתמש בסמנים כדי להציג מיקומים במפה.

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

אפשר להתאים אישית סמנים באמצעות המאפיינים הבאים:

תפקיד (חובה)
הערך של LatLng למיקום של הסמן במפה. זהו המאפיין היחיד שנדרש לאובייקט Marker.
עוגן
הנקודה בתמונה שתמוקם במיקום LatLng של הסמן. כברירת מחדל, המיקום הוא במרכז החלק התחתון של התמונה.
אלפא
הגדרת האטימות של הסמן. ברירת המחדל היא 1.0.
כותרת
מחרוזת שמוצגת בחלון המידע כשהמשתמש מקיש על הסמן.
קטע טקסט
טקסט נוסף שמוצג מתחת לכותרת.
סמל
מפת סיביות (bitmap) שמוצגת במקום תמונת הסמן שמוגדרת כברירת מחדל.
ניתן לגרירה
מגדירים את הערך true אם רוצים לאפשר למשתמש להזיז את הסמן. ברירת המחדל היא false.
גלוי
מגדירים את הערך false כדי להסתיר את הסמן. ברירת המחדל היא true.
כיוון שטוח או כיוון של שלט חוצות
כברירת מחדל, הסמנים מוצגים בכיוון של שלט חוצות, כלומר הם מוצגים בכיוון של מסך המכשיר ולא בכיוון של פני השטח של המפה. סיבוב, הטיה או שינוי מרחק התצוגה של המפה לא משנים את הכיוון של הסמן. אפשר להגדיר את הכיוון של סמן כך שיהיה שטוח על פני כדור הארץ. סמנים שטוחים מסתובבים כשמסובבים את המפה, ומשנים את הפרספקטיבה כשמטים את המפה. בדומה לסמנים של שלטי חוצות, סמנים שטוחים שומרים על הגודל שלהם כשמגדילים או מקטינים את התצוגה של המפה.
סיבוב
כיוון הסמן, מצוין במעלות בכיוון השעון. מיקום ברירת המחדל משתנה אם הסמן שטוח. מיקום ברירת המחדל של סמן שטוח הוא בכיוון צפון. כשהסמן לא שטוח, מיקום ברירת המחדל הוא כלפי מעלה והסיבוב הוא כזה שהסמן תמיד פונה למצלמה.

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

Kotlin

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation),
)

Java

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne = map.addMarker(new MarkerOptions().position(melbourneLocation));

התאמה אישית של צבע הסמן

אפשר להתאים אישית את הצבע של תמונת ברירת המחדל של הסמן על ידי העברת אובייקט BitmapDescriptor ל-method‏()icon. אתם יכולים להשתמש בקבוצה של צבעים מוגדרים מראש באובייקט BitmapDescriptorFactory, או להגדיר צבע סמן בהתאמה אישית באמצעות השיטה BitmapDescriptorFactory.defaultMarker(float hue). הגוון הוא ערך בין 0 ל-360, שמייצג נקודות בגלגל הצבעים.

Kotlin

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation)
        .icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_AZURE)),
)

Java

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne =
        map.addMarker(
                new MarkerOptions()
                        .position(melbourneLocation)
                        .icon(
                                BitmapDescriptorFactory.defaultMarker(
                                        BitmapDescriptorFactory.HUE_AZURE)));

התאמה אישית של אטימות הסמן

אתם יכולים לשלוט באטימות של סמן באמצעות השיטה MarkerOptions.alpha()‎. צריך לציין את ערך האלפא כמספר עשרוני בין 0.0 ל-1.0, כאשר 0 הוא שקוף לחלוטין ו-1 הוא אטום לחלוטין.

Kotlin

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation)
        .alpha(0.7f),
)

Java

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne =
        map.addMarker(new MarkerOptions().position(melbourneLocation).alpha(0.7f));

התאמה אישית של תמונת הסמן

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

fromAsset(String assetName)
יוצר סמן בהתאמה אישית באמצעות השם של תמונת Bitmap בספריית הנכסים.
fromBitmap(Bitmap image)
יוצר סמן בהתאמה אישית מתמונת Bitmap.
fromFile(String fileName)
יוצר סמל בהתאמה אישית באמצעות השם של קובץ תמונה מסוג Bitmap שנמצא באחסון הפנימי.
fromPath(String absolutePath)
יוצר סמן בהתאמה אישית מנתיב קובץ מוחלט של תמונת מפת סיביות (bitmap).
fromResource(int resourceId)
יוצרת סמן בהתאמה אישית באמצעות מזהה המשאב של תמונת Bitmap.

קטע הקוד הבא יוצר סמן עם סמל בהתאמה אישית.

Kotlin

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation)
        .title("Melbourne")
        .snippet("Population: 4,137,400")
        .icon(BitmapDescriptorFactory.fromResource(R.drawable.arrow)),
)

Java

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne =
        map.addMarker(
                new MarkerOptions()
                        .position(melbourneLocation)
                        .title("Melbourne")
                        .snippet("Population: 4,137,400")
                        .icon(BitmapDescriptorFactory.fromResource(R.drawable.arrow)));

איך משטחים סמן

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

כדי לשנות את הכיוון של הסמן, מגדירים את המאפיין flat של הסמן לערך true.

Kotlin

val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
    MarkerOptions()
        .position(perthLocation)
        .flat(true),
)

Java

final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth = map.addMarker(new MarkerOptions().position(perthLocation).flat(true));

סיבוב סמן

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

בדוגמה הבאה, הסמן מסובב ב-90 מעלות. הגדרת נקודת העיגון לערך 0.5,0.5 גורמת לסמן להסתובב סביב המרכז שלו, במקום סביב הבסיס שלו.

Kotlin

val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
    MarkerOptions()
        .position(perthLocation)
        .anchor(0.5f, 0.5f)
        .rotation(90.0f),
)

Java

final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth =
        map.addMarker(
                new MarkerOptions()
                        .position(perthLocation)
                        .anchor(0.5f, 0.5f)
                        .rotation(90.0f));

אינדקס Z של הסמן

המאפיין z-index מציין את סדר הערימה של הסמן הזה, ביחס לסמנים אחרים במפה. סמן עם ערך z-index גבוה משורטט מעל סמנים עם ערכי z-index נמוכים יותר. ערך ברירת המחדל של z-index הוא 0.

מגדירים את ה-z-index באובייקט האפשרויות של הסמן באמצעות קריאה ל-MarkerOptions.zIndex(), כמו שמוצג בקטע הקוד הבא:

Kotlin

map.addMarker(
    MarkerOptions()
        .position(LatLng(10.0, 10.0))
        .title("Marker z1")
        .zIndex(1.0f),
)

Java

map.addMarker(
        new MarkerOptions().position(new LatLng(10, 10)).title("Marker z1").zIndex(1.0f));

כדי לגשת ל-z-index של הסמן, אפשר להפעיל את Marker.getZIndex(), וכדי לשנות אותו אפשר להפעיל את Marker.setZIndex().

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

מידע על ההשפעה של z-index על אירועים מסוג קליק

טיפול באירועים של סמנים

‫Maps API מאפשר לכם להאזין לאירועי סמנים ולהגיב להם. כדי להאזין לאירועים האלה, צריך להגדיר את ה-listener המתאים באובייקט GoogleMap שאליו שייכים הסמנים. כשהאירוע מתרחש באחד מהסמנים במפה, הקריאה החוזרת של המאזין תופעל עם האובייקט Marker המתאים שמועבר כפרמטר. כדי להשוות בין האובייקט Marker הזה לבין ההפניה שלכם לאובייקט Marker, צריך להשתמש ב-equals() ולא ב-==.

אפשר להאזין לאירועים הבאים:

אירועים מסוג קליק על סמן

אפשר להשתמש ב-OnMarkerClickListener כדי להאזין לאירועים מסוג קליק על הסמן. כדי להגדיר את המאזין הזה במפה, צריך להפעיל את GoogleMap.setOnMarkerClickListener(OnMarkerClickListener). כשמשתמש לוחץ על סמן, הפונקציה onMarkerClick(Marker) נקראת והסמן מועבר כארגומנט. השיטה הזו מחזירה ערך בוליאני שמציין אם השתמשתם באירוע (כלומר, אתם רוצים לבטל את פעולת ברירת המחדל). אם הפונקציה מחזירה false, פעולת ברירת המחדל תתבצע בנוסף לפעולה בהתאמה אישית. פעולת ברירת המחדל של אירוע מסוג קליק על סמן היא להציג את חלון המידע שלו (אם הוא זמין) ולהזיז את המצלמה כך שהסמן יהיה במרכז המפה.

ההשפעה של z-index על אירועים מסוג קליק:

  • כשמשתמש לוחץ על אשכול של סמנים, אירוע מסוג קליק מופעל בסמן עם ערך ה-z-index הגבוה ביותר.
  • כל קליק מפעיל אירוע אחד לכל היותר. במילים אחרות, הקליק לא מועבר לסמנים או לשכבות-על אחרות עם ערכי z-index נמוכים יותר.
  • אם לוחצים על אשכול של סמנים, הקליקים הבאים יעברו בין הסמנים באשכול ויבחרו כל אחד מהם בתורו. סדר המחזור נותן עדיפות קודם כל ל-z-index, ואז לקרבה לנקודת הלחיצה.
  • אם המשתמש לוחץ מחוץ לאזור של האשכול, ה-API מחשב מחדש את האשכול ומאפס את מצב מחזור הקליקים כך שהוא מתחיל מההתחלה.
  • סמנים נחשבים כקבוצת z-index נפרדת בהשוואה לשכבות-על או לצורות אחרות (קווים פוליגוניים, פוליגונים, עיגולים ו/או שכבות-על של הקרקע), ללא קשר ל-z-index של שכבות-העל האחרות. אם כמה סמנים, שכבות-על או צורות מונחים זה על גבי זה, אירוע הקליק עובר קודם כל דרך אשכול הסמנים.

אירועי גרירה של סמנים

אפשר להשתמש ב-OnMarkerDragListener כדי להאזין לאירועי גרירה בסמן. כדי להגדיר את המאזין הזה במפה, צריך להפעיל את GoogleMap.setOnMarkerDragListener. כדי לגרור סמן, המשתמש צריך ללחוץ עליו לחיצה ארוכה. כשהמשתמש מסיר את האצבע מהמסך, הסמן נשאר במיקום הזה. כשגוררים סמן, onMarkerDragStart(Marker) נקרא בהתחלה. בזמן שגוררים את הסמן, מתבצעת קריאה קבועה ל-onMarkerDrag(Marker). בסיום הגרירה, מתבצעת קריאה ל-onMarkerDragEnd(Marker). אפשר לקבל את המיקום של הסמן בכל שלב על ידי קריאה ל-Marker.getPosition().