الحصول على مفتاح Maps Demo Key: يمكنك تجربة ميزات محدّدة من Maps JavaScript API و"حزمة أدوات خرائط Google الجاهزة للأماكن" بدون أي تكلفة باستخدام مفتاح Maps Demo Key، وبدون الحاجة إلى إدخال معلومات الفوترة.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

التطبيق المصغّر للإكمال التلقائي للأماكن

المطوّرون في المنطقة الاقتصادية الأوروبية

تنشئ "أداة الإكمال التلقائي للأماكن" حقل إدخال نصي، وتوفّر توقعات الأماكن في قائمة اختيار ضمن واجهة المستخدم، وتعرض تفاصيل المكان استجابةً لاختيار المستخدم. استخدِم "تطبيق الإكمال التلقائي للأماكن" لتضمين واجهة مستخدم كاملة ومستقلة للإكمال التلقائي في صفحة الويب. للاطّلاع على مرجع واجهة برمجة التطبيقات الكامل، يُرجى الانتقال إلى PlaceAutocompleteElement.

المتطلبات الأساسية

لاستخدام ميزة "الإكمال التلقائي للمكان"، يجب تفعيل Places API (الجديدة) في مشروعك على Google Cloud. لمزيد من التفاصيل، يُرجى الاطّلاع على البدء.

الميزات الجديدة

تم تحسين ميزة "الإكمال التلقائي للأماكن" بالطرق التالية:

تتيح واجهة مستخدم التطبيق المصغّر لميزة "الإكمال التلقائي" الترجمة الإقليمية (بما في ذلك اللغات التي تُكتب من اليمين إلى اليسار)، وذلك للعنصر النائب لإدخال النص وشعار قائمة عبارات البحث المقترَحة وعبارات البحث المقترَحة للأماكن.
تحسين أدوات تسهيل الاستخدام، بما في ذلك إتاحة استخدام قارئ الشاشة والتفاعل مع لوحة المفاتيح
تعرض أداة الإكمال التلقائي فئة المكان الجديدة (مرجع Place) لتبسيط معالجة العنصر المعروض.
دعم أفضل للأجهزة الجوّالة والشاشات الصغيرة
أداء أفضل ومظهر رسومي محسّن

تنشئ أداة "الإكمال التلقائي" حقل إدخال نص، وتوفّر توقّعات الأماكن في قائمة اختيار ضمن واجهة المستخدم، وتعرض تفاصيل المكان استجابةً لنقرة المستخدم باستخدام أداة الاستماع gmp-select. يوضّح هذا القسم كيفية إضافة تطبيق مصغّر للإكمال التلقائي إلى صفحة ويب أو خريطة Google.

لإضافة تطبيق "الإكمال التلقائي" المصغّر إلى صفحة ويب، أنشئ عنصر google.maps.places.PlaceAutocompleteElement جديدًا، وألحِقه بالصفحة كما هو موضّح في المثال التالي:

TypeScript

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

JavaScript

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

الاطّلاع على مثال الرمز الكامل

إذا كان عنوان إرسال الفواتير خارج المنطقة الاقتصادية الأوروبية، يمكنك أيضًا استخدام تطبيق "الإكمال التلقائي" المصغّر مع "خرائط Google".

لإضافة تطبيق مصغّر للإكمال التلقائي إلى خريطة، اطلب أولاً المكتبات المطلوبة، كما هو موضّح هنا:

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

بعد ذلك، في ملف HTML، يمكنك دمج عنصر gmp-place-autocomplete جديد داخل div، ودمج عنصر div هذا داخل gmp-map، كما هو موضّح في المثال التالي:

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

لإضافة تطبيق مصغّر للإكمال التلقائي إلى خريطة بشكل آلي، أنشئ مثيلاً جديدًا من google.maps.places.PlaceAutocompleteElement، وأضِف PlaceAutocompleteElement إلى div، وطبِّق السمة slot على div، كما هو موضّح في المثال التالي:

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

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

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

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

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

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

الاطّلاع على مثال الرمز الكامل

إضافة نص مؤقت

استخدِم السمة placeholder لإضافة نص مؤقت. يوضّح المثال التالي كيفية ضبط النص المؤقت في HTML:

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

يمكنك أيضًا ضبط النص المؤقت آليًا:

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

تقييد عبارات البحث المقترحة من خلال ميزة "الإكمال التلقائي"

تعرض ميزة "الإكمال التلقائي للأماكن" تلقائيًا جميع أنواع الأماكن، مع التركيز على التوقّعات القريبة من الموقع الجغرافي للمستخدم، وتجلب جميع حقول البيانات المتاحة للمكان الذي اختاره المستخدم. اضبط PlaceAutocompleteElementOptions لعرض عبارات بحث مقترَحة أكثر صلة بالموضوع، وذلك من خلال حصر النتائج أو تحيزها.

