Перейти к основному содержимому

Захват состояния интерфейса (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: для неудачного снимка используется прозрачный PNG 1×1, для неудачного дерева — пустой массив элементов, а краткое описание ошибки записывается в Manifest. При отсутствии зависимостей, недопустимых параметрах, невозможности создать архив или превышении 20 MiB LCC.capture_ui_state() выдаёт ошибку.

Исходный PNG снимка ограничен 16 MiB, 16384 пикселями по каждой стороне и 12 миллионами пикселей всего; JSON элементов — 4 MiB, 5000 узлами и максимальным индексом глубины 32. При превышении отдельного ограничения соответствующий компонент помечается как unavailable.