본문으로 건너뛰기

UI 상태 캡처 (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보다 낮거나, UI 상태 캡처 기능이 없으면 호출 즉시 XXTouch를 업데이트한 후 capture_ui_state를 사용하라는 안내가 표시되며 상태 객체는 생성되지 않습니다.

매개변수​

  • options.hit_test_spacing: 선택 사항인 양의 정수로, 화면 샘플링 간격을 나타내며, 기본값은 40입니다.
  • options.force_hit_test: 선택 사항인 부울 값으로, 화면 샘플링 적중을 강제로 적용할지 여부를 나타내며, 기본값은 false입니다.

반환 값​

UI 상태 객체를 반환합니다. 생성 시 즉시 현재의 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로 표시됩니다.