<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。 重要的是，如果浏览器支持该元素，则不会呈现子元素。 这样，您就可以为受支持和不受支持的浏览器编写简洁的 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>

通过基本示例测试该行为的工作方式。

聚酯纤维

或者，您可以从 npm安装一个聚酯纤维，该聚酯纤维会 透明地自动将所有出现的<geolocation>替换为 自定义元素<geo-location>（请注意短划线），并由常规 JavaScript Geolocation API 提供支持。如果浏览器支持 <geolocation> 元素， 则聚酯纤维不会执行任何操作。请查看此 聚酯纤维演示，了解 聚酯纤维的实际应用。源 代码可以在 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 元素实现性能更高的位置 重试场景。它代表着向特定于功能的元素转变，这些元素是根据用户如今实际使用 Web 的方式量身定制的。

对于其他权限用例，从 Chrome 144 开始，您可以加入 the <usermedia> HTML 元素源 试用，为摄像头和麦克风带来相同的便捷优势。

相关链接

• Chrome 平台状态中的 <geolocation> 元素
• Geolocation HTML 元素说明
• 演示页面
• Mozilla 标准立场
• WebKit 标准立场

致谢

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