גילוי מקומות באמצעות PlaceSearchElement

מטרה

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

מה זה PlaceSearchElement?

‫PlaceSearchElement הוא חלק מ-Places UI Kit ב-Maps JavaScript API. זהו רכיב HTML שמציג את התוצאות של חיפוש מקומות ישירות בפורמט של רשימה באפליקציה. הרכיב הזה מפשט את התהליך של הצגת מקומות שנמצאו באמצעות חיפוש בסביבה או חיפוש טקסט, ומספק חוויית משתמש חלקה לגילוי מקומות. כשמשתמש בוחר מקום מהרשימה, אפשר להציג את הפרטים שלו במפה, בדרך כלל באמצעות חלון מידע ורכיב Place Details.

המחשה של גילוי מקומות

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

תרחישים לדוגמה לחיפוש מקומות

שילוב של PlaceSearchElement יכול לשפר אפליקציות שונות בתעשיות שונות:

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

תהליך עבודה לפתרון: הטמעת Place Discovery

בקטע הזה נסביר איך לשלב את PlaceSearchElement כדי למצוא מקומות במפה, ונספק קטעי קוד לאינטראקציה עם Places UI Kit. איך מפעילים את המפה ומטמיעים את התכונות "חיפוש בסביבה" ו"חיפוש טקסט". לבסוף, משתמשים ברכיב Place Details כדי להציג פרטים נוספים על מקום מסוים כשהמשתמש לוחץ על הסיכה שלו במפה.

דרישות מוקדמות

מומלץ להכיר את המאמרים הבאים:

• PlaceSearchElement - משמש לחשיפת מקומות באמצעות חיפוש בסביבה או חיפוש טקסט
• רכיב פרטי המקום - משמש להצגת פרטים של מקום ספציפי
• ‫Maps JavaScript API – משמש להצגת מפה בדף ולייבוא Places UI Kit

מפעילים בפרויקט את Maps JavaScript API ואת Places UI Kit.

לפני שמתחילים, חשוב לוודא שטענתם את Maps JavaScript API וייבאתם את הספריות הנדרשות. הנחת המוצא במסמך הזה היא שיש לכם ידע מעשי בפיתוח אתרים, כולל HTML,‏ CSS ו-JavaScript.

הוספת מפה לדף

השלב הראשון הוא להוסיף מפה לדף. המפה הזו תשמש להצגת תוצאות של PlaceSearchElement כסיכות שאפשר לבחור.

יש שתי דרכים להוסיף מפה לדף:

1. שימוש בgmp-map רכיב אינטרנט ב-HTML.
2. באמצעות JavaScript.

קטעי הקוד בדף הזה נוצרו באמצעות מפה ב-JavaScript.

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

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

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

הגדרת PlaceSearchElement

עכשיו מגדירים את ה-HTML וה-CSS כדי להציג את PlaceSearchElement. בדוגמה הזו הרכיב צף מעל הצד השמאלי של המפה, אבל אתם יכולים לנסות פריסות שונות שמתאימות לאפליקציה שלכם.

ב-PlaceSearchElement משתמשים בגישת חיווי. במקום להגדיר אותו לגמרי ב-JavaScript, אתם מגדירים את סוג החיפוש ישירות ב-HTML על ידי הטמעה של רכיב בקשה, כמו <gmp-place-nearby-search-request>, בתוך הרכיב הראשי <gmp-place-search>.

בקוד ה-HTML, מפעילים רכיב <gmp-place-search>. כדי להפעיל אירועים מסוג קליק בתוצאות, משתמשים במאפיין selectable. בתוכו, מוסיפים <gmp-place-nearby-search-request> כדי לציין שהרכיב הזה ישמש לחיפוש בסביבה.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

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

קטע הקוד של הפעולה הזו נראה כך:

// Get references to the Place Search and its nested request element
const placeSearchElement = document.querySelector("gmp-place-search");
const placeSearchRequestElement = document.querySelector("gmp-place-nearby-search-request");

// Define the location restriction for the search
const circleRestriction = new Circle({
    center: marker.position,
    radius: 500
});

// Set the properties on the request element to perform an initial search for restaurants.
placeSearchRequestElement.locationRestriction = circleRestriction;
placeSearchRequestElement.includedPrimaryTypes = ['restaurant'];

