新的 HTML Geolocation 元素

如果你曾经使用过 navigator.geolocation.getCurrentPosition(),你一定熟悉这套流程:编写回调函数、处理错误、管理权限状态,并祈祷浏览器不会因为用户多次关闭提示而悄无声息地吞掉权限请求。新的 <geolocation> HTML 元素采用了完全不同的方法——在 HTML 中声明式地获取地理位置,由浏览器本身处理。

以下是关于它的定义、工作原理,以及使用前需要了解的内容。

什么是 <geolocation> HTML 元素?

<geolocation> HTML 元素是一个实验性的浏览器控制按钮,允许用户直接从页面共享其位置。不再是由你的 JavaScript 触发权限提示,而是用户自己激活控件。浏览器处理权限流程,你只需监听结果。

它在 Chrome 144 中发布。截至 2026 年初,这仍然是 Chromium 主导的功能,尚未在其他引擎中实现。将其视为可以实验的功能,而不是在没有降级方案的情况下普遍部署。你可以在 https://caniuse.com/mdn-html_elements_geolocation 上跟踪当前的实现状态。

Geolocation API 的问题

navigator.geolocation API 是命令式的。你的脚本调用 getCurrentPosition(),浏览器决定是否显示提示,如果用户多次关闭该提示,Chrome 可能会在一段时间内悄悄阻止它。没有错误,没有反馈——只有沉默。

上下文缺失使情况更糟。没有解释就出现的提示会被条件反射式地拒绝。这种拒绝可能会变得持久,并且用户没有明显的方法来撤销它。

HTML 中的声明式地理位置如何解决这个问题

<geolocation> 元素翻转了这个模型。用户点击按钮。这个点击本身就是权限信号。浏览器知道请求来自用户的主动操作,这有助于避免静默阻止场景,并在用户之前拒绝访问时为他们提供更清晰的恢复路径。

HTMLGeolocationElement 接口直接在元素上暴露结果:

<geolocation onlocation="handleLocation(event)"></geolocation>

function handleLocation(event) {
  if (event.target.position) {
    const { latitude, longitude } = event.target.position.coords;
    console.log(latitude, longitude);
  } else if (event.target.error) {
    console.error(event.target.error.message);
  }
}

该元素暴露 position 和 error 属性,当浏览器返回结果时,你可以监听 location 等事件。

关键属性

• autolocate — 如果之前已授予权限,则在页面加载时触发 location 事件,无需点击。如果尚未授予权限则不执行任何操作。
• watch — 对应 watchPosition(),随着设备移动持续触发。
• accuracymode — 接受 "precise" 或 "approximate"。精确模式对应 enableHighAccuracy: true,并将按钮图标更改为十字准星。请注意,在桌面设备上差异通常可以忽略不计——在户外的移动设备上测试以查看真实差异。

一个值得了解的特性:每页最多只能使用三个 <geolocation> 元素。超过该数量,所有元素都将停止工作。

该元素仍然依赖于与 Geolocation API 相同的底层安全模型,需要安全上下文(HTTPS)和明确的用户权限。

Geolocation API vs HTML Geolocation 元素:应该使用哪个?

目前,两者都用。<geolocation> HTML 元素不会取代 navigator.geolocation——它是对其的封装。在支持的地方使用该元素,并优雅地降级:

<geolocation onlocation="updateMap()">
  <!-- 仅在不支持 <geolocation> 的浏览器中渲染 -->
  <button onclick="navigator.geolocation.getCurrentPosition(updateMap)">
    使用我的位置
  </button>
</geolocation>

支持的浏览器会隐藏子内容。不支持的浏览器会渲染降级按钮。如果你想要更自动化的方法,npm 上有一个 polyfill,它会替换为由标准 API 支持的自定义元素。

特性检测很简单:

if ('HTMLGeolocationElement' in window) {
  // 支持该元素
} else {
  // 使用 navigator.geolocation
}

样式设置有严格限制

该元素看起来像一个按钮,但从 CSS 角度来看行为不同。浏览器强制执行约束以防止欺骗性模式:opacity 锁定为 1,文本和背景之间的对比度必须至少为 3:1,并且阻止扭曲变换。如果对比度或字体大小低于最小阈值,按钮不会在视觉上停用——它只是停止工作。你可以使用 :granted 伪类在授予权限后设置按钮样式。

未来发展方向

<geolocation> 元素是计划中的一系列特定功能元素中的第一个。用于摄像头和麦克风访问的 <usermedia> 元素已经在进行源试验。这种模式——声明式、用户发起、浏览器中介——显然是平台发展的方向。

结论

<geolocation> 元素代表了浏览器处理敏感权限方式的重大转变。通过将触发器从脚本转移到用户操作,它规避了命令式 API 的许多静默阻止陷阱,并为用户提供了更清晰的控制,决定何时以及是否共享其位置。浏览器支持仍然有限,但降级模式简洁,API 表面最小。今天就开始使用渐进增强进行实验——权限用户体验对用户来说确实更好,而声明式模型是 Web 平台的发展方向。

常见问题

我今天可以在生产环境中使用 geolocation 元素吗?

无法在所有浏览器中可靠使用。截至 2026 年初,它仅在 Chrome 144 及更高版本中发布。始终使用 navigator.geolocation.getCurrentPosition 包含降级方案,以便无论浏览器支持如何,你的功能都能为每位访问者工作。

如果我在单个页面上放置超过三个 geolocation 元素会发生什么?

所有元素都将停止运行。浏览器强制每页最多三个 geolocation 元素的硬限制。如果超过该数量,所有元素都不会触发 location 事件。设计页面时确保在任何给定时间 DOM 中仅出现必要的实例。

autolocate 属性会在页面加载时触发权限提示吗?

不会。autolocate 属性仅在用户在之前的交互中已授予权限时才会自动触发 location 事件。如果尚未授予权限,该属性不起作用,用户必须点击元素以启动权限流程。

为什么我不能像常规按钮一样自由设置 geolocation 元素的样式?

浏览器限制样式设置以防止可能欺骗用户在不知情的情况下共享其位置的欺骗性 UI 模式。opacity 必须保持为 1,文本与背景的对比度必须达到 3:1 的比率。如果违反这些阈值,元素会静默停止响应点击,而不是在视觉上禁用自身。