Places UI Kit : یک کتابخانه آماده برای استفاده که فضایی را برای سفارشی‌سازی و توسعه کم کد فراهم می‌کند. آن را امتحان کنید و نظرات خود را در مورد تجربه کیت UI خود به اشتراک بگذارید.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

ابزاره تکمیل خودکار جا

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

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

پیش‌نیازها

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

ویژگی‌های جدید

«تکمیل خودکار جا» به روش‌های زیر بهبود یافته است:

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

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

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

TypeScript

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

JavaScript

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

مشاهده نمونه کد کامل

اگر نشانی صورت‌حساب شما خارج از منطقه اقتصادی اروپا (EEA) باشد، می‌توانید از ابزارک «تکمیل خودکار» با «نقشه Google» نیز استفاده کنید.

برای افزودن ابزارک «تکمیل خودکار» به نقشه، ابتدا کتابخانه‌های موردنیاز را درخواست کنید، همان‌طور که در اینجا نشان داده شده است:

// In your TS or JS, request the needed libraries.
const { PlaceAutocompleteElement } = await google.maps.importLibrary("places");

سپس در HTML، عنصر gmp-place-autocomplete جدیدی را در div قرار دهید و آن div را در gmp-map قرار دهید، همان‌طور که در مثال زیر نشان داده شده است:

<gmp-map center="40.749933,-73.98633" zoom="13" map-id="DEMO_MAP_ID">
    <div
        class="place-autocomplete-card"
        slot="control-inline-start-block-start">
        <gmp-place-autocomplete
            placeholder="Search for a place..."></gmp-place-autocomplete>
    </div>
</gmp-map>index.html

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

// In your TS or JS, request the needed libraries.
const { PlaceAutocompleteElement } = await google.maps.importLibrary("places");

// Get the map element.
const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;

// Create the PlaceAutocompleteElement instance.
const placeAutocomplete = new PlaceAutocompleteElement({});

// Create a div and append the PlaceAutocompleteElement to it.
const card = document.createElement("div");
card.appendChild(placeAutocomplete);

// Apply the slot attribute to the div.
// This positions the control in the top-left corner of the map.
card.setAttribute("slot", "control-inline-start-block-start");

// Append the div to the map element (check for null).
if (mapElement) {
    mapElement.appendChild(card);
}

مشاهده نمونه کد کامل

افزودن نوشتار جای‌بان

از خصوصیت placeholder برای افزودن نوشتار جای‌بان استفاده کنید. مثال زیر تنظیم نوشتار جای‌بان را در HTML نشان می‌دهد:

<gmp-place-autocomplete
  placeholder="Search for a place..."
></gmp-place-autocomplete>

همچنین می‌توانید نوشتار جای‌بان را به‌صورت برنامه‌ریزی‌شده تنظیم کنید:

placeAutocomplete.placeholder = 'Search for a place...';

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

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

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

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

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

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

placeAutocomplete.includedRegionCodes = ['us', 'au'];;

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

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

// Use the bounds_changed event to restrict results to the current map bounds.
google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
    placeAutocomplete.locationRestriction = innerMap.getBounds();
});

برای برداشتن locationRestriction، آن را روی null تنظیم کنید.

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

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

placeAutocomplete.locationBias = {radius: 100, center: {lat: 40.749933, lng: -73.98633}};

برای برداشتن locationBias، آن را روی null تنظیم کنید.

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

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

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

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

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

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

TypeScript

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

JavaScript

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

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

در مثال قبلی، شنونده رویداد PlacePredictionSelectEvent را دریافت می‌کند و placePrediction.toPlace() را فرا می‌خواند تا نمونه‌ای از کلاس مکان (مرجع Place ) را دریافت کند. برای دریافت فیلدهای داده «جزئیات مکان» موردنیاز برای برنامه‌تان، place.fetchFields() را فراخوانی کنید.

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

TypeScript