يؤدي حصر النتائج إلى تجاهل تطبيق "الإكمال التلقائي" المصغّر لأي نتائج خارج منطقة الحصر. من الممارسات الشائعة حصر النتائج بحدود الخريطة. يؤدي تحيز النتائج إلى جعل تطبيق الإكمال التلقائي المصغّر يعرض النتائج ضمن المنطقة المحددة، ولكن قد تكون بعض النتائج المطابقة خارج تلك المنطقة.

إذا لم تقدّم أي حدود أو إطار عرض للخريطة، ستحاول واجهة برمجة التطبيقات رصد الموقع الجغرافي للمستخدم من عنوان IP الخاص به، وستوجّه النتائج إلى ذلك الموقع الجغرافي. اضبط حدودًا كلما أمكن ذلك. وإلا، قد يتلقّى مستخدمون مختلفون توقّعات مختلفة. لتحسين التوقّعات بشكل عام، من المهم أيضًا توفير إطار عرض معقول، مثل إطار العرض الذي تضبطه من خلال التحريك أو التكبير/التصغير على الخريطة، أو إطار عرض يحدّده المطوّر استنادًا إلى الموقع الجغرافي للجهاز ونطاقه الجغرافي. وعندما لا يتوفّر نطاق جغرافي، يتم اعتبار 5 كيلومترات كقيمة تلقائية معقولة لميزة "الإكمال التلقائي للأماكن". لا تضبط إطار عرض بنصف قطر يساوي صفرًا (نقطة واحدة) أو إطار عرض يمتد لبضعة أمتار فقط (أقل من 100 متر) أو إطار عرض يمتد على مستوى العالم.

حصر البحث عن الأماكن حسب البلد

لحصر البحث عن الأماكن في بلد واحد أو أكثر، استخدِم السمة includedRegionCodes لتحديد رموز البلدان كما هو موضّح في المقتطف التالي (يفترض ذلك أنّك أنشأت مثيلاً باسم placeAutocomplete):

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

حصر البحث عن الأماكن ضمن حدود الخريطة

لحصر البحث عن الأماكن ضمن حدود الخريطة، استخدِم السمة locationRestriction. يوضّح المقتطف التالي كيفية إضافة مستمع لتعديل الحدود عند تغييرها:

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

لإزالة locationRestriction، اضبطه على null.

تحيز نتائج البحث عن الأماكن

يمكنك تحديد نتائج البحث عن الأماكن في منطقة دائرية باستخدام السمة locationBias كما هو موضّح هنا:

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

لإزالة locationBias، اضبطه على null.

حصر نتائج البحث عن الأماكن بأنواع معيّنة

يمكنك حصر نتائج البحث عن الأماكن على أنواع معيّنة من الأماكن باستخدام السمة includedPrimaryTypes وتحديد نوع واحد أو أكثر، كما هو موضّح هنا:

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

للحصول على قائمة كاملة بالأنواع المتوافقة، يُرجى الاطّلاع على الجدولَين "أ" و"ب" لأنواع الأماكن.

الحصول على تفاصيل المكان

للحصول على تفاصيل المكان المحدّد، أضِف مستمعًا من النوع gmp-select إلى PlaceAutocompleteElement، كما هو موضّح في المثال التالي:

TypeScript

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

JavaScript

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

الاطّلاع على مثال الرمز الكامل

في المثال السابق، يتلقّى متتبِّع الأحداث PlacePredictionSelectEvent ويستدعي placePrediction.toPlace() للحصول على مثيل فئة المكان (مرجع Place). استدعِ place.fetchFields() للحصول على حقول بيانات تفاصيل المكان المطلوبة لتطبيقك.

يطلب المستمع في المثال التالي حقول 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;
    }
);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، أو أداة الإكمال التلقائي (الجديدة) في حزمة تطوير البرامج (SDK) للأماكن على Android، أو أداة الإكمال التلقائي (الجديدة) في حزمة تطوير البرامج (SDK) للأماكن على iOS.
تعرَّف على حقول البيانات الأساسية في ميزة "الإكمال التلقائي (جديد)" من البداية.
إنّ حقول تحديد الموقع الجغرافي وحصر الموقع الجغرافي اختيارية، ولكن يمكن أن يكون لها تأثير كبير في أداء ميزة "الإكمال التلقائي".
استخدِم معالجة الأخطاء للتأكّد من أنّ تطبيقك يتراجع بشكل سلس إذا عرضت واجهة برمجة التطبيقات خطأً.
تأكَّد من أنّ تطبيقك يتعامل مع الحالات التي لا يتم فيها تحديد أي خيار، ويوفّر للمستخدمين طريقة للمتابعة.

