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

اختيار النظام الأساسي: Android iOS JavaScript

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

يسهل تنفيذ عنصر "الإكمال التلقائي للأماكن" الأساسي مقارنةً بالعنصر PlaceAutocompleteElement، ويختلف عنه في ما يلي:

  • يعرض عنصر "الإكمال التلقائي للأماكن الأساسي" عنصر مكان يحتوي فقط على المعرّف الخاص بالمكان، بدلاً من عنصر PlacePrediction. يمكنك استخدام رقم تعريف المكان الذي تم عرضه مباشرةً مع عنصر تفاصيل Places UI Kit للحصول على تفاصيل إضافية عن المكان، بينما يتطلّب العنصر PlacePrediction أولاً تحويله إلى رقم تعريف مكان.
  • لا يتطلّب عنصر "الإكمال التلقائي للأماكن" الأساسي تحميل Places API.
  • يزيل عنصر "الإكمال التلقائي الأساسي للمكان" حقل الإدخال عندما يختار المستخدم توقعًا للمكان.

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

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

إضافة عنصر "الإكمال التلقائي للأماكن الأساسية"

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

إضافة عنصر "إكمال تلقائي أساسي" إلى صفحة ويب

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

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

إضافة عنصر "إكمال تلقائي أساسي" إلى خريطة

لإضافة عنصر "الإكمال التلقائي الأساسي" إلى خريطة، أضِف BasicPlaceAutocompleteElement إلى عنصر gmp-map واضبط موضعه باستخدام السمة slot، كما هو موضّح في المثال التالي:

<gmp-map zoom="12" center="37.4220656,-122.0840897" map-id="DEMO_MAP_ID">
  <gmp-basic-place-autocomplete
    slot="control-inline-start-block-start"></gmp-basic-place-autocomplete>
</gmp-map>
index.html

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ضبط عنصر "طلب بيانات المكان"

أضِف أداة معالجة لتعديل عنصر "طلب المكان" عندما يختار المستخدم نتيجة بحث مقترَحة: 

// Event listener for when a place is selected from the autocomplete list.
placeAutocompleteElement.addEventListener('gmp-select', (event) => {
    // Reset marker and InfoWindow, and prepare the details element.
    placeDetailsParent.appendChild(placeDetailsElement);
    placeDetailsElement.style.display = 'block';
    advancedMarkerElement.position = null;
    infoWindow.close();
    // Request details for the selected place.
    const placeDetailsRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
    placeDetailsRequest.place = event.place.id;
});
index.js

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

JavaScript

const placeAutocompleteElement = document.querySelector('gmp-basic-place-autocomplete');
const placeDetailsElement = document.querySelector('gmp-place-details-compact');
const placeDetailsParent = placeDetailsElement.parentElement;
const gmpMapElement = document.querySelector('gmp-map');
async function initMap() {
    // Asynchronously load required libraries from the Google Maps JS API.
    await google.maps.importLibrary('places');
    const { AdvancedMarkerElement } = (await google.maps.importLibrary('marker'));
    const { InfoWindow } = (await google.maps.importLibrary('maps'));
    // Get the initial center directly from the gmp-map element's property.
    const center = gmpMapElement.center;
    // Set the initial location bias for the autocomplete element.
    placeAutocompleteElement.locationBias = center;
    // Update the map object with specified options.
    const map = gmpMapElement.innerMap;
    map.setOptions({
        clickableIcons: false,
        mapTypeControl: false,
        streetViewControl: false,
    });
    // Create an advanced marker to show the location of a selected place.
    const advancedMarkerElement = new AdvancedMarkerElement({
        map: map,
        collisionBehavior: google.maps.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL,
    });
    // Create an InfoWindow to hold the place details component.
    const infoWindow = new InfoWindow({
        minWidth: 360,
        disableAutoPan: true,
        headerDisabled: true,
        pixelOffset: new google.maps.Size(0, -10),
    });
    // Event listener for when a place is selected from the autocomplete list.
    placeAutocompleteElement.addEventListener('gmp-select', (event) => {
        // Reset marker and InfoWindow, and prepare the details element.
        placeDetailsParent.appendChild(placeDetailsElement);
        placeDetailsElement.style.display = 'block';
        advancedMarkerElement.position = null;
        infoWindow.close();
        // Request details for the selected place.
        const placeDetailsRequest = placeDetailsElement.querySelector('gmp-place-details-place-request');
        placeDetailsRequest.place = event.place.id;
    });
    // Event listener for when the place details have finished loading.
    placeDetailsElement.addEventListener('gmp-load', () => {
        const location = placeDetailsElement.place.location;
        // Position the marker and open the InfoWindow at the place's location.
        advancedMarkerElement.position = location;
        infoWindow.setContent(placeDetailsElement);
        infoWindow.open({
            map,
            anchor: advancedMarkerElement,
        });
        map.setCenter(location);
    });
    // Event listener to close the InfoWindow when the map is clicked.
    map.addListener('click', () => {
        infoWindow.close();
        advancedMarkerElement.position = null;
    });
    // Event listener for when the map finishes moving (panning or zooming).
    map.addListener('idle', () => {
        const newCenter = map.getCenter();
        // Update the autocomplete's location bias to a 10km radius around the new map center.
        placeAutocompleteElement.locationBias = new google.maps.Circle({
            center: {
                lat: newCenter.lat(),
                lng: newCenter.lng(),
            },
            radius: 10000, // 10km in meters.
        });
    });
}
initMap();
index.js

CSS

html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

gmp-map {
  height: 100%;
}

gmp-basic-place-autocomplete {
  position: absolute;
  height: 30px;
  width: 500px;
  top: 10px;
  left: 10px;
  box-shadow: 4px 4px 5px 0px rgba(0, 0, 0, 0.2);
  color-scheme: light;
  border-radius: 10px;
}
style.css

HTML

<html>
  <head>
    <title>Basic 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 zoom="12" center="37.4220656,-122.0840897" map-id="DEMO_MAP_ID">
      <gmp-basic-place-autocomplete
        slot="control-inline-start-block-start"></gmp-basic-place-autocomplete>
    </gmp-map>
    <!-- Use inline styles to configure the Place Details Compact element because
     it will be placed within the info window, and info window content is inside 
     the shadow DOM when using <gmp-map> -->
    <gmp-place-details-compact
      orientation="horizontal"
      style="width: 400px;
      display: none;
      border: none;
      padding: 0;
      margin: 0;
      background-color: transparent;
      color-scheme: light;">
      <gmp-place-details-place-request></gmp-place-details-place-request>
      <gmp-place-standard-content></gmp-place-standard-content>
    </gmp-place-details-compact>
  </body>
</html>
index.html

تجربة عيّنة