דף זה תורגם על ידי Cloud Translation API.

מהי Places UI Kit ואיך אפשר להשתמש בה כדי ליצור פתרונות מעניינים?

מבוא

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

ערכת ה-UI של Places היא ספריית רכיבים מוכנה לשימוש וחסכונית, והיא מבוססת על המידע הנרחב של מפות Google על מקומות. היא מאפשרת לכם לשלב את חוויית השימוש המוכרת והאמינה של Google Places בתרחישי השימוש שלכם ב-front-end במפה שתבחרו.

רכיבים

ערכת ה-UI של Places כוללת קבוצה של רכיבי UI נפרדים שאפשר להשתמש בהם בנפרד או ביחד כדי ליצור חוויה חלקה של Places.

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

היתרונות העיקריים של Places UI Kit

קלות השימוש: אפשר לשלב באפליקציות את חוויית המשתמש המהימנה של Google Places עם מינימום קוד.
שימוש בכל מפה: בפעם הראשונה, אפשר להשתמש בתוכן של 'מקומות' במפה שאינה של Google.
ממשק משתמש מוכר: הרכיבים מספקים ממשק משתמש שתואם לחוויית השימוש במפות Google, ולכן הוא אינטואיטיבי למשתמשים.
התאמה אישית: ערכת ה-UI של Places מציעה אפשרויות רבות להתאמה אישית של המראה, ללא תשלום נוסף. אפשר להשתמש במגוון הגדרות ובמאפייני CSS מותאמים אישית כדי להגדיר את רכיבי התצוגה.
פתרון במחיר משתלם: שימוש ב-Places UI Kit יכול להיות פתרון משתלם יותר בהשוואה לשימוש ישיר ב-Places API.

תרחישים לדוגמה בעולם האמיתי

אפשר להשתמש בערכת ה-UI של Places במגוון אפליקציות כדי לשפר את חוויית המשתמש.

אפליקציות לחיפוש מקומי: אפליקציה עם רשימה של "דברים לעשות" יכולה להשתמש ברכיב Place Search כדי להציג רשימה של מסעדות, בתי קפה או אטרקציות בקרבת מקום. כשמשתמש בוחר מקום מהרשימה, אפשר להשתמש ברכיב Place Details (פרטי מקום) כדי להציג מידע נוסף על המיקום הזה.
אפליקציות לתכנון נסיעות: אפליקציה לתכנון נסיעות יכולה להשתמש בחיפוש מקומות כדי לאפשר למשתמשים לחפש בתי מלון או נקודות עניין בעיר ספציפית. רכיב פרטי המקום יכול להציג תמונות, דירוגים וביקורות של כל מיקום כדי לעזור בתכנון.
פורטלים לחיפוש נדל"ן ונכסים: אפליקציית נדל"ן יכולה להשתמש ברכיב 'חיפוש מקומות' כדי להציג קטגוריות שונות של מקומות בקרבת מקום, וכך לעזור לרוכשי בתים או לשוכרי דירות פוטנציאליים להבין אם אורח החיים בשכונה מתאים להם לפני שהם מתאמים ביקור בנכס.
אפליקציות של הודעות ורשתות חברתיות: אפליקציה של הודעות ורשת חברתית יכולה להשתמש בחיפוש מקומות כדי לחפש ולהציע מקומות בקרבת מקום, וכך לעזור למשתמשים למצוא בקלות מקום למפגש. רכיב פרטי המקום יכול לשמש להצגת מידע מפורט על מקומות כשמשתמשים משתפים מקומות. באמצעות הלחצן המובנה של מפות Google, המשתמשים יכולים לחקור בקלות ובדייקנות מיקומים נוספים ומידע על נסיעות במפות Google.

התאמה אישית

אפשר להתאים אישית את העיצוב של רכיבי ערכת ה-UI של 'מקומות' כך שיתאימו לצרכים שלכם.

שימוש במאפייני CSS בהתאמה אישית, למשל מאפייני ה-CSS של רכיב פרטי המקום, מאפשר לכם להתאים את המראה והתחושה של הרכיבים כך שיתאימו לעיצוב של האפליקציה. אתם יכולים להתאים אישית את הצבעים, הגופנים ואלמנטים חזותיים אחרים. חשוב להקפיד על דרישות השיוך כשמבצעים שינויים חזותיים. לדוגמה, אפשר לשנות את הצבע הראשי שמשמש לקישורים ולמספר הביקורות באמצעות מאפיין ה-CSS‏ --gmp-mat-color-primary.

אתם יכולים לשלוט בתוכן הספציפי של המקום שמוצג באמצעות רכיב gmp-place-content-config מוטמע כדי לבחור ולהגדיר את התוכן, או פשוט להשתמש ב-gmp-place-all-content כדי להציג את כל התוכן הזמין.

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

