jokymouse API

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

local jm = require("jokymouse")

一般功能

函数	签名	说明
platform	`jm.platform()`	返回当前平台标识
app_version	`jm.app_version()`	返回当前小丑鼠版本号
mouse_position	`jm.mouse_position()`	返回当前鼠标坐标两个值

生命周期与设置

函数	签名	说明
settings	`jm.settings()`	返回包含全部 settings 的 Lua table
sleep	`jm.sleep(ms)`	异步休眠，不阻塞线程
exit	`jm.exit(errmsg?)`	退出脚本，如果提供 `errmsg`，则弹窗提示

并发任务

函数	签名	说明
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`	任务执行失败，第二个返回值为错误信息

鼠标控制

函数	签名	说明
move_to	`jm.move_to(x, y, duration_ms?)`	将鼠标移动到绝对坐标；`duration_ms` 以毫秒传入，省略时立即移动
move_by	`jm.move_by(dx, dy, duration_ms?)`	按相对位移移动鼠标；`duration_ms` 以毫秒传入，省略时立即移动
mouse_press	`jm.mouse_press(btn?)`	按下鼠标按钮；`btn` 支持 `left`、`right`、`middle`，默认 `left`
mouse_release	`jm.mouse_release(btn?)`	释放鼠标按钮；
mouse_click	`jm.mouse_click(btn?)`	单击鼠标按钮；
scroll	`jm.scroll(length, axis?)`	滚轮滚动，`axis` 支持 `vertical`、`horizontal`，默认纵向 `vertical`

键盘与文本输入

函数	签名	说明
key_press	`jm.key_press(key)`	按下指定键；非法键名会抛错
key_release	`jm.key_release(key)`	释放指定键
key_click	`jm.key_click(key)`	单击指定键
write	`jm.write(text)`	直接输入一段文本

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

示例

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, 250)
jm.move_by(80, 0, 120)
jm.mouse_click("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。