Podstawowy element autouzupełniania miejsca

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

Komponent Autouzupełnianie miejsc (podstawowy) jest łatwiejszy do wdrożenia niż PlaceAutocompleteElement i różni się od niego w następujący sposób:

  • Element Autouzupełnianie miejsc zwraca obiekt Place zawierający tylko identyfikator miejsca, a nie obiekt PlacePrediction. Zwrócony identyfikator miejsca możesz użyć bezpośrednio z elementem szczegółów interfejsu Places UI Kit, aby uzyskać dodatkowe informacje o miejscu, podczas gdy obiekt PlacePrediction wymagałby najpierw konwersji na identyfikator miejsca.
  • Element Basic Place Autocomplete nie wymaga włączenia interfejsu Places API w Google Cloud Console.
  • Komponent Autouzupełnianie miejsc (podstawowe) czyści pole do wprowadzania danych, gdy użytkownik wybierze podpowiedź miejsca.

Wymagania wstępne

Aby korzystać z podstawowego elementu autouzupełniania miejsc, musisz włączyć w projekcie Google Cloud pakiet Places UI Kit. Więcej informacji znajdziesz w artykule Pierwsze kroki.

Dodawanie podstawowego elementu autouzupełniania miejsc

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

Dodawanie elementu podstawowego autouzupełniania do strony internetowej

Aby dodać element BasicAutocomplete do strony internetowej, utwórz nowy element 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 do mapy elementu podstawowego autouzupełniania

Aby dodać do mapy element podstawowego autouzupełniania, dołącz element BasicPlaceAutocompleteElement do elementu gmp-map i ustaw jego pozycję za pomocą atrybutu slot, jak 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 podstawowe autouzupełnianie miejsc wyświetla wszystkie typy miejsc, faworyzując podpowiedzi w pobliżu lokalizacji użytkownika. Ustaw BasicPlaceAutocompleteElementOptions, aby wyświetlać trafniejsze podpowiedzi przez ograniczenie lub ukierunkowanie wyników.

Ograniczenie wyników powoduje, że element Autouzupełnianie podstawowe ignoruje wszystkie wyniki, które znajdują się poza obszarem ograniczenia. Powszechną praktyką jest ograniczanie wyników do granic mapy. Dzięki temu element BasicAutocomplete wyświetla wyniki w określonym obszarze, ale niektóre dopasowania mogą znajdować się poza nim.

Jeśli nie podasz żadnych granic ani widocznego obszaru mapy, interfejs API spróbuje wykryć lokalizację użytkownika na podstawie jego adresu IP i będzie faworyzować wyniki z tej lokalizacji. W miarę możliwości ustawiaj granice. W przeciwnym razie różni użytkownicy mogą otrzymywać różne podpowiedzi. Aby ogólnie poprawić podpowiedzi, ważne jest, aby podać odpowiedni widoczny obszar, np. ustawiony przez przesuwanie lub powiększanie mapy, albo widoczny obszar ustawiony przez dewelopera na podstawie lokalizacji urządzenia i promienia. Jeśli promień nie jest dostępny, w przypadku podstawowego elementu autouzupełniania miejsc za rozsądną wartość domyślną 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(),
});

Jeśli ograniczasz widok do granic mapy, dodaj detektor, który będzie aktualizować granice, gdy się zmienią:

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

Aby usunąć locationRestriction, ustaw wartość null.

Wpływanie na wyniki wyszukiwania miejsc

Możesz zawęzić wyniki wyszukiwania miejsc do obszaru kołowego, używając właściwości locationBias i podają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 wartość 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 poniżej:

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

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

Konfigurowanie elementu Place Request

Dodaj detektor, aby zaktualizować 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ć do mapy Google podstawowy element autouzupełniania.

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>