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

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

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

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

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

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

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

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

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

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

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

لإضافة أداة Autocomplete إلى صفحة ويب، أنشئ 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);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

إضافة نص مؤقت

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

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

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

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

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

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

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

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

JavaScript

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

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

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

يطلب المستمع في المثال التالي حقول displayName وformattedAddress وlocation وviewport في place.fetchFields()، ثم يستخدم place.viewport مع fitBounds() لعرض المكان المحدّد على الخريطة.

TypeScript

// Add the gmp-select listener, and display the results on the map.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: [
                'displayName',
                'formattedAddress',
                'location',
                'viewport',
            ],
        });

        // If the place has a geometry, then present it on a map.
        if (place.viewport) {
            innerMap.fitBounds(place.viewport);
        } else {
            innerMap.setCenter(place.location!);
            innerMap.setZoom(17);
        }

        const content = document.createElement('div');
        const nameText = document.createElement('span');
        nameText.textContent = place.displayName ?? 'No name';
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        const addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress ?? 'No address';
        content.appendChild(addressText);

        updateInfoWindow(content, place.location);
        marker.position = place.location;
    }
);

JavaScript

// Add the gmp-select listener, and display the results on the map.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: [
                'displayName',
                'formattedAddress',
                'location',
                'viewport',
            ],
        });

        // If the place has a geometry, then present it on a map.
        if (place.viewport) {
            innerMap.fitBounds(place.viewport);
        } else {
            innerMap.setCenter(place.location);
            innerMap.setZoom(17);
        }

        const content = document.createElement('div');
        const nameText = document.createElement('span');
        nameText.textContent = place.displayName ?? 'No name';
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        const addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress ?? 'No address';
        content.appendChild(addressText);

        updateInfoWindow(content, place.location);
        marker.position = place.location;
    }
);

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

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

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

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

يضيف هذا المثال أداة 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; (الجديدة).

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

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

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

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

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

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

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

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

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

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

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

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

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

  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 طلبات "الإكمال التلقائي (جديد)" لكل طلب + الترميز الجغرافي.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. يؤدي ذلك إلى توجيه خدمة "الإكمال التلقائي (جديد)" لعرض النتائج ضمن تلك المنطقة فقط.