ویجت تکمیل خودکار مکان (پیش نمایش)

ویجت تکمیل خودکار مکان یک فیلد ورودی متن ایجاد می‌کند، پیش‌بینی‌های مکان را در فهرست انتخاب رابط کاربری ارائه می‌کند، و جزئیات مکان را در پاسخ به انتخاب کاربر برمی‌گرداند. از ویجت تکمیل خودکار مکان برای جاسازی یک رابط کاربری کامل خودکار مستقل در صفحه وب خود استفاده کنید.

پیش نیازها

برای استفاده از Place Autocomplete (پیش نمایش)، باید "Places API" را در پروژه Google Cloud خود فعال کنید و کانال بتا ( v: "beta" ) را در بوت استرپ لودر خود مشخص کنید. برای جزئیات بیشتر به شروع به کار مراجعه کنید.

چه خبر است

تکمیل خودکار مکان (پیش نمایش) به روش های زیر بهبود یافته است:

  • رابط کاربری ویجت تکمیل خودکار از محلی‌سازی منطقه‌ای (از جمله زبان‌های RTL) برای مکان‌گردان ورودی متن، نشان‌واره فهرست پیش‌بینی‌ها و پیش‌بینی‌های مکان پشتیبانی می‌کند.
  • دسترسی پیشرفته، از جمله پشتیبانی از صفحه‌خوان‌ها و تعامل با صفحه‌کلید.
  • ویجت Autocomplete کلاس Place جدید را برمی گرداند تا مدیریت شیء برگشتی را ساده کند.
  • پشتیبانی بهتر از دستگاه های تلفن همراه و صفحه نمایش های کوچک.
  • عملکرد بهتر و ظاهر گرافیکی بهبود یافته.

یک ویجت تکمیل خودکار اضافه کنید

می توانید یک ویجت تکمیل خودکار را به یک صفحه وب یا نقشه گوگل اضافه کنید. ویجت تکمیل خودکار یک فیلد ورودی متن ایجاد می‌کند، پیش‌بینی‌های مکان را در فهرست انتخاب رابط کاربری ارائه می‌کند، و جزئیات مکان را در پاسخ به کلیک کاربر از طریق شنونده gmp-placeselect برمی‌گرداند. این بخش به شما نشان می دهد که چگونه یک ویجت تکمیل خودکار را به یک صفحه وب یا نقشه گوگل اضافه کنید.

یک ویجت تکمیل خودکار را به یک صفحه وب اضافه کنید

برای افزودن ویجت تکمیل خودکار به یک صفحه وب، یک google.maps.places.PlaceAutocompleteElement جدید ایجاد کنید و همانطور که در مثال زیر نشان داده شده است آن را به صفحه اضافه کنید:

TypeScript 

// Request needed libraries.
//@ts-ignore
await google.maps.importLibrary("places") as google.maps.PlacesLibrary;
// Create the input HTML element, and append it.
//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
//@ts-ignore
document.body.appendChild(placeAutocomplete);
index.ts

جاوا اسکریپت 

// Request needed libraries.
//@ts-ignore
await google.maps.importLibrary("places");

// Create the input HTML element, and append it.
//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();

//@ts-ignore
document.body.appendChild(placeAutocomplete);

index.js

نمونه کد کامل را ببینید

ویجت تکمیل خودکار را به نقشه اضافه کنید

برای افزودن یک ویجت تکمیل خودکار به نقشه، یک نمونه جدید google.maps.places.PlaceAutocompleteElement ایجاد کنید، PlaceAutocompleteElement به یک div اضافه کنید و آن را به عنوان یک کنترل سفارشی روی نقشه فشار دهید، همانطور که در مثال زیر نشان داده شده است:

TypeScript 

//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
//@ts-ignore
placeAutocomplete.id = 'place-autocomplete-input';

const card = document.getElementById('place-autocomplete-card') as HTMLElement;
//@ts-ignore
card.appendChild(placeAutocomplete);
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
index.ts

جاوا اسکریپت 

