推出 <geolocation> HTML 元素

Mari Viana

Minh Le

Thomas Steiner

發布日期：2026 年 1 月 13 日

從 Chrome 144 開始，您可以使用新的 <geolocation> HTML 元素。這項元素代表網站要求使用者位置資料的方式出現重大轉變，從指令碼觸發的權限提示，轉向以使用者動作為導向的宣告式體驗。這項 API 可減少處理權限狀態和錯誤所需的樣板程式碼，並提供更強大的使用者意圖信號，有助於避免瀏覽器介入 (例如靜音封鎖)。

這項功能經過廣泛的實際測試，並與網路標準社群進行嚴謹的討論，如要瞭解這個元素的實用性，請務必查看其開發歷程，以及促成設計的資料。

從一般 <permission> 到特定 <geolocation>

<geolocation> 元素是「網頁內嵌權限控制」計畫的最新演進，最初是建議使用具有 type 屬性的通用 <permission> 元素 (請參閱原始說明)。類型屬性的值 (例如 "geolocation") 會決定要求的權限類型。舉例來說，初始提案包含攝影機、麥克風和地理位置等值。

驗證概念

我們在 Chrome 126 到 143 期間，針對一般 <permission> 元素進行來源試用。 這項試驗的目的是測試假設：專屬的內容相關按鈕可提升使用者信任感，並協助他們做出決定。

這項來源試驗的結果支援驗證這項核心概念：

• Zoom 報告指出，使用這個元素引導使用者完成復原程序後，攝影機或麥克風擷取錯誤 (例如系統層級的封鎖) 減少了 46.9%。
• Immobiliare.it 的地理位置資訊流程成功率提升了 20%。
• ZapImóveis 發現，向使用者顯示元素後，有 54.4% 的使用者成功從「先前遭到封鎖」狀態恢復。

重新定義設計

雖然概念證明可行，但實作方式仍需改進。 瀏覽器供應商 (包括 Apple (Safari/WebKit) 和 Mozilla (Firefox)) 的意見回饋指出，導入「一體適用」的元素會大幅增加獨特功能行為的複雜度。

因此，我們從一般權限控管機制，轉移至針對特定功能設計的元素 (請參閱 WICG 討論)。<geolocation> 元素是首批推出的專用控制項。此外，我們也正在開發專屬的 <usermedia> 元素 (用於攝影機和麥克風存取權)，並提供獨立的原始碼試用。

與原先提案著重於管理權限狀態 (即允許或拒絕) 不同，這些新元素可做為資料中介，有效取代在大多數用途中直接呼叫 JavaScript API 的需求。

為何要使用 <geolocation> 元素？

目前，地理位置資訊流程依賴 Geolocation API，如果不在適當情境下觸發，或甚至在網頁載入時觸發，可能會中斷使用者操作。但由於瀏覽器介入，依賴這些必要提示已變得較不可行。舉例來說，如果使用者已三次關閉提示，Chrome 會主動封鎖權限要求，強制執行暫時的靜音封鎖，一開始為期一週。也就是說，嘗試觸發提示的舊版程式碼可能會無聲無息地失敗，導致使用者體驗中斷，且無法清楚瞭解如何啟用這項功能。此外，標準提示通常缺乏背景資訊。如果系統意外顯示提示，使用者可能會反射性或不小心封鎖提示，但他們不知道這項決定會造成永久封鎖，而且難以撤銷。這個情境落差 (而非功能本身) 是高拒絕率的主要原因。

<geolocation> 元素可確保要求完全由使用者發起，解決情境落差問題。這個模型有三項明顯優勢：

• 明確的意圖和時機：使用者點選「使用位置資訊」按鈕，即明確表示他們想在當下使用位置資訊。這表示他們瞭解位置資訊的價值，並積極想使用這項資訊，將潛在的阻礙轉化為成功的互動。
• 簡化復原程序：如果使用者先前瀏覽網站時封鎖了位置資訊存取權 (可能是意外或缺乏脈絡)，點選元素會觸發專屬的復原流程。這樣一來，使用者就能在實際想使用位置資訊時重新啟用，不必費力地深入瀏覽器的網站設定。
• 自動重新整理：如果已授予權限，點選元素會如同按下重新整理按鈕，立即擷取新資料，不會再次提示。

