Temel Yer Adı Otomatik Tamamlama Öğesi

BasicPlaceAutocompleteElement, bir metin giriş alanı oluşturur, kullanıcı arayüzü seçim listesinde yer tahminleri sağlar ve seçilen yer için bir yer kimliği döndürür.

Temel Yer Adı Otomatik Tamamlama öğesinin uygulanması, PlaceAutocompleteElement öğesine kıyasla daha kolaydır ve aşağıdaki yönlerden farklılık gösterir:

  • Temel Yer Adı Otomatik Tamamlama öğesi, PlacePrediction nesnesi yerine yalnızca yer kimliğini içeren bir Place nesnesi döndürür. Döndürülen yer kimliğini doğrudan bir Places UI Kit Details öğesiyle kullanarak ek yer ayrıntıları alabilirsiniz. PlacePrediction nesnesinin ise önce yer kimliğine dönüştürülmesi gerekir.
  • Temel Yer Adı Otomatik Tamamlama öğesi, Google Cloud Console'da Places API'yi etkinleştirmenizi gerektirmez.
  • Temel Yer Adı Otomatik Tamamlama öğesi, kullanıcı bir yer tahmini seçtiğinde giriş alanını temizler.

Ön koşullar

Basic Yer Adı Otomatik Tamamlama öğesini kullanmak için Google Cloud projenizde Places UI Kit'i etkinleştirmeniz gerekir. Ayrıntılar için Başlangıç bölümüne bakın.

Temel Yer Adı Otomatik Tamamlama öğesi ekleme

Bu bölümde, bir web sayfasına veya haritaya nasıl temel otomatik tamamlama öğesi ekleyeceğiniz gösterilmektedir.

Web sayfasına Temel Otomatik Tamamlama öğesi ekleme

BasicAutocomplete öğesini bir web sayfasına eklemek için yeni bir google.maps.places.BasicPlaceAutocompleteElement oluşturun ve aşağıdaki örnekte gösterildiği gibi sayfaya ekleyin: 

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

Haritaya Basic Autocomplete öğesi ekleme

Haritaya Temel Otomatik Tamamlama öğesi eklemek için gmp-map öğesine BasicPlaceAutocompleteElement ekleyin ve aşağıdaki örnekte gösterildiği gibi slot özelliğini kullanarak konumunu ayarlayın:

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

Otomatik tamamlama tahminlerini kısıtlama

Varsayılan olarak, Temel Yer Adı Otomatik Tamamlama, kullanıcının konumuna yakın tahminlere öncelik vererek tüm yer türlerini sunar. Sonuçları kısıtlayarak veya sonuçlara ağırlık vererek daha alakalı tahminler sunmak için BasicPlaceAutocompleteElementOptions değerini ayarlayın.

Sonuçları kısıtlamak, Temel Otomatik Tamamlama öğesinin kısıtlama alanının dışındaki sonuçları yoksaymasına neden olur. Sonuçları harita sınırlarıyla kısıtlamak yaygın bir uygulamadır. Sonuçları yönlendirmek, BasicAutocomplete öğesinin belirtilen alan içindeki sonuçları göstermesini sağlar ancak bazı eşleşmeler bu alanın dışında olabilir.

Herhangi bir sınır veya harita görüntü alanı sağlamazsanız API, kullanıcının konumunu IP adresinden algılamaya çalışır ve sonuçları bu konuma göre önceliklendirir. Mümkün olduğunca sınırları belirleyin. Aksi takdirde, farklı kullanıcılar farklı tahminler alabilir. Ayrıca, tahminleri genel olarak iyileştirmek için haritada kaydırarak veya yakınlaştırarak ayarladığınız bir görüntü alanı ya da geliştirici tarafından cihaz konumuna ve yarıçapına göre ayarlanan bir görüntü alanı gibi mantıklı bir görüntü alanı sağlamak önemlidir. Yarıçap bilgisi mevcut olmadığında, Basic Yer Adı Otomatik Tamamlama öğesi için 5 km makul bir varsayılan değer olarak kabul edilir. Yarıçapı sıfır olan (tek bir nokta) bir görüntü alanı, yalnızca birkaç metre genişliğinde (100 m'den az) bir görüntü alanı veya tüm dünyayı kapsayan bir görüntü alanı ayarlamayın.

Yer aramasını ülkeye göre kısıtlama

Yer arama özelliğini bir veya daha fazla belirli ülkeyle kısıtlamak için includedRegionCodes özelliğini kullanarak ülke kodlarını aşağıdaki snippet'te gösterildiği gibi belirtin:

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

Yer aramasını harita sınırlarıyla kısıtlama

Yer arama özelliğini bir haritanın sınırlarıyla kısıtlamak için aşağıdaki snippet'te gösterildiği gibi sınırları eklemek üzere locationRestrictions özelliğini kullanın:

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

Harita sınırlarıyla kısıtlama yaparken, sınırlar değiştiğinde sınırları güncelleyecek bir dinleyici eklediğinizden emin olun:

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

locationRestriction öğesini kaldırmak için null olarak ayarlayın.

Yer arama sonuçlarını yönlendirme

locationBias özelliğini kullanarak ve bir yarıçap ileterek yer arama sonuçlarını dairesel bir alana yönlendirin:

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

locationBias öğesini kaldırmak için null olarak ayarlayın.

Yer arama sonuçlarını belirli türlerle kısıtlama

includedPrimaryTypes özelliğini kullanarak ve burada gösterildiği gibi bir veya daha fazla tür belirterek yer arama sonuçlarını belirli yer türleriyle kısıtlayın:

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

Desteklenen türlerin tam listesi için Yer türü tabloları A ve B'ye bakın.

Place Request öğesini yapılandırma

Kullanıcı bir tahmin seçtiğinde Place Request öğesini güncellemek için bir dinleyici ekleyin: 

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

Bu örnekte, Google Haritalar'a temel bir otomatik tamamlama öğesinin nasıl ekleneceği gösterilmektedir.

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>