组件：地理定位器

地理定位器组件是一个不可视组件，用于获取设备的地理位置信息（经纬度、海拔、速度等），并支持持续监听位置变化。它基于浏览器的 Geolocation API 实现，适用于位置服务、地图应用、定位导航、轨迹记录等场景。注意： 使用前需获得用户明确授权，且仅在 HTTPS 环境下可用。

典型使用场景：

地图应用（显示用户当前位置）
位置签到（打卡、签到功能）
导航与轨迹记录（运动轨迹、行车路线）
基于位置的服务（附近的人、周边推荐）
物流追踪（包裹实时位置）

快速索引

你想知道什么	直接看这里
如何获取当前位置	`获取位置(成功回调, 失败回调)`
如何持续监听位置变化	`监听位置被改变(回调函数)`
如何停止监听	`停止监听()`
位置对象包含哪些信息	见下方“位置信息详解”
如何判断用户是否授权	通过错误回调判断（`权限被拒绝`）
如何检查是否支持定位	调用 `获取位置` 并观察是否立即返回错误

基础示例

最简单的使用流程：获取当前位置 → 处理位置信息 → 处理错误。

变量 定位器 = 创建 地理定位器()

' 1. 获取当前位置
定位器.获取位置((位置对象) => {
        ' 成功回调
        调试输出("✅ 获取位置成功")
        调试输出("  纬度：" + 位置对象.coords.latitude)
        调试输出("  经度：" + 位置对象.coords.longitude)
        调试输出("  精度：" + 位置对象.coords.accuracy + " 米")
        弹出提示("当前位置：经度 " + 位置对象.coords.longitude + "，纬度 " + 位置对象.coords.latitude)
    },(错误对象) => {
        ' 失败回调
        调试输出("❌ 获取位置失败：" + 错误对象.message)
        如果(错误对象.code == 1)
            弹出提示("用户拒绝了位置授权")
        否则 如果(错误对象.code == 2)
            弹出提示("位置信息不可用，请检查GPS或网络")
        否则 如果(错误对象.code == 3)
            弹出提示("获取位置超时，请重试")
        否则
            弹出提示("定位失败：" + 错误对象.message)
        结束 如果
    }
)

综合示例：实时轨迹记录

本示例模拟一个轨迹记录应用，持续监听位置变化，并将每次位置更新添加到列表中，可用于运动记录、路线绘制等场景。

变量 定位器 = 创建 地理定位器()
变量 轨迹点列表 = []
变量 是否记录 = 假

' ========== 定义位置更新处理函数 ==========
函数 处理位置更新(位置对象)
    if (!是否记录) return
    
    变量 坐标 = 位置对象.coords
    变量 点 = {
        latitude: 坐标.latitude,
        longitude: 坐标.longitude,
        accuracy: 坐标.accuracy,
        altitude: 坐标.altitude,
        speed: 坐标.speed,
        timestamp: 位置对象.timestamp
    }
    添加成员(轨迹点列表, 点)
    
    变量 点数 = 取数组成员数(轨迹点列表)
    调试输出("📍 记录点 " + 点数 + "：(" + 坐标.latitude + ", " + 坐标.longitude + ")")
    ' 可在此更新 UI，例如在地图上绘制标记
结束 函数

' ========== 开始记录 ==========
函数 开始记录()
    是否记录 = 真
    
    ' 先获取一次当前位置（立即获取）
    定位器.获取位置((位置对象) => {
            处理位置更新(位置对象)
            ' 然后开始持续监听
            定位器.监听位置被改变(处理位置更新)
            弹出提示("开始记录轨迹")
        },(错误对象) => {
            弹出提示("无法获取位置：" + 错误对象.message)
            是否记录 = 假
        }
    )
结束 函数

