Élément Place Autocomplete de base

Sélectionnez la plate-forme : Android iOS JavaScript

Le BasicPlaceAutocompleteElement crée un champ de saisie de texte, fournit des prédictions de lieu dans une liste de sélection d'UI et renvoie un ID de lieu pour le lieu sélectionné.

L'élément Basic Place Autocomplete est plus simple à implémenter que le PlaceAutocompleteElement et présente les différences suivantes :

  • L'élément Basic Place Autocomplete renvoie un objet Place contenant uniquement l' ID de lieu, plutôt qu'un PlacePrediction objet. Vous pouvez utiliser l'ID de lieu renvoyé directement avec un élément Kit UI pour Places Details pour obtenir des informations supplémentaires sur le lieu, alors qu'un PlacePrediction objet nécessiterait d'abord une conversion en ID de lieu.
  • L'élément Basic Place Autocomplete ne nécessite pas l'activation de l'API Places dans la console Google Cloud.
  • L'élément Basic Place Autocomplete efface le champ de saisie lorsqu'un utilisateur sélectionne une prédiction de lieu.

Prérequis

Pour utiliser l'élément Basic Place Autocomplete, vous devez activer le Kit UI pour Places dans votre projet Google Cloud. Pour en savoir plus, consultez Commencer.

Ajouter un élément Basic Place Autocomplete

Cette section explique comment ajouter un élément Basic Autocomplete à une page Web ou à une carte.

Ajouter un élément Basic Autocomplete à une page Web

Pour ajouter l'élément BasicAutocomplete à une page Web, créez un nouvel élément google.maps.places.BasicPlaceAutocompleteElement, puis ajoutez-le à la page comme illustré dans l'exemple suivant : 

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

Ajouter un élément Basic Autocomplete à une carte

Pour ajouter un élément Basic Autocomplete à une carte, ajoutez un BasicPlaceAutocompleteElement à un gmp-map élément et définissez sa position à l'aide de l'attribut slot, comme illustré dans l'exemple suivant :

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

Limiter les prédictions de saisie semi-automatique

Par défaut, Basic Place Autocomplete présente tous les types de lieux, avec une pondération pour les prédictions à proximité de l'emplacement de l'utilisateur. Définissez BasicPlaceAutocompleteElementOptions pour présenter des prédictions plus pertinentes en limitant ou en pondérant les résultats.

Si vous limitez les résultats, l'élément Basic Autocomplete ignore tous les résultats en dehors de la zone de restriction. Une pratique courante consiste à limiter les résultats aux limites de la carte. Pondérer la saisie semi-automatique permet d'afficher les résultats dans la zone spécifiée. Toutefois, certaines correspondances peuvent se trouver en dehors de cette zone.

Si vous ne définissez pas de limite ni de fenêtre d'affichage de la carte, l'API tentera de détecter l'emplacement de l'utilisateur en fonction de son adresse IP et pondérera les résultats en conséquence. Définissez des limites chaque fois que cela est possible. Sinon, différents utilisateurs peuvent recevoir des prédictions différentes. De plus, pour améliorer les prédictions de manière générale, il est important de fournir une fenêtre d'affichage pertinente telle que celle que vous définissez en faisant un panoramique ou un zoom sur la carte, ou une fenêtre d'affichage définie par le développeur en fonction de la position de l'appareil et du rayon. Si aucun rayon n'est disponible, un rayon de 5 km est considéré comme une valeur par défaut raisonnable pour l'élément Basic Place Autocomplete. Ne définissez pas une fenêtre d'affichage avec un rayon égal à zéro (un seul point), ni une fenêtre d'affichage qui n'inclut que quelques mètres (moins de 100 m) ou s'étend à tout le globe terrestre.

Restreindre la recherche de lieux par pays

Pour limiter la recherche de lieux à un ou plusieurs pays spécifiques, utilisez la includedRegionCodes propriété pour spécifier le ou les codes pays, comme indiqué dans l'extrait suivant :

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

Restreindre la recherche de lieux aux limites de la carte

Pour limiter la recherche de lieux aux limites d'une carte, utilisez la locationRestrictions propriété pour ajouter les limites, comme indiqué dans l'extrait suivant :

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

Lorsque vous restreignez la recherche aux limites de la carte, veillez à ajouter un écouteur pour modifier les limites lorsqu'elles changent :

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

Pour supprimer le locationRestriction, définissez-le sur null.

Pondérer les résultats de recherche de lieu

Pour pondérer les résultats de recherche sur une zone circulaire, utilisez la propriété locationBias et transmettez un rayon, comme indiqué ci-dessous :

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

Pour supprimer le locationBias, définissez-le sur null.

Limiter les résultats de recherche de lieux à certains types

Pour limiter les résultats de recherche de lieux à certains types de lieux, utilisez la includedPrimaryTypes propriété et indiquez un ou plusieurs types, comme indiqué ci-dessous :

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

Pour obtenir la liste complète des types pris en charge, consultez les tableaux A et B des types de lieux.

Configurer l'élément Place Request

Ajoutez un écouteur pour mettre à jour l'élément Place Request lorsque l'utilisateur sélectionne une prédiction : 

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

Cet exemple vous explique comment ajouter un élément Basic Autocomplete à une carte 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>