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

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

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

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

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

پیش‌نیازها

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

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

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

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

ابزارک «تکمیل خودکار» فیلد ورودی نوشتاری ایجاد می‌کند، پیش‌بینی‌های مکان را در فهرست انتخاب میانای کاربری ارائه می‌دهد، و جزئیات مکان را در پاسخ به کلیک کاربر بااستفاده از شنودگر 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 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>index.html

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

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

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

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

برای دریافت جزئیات مکان برای مکان انتخاب‌شده، شنودگر 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

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

در مثال قبلی، شنونده رویداد شیئی از کلاس 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 نشانی‌ها و مختصات عرض جغرافیایی/طول جغرافیایی را ارائه می‌دهد. انجام چهار درخواست درخواست تکمیل خودکار به‌علاوه یک تماس Geocoding API درباره پیش‌بینی مکان انتخابی کمتر از هزینه «تکمیل خودکار» (جدید) به‌ازای هر جلسه است.^۱

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

نه

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

بله

نه

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

انحراف مکانی

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

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