Wingman

Appearance

API: UIA List ​

列表（List）控件显示可选择的项目集合，常用于：

  • 文件列表
  • 用户列表
  • 项目选择
  • 数据表格

查找列表 ​

说明：列表通常有名称或标题，可以通过名称查找。

函数签名：

python
find_by_name(name: str) -> UIElement | None
lua
find_by_name(name: string) -> UIElement | nil
python
from wingman import uia

# 查找名为"文件列表"的列表控件
list_box = uia.find_by_name("文件列表")
if list_box:
    print("找到列表控件")

遍历列表项 ​

获取所有列表项 ​

说明：使用 get_children() 获取列表中的所有项目。

返回：列表项元素数组

python
from wingman import uia

list_box = uia.find_by_name("文件列表")
if list_box:
    # 获取所有列表项
    items = list_box["get_children"]()
    print(f"共有 {len(items)} 个项目")

    # 遍历打印
    for i, item in enumerate(items):
        info = item["get_info"]()
        name = info.get('name', '(无名称)')
        print(f"  [{i}] {name}")

检查选中状态 ​

对列表容器调 get_selection() 可读取当前选中项（返回首个选中的列表元素；无选中返回 None/nil）：

python
from wingman import uia

list_box = uia.find_list("文件列表")
if list_box:
    selected = list_box["get_selection"]()
    if selected:
        print(f"当前选中: {selected['get_info']()['name']}")
    else:
        print("当前无选中项")

get_info() 返回键中仍无 is_selected 字段；判断具体某一项是否被选中，可对比 get_selection() 返回元素与目标项。

选择列表项 ​

点击选择 ​

说明：通过点击列表项来选中它。

python
from wingman import uia

list_box = uia.find_by_name("文件列表")
if list_box:
    items = list_box["get_children"]()

    # 点击第三个项目（索引从 0 开始）
    if len(items) > 2:
        items[2]["click"]()
        print("已点击第三个项目")

按名称查找并选择 ​

说明：直接按项目名称查找，然后点击选中。

python
from wingman import uia

# 直接按名称查找列表项
item = uia.find_by_name("目标文件.txt")
if item:
    item["click"]()
    print("已选中：目标文件.txt")
else:
    print("未找到目标文件")

双击列表项 ​

说明：双击列表项通常用于打开或执行该项目的操作。

使用场景：

  • 打开文件
  • 查看详情
  • 执行项目
python
from wingman import uia

list_box = uia.find_by_name("文件列表")
if list_box:
    items = list_box["get_children"]()

    # 双击打开项目
    if len(items) > 2:
        items[2]["double_click"]()
        print("已双击打开第三个项目")

可用接口 ​

查找列表 ​

Python 函数Lua 函数说明参数
find_by_name(name)find_by_name(name)按名称查找name - 列表名称
find_by_id(id)find_by_id(id)按 AutomationId 查找id - AutomationId

列表操作 ​

Python 方法Lua 方法说明
get_children():get_children()获取所有列表项
click():click()点击列表项
double_click():double_click()双击列表项
get_info():get_info()获取列表项信息

select() 编程选中列表项（2026-10-09 落地，不动鼠标）：

python
from wingman import uia

item = uia.find_list_item("目标文件.txt")
if item:
    item["select"]()

编程选中要求目标控件支持 SelectionItem 模式（Windows）/ 可设置 AXSelected（macOS）；不支持的控件返回 false，此时请回退用 click()。