<geolocation> HTML 元素简介

Mari Viana
Mari Viana
LinkedIn
Minh Le
Minh Le
LinkedIn
Thomas Steiner

发布时间：2026 年 1 月 13 日

从 Chrome 144 开始，您可以使用新的 <geolocation> HTML 元素。此元素代表着网站请求用户位置数据的方式发生了重大转变，即从脚本触发的权限提示转向声明式、以用户操作为导向的体验。它减少了处理权限状态和错误所需的样板代码，并提供了更强的用户意图信号，有助于避免浏览器干预（例如静默阻止）。

此次发布是经过广泛的实际测试并与 Web 标准社区进行严谨讨论后得出的结果。为了了解此元素的实用性，务必要了解其开发历史以及推动其设计的数据。

从通用 <permission> 到特定 <geolocation>

<geolocation> 元素是页面嵌入式权限控制计划的最新发展，该计划最初提出的是一个带有 type 属性的通用 <permission> 元素（请参阅原始说明）。type 属性的值（例如 "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 的需求。

下表介绍了地理定位 JavaScript API、<permission> 元素和新的 <geolocation> 元素之间的区别。
功能 Geolocation JS API HTML 元素 HTML 元素
权限提示的触发事件 强制性脚本执行（getCurrentPosition） 用户点击浏览器控制的 元素 用户点击浏览器控制的 元素
浏览器角色 根据状态决定提示 充当权限中介 充当数据中介
网站责任 手动调用 JavaScript API、处理回调和管理权限错误 在授予权限后实现 geolocation API 监听 location 事件
核心目标 基本位置信息使用权 权限请求 权限请求和位置信息使用权限

为何要使用 <geolocation> 元素？

目前，地理定位流程依赖于 Geolocation API，该 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> 元素演示，展示了三种主要配置：手动请求、自动请求（使用 autolocate）和监听位置（使用 watch）。您可以在实时演示页面上测试这些行为。

样式限制

为确保用户信任并防止欺骗性设计模式，<geolocation> 元素应用了与之前的 <permission> 元素实验类似的特定样式限制。虽然您可以自定义按钮以匹配网站的主题，但浏览器会强制执行以下几项安全措施：

  • 可读性：检查文本和背景颜色是否具有足够的对比度（通常至少为 3:1），以确保权限请求始终清晰可读。此外，必须将 Alpha 通道（不透明度）设置为 1，以防止元素出现欺骗性透明效果。
  • 尺寸和间距：该元素会强制执行宽度、高度和字体大小的最小和最大边界。系统会停用负边距或轮廓偏移，以防止元素在视觉上被遮挡或以欺骗性方式与其他内容重叠。
  • 视觉完整性：扭曲效果受到限制 - 例如，转换仅支持 2D 平移和按比例缩放。
  • CSS 伪类：该元素支持基于状态的样式设置，例如：granted（当权限处于有效状态时）。

渐进增强策略

我们知道，标准化新的 HTML 元素是一个循序渐进的过程。不过，开发者可以立即采用 <geolocation> 元素，而不会影响其他浏览器中用户的兼容性。

该元素旨在实现优雅降级。不支持 <geolocation> 元素的浏览器会将其视为 [HTMLUnknownElement](https://developer.mozilla.org/docs/Web/API/HTMLUnknownElement)。重要的是，如果浏览器支持该元素，则不会呈现子元素。 这样一来，无论浏览器是否受支持，都可以清晰地编写 HTML。

自定义后备格式

如果您想完全控制回退体验，可以利用子元素（例如您与常规 JavaScript 地理定位 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 地理定位 API 支持的自定义元素 <geo-location>（请注意短划线）。如果浏览器支持 <geolocation> 元素，则填充程序不会执行任何操作。不妨查看此演示，了解 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 114 开始，您可以加入 <usermedia> HTML 元素源试用，从而为摄像头和麦克风带来同样的人体工程学优势。

致谢

本文档由 Andy Paicu、Gilberto Cocchi 和 Rachel Andrew 审核。