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

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

پیش نیازها

برای استفاده از 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);

جاوا اسکریپت

// 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);

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

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

برای افزودن یک ویجت تکمیل خودکار به نقشه، یک نمونه جدید 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);

جاوا اسکریپت

//@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);

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

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

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

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

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

برای محدود کردن جستجوی مکان به یک یا چند کشور خاص، از ویژگی 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-place-select به 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);
});

جاوا اسکریپت

// 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,
  );
});

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

در مثال قبل، شنونده رویداد یک شی از کلاس 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;
});

جاوا اسکریپت

// 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;
});

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

نتایج کدگذاری جغرافیایی را برای مکان انتخاب شده دریافت کنید

برای دریافت نتایج کدگذاری جغرافیایی برای مکان انتخاب شده، از google.maps.Geocoder برای دریافت مکان استفاده کنید، همانطور که در قطعه زیر نشان داده شده است:

const map = new google.maps.Map(document.getElementById('map'), {
  center: {lat: 50.064192, lng: -130.605469},
  zoom: 3,
});

const marker = new google.maps.Marker({map});
const autocomplete = new google.maps.places.PlaceAutocompleteElement();
const geocoder = new google.maps.Geocoder();

autocomplete.addListener('gmp-placeselect', async ({prediction: place}) => {
  const results = await geocoder.geocode({place.id});
  marker.setPlace({
    placeId: place.id,
    location: results[0].geometry.location,
  });
});

نمونه نقشه ها

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

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

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

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();

جاوا اسکریپت

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();

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;
}

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>

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();

جاوا اسکریپت

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();

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;
}

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>

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

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

توجه: این نمونه از یک کتابخانه متن باز استفاده می کند. برای پشتیبانی و بازخورد مربوط به کتابخانه به README مراجعه کنید.

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

پیکربندی Place Picker

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

شروع کنید

برای شروع، کتابخانه Extended Component را با npm بارگیری کنید.

برای بهترین عملکرد، از یک مدیریت بسته استفاده کنید و فقط اجزای مورد نیاز خود را وارد کنید. این بسته در npm با نام @googlemaps/extended-component-library فهرست شده است. نصبش کن با:

  npm i @googlemaps/extended-component-library;

سپس هر مؤلفه ای را که در برنامه خود استفاده می کنید وارد کنید.

  import '@googlemaps/extended-component-library/place_picker.js';

پس از بارگیری کتابخانه npm، یک کلید API از کنسول Cloud دریافت کنید .

  <gmpx-api-loader key="YOUR_API_KEY" solution-channel="GMP_DOCS_placepicker_v1"></gmpx-api-loader>

از تگ جزء انتخابگر مکان استفاده کنید.

  <gmpx-place-picker placeholder="Enter a place" id="place-picker" style="width: 100%">
  </gmpx-place-picker>

برای جزئیات بیشتر، GitHub یا npm را بررسی کنید. برای دیدن اجزای مورد استفاده در کد نمونه، صفحه نمونه ها را در GitHub بررسی کنید.