跳到主要内容

抓取界面状态 (LCC.capture_ui_state)

声明​

local state = LCC.capture_ui_state(options)

使用要求​

LCC.capture_ui_state 依赖 ui_element 模块，要求 ui_element._VERSION 不低于 0.6.0。如果设备无法加载该模块、模块没有有效版本号、版本低于 0.6.0，或缺少界面状态抓取能力，调用会直接提示更新 XXTouch 后再使用 capture_ui_state，不会创建部分状态对象。

参数​

  • options.hit_test_spacing：可选正整数，屏幕采样命中间距，默认 40。
  • options.force_hit_test：可选布尔值，是否强制执行屏幕采样命中，默认 false。

返回值​

返回界面状态对象。创建时立即抓取当前 PNG 截图和原始文本元素树，并生成一次 .xxtuie 归档；之后保存和写日志都复用这份缓存字节，不会重新抓取。

local state = LCC.capture_ui_state({
    hit_test_spacing = 40,
    force_hit_test = false,
})

local info = state:status()
local ok, err = state:save_to_file(XXT_SCRIPTS_PATH .. "/现场.xxtuie")
if not ok then
    error(err)
end

LCC.log(1, "现场", state)
state:destroy()

对象方法​

state:status()​

每次返回一份新的状态表，修改返回值不会影响对象内部状态。销毁对象后仍可查询。

  • status：complete、screenshot、elements 或 unavailable。
  • captured_at / capturedAt：开始抓取时的 UTC 时间。
  • screenshot.status：captured 或 unavailable，并包含 width、height；失败时还包含 error。
  • elements.status：captured 或 unavailable，并包含 count；失败时还包含 error。

state:save_to_file(path)​

把缓存归档原子写入指定路径，并覆盖已有文件。成功返回 true，失败返回 nil, err。路径和扩展名完全按调用方传入值使用；建议采用 .xxtuie，否则文件管理器可能无法自动识别。对象销毁后不能再保存。

state:destroy()​

释放缓存归档。该操作可重复调用；销毁后 status() 仍可使用，但保存和写日志会失败。

部分抓取失败​

通过版本与能力检查后，截图和文本元素树会独立抓取。任何一项运行时抓取失败，仍返回固定包含 manifest.json、screenshot.png 和 elements.json 的合法归档：失败的截图使用 1×1 透明 PNG，失败的元素树使用空元素数组，错误摘要写入 Manifest。依赖不满足、参数非法、归档本身无法生成或超过 20 MiB 时，LCC.capture_ui_state() 会抛出错误。

截图原始 PNG 最大 16 MiB、单边最大 16384 像素、总像素最大 1200 万；元素 JSON 最大 4 MiB、最多 5000 个节点、最大深度索引为 32。超过单项限制会把该项标记为 unavailable。