HTMLGeolocationElement

Constructeur

HTMLGeolocationElement() Expérimental

Crée une nouvelle instance de l'objet HTMLGeolocationElement. Notez que ce constructeur n'est pas appelé directement, mais via une méthode DOM telle que Document.createElement().

Propriétés d'instance

Hérite également des propriétés de son interface parente, HTMLElement.

autolocate Expérimental

Une valeur booléenne indiquant si le navigateur doit demander immédiatement les données de localisation lorsque l'élément <geolocation> est affiché, à condition que l'autorisation ait été accordée auparavant. Reflète la valeur de l'attribut autolocate de l'élément <geolocation>.

error Lecture seule Expérimental

Un objet GeolocationPositionError représentant les informations d'erreur en cas d'échec de récupération des données.

initialPermissionStatus Lecture seule Expérimental

Une valeur énumérée représentant l'état d'autorisation pour la fonctionnalité de géolocalisation lors du premier chargement de la page.

invalidReason Lecture seule Expérimental

Une valeur énumérée représentant la raison pour laquelle l'élément <geolocation> est invalide (bloqué), le cas échéant.

isValid Lecture seule Expérimental

Une valeur booléenne indiquant si l'élément <geolocation> est valide ou invalide (bloqué).

permissionStatus Lecture seule Expérimental

Une chaîne de caractères représentant l'état actuel d'autorisation pour la fonctionnalité de géolocalisation.

position Lecture seule Expérimental

Un objet GeolocationPosition représentant la position de l'utilisateur·ice en cas de récupération réussie des données de localisation.

watch Expérimental

Une valeur booléenne indiquant si le navigateur doit mettre à jour en continu les données de localisation de l'utilisateur·ice à chaque changement de position de l'appareil, ou ne les récupérer qu'une seule fois. Reflète la valeur de l'attribut watch de l'élément <geolocation>.

Méthodes d'instance

Hérite également des méthodes de son interface parente, HTMLElement.

Évènements

Hérite également des évènements de son interface parente, HTMLElement.

location Expérimental

Déclenché chaque fois que le navigateur reçoit des données de localisation, ou des informations d'erreur lorsque la demande de données de localisation a échoué.

promptaction Expérimental

Déclenché chaque fois que l'utilisateur·ice active l'élément <geolocation> et sélectionne une option dans la boîte de dialogue qui s'affiche, soit pour accorder soit pour refuser l'autorisation de géolocalisation.

promptdismiss Expérimental

Déclenché chaque fois que l'utilisateur·ice active l'élément <geolocation> et ferme la boîte de dialogue qui s'affiche, en appuyant sur le bouton « fermer » ou la touche Échap.

validationstatuschange Expérimental

Déclenché chaque fois que la valeur isValid de l'élément <geolocation> change.

Description

L'interface HTMLGeolocationElement représente l'élément HTML <geolocation>, qui crée un contrôle interactif permettant à l'utilisateur·ice de partager ses données de localisation avec la page.

Lorsque l'utilisateur·ice active le contrôle, une boîte de dialogue s'affiche pour demander l'autorisation de partager ses données de localisation. Si l'autorisation est accordée, le navigateur tente de récupérer les données de localisation de l'utilisateur·ice en utilisant l'API de géolocalisation en arrière-plan.

Par défaut, le navigateur demande les données de localisation une seule fois, comme si la méthode Geolocation.getCurrentPosition() était appelée. Cependant, si l'attribut watch est défini sur true, le navigateur met à jour les données à chaque changement de position de l'appareil, comme si Geolocation.watchPosition() était appelée.

Lorsque la demande de données aboutit, l'évènement location est déclenché, ce qui permet de réagir, par exemple en récupérant les données et en affichant la localisation sur une carte.

• Si les données de localisation sont récupérées avec succès, elles sont disponibles dans la propriété HTMLGeolocationElement.position, qui contient un objet GeolocationPosition.
• Si la récupération des données échoue, les informations d'erreur sont disponibles dans la propriété HTMLGeolocationElement.error, qui contient un objet GeolocationPositionError.

