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 particulièrement utile si vous :

effectuez des requêtes HTTP auprès des points de terminaison de l'API Places (nouvelle ou ancienne) ;
utilisez la classe Place dans l'API Maps JavaScript ;
gérez la réponse de l'API pour afficher des informations sur le lieu dans l'interface utilisateur de votre application Web.

Prérequis

Activez le Kit UI pour Places sur votre projet Google Cloud. Vous pouvez continuer à utiliser votre clé API existante ou en générer une 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 d'importation dynamique de la bibliothèque pour charger l'API Maps JavaScript. Si vous utilisez la balise de chargement de script 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 Element et Place Details Compact Element sont des éléments HTML qui affichent des informations sur un lieu.

Implémentation actuelle

Vous effectuez un appel Place Details à l'aide d'une requête HTTP ou utilisez 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.

Migrer vers l'élément Place Details

Modifier la structure HTML

Identifiez le conteneur HTML dans lequel les informations sur le lieu sont affichées. Remplacez vos éléments HTML personnalisés (div, 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 Place Details Compact
Élément Place Details

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

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 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) afin de demander des données spécifiques.
Dans la résolution du rappel, sélectionner manuellement vos éléments HTML et les remplir 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 implique les éléments suivants :

Récupérer votre ID de lieu ou votre objet Place.
Obtenir une référence à l'élément <gmp-place-details-place-request>.
Transmettre 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. S'il existe, obtenez une référence à l'élément Place Details Place Request 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 Element est un élément HTML qui affiche les résultats d'une recherche de lieu dans une liste.

Implémentation actuelle

Vous effectuez une recherche de texte ou une recherche à proximité à l'aide d'une requête HTTP ou 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.

Migrer 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 (div, spans pour le nom, l'adresse, etc.) par l'élément HTML de l'élément Place Search.

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 <gmp-place-search> composant. 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 de texte.
<gmp-place-nearby-search-request> pour une recherche à proximité.

Pour définir l'affichage des résultats, vous pouvez utiliser le <gmp-place-all-content> raccourci 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 recherche à proximité

<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'une 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'une locationRestriction valide a été fournie.

Implémenter l'élément Basic Place Autocomplete

Pour les développeurs qui ont besoin d'une expérience de recherche sans l'interface utilisateur 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 l'affichage des résultats dans votre interface utilisateur personnalisée. La seule responsabilité de l'élément Autocomplete est 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 lui-même et ne fournit aucune autre information accessible de manière programmatique.

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 saisit du texte et affiche les résultats.
Utiliser l'ID de lieu du lieu sélectionné par l'utilisateur pour obtenir plus d'informations, par exemple à l'aide de l'API Place Details.
Afficher les informations sur le lieu sélectionné.

Migrer 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 du composant Web pour initialiser un élément Basic Place Autocomplete 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 obtient une référence à l'élément Basic Place Autocomplete et écoute 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 la liste déroulante Autocomplete, 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 informations sur le lieu sélectionné.

Gérer la personnalisation

Personnalisation de l'élément Place Details

Orientation

L'élément Place Details peut être affiché en orientation horizontale et 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, si vous excluez l'élément de contenu <gmp-place-type> , l'élément Place Details n'affichera plus le type de lieu du lieu sélectionné. Pour obtenir la liste complète des éléments de contenu, consultez la PlaceContentConfigElement documentation de référence.

L'ajout ou la suppression de champs dans l'élément Place Details ne modifie pas le coût de l'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é en orientation horizontale et verticale. Utilisez l'attribut orientation sur <gmp-place-search> pour choisir entre l'orientation verticale et 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 sera affichée, 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 l'élément Basic 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 se déclenche lorsqu'un utilisateur effectue une sélection.
- Sur l'élément Place Search, il se déclenche lorsqu'un utilisateur clique sur un lieu dans la liste de résultats.
- Sur l'élément Basic Place Autocomplete, il se déclenche 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: se déclenche lorsque l'élément et son contenu ont terminé de se charger et de s'afficher.
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 d'élément 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é 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
- Emplacement (latitude et longitude)
- Fenêtre d'affichage
Pour l'élément Basic Place Autocomplete, 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 de manière programmatique.

Pour obtenir des exemples plus détaillés, consultez la documentation individuelle 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, les tests sont essentiels pour une transition fluide et une expérience utilisateur positive. Vos tests doivent couvrir plusieurs domaines clés, en traitant 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 Place Details, commencez par vérifier que les informations s'affichent correctement pour un large éventail de lieux. Pour effectuer le test, transmettez différents ID de lieu à la .place propriété 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. Soyez particulièrement attentif à 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 affichage 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' <gmp-place-text-search-request> élément 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 locationRestriction et includedTypes propriétés sur l'élément <gmp-place-nearby-search-request>. Utilisez différentes tailles de lieux et différents filtres de type.

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

Élément Basic Place Autocomplete

Pour l'élément Basic Place Autocomplete, concentrez-vous 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 la liste déroulante 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.

Gestion des erreurs

Des tests rigoureux de la gestion des erreurs sont essentiels pour 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 interface utilisateur défectueuse ou déroutante.

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

Migrer 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

Migrer vers l'élément Place Search

Modifier la structure HTML

Exemple de recherche à proximité

Exemple de recherche de texte

Adapter la logique JavaScript

Implémenter l'élément Basic Place Autocomplete

Implémentation actuelle

Migrer vers l'élément Place Autocomplete

Modifier la structure HTML

Adapter la logique JavaScript

Gérer la personnalisation

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 l'élément Basic 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 d'élément de manière programmatique

Tests et amélioration

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