// Add the gmp-select listener, and display the results on the map.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: [
                'displayName',
                'formattedAddress',
                'location',
                'viewport',
            ],
        });

        // If the place has a geometry, then present it on a map.
        if (place.viewport) {
            innerMap.fitBounds(place.viewport);
        } else {
            innerMap.setCenter(place.location!);
            innerMap.setZoom(17);
        }

        const content = document.createElement('div');
        const nameText = document.createElement('span');
        nameText.textContent = place.displayName ?? 'No name';
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        const addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress ?? 'No address';
        content.appendChild(addressText);

        updateInfoWindow(content, place.location);
        marker.position = place.location;
    }
);index.ts

JavaScript

// Add the gmp-select listener, and display the results on the map.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: [
                'displayName',
                'formattedAddress',
                'location',
                'viewport',
            ],
        });

        // If the place has a geometry, then present it on a map.
        if (place.viewport) {
            innerMap.fitBounds(place.viewport);
        } else {
            innerMap.setCenter(place.location);
            innerMap.setZoom(17);
        }

        const content = document.createElement('div');
        const nameText = document.createElement('span');
        nameText.textContent = place.displayName ?? 'No name';
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        const addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress ?? 'No address';
        content.appendChild(addressText);

        updateInfoWindow(content, place.location);
        marker.position = place.location;
    }
);index.js

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

نقشه‌های نمونه

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

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

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

TypeScript

async function init(): Promise<void> {
    // Request needed libraries.
    const { PlaceAutocompleteElement } =
        await google.maps.importLibrary('places');
    // Create the input HTML element, and append it.
    const placeAutocomplete = new PlaceAutocompleteElement();
    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-select listener, and display the results.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({
            placePrediction,
        }: google.maps.places.PlacePredictionSelectEvent) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: ['displayName', 'formattedAddress', 'location'],
            });
            selectedPlaceTitle.textContent = 'Selected Place:';
            selectedPlaceInfo.textContent = JSON.stringify(
                place.toJSON(),
                /* replacer */ null,
                /* space */ 2
            );
        }
    );
}

void init();index.ts

JavaScript

async function init() {
    // Request needed libraries.
    const { PlaceAutocompleteElement } =
        await google.maps.importLibrary('places');
    // Create the input HTML element, and append it.
    const placeAutocomplete = new PlaceAutocompleteElement();
    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-select listener, and display the results.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({ placePrediction }) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: ['displayName', 'formattedAddress', 'location'],
            });
            selectedPlaceTitle.textContent = 'Selected Place:';
            selectedPlaceInfo.textContent = JSON.stringify(
                place.toJSON(),
                /* replacer */ null,
                /* space */ 2
            );
        }
    );
}

void init();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>
        <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>
        <p style="font-family: roboto, sans-serif">Search for a place here:</p>
    </body>
</html>index.html

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

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

TypeScript

const mapElement = document.querySelector('gmp-map')!;
const placeAutocomplete = document.querySelector('gmp-place-autocomplete')!;
let innerMap: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
let infoWindow: google.maps.InfoWindow;
async function init(): Promise<void> {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Use the bounds_changed event to restrict results to the current map bounds.
    innerMap.addListener('bounds_changed', () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds()!;
    });

    // Create the marker and infoWindow.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    infoWindow = new InfoWindow();

    // Add the gmp-select listener, and display the results on the map.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({ placePrediction }) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: [
                    'displayName',
                    'formattedAddress',
                    'location',
                    'viewport',
                ],
            });

            // If the place has a geometry, then present it on a map.
            if (place.viewport) {
                innerMap.fitBounds(place.viewport);
            } else {
                innerMap.setCenter(place.location!);
                innerMap.setZoom(17);
            }

            const content = document.createElement('div');
            const nameText = document.createElement('span');
            nameText.textContent = place.displayName ?? 'No name';
            content.appendChild(nameText);
            content.appendChild(document.createElement('br'));
            const addressText = document.createElement('span');
            addressText.textContent = place.formattedAddress ?? 'No address';
            content.appendChild(addressText);

            updateInfoWindow(content, place.location);
            marker.position = place.location;
        }
    );
}

// Helper function to create an info window.
function updateInfoWindow(
    content: string | Element | Text | null | undefined,
    center: google.maps.LatLng | google.maps.LatLngLiteral | null | undefined
) {
    infoWindow.setContent(content);
    infoWindow.setPosition(center);
    infoWindow.open({
        map: innerMap,
        anchor: marker,
        shouldFocus: false,
    });
}

