app.mouse - 鼠标模拟 API

模拟鼠标操作（点击、移动、拖拽、滚动）。

权限: 需在 manifest 中声明 mouse（L3 dangerous） 系统要求: 需要辅助功能权限（Accessibility Permission），position() 除外

方法

app.mouse.click(x, y, opts?)

在指定坐标点击鼠标。

参数:

• x (number) - X 坐标（屏幕像素）
• y (number) - Y 坐标（屏幕像素）
• opts (table, 可选):
  • button (string, 可选) - 按键："left"（默认）、"right"、"middle"
  • clicks (number, 可选) - 点击次数（默认 1，2 为双击）
  • modifiers (array, 可选) - 修饰键数组（如 {"cmd", "shift"}）

返回值: boolean, error

-- 左键单击
app.mouse.click(100, 200)

-- 右键单击
app.mouse.click(100, 200, {button = "right"})

-- 双击
app.mouse.click(100, 200, {clicks = 2})

-- Cmd+点击
app.mouse.click(100, 200, {modifiers = {"cmd"}})

app.mouse.move(x, y)

移动鼠标到指定坐标。

参数:

• x (number) - X 坐标
• y (number) - Y 坐标

返回值: boolean, error

app.mouse.move(500, 300)

app.mouse.drag(fromX, fromY, toX, toY, opts?)

从一个坐标拖拽到另一个坐标。

参数:

• fromX (number) - 起始 X 坐标
• fromY (number) - 起始 Y 坐标
• toX (number) - 目标 X 坐标
• toY (number) - 目标 Y 坐标
• opts (table, 可选):
  • button (string, 可选) - 按键："left"（默认）或 "right"
  • duration (number, 可选) - 拖拽持续时间（秒，默认 0.5）

返回值: boolean, error

-- 简单拖拽
app.mouse.drag(100, 200, 500, 400)

-- 慢速拖拽
app.mouse.drag(100, 200, 500, 400, {duration = 2.0})

-- 右键拖拽
app.mouse.drag(100, 200, 500, 400, {button = "right"})

app.mouse.position()

获取当前鼠标位置。

此方法不需要辅助功能权限。

返回值: table - {x, y}

local pos = app.mouse.position()
app.log.info(string.format("鼠标位置: %d, %d", pos.x, pos.y))

app.mouse.scroll(dx, dy)

模拟滚轮滚动。

参数:

• dx (number) - 水平滚动量（正数向右，负数向左）
• dy (number) - 垂直滚动量（正数向下，负数向上）

返回值: boolean, error

-- 向下滚动
app.mouse.scroll(0, 5)

-- 向上滚动
app.mouse.scroll(0, -5)

-- 水平滚动
app.mouse.scroll(3, 0)

示例

自动化 UI 操作

function MyPlugin:handleAutomate(context)
    -- 获取当前鼠标位置
    local startPos = app.mouse.position()

    -- 移动到目标位置并点击
    app.mouse.move(200, 100)
    app.thread.sleep(0.2)
    app.mouse.click(200, 100)
    app.thread.sleep(0.5)

    -- 拖拽文件
    app.mouse.drag(200, 100, 500, 300, {duration = 1.0})

    -- 恢复鼠标位置
    app.mouse.move(startPos.x, startPos.y)
end

框选区域

function MyPlugin:handleSelectRegion(context)
    -- 获取用户点击的起始位置
    local pos = app.mouse.position()

    -- 向右下方拖拽选择
    app.mouse.drag(pos.x, pos.y, pos.x + 300, pos.y + 200, {
        duration = 0.3
    })
end

注意事项

1. 辅助功能权限：除 position() 外，所有方法需要辅助功能权限
2. 权限等级：L3 dangerous，需在 manifest 中声明 mouse 权限
3. 坐标系：使用屏幕像素坐标，原点在主屏幕左上角
4. 拖拽插值：drag() 使用线性插值生成中间移动事件，模拟真实拖拽
5. 修饰键：支持 cmd/command、shift、alt/option、ctrl/control、fn