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

Objectif : Remplacer votre implémentation de l'API Places ou de la classe Place par le kit d'UI Places.

À qui s'adresse ce guide ?

Les développeurs qui :

• Effectuer des requêtes HTTP vers les points de terminaison de l'API Places (nouvelle version ou version précédente)
• Utilisation de 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'UI de leur application Web.

Prérequis

Activez le kit d'interface utilisateur Places sur votre projet Google Cloud. Vous pouvez continuer à utiliser votre clé API existante ou en générer une pour Places UI Kit. 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 d'importation dynamique de bibliothèque 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 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 informations sur un lieu.

Implémentation actuelle

• Vous pouvez effectuer un appel Place Details à l'aide d'une requête HTTP ou utiliser la classe Place de l'API JavaScript.
• Vous analysez la réponse de l'API et affichez les informations sur le lieu à l'aide de HTML et de CSS.

Migration vers l'élément "Détails du lieu"

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 Détails du lieu.

Vous avez le choix entre deux éléments :

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

Pour savoir lequel utiliser, consultez Place Details Element.

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

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

• Récupérer un ID de lieu
• Utiliser PlacesService().getDetails() ou effectuer un appel de service Web.
• Spécifiez 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, sélectionnez manuellement vos éléments HTML et remplissez-les avec les données reçues.

Voici un exemple d'implémentation de Détails du lieu :

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

Remarque : Votre logique peut être différente si vous utilisez un appel d'API REST ou l'ancienne bibliothèque JavaScript.

Nouvelle logique

Votre nouvelle logique impliquera :

• Récupérez votre ID de lieu ou votre objet Lieu.
• Obtenez une référence à l'élément <gmp-place-details-place-request>.
• Transmettez l'identifiant de lieu ou l'objet Lieu à 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 Détails du lieu. Si cet élément existe, obtenez une référence à l'élément Place Request de Place Details et 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. Il est remplacé 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 pouvez effectuer une recherche de texte ou une recherche à proximité à l'aide d'une requête HTTP, ou utiliser 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 des 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 insérés suivants :

• <gmp-place-text-search-request> pour une recherche textuelle.
• <gmp-place-nearby-search-request> pour une recherche à proximité.

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 liste) et orientation (pour une mise en page horizontale ou verticale) peuvent être définis directement sur le composant parent.

Exemple de requête 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 recherche de texte

<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 de 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 de texte (<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 à proximité (<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 de texte, la recherche s'exécute dès que vous attribuez une valeur à textQuery.
• Pour une recherche à proximité, la recherche s'exécute après qu'un locationRestriction valide a été fourni.

Implémenter un é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 conservant un contrôle total sur la façon dont les résultats sont affichés dans votre interface utilisateur personnalisée. L'élément Autocomplete a pour seule responsabilité 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 ni aucune autre information accessible par programmation.

Implémentation actuelle

Votre logique existante implique probablement :

• Afficher un champ de saisie de texte sur votre page qui appelle Place Autocomplete lorsque l'utilisateur saisit du texte et affiche les résultats.
• Utilisez l'ID du lieu sélectionné par l'utilisateur pour obtenir 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 d'entrée 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 de saisie semi-automatique de base pour les lieux 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 de saisie semi-automatique de base des lieux et écoutera les événements gmp-select :

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

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

L'événement gmp-select est déclenché lorsqu'un lieu est sélectionné dans la liste déroulante de saisie semi-automatique. L'ID 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é.

Personnaliser votre identifiant

Personnalisation de l'élément Place Details

Orientation

L'élément "Détails du lieu" peut être affiché à l'horizontale ou à la verticale. Utilisez l'attribut orientation sur gmp-place-details-compact pour choisir entre les orientations 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 PlaceDetails. Par exemple, si vous excluez l'élément de contenu <gmp-place-type>, l'élément Place Details ne rendra plus le type de 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 "Détails du lieu" ne modifie pas le coût de rendu 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 de PlaceDetailsCompactElement.

Personnalisation de l'élément Place Search

Orientation

L'élément de recherche de lieux peut être affiché à l'horizontale ou à la verticale. Utilisez l'attribut orientation sur <gmp-place-search> pour choisir entre vertical et horizontal. 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 l'intégralité du contenu. Vous pouvez également utiliser une sélection de balises HTML pour configurer le contenu affiché.

L'inclusion de <gmp-place-address> dans <gmp-place-content-config> n'affichera que l'adresse de chaque lieu, 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 de saisie semi-automatique. 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 d'UI 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 de saisie semi-automatique de base pour les lieux, 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 l'élément et son contenu ont fini de se charger et de s'afficher.
• gmp-requesterror : déclenché lorsqu'une requête envoyé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 des données spécifiques à partir des éléments de manière programmatique après qu'ils ont été utilisés ou chargés.

• Pour l'élément Place Search et l'élément Place Details, vous pouvez récupérer les informations suivantes :
  • ID de lieu
  • Position (latitude et longitude)
  • Fenêtre d'affichage
• Pour l'élément Place Autocomplete de base, 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 individuelle des éléments Place Search, Place Details et Basic Place Autocomplete.

Tests et amélioration

Une fois que vous avez intégré un ou plusieurs éléments du kit d'interface utilisateur 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 et aborder tous les éléments que vous avez implémentés : les éléments Place Details, Place Search et Basic Place Autocomplete.

Élément Place Details

Pour l'élément Détails du lieu, commencez par vérifier que les détails s'affichent correctement pour une grande variété de lieux. Testez 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 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 de recherche de lieux

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 recherche de texte, 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 générales, adresses spécifiques et requêtes avec des biais de localisation.
• Pour une recherche à proximité, 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 zones géographiques et différents types de filtres.

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 de saisie semi-automatique de base de lieux, concentrez les tests sur l'interaction 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 dans le 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 remplir un autre élément, tel que l'élément Place Details.

Traiter les erreurs

Il est essentiel de tester rigoureusement la gestion des erreurs dans 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 déroutante.