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

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

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

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

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

لاستخدام عنصر "الإكمال التلقائي للأماكن" الأساسي، يجب تفعيل حزمة أدوات "خرائط Google" الجاهزة للأماكن في مشروعك على 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>

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

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

When restricting to map bounds, be sure to add a listener to update the bounds when they change:

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'],
});

للحصول على قائمة كاملة بالأنواع المتوافقة، يُرجى الاطّلاع على الجدولَين "أ" و"ب" لأنواع الأماكن.

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

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

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

يوضّح لك هذا المثال كيفية إضافة عنصر "إكمال تلقائي أساسي" إلى خريطة 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 init() {
    // Asynchronously load required libraries from the Google Maps JS API.
    const [{ AdvancedMarkerElement }, { InfoWindow, Circle }, { Size }] =
        await Promise.all([
            google.maps.importLibrary('marker'),
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('core'),
            google.maps.importLibrary('places'),
        ]);

    // 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,
        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 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;
        if (!location) {
            advancedMarkerElement.position = null;
            return;
        }

        // 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 Circle({
            center: newCenter,
            radius: 10000, // 10km in meters.
        });
    });
}

void init();

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

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