Zum Hauptinhalt springen

UI-Zustand erfassen (LCC.capture_ui_state)

Deklaration​

local state = LCC.capture_ui_state(options)

Voraussetzungen​

LCC.capture_ui_state benötigt das Modul ui_element mit ui_element._VERSION ab 0.6.0. Kann das Gerät das Modul nicht laden, fehlt eine gültige Versionsnummer, ist die Version älter als 0.6.0 oder fehlt die UI-Zustandserfassung, fordert der Aufruf direkt zur Aktualisierung von XXTouch auf, bevor capture_ui_state verwendet wird; ein Teilobjekt wird nicht erstellt.

Parameter​

  • options.hit_test_spacing: optional positive Ganzzahl; Abstand der Bildschirmabtastung für Treffer, Standard 40.
  • options.force_hit_test: optionaler Boolean; ob die Trefferprüfung durch Bildschirmabtastung erzwungen wird, Standard false.

Rückgabewerte​

Gibt ein UI-Zustandsobjekt zurück. Beim Erstellen werden der aktuelle PNG-Screenshot und der rohe Textelementbaum sofort erfasst und einmalig als .xxtuie-Archiv gespeichert. Später verwenden Speichern und Protokollieren dieselben zwischengespeicherten Bytes, ohne erneut zu erfassen.

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()

Objektmethoden​

state:status()​

Jeder Aufruf gibt eine neue Statustabelle zurück; Änderungen am Rückgabewert beeinflussen den internen Zustand nicht. Sie kann auch nach dem Zerstören des Objekts abgefragt werden.

  • status: complete, screenshot, elements oder unavailable.
  • captured_at / capturedAt: UTC-Zeit, zu der die Erfassung begonnen hat.
  • screenshot.status: captured oder unavailable, einschließlich width und height; bei Fehlern zusätzlich error.
  • elements.status: captured oder unavailable, einschließlich count; bei Fehlern zusätzlich error.

state:save_to_file(path)​

Schreibt das zwischengespeicherte Archiv atomar in den angegebenen Pfad und ersetzt eine vorhandene Datei. Bei Erfolg wird true, bei Fehler nil, err zurückgegeben. Pfad und Erweiterung werden exakt wie übergeben verwendet; .xxtuie wird empfohlen, damit der Dateimanager die Datei automatisch erkennt. Nach dem Zerstören des Objekts ist Speichern nicht mehr möglich.

state:destroy()​

Gibt das zwischengespeicherte Archiv frei. Der Vorgang ist idempotent; nach dem Zerstören funktioniert status() weiterhin, Speichern und Protokollieren schlagen jedoch fehl.

Teilweise Erfassungsfehler​

Nach erfolgreicher Versions- und Fähigkeitsprüfung werden Screenshot und Textelementbaum unabhängig erfasst. Wenn eine Erfassung zur Laufzeit fehlschlägt, wird weiterhin ein gültiges Archiv mit genau manifest.json, screenshot.png und elements.json zurückgegeben: Ein fehlender Screenshot verwendet ein transparentes 1×1-PNG, ein fehlender Elementbaum ein leeres Elementarray, und die Manifest-Datei enthält eine kurze Fehlermeldung. Bei fehlender Abhängigkeit, ungültigen Parametern, nicht erstellbarem Archiv oder mehr als 20 MiB löst LCC.capture_ui_state() einen Fehler aus.

Das Original-PNG ist auf 16 MiB, 16384 Pixel je Seite und 12 Megapixel insgesamt begrenzt. Das Element-JSON ist auf 4 MiB, 5000 Knoten und einen Tiefenindex von 32 begrenzt. Bei Überschreitung einer Einzelgrenze wird der jeweils betroffene Bestandteil (Screenshot oder Elementbaum) als unavailable markiert.