<geolocation> HTML 元素简介

Mari Viana

Minh Le

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 的需求。

为何要使用 <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> 元素应用了与之前的 <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 元素源试用，从而为摄像头和麦克风带来同样的人体工程学优势。

相关链接

• Chrome 平台状态中的 <geolocation> 元素
• 地理定位 HTML 元素讲解
• 演示页面
• Mozilla 标准立场
• WebKit 标准位置

致谢

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