כך יכולה להיראות האפליקציה בשלב הזה:

המשתמשים יכולים לחפש

בPlaceSearchElement יש שתי אפשרויות חיפוש:

• ‫<gmp-place-nearby-search-request> – עיבוד של תוצאות החיפוש מחיפוש בסביבה של מקומות, באמצעות סוגי מקומות.
• <gmp-place-text-search-request> – הצגת תוצאות חיפוש מחיפוש טקסט של מקומות, באמצעות קלט טקסט חופשי כמו "סושי בתל אביב".

אלה רכיבים שמוצבים בתוך <gmp-place-search>. לאחר מכן, מפעילים חיפושים על ידי הגדרת מאפיינים ברכיב הבקשה המקונן באמצעות JavaScript.

בקטע הזה מוסבר איך להטמיע את שתי השיטות.

חיפוש בסביבה

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

מומלץ לבחור קבוצת משנה של סוגים שרלוונטיים לתרחיש לדוגמה שלכם. לדוגמה, אם אתם מפתחים אפליקציה שמציגה לתיירים מה נמצא בקרבת המלון, תוכלו לבחור את הממשקים הבאים: bakery,‏ coffee_shop,‏ museum,‏ restaurant ו-tourist_attraction.

קובץ ה-HTML צריך להכיל את הרכיב <gmp-place-search> עם <gmp-place-nearby-search-request> מקונן בתוכו.

<gmp-place-search selectable>
  <gmp-place-nearby-search-request>
  </gmp-place-nearby-search-request>
</gmp-place-search>

בשלב הבא, יוצרים מאזין JavaScript לאירוע change בבורר סוגי המקומות. המאזין הזה יפעיל פונקציה שמעדכנת את המאפיינים של הרכיב <gmp-place-nearby-search-request>, מה שמפעיל באופן אוטומטי חיפוש חדש ומעדכן את הרשימה.

// Get a reference to the nested request element
const placeSearchRequestElement = document.querySelector('gmp-place-nearby-search-request');

// Function to update the place search based on the selected type
function updatePlaceList() {
    const selectedType = placeTypeSelect.value;
    if (!selectedType) {
        // If no type is selected, don't perform a search.
        // You could optionally hide the list or clear previous results here.
        placeSearchElement.style.display = 'none';
        return;
    }
    placeSearchElement.style.display = 'block';

    // Set properties on the request element to trigger a new search
    placeSearchRequestElement.locationRestriction = searchCircle;
    placeSearchRequestElement.maxResultCount = 8;
    placeSearchRequestElement.includedPrimaryTypes = [selectedType];
}

אותו searchCircle משלב ההגדרה משמש ל-locationRestriction. המאפיין includedPrimaryTypes מוגדר לערך שהמשתמש בחר. השדה האופציונלי maxResultCount מוגדר גם כדי להגביל את מספר התוצאות.

חיפוש טקסט

כדי להפעיל חיפוש טקסט, צריך לשנות את הגדרת ה-HTML. במקום בקשת החיפוש בסביבה, אתם מוסיפים רכיב <gmp-place-text-search-request>.

<gmp-place-search selectable>
  <gmp-place-text-search-request>
  </gmp-place-text-search-request>
</gmp-place-search>

מוסיפים לממשק המשתמש שדה להזנת טקסט וכפתור חיפוש. יוצרים מאזין JavaScript לאירוע click של הלחצן. הגורם המטפל באירועים יקבל את הקלט של המשתמש ויעדכן את המאפיינים של הרכיב <gmp-place-text-search-request> כדי לבצע את החיפוש.

// Get a reference to the text search request element
const placeTextSearchRequestElement = document.querySelector('gmp-place-text-search-request');
const textSearchInput = document.getElementById('textSearchInput');
const textSearchButton = document.getElementById('textSearchButton');

textSearchButton.addEventListener('click', performTextSearch);

function performTextSearch() {
    const query = textSearchInput.value.trim();
    if (!query) {
        console.log("Search query is empty.");
        return;
    }
    // Set properties on the request element to trigger a new search
    placeTextSearchRequestElement.textQuery = query;
    placeTextSearchRequestElement.locationBias = map.getBounds();
    placeTextSearchRequestElement.maxResultCount = 8;
}

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

הצגת סיכות ופרטים של מקומות

