Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Adopter le kit UI pour Places pour les utilisateurs existants de l'API Places

Découvrez comment migrer votre implémentation existante de l'API Places ou de la classe Place vers les composants du kit UI pour Places.

À qui s'adresse ce guide ?

Ce guide s'adresse aux développeurs qui disposent d'une implémentation existante utilisant l'API Places et qui souhaitent mettre à jour leur code pour utiliser le Kit UI pour Places. Il vous sera plus utile si vous êtes déjà :

En envoyant des requêtes HTTP aux points de terminaison de l'API Places (nouvelle ou ancienne version).
Utiliser la classe Place dans l'API Maps JavaScript
Gérer la réponse de l'API pour afficher les informations sur le lieu dans l'interface utilisateur de votre application Web.

Prérequis

Activez le kit d'UI Places sur votre projet Google Cloud. Vous pouvez continuer à utiliser votre clé API existante ou en générer une nouvelle pour le Kit UI pour Places. Pour en savoir plus, y compris sur la restriction d'une clé, consultez Utiliser des clés API.

Mettre à jour le chargement de l'API Maps JavaScript

Le Kit UI pour Places nécessite la méthode Dynamic Library Import pour charger l'API Maps JavaScript. Si vous utilisez la balise de chargement de script en direct, vous devez la mettre à jour.

Une fois que vous avez mis à jour le script de chargement de l'API Maps JavaScript, importez les bibliothèques requises pour utiliser le kit UI pour Places.

Implémenter l'élément Place Details

Les éléments Place Details et Place Details Compact sont des éléments HTML qui affichent des détails sur un lieu.

Implémentation actuelle

Vous effectuez un appel Place Details à l'aide d'une requête HTTP ou vous utilisez la classe Place de l'API JavaScript.
Vous analysez la réponse de l'API et affichez les détails du lieu à l'aide de code HTML et CSS.

Migration vers l'élément Place Details

Modifier la structure HTML

