メインコンテンツへ移動

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 アーカイブを 1 度生成します。以降の保存やログ書き込みでは、このキャッシュ済みバイト列を再利用し、再取得は行いません。

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、1 辺あたり最大 16384 ピクセル、合計最大 1,200 万ピクセルです。要素 JSON は最大 4 MiB、最大 5000 ノード、深度インデックスは最大 32 です。個別の上限を超えた項目は unavailable としてマークされます。