Przedstawiamy element HTML <geolocation>

Mari Viana

Minh Le

Thomas Steiner

Opublikowano: 13 stycznia 2026 r.

Od Chrome 144 możesz używać nowego <geolocation> elementu HTML. Ten element stanowi znaczącą zmianę w sposobie, w jaki witryny proszą o dane o lokalizacji użytkownika. Odchodzi się od wyświetlania promptów z prośbą o pozwolenie wywoływanych przez skrypt na rzecz deklaratywnego działania zorientowanego na użytkownika. Zmniejsza to ilość powtarzalnego kodu wymaganego do obsługi stanów uprawnień i błędów oraz zapewnia silniejszy sygnał intencji użytkownika, co pomaga uniknąć interwencji przeglądarki (takich jak ciche blokowanie).

Wprowadzenie tej funkcji jest wynikiem szeroko zakrojonych testów w rzeczywistych warunkach i rygorystycznych dyskusji ze społecznością zajmującą się standardami internetowymi. Aby zrozumieć przydatność tego elementu, należy przeanalizować historię jego rozwoju i dane, które wpłynęły na jego projekt.

Od ogólnego elementu <permission> do konkretnego elementu <geolocation>

Element <geolocation> to najnowsza ewolucja inicjatywy Page-Embedded Permission Control, w której początkowo proponowano ogólny <permission> element z atrybutem type (zobacz oryginalny opis). Wartość atrybutu type (np. "geolocation") określałaby typ żądanego uprawnienia. Na przykład pierwotna oferta pakietowa obejmowała wartości takie jak aparat, mikrofon i geolokalizacja.

Weryfikacja koncepcji

Od Chrome 126 do 143 przeprowadziliśmy test origin ogólnego elementu <permission>. Celem tego testu było sprawdzenie hipotezy, że dedykowany, przycisk w kontekście zwiększy zaufanie użytkowników i ułatwi im podejmowanie decyzji.

Wyniki tego testu origin potwierdziły tę podstawową koncepcję:

• Zoom odnotował spadek o 46,9% liczby błędów przechwytywania obrazu z kamery lub dźwięku z mikrofonu (takich jak blokady na poziomie systemu) dzięki użyciu elementu, który prowadzi użytkowników przez proces odzyskiwania.
• Immobiliare.it odnotował wzrost o 20% liczby udanych przepływów geolokalizacji.
• ZapImóveis zaobserwował 54,4% wskaźnik sukcesu w przypadku użytkowników, którzy po wyświetleniu elementu wracali do stanu „wcześniej zablokowany”.

Zmiana definicji projektu

Chociaż koncepcja okazała się skuteczna, implementacja wymagała dopracowania. Opinie dostawców przeglądarek, w tym Apple (Safari/WebKit) i Mozilli (Firefox), wskazywały że element "uniwersalny" wprowadza znaczną złożoność w zakresie unikalnych zachowań funkcji.

W związku z tym przeszliśmy od ogólnej kontroli uprawnień do elementów ukierunkowanych na konkretne funkcje, (zobacz WICG dyskusję). Element <geolocation> jest pierwszym z tych specjalistycznych elementów sterujących, który został wprowadzony. Następnie opracowujemy też dedykowany <usermedia> element (do uzyskiwania dostępu do kamery i mikrofonu), który ma własny oddzielny test origin.

W przeciwieństwie do pierwotnej propozycji, która koncentrowała się na zarządzaniu stanem uprawnień (czyli zezwalaniu lub odmawianiu), te nowe elementy działają jako pośrednicy danych, skutecznie zastępując konieczność bezpośredniego wywoływania interfejsów JavaScript API w większości przypadków użycia.

Dlaczego warto używać elementu <geolocation>?