Identifiez le conteneur HTML dans lequel les détails du lieu sont affichés. Remplacez vos éléments HTML personnalisés (divs, spans pour le nom, l'adresse, les photos, etc.) par le code HTML de l'élément Place Details.

Vous avez le choix entre deux éléments :

Élément compact Place Details
Élément Place Details

Pour en savoir plus sur l'élément à utiliser, consultez Élément Place Details.

Votre code HTML existant peut ressembler à ceci.

<div id="my-place-details-container">
    <h2 id="place-name"></h2>
    <p id="place-address"></p>
    <img id="place-photo" src="" alt="Place photo">
    <!-- ... more custom elements -->
</div>

Exemple de nouveau code HTML, indiquant explicitement le contenu à afficher :

<gmp-place-details-compact orientation="horizontal" truncation-preferred style="display: none;">
    <gmp-place-details-place-request></gmp-place-details-place-request>
    <gmp-place-content-config>
        <gmp-place-media lightbox-preferred></gmp-place-media>
        <gmp-place-address></gmp-place-address>
        <gmp-place-rating></gmp-place-rating>
        <gmp-place-type></gmp-place-type>
        <gmp-place-price></gmp-place-price>
        <gmp-place-accessible-entrance-icon></gmp-place-accessible-entrance-icon>
        <gmp-place-open-now-status></gmp-place-open-now-status>
    </gmp-place-content-config>
</gmp-place-details-compact>

Adapter la logique JavaScript

Logique existante

Votre logique existante implique probablement les éléments suivants :

Récupérer un ID de lieu.
Utiliser PlacesService().getDetails() ou effectuer un appel de service Web.
Spécifier un tableau de champs (pour l'API JS) ou un FieldMask (pour le service Web) pour demander des données spécifiques.
Dans la résolution du rappel, en sélectionnant manuellement vos éléments HTML et en les remplissant avec les données reçues.

Voici un exemple d'implémentation de Place Details :

async function getPlaceDetails(placeId) {
    const { Place } = await google.maps.importLibrary('places');
    // Use place ID to create a new Place instance.
    const place = new Place({
        id: placeId
    });
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    // Log the result
    console.log(place.displayName);
    console.log(place.formattedAddress);
}

Nouvelle logique

Votre nouvelle logique impliquera les éléments suivants :

Récupérez votre ID de lieu ou votre objet Place.
Obtenez une référence à l'élément <gmp-place-details-place-request>.
Transmettez l'ID de lieu ou l'objet Place à la propriété "place" de l'élément <gmp-place-details-place-request>.

Voici un exemple d'implémentation du kit UI Place Details dans votre logique JavaScript. Obtenez une référence à l'élément Place Details. Si elle existe, obtenez une référence à l'élément Place Request de Place Details, puis définissez la propriété "place" à l'aide d'un ID de lieu. Dans l'exemple de code HTML ci-dessus, le style de l'élément Place Details est défini sur display: none. Cette valeur est remplacée par display: block.

function displayPlaceDetailsWithUIKit(placeId) {
  const placeDetailsElement = document.querySelector('gmp-place-details-compact');
  if (placeDetailsElement) {
    const placeDetailsRequest = document.querySelector('gmp-place-details-place-request');
    // Configure the element with the Place ID
    placeDetailsRequest.place = placeId
    placeDetailsElement.style.display = 'block';
    console.log("PlaceDetailsElement configured for place:", placeId);
  } else {
    console.error("PlaceDetailsElement not found in the DOM.");
  }
}

// Example usage:
const placeId = 'ChIJC8HakaIRkFQRiOgkgdHmqkk';
displayPlaceDetailsWithUIKit(placeId);

Implémenter l'élément Place Search

L'élément Place Search est un élément HTML qui affiche les résultats d'une recherche de lieux dans une liste.

Implémentation actuelle

Vous effectuez une recherche textuelle ou une recherche à proximité à l'aide d'une requête HTTP, ou vous utilisez la classe Place de l'API JavaScript.
Vous spécifiez les paramètres de requête, les restrictions ou les biais de localisation, les types et les champs demandés à l'aide de FieldMask.
Vous analysez la réponse de l'API, parcourez le tableau de lieux et créez manuellement des éléments de liste HTML.

Migration vers l'élément Place Search

Modifier la structure HTML

Identifiez le conteneur HTML dans lequel vous affichez votre liste de lieux. Remplacez vos éléments HTML personnalisés (divs, spans pour le nom, l'adresse, etc.) par l'élément HTML Place Search Element.

Votre code HTML existant peut se présenter comme suit :

<div id="search-results-area">
    <h3>Nearby Places:</h3>
    <ul id="manual-places-list">
        <!-- JavaScript would dynamically insert list items here -->
        <!-- Example of what JS might generate:
    <li class="place-entry" data-place-id="SOME_PLACE_ID_1">
      <img class="place-icon" src="icon_url_1.png" alt="Icon">
      <span class="place-name">Place Name One</span> -
      <span class="place-vicinity">123 Main St</span>
    </li>
    <li class="place-entry" data-place-id="SOME_PLACE_ID_2">
      <img class="place-icon" src="icon_url_2.png" alt="Icon">
      <span class="place-name">Place Name Two</span> -
      <span class="place-vicinity">456 Oak Ave</span>
    </li>
    -->
        <li class="loading-message">Loading places...</li>
    </ul>
</div>

L'élément Place Search est implémenté à l'aide du composant <gmp-place-search>. Pour configurer le type de recherche, incluez l'un des composants de configuration d'emplacement suivants :

<gmp-place-text-search-request> pour une recherche textuelle.
<gmp-place-nearby-search-request> pour une requête Nearby Search.

Pour définir la façon dont les résultats sont affichés, vous pouvez utiliser le raccourci <gmp-place-all-content> ou fournir votre propre ensemble de composants de présentation individuels. Les attributs clés tels que selectable (pour autoriser les clics sur les éléments de la liste) et orientation (pour une mise en page horizontale ou verticale) peuvent être définis directement sur le composant parent.

Exemple de Nearby Search

<gmp-place-search orientation="horizontal" selectable>
    <gmp-place-all-content> </gmp-place-all-content>
    <gmp-place-nearby-search-request></gmp-place-nearby-search-request>
</gmp-place-search>

Exemple de Text Search

<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-all-content> </gmp-place-all-content>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

Adapter la logique JavaScript

Dans votre code JavaScript, obtenez une référence au composant du contrôleur de recherche à l'aide de document.querySelector(). Selon votre configuration, il s'agira de l'élément <gmp-place-text-search-request> ou <gmp-place-nearby-search-request>.

Ensuite, définissez les propriétés de ce contrôleur pour définir votre recherche. Les propriétés requises dépendent du type de recherche que vous effectuez.

Pour une recherche textuelle (<gmp-place-text-search-request>), la propriété principale est textQuery :

const textSearchController = document.querySelector('gmp-place-text-search-request');
textSearchController.textQuery = 'museums in London';

Pour une recherche Nearby Search (<gmp-place-nearby-search-request>), vous devez définir la zone de recherche à l'aide d'un locationRestriction. Vous pouvez ensuite utiliser includedTypes pour filtrer des types de lieux spécifiques dans cette zone :

const nearbySearchController = document.querySelector('gmp-place-nearby-search-request');
nearbySearchController.locationRestriction = new google.maps.Circle({
    center: { lat: 51.5190, lng: -0.1347 },
    radius: 1000
});
nearbySearchController.includedTypes = ['restaurant'];

Le composant parent <gmp-place-search> lance automatiquement une nouvelle recherche dès que les propriétés requises de son contrôleur sont définies.

Pour une recherche textuelle, la recherche s'exécute dès que vous attribuez une valeur à textQuery.
Pour une recherche Nearby Search, la recherche est exécutée après qu'un locationRestriction valide a été fourni.

Implémenter l'élément Place Autocomplete de base

Pour les développeurs qui ont besoin d'une expérience de recherche sans l'UI fournie par l'élément Place Search, l'élément Basic Place Autocomplete est disponible.

Cet élément est idéal pour créer un champ de saisie de recherche tout en gardant un contrôle total sur l'affichage des résultats dans votre interface utilisateur personnalisée. L'élément Autocomplete a pour seul rôle de fournir des prédictions de lieux à mesure que l'utilisateur saisit du texte et d'exposer de manière programmatique un ID de lieu pour le lieu sélectionné.

Il n'affiche aucun détail et ne fournit aucune autre information accessible par programmation.

Implémentation actuelle

Votre logique existante implique probablement les éléments suivants :

Afficher un champ de saisie de texte sur votre page qui appelle Place Autocomplete à mesure que l'utilisateur tape, et affiche les résultats.
Utiliser l'ID de lieu du lieu sélectionné par l'utilisateur pour récupérer plus de détails, par exemple à l'aide de l'API Place Details.
Affichage des détails du lieu sélectionné.

Migration vers l'élément Place Autocomplete

Modifier la structure HTML

Identifiez et supprimez l'élément HTML auquel vous associez le widget Autocomplete. Il utilise probablement un champ de saisie HTML standard.

<input id="pac-input" type="text" placeholder="Search for a location" />

Exemple de nouveau code HTML, utilisant l'approche des composants Web pour initialiser un élément Place Autocomplete Basic sur votre page.

<gmp-basic-place-autocomplete></gmp-basic-place-autocomplete>

Adapter la logique JavaScript

Votre logique JavaScript implique probablement la création du widget Autocomplete associé à un élément HTML input. Ce widget écoute ensuite l'événement place_changed, ce qui déclenche une action avec les données renvoyées.

Exemple de code JavaScript existant à supprimer :

// Get the input element
const input = document.getElementById("pac-input");

// Create the Autocomplete widget instance
const autocomplete = new google.maps.places.Autocomplete(input, {
  fields: ["place_id", "geometry", "name"]
});

// Add a listener for the 'place_changed' event
autocomplete.addListener("place_changed", () => {
  // Your logic to get and display place information
  console.log(place.place_id);
});

Votre nouvelle logique JavaScript obtiendra une référence à l'élément Basic Place Autocomplete et écoutera les événements gmp-select :

const placeAutocomplete = document.querySelector('gmp-basic-place-autocomplete');

placeAutocomplete.addEventListener('gmp-select', (event) => {
  console.log(event.place);
});

Lorsqu'un lieu est sélectionné dans le menu déroulant de saisie semi-automatique, l'événement gmp-select se déclenche. L'ID de lieu du lieu sélectionné peut être récupéré à partir de l'objet event. L'ID de lieu peut ensuite être utilisé pour initialiser une instance de l'élément Place Details afin d'afficher les détails du lieu sélectionné.

Personnalisation de la poignée

Personnalisation de l'élément Place Details

Orientation

L'élément Place Details peut être affiché à l'horizontale ou à la verticale. Utilisez l'attribut orientation sur gmp-place-details-compact pour choisir entre l'orientation verticale et horizontale. Exemple :

<gmp-place-details-compact orientation="vertical">

Choisir les champs à afficher

Utilisez des éléments de contenu pour spécifier le contenu à afficher dans l'élément Place Details. Par exemple, l'exclusion de l'élément de contenu <gmp-place-type> empêche l'élément Place Details d'afficher le type de lieu du lieu sélectionné. Pour obtenir la liste complète des éléments de contenu, consultez la documentation de référence sur PlaceContentConfigElement.

L'ajout ou la suppression de champs dans l'élément Place Details ne modifie pas le coût d'affichage de l'élément sur la page.

Définir des styles CSS

Des propriétés CSS personnalisées sont disponibles pour configurer les couleurs et les polices de l'élément. Par exemple, pour définir l'arrière-plan de l'élément sur vert, définissez la propriété CSS suivante :

gmp-place-details-compact {
  --gmp-mat-color-surface: green;
}

Pour en savoir plus, consultez la documentation de référence sur PlaceDetailsCompactElement.

Personnalisation de l'élément Place Search

Orientation

L'élément Place Search peut être affiché à l'horizontale ou à la verticale. Utilisez l'attribut orientation sur <gmp-place-search> pour choisir entre l'orientation verticale et l'orientation horizontale. Exemple :

<gmp-place-search orientation="horizontal" selectable>

Choisir les champs à afficher

Utilisez des éléments de contenu pour spécifier le contenu à afficher dans l'élément Place Search. L'élément <gmp-place-all-content> peut être utilisé pour afficher tout le contenu, ou une sélection de balises HTML peut être utilisée pour configurer le contenu affiché.

Si vous incluez <gmp-place-address> dans <gmp-place-content-config>, seule l'adresse de chaque lieu s'affiche, par exemple :

<gmp-place-search orientation="horizontal" selectable>
  <gmp-place-content-config>
    <gmp-place-address></gmp-place-address>
  </gmp-place-content-config>
  <gmp-place-text-search-request></gmp-place-text-search-request>
</gmp-place-search>

Personnalisation de base de l'élément Place Autocomplete

Définir des styles CSS

Des propriétés CSS personnalisées sont disponibles pour personnaliser l'apparence de l'élément Autocomplete. Par exemple, pour définir la couleur d'arrière-plan sur violet clair, vous devez définir la propriété background-color sur l'élément.

gmp-basic-place-autocomplete {
  background-color: #d993e6;
}

Pour en savoir plus, consultez la documentation de référence sur BasicPlaceAutocompleteElement.

Gérer les événements et les données

Les éléments du kit UI pour Places sont des composants interactifs qui vous permettent d'écouter des événements et de récupérer des données de manière programmatique.

Écouter les événements

Vous pouvez ajouter des écouteurs d'événements aux éléments pour déclencher des actions en fonction de l'interaction de l'utilisateur ou de l'état de l'élément.

Événement de sélection

gmp-select : cet événement est déclenché lorsqu'un utilisateur effectue une sélection.
- Sur l'élément Place Search, il est déclenché lorsqu'un utilisateur clique sur un lieu dans la liste des résultats.
- Sur l'élément Place Autocomplete de base, il est déclenché lorsqu'un utilisateur clique sur une prédiction dans la liste déroulante.

Événements courants

Les éléments Place Search, Place Details et Basic Place Autocomplete sont tous compatibles avec les événements suivants :

gmp-load : déclenché lorsque le chargement et l'affichage de l'élément et de son contenu sont terminés.
gmp-requesterror : se déclenche lorsqu'une requête adressée au serveur échoue, par exemple en raison d'une clé API non valide.

Accéder aux données des éléments de manière programmatique

Vous pouvez récupérer de manière programmatique des données spécifiques à partir des éléments après qu'ils ont été chargés ou que l'utilisateur a interagi avec eux.

Pour les éléments Place Search et Place Details, vous pouvez récupérer les informations suivantes :
- ID de lieu
- Emplacement (latitude et longitude)
- Fenêtre d'affichage
Pour l'élément Place Autocomplete Basic, vous pouvez récupérer les informations suivantes :
- ID de lieu

Toutes les autres données contenues dans les éléments ne sont pas accessibles par programmation.

Pour obtenir des exemples plus détaillés, consultez la documentation de l'élément Place Search, de l'élément Place Details et de l'élément Basic Place Autocomplete.

Une fois que vous avez intégré un ou plusieurs éléments du kit UI pour Places, il est essentiel de les tester pour assurer une transition fluide et une expérience utilisateur positive. Vos tests doivent couvrir plusieurs domaines clés, en abordant tous les éléments que vous avez implémentés : Place Details, Place Search et Basic Place Autocomplete.

Élément Place Details

Pour l'élément Place Details, commencez par vérifier que les détails s'affichent correctement pour différents types de lieux. Effectuez un test en transmettant différents ID de lieu à la propriété .place de l'élément <gmp-place-details-place-request>. Utilisez des ID représentant différents types d'établissements (entreprises avec des données enrichies, points d'intérêt, adresses de base) et des lieux dans différentes régions ou langues. Portez une attention particulière à la mise en forme, à la mise en page et à la présence du contenu.

Élément Place Search

Si vous avez implémenté l'élément Place Search, vérifiez son rendu et son comportement dans différents scénarios de recherche.

Pour une Text Search, effectuez un test en définissant la propriété textQuery sur l'élément <gmp-place-text-search-request> avec différentes entrées : requêtes larges, adresses spécifiques et requêtes avec des pondérations de localisation.
Pour une recherche Nearby Search, effectuez un test en définissant les propriétés locationRestriction et includedTypes sur l'élément <gmp-place-nearby-search-request>. Utilisez différentes tailles de lieu et différents filtres de type.

Vérifiez que la liste contient des résultats pertinents et que l'événement gmp-select se déclenche correctement lors de la sélection.

Élément Place Autocomplete de base

Pour l'élément Place Autocomplete Basic, concentrez les tests sur l'interaction de l'utilisateur et les données transmises par l'événement de sélection. Vérifiez que l'événement gmp-select se déclenche de manière fiable lorsqu'un utilisateur clique sur une prédiction. Vérifiez que l'objet event.place du gestionnaire d'événements contient un ID de lieu valide.

Plus important encore, testez le flux de bout en bout : sélectionnez un lieu dans le menu déroulant Autocomplete et vérifiez que son ID de lieu peut être utilisé pour renseigner un autre élément, tel que l'élément Place Details.

Gestion des exceptions

Il est essentiel de tester rigoureusement la gestion des erreurs sur tous les composants. Simulez la transmission d'ID de lieu non valides ou inexistants à l'élément Place Details, ou l'utilisation de paramètres de recherche non valides pour l'élément Place Search. Déclenchez l'événement gmp-requesterror en simulant des problèmes de réseau ou en utilisant une clé API non valide pour vous assurer que votre application le gère correctement. Implémentez des messages d'erreur et une journalisation conviviaux pour éviter une UI défectueuse ou confuse.

Adopter le kit UI pour Places pour les utilisateurs existants de l'API Places Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

À qui s'adresse ce guide ?

Prérequis

Mettre à jour le chargement de l'API Maps JavaScript

Implémenter l'élément Place Details

Implémentation actuelle

Migration vers l'élément Place Details

Modifier la structure HTML

Adapter la logique JavaScript

Logique existante

Nouvelle logique

Implémenter l'élément Place Search

Implémentation actuelle

Migration vers l'élément Place Search

Modifier la structure HTML

Exemple de Nearby Search

Exemple de Text Search

Adapter la logique JavaScript

Implémenter l'élément Place Autocomplete de base

Implémentation actuelle

Migration vers l'élément Place Autocomplete

Modifier la structure HTML

Adapter la logique JavaScript

Personnalisation de la poignée

Personnalisation de l'élément Place Details

Orientation

Choisir les champs à afficher

Définir des styles CSS

Personnalisation de l'élément Place Search

Orientation

Choisir les champs à afficher

Personnalisation de base de l'élément Place Autocomplete

Définir des styles CSS

Gérer les événements et les données

Écouter les événements

Événement de sélection

Événements courants

Accéder aux données des éléments de manière programmatique

Tests et affinement

Adopter le kit UI pour Places pour les utilisateurs existants de l'API Places