ui.auto

用定位器完成常见桌面操作：等待控件、点击、输入、读取和截图。

版本 0.1.0 · Windows 专用 · 依赖 uia 与 opencv

快速开始

import ui.auto as uiauto

auto window = uiauto.test_window()
uiauto.Locator edit = uiauto.within(
    uiauto.by_class_name("Edit", "", 50004),
    window.hwnd()
)
assert uiauto.wait_exists(edit)
assert uiauto.type_text(edit, "hello")
println(uiauto.read(edit))
window.release()
uiauto.shutdown()

test_window() 是可重复验证用的自建窗口；面向已有应用时使用 within(locator, hwnd) 限定搜索范围。

接口

入口	用途
`by_automation_id / by_class_name / by_name / by_control_type / by_process_id`	构造定位器。
`uiauto.Locator`	导出的定位器类型，可用于参数和变量声明；`import ui.auto as uiauto`。
`within / with_timeout`	限定窗口与等待时间；五个定位操作先校验数值条件，再访问根窗口。缺失目标是正常的 false/空文本结果。
`locator_from_json`	读取定位信息；策略只接受 `automationId`、`classNameName`、`processClassPath`。前两种分别要求对应 ID 或类名，未知策略或缺少必要字段均报错；显式 `null` 不当作字段缺失。类路径沿 UIA Control View 的路径与序号精确匹配，并与其他条件取交集。
`wait_exists / click / type_text / read`	基础交互。
`screenshot(locator, path)`	将目标区域保存为图像；依赖 OpenCV 后端。

验证与边界

xl run examples/extlibs/ui_auto.xl
powershell -NoProfile -ExecutionPolicy Bypass -File extlibs/ui.auto/test/check.ps1 -SkipAot

2026-10-27 当前 Windows 发布版默认门禁通过自建窗口的成功/缺失/错误进程定位、定位器 JSON 往返、输入读取、内嵌 NUL 拒绝和真实 PNG 截图；JIT 与 AOT 均检查固定文字像素。另由独立 C 进程提供受控窗口，JIT/AOT 的 XLang 程序按进程 ID 完成定位、输入、读取、点击和截图；两份独立 PNG 均检查尺寸和文字像素，门禁结束后回收夹具进程。examples/extlibs/ui_auto_c.c 直接调用 UIA C API，与 XLang 公开范例同输出；extlibs/ui.auto/examples/screenshot_c.c 通过 UIA 和 OpenCV 的公开 C 接口截取目标控件，保存并回读 PNG，包级门禁同样检查尺寸和文字像素。上面的 -SkipAot 只运行 C/JIT 聚焦门禁。这里只验收 OpenCV 公开调用链，不承担桥接内部测试；UIA 上下文限定在创建线程使用，真实第三方桌面的权限、DPI/多屏、远程会话及长期事件处理仍未认证。