跳到主要内容

# 抓取界面状态 (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`。