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

توسعه‌دهندگان منطقه اقتصادی اروپا (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);

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

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

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

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

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

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

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

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

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

In the preceding example, the event listener receives a PlacePredictionSelectEvent and calls placePrediction.toPlace() to get a Place class (Place reference) instance. برای دریافت فیلدهای داده «جزئیات جا» که برای برنامه‌تان نیاز دارید، place.fetchFields() را فراخوانی کنید.

شنونده در مثال بعدی فیلدهای displayName، formattedAddress، location، و viewport را در place.fetchFields() درخواست می‌کند، سپس از place.viewport با fitBounds() برای نمایش مکان انتخاب‌شده روی نقشه استفاده می‌کند.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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>

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

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

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

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

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

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

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

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

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

  • اگر فقط به طول و عرض جغرافیایی یا نشانی مکان انتخابی کاربر نیاز دارید، Geocoding API این اطلاعات را با هزینه کمتری نسبت‌به فراخوانی Place Details (New)‎ ارائه می‌دهد.
  • اگر کاربران پیش‌بینی تکمیل خودکار را در میانگین چهار درخواست پیش‌بینی «تکمیل خودکار» (جدید) یا کمتر انتخاب کنند، قیمت‌گذاری به‌ازای درخواست می‌تواند مقرون‌به‌صرفه‌تر از قیمت‌گذاری به‌ازای جلسه باشد.
برای انتخاب پیاده‌سازی «تکمیل خودکار (جدید)» که کمترین هزینه را برای برنامه شما دارد، ردیفی را در جدول زیر پیدا کنید که با نیازهای برنامه شما مطابقت دارد.
آنچه برنامه شما نیاز دارد میانگین درخواست‌های «تکمیل خودکار» (جدید) قبل‌از اینکه کاربر پیش‌بینی‌ای را انتخاب کند پیاده‌سازی توصیه‌شده
جزئیات مکان به‌غیراز نشانی و مکان، مثل نام مکان، وضعیت کسب‌وکار، یا ساعت کاری هر شماره‌ای «تکمیل خودکار» مبتنی بر جلسه (جدید) با «جزئیات مکان» (جدید)
فقط نشانی و عرض/طول جغرافیایی پیش‌بینی انتخاب‌شده چهار یا کمتر «تکمیل خودکار» (جدید) برای هر درخواست با Geocoding API
فقط نشانی و عرض/طول جغرافیایی پیش‌بینی انتخاب‌شده بیشتر از چهار «تکمیل خودکار» مبتنی بر جلسه (جدید) برای برنامه‌های فقط نشانی

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

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

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

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

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

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

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

Per-request Autocomplete (New) with the Geocoding API

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

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

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

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

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

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

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

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

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

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

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

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

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

  • محدودیت‌های کشور، سوگیری مکان، و (برای پیاده‌سازی‌های برنامه‌ای) اولویت زبان را به پیاده‌سازی «تکمیل خودکار» (جدید) خود اضافه کنید. برای ابزاره‌ها به اولویت زبان نیازی نیست چون آن‌ها اولویت‌های زبان را از مرورگر یا دستگاه همراه کاربر انتخاب می‌کنند.
  • اگر Autocomplete (New) با نقشه همراه باشد، می‌توانید مکان را براساس نمای نقشه سوگیری کنید.
  • در شرایطی که کاربر یکی از پیش‌بینی‌های 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 برای فیلتر کردن نتایج استفاده کنید تا فقط مکان‌های داخل کشور مشخص‌شده نشان داده شود.

محدود کردن مکان

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

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