أفضل الممارسات لتحسين التكلفة

تحسين التكلفة الأساسية

لتحسين تكلفة استخدام خدمة "الإكمال التلقائي (جديد)"، استخدِم أقنعة الحقول في تطبيقات "تفاصيل المكان (جديد)" و"الإكمال التلقائي (جديد)" المصغّرة لعرض حقول بيانات "الإكمال التلقائي (جديد)" التي تحتاج إليها فقط.

تحسين التكلفة المتقدّم

ننصحك بتنفيذ ميزة "الإكمال التلقائي (جديد)" آليًا للوصول إلى رمز التخزين التعريفي: أسعار طلبات الإكمال التلقائي وطلب نتائج Geocoding API حول المكان المحدّد بدلاً من تفاصيل المكان (جديد). يكون التسعير لكل طلب مع Geocoding API أكثر فعالية من حيث التكلفة مقارنةً بالتسعير لكل جلسة (المستند إلى الجلسة) في حال استيفاء الشرطَين التاليَين:

إذا كنت بحاجة فقط إلى خط العرض وخط الطول أو عنوان المكان الذي اختاره المستخدم، توفّر Geocoding API هذه المعلومات بتكلفة أقل من طلب تفاصيل المكان (الإصدار الجديد).
إذا اختار المستخدمون عبارة بحث مقترحة ضمن متوسط أربعة طلبات أو أقل من طلبات عبارات البحث المقترحة (الجديدة)، يمكن أن يكون السعر لكل طلب أقل تكلفة من السعر لكل جلسة.

لاختيار طريقة تنفيذ ميزة "الإكمال التلقائي (جديد)" الأقل تكلفة لتطبيقك، ابحث عن الصف في الجدول التالي الذي يتطابق مع احتياجات تطبيقك.

المعلومات المطلوبة في طلبك	متوسط طلبات الإكمال التلقائي (الجديدة) قبل أن يختار المستخدم عبارة مقترَحة	عمليات التنفيذ المقترَحة
تفاصيل المكان بخلاف العنوان والموقع الجغرافي، مثل اسم المكان أو حالة النشاط التجاري أو ساعات العمل	أي عدد	الإكمال التلقائي المستند إلى الجلسة (جديد) مع تفاصيل المكان (جديد)
العنوان وخط العرض/خط الطول للتوقّع المحدّد فقط	أربعة أو أقل	ميزة "الإكمال التلقائي (جديد)" لكل طلب مع Geocoding API
العنوان وخط العرض/خط الطول للتوقّع المحدّد فقط	أكثر من أربعة	الإكمال التلقائي المستند إلى الجلسة (الجديد) للتطبيقات التي تستخدم العناوين فقط

قد تكون Geocoding API خيارًا أكثر فعالية من حيث التكلفة من تفاصيل المكان (جديد) لتطبيقك، وذلك استنادًا إلى أداء استخدامك لخدمة الإكمال التلقائي (جديد). تختلف كفاءة ميزة "الإكمال التلقائي (جديد)" في كل تطبيق حسب ما يُدخله المستخدمون ومكان استخدام التطبيق وما إذا تم تنفيذ أفضل الممارسات لتحسين الأداء.

للعثور على متوسط عدد الطلبات للجدول، حلِّل عدد الأحرف التي يكتبها المستخدم في المتوسط قبل اختيار عبارة مقترَحة من ميزة "الإكمال التلقائي (جديد)" في تطبيقك.

الإكمال التلقائي المستنِد إلى الجلسة (جديد) مع تفاصيل المكان (جديد)

استخدام ميزة "الإكمال التلقائي (جديد)" المستندة إلى الجلسة مع ميزة "تفاصيل المكان (جديد)"
بما أنّ تطبيقك يتطلّب استخدام واجهة برمجة التطبيقات Place Details (New)، مثل اسم المكان أو حالة النشاط التجاري أو ساعات العمل، يجب أن يستخدم تنفيذك لواجهة برمجة التطبيقات Autocomplete (New) رمزًا مميزًا للجلسة (برمجيًا أو مضمّنًا في تطبيقات JavaScript أو Android أو iOS المصغّرة) لكل جلسة بالإضافة إلى رموز التخزين التعريفية السارية في Places، استنادًا إلى حقول بيانات المكان التي تطلبها.¹

