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

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

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

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

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

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

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

ملاحظة: يتم تحصيل رسوم عنصر "الإكمال التلقائي الأساسي للأماكن" باستخدام رمز التخزين التعريفي: Places UI Kit - الإكمال التلقائي لكل جلسة، وليس رموز التخزين التعريفية لطلب الإكمال التلقائي العادي أو جلسة الإكمال التلقائي.

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

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

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

لإضافة عنصر 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

ملاحظة: تسمح سمة معرّف الخريطة بتخزين إعدادات تنسيق الخريطة وإعدادات الضبط في Google Cloud، وهي مطلوبة لـ هذا المثال. يمكن استخدام المعرّف DEMO_MAP_ID للاختبار ولا يلزم تفعيله في Cloud.

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

تلقائيًا، يعرض عنصر "الإكمال التلقائي الأساسي للأماكن" جميع أنواع الأماكن، مع التركيز على عبارات البحث المقترحة بالقرب من موقع المستخدم. اضبط 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 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();
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>
        <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>
index.html