//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();

//@ts-ignore
placeAutocomplete.id = "place-autocomplete-input";

const card = document.getElementById("place-autocomplete-card");

//@ts-ignore
card.appendChild(placeAutocomplete);
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
index.js

نمونه کد کامل را ببینید

پیش بینی های تکمیل خودکار را محدود کنید

به‌طور پیش‌فرض، «تکمیل خودکار مکان» همه انواع مکان‌ها را ارائه می‌کند که برای پیش‌بینی‌های نزدیک به مکان کاربر تعصب دارند و همه فیلدهای داده موجود را برای مکان انتخابی کاربر واکشی می‌کند. PlaceAutocompleteElementOptions را برای ارائه پیش‌بینی‌های مرتبط‌تر، با محدود کردن یا سوگیری نتایج، تنظیم کنید.

محدود کردن نتایج باعث می‌شود که ویجت تکمیل خودکار نتایجی را که خارج از محدوده محدودیت هستند نادیده بگیرد. یک روش معمول محدود کردن نتایج به محدوده نقشه است. نتایج بایاس باعث می شود که ویجت تکمیل خودکار نتایج را در محدوده مشخص شده نشان دهد، اما برخی از موارد منطبق ممکن است خارج از آن منطقه باشند.

اگر هیچ محدوده یا یک نمای نقشه ارائه نکنید، API سعی می کند موقعیت مکانی کاربر را از آدرس IP آنها تشخیص دهد و نتایج را به آن مکان سوگیری می کند. هر زمان که ممکن است یک محدوده تعیین کنید. در غیر این صورت، کاربران مختلف ممکن است پیش بینی های متفاوتی دریافت کنند. همچنین، برای بهبود کلی پیش‌بینی‌ها، مهم است که یک نمای دید معقول ارائه کنید، مانند تصویری که با حرکت دادن یا بزرگ‌نمایی روی نقشه تنظیم می‌کنید، یا یک درگاه نمای تنظیم‌شده توسط برنامه‌نویس بر اساس مکان و شعاع دستگاه. وقتی شعاع در دسترس نباشد، 5 کیلومتر پیش‌فرض معقول برای تکمیل خودکار مکان در نظر گرفته می‌شود. یک دریچه دید با شعاع صفر (یک نقطه)، یک دریچه دید با عرض تنها چند متر (کمتر از 100 متر)، یا یک دریچه دید که سراسر کره زمین را در بر می گیرد، تنظیم نکنید.

جستجوی مکان را بر اساس کشور محدود کنید

برای محدود کردن جستجوی مکان به یک یا چند کشور خاص، از ویژگی componentRestrictions برای تعیین کد(های) کشور همانطور که در قطعه زیر نشان داده شده است استفاده کنید:

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

جستجوی مکان را به محدوده نقشه محدود کنید

برای محدود کردن جستجوی مکان به محدوده‌های نقشه، از ویژگی locationRestrictions برای اضافه کردن محدوده‌ها استفاده کنید، همانطور که در قطعه زیر نشان داده شده است:

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

وقتی محدودیت‌های نقشه را محدود می‌کنید، حتماً شنونده‌ای اضافه کنید تا زمانی که محدوده‌ها تغییر می‌کنند، آن‌ها را به‌روزرسانی کند:

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

برای حذف locationRestriction ، آن را روی null قرار دهید.

نتایج جستجوی مکان سوگیری

Bias نتایج جستجو را با استفاده از ویژگی locationBias و عبور از یک شعاع در یک ناحیه دایره ای قرار می دهد، همانطور که در اینجا نشان داده شده است:

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

برای حذف locationBias ، آن را روی null قرار دهید.

نتایج جستجوی مکان را به انواع خاصی محدود کنید

نتایج جستجوی مکان را به انواع خاصی از مکان‌ها با استفاده از ویژگی types محدود کنید و یک یا چند نوع را مشخص کنید، همانطور که در اینجا نشان داده شده است:

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

