Podstawowy element autouzupełniania miejsca

Wybierz platformę: Android iOS JavaScript

The BasicPlaceAutocompleteElement tworzy pole wprowadzania tekstu, wyświetla podpowiedzi miejsc na liście wyboru w interfejsie i zwraca identyfikator wybranego miejsca.

Element autouzupełniania podstawowego miejsca jest prostszy we wdrożeniu niż PlaceAutocompleteElement i różni się od niego w tych aspektach:

  • Element autouzupełniania podstawowego miejsca zwraca obiekt Place zawierający tylko identyfikator miejsca, a nie PlacePrediction obiekt. Zwrócony identyfikator miejsca możesz użyć bezpośrednio z elementem szczegółów Places UI Kit , aby uzyskać dodatkowe informacje o miejscu, natomiast obiekt PlacePrediction wymaga najpierw przekonwertowania na identyfikator miejsca.
  • Element Basic Autouzupełniania miejsc nie wymaga włączenia interfejsu Places API w konsoli Google Cloud.
  • Element autouzupełniania podstawowego miejsca czyści pole wprowadzania, gdy użytkownik wybierze podpowiedź miejsca.

Wymagania wstępne

Aby używać elementu autouzupełniania podstawowego miejsca, musisz włączyć Places UI Kit w projekcie Google Cloud. Więcej informacji znajdziesz w przewodniku dla początkujących.

Dodawanie elementu autouzupełniania miejsc Basic

W tej sekcji dowiesz się, jak dodać element autouzupełniania podstawowego do strony internetowej lub mapy.

Dodawanie elementu autouzupełniania podstawowego do strony internetowej

Aby dodać element BasicAutocomplete do strony internetowej, utwórz nowy google.maps.places.BasicPlaceAutocompleteElement, i dołącz go do strony, jak pokazano w tym przykładzie: 

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

Dodawanie elementu autouzupełniania podstawowego do mapy

Aby dodać element autouzupełniania podstawowego do mapy, dołącz element BasicPlaceAutocompleteElement do elementu gmp-map i ustaw jego pozycję za pomocą atrybutu slot, jak pokazano w tym przykładzie:

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

Ograniczanie podpowiedzi autouzupełniania

Domyślnie autouzupełnianie podstawowego miejsca wyświetla wszystkie typy miejsc, z uwzględnieniem podpowiedzi w pobliżu lokalizacji użytkownika. Ustaw BasicPlaceAutocompleteElementOptions, aby wyświetlać trafniejsze podpowiedzi ograniczając lub uwzględniając wyniki.

Ograniczenie wyników powoduje, że element autouzupełniania podstawowego ignoruje wszystkie wyniki, które znajdują się poza obszarem ograniczenia. Powszechną praktyką jest ograniczanie wyników do granic mapy. Uwzględnianie wyników powoduje, że element BasicAutocomplete wyświetla wyniki w określonym obszarze, ale niektóre dopasowania mogą znajdować się poza tym obszarem.

Jeśli nie podasz żadnych granic ani widocznego obszaru mapy, interfejs API spróbuje wykryć lokalizację użytkownika na podstawie jego adresu IP i uwzględni wyniki w tej lokalizacji. Jeśli to możliwe, ustaw granice. W przeciwnym razie różni użytkownicy mogą otrzymywać różne podpowiedzi. Aby ogólnie poprawić podpowiedzi, ważne jest też, aby podać rozsądny widoczny obszar, np. taki, który ustawisz, przesuwając lub powiększając mapę, albo widoczny obszar ustawiony przez dewelopera na podstawie lokalizacji i promienia urządzenia. Gdy promień jest niedostępny, za rozsądną wartość domyślną dla elementu autouzupełniania podstawowego miejsca uznaje się 5 km. Nie ustawiaj widocznego obszaru o zerowym promieniu (pojedynczy punkt), widocznego obszaru o szerokości zaledwie kilku metrów (mniej niż 100 m) ani widocznego obszaru obejmującego cały świat.

Ograniczanie wyszukiwania miejsc według kraju

Aby ograniczyć wyszukiwanie miejsc do co najmniej 1 konkretnego kraju, użyj właściwości includedRegionCodes , aby określić kody krajów, jak pokazano w tym fragmencie kodu:

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

Ograniczanie wyszukiwania miejsc do granic mapy

Aby ograniczyć wyszukiwanie miejsc do granic mapy, użyj właściwości locationRestrictions , aby dodać granice, jak pokazano w tym fragmencie kodu:

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

Ograniczając wyszukiwanie do granic mapy, pamiętaj, aby dodać detektor, który będzie aktualizować granice, gdy się zmienią:

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

Aby usunąć locationRestriction, ustaw ją na null.

Uwzględnianie wyników wyszukiwania miejsc

Uwzględnij wyniki wyszukiwania miejsc w obszarze koła, używając właściwości locationBias i przekazując promień, jak pokazano tutaj:

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

Aby usunąć locationBias, ustaw ją na null.

Ograniczanie wyników wyszukiwania miejsc do określonych typów

Ogranicz wyniki wyszukiwania miejsc do określonych typów miejsc, używając właściwości includedPrimaryTypes i określając co najmniej 1 typ, jak pokazano tutaj:

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

Pełną listę obsługiwanych typów znajdziesz w tabelach typów miejsc A i B.

Konfigurowanie elementu żądania miejsca

Dodaj detektor, który będzie aktualizować element żądania miejsca, gdy użytkownik wybierze podpowiedź: 

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

Ten przykład pokazuje, jak dodać element autouzupełniania podstawowego do mapy 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>