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

توسعه‌دهندگان منطقه اقتصادی اروپا (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» نیز استفاده کنید.

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

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

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

در مثال قبلی، شنونده رویداد PlacePredictionSelectEvent را دریافت می‌کند و placePrediction.toPlace() را فرا می‌خواند تا نمونه‌ای از کلاس مکان (مرجع Place ) را دریافت کند. برای دریافت 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 اضافه کنید.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

بله

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

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

نه

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

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

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

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

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

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

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

  1. برای اطلاع از هزینه‌ها، فهرست قیمت‌های «پلاتفرم 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 برای فیلتر کردن نتایج استفاده کنید تا فقط مکان‌های داخل کشور مشخص‌شده نشان داده شود.

محدودیت مکان

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

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