app.location - 位置服务 API

获取当前地理位置、地理编码/反地理编码，以及监听位置变化。

权限: L2 敏感级，需要系统位置服务权限。首次调用时系统会弹出授权提示。

方法

app.location.isEnabled()

检查位置服务是否已开启（系统级别）。

返回值: boolean

if not app.location.isEnabled() then
    app.dialog.alert("位置服务", "请在系统设置中开启位置服务")
end

app.location.authorizationStatus()

获取应用的位置权限状态。

返回值: string

"authorized" - 已授权
"denied" - 已拒绝
"notDetermined" - 尚未请求授权
"restricted" - 受限制（如家长控制）

local status = app.location.authorizationStatus()
if status == "denied" then
    app.dialog.alert("权限不足", "请在系统设置中允许访问位置")
end

app.location.current()

获取当前地理位置（同步，阻塞直到获取到位置或超时）。

返回值: table, error - 位置信息:

latitude (number) - 纬度
longitude (number) - 经度
altitude (number) - 海拔（米）
accuracy (number) - 水平精度（米）
timestamp (string) - 时间戳（ISO 8601）

local loc, err = app.location.current()
if loc then
    app.log.info(string.format("位置: %.6f, %.6f (精度: %.0fm)",
        loc.latitude, loc.longitude, loc.accuracy))
else
    app.log.error("获取位置失败: " .. (err or ""))
end

app.location.geocode(address)

将地址字符串转换为地理坐标（正向地理编码）。

参数:

address (string) - 地址字符串

返回值: table, error - 地理信息:

latitude (number) - 纬度
longitude (number) - 经度
name (string) - 地点名称
street (string) - 街道
city (string) - 城市
state (string) - 省/州
country (string) - 国家
countryCode (string) - 国家代码（如 “CN”）
postalCode (string) - 邮编

local result, err = app.location.geocode("北京市海淀区中关村大街")
if result then
    app.log.info(string.format("坐标: %.6f, %.6f", result.latitude, result.longitude))
    app.log.info("城市: " .. result.city)
end

app.location.reverseGeocode(lat, lon)

将坐标转换为地址信息（反向地理编码）。

参数:

lat (number) - 纬度
lon (number) - 经度

返回值: table, error - 地理信息（字段同 geocode() 返回值）

local loc = app.location.current()
if loc then
    local addr, err = app.location.reverseGeocode(loc.latitude, loc.longitude)
    if addr then
        app.log.info("当前地址: " .. (addr.street or "") .. ", " .. (addr.city or ""))
    end
end

app.location.watch(event, callback)

监听位置变化事件。

参数:

event (string) - 事件名称（目前仅支持 "locationChanged"）
callback (function) - 回调函数，接收位置表:
- latitude (number) - 纬度
- longitude (number) - 经度
- altitude (number) - 海拔（米）
- accuracy (number) - 水平精度（米）
- timestamp (string) - 时间戳（ISO 8601）

返回值: string, error - watcher 句柄 ID

local handle, err = app.location.watch("locationChanged", function(e)
    app.log.info(string.format("位置更新: %.6f, %.6f", e.latitude, e.longitude))
end)

app.location.stopAllWatchers()

停止当前插件注册的所有位置监听器。

返回值: boolean

app.location.stopAllWatchers()

app.location.listWatchers()

列出当前插件已注册的位置监听器。

返回值: array<table> - 每项包含:

id (string) - watcher 句柄 ID
event (string) - 监听的事件名称

local watchers = app.location.listWatchers()
app.log.info("活跃位置监听器: " .. #watchers)

说明

位置服务需要用户明确授权，拒绝后需要在「系统设置 → 隐私与安全性 → 位置服务」中手动开启
current() 内部使用 CoreLocation 框架，在精度与速度之间取平衡；室内环境下精度可能下降
geocode() 和 reverseGeocode() 依赖 Apple 地图服务，需要网络连接
watch() 注册的监听器在插件卸载时自动清理
位置权限属于 L2 敏感权限，插件需在 plugin.json 中声明 "permissions": ["location"]

示例

获取当前位置并显示地址

function MyPlugin:handleGetLocation(context)
    local status = app.location.authorizationStatus()
    if status ~= "authorized" then
        app.dialog.alert("权限", "位置服务未授权（状态: " .. status .. "）")
        return
    end

    app.progress.show("定位中", {message = "正在获取当前位置..."})

    local loc, err = app.location.current()
    app.progress.hide()

    if not loc then
        app.dialog.alert("错误", "获取位置失败: " .. (err or ""))
        return
    end

    local addr, _ = app.location.reverseGeocode(loc.latitude, loc.longitude)

    local info = string.format(
        "坐标: %.6f, %.6f\n海拔: %.0f 米\n精度: %.0f 米",
        loc.latitude, loc.longitude, loc.altitude, loc.accuracy
    )

    if addr then
        info = info .. "\n\n地址: " .. (addr.street or "") ..
               "\n城市: " .. (addr.city or "") ..
               "\n国家: " .. (addr.country or "")
    end

    app.dialog.alert("当前位置", info)
end

将坐标写入文件元数据

function MyPlugin:handleTagWithLocation(context)
    local loc, err = app.location.current()
    if not loc then return end

    for _, file in ipairs(context.selectedFiles) do
        local coord = string.format("%.6f,%.6f", loc.latitude, loc.longitude)
        app.xattr.set(file, "com.irightmenu.gps", coord)
    end

    app.notification.show("完成", "已为 " .. #context.selectedFiles .. " 个文件标记位置")
end