導入作業

整合元素所需的樣板遠少於 JavaScript API。開發人員可以將代碼加到網頁，並監聽 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);
  }
}

主要屬性和屬性

• autolocate：在元素載入時自動嘗試擷取位置資訊，但前提是目前的權限狀態已允許這麼做 (避免出現非預期的提示)。
• accuracymode：接受 "precise" 或 "approximate" 值，對應標準 enableHighAccuracy 選項。
• watch：將行為切換為符合 watchPosition()，在使用者移動時持續觸發事件。
• position：DOM 元素上的唯讀屬性，會在可用時傳回 GeolocationPosition 物件。
• error：唯讀屬性，如果要求失敗，會傳回 GeolocationPositionError。

樣式限制

為確保使用者信任度並防範欺騙性設計模式，<geolocation> 元素會套用特定樣式限制，與先前的<permission>元素實驗類似。雖然您可以自訂按鈕，使其符合網站的主題，但瀏覽器會強制執行幾項防護措施：

• 可讀性：系統會檢查文字和背景顏色是否具有足夠的對比度 (通常至少為 3:1)，確保權限要求一律可讀。此外，Alpha 通道 (不透明度) 必須設為 1，以免元素呈現誤導性的透明度。
• 大小和間距：元素會強制執行寬度、高度和字型大小的最小和最大界限。系統會停用負邊界或外框偏移，避免元素在視覺上遭到遮蔽，或以欺騙手法與其他內容重疊。
• 視覺完整性：限制扭曲效果，例如變形僅支援 2D 轉換和比例縮放。
• CSS 虛擬類別：這個元素支援以狀態為基礎的樣式，例如：granted (權限處於啟用狀態時)。

漸進增強策略

我們瞭解標準化新 HTML 元素需要一段時間。不過，開發人員現在就能採用 <geolocation> 元素，不必擔心其他瀏覽器的使用者無法相容。

這個元素設計為可優雅降級。不支援 <geolocation> 元素的瀏覽器會將其視為 [HTMLUnknownElement](https://developer.mozilla.org/docs/Web/API/HTMLUnknownElement)。重要事項：如果瀏覽器支援該元素，就不會轉譯子項。 這樣一來，無論瀏覽器是否支援，都能乾淨地編寫 HTML。

自訂備用模式

如要完全控管備用體驗，可以使用子元素 (例如按鈕)，並透過一般 JavaScript Geolocation API 連結。

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

Polyfill

或者，您也可以從 npm 安裝 Polyfill，這個 Polyfill 會自動取代所有 <geolocation>，並以一般 JavaScript Geolocation API 支援的自訂元素 <geo-location> (請注意連字號) 取代。如果瀏覽器支援 <geolocation> 元素，polyfill 就不會執行任何動作。請參閱這項 示範，瞭解 polyfill 的實際運作方式。原始碼位於 GitHub。

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

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

特徵偵測

如要使用更複雜的邏輯，可以透過介面以程式輔助方式偵測支援：

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

總結

我們很期待看到開發人員使用新的 <geolocation> HTML 元素，實作效能更高的位置資訊重試情境。這代表我們將朝向特定功能元素發展，根據使用者目前的實際網路使用方式量身打造。

如要瞭解其他權限用途，自 Chrome 144 起，您可以加入 <usermedia> HTML 元素來源試用，將這些符合人體工學的優點帶入攝影機和麥克風。

相關連結

• Chrome 平台狀態的 <geolocation> 元素
• 地理位置 HTML 元素說明
• 示範頁面
• Mozilla 標準立場
• WebKit 標準位置

特別銘謝

本文由 Andy Paicu、Gilberto Cocchi 和 Rachel Andrew 審查。