跳至主要內容

擷取介面狀態 (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。