עכשיו האפליקציה יכולה לבצע חיפוש מקומות ולאכלס את הרכיב. בשלב הבא נשפר את הפונקציונליות שלו:

• הצגת סיכות במפה לכל מקום שמאוכלס ב-PlaceSearchElement.
• לאפשר למשתמש ללחוץ על סיכה או על המקום ב-PlaceSearchElement כדי להציג פרטים נוספים על המקום הספציפי הזה.

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

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

let markers = {};

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

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

כדי להאזין לזמינות של תוצאות החיפוש, מוסיפים רכיב event listener מסוג gmp-load לרכיב <gmp-place-search>. האירוע הזה מופעל אחרי שהחיפוש מסתיים והתוצאות מוצגות.

נוסיף את המאזין בתוך פונקציית החיפוש (למשל, updatePlaceList), ונשתמש באפשרות { once: true } כדי לוודא שהוא מופעל רק עבור התוצאות של החיפוש הנוכחי.

// In your search function, after setting the request properties:
placeSearchElement.addEventListener('gmp-load', addMarkers, { once: true });

הפונקציה addMarkers נראית כך:

async function addMarkers() {
    const { LatLngBounds } = await google.maps.importLibrary("core");
    const bounds = new LatLngBounds();

    if (placeSearchElement.places.length > 0) {
        // Remove existing markers
        for (const m in markers) {
            markers[m].map = null;
        }
        markers = {};

        // Loop through each place from the search results
        // and add a marker for each one.
        for (const place of placeSearchElement.places) {
            const marker = new google.maps.marker.AdvancedMarkerElement({
                map: map,
                position: place.location,
            });

            markers[place.id] = marker;
            bounds.extend(place.location);
            marker.collisionBehavior = google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;

            // Add a click listener for each marker.
            marker.addListener('gmp-click', (event) => {
                // The main logic for showing details will go here.
            });
        }
        // Position the map to display all markers.
        map.setCenter(bounds.getCenter());
        map.fitBounds(bounds);
    }
}

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

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

מוסיפים לקוד את ה-HTML של הרכיב הקומפקטי של פרטי המקום, לדוגמה:

<gmp-place-details-compact orientation="vertical" style="display: none;">
    <gmp-place-all-content></gmp-place-all-content>
    <gmp-place-attribution light-scheme-color="gray" dark-scheme-color="white"></gmp-place-attribution>
</gmp-place-details-compact>

השדה style מוגדר כ-display: none, והוא לא יוצג עד שיהיה בו צורך. הערך gmp-place-all-content מועבר כדי לעבד את כל תוכן הרכיב. כדי לבחור איזה תוכן להציג, עיינו במסמכי התיעוד של רכיב Place Details Compact.

יוצרים משתנה גלובלי ב-JavaScript שיכיל הפניה לרכיב הקומפקטי של פרטי המקום, ומאכלסים אותו בקוד האתחול, לדוגמה:

let placeDetailsElement;
...
placeDetailsElement = document.querySelector('gmp-place-details-compact');

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

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

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

async function addMarkers() {
          ...
            marker.addListener('gmp-click', (event) => {
                //Set up Place Details Compact Widget
                placeDetailsElement.style.display = "block";
                // Remove any existing place request element
                const existingPlaceRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
                if (existingPlaceRequest) {
                    existingPlaceRequest.remove();
                }
                // Create and configure the new place request element
                const placeRequestElement = new google.maps.places.PlaceDetailsPlaceRequestElement({ place: place.id });
                // Prepend the new place request element to the main widget
                placeDetailsElement.prepend(placeRequestElement);
                if (infoWindow.isOpen) {
                    infoWindow.close();
                }
                infoWindow.setOptions({
                    content: placeDetailsElement
                });
                infoWindow.open({
                    anchor: marker,
                    map: map
                });
                // Position the map to show the selected place
                placeDetailsElement.addEventListener('gmp-load', () => {
                    map.fitBounds(place.viewport, { top: 500, left: 400 });
                });
            });
          ...
        });
    }
}

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

placeSearchElement.addEventListener("gmp-select", ({ place }) => {
    if (markers[place.id]) {
        markers[place.id].click();
    }
});

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

האפליקציה תיראה כך:

סיכום

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

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

תורמים

הנריק ואלווה | מהנדס DevX