تنفيذ التطبيقات المصغّرة
يتم دمج إدارة الجلسات تلقائيًا في التطبيقات المصغّرة التي تستخدم JavaScript أو Android أو iOS. ويشمل ذلك كلاً من طلبات "الإكمال التلقائي (الجديد)" وطلب "تفاصيل المكان (الجديد)" بشأن عبارة البحث المقترَحة المحدّدة. تأكَّد من تحديد المَعلمة fields لضمان طلب حقول البيانات التي تحتاج إليها فقط من ميزة "الإكمال التلقائي (جديد)".

التنفيذ الآلي
استخدِم رمزًا مميزًا للجلسة مع طلبات "الإكمال التلقائي (الجديد)". عند طلب تفاصيل المكان (الإصدار الجديد) حول عبارة البحث المقترَحة المحدّدة، يجب تضمين المَعلمات التالية:

رقم تعريف المكان من ردّ "الإكمال التلقائي (الجديد)"
الرمز المميّز للجلسة المستخدَم في طلب الإكمال التلقائي (الجديد)
المَعلمة fields التي تحدّد حقول بيانات ميزة "الإكمال التلقائي (جديد)" التي تحتاج إليها

ميزة "الإكمال التلقائي" (الجديدة) لكل طلب مع Geocoding API

تنفيذ ميزة "الإكمال التلقائي (جديد)" آليًا بدون الرموز المميّزة للجلسات واستدعاء Geocoding API في توقّعات المكان المحدّد
توفّر Geocoding API العناوين وإحداثيات خطوط العرض والطول. إنّ إجراء أربعة طلبات إكمال تلقائي بالإضافة إلى طلب بيانات من Geocoding API بشأن عبارة البحث المقترَحة للمكان المحدّد هو أقل من تكلفة الإكمال التلقائي (الجديد) لكل جلسة.¹

ننصحك باتّباع أفضل الممارسات المتعلّقة بالأداء لمساعدة المستخدمين في الحصول على عبارة البحث المقترَحة التي يبحثون عنها باستخدام عدد أقل من الأحرف.

ميزة "الإكمال التلقائي (جديد)" المستندة إلى الجلسة للتطبيقات التي تستخدم العناوين فقط

استخدام ميزة "الإكمال التلقائي (جديد)" المستندة إلى الجلسة مع ميزة "تفاصيل المكان (جديد)"
بما أنّ متوسط عدد الطلبات التي تتوقع إجراؤها قبل أن يختار المستخدم توقّعًا من ميزة "الإكمال التلقائي (جديد)" يتجاوز تكلفة السعر لكل جلسة، يجب أن يستخدم تنفيذك لميزة "الإكمال التلقائي (جديد)" رمزًا مميزًا للجلسة لكل من طلبات "الإكمال التلقائي (جديد)" وطلب "تفاصيل المكان (جديد)" المرتبط بها لكل جلسة. ¹

تنفيذ التطبيقات المصغّرة
يتم دمج إدارة الجلسات تلقائيًا في التطبيقات المصغّرة التي تستخدم JavaScript أو Android أو iOS. ويشمل ذلك كلاً من طلبات "الإكمال التلقائي (الجديد)" وطلب "تفاصيل المكان (الجديد)" المتعلّق بعبارة البحث المقترَحة المحدّدة. احرص على تحديد مَعلمة fields لضمان طلب الحقول التي تحتاج إليها فقط.

التنفيذ الآلي
استخدِم رمزًا مميزًا للجلسة مع طلبات "الإكمال التلقائي (الجديد)". عند طلب تفاصيل المكان (الجديدة) حول عبارة البحث المقترَحة المحدّدة، يجب تضمين المَعلمات التالية:

رقم تعريف المكان من ردّ "الإكمال التلقائي (الجديد)"
الرمز المميّز للجلسة المستخدَم في طلب الإكمال التلقائي (الجديد)
المَعلمة fields التي تحدّد الحقول مثل العنوان والشكل الهندسي

ننصحك بتأخير طلبات "الإكمال التلقائي (جديد)"
يمكنك استخدام استراتيجيات مثل تأخير طلب "الإكمال التلقائي (جديد)" إلى أن يكتب المستخدم الأحرف الثلاثة أو الأربعة الأولى لكي يرسل تطبيقك عددًا أقل من الطلبات. على سبيل المثال، إذا أرسلت طلبات بيانات من واجهة برمجة التطبيقات "الإكمال التلقائي (جديد)" لكل حرف بعد أن يكتب المستخدم الحرف الثالث، يعني ذلك أنّه إذا كتب المستخدم سبعة أحرف ثم اختار عبارة بحث مقترَحة ترسل لها طلب بيانات من واجهة برمجة التطبيقات واحدًا من Geocoding API، ستكون التكلفة الإجمالية لـ 4 طلبات بيانات من واجهة برمجة التطبيقات "الإكمال التلقائي (جديد)" لكل طلب + الترميز الجغرافي.¹