void init();index.ts

JavaScript

const mapElement = document.querySelector('gmp-map');
const placeAutocomplete = document.querySelector('gmp-place-autocomplete');
let innerMap;
let marker;
let infoWindow;
async function init() {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Use the bounds_changed event to restrict results to the current map bounds.
    innerMap.addListener('bounds_changed', () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds();
    });

    // Create the marker and infoWindow.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    infoWindow = new InfoWindow();

    // Add the gmp-select listener, and display the results on the map.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({ placePrediction }) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: [
                    'displayName',
                    'formattedAddress',
                    'location',
                    'viewport',
                ],
            });

            // If the place has a geometry, then present it on a map.
            if (place.viewport) {
                innerMap.fitBounds(place.viewport);
            } else {
                innerMap.setCenter(place.location);
                innerMap.setZoom(17);
            }

            const content = document.createElement('div');
            const nameText = document.createElement('span');
            nameText.textContent = place.displayName ?? 'No name';
            content.appendChild(nameText);
            content.appendChild(document.createElement('br'));
            const addressText = document.createElement('span');
            addressText.textContent = place.formattedAddress ?? 'No address';
            content.appendChild(addressText);

            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: innerMap,
        anchor: marker,
        shouldFocus: false,
    });
}

void init();index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
gmp-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: small;
}

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>
        <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 center="40.749933,-73.98633" zoom="13" map-id="DEMO_MAP_ID">
            <div
                class="place-autocomplete-card"
                slot="control-inline-start-block-start">
                <gmp-place-autocomplete
                    placeholder="Search for a place..."></gmp-place-autocomplete>
            </div>
        </gmp-map>
    </body>
</html>index.html

بهینه‌سازی تکمیل خودکار (جدید)

این بخش روال‌های مطلوب را شرح می‌دهد تا به شما کمک کند بیشترین بهره را از سرویس «تکمیل خودکار» (جدید) ببرید.

در اینجا چند دستورالعمل کلی آمده است:

سریع‌ترین راه برای توسعه یک میانای کاربری کاربردی استفاده از ویجت تکمیل خودکار (جدید) در Maps JavaScript API، ویجت تکمیل خودکار (جدید) در Places SDK for Android، یا ویجت تکمیل خودکار (جدید) در Places SDK for iOS است.
از همان ابتدا با فیلدهای داده ضروری «تکمیل خودکار» (جدید) آشنا شوید.
فیلدهای «سوگیری مکان» و «محدودیت مکان» اختیاری هستند اما می‌توانند تأثیر قابل‌توجهی بر عملکرد تکمیل خودکار داشته باشند.
از مدیریت خطا استفاده کنید تا مطمئن شوید که اگر میانای برنامه‌سازی کاربردی خطایی برگرداند، برنامه شما به‌خوبی تنزل پیدا می‌کند.
مطمئن شوید که برنامه‌تان شرایطی را که هیچ انتخابی وجود ندارد مدیریت می‌کند و راهی برای ادامه دادن به کاربران ارائه می‌دهد.

روال‌های مطلوب بهینه‌سازی هزینه

بهینه‌سازی هزینه پایه

برای بهینه‌سازی هزینه استفاده از سرویس «تکمیل خودکار (جدید)»، از ماسک‌های فیلد در ابزاره‌های «جزئیات مکان (جدید)» و «تکمیل خودکار (جدید)» استفاده کنید تا فقط فیلدهای داده «تکمیل خودکار (جدید)» موردنیازتان برگردانده شود.

بهینه‌سازی پیشرفته هزینه

برای دسترسی به واحد نگهداری موجودی: قیمت‌گذاری درخواست تکمیل خودکار و درخواست نتایج Geocoding API درباره مکان انتخاب‌شده به‌جای «جزئیات مکان» (جدید)، پیاده‌سازی برنامه‌ریزی‌شده «تکمیل خودکار» (جدید) را درنظر بگیرید. اگر هر دو شرط زیر برقرار باشد، قیمت‌گذاری به‌ازای درخواست همراه با Geocoding API مقرون‌به‌صرفه‌تر از قیمت‌گذاری به‌ازای جلسه (جلسه‌محور) است:

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