برای فهرست کامل انواع پشتیبانی شده، جدول 3: انواع پشتیبانی شده در درخواست های تکمیل خودکار را ببینید.

جزئیات مکان را دریافت کنید

برای دریافت جزئیات مکان برای مکان انتخاب شده، یک شنونده gmp-placeselect به PlaceAutocompleteElement اضافه کنید، همانطور که در مثال زیر نشان داده شده است:

TypeScript 

// Add the gmp-placeselect listener, and display the results.
//@ts-ignore
placeAutocomplete.addEventListener('gmp-placeselect', async ({ place }) => {
    await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });

    selectedPlaceTitle.textContent = 'Selected Place:';
    selectedPlaceInfo.textContent = JSON.stringify(
        place.toJSON(), /* replacer */ null, /* space */ 2);
});
index.ts

جاوا اسکریپت 

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

نمونه کد کامل را ببینید

در مثال قبل، شنونده رویداد یک شی از کلاس Place را برمی گرداند. با place.fetchFields() برای دریافت فیلدهای داده Place Details مورد نیاز برای برنامه خود فراخوانی کنید.

شنونده در مثال بعدی اطلاعات مکان را درخواست می کند و آن را روی نقشه نمایش می دهد.

TypeScript 

// Add the gmp-placeselect listener, and display the results on the map.
//@ts-ignore
placeAutocomplete.addEventListener('gmp-placeselect', 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;
});
index.ts

جاوا اسکریپت 

// Add the gmp-placeselect listener, and display the results on the map.
//@ts-ignore
placeAutocomplete.addEventListener("gmp-placeselect", 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;
});
index.js

نمونه کد کامل را ببینید

نمونه نقشه ها

این بخش شامل کد کامل برای نمونه نقشه های ارائه شده در این صفحه است.

عنصر تکمیل خودکار

این مثال یک ویجت تکمیل خودکار را به یک صفحه وب اضافه می کند و نتایج را برای هر مکان انتخاب شده نمایش می دهد.

TypeScript 

async function initMap(): Promise<void> {
    // Request needed libraries.
    //@ts-ignore
    await google.maps.importLibrary("places") as google.maps.PlacesLibrary;
    // Create the input HTML element, and append it.
    //@ts-ignore
    const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
    //@ts-ignore
    document.body.appendChild(placeAutocomplete);

    // Inject HTML UI.
    const selectedPlaceTitle = document.createElement('p');
    selectedPlaceTitle.textContent = '';
    document.body.appendChild(selectedPlaceTitle);

    const selectedPlaceInfo = document.createElement('pre');
    selectedPlaceInfo.textContent = '';
    document.body.appendChild(selectedPlaceInfo);

    // Add the gmp-placeselect listener, and display the results.
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-placeselect', async ({ place }) => {
        await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });

        selectedPlaceTitle.textContent = 'Selected Place:';
        selectedPlaceInfo.textContent = JSON.stringify(
            place.toJSON(), /* replacer */ null, /* space */ 2);
    });
}

initMap();
index.ts

جاوا اسکریپت 

async function initMap() {
  // Request needed libraries.
  //@ts-ignore
  await google.maps.importLibrary("places");

  // Create the input HTML element, and append it.
  //@ts-ignore
  const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();

  //@ts-ignore
  document.body.appendChild(placeAutocomplete);

  // Inject HTML UI.
  const selectedPlaceTitle = document.createElement("p");

  selectedPlaceTitle.textContent = "";
  document.body.appendChild(selectedPlaceTitle);

  const selectedPlaceInfo = document.createElement("pre");

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

initMap();
index.js

CSS 

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

p {
  font-family: Roboto, sans-serif;
  font-weight: bold;
}

style.css

HTML 

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

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p style="font-family: roboto, sans-serif">Search for a place here:</p>

    <!-- 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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "beta"});</script>
  </body>
</html>
index.html

Sample را امتحان کنید

تکمیل خودکار نقشه

این مثال به شما نشان می دهد که چگونه یک ویجت تکمیل خودکار را به نقشه گوگل اضافه کنید.

