השקת Places UI Kit: ספריית רכיבים מוכנה לשימוש בעלות נמוכה, שמאפשרת לכם להוסיף לכל מפה שתבחרו את ממשק המשתמש המוכר של 'מקומות' במפות Google. כדאי לנסות אותו ולשלוח לנו משוב כדי לעזור לנו לעצב את העתיד של GMP.

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

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

המטרה: להחליף את ההטמעה של Places API או של Place Class ב-Places UI Kit.

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

מפתחים שהם:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Place Details Compact Element
רכיב 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 ומאכלסים אותם בנתונים שהתקבלו.

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

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 של 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 Element, יש אפשרות להשתמש ב-Basic Place Autocomplete Element.

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

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

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

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

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

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

שינוי מבנה ה-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 כנראה כוללת יצירה של הווידג'ט להשלמה אוטומטית שמצורף לרכיב 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 Place Autocomplete (השלמה אוטומטית בסיסית של מקומות) ותאזין לאירועים gmp-select:

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

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

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

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

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

כיוון

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

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

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

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

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

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

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

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

אירוע בחירה

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

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

כל הרכיבים Place Search,‏ Place Details ו-Basic Place Autocomplete תומכים באירועים הבאים:

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

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

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

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

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

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

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

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

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

Place Search Element

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

לוגיקה קיימת

לוגיקה חדשה

הטמעה של אלמנט חיפוש מקומות

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

העברה לאלמנט חיפוש מקומות

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

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

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

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

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

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

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

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

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

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

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

כיוון

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

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

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

כיוון

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

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

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

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

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

אירוע בחירה

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

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

בדיקה ושיפור

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