סמנים

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

דוגמאות קוד

המאגר ApiDemos ב-GitHub כולל דוגמה שממחישה תכונות שונות של סמנים:

Kotlin

• MapWithMarker: מפה פשוטה עם סמן. תוכלו לעיין במדריך בנושא הוספת מפה עם marker-kt.
• MarkerDemoActivity: שימוש בסמנים במפה, כולל אפשרויות ומאזינים

Java

• MapWithMarker: מפה פשוטה עם סמן. כדאי לעיין במדריך בנושא הוספת מפה עם סמן.
• MarkerDemoActivity: שימוש בסמנים במפה, כולל אפשרויות ומאזינים

מבוא

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

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

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

תחילת העבודה עם סמנים

בפרק הזה של Maps Live נסביר את העקרונות הבסיסיים להוספת סמנים למפה באמצעות ה-SDK של מפות Google ל-Android.

הוסף סמן

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

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

      

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

      

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

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

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

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

/**
 * A demo class that stores and retrieves data objects with each marker.
 */
class MarkerDemoActivity : AppCompatActivity(),
    OnMarkerClickListener, OnMapReadyCallback {
    private val PERTH = LatLng(-31.952854, 115.857342)
    private val SYDNEY = LatLng(-33.87365, 151.20689)
    private val BRISBANE = LatLng(-27.47093, 153.0235)

    private var markerPerth: Marker? = null
    private var markerSydney: Marker? = null
    private var markerBrisbane: Marker? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_markers)
        val mapFragment =
            supportFragmentManager.findFragmentById(R.id.map) as SupportMapFragment?
        mapFragment!!.getMapAsync(this)
    }

    /** Called when the map is ready.  */
    override fun onMapReady(map: GoogleMap) {
        // Add some markers to the map, and add a data object to each marker.
        markerPerth = map.addMarker(
            MarkerOptions()
                .position(PERTH)
                .title("Perth")
        )
        markerPerth?.tag = 0
        markerSydney = map.addMarker(
            MarkerOptions()
                .position(SYDNEY)
                .title("Sydney")
        )
        markerSydney?.tag = 0
        markerBrisbane = map.addMarker(
            MarkerOptions()
                .position(BRISBANE)
                .title("Brisbane")
        )
        markerBrisbane?.tag = 0

        // Set a listener for marker click.
        map.setOnMarkerClickListener(this)
    }

    /** Called when the user clicks a marker.  */
    override fun onMarkerClick(marker: Marker): Boolean {

        // 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(
                this,
                "${marker.title} has been clicked $newClickCount times.",
                Toast.LENGTH_SHORT
            ).show()
        }

        // Return false to indicate that we have not consumed the event and that we wish
        // for the default behavior to occur (which is for the camera to move such that the
        // marker is centered and for the marker's info window to open, if it has one).
        return false
    }
}

      

/**
 * A demo class that stores and retrieves data objects with each marker.
 */
public class MarkerDemoActivity extends AppCompatActivity implements
    GoogleMap.OnMarkerClickListener,
    OnMapReadyCallback {

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

    private Marker markerPerth;
    private Marker markerSydney;
    private Marker markerBrisbane;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_markers);
        SupportMapFragment mapFragment =
            (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /** Called when the map is ready. */
    @Override
    public void onMapReady(GoogleMap map) {
        // Add some markers to the map, and add a data object to each marker.
        markerPerth = map.addMarker(new MarkerOptions()
            .position(PERTH)
            .title("Perth"));
        markerPerth.setTag(0);

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

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

        // Set a listener for marker click.
        map.setOnMarkerClickListener(this);
    }

    /** Called when the user clicks a marker. */
    @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(this,
                marker.getTitle() +
                    " has been clicked " + clickCount + " times.",
                Toast.LENGTH_SHORT).show();
        }

        // Return false to indicate that we have not consumed the event and that we wish
        // for the default behavior to occur (which is for the camera to move such that the
        // marker is centered and for the marker's info window to open, if it has one).
        return false;
    }
}

      

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

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

איך הופכים סמן לניתן לגרירה

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

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

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

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

      

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.

כיוון אופקי או כיוון של מודעה על לוח

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

סיבוב

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

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

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

      

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 שמייצג נקודות בגלגל הצבעים.

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

      

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(). צריך לציין את הערך של אלפא כערך של float בין 0.0 ל-1.0, כאשר 0 הוא שקיפות מלאה ו-1 הוא אטימות מלאה.

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

      

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.

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

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))
)

      

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.

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

      

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 גורמת לסמן להסתובב סביב מרכזו, במקום סביב הבסיס שלו.

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

      

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 מציין את סדר העריכה של הסמן הזה ביחס לסימנים אחרים במפה. סמן עם ערך z-index גבוה מצויר מעל סמנים עם ערכי z-index נמוכים יותר. ערך ברירת המחדל של z-index הוא 0.

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

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

      

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

      

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

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

בהמשך מוסבר על ההשפעה של z-index על אירועי קליקים.

טיפול באירועי סמן

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

אתם יכולים להאזין לאירועים הבאים:

• אירועי קליק על סמנים
• אירועי גרירה של סמנים
• אירועי קליקים בחלון המידע

אירועי קליקים על סמנים

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

השפעת הערך של z-index על אירועי קליקים:

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

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

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