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

انتخاب پلاتفرم: Android iOS JavaScript

این 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>
index.html

توجه: ویژگی شناسه نقشه به تنظیمات پیکربندی و سبک‌دهی نقشه اجازه می‌دهد در Google Cloud ذخیره شود، و برای این مثال الزامی است. از شناسه DEMO_MAP_ID می‌توان برای آزمایش استفاده کرد و نیازی نیست در Cloud فعال شود.

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

به‌طور پیش‌فرض، «تکمیل خودکار مکان پایه» همه انواع مکان را ارائه می‌دهد و پیش‌بینی‌های نزدیک به مکان کاربر را اولویت می‌دهد. با محدود کردن یا متمایل کردن نتایج، 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(),
});

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

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 را ببینید.

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

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

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

این مثال نشان می‌دهد چگونه عنصر «تکمیل خودکار پایه» را به نقشه 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();
index.js

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;
}
style.css

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>
index.html