jokymouse.system API

jokymouse.system 模块通过 require("jokymouse.system") 加载，提供平台识别、设备标识、系统时间与窗口检索能力。

local system = require("jokymouse.system")

可用函数

函数	签名	说明
platform	`system.platform()`	返回当前平台标识
deviceid	`system.deviceid()`	返回当前设备的稳定标识字符串
time	`system.time()`	返回当前毫秒时间戳
get_active_window	`system.get_active_window()`	返回当前前台窗口，找不到返回 `nil`
find_window	`system.find_window(opts?)`	查找第一个匹配窗口，找不到返回 `nil`
find_windows	`system.find_windows(opts?)`	查找全部匹配窗口，返回数组

get_active_window

local system = require("jokymouse.system")

local current = system.get_active_window()
if current then
  local info = current:info()
  print("active", info)
end

find_window / find_windows

opts 字段

字段	类型	默认值	说明
title	`string`	`nil`	标题匹配语法，默认全等且区分大小写
process_name	`string`	`nil`	进程名全等匹配，忽略大小写

title 匹配语法

settings 默认全等匹配，区分大小写
*settings 标题包含 settings
!settings 标题全等匹配，忽略大小写
!*settings 或 *!settings 标题包含匹配，忽略大小写

! 与 * 只在开头生效，顺序不限。

Window 对象

find_window 与 find_windows 返回 Window userdata。可用方法如下：

方法	签名	说明
exists	`win:exists()`	窗口是否仍然存在
info	`win:info()`	返回窗口信息 table

info 返回结构

{
  title = "窗口标题",
  process_name = "WeChat",
  process_path = "/Applications/WeChat.app/...",
  region = {
    x = 100,
    y = 120,
    width = 900,
    height = 680
  },
  is_active = true
}

示例

local jm = require("jokymouse")
local system = require("jokymouse.system")

local platform = system.platform()
local deviceid = system.deviceid()
local ts = system.time()
print("platform", platform)
print("deviceid", deviceid)
print("now", ts)

local win = system.find_window({
  title = "!*微信"
})

if not win then
  jm.panic("未找到目标窗口")
end

if not win:exists() then
  jm.panic("窗口已失效")
end

local info = win:info()
print(info)

平台说明

deviceid() 返回的是当前设备的稳定标识，适合做设备绑定、去重或本地缓存隔离，不应展示给普通用户做可读信息。
macOS：窗口信息读取依赖系统窗口查询能力，部分应用标题可能为空。
Linux：当前只支持 X11 会话；Wayland 会返回不支持错误。
Windows：窗口查询依赖 Win32 API，返回结果受系统窗口枚举规则影响。