איך משתמשים קיימים ב-Places API יכולים להשתמש ב-Places UI Kit

כאן מוסבר איך להעביר את ההטמעה הקיימת של Places API או של Place Class לרכיבים של Places UI Kit.

למי מיועד מדריך זה

המדריך הזה מיועד למפתחים שיש להם הטמעה קיימת באמצעות Places API ורוצים לעדכן את הקוד שלהם כדי להשתמש ב-Places UI Kit. הכי מומלץ להשתמש בפתרון הזה אם אתם כבר:

  • שליחת בקשות HTTP לנקודות קצה (endpoints) של Places API (חדש או מדור קודם).
  • שימוש במחלקת המקומות ב-Maps JavaScript API.
  • טיפול בתגובת ה-API כדי להציג מידע על מקומות בממשק המשתמש של אפליקציית האינטרנט.

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

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

עדכון הטעינה של Maps JavaScript API

כדי להשתמש ב-Places UI Kit, צריך להשתמש בשיטה Dynamic Library Import לטעינת Maps JavaScript API. אם אתם משתמשים בתג לטעינה ישירה של סקריפט, אתם צריכים לעדכן אותו.

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

הטמעה של רכיב פרטי המקום

‫Place Details Element ו-Place Details Compact Element הם רכיבי HTML שמציגים פרטים של מקום.

ההטמעה הנוכחית

  • מבצעים קריאה של Place Details באמצעות בקשת HTTP, או משתמשים ב-Place Class של JavaScript API.
  • מנתחים את התגובה של ה-API ומציגים את פרטי המקום באמצעות HTML ו-CSS.

העברה לרכיב Place Details

שינוי מבנה ה-HTML