TypeScript 

let map: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
let infoWindow: google.maps.InfoWindow;
async function initMap(): Promise<void> {
    // Request needed libraries.
    //@ts-ignore
    const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary("marker"),
        google.maps.importLibrary("places")
      ]);

    // Initialize the map.
    map = new google.maps.Map(document.getElementById('map') as HTMLElement, {
        center: { lat: 40.749933, lng: -73.98633 },
        zoom: 13,
        mapId: '4504f8b37365c3d0',
        mapTypeControl: false,
    });
    //@ts-ignore
    const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
    //@ts-ignore
    placeAutocomplete.id = 'place-autocomplete-input';

    const card = document.getElementById('place-autocomplete-card') as HTMLElement;
    //@ts-ignore
    card.appendChild(placeAutocomplete);
    map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);

    // Create the marker and infowindow
    marker = new google.maps.marker.AdvancedMarkerElement({
        map,
    });

    infoWindow = new google.maps.InfoWindow({});

    // Add the gmp-placeselect listener, and display the results on the map.
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-placeselect', 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;
    });
}

// Helper function to create an info window.
function updateInfoWindow(content, center) {
    infoWindow.setContent(content);
    infoWindow.setPosition(center);
    infoWindow.open({
        map,
        anchor: marker,
        shouldFocus: false,
    });
}

initMap();
index.ts

جاوا اسکریپت 

let map;
let marker;
let infoWindow;

async function initMap() {
  // Request needed libraries.
  //@ts-ignore
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("marker"),
    google.maps.importLibrary("places"),
  ]);

  // Initialize the map.
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 40.749933, lng: -73.98633 },
    zoom: 13,
    mapId: "4504f8b37365c3d0",
    mapTypeControl: false,
  });

  //@ts-ignore
  const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();

  //@ts-ignore
  placeAutocomplete.id = "place-autocomplete-input";

  const card = document.getElementById("place-autocomplete-card");

  //@ts-ignore
  card.appendChild(placeAutocomplete);
  map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
  // Create the marker and infowindow
  marker = new google.maps.marker.AdvancedMarkerElement({
    map,
  });
  infoWindow = new google.maps.InfoWindow({});
  // Add the gmp-placeselect listener, and display the results on the map.
  //@ts-ignore
  placeAutocomplete.addEventListener("gmp-placeselect", 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;
  });
}

// Helper function to create an info window.
function updateInfoWindow(content, center) {
  infoWindow.setContent(content);
  infoWindow.setPosition(center);
  infoWindow.open({
    map,
    anchor: marker,
    shouldFocus: false,
  });
}

initMap();
index.js

CSS 

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

#place-autocomplete-card {
  background-color: #fff;
  border-radius: 5px;
  box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
  margin: 10px;
  padding: 5px;
  font-family: Roboto, sans-serif;
  font-size: large;
  font-weight: bold;
}

gmp-place-autocomplete {
  width: 300px;
}

#infowindow-content .title {
  font-weight: bold;
}

#map #infowindow-content {
  display: inline;
}

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 class="place-autocomplete-card" id="place-autocomplete-card">
      <p>Search for a place here:</p>
    </div>
    <div id="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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "beta"});</script>
  </body>
</html>
index.html

Sample را امتحان کنید

از مولفه Place Picker استفاده کنید

جزء انتخابگر مکان یک ورودی متنی است که به کاربران نهایی امکان می دهد آدرس یا مکان خاصی را با استفاده از تکمیل خودکار جستجو کنند. این بخشی از Extended Component Library است، مجموعه‌ای از مؤلفه‌های وب که به توسعه‌دهندگان کمک می‌کند نقشه‌ها و ویژگی‌های مکان بهتری را سریع‌تر بسازند.

از پیکربندی Place Picker برای ایجاد کد قابل جاسازی برای یک مؤلفه Place Picker سفارشی استفاده کنید، سپس آن را صادر کنید تا با فریم ورک‌های محبوبی مانند React و Angular یا اصلاً فریمورک استفاده نشود.

