useGeolocation 是 Vue 3 中封装的地理位置获取组合式函数，返回 position、loading、error 响应式状态及 trigger() 方法，支持错误分类、手动触发、权限引导、缓存防抖、逆地理编码等扩展能力，与 UI 解耦且具备兼容性降级策略。

Vue 3 中地理位置获取的通用封装，核心是把 定位能力抽象为可复用的组合式函数（composable），而非绑定具体组件或 UI。它应屏蔽浏览器 API 差异、错误分类、加载状态，并支持手动触发、自动重试、权限引导等常见场景。

抽离为 useGeolocation 组合式函数

不依赖模板，只返回响应式状态和操作方法：

• 返回 position（包含 latitude、longitude、accuracy）、loading、error 三个响应式引用
• 提供 trigger() 手动获取，支持传入 options（如 { enableHighAccuracy: true, timeout: 5000 }）
• 内部自动处理 navigator.geolocation 不可用、用户拒绝、超时、位置不可用等典型错误，并映射为语义化错误码（如 'PERMISSION_DENIED'、'TIMEOUT'）
• 默认不自动执行，由调用方决定何时触发，避免无意义的初始请求

适配不同使用场景的扩展能力

基础函数之上，可通过参数或二次封装满足业务需求：

Springboot Vue Builder

从零开始编排 SpringBoot+Vue 全栈项目工作流，适用于新建全栈项目或完整脚手架请求，触发后依次调用 product‑spec‑builder（需求调研）等模块。

下载

• 支持 watch 监听：传入 immediate: true 或配合 watchEffect 实现“位置变化即更新”
• 集成逆地理编码：可选传入高德/百度 SDK 实例，拿到坐标后自动调用 AMap.Geocoder.getAddress 补全省市区地址
• 缓存与防抖：对短时间内重复调用做节流（如 30 秒内不重复请求），或基于 localStorage 缓存上次成功结果（带过期时间）
• 权限引导联动：当错误为权限拒绝时，暴露 openSettings() 方法（调用 navigator.permissions.query + 引导跳转系统设置）

与表单组件解耦协作

地理位置常用于表单项（如地址编辑器），但定位逻辑不应耦合在 UI 组件里：

• 表单组件内调用 useGeolocation()，仅负责展示状态（加载中图标、错误提示、坐标回显）
• 通过 v-model 向上透传经纬度对象（如 { lng: 121.47, lat: 31.23 }），而非让组合函数直接修改 props
• 校验逻辑交由 el-form 的 rules 处理：例如要求 lng 和 lat 均为有效数字且在合理范围内（-180~180，-90~90）
• 重置时清空本地 state，不主动再触发一次定位，避免干扰用户已有输入

兼容性与降级策略

真实环境中需应对老旧浏览器或弱网情况：

• 检测 navigator.geolocation 是否存在，不存在时直接设 error = 'UNSUPPORTED_BROWSER'
• 失败时提供 fallback：如预设城市中心坐标、允许手动输入、或调用 IP 定位接口（如高德 /v3/config/district 结合 IP）
• 对 iOS Safari 等限制后台定位的环境，提示“请在前台页面中开启定位”而非静默失败
• 所有外部依赖（如地图 SDK）按需加载，不阻塞主逻辑

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！