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

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

לעומת זאת, ברכיב הפשוט של ההשלמה האוטומטית של מקומות (Basic Place Autocomplete), PlaceAutocompleteElement, השדה של הקלט מתנקה כשמשתמש בוחר תחזית של מקום, ומוחזר גם אובייקט Place שמכיל רק את מזהה המקום, ולא אובייקט PlacePrediction. אפשר להשתמש במזהה המקום הזה עם רכיב של ערכת ממשק המשתמש של Places כדי לקבל פרטים נוספים על המקום.

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

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

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

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

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

כדי להוסיף את האלמנט BasicAutocomplete לדף אינטרנט, יוצרים google.maps.places.BasicPlaceAutocompleteElement חדש ומצרפים אותו לדף כמו בדוגמה הבאה: 

  // Request needed libraries.
const {BasicPlaceAutocompleteElement} = await google.maps.importLibrary('places');
// Create the input HTML element, and append it.
const placeAutocomplete = new BasicPlaceAutocompleteElement();
document.body.appendChild(placeAutocomplete);

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

כדי להוסיף למפה רכיב של השלמה אוטומטית בסיסית, יוצרים מופע חדש של BasicPlaceAutocompleteElement, מוסיפים אותו ל-div ומעבירים אותו למפה כרכיב בקרה בהתאמה אישית, כמו בדוגמה הבאה:

  const placeAutocomplete = new google.maps.places.BasicPlaceAutocompleteElement();
  placeAutocomplete.id = 'place-autocomplete-input';
  placeAutocomplete.locationBias = center;
  const card = document.getElementById('place-autocomplete-card');
  card.appendChild(placeAutocomplete);
  map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);

הגבלת החיזויים להשלמה האוטומטית

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

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

אם לא מספקים גבולות או אזור תצוגה של מפה, ה-API ינסה לזהות את מיקום המשתמש מכתובת ה-IP שלו, ויטה את התוצאות למיקום הזה. הגדירו גבולות בכל הזדמנות. אחרת, משתמשים שונים עשויים לקבל תחזיות שונות. כדי לשפר את התחזיות באופן כללי, חשוב לספק אזור תצוגה הגיוני, למשל אזור תצוגה שהגדרתם על ידי הזזה או שינוי גודל במפה, או אזור תצוגה שהוגדר על ידי מפתח על סמך מיקום המכשיר והרדיוס. אם לא מצוין רדיוס, ברירת המחדל הסבירה עבור רכיב השלמה אוטומטית בסיסי של מקומות היא 5 ק"מ. אל תגדירו אזור תצוגה עם רדיוס אפס (נקודה אחת), אזור תצוגה שרוחבו כמה מטרים בלבד (פחות מ-100 מ'), או אזור תצוגה שמשתרע על פני כדור הארץ.

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

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

const pac = new google.maps.places.BasicPlaceAutocompleteElement({
  includedRegionCodes: ['us', 'au'],
});

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

כדי להגביל את החיפוש של מקומות לגבולות של מפה, משתמשים במאפיין locationRestrictions כדי להוסיף את הגבולות, כמו שמוצג בקטע הקוד הבא:

const pac = new google.maps.places.BasicPlaceAutocompleteElement({
  locationRestriction: map.getBounds(),
});

כשמגבילים את המפה לגבולות מסוימים, חשוב להוסיף listener כדי לעדכן את הגבולות כשהם משתנים:

map.addListener('bounds_changed', () => {
  autocomplete.locationRestriction = map.getBounds();
});

כדי להסיר את locationRestriction, מגדירים אותו כnull.

הטיה בתוצאות החיפוש של מקומות

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

const autocomplete = new google.maps.places.BasicPlaceAutocompleteElement({
  locationBias: {radius: 100, center: {lat: 50.064192, lng: -130.605469}},
});

כדי להסיר את locationBias, מגדירים אותו כnull.

הגבלת תוצאות החיפוש של מקומות לסוגים מסוימים

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

const autocomplete = new google.maps.places.BasicPlaceAutocompleteElement({
  includedPrimaryTypes: ['establishment'],
});

רשימה מלאה של הסוגים הנתמכים זמינה בטבלאות A ו-B של סוגי מקומות.

קבלת פרטי מקום

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

// Add the gmp-select listener, and display the results.
  placeAutocomplete.addEventListener('gmp-select', async ({ place }) => {
      await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });
      selectedPlaceTitle.textContent = 'Selected Place:';
      selectedPlaceInfo.textContent = JSON.stringify(place.toJSON(), /* replacer */ null, /* space */ 2);
  });

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

