app.api - API 可用性查询

查询 API 函数的可用性和版本信息。

方法

app.api.version()

获取当前 API 引擎版本。

返回值: string

local ver = app.api.version()
-- "1.1.0"

app.api.available(path)

检查指定 API 函数是否可用（已注册且未被权限拒绝）。

参数:

path (string) - 函数完整路径，如 "app.bluetooth.watch"

返回值: boolean

if app.api.available("app.bluetooth.watch") then
    app.bluetooth.watch("deviceDisconnected", function(e)
        app.log.info("设备断开: " .. e.name)
    end)
else
    app.log.warn("蓝牙监听 API 不可用")
end

app.api.since(path)

查询指定 API 函数的引入版本。

参数:

path (string) - 函数完整路径

返回值: string | nil - 引入版本号，未知时返回 nil

local v = app.api.since("app.bluetooth.watch")
-- "1.1.0"

local v2 = app.api.since("app.nonexistent.fn")
-- nil

说明

L0 安全模块，所有插件均可使用，无需额外权限
替代已废弃的 _API_VERSION 全局变量
app.api.available 区分”函数存在”和”被权限拒绝”两种情况；若函数存在但当前插件缺少所需权限，仍返回 false
建议在调用高权限 API 前先用 app.api.available 检查，以便给用户提供友好的降级提示

错误码 `app.errors`

所有 API 返回的 err.code 取值是一组固定常量，通过 app.errors.* 访问，避免手写魔法字符串：

常量	值	含义
`app.errors.INVALID_ARGUMENT`	`"INVALID_ARGUMENT"`	参数缺失、类型错误或格式不合法
`app.errors.OPERATION_FAILED`	`"OPERATION_FAILED"`	操作执行失败（默认兜底）
`app.errors.PERMISSION_DENIED`	`"PERMISSION_DENIED"`	插件未声明该权限（`plugin.json`）
`app.errors.SYSTEM_PERMISSION_NOT_GRANTED`	`"SYSTEM_PERMISSION_NOT_GRANTED"`	系统级权限未授予（辅助功能、蓝牙、位置等）

典型用法：

local ok, err = app.shell.execute("some cmd")
if not ok then
    if err.code == app.errors.PERMISSION_DENIED then
        app.dialog.alert("需要授权", err.message)
    elseif err.code == app.errors.INVALID_ARGUMENT then
        app.log.error("参数错误: " .. err.message)
    else
        app.log.error(err.message)  -- 兜底：直接记日志
    end
end

大多数场景下插件只需读 err.message 展示给用户；err.code 适合在需要按失败原因分流时使用。

示例

按版本选择实现

function MyPlugin:onMenuItems(context)
    -- 优先使用新版 API，兼容旧版引擎
    if app.api.available("app.chooser.show") then
        local item = app.chooser.show({{text = "选项 A"}, {text = "选项 B"}})
        if item then
            self:handleChoice(item.text)
        end
    else
        local choice = app.dialog.input("请输入选项", "选项 A")
        if choice then
            self:handleChoice(choice)
        end
    end
end

版本检测与提示

function MyPlugin:onMenuItems(context)
    local ver = app.api.version()
    app.log.info("API 引擎版本: " .. ver)

    if not app.api.available("app.ocr.recognize") then
        app.dialog.alert("功能不可用", "当前版本不支持文字识别，请升级 iRightMenu Pro。")
        return
    end

    local text = app.ocr.recognize(context.selectedFiles[1])
    app.clipboard.set(text)
    app.notification.show("识别完成", "已复制到剪贴板")
end