Les évènements promptaction et promptdismiss permettent de réagir aux interactions de l'utilisateur·ice avec la boîte de dialogue <geolocation>, par exemple pour lui demander de faire un autre choix si l'accès aux données a été refusé.

Lorsqu'un bloqueur est actif sur un élément <geolocation>, il est empêché de fonctionner (invalide), temporairement ou définitivement selon la raison. Vous pouvez vérifier s'il est invalide en consultant la propriété HTMLGeolocationElement.isValid. Vous pouvez aussi obtenir la raison de l'invalidité via la propriété HTMLGeolocationElement.invalidReason — voir cette page pour la liste complète des raisons possibles.

Exemples

Exemple simple

Pour des exemples minimaux utilisant l'élément <geolocation> et l'objet associé HTMLGeolocationElement pour retourner des données de localisation, consultez notre exemple simple ^(angl.) (code source ^(angl.)) et exemple simple avec suivi ^(angl.) (code source ^(angl.)).

Voir la page de référence <geolocation> pour un guide détaillé.

Exemple de carte intégrée

Cet exemple utilise l'élément <geolocation> pour récupérer votre position actuelle, qui est affichée sur une carte rendue avec Leaflet JS ^(angl.). L'exemple utilise également un élément <button> classique pour récupérer les données de localisation dans les navigateurs qui ne prennent pas en charge <geolocation>.

HTML

Nous incluons un élément <geolocation> avec l'attribut autolocate afin que le navigateur tente de récupérer automatiquement les données de localisation, à condition que l'autorisation ait été accordée auparavant. À l'intérieur de l'élément <geolocation>, nous imbriquons un bouton de secours <button>, qui sera affiché dans les navigateurs ne prenant pas en charge <geolocation> pour permettre la demande de localisation.

<geolocation autolocate>
  <button id="fallback">Use location</button>
</geolocation>

Ensuite, nous incluons un élément HTML <p> pour afficher les messages d'état et les erreurs.

<p id="status">Status:</p>

Enfin, nous incluons un élément HTML <div> pour afficher la carte.

<div id="map"></div>

JavaScript

Dans notre script, nous commençons par récupérer une référence vers l'élément <p> d'état :

const statusElem = document.querySelector("#status");

Ensuite, nous détectons si l'élément <geolocation> est pris en charge en testant typeof HTMLGeolocationElement === "function" :

if (typeof HTMLGeolocationElement === "function") {
  // <geolocation> is supported
} else {
  // <geolocation> is not supported; use fallback button
}

Si <geolocation> est pris en charge, le bloc if s'exécute. Il commence par récupérer une référence vers l'élément <geolocation> :

const geo = document.querySelector("geolocation");

Ensuite, nous ajoutons un écouteur d'évènement location à l'objet HTMLGeolocationElement obtenu, pour détecter quand la demande de localisation est retournée. Si les données sont retournées avec succès, nous y accédons via la propriété HTMLGeolocationElement.position, et récupérons les valeurs de latitude et longitude. Nous les affichons dans la console, puis les traçons sur la carte en les passant à la fonction drawMap() (que nous définirons plus tard) avec une référence vers l'objet HTMLGeolocationElement. Si la demande échoue, nous accédons à l'erreur via la propriété HTMLGeolocationElement.error et affichons le message d'erreur dans la console.

geo.addEventListener("location", () => {
  if (geo.position) {
    console.log(
      `${geo.position.coords.latitude},${geo.position.coords.longitude}`,
    );
    drawMap(geo.position.coords.latitude, geo.position.coords.longitude, geo);
  } else if (geo.error) {
    console.log(geo.error.message);
  }
});

Ensuite, nous ajoutons les écouteurs d'évènements promptdismiss et promptaction à l'objet HTMLGeolocationElement obtenu. Ceux-ci permettent d'exécuter des fonctions en réponse à la fermeture de la boîte de dialogue <geolocation> ou au choix d'une option dans la boîte de dialogue.

geo.addEventListener("promptdismiss", notifyUserRetrySelection);
geo.addEventListener("promptaction", notifyUserGrantPermission);