Obecnie przepływy geolokalizacji opierają się na interfejsie Geolocation API, który wywołuje prompty z prośbą o pozwolenie, które mogą przeszkadzać użytkownikom, jeśli są wywoływane poza kontekstem lub nawet podczas wczytywania strony. Co najważniejsze, poleganie na tych imperatywnych promptach staje się coraz mniej opłacalne ze względu na interwencje przeglądarki. Na przykład Chrome aktywnie blokuje prośby o pozwolenie jeśli użytkownik odrzuci prompt 3 razy, wymuszając tymczasowe ciche blokowanie które początkowo trwa tydzień. Oznacza to, że starszy kod próbujący wywołać prompt może się nie powieść, co spowoduje, że użytkownik będzie miał problemy z korzystaniem z funkcji i nie będzie miał jasnego sposobu na jej włączenie. Ponadto standardowe prompty często nie mają kontekstu. Jeśli prompt pojawi się nieoczekiwanie, użytkownicy mogą go odruchowo lub przypadkowo zablokować, nie wiedząc, że ta decyzja spowoduje trwałe zablokowanie, które trudno cofnąć. Ta luka w kontekście, a nie sama funkcja, jest główną przyczyną wysokiego odsetka odmów.

Element <geolocation> rozwiązuje problem luki w kontekście, zapewniając, że prośby są inicjowane wyłącznie przez użytkownika. Ten model ma 3 główne zalety:

• Jasna intencja i czas: klikając przycisk Użyj lokalizacji , użytkownik wyraźnie sygnalizuje, że chce użyć swojej lokalizacji w danym momencie. Sygnalizuje to, że rozumie wartość i aktywnie chce używać lokalizacji, co przekształca potencjalną blokadę w udaną interakcję.
• Uproszczone odzyskiwanie: jeśli użytkownik wcześniej zablokował dostęp do lokalizacji podczas przeglądania witryny (być może przypadkowo lub z powodu braku kontekstu), kliknięcie elementu spowoduje uruchomienie specjalnego procesu odzyskiwania. Pomaga to ponownie włączyć lokalizację w momencie, gdy użytkownik faktycznie chce jej użyć, bez konieczności przechodzenia do ustawień witryny w przeglądarce.
• Automatyczne odświeżanie: jeśli uprawnienie jest już przyznane, kliknięcie elementu działa jak przycisk odświeżania, natychmiast pobierając nowe dane bez ponownego wyświetlania prompta.

Implementacja

Integracja elementu wymaga znacznie mniej kodu boilerplate niż interfejs JavaScript API. Zamiast ręcznie zarządzać wywołaniami zwrotnymi i stanami błędów, deweloperzy mogą dodać tag do strony i nasłuchiwać zdarzenia onlocation.

<geolocation
  onlocation="handleLocation(event)"
  autolocate
  accuracymode="precise">
</geolocation>

function handleLocation(event) {
  // Directly access the GeolocationPosition object on the element
  if (event.target.position) {
    const { latitude, longitude } = event.target.position.coords;
    console.log("Location retrieved:", latitude, longitude);
  } else if (event.target.error) {
    console.error("Error:", event.target.error.message);
  }
}

Kluczowe atrybuty i właściwości

• autolocate: automatycznie próbuje pobrać lokalizację po wczytaniu elementu, ale tylko wtedy, gdy bieżący stan uprawnień na to pozwala (zapobiega nieoczekiwanym promptom).
• accuracymode: akceptuje wartość "precise" lub "approximate", która odpowiada standardowej opcji enableHighAccuracy.
• watch: przełącza zachowanie tak, aby pasowało do watchPosition(), i ciągle wywołuje zdarzenia , gdy użytkownik się porusza.
• position: właściwość tylko do odczytu w elemencie DOM, która po udostępnieniu zwraca obiekt GeolocationPosition.
• error: właściwość tylko do odczytu, która zwraca GeolocationPositionError, jeśli żądanie się nie powiedzie.

Ograniczenia dotyczące stylu

Aby zapewnić zaufanie użytkowników i zapobiec wprowadzającym w błąd wzorcom projektowym, element <geolocation> stosuje określone ograniczenia dotyczące stylu podobne do wcześniejszego <permission> eksperymentu z elementem. Możesz dostosować przycisk do motywu witryny, ale przeglądarka wymusza kilka zabezpieczeń:

• Czytelność: kolory tekstu i tła są sprawdzane pod kątem wystarczającego kontrastu (zwykle co najmniej 3:1), aby prośba o pozwolenie była zawsze czytelna. Ponadto kanał alfa (nieprzezroczystość) musi być ustawiony na 1, aby element nie był wprowadzająco przezroczysty.
• Rozmiar i odstępy: element wymusza minimalne i maksymalne granice szerokości, wysokości i rozmiaru czcionki. Ujemne marginesy lub przesunięcia konturów są wyłączone, aby element nie był wizualnie zasłonięty ani nie nakładał się na inne treści w sposób wprowadzający w błąd.
• Integralność wizualna: efekty zniekształcenia są ograniczone – na przykład transformacja obsługuje tylko tłumaczenia 2D i proporcjonalne skalowanie.
• Pseudoklasy CSS: element obsługuje stylizację opartą na stanie, np. :granted (gdy uprawnienie jest aktywne).

Strategia progresywnego ulepszania

Rozumiemy, że standaryzacja nowych elementów HTML to proces stopniowy. Deweloperzy mogą jednak już dziś używać elementu <geolocation> bez naruszania zgodności z innymi przeglądarkami.

Element został zaprojektowany tak, aby działał w sposób płynny. Przeglądarki, które nie obsługują elementu <geolocation>, będą go traktować jako HTMLUnknownElement. Co ważne, jeśli przeglądarka obsługuje element, nie będzie renderować elementów podrzędnych. Umożliwia to czyste pisanie kodu HTML zarówno w przypadku obsługiwanych, jak i nieobsługiwanych przeglądarek.

Niestandardowy wzorzec rezerwowy

Jeśli chcesz w pełni kontrolować działanie rezerwowe, możesz użyć elementów podrzędnych, takich jak przycisk, który połączysz ze zwykłym interfejsem Geolocation JavaScript API.

<geolocation onlocation="updateMap()">
  <!-- Fallback contents if the element is not supported -->
  <button onclick="navigator.geolocation.getCurrentPosition(updateMap)">
    Use my location
  </button>
</geolocation>

Sprawdź, jak działa to zachowanie, na podstawie prostego przykładu.

Kod polyfill

Możesz też zainstalować kod polyfill z npm, który w sposób przezroczysty i automatyczny zastępuje wszystkie wystąpienia elementu <geolocation> elementem niestandardowym <geo-location> (zwróć uwagę na myślnik) obsługiwanym przez zwykły interfejs Geolocation JavaScript API. Jeśli przeglądarka obsługuje element <geolocation>, kod polyfill po prostu nic nie robi. Zapoznaj się z tą prezentacją kodu polyfill, która pokazuje jego działanie. Kod źródłowy znajdziesz na GitHubie.

if (!('HTMLGeolocationElement' in window)) {
  await import('https://unpkg.com/geolocation-element-polyfill/index.js');
}

<geolocation onlocation="updateMap()"></geolocation>

Wykrywanie funkcji

W przypadku bardziej złożonej logiki możesz programowo wykrywać obsługę za pomocą interfejsu:

if ('HTMLGeolocationElement' in window) {
  // Use modern <geolocation> element logic
} else {
  // Fallback to legacy navigator.geolocation API
}

Podsumowanie

Cieszymy się, że deweloperzy będą mogli implementować wydajniejsze scenariusze ponawiania lokalizacji za pomocą nowego elementu HTML <geolocation>. Stanowi on przejście na elementy ukierunkowane na konkretne funkcje, które są dostosowane do sposobu, w jaki użytkownicy korzystają obecnie z internetu.

W przypadku innych zastosowań uprawnień od Chrome 144 możesz dołączyć do testu origin elementu HTML <usermedia>, który zapewnia te same ergonomiczne korzyści w przypadku kamery i mikrofonu.

Powiązane artykuły

• Element <geolocation> w dokumentacji stanu platformy Chrome
• Opis elementu HTML Geolocation
• Strona demonstracyjna
• Stanowisko Mozilli w sprawie standardów
• Stanowisko WebKit w sprawie standardów

Podziękowania

Ten dokument został sprawdzony przez Andy'ego Paicu, Gilberto Cocchi i Rachel Andrew.