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

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

מעבר לרכיב Place Details

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

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

יש שני רכיבים שאפשר לבחור:

רכיב קומפקטי של פרטי מקום
רכיב 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 (לשירות אינטרנט) כדי לבקש נתונים ספציפיים.
בפונקציית ה-callback, בוחרים ידנית את רכיבי ה-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>.
מעבירים את מזהה המקום או את אובייקט המקום למאפיין המקום ברכיב <gmp-place-details-place-request>.

בדוגמה הבאה אפשר לראות איך מטמיעים את ערכת ממשק המשתמש של פרטי המקום בלוגיקה של JavaScript. מקבלים הפניה לרכיב 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, או משתמשים ב-JavaScript API Place Class.
אתם מציינים פרמטרים של שאילתות, הגבלות או הטיות של מיקום, סוגים ושדות מבוקשים באמצעות 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 תקין.

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

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

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

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

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

סביר להניח שהלוגיקה הקיימת שלכם כוללת:

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

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

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

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

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

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

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

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

סביר להניח שהלוגיקה של JavaScript כוללת יצירה של ווידג'ט ההשלמה האוטומטית שמצורף לרכיב HTML מסוג input. הווידג'ט הזה מאזין לאירוע 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 החדשה תקבל הפניה לרכיב הבסיסי של ההשלמה האוטומטית למקומות, ותאזין לאירועי gmp-select:

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

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

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

התאמה אישית של הכינוי

התאמה אישית של רכיב Place Details

כיוון

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

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

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

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

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

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

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

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

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

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

כיוון

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

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

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

משתמשים ברכיבי תוכן כדי לציין את התוכן שיוצג ברכיב חיפוש המקומות. אפשר להשתמש ברכיב <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: האירוע הזה מופעל כשהמשתמש בוחר אפשרות.
- ברכיב חיפוש מקומות, האירוע מופעל כשמשתמש לוחץ על מקום ברשימת התוצאות.
- ברכיב הבסיסי של השלמה אוטומטית למקומות, האירוע מופעל כשמשתמש לוחץ על חיזוי ברשימה הנפתחת.

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

הרכיבים "חיפוש מקומות", "פרטי מקומות" ו"השלמה אוטומטית בסיסית של מקומות" תומכים באירועים הבאים:

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

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

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

אפשר לאחזר את המידע הבא לגבי רכיב חיפוש המקומות ורכיב פרטי המקום:
- מזהה מקום
- מיקום (קו רוחב וקו אורך)
- אזור התצוגה
ברכיב 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 מופעל בצורה תקינה כשבוחרים תוצאה.

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

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

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

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

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

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

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

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

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

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

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

מעבר לרכיב Place Details

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

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

לוגיקה קיימת

לוגיקה חדשה

הטמעת רכיב חיפוש המקומות

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

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

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

דוגמה לחיפוש בסביבה

דוגמה לחיפוש טקסט

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

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

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

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

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

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

התאמה אישית של הכינוי

התאמה אישית של רכיב Place Details

כיוון

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

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

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

כיוון

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

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

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

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

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

אירוע בחירה

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

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

בדיקה ושיפור

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