،

ویجت تکمیل خودکار مکان یک فیلد ورودی متن ایجاد می‌کند، پیش‌بینی‌های مکان را در فهرست انتخاب رابط کاربری ارائه می‌کند، و جزئیات مکان را در پاسخ به انتخاب کاربر برمی‌گرداند. از ویجت تکمیل خودکار مکان برای جاسازی یک رابط کاربری کامل خودکار مستقل در صفحه وب خود استفاده کنید.

پیش نیازها

برای استفاده از Place Autocomplete (پیش نمایش)، باید "Places API" را در پروژه Google Cloud خود فعال کنید و کانال بتا ( v: "beta" ) را در بوت استرپ لودر خود مشخص کنید. برای جزئیات بیشتر به شروع به کار مراجعه کنید.

چه خبر است

تکمیل خودکار مکان (پیش نمایش) به روش های زیر بهبود یافته است:

  • رابط کاربری ویجت تکمیل خودکار از محلی‌سازی منطقه‌ای (از جمله زبان‌های RTL) برای مکان‌گردان ورودی متن، نشان‌واره فهرست پیش‌بینی‌ها و پیش‌بینی‌های مکان پشتیبانی می‌کند.
  • دسترسی پیشرفته، از جمله پشتیبانی از صفحه‌خوان‌ها و تعامل با صفحه‌کلید.
  • ویجت Autocomplete کلاس Place جدید را برمی گرداند تا مدیریت شیء برگشتی را ساده کند.
  • پشتیبانی بهتر از دستگاه های تلفن همراه و صفحه نمایش های کوچک.
  • عملکرد بهتر و ظاهر گرافیکی بهبود یافته.

یک ویجت تکمیل خودکار اضافه کنید

می توانید یک ویجت تکمیل خودکار را به یک صفحه وب یا نقشه گوگل اضافه کنید. ویجت تکمیل خودکار یک فیلد ورودی متن ایجاد می‌کند، پیش‌بینی‌های مکان را در فهرست انتخاب رابط کاربری ارائه می‌کند، و جزئیات مکان را در پاسخ به کلیک کاربر از طریق شنونده gmp-placeselect برمی‌گرداند. این بخش به شما نشان می دهد که چگونه یک ویجت تکمیل خودکار را به یک صفحه وب یا نقشه گوگل اضافه کنید.

یک ویجت تکمیل خودکار را به یک صفحه وب اضافه کنید

برای افزودن ویجت تکمیل خودکار به یک صفحه وب، یک google.maps.places.PlaceAutocompleteElement جدید ایجاد کنید و همانطور که در مثال زیر نشان داده شده است آن را به صفحه اضافه کنید:

TypeScript 

// Request needed libraries.
//@ts-ignore
await google.maps.importLibrary("places") as google.maps.PlacesLibrary;
// Create the input HTML element, and append it.
//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
//@ts-ignore
document.body.appendChild(placeAutocomplete);
index.ts

جاوا اسکریپت 

// Request needed libraries.
//@ts-ignore
await google.maps.importLibrary("places");

// Create the input HTML element, and append it.
//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();

//@ts-ignore
document.body.appendChild(placeAutocomplete);

index.js

نمونه کد کامل را ببینید

ویجت تکمیل خودکار را به نقشه اضافه کنید

برای افزودن یک ویجت تکمیل خودکار به نقشه، یک نمونه جدید google.maps.places.PlaceAutocompleteElement ایجاد کنید، PlaceAutocompleteElement به یک div اضافه کنید و آن را به عنوان یک کنترل سفارشی روی نقشه فشار دهید، همانطور که در مثال زیر نشان داده شده است:

TypeScript 

//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
//@ts-ignore
placeAutocomplete.id = 'place-autocomplete-input';

const card = document.getElementById('place-autocomplete-card') as HTMLElement;
//@ts-ignore
card.appendChild(placeAutocomplete);
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
index.ts

جاوا اسکریپت 

//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();

