iRightMenu Pro Lua API 参考

完整的 Lua 插件 API 参考文档。

引擎版本: 1.3.0 最后更新: 2026 年 4 月

真值来源：客户端 LuaAPIRegistry.swift 中 engineVersion（按 since: 字段最大值计算）。

API 模块索引

快速参考

常用 API 速查

-- 日志
app.log.info("消息")
app.log.error("错误")

-- 上下文
local files = app.context.selectedFiles()
local dir = app.context.currentDirectory()

-- 对话框
app.dialog.alert("标题", "内容")
local ok = app.dialog.confirm("确认吗？")
local input = app.dialog.input("请输入", "默认值")

-- 进度
app.progress.show("处理中", {message = "请稍候..."})
app.progress.update(50, "一半了")
app.progress.hide()

-- 通知
app.notification.show("完成", "处理了 10 个文件")

-- 设置
local val = app.settings.get("key", "default")
app.settings.set("key", "value")

-- 文件
local content = app.file.read("/path/to/file")
app.file.write("/path/to/file", "content")
app.file.copy(src, dst)
app.file.move(src, dst)
app.file.delete(path)

-- 路径
app.path.basename("/a/b/c.txt")  -- "c.txt"
app.path.dirname("/a/b/c.txt")   -- "/a/b"
app.path.join("/a", "b", "c")    -- "/a/b/c"
app.path.exists(path)            -- true/false

-- Shell
local result = app.shell.execute("ls -la")
-- result.code, result.stdout, result.stderr
app.shell.quote("my file")      -- "'my file'"（Shell 安全引用）

-- JSON
local t = app.json.parse('{"a":1}')
local s = app.json.stringify({a = 1})

-- UTI / URL
local uti = app.uti.fromExtension("pdf")   -- "com.adobe.pdf"
local url = app.url.parse("https://example.com/path?q=1")

-- 扩展属性 / 标签
local tags = app.xattr.getTags(path)
app.xattr.addTag(path, "重要")
app.trash.moveToTrash(path)

-- 数据格式
local rows = app.csv.parseFile("data.csv", {header = true})
local doc = app.xml.parseFile("config.xml")
local info = app.pdf.info("document.pdf")

-- 网络 / 系统
local ip = app.network.localIP()
local bat = app.power.battery()
local isDark = app.screen.isDarkMode()
app.audio.setVolume(0.5)

-- OCR / 二维码
local text = app.ocr.recognize("image.png")
app.qrcode.generate("hello", {path = "/tmp/qr.png"})

-- 防休眠 / 文件监听
local id = app.wakelock.preventSleep({duration = 3600})
local wid = app.watcher.watch("/path", function(e) end)

-- 分享 / 快捷指令
app.share.show({"/path/to/file.pdf"})
app.shortcuts.run("My Shortcut", {input = "hello"})

-- 定时器
app.timer.after(3, function() print("done") end)
local tid = app.timer.every(10, function() print("tick") end)

-- 颜色
local c = app.color.parse("#FF6600")
local hex = app.color.lighten("#336699", 20)
local ratio = app.color.contrast("#000", "#FFF")

-- Keychain
app.keychain.set("api_key", "sk-xxx")
local token = app.keychain.get("api_key")
app.keychain.has("api_key")  -- true/false

-- UserDefaults
local val = app.defaults.read("com.apple.finder", "AppleShowAllFiles")
app.defaults.write("com.apple.finder", "AppleShowAllFiles", true)

-- WebSocket
local wsId = app.websocket.connect("wss://echo.websocket.org", {
    onMessage = function(id, data) print(data) end
})
app.websocket.send(wsId, "hello")

-- 键盘/鼠标
app.keyboard.hotkey({"cmd"}, "c")
app.mouse.click(100, 200)
local pos = app.mouse.position()

-- 选择器
local item = app.chooser.show({{text = "A"}, {text = "B"}})

-- WebView
local wvId = app.webview.open({html = "<h1>Hello</h1>"})
app.webview.eval(wvId, "document.title")

-- 蓝牙
local devices = app.bluetooth.connectedDevices()
app.bluetooth.watch("deviceDisconnected", function(e) end)

-- 窗口管理
local windows = app.window.list({app = "Safari"})
app.window.move({app = "Safari"}, 0, 0)
app.window.maximize({app = "Safari"})

-- 位置
local loc = app.location.current()
local addr = app.location.reverseGeocode(loc.latitude, loc.longitude)

-- 事件监听（各模块）
app.application.watch("terminate", function(e) end)
app.system.watch("sleep", function() end)
app.power.watch("powerSourceChanged", function(e) end)
app.network.watch("networkChanged", function(e) end)
app.screen.watch("darkModeChanged", function(e) end)

返回值约定

所有 API 统一采用 result, error 双返回值模式：

local result, err = app.xxx.yyy(...)
if not result then
    -- err 为错误原因字符串（权限拒绝 / 参数缺失 / 连接超时等）
    app.log.error("失败: " .. (err or "unknown"))
end

规则：

• 成功：返回结果值（string / number / bool / table），第二个返回值自动为 nil
• 失败：返回 nil, "错误描述" 或 false, "错误描述"
• 用户取消：对话框取消返回 nil（不带错误信息，不算错误）

错误语义边界：

• Shell：命令 exit code != 0 是 API 成功（result = {code, stdout, stderr}），仅连接超时才返回 error
• HTTP：HTTP 4xx/5xx 是 API 成功（result = {status, body}），仅网络错误/DNS 失败才返回 error
• Dialog：用户取消是正常返回 nil，不是错误