הדרכה בנושא הטמעה

ערכת ה-UI של Places זמינה דרך Maps JavaScript ו-Places SDK ל-Android ול-iOS.

תחילת העבודה

כדי להתחיל להשתמש בערכת ה-UI של Places, צריך לבצע את השלבים הבאים:

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

לפרטים נוספים שספציפיים לפלטפורמה, אפשר לעיין בהנחיות לתחילת העבודה עם ערכת ה-UI של Places ל-JavaScript, ל-Android ול-iOS.

דוגמה להטמעה

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

בהמשך מופיעים קטעי הקוד. הדמו והקוד המלא זמינים במאגר GitHub הזה.

לפני שמתחילים, חשוב לוודא שביצעתם את השלבים שלמעלה בקטע 'תחילת העבודה' שרלוונטיים ל-JavaScript.

טוענים את הספריות הנדרשות ב-HTML.

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

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

<div id="map-container"></div>
<div class="controls">
    <input type="text" class="query-input" />
    <button class="search-button">Search</button>
</div>

מוסיפים את הרכיב Place Search. רכיב חיפוש המקומות מספק פריסות אופקיות ואנכיות. בדוגמה הזו אנחנו משתמשים בפריסה אופקית. המאפיין selectable מאפשר ללחוץ על פריט ברשימת תוצאות החיפוש (האירוע gmp-select יופעל בלחיצה).

בתוך הרכיב gmp-place-search, מוסיפים שני רכיבי צאצא:

האפליקציה gmp-place-all-content משמשת להצגת כל התוכן שזמין
המאפיין gmp-place-text-search-request משמש להגדרת הרכיב Place Search.

בדוגמה הזו נגדיר את ההגדרה ב-JavaScript

<div class="list-container">
    <gmp-place-search orientation="horizontal" selectable>
         <gmp-place-all-content></gmp-place-all-content>  
         <gmp-place-text-search-request></gmp-place-text-search-request>
    </gmp-place-search>
</div>

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

‫gmp-place-all-content מציין הצגה של כל התוכן הזמין
משתמשים ב-gmp-place-details-place-request כדי לבחור מקום.

בדוגמה הזו נגדיר את המקום ב-JavaScript

<div id="details-container">
     <gmp-place-details-compact orientation="horizontal">
        <gmp-place-details-place-request></gmp-place-details-place-request> 
        <gmp-place-all-content></gmp-place-all-content>
    </gmp-place-details-compact> 
</div>

ב-JavaScript, מייבאים את הספריות שצריך בשביל הדוגמה הזו. ספריית המקומות מייבאת את ספריית Places UI Kit ל-JavaScript.

const {Map} = await google.maps.importLibrary("maps");
await google.maps.importLibrary("places");
({AdvancedMarkerElement} = await google.maps.importLibrary("marker"));
({LatLngBounds, LatLng} = await google.maps.importLibrary("core"));

יצירת מפות דינמיות.

const mapContainer = document.getElementById("map-container");
const mapOptions = {
    center: {lat: 37.422, lng: -122.085},
    zoom: 12 
};
const gMap = new Map(mapContainer, mapOptions);

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

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

const queryInput = document.querySelector(".query-input");
const searchButton = document.querySelector(".search-button");
const placeSearch = document.querySelector("gmp-place-search");
const placeSearchQuery = document.querySelector("gmp-place-text-search-request");
const placeDetails = document.querySelector("gmp-place-details-compact");
const placeRequest = document.querySelector("gmp-place-details-place-request");

placeDetailsPopup = new AdvancedMarkerElement({
    map: null,
    content: placeDetails,
    zIndex: 1
});

searchButton.addEventListener("click", searchPlaces);

function searchPlaces(){    
    if (queryInput.value.trim()) {
        placeSearchQuery.textQuery = queryInput.value.trim();
        placeSearchQuery.locationBias = gMap.getBounds();
        placeSearch.addEventListener('gmp-load', addMarkers, { once: true });
    }
}

async function addMarkers(){
    const bounds = new LatLngBounds();
    placeSearch.places.forEach((place) => {
        let marker = new AdvancedMarkerElement({
            map: gMap,
            position: place.location
        });
        bounds.extend(place.location);
        marker.addListener('click',(event) => {
            placeRequest.place = place;
            placeDetails.style.display = 'block';
            placeDetailsPopup.position = place.location;
            placeDetailsPopup.map = gMap;
            gMap.fitBounds(place.viewport, {top: 200, left: 100});
        });
        gMap.setCenter(bounds.getCenter());
        gMap.fitBounds(bounds);
    });
}

מומלץ לעיין בהדמו ובקוד המלא במאגר GitHub הזה.

מקורות מידע שיעזרו לכם ליצור

תורמים

מחברים ראשיים:

Teresa Qin | Google Maps Platform Solutions Engineer

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