برای دریافت راهنمایی در انتخاب پیاده‌سازی «تکمیل خودکار (جدید)» که مناسب نیازهایتان باشد، برگه‌ای را که با پاسخ شما به سؤال زیر مطابقت دارد انتخاب کنید.

آیا برنامه شما به اطلاعات دیگری غیراز نشانی و طول/عرض جغرافیایی پیش‌بینی انتخابی نیاز دارد؟

بله، به جزئیات بیشتری نیاز است

از «تکمیل خودکار» (جدید) مبتنی بر جلسه با «جزئیات مکان» (جدید) استفاده کنید.
ازآنجایی‌که برنامه شما به «جزئیات مکان (جدید)» مانند نام مکان، وضعیت کسب‌وکار، یا ساعت کاری نیاز دارد، پیاده‌سازی شما از «تکمیل خودکار (جدید)» باید از کد جلسه استفاده کند (به‌صورت برنامه‌نویسی‌شده یا تعبیه‌شده در ابزاره‌های JavaScript، Android، یا iOS) به‌ازای هر جلسه به‌علاوه شناسه‌های یکتای کالای «مکان‌ها»ی مربوطه، بسته به اینکه کدام فیلدهای داده مکان را درخواست می‌کنید.^۱

پیاده‌سازی ابزاره
مدیریت جلسه به‌طور خودکار در ابزاره‌های JavaScript، Android، یا iOS ساخته می‌شود. این شامل درخواست‌های «تکمیل خودکار» (جدید) و درخواست «جزئیات مکان» (جدید) در پیش‌بینی انتخاب‌شده می‌شود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید فقط فیلدهای داده «تکمیل خودکار (جدید)» موردنیازتان را درخواست می‌کنید.

پیاده‌سازی برنامه‌ریزی‌شده
از کد جلسه با درخواست‌های «تکمیل خودکار» (جدید) استفاده کنید. هنگام درخواست «جزئیات مکان (جدید)» درباره پیش‌بینی انتخاب‌شده، پارامترهای زیر را اضافه کنید:

شناسه مکان از پاسخ «تکمیل خودکار (جدید)»
کد جلسه استفاده‌شده در درخواست «تکمیل خودکار (جدید)»
پارامتر fields که فیلدهای داده «تکمیل خودکار (جدید)» موردنیازتان را مشخص می‌کند

نه، فقط به نشانی و مکان نیاز دارد

Geocoding API می‌تواند گزینه مقرون‌به‌صرفه‌تری نسبت‌به Place Details (New) برای برنامه شما باشد، بسته به عملکرد استفاده شما از Autocomplete (New). کارایی «تکمیل خودکار (جدید)» هر برنامه بسته به آنچه کاربران وارد می‌کنند، جایی که برنامه استفاده می‌شود، و اینکه آیا روال‌های مطلوب بهینه‌سازی عملکرد اجرا شده است یا نه متفاوت است.

برای پاسخ دادن به سؤال زیر، تحلیل کنید که کاربر به‌طور میانگین چند نویسه تایپ می‌کند تا پیش‌بینی «تکمیل خودکار» (جدید) را در برنامه‌تان انتخاب کند.

آیا کاربران شما به‌طور میانگین با چهار درخواست یا کمتر، پیش‌بینی «تکمیل خودکار (جدید)» را انتخاب می‌کنند؟

بله

«تکمیل خودکار» (جدید) را به‌صورت برنامه‌نویسی‌شده بدون کد جلسه پیاده‌سازی کنید و Geocoding API را در پیش‌بینی مکان انتخاب‌شده فراخوانی کنید.
Geocoding API نشانی‌ها و مختصات طول/عرض جغرافیایی را ارائه می‌دهد. انجام چهار درخواست تکمیل خودکار به‌علاوه یک فراخوانی Geocoding API درباره پیش‌بینی مکان انتخاب‌شده کمتر از هزینه هر جلسه «تکمیل خودکار (جدید)» است.^۱

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

نه