' ========== 停止记录 ==========
函数 停止记录()
    是否记录 = 假
    定位器.停止监听()
    变量 点数 = 取数组成员数(轨迹点列表)
    弹出提示("已停止记录，共记录 " + 点数 + " 个轨迹点")
    调试输出("📊 轨迹点总数：" + 点数)
结束 函数

' ========== 演示：开始记录，5秒后停止 ==========
开始记录()
延时执行(() => {
    停止记录()
}, 5000)

函数详解

获取位置(成功回调, 失败回调)

功能： 获取设备当前的地理位置信息（单次获取）。该方法会向用户弹窗请求授权（首次使用时）。
参数：
- 成功回调：函数，格式为 (位置对象) => { ... }，位置对象包含经纬度、精度、海拔等信息（详见下方“位置信息详解”）。
- 失败回调：函数，格式为 (错误对象) => { ... }，错误对象包含 code 和 message 属性。
返回值： 无。
示例： 见基础示例。

监听位置被改变(回调函数)

功能： 持续监听设备位置变化，每当位置更新时触发回调。适合实时跟踪场景（如导航）。
参数： 回调函数，格式同 成功回调，每次位置变化都会调用。
返回值： 无。
示例： 定位器.监听位置被改变((位置) => { 调试输出(位置.coords.latitude) })

停止监听()

功能： 停止位置变化监听，释放相关资源。不再触发 监听位置被改变 的回调。
返回值： 无。
示例： 定位器.停止监听()

位置信息详解

成功回调 返回的 位置对象 包含以下属性：

属性	类型	说明
`coords.latitude`	数值	纬度（-90 到 90）
`coords.longitude`	数值	经度（-180 到 180）
`coords.accuracy`	数值	经纬度精度（米）
`coords.altitude`	数值（可能为 `空`）	海拔（米）
`coords.altitudeAccuracy`	数值（可能为 `空`）	海拔精度（米）
`coords.heading`	数值（可能为 `空`）	行进方向（0-360 度，相对正北）
`coords.speed`	数值（可能为 `空`）	速度（米/秒）
`timestamp`	数值	时间戳（毫秒）

💡 部分属性（如 heading、speed）仅在移动设备且启用 GPS 时有效，桌面浏览器通常为 空。

错误对象详解

失败回调 返回的 错误对象 包含以下属性：

属性	说明
`code`	错误码：`1` 用户拒绝授权，`2` 位置不可用（如 GPS 关闭），`3` 获取超时
`message`	错误描述文本

事件说明

地理定位器组件的事件与回调函数对应关系如下：

事件	对应方法	触发时机
`位置被改变(事件源)`	`监听位置被改变`	位置发生变化（持续监听模式下）

注意： 获取位置 的成功/失败是通过回调函数传递的，没有对应的事件。

⚠️ 注意事项

用户授权：首次调用 获取位置 会弹窗请求权限，用户拒绝后需引导用户手动开启（在浏览器设置中）。
HTTPS 要求：地理定位功能仅在安全上下文（HTTPS）或 localhost 下可用。
超时设置：目前组件未提供超时配置，默认超时时间由浏览器决定（通常较长），若需调整可考虑封装自定义逻辑。
功耗与电量：持续监听位置变化会消耗较多电量，建议在不需要时调用 停止监听()。
精度与响应速度：accuracy 越小精度越高，但获取时间可能更长。浏览器会根据设备自动平衡。
位置缓存：有时浏览器会返回缓存的位置数据，可通过 timestamp 判断是否过旧。
错误处理：务必设置失败回调，尤其是处理用户拒绝授权的情况，提供友好的降级方案。
后台运行：浏览器页面切换到后台时，位置监听可能被暂停或节流，建议结合页面可见性 API 管理监听状态。
模拟器测试：在浏览器开发者工具中，可模拟位置数据（Chrome DevTools 的 Sensors 面板）。
坐标系：返回的经纬度为 WGS84 坐标系，可直接用于主流地图服务（如高德、百度需要转换坐标系）。

轻语言网站开发SDK文档