jokymouse API

jokymouse 指的是通过 require("jokymouse") 加载的核心模块。它负责脚本生命周期控制、settings 读取、异步任务，以及鼠标键盘自动化能力。

local jm = require("jokymouse")

一般功能

函数	签名	说明
version	`jm.version()`	返回当前小丑鼠版本号
position	`jm.position()`	返回当前鼠标坐标两个值
is_dev_mode	`jm.is_dev_mode()`	返回当前脚本是否以开发模式运行

屏幕坐标系：左上角是原点 (0, 0)，x 向右增大，y 向下增大。

生命周期与设置

函数	签名	说明
settings	`jm.settings()`	返回包含全部 settings 的 Lua table
sleep	`jm.sleep(ms)`	异步休眠，不阻塞线程
ensure_running	`jm.ensure_running()`	检查脚本是否仍应继续运行；若已被停止或要求退出，会立刻中断
exit	`jm.exit()`	正常退出脚本，同时停止其他 fork 出来的任务
panic	`jm.panic(errmsg)`	以错误方式中止脚本；等价于在 Lua 层调用 `error(errmsg)`

jm.ensure_running() 适合放在长循环、轮询等待、批量处理的间隙里。这样用户手动停止脚本时，脚本可以更快响应。(一般情况下，你无需手动调用，因为所有 jokymouse 内部 API 都会自动调用它。)

鼠标控制

函数	签名	说明
move_to	`jm.move_to(x, y, opts?)`	将鼠标移动到绝对坐标；`opts` 支持 `{ duration?, speed? }`，可指定时长或速度，省略时立即移动
move_by	`jm.move_by(dx, dy, opts?)`	按相对位移移动鼠标；`opts` 支持 `{ duration?, speed? }`，可指定时长或速度，省略时立即移动
drag_to	`jm.drag_to(x, y, opts?)`	按住鼠标并拖拽到绝对坐标；`opts` 支持 `{ btn?, duration?, speed?, hold_before?, hold_after? }`
drag_by	`jm.drag_by(dx, dy, opts?)`	按住鼠标并按相对位移拖拽；`opts` 支持 `{ btn?, duration?, speed?, hold_before?, hold_after? }`
mouse_press	`jm.mouse_press(btn?)`	按下鼠标按钮；`btn` 支持 `left`、`right`、`middle`，默认 `left`
mouse_release	`jm.mouse_release(btn?)`	释放鼠标按钮；
mouse_click	`jm.mouse_click(opts?)`	鼠标点击；`opts` 为 `{ btn?, hold?, clicks?, interval? }`，支持单击/双击/三击等
scroll	`jm.scroll(length, axis?)`	滚轮滚动，`axis` 支持 `vertical`、`horizontal`，默认纵向 `vertical`

jm.mouse_click()                           -- 左键快速点击
jm.mouse_click({ btn = "left", hold = 30 }) -- 左键按住 30ms 后释放
jm.mouse_click({ btn = "right" })          -- 右键快速点击
jm.mouse_click({ btn = "left", clicks = 2 }) -- 左键双击
jm.mouse_click({ btn = "left", clicks = 3, interval = 50 }) -- 左键三击
jm.drag_to(640, 360, { duration = 250 })   -- 左键平滑拖到目标位置
jm.drag_by(120, 40, { hold_before = 40 })  -- 左键按下后等待 40ms 再拖动

在某些系统或窗口环境下，过快的点击可能无法被正确识别。适当增加 hold 时长可以提升兼容性。

mouse_click 的 opts 支持字段：

字段	类型	说明
btn	`string`	鼠标按键，支持 `left`（默认）、`right`、`middle`
hold	`integer`	每次点击按住时长，单位毫秒
clicks	`integer`	点击次数，默认 `1`，可用于双击、三击等
interval	`integer`	多次点击之间的间隔，单位毫秒，默认 `40`

move_to / move_by 的 opts 支持字段：

字段	类型	说明
duration	`integer`	移动总时长，单位毫秒
speed	`number`	移动速度，单位 `px/second`，会按当前距离自动换算时长

当 duration 和 speed 同时存在时，优先使用 duration。

opts 必须传 table，不再接受旧的数字第三参数写法。

drag_to / drag_by 在此基础上额外支持：

字段	类型	说明
btn	`string`	拖拽按键，支持 `left`、`right`、`middle`，默认 `left`
hold_before	`integer`	按下后等待多久再开始移动，单位毫秒，默认 `20`
hold_after	`integer`	移动完成后等待多久再释放，单位毫秒，默认 `0`

键盘与文本输入

函数	签名	说明
key_press	`jm.key_press(key)`	按下指定键；非法键名会抛错
key_release	`jm.key_release(key)`	释放指定键
key_click	`jm.key_click(opts)`	单击指定键；支持字符串键名或 `{ key, hold? }`，`hold` 指定按住时长（毫秒）
hotkey	`jm.hotkey(key1, ...)`	热键组合；按传入顺序按下，再按相反顺序释放；默认键间隔 `10ms`，尾部可传 `{ interval = ms }`
write	`jm.write(opts)`	输入文本；支持直接传字符串，或 `{ text, interval? }` 控制逐字符间隔

jm.key_click("enter")
jm.key_click({ key = "space", hold = 40 })
jm.hotkey("ctrl", "c")
jm.hotkey("ctrl", "shift", "esc")
jm.hotkey("ctrl", "shift", "esc", { interval = 20 })
jm.write("hello")
jm.write({ text = "你好 world", interval = 40 })

键名列表与平台差异请参考键名列表。

并发任务

函数	签名	说明
fork	`jm.fork(fn, ...)`	启动异步子任务，返回 `task_id`
cancel_task	`jm.cancel_task(task_id)`	尝试取消运行中的任务，成功时返回 `true`
wait_task	`jm.wait_task(task_id, timeout_ms?)`	等待任务结束，返回两个值：`done` 和 `status`

wait_task 的返回语义如下：

返回结果	含义
`true, "completed"`	任务成功完成
`true, "cancelled"`	任务被取消
`false, "not_found"`	未找到对应任务
`false, "timeout"`	在给定超时时间内仍未结束
`false, err_msg`	任务执行失败，第二个返回值为错误信息

示例

local jm = require("jokymouse")

local monitor_task = jm.fork(function()
  while true do
    jm.ensure_running()
    jm.sleep(500)
  end
end)

jm.move_to(640, 360, { duration = 250 })
jm.move_by(80, 0, { speed = 720 })
jm.drag_to(820, 420, { duration = 300, hold_before = 30 })
jm.mouse_click({ btn = "left" })
jm.scroll(-240, "vertical")

local finished, status = jm.wait_task(monitor_task, 100)
if not finished and status == "timeout" then
  jm.cancel_task(monitor_task)
end

jm.exit()

系统平台、系统时间与窗口能力不在 jokymouse 内，单独放在 jokymouse.system API；提示框相关接口在 jokymouse.dialog API；调试输出请看 jokymouse.log API；屏幕尺寸、取色和找图能力在 jokymouse.screen API；文件读写请看 jokymouse.fs API；需要跨次运行保存轻量状态时请看 jokymouse.storage API。