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

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

پیاده‌سازی عنصر «تکمیل خودکار جا» ساده‌تر از PlaceAutocompleteElement است و از جنبه‌های زیر با آن تفاوت دارد:

  • عنصر «تکمیل خودکار جا» پایه، شیء جا را برمی‌گرداند که فقط حاوی شناسه جا است، نه شیء PlacePrediction. می‌توانید از شناسه مکان برگردانده‌شده مستقیماً با عنصر جزئیات کیت میانای کاربر «جاها» استفاده کنید تا جزئیات مکان بیشتری دریافت کنید، درحالی‌که شیء PlacePrediction ابتدا باید به شناسه مکان تبدیل شود.
  • عنصر «تکمیل خودکار جا» پایه نیازی به فعال کردن Places API در «کنسول Google Cloud» ندارد.
  • وقتی کاربر پیش‌بینی مکانی را انتخاب می‌کند، عنصر «تکمیل خودکار جا» پایه فیلد ورودی را پاک می‌کند.

پیش‌نیازها

برای استفاده از عنصر «تکمیل خودکار جا» پایه، باید «کیت میانای کاربر جاها» را در پروژه Google Cloud خود فعال کنید. برای جزئیات، به شروع به کار مراجعه کنید.

افزودن عنصر «تکمیل خودکار جا» پایه

این بخش به شما نشان می‌دهد که چگونه یک عنصر «تکمیل خودکار پایه» را به صفحه وب یا نقشه اضافه کنید.

افزودن عنصر «تکمیل خودکار پایه» به صفحه وب

برای افزودن عنصر 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 را به عنصر gmp-map اضافه کنید و موقعیت آن را بااستفاده از مشخصه slot تنظیم کنید، همان‌طور که در مثال زیر نشان داده شده است:

<gmp-map
    zoom="12"
    center="37.4220656,-122.0840897"
    map-id="DEMO_MAP_ID">
    <gmp-basic-place-autocomplete
        slot="control-inline-start-block-start"></gmp-basic-place-autocomplete>
</gmp-map>

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

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

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

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

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

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

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

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

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

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

When restricting to map bounds, be sure to add a listener to update the bounds when they change:

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

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

پیکربندی عنصر «درخواست مکان»

شنونده‌ای اضافه کنید تا وقتی کاربر پیش‌بینی‌ای را انتخاب می‌کند، عنصر «درخواست مکان» به‌روز شود: 

// Event listener for when a place is selected from the autocomplete list.
placeAutocompleteElement.addEventListener('gmp-select', (event) => {
    // Reset marker and InfoWindow, and prepare the details element.
    placeDetailsParent.appendChild(placeDetailsElement);
    placeDetailsElement.style.display = 'block';
    advancedMarkerElement.position = null;
    infoWindow.close();

    // Request details for the selected place.
    const placeDetailsRequest = placeDetailsElement.querySelector(
        'gmp-place-details-place-request'
    );
    placeDetailsRequest.place = event.place.id;
});

این مثال به شما نشان می‌دهد که چگونه یک عنصر «تکمیل خودکار پایه» را به نقشه Google اضافه کنید.

JavaScript

const placeAutocompleteElement = document.querySelector(
    'gmp-basic-place-autocomplete'
);
const placeDetailsElement = document.querySelector('gmp-place-details-compact');
const placeDetailsParent = placeDetailsElement.parentElement;
const gmpMapElement = document.querySelector('gmp-map');

async function init() {
    // Asynchronously load required libraries from the Google Maps JS API.
    const [{ AdvancedMarkerElement }, { InfoWindow, Circle }, { Size }] =
        await Promise.all([
            google.maps.importLibrary('marker'),
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('core'),
            google.maps.importLibrary('places'),
        ]);

    // Get the initial center directly from the gmp-map element's property.
    const center = gmpMapElement.center;

    // Set the initial location bias for the autocomplete element.
    placeAutocompleteElement.locationBias = center;

    // Update the map object with specified options.
    const map = gmpMapElement.innerMap;
    map.setOptions({
        clickableIcons: false,
        mapTypeControl: false,
        streetViewControl: false,
    });

    // Create an advanced marker to show the location of a selected place.
    const advancedMarkerElement = new AdvancedMarkerElement({
        map,
        collisionBehavior: 'REQUIRED_AND_HIDES_OPTIONAL',
    });

    // Create an InfoWindow to hold the place details component.
    const infoWindow = new InfoWindow({
        minWidth: 360,
        disableAutoPan: true,
        headerDisabled: true,
        pixelOffset: new Size(0, -10),
    });

    // Event listener for when a place is selected from the autocomplete list.
    placeAutocompleteElement.addEventListener('gmp-select', (event) => {
        // Reset marker and InfoWindow, and prepare the details element.
        placeDetailsParent.appendChild(placeDetailsElement);
        placeDetailsElement.style.display = 'block';
        advancedMarkerElement.position = null;
        infoWindow.close();

        // Request details for the selected place.
        const placeDetailsRequest = placeDetailsElement.querySelector(
            'gmp-place-details-place-request'
        );
        placeDetailsRequest.place = event.place.id;
    });

    // Event listener for when the place details have finished loading.
    placeDetailsElement.addEventListener('gmp-load', () => {
        const location = placeDetailsElement.place?.location;
        if (!location) {
            advancedMarkerElement.position = null;
            return;
        }

        // Position the marker and open the InfoWindow at the place's location.
        advancedMarkerElement.position = location;
        infoWindow.setContent(placeDetailsElement);
        infoWindow.open({
            map,
            anchor: advancedMarkerElement,
        });
        map.setCenter(location);
    });

    // Event listener to close the InfoWindow when the map is clicked.
    map.addListener('click', () => {
        infoWindow.close();
        advancedMarkerElement.position = null;
    });

    // Event listener for when the map finishes moving (panning or zooming).
    map.addListener('idle', () => {
        const newCenter = map.getCenter();

        // Update the autocomplete's location bias to a 10km radius around the new map center.
        placeAutocompleteElement.locationBias = new Circle({
            center: newCenter,
            radius: 10000, // 10km in meters.
        });
    });
}

void init();

CSS

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

gmp-map {
    height: 100%;
}

gmp-basic-place-autocomplete {
    position: absolute;
    height: 30px;
    width: 500px;
    top: 10px;
    left: 10px;
    box-shadow: 4px 4px 5px 0px rgba(0, 0, 0, 0.2);
    color-scheme: light;
    border-radius: 10px;
}

HTML

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

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <gmp-map
            zoom="12"
            center="37.4220656,-122.0840897"
            map-id="DEMO_MAP_ID">
            <gmp-basic-place-autocomplete
                slot="control-inline-start-block-start"></gmp-basic-place-autocomplete>
        </gmp-map>
        <!-- Use inline styles to configure the Place Details Compact element because
     it will be placed within the info window, and info window content is inside 
     the shadow DOM when using <gmp-map> -->
        <gmp-place-details-compact
            orientation="horizontal"
            style="
                width: 400px;
                display: none;
                border: none;
                padding: 0;
                margin: 0;
                background-color: transparent;
                color-scheme: light;
            ">
            <gmp-place-details-place-request></gmp-place-details-place-request>
            <gmp-place-standard-content></gmp-place-standard-content>
        </gmp-place-details-compact>
    </body>
</html>