המאזין בדוגמה הבאה מבקש מידע על מקום ומציג אותו במפה.

  // Add the gmp-placeselect listener, and display the results on the map.
  //@ts-ignore
  placeAutocomplete.addEventListener('gmp-select', async ({ place }) => {
      await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });
      // If the place has a geometry, then present it on a map.
      if (place.viewport) {
          map.fitBounds(place.viewport);
      }
      else {
          map.setCenter(place.location);
          map.setZoom(17);
      }
      let content = '<div id="infowindow-content">' +
          '<span id="place-displayname" class="title">' + place.displayName + '</span><br />' +
          '<span id="place-address">' + place.formattedAddress + '</span>' +
          '</div>';
      updateInfoWindow(content, place.location);
      marker.position = place.location;
  });

בדוגמה הזו אנחנו מראים איך להוסיף רכיב השלמה אוטומטית בסיסי למפת Google.

JavaScript

const mapContainer = document.getElementById("map-container");
const autocompleteElement = document.querySelector('gmp-basic-place-autocomplete');
const detailsElement = document.querySelector('gmp-place-details-compact');
const mapElement = document.querySelector('gmp-map');
const advancedMarkerElement = document.querySelector('gmp-advanced-marker');
let center = { lat: 40.749933, lng: -73.98633 }; // New York City
async function initMap() {
    //@ts-ignore
    const { BasicPlaceAutocompleteElement, PlaceDetailsElement } = await google.maps.importLibrary('places');
    //@ts-ignore
    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');
    //@ts-ignore
    const { LatLngBounds } = await google.maps.importLibrary('core');
    // Set the initial map location and autocomplete location bias
    mapElement.center = center;
    autocompleteElement.locationBias = center;
    // Get the underlying google.maps.Map object to add listeners
    const map = mapElement.innerMap;
    // Add the listener tochange locationBias to locationRestriction when the map moves
    map.addListener('bounds_changed', () => {
        autocompleteElement.locationBias = null;
        autocompleteElement.locationRestriction = map.getBounds();
        console.log("bias changed to restriction");
    });
    // Add the listener to update the Place Request element when the user selects a prediction
    autocompleteElement.addEventListener('gmp-select', async (event) => {
        const placeDetailsRequest = document.querySelector('gmp-place-details-place-request');
        placeDetailsRequest.place = event.place.id;
    });
    // Add the listener to update the marker when the Details element loads
    detailsElement.addEventListener('gmp-load', async () => {
        const location = detailsElement.place.location;
        detailsElement.style.display = "block";
        advancedMarkerElement.position = location;
        advancedMarkerElement.content = detailsElement;
        if (detailsElement.place.viewport) {
            map.fitBounds(detailsElement.place.viewport);
        }
        else {
            map.setCenter(location);
            map.setZoom(17);
        }
    });
}
initMap();
index.js

CSS

html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

#map-container {
  display: flex;
  flex-direction: row;
  height: 100%;
}

#gmp-map {
  height: 100%;
}

gmp-basic-place-autocomplete {
  position: absolute;
  height: 50px;
  top: 10px;
  left: 10px;
  z-index: 1;
  box-shadow: 2px 2px 5px 0px rgba(0,0,0,0.2); 
  color-scheme: light;
  border-radius: 10px;
}

gmp-place-details-compact {
  width: 360px;
  max-height: 300px;
  border: none;
  padding: 0;
  margin: 0;
  position: absolute;
  transform: translate(calc(-180px), calc(-215px)); 
  box-shadow: 2px 2px 5px 0px rgba(0,0,0,0.2); 
  color-scheme: light;
}

/* This creates the pointer attached to the bottom of the element. */
gmp-place-details-compact::after {
  content: "";
  position: absolute;
  top: 100%;
  left: 50%;
  transform: translateX(-50%);
  width: 0;
  height: 0;
  border-left: 16px solid transparent;
  border-right: 16px solid transparent;
  border-top: 20px solid var(--gmp-mat-color-surface, light-dark(white, black));
}
style.css

HTML

<html>
  <head>
    <title>Place Autocomplete map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
   <div id="map-container">
      <gmp-basic-place-autocomplete></gmp-basic-place-autocomplete>
      <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>
      <gmp-map zoom="14" map-id="DEMO_MAP_ID">
         <gmp-advanced-marker></gmp-advanced-marker> 
      </gmp-map>
    </div>

    <!-- prettier-ignore -->
    <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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
  </body>
</html>
index.html

לניסיון