useGeolocation

跟踪地理位置的 React Hook

如果用户愿意，它允许用户向网络应用程序提供他们的位置。 出于隐私原因，报告位置信息需要用户许可

useGeolocation 封装了 Geolocation API，用于响应式地跟踪用户的地理位置。它返回一个包含 coordinates（纬度、经度、海拔、精度等）、locatedAt 时间戳、error 对象和 isSupported 标志的对象。该 hook 监听位置变化并自动更新。可以传递标准 PositionOptions（如 enableHighAccuracy 和 timeout）作为选项。

使用场景

• 在地图上显示用户的当前位置或提供基于位置的搜索结果
• 构建地理围栏功能，当用户进入或离开某个地理区域时触发操作
• 基于用户的实时位置计算距离或方向

注意事项

• SSR 安全：在服务端渲染期间返回默认坐标和 null 值。服务端不会访问 navigator.geolocation。
• 权限：浏览器会提示用户授予位置权限。error 属性会捕获任何拒绝或超时。可配合 usePermission（使用 "geolocation"）主动检查权限状态。
• 隐私：位置数据是敏感的。仅在真正需要时请求地理位置，并告知用户为什么需要访问其位置。

Usage

function Demo() {
  const { coordinates, locatedAt, error } = useGeolocation();

  return (
    <div>
      <pre lang="json">
        {JSON.stringify(
          {
            coordinates: {
              accuracy: coordinates.accuracy,
              latitude: coordinates.latitude,
              longitude: coordinates.longitude,
              altitude: coordinates.altitude,
              altitudeAccuracy: coordinates.altitudeAccuracy,
              heading: coordinates.heading,
              speed: coordinates.speed,
            },
            locatedAt,
            error: error ? error.message : error,
          },
          null,
          2,
        )}
      </pre>
    </div>
  );
};

API

useGeoLocation

Returns

{ readonly coordinates: GeolocationCoordinates; readonly locatedAt: number | null; readonly error: GeolocationPositionError | null; readonly isSupported: boolean; }: 包含以下元素的对象：

• 坐标。
• 获取坐标的时间戳。
• 错误。
• 浏览器是否支持 geolocation。

Arguments