Passer au contenu principal

Capturer l'état de l'interface (LCC.capture_ui_state)

Déclaration​

local state = LCC.capture_ui_state(options)

Conditions d'utilisation​

LCC.capture_ui_state dépend du module ui_element et exige que ui_element._VERSION soit au moins 0.6.0. Si l'appareil ne peut pas charger le module, si celui-ci n'a pas de numéro de version valide, si sa version est inférieure à 0.6.0 ou s'il ne fournit pas la capacité de capture d'état de l'interface, l'appel demande directement de mettre XXTouch à jour avant d'utiliser capture_ui_state et ne crée aucun objet d'état partiel.

Paramètres​

  • options.hit_test_spacing : entier positif facultatif, espacement des points de détection lors de l'échantillonnage de l'écran, 40 par défaut.
  • options.force_hit_test : booléen facultatif, indique s'il faut forcer la détection lors de l'échantillonnage de l'écran, false par défaut.

Valeur de retour​

Renvoie un objet représentant l'état de l'interface. Au moment de sa création, l'objet capture immédiatement une capture PNG actuelle et l'arbre brut des éléments textuels, puis génère une archive .xxtuie ; les opérations d'enregistrement et d'écriture du journal réutilisent ensuite ces octets mis en cache sans effectuer une nouvelle capture.

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

Méthodes de l'objet​

state:status()​

Chaque appel renvoie une nouvelle table d'état ; modifier la valeur renvoyée n'affecte pas l'état interne de l'objet. L'état peut encore être interrogé après la destruction de l'objet.

  • status : complete, screenshot, elements ou unavailable.
  • captured_at / capturedAt : heure UTC à laquelle la capture a commencé.
  • screenshot.status : captured ou unavailable, avec width et height ; en cas d'échec, contient également error.
  • elements.status : captured ou unavailable, avec count ; en cas d'échec, contient également error.

state:save_to_file(path)​

Écrit atomiquement l'archive mise en cache à l'emplacement indiqué et remplace le fichier existant. Renvoie true en cas de succès et nil, err en cas d'échec. Le chemin et l'extension sont utilisés exactement comme fournis par l'appelant ; .xxtuie est recommandé, faute de quoi le gestionnaire de fichiers pourrait ne pas reconnaître automatiquement le fichier. L'enregistrement n'est plus possible après la destruction de l'objet.

state:destroy()​

Libère l'archive mise en cache. L'opération peut être appelée plusieurs fois ; après la destruction, status() reste disponible, mais l'enregistrement et l'écriture du journal échouent.

Échec partiel de la capture​

Après les contrôles de version et de capacité, la capture d'écran et l'arbre des éléments textuels sont obtenus indépendamment. Si l'une des captures échoue à l'exécution, l'appel renvoie toujours une archive valide contenant exactement manifest.json, screenshot.png et elements.json : la capture échouée utilise un PNG transparent de 1×1, l'arbre échoué utilise un tableau d'éléments vide et le résumé de l'erreur est écrit dans le Manifest. Si la dépendance n'est pas satisfaite, si les paramètres sont invalides, si l'archive ne peut pas être générée ou si elle dépasse 20 MiB, LCC.capture_ui_state() lève une erreur.

Le PNG original de la capture est limité à 16 MiB, à 16384 pixels par côté et à 12 millions de pixels au total ; le JSON des éléments est limité à 4 MiB et à 5000 nœuds, avec un index de profondeur maximal de 32. Le dépassement d'une limite individuelle marque l'élément concerné comme unavailable.