Charger l'API Maps JavaScript

Ce guide vous explique comment charger l'API Maps JavaScript. Vous pouvez le faire de trois manières :

Utiliser l'importation dynamique de bibliothèques

L'importation dynamique de bibliothèques permet de charger des bibliothèques au moment de l'exécution. Cela vous permet de demander les bibliothèques nécessaires au moment où vous en avez besoin, plutôt que toutes en même temps au moment du chargement. Il protège également votre page contre le chargement de l'API Maps JavaScript à plusieurs reprises.

Chargez l'API Maps JavaScript en ajoutant le chargeur d'amorçage intégré au code de votre application, comme indiqué dans l'extrait suivant :

<script>
  (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: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

Vous pouvez également ajouter le code du chargeur d'amorçage directement à votre code JavaScript.

Pour charger des bibliothèques lors de l'exécution, utilisez l'opérateur await pour appeler importLibrary() à partir d'une fonction async. Déclarer des variables pour les classes nécessaires vous permet d'éviter d'utiliser un chemin qualifié (par exemple, google.maps.Map), comme illustré dans l'exemple de code suivant :

let map;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.js

Votre fonction peut également charger des bibliothèques sans déclarer de variable pour les classes nécessaires, ce qui est particulièrement utile si vous avez ajouté une carte à l'aide de l'élément gmp-map. Sans la variable, vous devez utiliser des chemins qualifiés, par exemple google.maps.Map :

let map;
let center =  { lat: -34.397, lng: 150.644 };

async function initMap() {
  await google.maps.importLibrary("maps");
  await google.maps.importLibrary("marker");

  map = new google.maps.Map(document.getElementById("map"), {
    center,
    zoom: 8,
    mapId: "DEMO_MAP_ID",
  });

  addMarker();
}

async function addMarker() {
  const marker = new google.maps.marker.AdvancedMarkerElement({
    map,
    position: center,
  });
}

initMap();

Vous pouvez également charger les bibliothèques directement dans le code HTML, comme indiqué ci-dessous :

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

Découvrez comment migrer vers l'API Dynamic Library Loading.

Paramètres obligatoires

  • key : votre clé API. L'API Maps JavaScript ne se charge pas tant qu'aucune clé API valide n'est spécifiée.

Paramètres facultatifs

  • v : version de l'API Maps JavaScript à charger.

  • libraries : tableau des bibliothèques supplémentaires de l'API Maps JavaScript à charger. Généralement, il n'est pas recommandé de spécifier un ensemble défini de bibliothèques, mais cette option est disponible pour les développeurs qui souhaitent affiner le comportement de mise en cache sur leur site Web.

  • language : langue à utiliser. Ce paramètre affecte le nom des commandes, les avis de droits d'auteur, les itinéraires, les libellés de commandes et les réponses aux demandes de service. Consultez la liste des langues acceptées.

  • region : code régional à utiliser. Ce paramètre modifie le comportement de l'API en fonction d'un pays ou d'un territoire donné.

  • authReferrerPolicy : les clients Maps JS peuvent configurer des restrictions d'URL de provenance HTTP dans la console Cloud afin de limiter les URL autorisées à utiliser une clé API donnée. Par défaut, ces restrictions peuvent être configurées pour n'autoriser que certains chemins à utiliser une clé API. Si une URL du même domaine ou de la même origine peut utiliser la clé API, vous pouvez définir authReferrerPolicy: "origin" pour limiter la quantité de données envoyées lors de l'autorisation des requêtes à partir de l'API Maps JavaScript. Lorsque ce paramètre est spécifié et que des restrictions d'URL de provenance HTTP sont activées dans la console Cloud, l'API Maps JavaScript ne peut être chargée que si une restriction d'URL de provenance HTTP correspond au domaine du site Web actuel sans chemin spécifié.

  • mapIds : tableau d'ID de cartes. Entraîne le préchargement de la configuration pour les ID de carte spécifiés. Il n'est pas nécessaire de spécifier des ID de carte ici pour les utiliser, mais cette option est disponible pour les développeurs qui souhaitent affiner les performances réseau.

  • channel : consultez Suivi de l'utilisation par chaîne.

  • solutionChannel : pour vous aider à démarrer rapidement, Google Maps Platform propose de nombreux types d'exemples de code. Pour suivre l'adoption de nos exemples de code plus complexes et améliorer la qualité de la solution, Google inclut le paramètre de requête solutionChannel des appels d'API dans les exemples.

Utiliser le tag de chargement direct du script

Cette section explique comment utiliser la balise de chargement de script direct. Étant donné que le script direct charge les bibliothèques lorsque la carte se charge, il peut simplifier les cartes créées à l'aide d'un élément gmp-map en supprimant la nécessité de demander explicitement des bibliothèques au moment de l'exécution. Étant donné que la balise de chargement direct de script charge toutes les bibliothèques demandées en même temps lorsque le script est chargé, les performances peuvent être affectées pour certaines applications. N'incluez la balise de chargement de script en direct qu'une seule fois par chargement de page.

Ajouter un tag de script

Pour charger l'API Maps JavaScript intégrée dans un fichier HTML, ajoutez un tag script comme indiqué ci-dessous.

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

Paramètres d'URL de chargement direct de script

Cette section présente tous les paramètres que vous pouvez spécifier dans la chaîne de requête de l'URL de chargement de script lorsque l'API Maps JavaScript est chargée. Certains paramètres sont obligatoires, d'autres sont facultatifs. Comme c'est la norme pour les URL, les différents paramètres sont séparés par une esperluette (&).

L'exemple d'URL suivant comporte des espaces réservés pour tous les paramètres possibles :

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&loading=async
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&auth_referrer_policy="AUTH_REFERRER_POLICY"
&map_ids="MAP_IDS"
&channel="CHANNEL"
&solution_channel="SOLUTION_IDENTIFIER"

Dans l'exemple de tag de script suivant, l'URL charge l'API Maps JavaScript :

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

Paramètres obligatoires (direct)

Les paramètres suivants sont requis pour charger l'API Maps JavaScript.

  • key : votre clé API. L'API Maps JavaScript ne se charge pas tant qu'aucune clé API valide n'est spécifiée.

Paramètres facultatifs (directs)

Utilisez ces paramètres pour demander une version spécifique de l'API Maps JavaScript, charger des bibliothèques supplémentaires, localiser votre carte ou spécifier la règle de vérification de l'URL de provenance HTTP.

  • loading : stratégie de chargement du code que l'API Maps JavaScript peut utiliser. Définissez la valeur sur async pour indiquer que l'API Maps JavaScript n'a pas été chargée de manière synchrone et qu'aucun code JavaScript n'est déclenché par l'événement load du script. Nous vous recommandons vivement de définir cette valeur sur async chaque fois que possible pour améliorer les performances. (Utilisez plutôt le paramètre callback pour effectuer des actions lorsque l'API Maps JavaScript est disponible.) Disponible à partir de la version 3.55.

  • callback : nom d'une fonction globale à appeler une fois que l'API Maps JavaScript a été entièrement chargée.

  • v : version de l'API Maps JavaScript à utiliser.

  • libraries : liste des bibliothèques supplémentaires de l'API Maps JavaScript à charger, séparées par une virgule.

  • language : langue à utiliser. Ce paramètre affecte le nom des commandes, les avis de droits d'auteur, les itinéraires et les libellés de commandes, ainsi que les réponses aux demandes de service. Consultez la liste des langues disponibles.

  • region : code régional à utiliser. Ce paramètre modifie le comportement de l'API en fonction d'un pays ou d'un territoire donné.

  • auth_referrer_policy : les clients peuvent configurer des restrictions d'URL de provenance HTTP dans la console Cloud afin de limiter les URL autorisées à utiliser une clé API donnée. Par défaut, ces restrictions peuvent être configurées pour n'autoriser que certains chemins à utiliser une clé API. Si une URL du même domaine ou de la même origine peut utiliser la clé API, vous pouvez définir auth_referrer_policy=origin pour limiter la quantité de données envoyées lors de l'autorisation des requêtes à partir de l'API Maps JavaScript. Cette fonctionnalité est disponible à partir de la version 3.46. Lorsque ce paramètre est spécifié et que des restrictions d'URL de provenance HTTP sont activées dans la console Cloud, l'API Maps JavaScript ne peut être chargée que si une restriction d'URL de provenance HTTP correspond au domaine du site Web actuel sans chemin spécifié.

  • mapIds : liste d'ID de cartes séparés par une virgule. Entraîne le préchargement de la configuration pour les ID de carte spécifiés. Il n'est pas obligatoire de spécifier des ID de carte ici pour les utiliser, mais cette option est disponible pour les développeurs qui souhaitent affiner les performances réseau.

  • channel : consultez Suivi de l'utilisation par canal.

  • solution_channel : pour vous aider à démarrer rapidement, Google Maps Platform propose de nombreux types d'exemples de code. Pour suivre l'adoption de nos exemples de code plus complexes et améliorer la qualité de la solution, Google inclut le paramètre de requête solution_channel des appels d'API dans les exemples.

Utiliser le package js-api-loader NPM

Le package @googlemaps/js-api-loader est disponible pour le chargement à l'aide du gestionnaire de paquets NPM. Installez-le à l'aide de la commande suivante :

npm install @googlemaps/js-api-loader

Ce package peut être importé dans l'application avec :

import { Loader } from "@googlemaps/js-api-loader"

Le chargeur expose une promesse et une interface de rappel. Voici un exemple d'utilisation de la méthode load() de promesse par défaut.

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

index.js

Voir un exemple avec js-api-loader

L'exemple suivant montre comment utiliser loader.importLibrary() pour charger des bibliothèques :

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader
  .importLibrary('maps')
  .then(({Map}) => {
    new Map(document.getElementById("map"), mapOptions);
  })
  .catch((e) => {
    // do something
});

Migrer vers l'API Dynamic Library Import

Cette section décrit la procédure à suivre pour migrer votre intégration afin d'utiliser l'API Dynamic Library Import.

Étapes de migration

Tout d'abord, remplacez le tag de chargement de script direct par le tag d'amorçage de chargement intégré.

Avant

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

Après

<script>
  (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: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

Ensuite, modifiez le code de votre application :

  • Modifiez la fonction initMap() pour qu'elle soit asynchrone.
  • Appelez importLibrary() pour charger les bibliothèques dont vous avez besoin et y accéder.

Avant

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;

Après

let map;
// initMap is now async
async function initMap() {
    // Request libraries when needed, not in the script tag.
    const { Map } = await google.maps.importLibrary("maps");
    // Short namespaces can be used.
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}

initMap();