إذا كان تأخير الطلبات يمكن أن يخفّض متوسط الطلبات الآلية إلى أقل من أربعة، يمكنك اتّباع الإرشادات الخاصة بتنفيذ ميزة "الإكمال التلقائي (الجديدة)" العالية الأداء مع Geocoding API. يُرجى العِلم أنّ تأخير الطلبات قد يظهر للمستخدم على أنّه وقت استجابة، وقد يتوقّع المستخدم ظهور عبارات بحث مقترَحة مع كل ضغطة مفتاح جديدة.

ننصحك باتّباع أفضل الممارسات المتعلّقة بالأداء لمساعدة المستخدمين في الحصول على التوقّعات التي يبحثون عنها باستخدام عدد أقل من الأحرف.

لمعرفة التكاليف، يُرجى الاطّلاع على قوائم أسعار "منصة خرائط Google".

أفضل الممارسات المتعلّقة بالأداء

توضّح الإرشادات التالية طرق تحسين أداء ميزة "الإكمال التلقائي (جديد)":

أضِف القيود المفروضة على البلدان والانحياز للموقع الجغرافي واللغة المفضّلة (لعمليات التنفيذ الآلية) إلى عملية تنفيذ ميزة "الإكمال التلقائي (جديد)". لا حاجة إلى تحديد اللغة المفضّلة في التطبيقات المصغّرة لأنّها تختار اللغات المفضّلة من متصفّح المستخدم أو جهازه الجوّال.
إذا كانت ميزة "الإكمال التلقائي (جديد)" مصحوبة بخريطة، يمكنك تحديد الموقع الجغرافي حسب إطار العرض في الخريطة.
في الحالات التي لا يختار فيها المستخدم إحدى عبارات البحث المقترَحة في ميزة "الإكمال التلقائي" (الجديدة)، لأنّ أيًا من هذه العبارات لا يمثّل العنوان المطلوب، يمكنك إعادة استخدام البيانات التي أدخلها المستخدم في الأصل لمحاولة الحصول على نتائج أكثر صلة:
- إذا كنت تتوقّع أن يُدخل المستخدم معلومات العنوان فقط، أعِد استخدام البيانات التي أدخلها المستخدم الأصلي في طلب إلى 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.

يمكنك أيضًا حصر النتائج بالمنطقة المحدّدة من خلال المَعلمة location ومَعلمة radius، وذلك من خلال إضافة المَعلمة locationRestriction. يؤدي ذلك إلى توجيه ميزة "الإكمال التلقائي (جديد)" لعرض النتائج فقط ضمن تلك المنطقة.

التطبيق المصغّر للإكمال التلقائي للأماكن تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

المتطلبات الأساسية

الميزات الجديدة

إضافة تطبيق مصغّر للإكمال التلقائي

إضافة تطبيق مصغّر للإكمال التلقائي إلى صفحة ويب

TypeScript

JavaScript

إضافة تطبيق مصغّر للإكمال التلقائي إلى خريطة

إضافة نص مؤقت

تقييد عبارات البحث المقترحة من خلال ميزة "الإكمال التلقائي"

حصر البحث عن الأماكن حسب البلد

حصر البحث عن الأماكن ضمن حدود الخريطة

تحيز نتائج البحث عن الأماكن

حصر نتائج البحث عن الأماكن بأنواع معيّنة

الحصول على تفاصيل المكان

TypeScript

JavaScript

TypeScript

JavaScript

أمثلة على الخرائط

عنصر الإكمال التلقائي

TypeScript

JavaScript

CSS

HTML

خريطة الإكمال التلقائي

TypeScript

JavaScript

CSS

HTML

تحسين ميزة "الإكمال التلقائي (جديد)"

أفضل الممارسات لتحسين التكلفة

تحسين التكلفة الأساسية

تحسين التكلفة المتقدّم

الإكمال التلقائي المستنِد إلى الجلسة (جديد) مع تفاصيل المكان (جديد)

ميزة "الإكمال التلقائي" (الجديدة) لكل طلب مع Geocoding API

ميزة "الإكمال التلقائي (جديد)" المستندة إلى الجلسة للتطبيقات التي تستخدم العناوين فقط

أفضل الممارسات المتعلّقة بالأداء

تحديد الموقع الجغرافي

تقييد الموقع الجغرافي

التطبيق المصغّر للإكمال التلقائي للأماكن