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

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

ينشئ أداة الإكمال التلقائي للأماكن حقل إدخال نصي، ويوفّر توقعات للأماكن في قائمة اختيار ضمن واجهة المستخدم، ويعرض تفاصيل المكان استجابةً لاختيار المستخدم. استخدِم أداة Place Autocomplete Widget لتضمين واجهة مستخدم كاملة ومستقلة للإكمال التلقائي للأماكن في صفحة الويب.

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

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

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

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

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

إضافة أداة الإكمال التلقائي

تنشئ أداة Autocomplete المصغّرة حقل إدخال نص، وتوفّر توقعات خاصة بالأماكن في قائمة اختيار ضمن واجهة المستخدم، وتعرض تفاصيل المكان استجابةً لنقرة المستخدم باستخدام أداة الاستماع 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);

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

إضافة أداة Autocomplete إلى خريطة

إذا كان عنوان إرسال الفواتير خارج المنطقة الاقتصادية الأوروبية، يمكنك أيضًا استخدام أداة "الإكمال التلقائي" مع "خريطة 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 على 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...';

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

تعرض خدمة &quot;الإكمال التلقائي للأماكن&quot; تلقائيًا جميع أنواع الأماكن، مع إعطاء الأولوية للتوقعات القريبة من الموقع الجغرافي للمستخدم، كما تسترد جميع حقول البيانات المتاحة للمكان الذي يختاره المستخدم. اضبط 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'],
});

للاطّلاع على قائمة كاملة بالأنواع المتوافقة، يُرجى الرجوع إلى جدولَي أنواع الأماكن 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
        );
    }
);

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

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

في المثال السابق، يعرض متتبِّع الأحداث عنصرًا من فئة المكان. اتّصِل بـ 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;
    }
);

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

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

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

يحتوي هذا القسم على الرمز الكامل لخرائط الأمثلة المعروضة في هذه الصفحة.

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

يضيف هذا المثال أداة Autocomplete إلى صفحة ويب، ويعرض النتائج لكل مكان تم اختياره.

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>

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

يوضّح لك هذا المثال كيفية إضافة أداة Autocomplete إلى خريطة 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>

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

يوضّح هذا القسم أفضل الممارسات التي تساعدك على الاستفادة إلى أقصى حدّ من خدمة &quot;الإكمال التلقائي&quot; (الجديدة).

في ما يلي بعض الإرشادات العامة:

  • أسرع طريقة لتطوير واجهة مستخدم تعمل بشكل جيد هي استخدام أداة الإكمال التلقائي (جديدة) في Maps JavaScript API، أو أداة الإكمال التلقائي (جديدة) في Places SDK for Android، أو أداة الإكمال التلقائي (جديدة) في Places SDK for iOS.
  • التعرّف على حقول البيانات الأساسية الخاصة بميزة "الإكمال التلقائي" (جديدة) منذ البداية
  • حقلَي "تفضيل الموقع الجغرافي" و"حظر الموقع الجغرافي" اختياريان، ولكن يمكن أن يكون لهما تأثير كبير في أداء ميزة "الإكمال التلقائي".
  • استخدِم ميزة معالجة الأخطاء للتأكّد من أنّ تطبيقك يتراجع بشكل سليم في حال عرض واجهة برمجة التطبيقات رسالة خطأ.
  • تأكَّد من أنّ تطبيقك يتعامل مع الحالات التي لا يتم فيها تحديد أي خيار، ويوفّر للمستخدمين طريقة للمتابعة.

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

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

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

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

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

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

هل يتطلّب تطبيقك أي معلومات أخرى غير العنوان وخطوط الطول والعرض الخاصة بالتوقّع المحدّد؟

نعم، يجب إضافة المزيد من التفاصيل

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

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

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

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

لا، يجب توفير العنوان والموقع الجغرافي فقط

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

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

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

نعم

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

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

لا

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

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

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

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

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

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

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


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

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

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

  • أضِف القيود المفروضة على البلدان وتفضيل الموقع الجغرافي وخيار اللغة المفضّلة (في عمليات التنفيذ الآلية) إلى عملية تنفيذ "الإكمال التلقائي (جديد)". لا حاجة إلى تحديد اللغة المفضّلة عند استخدام التطبيقات المصغّرة لأنّها تستند إلى اللغة المفضّلة المحدّدة في متصفّح المستخدم أو جهازه الجوّال.
  • إذا كانت ميزة "الإكمال التلقائي (جديدة)" مصحوبة بخريطة، يمكنك تحديد الموقع الجغرافي حسب إطار عرض الخريطة.
  • في الحالات التي لا يختار فيها المستخدم إحدى عبارات البحث المقترَحة من ميزة &quot;الإكمال التلقائي (الجديدة)&quot;، وذلك بشكل عام لأنّ أيًا من عبارات البحث المقترَحة هذه ليس عنوان النتيجة المطلوب، يمكنك إعادة استخدام بيانات أدخلها المستخدم الأصلية لمحاولة الحصول على نتائج أكثر صلة بالموضوع:
    • إذا كنت تتوقّع أن يدخل المستخدم معلومات العنوان فقط، أعِد استخدام إدخال المستخدم الأصلي في طلب إلى Geocoding API.
    • إذا كنت تتوقّع أن يُدخل المستخدم طلبات بحث عن مكان معيّن بالاسم أو العنوان، استخدِم طلب "تفاصيل المكان (جديد)". إذا كنت تتوقّع ظهور النتائج في منطقة معيّنة فقط، استخدِم تفضيل الموقع الجغرافي.
    تشمل السيناريوهات الأخرى التي يُنصح فيها بالرجوع إلى Geocoding API ما يلي:
    • المستخدمون الذين يدخلون عناوين أماكن فرعية، مثل عناوين وحدات أو شقق معيّنة داخل مبنى على سبيل المثال، يؤدي إدخال العنوان التشيكي "Stroupežnického 3191/17, Praha" إلى ظهور عبارة بحث مقترَحة جزئية في ميزة "الإكمال التلقائي (الجديدة)".
    • المستخدمون الذين يدخلون عناوين تتضمّن بادئات مقاطع طرق، مثل "23-30 29th St, Queens" في مدينة نيويورك أو "47-380 Kamehameha Hwy, Kaneohe" في جزيرة كاواي في هاواي

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

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

حصر الوصول إلى الموقع الجغرافي

يمكنك حصر النتائج على منطقة محدّدة من خلال تمرير المَعلمة locationRestriction.

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