מזהים את קונטיינר ה-HTML שבו מוצגים פרטי המקום. מחליפים את רכיבי ה-HTML המותאמים אישית (div,‏ span לשם, לכתובת, לתמונות וכו') ב-HTML של רכיב פרטי המקום.

יש שני אלמנטים שאפשר לבחור מביניהם:

  • Place Details Compact Element
  • רכיב Place Details

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

קוד ה-HTML הקיים שלכם יכול להיראות כך.

<div id="my-place-details-container">
    <h2 id="place-name"></h2>
    <p id="place-address"></p>
    <img id="place-photo" src="" alt="Place photo">
    <!-- ... more custom elements -->
</div>

דוגמה ל-HTML חדש, עם ציון מפורש של התוכן שיוצג:

<gmp-place-details-compact orientation="horizontal" truncation-preferred style="display: none;">
    <gmp-place-details-place-request></gmp-place-details-place-request>
    <gmp-place-content-config>
        <gmp-place-media lightbox-preferred></gmp-place-media>
        <gmp-place-address></gmp-place-address>
        <gmp-place-rating></gmp-place-rating>
        <gmp-place-type></gmp-place-type>
        <gmp-place-price></gmp-place-price>
        <gmp-place-accessible-entrance-icon></gmp-place-accessible-entrance-icon>
        <gmp-place-open-now-status></gmp-place-open-now-status>
    </gmp-place-content-config>
</gmp-place-details-compact>

התאמת הלוגיקה של JavaScript

לוגיקה קיימת

הלוגיקה הקיימת שלכם כנראה כוללת:

  • אחזור מזהה מקום.
  • שימוש ב-PlacesService().getDetails() או ביצוע קריאה לשירות אינטרנט.
  • ציון מערך שדות (ל-JS API) או FieldMask (לשירות אינטרנט) כדי לבקש נתונים ספציפיים.
  • בפתרון של הקריאה החוזרת, בוחרים ידנית את רכיבי ה-HTML ומאכלסים אותם בנתונים שהתקבלו.

הדוגמה הבאה ממחישה איך יכול להיות שהטמעתם את Place Details:

async function getPlaceDetails(placeId) {
    const { Place } = await google.maps.importLibrary('places');
    // Use place ID to create a new Place instance.
    const place = new Place({
        id: placeId
    });
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    // Log the result
    console.log(place.displayName);
    console.log(place.formattedAddress);
}
לוגיקה חדשה

הלוגיקה החדשה תכלול:

  • אחזור מזהה המקום או אובייקט המקום.
  • קבלת הפניה לרכיב <gmp-place-details-place-request>.
  • מעבירים את מזהה המקום או את אובייקט המקום למאפיין place ברכיב <gmp-place-details-place-request>.

בדוגמה הבאה אפשר לראות איך מטמיעים את ערכת ה-UI של פרטי מקום בלוגיקה של JavaScript. קבלת הפניה לרכיב Place Details. אם הוא קיים, מקבלים הפניה לרכיב Place Details Place Request ומגדירים את מאפיין המקום באמצעות מזהה מקום. בדוגמה של קוד ה-HTML שלמעלה, הסגנון של רכיב פרטי המקום מוגדר כ-display: none. הערך הזה עודכן ל-display: block.

function displayPlaceDetailsWithUIKit(placeId) {
  const placeDetailsElement = document.querySelector('gmp-place-details-compact');
  if (placeDetailsElement) {
    const placeDetailsRequest = document.querySelector('gmp-place-details-place-request');
    // Configure the element with the Place ID
    placeDetailsRequest.place = placeId
    placeDetailsElement.style.display = 'block';
    console.log("PlaceDetailsElement configured for place:", placeId);
  } else {
    console.error("PlaceDetailsElement not found in the DOM.");
  }
}

// Example usage:
const placeId = 'ChIJC8HakaIRkFQRiOgkgdHmqkk';
displayPlaceDetailsWithUIKit(placeId);

רכיב חיפוש המקומות הוא רכיב HTML שמציג את תוצאות החיפוש של מקום ברשימה.

  • מבצעים חיפוש טקסט או חיפוש בסביבה באמצעות בקשת HTTP, או משתמשים ב-Place Class של JavaScript API.
  • אתם מציינים פרמטרים של שאילתות, הגבלות או הטיה של מיקום, סוגים ושדות מבוקשים באמצעות FieldMask.
  • מנתחים את התגובה של ה-API, חוזרים על הפעולה במערך המקומות ויוצרים באופן ידני פריטים ברשימת HTML.

שינוי מבנה ה-HTML

מזהים את מאגר ה-HTML שבו מוצגת רשימת המקומות. מחליפים את רכיבי ה-HTML המותאמים אישית (div, span לשם, לכתובת וכו') ברכיב ה-HTML של רכיב חיפוש המקומות.

קוד ה-HTML הקיים שלכם עשוי להיראות כך:

<div id="search-results-area">
    <h3>Nearby Places:</h3>
    <ul id="manual-places-list">
        <!-- JavaScript would dynamically insert list items here -->
        <!-- Example of what JS might generate:
    <li class="place-entry" data-place-id="SOME_PLACE_ID_1">
      <img class="place-icon" src="icon_url_1.png" alt="Icon">
      <span class="place-name">Place Name One</span> -
      <span class="place-vicinity">123 Main St</span>
    </li>
    <li class="place-entry" data-place-id="SOME_PLACE_ID_2">
      <img class="place-icon" src="icon_url_2.png" alt="Icon">
      <span class="place-name">Place Name Two</span> -
      <span class="place-vicinity">456 Oak Ave</span>
    </li>
    -->
        <li class="loading-message">Loading places...</li>
    </ul>
</div>

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

  • <gmp-place-text-search-request> לחיפוש טקסט.
  • <gmp-place-nearby-search-request> לחיפוש בסביבה.

כדי להגדיר איך התוצאות יוצגו, אפשר להשתמש ב<gmp-place-all-content>קיצור הדרך או לספק קבוצה משלכם של רכיבי הצגה נפרדים. אפשר להגדיר מאפייני מפתח כמו selectable (כדי לאפשר קליקים על פריטים ברשימה) ו-orientation (לפריסה אופקית או אנכית) ישירות ברכיב ההורה.

דוגמה לחיפוש בסביבה
<gmp-place-search orientation="horizontal" selectable>
    <gmp-place-all-content> </gmp-place-all-content>
    <gmp-place-nearby-search-request></gmp-place-nearby-search-request>
</gmp-place-search>
דוגמה לחיפוש טקסט
<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>

התאמת הלוגיקה של JavaScript

ב-JavaScript, מקבלים הפניה לרכיב של בקר החיפוש באמצעות document.querySelector(). בהתאם להגדרה, זה יהיה רכיב <gmp-place-text-search-request> או <gmp-place-nearby-search-request>.

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

בחיפוש טקסט (<gmp-place-text-search-request>), המאפיין הראשי הוא textQuery:

const textSearchController = document.querySelector('gmp-place-text-search-request');
textSearchController.textQuery = 'museums in London';

כדי לבצע חיפוש בסביבה (<gmp-place-nearby-search-request>), צריך להגדיר את אזור החיפוש באמצעות locationRestriction. אחר כך תוכלו להשתמש ב-includedTypes כדי לסנן לפי סוגים ספציפיים של מקומות באזור הזה:

const nearbySearchController = document.querySelector('gmp-place-nearby-search-request');
nearbySearchController.locationRestriction = new google.maps.Circle({
    center: { lat: 51.5190, lng: -0.1347 },
    radius: 1000
});
nearbySearchController.includedTypes = ['restaurant'];

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

  • בחיפוש טקסט, החיפוש מופעל ברגע שמקצים ערך ל-textQuery.
  • בחיפוש בסביבה, החיפוש מופעל אחרי שמספקים locationRestriction תקין.

הטמעה של רכיב בסיסי של השלמה אוטומטית למקומות

מפתחים שרוצים להשתמש בחוויית חיפוש בלי ממשק המשתמש שמוצע ברכיב Place Search יכולים להשתמש ברכיב Basic Place Autocomplete.

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

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

ההטמעה הנוכחית

הלוגיקה הקיימת שלכם כנראה כוללת:

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

העברה לרכיב השלמה אוטומטית למקומות

שינוי מבנה ה-HTML

מזהים ומסירים את רכיב ה-HTML שאליו מצורף הווידג'ט Autocomplete. סביר להניח שהיא משתמשת בשדה להזנת קלט HTML רגיל.

<input id="pac-input" type="text" placeholder="Search for a location" />

דוגמה ל-HTML חדש, שמשתמש בגישה של רכיבי אינטרנט כדי לאתחל רכיב Basic Place Autocomplete בדף.

<gmp-basic-place-autocomplete></gmp-basic-place-autocomplete>

התאמת הלוגיקה של JavaScript

הלוגיקה של JavaScript כנראה כוללת יצירה של ווידג'ט להשלמה אוטומטית שמצורף לרכיב input HTML. הווידג'ט הזה מקשיב לאירוע place_changed ומפעיל פעולה עם הנתונים שמוחזרים.

דוגמה לקוד JavaScript קיים שצריך להסיר:

// Get the input element
const input = document.getElementById("pac-input");

// Create the Autocomplete widget instance
const autocomplete = new google.maps.places.Autocomplete(input, {
  fields: ["place_id", "geometry", "name"]
});

// Add a listener for the 'place_changed' event
autocomplete.addListener("place_changed", () => {
  // Your logic to get and display place information
  console.log(place.place_id);
});

הלוגיקה החדשה של JavaScript תקבל הפניה לרכיב Basic השלמה אוטומטית למקומות, ותאזין לאירועים gmp-select:

const placeAutocomplete = document.querySelector('gmp-basic-place-autocomplete');

placeAutocomplete.addEventListener('gmp-select', (event) => {
  console.log(event.place);
});

כשבוחרים מקום מהרשימה הנפתחת של ההשלמה האוטומטית, האירוע gmp-select מופעל. אפשר לאחזר את מזהה המקום של המקום שנבחר מהאובייקט event. אחר כך אפשר להשתמש במזהה המקום כדי לאתחל מופע של רכיב Place Details, כדי להציג את פרטי המקום שנבחר.

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

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

כיוון

אפשר לעבד את רכיב פרטי המקום גם בכיוון אופקי וגם בכיוון אנכי. במאפיין orientation ב-gmp-place-details-compact אפשר לבחור בין פורמט אנכי לאופקי. לדוגמה:

<gmp-place-details-compact orientation="vertical">

בחירת שדות לעיבוד

משתמשים ברכיבי תוכן כדי לציין את התוכן שיוצג ברכיב PlaceDetails. לדוגמה, החרגת רכיב התוכן <gmp-place-type> תגרום לכך שרכיב Place Details לא יציג את סוג המקום של המקום שנבחר. רשימה מלאה של רכיבי התוכן זמינה במאמרי העזרה בנושא PlaceContentConfigElement.

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

הגדרת סגנונות CSS

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

gmp-place-details-compact {
  --gmp-mat-color-surface: green;
}

פרטים נוספים מופיעים במאמרי העזרה של PlaceDetailsCompactElement.

התאמה אישית של רכיב חיפוש המקומות

כיוון

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

<gmp-place-search orientation="horizontal" selectable>

בחירת שדות לעיבוד

משתמשים ברכיבי תוכן כדי לציין את התוכן שיוצג ברכיב Place Search. אפשר להשתמש ברכיב <gmp-place-all-content> כדי להציג את כל התוכן, או להשתמש במבחר של תגי HTML כדי להגדיר את התוכן שעבר עיבוד.

הכללת <gmp-place-address> בתוך <gmp-place-content-config> תציג רק את הכתובת של כל מקום, לדוגמה:

<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-content-config>
    <gmp-place-address></gmp-place-address>
  </gmp-place-content-config>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

התאמה אישית של רכיב ההשלמה האוטומטית למקומות

הגדרת סגנונות CSS

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

gmp-basic-place-autocomplete {
  background-color: #d993e6;
}

פרטים נוספים מופיעים במאמרי עזרה BasicPlaceAutocompleteElement.

טיפול באירועים ובנתונים

רכיבי Places UI Kit הם רכיבים אינטראקטיביים שמאפשרים להאזין לאירועים ולאחזר נתונים באופן פרוגרמטי.

האזנה לאירועים

אפשר להוסיף רכיבי Event Listener לרכיבים כדי להפעיל פעולות על סמך אינטראקציה של משתמשים או על סמך מצב הרכיב.

אירוע בחירה

  • ‫gmp-select: האירוע הזה מופעל כשמשתמש מבצע בחירה.
    • ב-Place Search Element, התג מופעל כשמשתמש לוחץ על מקום ברשימת התוצאות.
    • ב-Basic Place Autocomplete Element, האירוע מופעל כשמשתמש לוחץ על תחזית ברשימה הנפתחת.

אירועים נפוצים

כל הרכיבים חיפוש מקומות, Place Details ו-Basic השלמה אוטומטית למקומות תומכים באירועים הבאים:

  • ‫gmp-load: מופעל כשהרכיב והתוכן שלו מסיימים את הטעינה והרינדור.
  • ‫gmp-requesterror: מופעל כשבקשה לשרת נכשלת, למשל בגלל מפתח API לא תקין.

גישה פרוגרמטית לנתונים של רכיבים

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

  • ברכיב חיפוש מקומות וברכיב Place Details, אפשר לאחזר את המידע הבא:
    • מזהה מקום
    • מיקום (קו רוחב וקו אורך)
    • אזור התצוגה
  • ברכיב Basic השלמה אוטומטית למקומות, אפשר לאחזר את המידע הבא:
    • מזהה מקום

אין גישה תוכנתית לכל שאר הנתונים שכלולים ברכיבים.

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

בדיקה ושיפור

אחרי שמטמיעים רכיבים של Places UI Kit, חשוב לבצע בדיקות כדי להבטיח מעבר חלק וחוויית משתמש חיובית. הבדיקה צריכה לכלול כמה תחומים מרכזיים, ולבדוק את כל הרכיבים שהטמעתם: Place Details,‏ חיפוש מקומות ו-Basic השלמה אוטומטית למקומות.

רכיב Place Details

כדי להתחיל להשתמש ברכיב 'פרטי מקום', צריך לוודא שהפרטים מוצגים בצורה נכונה במגוון רחב של מקומות. כדי לבדוק את ההטמעה, מעבירים מזהים שונים של מקומות למאפיין .place של רכיב <gmp-place-details-place-request>. להשתמש במזהים שמייצגים סוגים שונים של מקומות (עסקים עם נתונים עשירים, נקודות עניין, כתובות בסיסיות) ומקומות באזורים או בשפות שונות. חשוב לשים לב לפורמט, לפריסה ולנוכחות של התוכן.

רכיב חיפוש מקומות

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

  • כדי לבדוק חיפוש טקסט, מגדירים את המאפיין textQuery ברכיב <gmp-place-text-search-request> עם קלט שונה: שאילתות רחבות, כתובות ספציפיות ושאילתות עם הטיה למיקום.
  • כדי לבדוק חיפוש בסביבה, מגדירים את המאפיינים locationRestriction ו-includedTypes ברכיב <gmp-place-nearby-search-request>. אפשר להשתמש בגדלים שונים של מיקומים ובמסנני סוגים.

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

רכיב בסיסי של השלמה אוטומטית למקומות

באלמנט Basic של השלמה אוטומטית למקומות, כדאי להתמקד בבדיקה של אינטראקציית משתמש ושל הנתונים שמועברים על ידי אירוע הבחירה. מוודאים שgmp-selectהאירוע מופעל באופן מהימן כשמשתמש לוחץ על תחזית. מוודאים שהאובייקט event.place בגורם המטפל באירועים מכיל מזהה מקום תקין.

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

טיפול בשגיאות

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