app.hotkey - 全局热键 API

注册和管理全局键盘快捷键。插件可在后台响应快捷键。

权限: L3 dangerous（需要辅助功能权限）

方法

app.hotkey.bind(mods, key, callback)

注册全局快捷键。

参数:

• mods (array) - 修饰键数组: "cmd", "shift", "alt"/"option", "ctrl"/"control", "fn"
• key (string) - 按键名: "a"-"z", "0"-"9", "f1"-"f12", "space", "return", "tab", "escape", "left", "right", "up", "down", "delete", "home", "end", "pageup", "pagedown" 等
• callback (function) - 快捷键触发时执行的回调函数

返回值: string, error - 热键 ID

-- 注册 Cmd+Shift+T
local id, err = app.hotkey.bind({"cmd", "shift"}, "t", function()
    app.notification.show("热键", "Cmd+Shift+T 被按下！")
end)

-- 注册 Ctrl+Alt+Space
app.hotkey.bind({"ctrl", "alt"}, "space", function()
    app.log.info("快速启动")
end)

app.hotkey.unbind(id)

注销指定快捷键。

参数:

• id (string) - 热键 ID

返回值: boolean, error

local ok, err = app.hotkey.unbind(id)

app.hotkey.unbindAll()

注销当前插件的所有快捷键。

返回值: boolean

app.hotkey.unbindAll()

app.hotkey.list()

列出当前插件的已注册快捷键。

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

• id (string) - 热键 ID
• key (string) - 按键名
• mods (array) - 修饰键数组
• enabled (boolean) - 是否启用

local hotkeys = app.hotkey.list()
for _, hk in ipairs(hotkeys) do
    local mods = table.concat(hk.mods, "+")
    app.log.info(hk.id .. ": " .. mods .. "+" .. hk.key .. " enabled=" .. tostring(hk.enabled))
end

app.hotkey.enable(id)

启用已禁用的快捷键。

参数:

• id (string) - 热键 ID

返回值: boolean, error

app.hotkey.disable(id)

临时禁用快捷键（不删除注册）。

参数:

• id (string) - 热键 ID

返回值: boolean, error

-- 临时禁用
app.hotkey.disable(id)
-- ... 某些操作后 ...
-- 重新启用
app.hotkey.enable(id)

说明

• 每个插件最多 20 个快捷键
• 需要 macOS 辅助功能权限（系统偏好设置 > 隐私与安全性 > 辅助功能）
• 相同按键组合不能被多个插件重复注册
• 快捷键在应用的所有窗口和其他应用中均有效
• 快捷键在插件卸载时自动注销
• 回调在插件执行队列上调用（线程安全）
• 快捷键不会消费原始事件，其他应用仍可接收

示例

快速操作面板

function MyPlugin:init()
    -- Cmd+Shift+K 打开快速操作
    app.hotkey.bind({"cmd", "shift"}, "k", function()
        local items = {
            {text = "新建文件", id = "new"},
            {text = "打开终端", id = "terminal"},
            {text = "复制路径", id = "copypath"},
        }
        local selected = app.chooser.show({
            title = "快速操作",
            items = items,
        })
        if selected then
            self:executeAction(selected[1])
        end
    end)
end