//@ts-ignore
placeAutocomplete.id = "place-autocomplete-input";

const card = document.getElementById("place-autocomplete-card");

//@ts-ignore
card.appendChild(placeAutocomplete);
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
index.js

نمونه کد کامل را ببینید

پیش بینی های تکمیل خودکار را محدود کنید

به‌طور پیش‌فرض، «تکمیل خودکار مکان» همه انواع مکان‌ها را ارائه می‌کند که برای پیش‌بینی‌های نزدیک به مکان کاربر تعصب دارند و همه فیلدهای داده موجود را برای مکان انتخابی کاربر واکشی می‌کند. PlaceAutocompleteElementOptions را برای ارائه پیش‌بینی‌های مرتبط‌تر، با محدود کردن یا سوگیری نتایج، تنظیم کنید.

محدود کردن نتایج باعث می‌شود که ویجت تکمیل خودکار نتایجی را که خارج از محدوده محدودیت هستند نادیده بگیرد. یک روش معمول محدود کردن نتایج به محدوده نقشه است. نتایج بایاس باعث می شود که ویجت تکمیل خودکار نتایج را در محدوده مشخص شده نشان دهد، اما برخی از موارد منطبق ممکن است خارج از آن منطقه باشند.

اگر هیچ محدوده یا یک نمای نقشه ارائه نکنید، API سعی می کند موقعیت مکانی کاربر را از آدرس IP آنها تشخیص دهد و نتایج را به آن مکان سوگیری می کند. هر زمان که ممکن است یک محدوده تعیین کنید. در غیر این صورت، کاربران مختلف ممکن است پیش بینی های متفاوتی دریافت کنند. همچنین، برای بهبود کلی پیش‌بینی‌ها، مهم است که یک نمای دید معقول ارائه کنید، مانند تصویری که با حرکت دادن یا بزرگ‌نمایی روی نقشه تنظیم می‌کنید، یا یک درگاه نمای تنظیم‌شده توسط برنامه‌نویس بر اساس مکان و شعاع دستگاه. وقتی شعاع در دسترس نباشد، 5 کیلومتر پیش‌فرض معقول برای تکمیل خودکار مکان در نظر گرفته می‌شود. یک دریچه دید با شعاع صفر (یک نقطه)، یک دریچه دید با عرض تنها چند متر (کمتر از 100 متر)، یا یک دریچه دید که سراسر کره زمین را در بر می گیرد، تنظیم نکنید.

جستجوی مکان را بر اساس کشور محدود کنید

برای محدود کردن جستجوی مکان به یک یا چند کشور خاص، از ویژگی componentRestrictions برای تعیین کد(های) کشور همانطور که در قطعه زیر نشان داده شده است استفاده کنید:

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

جستجوی مکان را به محدوده نقشه محدود کنید

برای محدود کردن جستجوی مکان به محدوده‌های نقشه، از ویژگی locationRestrictions برای اضافه کردن محدوده‌ها استفاده کنید، همانطور که در قطعه زیر نشان داده شده است:

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

وقتی محدودیت‌های نقشه را محدود می‌کنید، حتماً شنونده‌ای اضافه کنید تا زمانی که محدوده‌ها تغییر می‌کنند، آن‌ها را به‌روزرسانی کند:

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

برای حذف locationRestriction ، آن را روی null قرار دهید.

نتایج جستجوی مکان سوگیری

Bias نتایج جستجو را با استفاده از ویژگی locationBias و عبور از یک شعاع در یک ناحیه دایره ای قرار می دهد، همانطور که در اینجا نشان داده شده است:

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

برای حذف locationBias ، آن را روی null قرار دهید.

نتایج جستجوی مکان را به انواع خاصی محدود کنید

نتایج جستجوی مکان را به انواع خاصی از مکان‌ها با استفاده از ویژگی types محدود کنید و یک یا چند نوع را مشخص کنید، همانطور که در اینجا نشان داده شده است:

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

برای فهرست کامل انواع پشتیبانی شده، جدول 3: انواع پشتیبانی شده در درخواست های تکمیل خودکار را ببینید.