Enfin, pour le bloc if, nous définissons les fonctions notifyUserRetrySelection() et notifyUserGrantPermission() référencées dans les deux écouteurs précédents. La première affiche un message dans le paragraphe d'état pour demander à l'utilisateur·ice d'appuyer à nouveau sur le bouton et d'autoriser la localisation, car dans ce cas, il faudra toujours réessayer. La seconde utilise la propriété HTMLGeolocationElement.permissionStatus pour vérifier si le statut d'autorisation est denied ou prompt et, le cas échéant, nous demandons à l'utilisateur·ice d'appuyer à nouveau sur le bouton et d'autoriser la localisation. Il n'est pas nécessaire de le demander si l'autorisation a déjà été accordée.

function notifyUserRetrySelection() {
  statusElem.textContent =
    'Veuillez appuyer à nouveau sur le bouton "Utiliser la localisation" et autoriser la localisation pour ce site.';
}

function notifyUserGrantPermission() {
  if (geo.permissionStatus === "denied" || geo.permissionStatus === "prompt") {
    statusElem.textContent =
      'Veuillez appuyer à nouveau sur le bouton "Utiliser la localisation" et autoriser la localisation pour ce site.';
  }
}

Si <geolocation> n'est pas pris en charge, le bloc else s'exécute. Il commence par récupérer une référence vers l'élément <button> de secours :

const fallback = document.querySelector("#fallback");

Ensuite, nous ajoutons un gestionnaire d'évènement click à l'objet HTMLButtonElement obtenu. À l'intérieur, nous utilisons un appel à Geolocation.getCurrentPosition() pour émuler les cas de succès et d'échec du chemin de code HTMLGeolocationElement. Le résultat est le même — nous traçons les données de localisation sur la carte en les passant à la fonction drawMap() (avec une référence vers l'objet HTMLButtonElement), ou affichons le message d'erreur dans le paragraphe d'état.

fallback.addEventListener("click", () => {
  navigator.geolocation.getCurrentPosition(
    (position) => {
      drawMap(position.coords.latitude, position.coords.longitude, fallback);
    },
    (error) => {
      statusElem.textContent += `${error.message}, `;
    },
  );
});

La dernière étape consiste à définir la fonction drawMap(), qui prend les données de latitude et longitude en arguments, ainsi qu'une référence vers le bouton qui a déclenché la commande. Le corps de la fonction utilise le code de Leaflet JS ^(angl.) (voir le Guide de démarrage rapide ^(angl.)) pour afficher la position de l'utilisateur·ice sur la carte, affiche un message de succès dans le paragraphe d'état, et masque le bouton. La dernière étape est une simplification pour éviter que le code ne produise une erreur si l'utilisateur·ice appuie à nouveau sur le bouton après le succès.

function drawMap(lat, long, btn) {
  const map = L.map("map").setView([lat, long], 13);
  L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", {
    maxZoom: 19,
    attribution:
      '&copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>',
  }).addTo(map);
  const marker = L.marker([lat, long]).addTo(map);

  statusElem.textContent = "Carte tracée avec succès.";
  btn.style.display = "none";
}

Résultat

Voir ce code en direct ^(angl.) (code source ^(angl.)). Essayez d'afficher les démos dans un navigateur pris en charge et un navigateur non pris en charge si possible, et notez la différence dans le flux de la boîte de dialogue d'autorisation lorsque vous autorisez l'utilisation de geolocation.

Essayez également ce qui suit :

• Après avoir autorisé la permission geolocation et vu la carte s'afficher, essayez de révoquer cette autorisation en utilisant les contrôles du navigateur disponibles, puis actualisez la page pour réinitialiser l'exemple.
• Essayez maintenant de refuser la permission d'utiliser geolocation ou de fermer la boîte de dialogue d'autorisation, et notez comment les écouteurs d'évènements promptdismiss et promptaction que nous avons configurés plus tôt affichent un message dans le paragraphe d'état pour aider l'utilisateur·ice à utiliser la page.

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'élément HTML <geolocation>
• La politique de permissions geolocation
• L'API Geolocation
• L'API Permissions
• Présentation de l'élément HTML <geolocation> sur developer.chrome.com (2026)