از «تکمیل خودکار مبتنی بر جلسه» (جدید) با «جزئیات مکان» (جدید) استفاده کنید.
ازآنجایی‌که تعداد میانگین درخواست‌هایی که انتظار دارید قبل‌از اینکه کاربر پیش‌بینی «تکمیل خودکار (جدید)» را انتخاب کند ایجاد کنید از هزینه قیمت‌گذاری به‌ازای هر جلسه فراتر می‌رود، پیاده‌سازی «تکمیل خودکار (جدید)» شما باید برای درخواست‌های «تکمیل خودکار (جدید)» و درخواست «جزئیات مکان (جدید)» مرتبط از کد جلسه استفاده کند. ^۱

پیاده‌سازی ابزاره
مدیریت جلسه به‌طور خودکار در ابزاره‌های JavaScript، Android، یا iOS ساخته می‌شود. این شامل درخواست‌های «تکمیل خودکار» (جدید) و درخواست «جزئیات مکان» (جدید) در پیش‌بینی انتخاب‌شده می‌شود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید فقط فیلدهای موردنیازتان را درخواست می‌کنید.

پیاده‌سازی برنامه‌ریزی‌شده
از نشانه جلسه با درخواست‌های «تکمیل خودکار (جدید)» استفاده کنید. هنگام درخواست «جزئیات مکان (جدید)» درباره پیش‌بینی انتخاب‌شده، پارامترهای زیر را اضافه کنید:

شناسه مکان از پاسخ «تکمیل خودکار (جدید)»
کد جلسه استفاده‌شده در درخواست «تکمیل خودکار (جدید)»
پارامتر fields که فیلدهایی مثل نشانی و هندسه را مشخص می‌کند

به‌تأخیر انداختن درخواست‌های «تکمیل خودکار» (جدید) را مدنظر قرار دهید
می‌توانید از استراتژی‌هایی مانند به‌تأخیر انداختن درخواست «تکمیل خودکار» (جدید) تا زمانی که کاربر سه یا چهار نویسه اول را تایپ کند استفاده کنید تا برنامه‌تان درخواست‌های کمتری ارسال کند. برای مثال، ارسال درخواست‌های «تکمیل خودکار (جدید)» برای هر نویسه پس‌از اینکه کاربر نویسه سوم را تایپ کرد به این معنی است که اگر کاربر هفت نویسه تایپ کند و سپس پیش‌بینی‌ای را انتخاب کند که برای آن یک درخواست Geocoding API ارسال می‌کنید، هزینه کل برای ۴ درخواست «تکمیل خودکار (جدید)» به‌ازای هر درخواست + Geocoding خواهد بود.^۱

اگر با به‌تأخیر انداختن درخواست‌ها می‌توانید میانگین درخواست‌های برنامه‌ریزی‌شده را به زیر چهار برسانید، می‌توانید راهنمای پیاده‌سازی «تکمیل خودکار (جدید)» با Geocoding API را دنبال کنید. توجه داشته باشید که تأخیر در درخواست‌ها می‌تواند ازسوی کاربر به‌عنوان تأخیر درک شود، زیرا ممکن است کاربر انتظار داشته باشد با هر ضربه کلید جدید، پیش‌بینی‌ها را ببیند.

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

برای اطلاع از هزینه‌ها، فهرست‌های قیمت‌گذاری «پلاتفرم Google Maps» را ببینید.

روال‌های مطلوب عملکرد

دستورالعمل‌های زیر روش‌های بهینه‌سازی عملکرد «تکمیل خودکار (جدید)» را شرح می‌دهد:

محدودیت‌های کشور، انحراف مکان، و (برای پیاده‌سازی‌های برنامه‌ریزی‌شده) اولویت زبان را به پیاده‌سازی «تکمیل خودکار» (جدید) اضافه کنید. برای ابزاره‌ها به اولویت زبان نیازی نیست چون آن‌ها اولویت‌های زبان را از مرورگر یا دستگاه همراه کاربر انتخاب می‌کنند.
اگر «تکمیل خودکار (جدید)» با نقشه همراه باشد، می‌توانید مکان را براساس نمای درگاه نقشه گرایش دهید.
در شرایطی که کاربر یکی از پیش‌بینی‌های Autocomplete (New) را انتخاب نمی‌کند، معمولاً به این دلیل که هیچ‌کدام از آن پیش‌بینی‌ها نشانی نتیجه موردنظر نیست، می‌توانید از ورودی اصلی کاربر مجدداً استفاده کنید تا نتایج مرتبط‌تری دریافت کنید:
- اگر انتظار دارید کاربر فقط اطلاعات نشانی را وارد کند، ورودی کاربر اصلی را در تماس با Geocoding API دوباره استفاده کنید.
- اگر انتظار دارید کاربر پُرسمان‌های مربوط به مکان خاصی را براساس نام یا نشانی وارد کند، از درخواست «جزئیات مکان (جدید)» استفاده کنید. اگر نتایج فقط در منطقه خاصی موردانتظار است، از سوگیری مکان استفاده کنید.
سناریوهای دیگری که بهتر است به Geocoding API برگردید عبارت‌اند از:
- کاربرانی که نشانی‌های فرعی وارد می‌کنند، مثل نشانی‌های واحدهای خاص یا آپارتمان‌ها در یک ساختمان. برای مثال، نشانی چک «Stroupežnického 3191/17, Praha» پیش‌بینی جزئی در «تکمیل خودکار» (جدید) ارائه می‌دهد.
- کاربرانی که نشانی‌ها را با پیشوند بخش جاده وارد می‌کنند، مانند «23-30 29th St, Queens» در شهر نیویورک یا «47-380 Kamehameha Hwy, Kaneohe» در جزیره کائوآئی در هاوایی.

انحراف مکانی

با ارسال پارامتر location و پارامتر radius، نتایج را به منطقه مشخصی متمایل کنید. این دستور به «تکمیل خودکار (جدید)» می‌گوید که نمایش نتایج در محدوده تعریف‌شده را ترجیح دهد. نتایج خارج از منطقه تعریف‌شده ممکن است همچنان نمایش داده شود. می‌توانید از پارامتر includedRegionCodes برای فیلتر کردن نتایج استفاده کنید تا فقط مکان‌های درون کشور مشخص‌شده را نشان دهد.

هشدار: اگر radius ارائه نشود، پارامتر location نادیده گرفته می‌شود.

نتایج مربوط به مؤسسه‌ها معمولاً رتبه بالایی ندارند که درصورت بزرگ بودن منطقه جستجو در نتایج نشان داده شوند. اگر می‌خواهید مؤسسه‌ها در نتایج مختلط مؤسسه/مختصات جغرافیایی نشان داده شوند، می‌توانید شعاع کوچک‌تری را مشخص کنید. همچنین می‌توانید از types=establishment برای محدود کردن نتایج فقط به مؤسسه‌ها استفاده کنید.

مکان محدودکننده

با ارسال پارامتر locationRestriction، نتایج را به منطقه مشخصی محدود کنید.

همچنین می‌توانید با افزودن پارامتر locationRestriction نتایج را به منطقه‌ای که با location و پارامتر radius تعریف شده است محدود کنید. این دستور به «تکمیل خودکار (جدید)» می‌دهد که فقط نتایج را در آن منطقه برگرداند.

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

پیش‌نیازها

ویژگی‌های جدید

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

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

TypeScript

JavaScript

افزودن ابزاره «تکمیل خودکار» به نقشه

افزودن نوشتار جای‌بان

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

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

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

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

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

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

TypeScript

JavaScript

TypeScript

JavaScript

نقشه‌های نمونه

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

TypeScript

JavaScript

CSS

HTML

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

TypeScript

JavaScript

CSS

HTML

بهینه‌سازی تکمیل خودکار (جدید)

روال‌های مطلوب بهینه‌سازی هزینه

بهینه‌سازی هزینه پایه

بهینه‌سازی پیشرفته هزینه

بله، به جزئیات بیشتری نیاز است

نه، فقط به نشانی و مکان نیاز دارد

بله

نه

روال‌های مطلوب عملکرد

انحراف مکانی

مکان محدودکننده

ابزاره تکمیل خودکار جا