جزئیات مکان را دریافت کنید

برای دریافت جزئیات مکان برای مکان انتخاب شده، یک شنونده gmp-placeselect به PlaceAutocompleteElement اضافه کنید، همانطور که در مثال زیر نشان داده شده است:

TypeScript 

// Add the gmp-placeselect listener, and display the results.
//@ts-ignore
placeAutocomplete.addEventListener('gmp-placeselect', async ({ place }) => {
    await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });

    selectedPlaceTitle.textContent = 'Selected Place:';
    selectedPlaceInfo.textContent = JSON.stringify(
        place.toJSON(), /* replacer */ null, /* space */ 2);
});
index.ts

جاوا اسکریپت 

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

نمونه کد کامل را ببینید

در مثال قبل، شنونده رویداد یک شی از کلاس Place را برمی گرداند. با place.fetchFields() برای دریافت فیلدهای داده Place Details مورد نیاز برای برنامه خود فراخوانی کنید.

شنونده در مثال بعدی اطلاعات مکان را درخواست می کند و آن را روی نقشه نمایش می دهد.

TypeScript 

// Add the gmp-placeselect listener, and display the results on the map.
//@ts-ignore
placeAutocomplete.addEventListener('gmp-placeselect', 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;
});
index.ts

جاوا اسکریپت 

// Add the gmp-placeselect listener, and display the results on the map.
//@ts-ignore
placeAutocomplete.addEventListener("gmp-placeselect", 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;
});
index.js

نمونه کد کامل را ببینید

نمونه نقشه ها

این بخش شامل کد کامل برای نمونه نقشه های ارائه شده در این صفحه است.

عنصر تکمیل خودکار

این مثال یک ویجت تکمیل خودکار را به یک صفحه وب اضافه می کند و نتایج را برای هر مکان انتخاب شده نمایش می دهد.

TypeScript 

async function initMap(): Promise<void> {
    // Request needed libraries.
    //@ts-ignore
    await google.maps.importLibrary("places") as google.maps.PlacesLibrary;
    // Create the input HTML element, and append it.
    //@ts-ignore
    const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
    //@ts-ignore
    document.body.appendChild(placeAutocomplete);

    // Inject HTML UI.
    const selectedPlaceTitle = document.createElement('p');
    selectedPlaceTitle.textContent = '';
    document.body.appendChild(selectedPlaceTitle);

    const selectedPlaceInfo = document.createElement('pre');
    selectedPlaceInfo.textContent = '';
    document.body.appendChild(selectedPlaceInfo);

    // Add the gmp-placeselect listener, and display the results.
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-placeselect', async ({ place }) => {
        await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });

        selectedPlaceTitle.textContent = 'Selected Place:';
        selectedPlaceInfo.textContent = JSON.stringify(
            place.toJSON(), /* replacer */ null, /* space */ 2);
    });
}

initMap();
index.ts

جاوا اسکریپت 

async function initMap() {
  // Request needed libraries.
  //@ts-ignore
  await google.maps.importLibrary("places");

  // Create the input HTML element, and append it.
  //@ts-ignore
  const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();

  //@ts-ignore
  document.body.appendChild(placeAutocomplete);

  // Inject HTML UI.
  const selectedPlaceTitle = document.createElement("p");

  selectedPlaceTitle.textContent = "";
  document.body.appendChild(selectedPlaceTitle);

  const selectedPlaceInfo = document.createElement("pre");

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

initMap();
index.js

CSS 

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

p {
  font-family: Roboto, sans-serif;
  font-weight: bold;
}

style.css

HTML 

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

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p style="font-family: roboto, sans-serif">Search for a place here:</p>

    <!-- 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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "beta"});</script>
  </body>
</html>
index.html

Sample را امتحان کنید

تکمیل خودکار نقشه

این مثال به شما نشان می دهد که چگونه یک ویجت تکمیل خودکار را به نقشه گوگل اضافه کنید.

TypeScript 

