حزمة أدوات Places UI Kit: هي مكتبة جاهزة للاستخدام تتيح للمطوّرين إمكانية التخصيص والتحكّم. ننصحك بتجربتها ومشاركة ملاحظاتك حول تجربتك مع حزمة واجهة المستخدم.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

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

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

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

TypeScript

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

JavaScript

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

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

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

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

TypeScript

// Get the inner map.
innerMap = mapElement.innerMap;
innerMap.setOptions({
    mapTypeControl: false,
});

// 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();
});index.ts

JavaScript

// Get the inner map.
innerMap = mapElement.innerMap;
innerMap.setOptions({
    mapTypeControl: false,
});
// 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();
});index.js

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

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

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

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

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

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

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

const pac = new google.maps.places.PlaceAutocompleteElement({
  includedRegionCodes: ['us', 'au'],
});

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

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

const pac = new google.maps.places.PlaceAutocompleteElement({
  locationRestriction: map.getBounds(),
});

عند حصر النتائج في حدود الخريطة، احرص على إضافة أداة معالجة لتعديل الحدود عند تغييرها:

map.addListener('bounds_changed', () => {
  autocomplete.locationRestriction = map.getBounds();
});

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

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

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

const autocomplete = new google.maps.places.PlaceAutocompleteElement({
  locationBias: {radius: 100, center: {lat: 50.064192, lng: -130.605469}},
});

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

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

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

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

للحصول على قائمة كاملة بالأنواع المتوافقة، راجِع جدولَي أنواع الأماكن A وB.

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

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

TypeScript

// Add the gmp-placeselect listener, and display the results.
//prettier-ignore
//@ts-ignore
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.ts

JavaScript

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

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

في المثال السابق، يعرض معالج الأحداث عنصرًا من فئة المكان. اتّصِل بـ place.fetchFields() للحصول على حقول البيانات الخاصة بـ "تفاصيل المكان" المطلوبة لتطبيقك.

يطلب المستمع في المثال التالي معلومات عن مكان معيّن ويعرضها على خريطة.

TypeScript

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

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

    let content = document.createElement('div');
    let nameText = document.createElement('span');
    nameText.textContent = place.displayName;
    content.appendChild(nameText);
    content.appendChild(document.createElement('br'));
    let addressText = document.createElement('span');
    addressText.textContent = place.formattedAddress;
    content.appendChild(addressText);

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

JavaScript

// Add the gmp-placeselect listener, and display the results on the map.
//prettier-ignore
//@ts-ignore
placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
    const place = placePrediction.toPlace();
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    // 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);
    }
    let content = document.createElement('div');
    let nameText = document.createElement('span');
    nameText.textContent = place.displayName;
    content.appendChild(nameText);
    content.appendChild(document.createElement('br'));
    let addressText = document.createElement('span');
    addressText.textContent = place.formattedAddress;
    content.appendChild(addressText);
    updateInfoWindow(content, place.location);
    marker.position = place.location;
});index.js

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

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

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

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

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

TypeScript

async function initMap(): Promise<void> {
    // Request needed libraries.
    (await google.maps.importLibrary('places')) as google.maps.PlacesLibrary;
    // Create the input HTML element, and append it.
    const placeAutocomplete = new google.maps.places.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-placeselect listener, and display the results.
    //prettier-ignore
    //@ts-ignore
    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);
    });
}

initMap();index.ts

JavaScript

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('places'));
    // Create the input HTML element, and append it.
    const placeAutocomplete = new google.maps.places.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-placeselect listener, and display the results.
    //prettier-ignore
    //@ts-ignore
    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);
    });
}
initMap();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>
    </head>
    <body>
        <p style="font-family: roboto, sans-serif">Search for a place here:</p>

        <!-- prettier-ignore -->
        <script>(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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
    </body>
</html>index.html

تجربة عيّنة

JSFiddle.net

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

يوضّح لك هذا المثال كيفية إضافة أداة Autocomplete إلى خريطة Google.

TypeScript

const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;
const placeAutocomplete = document.querySelector(
    'gmp-place-autocomplete'
) as google.maps.places.PlaceAutocompleteElement;
let innerMap;
let marker: google.maps.marker.AdvancedMarkerElement;
let infoWindow: google.maps.InfoWindow;
let center = { lat: 40.749933, lng: -73.98633 }; // New York City
async function initMap(): Promise<void> {
    // Request needed libraries.
    const [] = await Promise.all([
        google.maps.importLibrary('marker'),
        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.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds();
    });

    // Create the marker and infowindow.
    marker = new google.maps.marker.AdvancedMarkerElement({
        map: innerMap,
    });

    infoWindow = new google.maps.InfoWindow({});

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

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

      let content = document.createElement('div');
      let nameText = document.createElement('span');
      nameText.textContent = place.displayName;
      content.appendChild(nameText);
      content.appendChild(document.createElement('br'));
      let addressText = document.createElement('span');
      addressText.textContent = place.formattedAddress;
      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,
    });
}

initMap();index.ts

JavaScript

const mapElement = document.querySelector('gmp-map');
const placeAutocomplete = document.querySelector('gmp-place-autocomplete');
let innerMap;
let marker;
let infoWindow;
let center = { lat: 40.749933, lng: -73.98633 }; // New York City
async function initMap() {
    // Request needed libraries.
    const [] = await Promise.all([
        google.maps.importLibrary('marker'),
        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.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds();
    });
    // Create the marker and infowindow.
    marker = new google.maps.marker.AdvancedMarkerElement({
        map: innerMap,
    });
    infoWindow = new google.maps.InfoWindow({});
    // Add the gmp-placeselect listener, and display the results on the map.
    //prettier-ignore
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: ['displayName', 'formattedAddress', 'location'],
        });
        // 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);
        }
        let content = document.createElement('div');
        let nameText = document.createElement('span');
        nameText.textContent = place.displayName;
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        let addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress;
        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,
    });
}
initMap();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: large;
    font-weight: bold;
}

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>
        <!-- prettier-ignore -->
        <script>(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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</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">
                <p>Search for a place here:</p>
                <gmp-place-autocomplete></gmp-place-autocomplete>
            </div>
        </gmp-map>
    </body>
</html>index.html

تجربة عيّنة

JSFiddle.net

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لا، يحتاج فقط إلى العنوان والموقع الجغرافي

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

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

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

نعم

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

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

لا

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

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

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

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

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

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

تحذير: إذا لم يتم توفير radius، سيتم تجاهل المَعلمة location.

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

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

لحصر النتائج في منطقة محدّدة، أضِف المَعلمة locationRestriction.

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

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

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

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

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

إضافة أداة الإكمال التلقائي إلى صفحة ويب

TypeScript

JavaScript

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

TypeScript

JavaScript

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

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

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

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

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

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

TypeScript

JavaScript

TypeScript

JavaScript

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

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

TypeScript

JavaScript

CSS

HTML

تجربة عيّنة

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

TypeScript

JavaScript

CSS

HTML

تجربة عيّنة

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

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

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

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

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

لا، يحتاج فقط إلى العنوان والموقع الجغرافي

نعم

لا

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

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

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

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