app.keyboard - 键盘模拟 API

模拟键盘输入和快捷键操作。

权限: 需在 manifest 中声明 keyboard（L3 dangerous） 系统要求: 需要辅助功能权限（Accessibility Permission）

方法

app.keyboard.type(text)

模拟键盘输入文本。逐字符输入，支持 Unicode 字符。

参数:

• text (string) - 要输入的文本

返回值: boolean, error

local ok, err = app.keyboard.type("Hello, World!")

-- 输入中文
local ok, err = app.keyboard.type("你好世界")

app.keyboard.pressKey(key, modifiers?)

模拟按下单个按键。

参数:

• key (string) - 按键名称（见下方按键列表）
• modifiers (array, 可选) - 修饰键数组

返回值: boolean, error

-- 按下回车键
app.keyboard.pressKey("return")

-- 按下 Tab
app.keyboard.pressKey("tab")

-- 带修饰键
app.keyboard.pressKey("a", {"cmd", "shift"})

app.keyboard.hotkey(modifiers, key)

模拟快捷键组合。

参数:

• modifiers (array) - 修饰键数组
• key (string) - 按键名称

返回值: boolean, error

-- Cmd+C（复制）
app.keyboard.hotkey({"cmd"}, "c")

-- Cmd+Shift+S（另存为）
app.keyboard.hotkey({"cmd", "shift"}, "s")

-- Ctrl+Alt+Delete
app.keyboard.hotkey({"ctrl", "alt"}, "delete")

按键名称

字母和数字

a-z、0-9

功能键

方向键

left、right、up、down

功能键

f1 ~ f12

导航键

home、end、pageup、pagedown

符号键

-、=、[、]、;、'、,、.、/、\、`

修饰键

示例

自动填充表单

function MyPlugin:handleAutoFill(context)
    -- 切换到目标应用
    app.keyboard.hotkey({"cmd"}, "tab")
    app.thread.sleep(0.5)

    -- 输入用户名
    app.keyboard.type("admin@example.com")
    app.keyboard.pressKey("tab")  -- 切换到下一个字段

    -- 输入密码
    app.keyboard.type("password123")
    app.keyboard.pressKey("return")  -- 提交
end

快速操作

function MyPlugin:handleQuickAction(context)
    -- 全选
    app.keyboard.hotkey({"cmd"}, "a")
    app.thread.sleep(0.1)

    -- 复制
    app.keyboard.hotkey({"cmd"}, "c")
    app.thread.sleep(0.1)

    -- 新建文档
    app.keyboard.hotkey({"cmd"}, "n")
    app.thread.sleep(0.5)

    -- 粘贴
    app.keyboard.hotkey({"cmd"}, "v")
end

注意事项

1. 辅助功能权限：首次使用会提示用户授予辅助功能权限，需在系统设置中手动允许
2. 权限等级：L3 dangerous，需在 manifest 中声明 keyboard 权限
3. 输入延迟：type() 逐字符输入，每个字符间隔约 10ms
4. 焦点要求：键盘事件发送到当前焦点窗口，确保目标应用在前台