let map: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
let infoWindow: google.maps.InfoWindow;
async function initMap(): Promise<void> {
    // Request needed libraries.
    //@ts-ignore
    const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary("marker"),
        google.maps.importLibrary("places")
      ]);

    // Initialize the map.
    map = new google.maps.Map(document.getElementById('map') as HTMLElement, {
        center: { lat: 40.749933, lng: -73.98633 },
        zoom: 13,
        mapId: '4504f8b37365c3d0',
        mapTypeControl: false,
    });
    //@ts-ignore
    const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
    //@ts-ignore
    placeAutocomplete.id = 'place-autocomplete-input';

    const card = document.getElementById('place-autocomplete-card') as HTMLElement;
    //@ts-ignore
    card.appendChild(placeAutocomplete);
    map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);

    // Create the marker and infowindow
    marker = new google.maps.marker.AdvancedMarkerElement({
        map,
    });

    infoWindow = new google.maps.InfoWindow({});

    // Add the gmp-placeselect listener, and display the results on the map.
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-placeselect', 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;
    });
}

// Helper function to create an info window.
function updateInfoWindow(content, center) {
    infoWindow.setContent(content);
    infoWindow.setPosition(center);
    infoWindow.open({
        map,
        anchor: marker,
        shouldFocus: false,
    });
}

initMap();
index.ts

جاوا اسکریپت 

let map;
let marker;
let infoWindow;

async function initMap() {
  // Request needed libraries.
  //@ts-ignore
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("marker"),
    google.maps.importLibrary("places"),
  ]);

  // Initialize the map.
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 40.749933, lng: -73.98633 },
    zoom: 13,
    mapId: "4504f8b37365c3d0",
    mapTypeControl: false,
  });

  //@ts-ignore
  const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();

  //@ts-ignore
  placeAutocomplete.id = "place-autocomplete-input";

  const card = document.getElementById("place-autocomplete-card");

  //@ts-ignore
  card.appendChild(placeAutocomplete);
  map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);
  // Create the marker and infowindow
  marker = new google.maps.marker.AdvancedMarkerElement({
    map,
  });
  infoWindow = new google.maps.InfoWindow({});
  // Add the gmp-placeselect listener, and display the results on the map.
  //@ts-ignore
  placeAutocomplete.addEventListener("gmp-placeselect", 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;
  });
}

// Helper function to create an info window.
function updateInfoWindow(content, center) {
  infoWindow.setContent(content);
  infoWindow.setPosition(center);
  infoWindow.open({
    map,
    anchor: marker,
    shouldFocus: false,
  });
}

initMap();
index.js

CSS 

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

#place-autocomplete-card {
  background-color: #fff;
  border-radius: 5px;
  box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
  margin: 10px;
  padding: 5px;
  font-family: Roboto, sans-serif;
  font-size: large;
  font-weight: bold;
}

gmp-place-autocomplete {
  width: 300px;
}

#infowindow-content .title {
  font-weight: bold;
}

#map #infowindow-content {
  display: inline;
}

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 class="place-autocomplete-card" id="place-autocomplete-card">
      <p>Search for a place here:</p>
    </div>
    <div id="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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "beta"});</script>
  </body>
</html>
index.html

Sample را امتحان کنید

از مولفه Place Picker استفاده کنید

جزء انتخابگر مکان یک ورودی متنی است که به کاربران نهایی امکان می دهد آدرس یا مکان خاصی را با استفاده از تکمیل خودکار جستجو کنند. این بخشی از Extended Component Library است، مجموعه‌ای از مؤلفه‌های وب که به توسعه‌دهندگان کمک می‌کند نقشه‌ها و ویژگی‌های مکان بهتری را سریع‌تر بسازند.

از پیکربندی Place Picker برای ایجاد کد قابل جاسازی برای یک مؤلفه Place Picker سفارشی استفاده کنید، سپس آن را صادر کنید تا با فریم ورک‌های محبوبی مانند React و Angular یا اصلاً فریمورک استفاده نشود.