نقدّم لك مجموعة أدوات واجهة المستخدم الخاصة بـ Places: هي مكتبة مكوّنات جاهزة للاستخدام ومنخفضة التكلفة تتيح لك إضافة واجهة مستخدم Places المألوفة من "خرائط Google" إلى أي خريطة تختارها. ننصحك بتجربتها و مشاركة ملاحظاتك للمساعدة في رسم مستقبل "منصة Google للتسويق".

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

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

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

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

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

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

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

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

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

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

لإضافة عنصر 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، وألحِقه بـ div، ثم أضِفه إلى الخريطة كعنصر تحكّم مخصّص، كما هو موضّح في المثال التالي:

  const placeAutocomplete = new google.maps.places.BasicPlaceAutocompleteElement();
  placeAutocomplete.id = 'place-autocomplete-input';
  placeAutocomplete.locationBias = center;
  const card = document.getElementById('place-autocomplete-card');
  card.appendChild(placeAutocomplete);
  map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);

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

تعرض ميزة "الإكمال التلقائي للأماكن" الأساسية تلقائيًا جميع أنواع الأماكن، مع إعطاء الأولوية للتوقّعات القريبة من الموقع الجغرافي للمستخدم. اضبط قيمة 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.

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

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

// Add the listener to update the Place Request element when the user selects a prediction
autocompleteElement.addEventListener('gmp-select', async (event) => {
    const placeDetailsRequest = document.querySelector('gmp-place-details-place-request');
    placeDetailsRequest.place = event.place.id;
});index.js

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

JavaScript

const mapContainer = document.getElementById("map-container");
const autocompleteElement = document.querySelector('gmp-basic-place-autocomplete');
const detailsElement = document.querySelector('gmp-place-details-compact');
const mapElement = document.querySelector('gmp-map');
const advancedMarkerElement = document.querySelector('gmp-advanced-marker');
let center = { lat: 40.749933, lng: -73.98633 }; // New York City
async function initMap() {
    //@ts-ignore
    const { BasicPlaceAutocompleteElement, PlaceDetailsElement } = await google.maps.importLibrary('places');
    //@ts-ignore
    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');
    //@ts-ignore
    const { LatLngBounds } = await google.maps.importLibrary('core');
    // Set the initial map location and autocomplete location bias
    mapElement.center = center;
    autocompleteElement.locationBias = center;
    // Get the underlying google.maps.Map object to add listeners
    const map = mapElement.innerMap;
    // Add the listener tochange locationBias to locationRestriction when the map moves
    map.addListener('bounds_changed', () => {
        autocompleteElement.locationBias = null;
        autocompleteElement.locationRestriction = map.getBounds();
        console.log("bias changed to restriction");
    });
    // Add the listener to update the Place Request element when the user selects a prediction
    autocompleteElement.addEventListener('gmp-select', async (event) => {
        const placeDetailsRequest = document.querySelector('gmp-place-details-place-request');
        placeDetailsRequest.place = event.place.id;
    });
    // Add the listener to update the marker when the Details element loads
    detailsElement.addEventListener('gmp-load', async () => {
        const location = detailsElement.place.location;
        detailsElement.style.display = "block";
        advancedMarkerElement.position = location;
        advancedMarkerElement.content = detailsElement;
        if (detailsElement.place.viewport) {
            map.fitBounds(detailsElement.place.viewport);
        }
        else {
            map.setCenter(location);
            map.setZoom(17);
        }
    });
}
initMap();index.js

CSS

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

#map-container {
  display: flex;
  flex-direction: row;
  height: 100%;
}

#gmp-map {
  height: 100%;
}

gmp-basic-place-autocomplete {
  position: absolute;
  height: 50px;
  top: 10px;
  left: 10px;
  z-index: 1;
  box-shadow: 2px 2px 5px 0px rgba(0,0,0,0.2); 
  color-scheme: light;
  border-radius: 10px;
}

gmp-place-details-compact {
  width: 360px;
  max-height: 300px;
  border: none;
  padding: 0;
  margin: 0;
  position: absolute;
  transform: translate(calc(-180px), calc(-215px)); 
  box-shadow: 2px 2px 5px 0px rgba(0,0,0,0.2); 
  color-scheme: light;
}

/* This creates the pointer attached to the bottom of the element. */
gmp-place-details-compact::after {
  content: "";
  position: absolute;
  top: 100%;
  left: 50%;
  transform: translateX(-50%);
  width: 0;
  height: 0;
  border-left: 16px solid transparent;
  border-right: 16px solid transparent;
  border-top: 20px solid var(--gmp-mat-color-surface, light-dark(white, black));
}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>
  </head>
  <body>
   <div id="map-container">
      <gmp-basic-place-autocomplete></gmp-basic-place-autocomplete>
      <gmp-place-details-compact orientation="horizontal">
        <gmp-place-details-place-request></gmp-place-details-place-request>
        <gmp-place-all-content></gmp-place-all-content>
      </gmp-place-details-compact>
      <gmp-map zoom="14" map-id="DEMO_MAP_ID">
         <gmp-advanced-marker></gmp-advanced-marker> 
      </gmp-map>
    </div>

    <!-- 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