Premiers pas

Suivez ces étapes pour ajouter la bibliothèque de contexte local à votre projet, puis initialiser et configurer la vue de carte de contexte local.

Activer les API et les SDK requis

Pour utiliser la bibliothèque de contexte local, vous devez activer les API Maps JavaScript et Places. Pour ce faire, suivez ces instructions pour Activer un ou plusieurs SDK ou API. Notez que les deux API doivent être activées dans le même projet dans la console Google Cloud.

Charger la bibliothèque de contexte local

Pour charger la bibliothèque de contexte local, chargez l'API Maps JavaScript normalement, en incluant les paramètres suivants :

  • libraries=localContext charge la bibliothèque de contexte local.
  • v=beta est nécessaire pour utiliser cette version.
  • key contient votre clé API.
  • callback exécute la fonction initMap().

L'exemple suivant illustre un tag de script avec toutes les options mentionnées ci-dessus :

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=localContext&v=beta&callback=initMap">
</script>

Créer une vue de carte de contexte local

Pour ajouter la bibliothèque de contexte local à une page Web, créez d'abord une instance LocalContextMapView, puis définissez les propriétés souhaitées :

  • element : élément div où la carte doit s'afficher (dans ce cas, elle est nommée "map").
  • placeTypePreferences : types de lieux que la bibliothèque de contexte local doit renvoyer (10 au maximum).
  • maxPlaceCount : nombre maximal de lieux à afficher (entre 1 et 24).
  • locationRestriction (facultatif) : limite la recherche de lieux à un emplacement donné. Par défaut, il s'agit de la fenêtre d'affichage de la carte.

Une fois que vous disposez d'une instance LocalContextMapView, vous pouvez définir les options de carte sur l'instance Map interne. La carte contenue dans une LocalContextMapView accepte les mêmes options de carte qu'une carte API Maps JavaScript standard. L'exemple suivant montre comment créer une instance LocalContextMapView et définir quelques options sur la Map interne :

TypeScript

let map: google.maps.Map;

function initMap() {
  const localContextMapView = new google.maps.localContext.LocalContextMapView({
    element: document.getElementById("map"),
    placeTypePreferences: [
      { type: "restaurant" },
      { type: "tourist_attraction" },
    ],
    maxPlaceCount: 12,
  });

  map = localContextMapView.map!;

  map.setOptions({
    center: { lat: 51.507307, lng: -0.08114 },
    zoom: 14,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

let map;

function initMap() {
  const localContextMapView = new google.maps.localContext.LocalContextMapView({
    element: document.getElementById("map"),
    placeTypePreferences: [
      { type: "restaurant" },
      { type: "tourist_attraction" },
    ],
    maxPlaceCount: 12,
  });

  map = localContextMapView.map;
  map.setOptions({
    center: { lat: 51.507307, lng: -0.08114 },
    zoom: 14,
  });
}

window.initMap = initMap;

Reporter le chargement des données de contexte local

Vous pouvez reporter le chargement des données de contexte local lors de l'initialisation en définissant l'option LocalContextMapView maxPlaceCount sur 0. Cela est utile lorsque vous souhaitez attendre que les utilisateurs soient prêts à voir les données. Lorsque vous êtes prêt à charger des données de contexte local, définissez maxPlaceCount sur une valeur égale ou supérieure à 1. L'exemple suivant initialise la carte sans charger les données de contexte local, puis définit maxPlaceCount pour charger les données :

// Initialize without Local Context data.
const localContextMapView = new google.maps.localContext.LocalContextMapView({
    element: document.querySelector('#map'),
    placeTypePreferences: ['restaurant'],
    maxPlaceCount: 0, // Avoids an automatic call to load places during initialization.
  });

//...

// Show places now.
localContextMapView.maxPlaceCount = 12;

Activer/Désactiver l'affichage de l'interface utilisateur de contexte local

Vous pouvez activer/désactiver les éléments de l'interface utilisateur de Contexte local en définissant l'option LocalContextMapView maxPlaceCount sur 0. Pour afficher à nouveau l'interface utilisateur de contexte local, définissez maxPlaceCount sur une valeur égale ou supérieure à 1.

Définir des dimensions de carte minimales

La bibliothèque de contexte local modifie l'affichage de manière responsive en fonction de la taille de rendu de LocalContextMapView. Les dimensions minimales acceptées pour LocalContextMapView sont :

  • 300 x 480 pixels (portrait)
  • 480 x 380 pixels (paysage)

Lorsque l'élément conteneur pour LocalContextMapView passe en dessous des dimensions minimales acceptées, les éléments de la bibliothèque de contexte local, y compris le sélecteur de lieu et les points d'intérêt, ne sont pas visibles. Le niveau de zoom du navigateur a une incidence sur les dimensions minimales acceptées. Par exemple, si le zoom de la fenêtre est de 200 %, les dimensions minimales acceptées sont 600 x 960 (portrait) et 960 x 760 (paysage).

Recommandations CSS

Les classes CSS du DOM de la bibliothèque de contexte local ne font pas partie de l'API publique. Vous ne pouvez donc pas styliser, modifier ou sélectionner des éléments dans ce DOM. Nous vous recommandons vivement de suivre les consignes suivantes pour éviter les conflits de styles DOM et pour vous assurer que la vue de la bibliothèque de contexte local s'affiche correctement :

  • N'utilisez pas les classes CSS de la bibliothèque locale, car elles peuvent être modifiées sans préavis.
  • Ne stylisez et ne modifiez pas les éléments du DOM de la bibliothèque de contexte local, et ne les sélectionnez pas.

Si vous utilisez un framework CSS qui apporte de telles modifications, vous pourrez peut-être contourner les conflits liés aux styles.

Par exemple, si vous souhaitez remplacer la page box-sizing par border-box :

  • Utilisez des forçages box-sizing qui définissent l'élément <html> sur border-box.
  • Utilisez box-sizing: initial pour l'élément qui contient la vue de carte de la bibliothèque de contexte local.
  • Utilisez box-sizing: inherit pour tous les autres éléments.

Cela permet de s'assurer que le DOM de la bibliothèque de contexte local a rétabli la valeur par défaut standard de box-sizing avec un sélecteur de faible précision.

Le code se présente comme suit :

html {
  box-sizing: border-box;
}
*, *::before, *::after {
  box-sizing: inherit;
}

.container-for-google-maps {
  box-sizing: initial;
}