控件别名

控件别名注册

小白向面板步骤说明见控件获取 — 所有操作 → 注册别名。

预先注册控件配置，后续用名字调用，适合流程编排和多步骤脚本：

auto.register('sessions',
    list_type='ListControl', list_aid='session_list',
    item_cls='ChatSessionCell',
    unread_pattern=r'\[(\d+)条\]', mute_keyword='消息免打扰')
auto.register('send_btn', ctrl_type='ButtonControl', name='发送')
auto.register('input_box', ctrl_type='EditControl', aid='chat_input')

# 通过别名操作
auto.click_cfg('send_btn')
auto.input_cfg('input_box', '你好')
auto.send_msg_cfg('input_box', '你好')   # 点击 + 输入 + 回车

# 链式代理（_AliasProxy）
auto.use('input_box').click().input('你好').enter()
auto.use('sessions').get_list()          # 同 get_list_cfg
auto.use('sessions').click_item('某会话', exact=True)
auto.use('sessions').get_unread()
auto.use('sessions').click_unread(index=0)

API 参考

控件别名（小白入门）

注册别名 = 给控件或列表起一个短名字，把「怎么查找」存进 WinAuto 内部字典；之后用 click_cfg('名字')、use('名字').input(...) 即可，不必重复写 aid / name / depth。

面板操作步骤（截图级说明）见控件获取 — 所有操作 → 注册别名。

两类注册

类型	register 示例	典型后续调用
单个控件	`auto.register('input_box', ctrl_type='EditControl', aid='chat_input')`	`input_cfg` / `click_cfg` / `use('input_box').input(...)`
列表	`auto.register('sessions', list_aid='session_list', item_cls='ChatSessionCell', ...)`	`get_list_cfg` / `click_list_cfg` / `use('sessions').click_item('名称')`

常用 API 对照

你想做的事	代码
注册	`auto.register('别名', aid='...', ...)`
看注册内容	`auto.cfg('别名')`
查找	`ctrl = auto.find_cfg('别名')`
点击	`auto.click_cfg('别名', mode='uia')`
输入	`auto.input_cfg('别名', '文字')`
输入并发送	`auto.send_msg_cfg('别名', '文字')`
读列表	`items = auto.get_list_cfg('别名')`
点列表里某一行	`auto.click_list_cfg('别名', '会话名')`
链式	`auto.use('别名').click().input('hi').enter()`

和直接 `find` 的对比

# 不用别名：每步都要写一长串（难维护）
auto.input('你好', ctrl_type='EditControl', aid='chat_input', depth=12)
auto.input('再见', ctrl_type='EditControl', aid='chat_input', depth=12)

# 用别名：注册一次，后面只写名字
auto.register('box', ctrl_type='EditControl', aid='chat_input', depth=12)
auto.input_cfg('box', '你好')
auto.input_cfg('box', '再见')

✨register

注册命名配置，供 *_cfg / use() 使用。

auto.register('input', ctrl_type='EditControl', aid='chat_input_field')
auto.register('sessions', list_type='ListControl', list_aid='session_list', item_cls='ChatSessionCell')

auto.click_cfg('send_btn')
auto.input_cfg('input', '你好')
auto.use('input').click().input('test').enter()
sessions = auto.use('sessions').get_list()

参数：

参数名	类型	默认值	描述
alias	str	无	别名名称
ctrl_type	str	''	UIA 类型名
name	str	''	`Name` 属性
aid	str	''	`AutomationId`
cls	str	''	`ClassName`
depth	int	10	搜索深度
**list_kw	—	—	列表相关参数（`list_type`、`list_aid` 等）

返回值：

类型：WinAuto

✨cfg

读取已注册别名的配置字典。

auto.register('input_box', ctrl_type='EditControl', aid='chat_input', depth=12)
print(auto.cfg('input_box'))

参数：

参数名	类型	默认值	描述
alias	str	无	已注册的别名

返回值：

类型：dict

✨find_cfg

按注册别名查找控件。

auto.register('input_box', ctrl_type='EditControl', aid='chat_input', depth=12)
ctrl = auto.find_cfg('input_box')
print(ctrl.Name if ctrl else '未找到')

参数：

参数名	类型	默认值	描述
alias	str	无	已注册的别名

返回值：

类型：Control | None

✨click_cfg

按注册配置点击。

auto.register('send_btn', ctrl_type='ButtonControl', name='发送', depth=12)
auto.click_cfg('send_btn', mode='uia')

参数：

参数名	类型	默认值	描述
alias	str	无	已注册的别名
mode	str	None	操作模式

返回值：

类型：WinAuto

✨input_cfg

按注册配置输入。

auto.register('input_box', ctrl_type='EditControl', aid='chat_input', depth=12)
auto.input_cfg('input_box', '你好', mode='uia')

参数：

参数名	类型	默认值	描述
alias	str	无	已注册的别名
text	str	无	要输入的文字
mode	str	None	操作模式

返回值：

类型：WinAuto

✨send_msg_cfg

按注册配置输入并发送。

auto.register('input_box', ctrl_type='EditControl', aid='chat_input', depth=12)
auto.send_msg_cfg('input_box', '你好', mode='uia')

参数：

参数名	类型	默认值	描述
alias	str	无	已注册的别名
text	str	无	要发送的文字
mode	str	None	操作模式

返回值：

类型：WinAuto

✨get_list_cfg

按注册配置获取列表项。

auto.register('sessions',
    list_type='ListControl', list_aid='session_list', item_cls='ChatSessionCell')
items = auto.get_list_cfg('sessions')
for it in items:
    print(it.get('name'), it.get('unread'))

参数：

参数名	类型	默认值	描述
alias	str	无	已注册的列表别名

返回值：

类型：list[dict]

✨click_list_cfg

按注册别名点击列表中的指定项。

auto.register('sessions', list_aid='session_list', item_cls='ChatSessionCell')
auto.click_list_cfg('sessions', '示例会话', mode='uia')

参数：

参数名	类型	默认值	描述
alias	str	无	已注册的列表别名
name	str	无	列表项名称
exact	bool	True	是否精确匹配
mode	str	None	操作模式

返回值：

类型：WinAuto

✨get_unread_cfg

按注册别名获取未读会话列表。

auto.register('sessions', list_aid='session_list', item_cls='ChatSessionCell')
unread = auto.get_unread_cfg('sessions')
print(len(unread), '个未读')

参数：

参数名	类型	默认值	描述
alias	str	无	已注册的列表别名
include_mute	bool	False	是否包含免打扰

返回值：

类型：list[dict]

✨click_unread_cfg

按注册别名点击第 N 个未读会话。

auto.register('sessions', list_aid='session_list', item_cls='ChatSessionCell')
item = auto.click_unread_cfg('sessions', index=0, mode='uia')
print(item)

参数：

参数名	类型	默认值	描述
alias	str	无	已注册的列表别名
index	int	0	未读索引（0=第一个）
include_mute	bool	False	是否包含免打扰
mode	str	None	操作模式

返回值：

类型：dict | None

✨use

返回 _AliasProxy 链式代理。

auto.register('input_box', ctrl_type='EditControl', aid='chat_input', depth=12)
auto.use('input_box').click(mode='uia').input('你好').enter()

auto.register('sessions', list_aid='session_list', item_cls='ChatSessionCell')
auto.use('sessions').click_item('示例会话').click_unread(0)

参数：

参数名	类型	默认值	描述
alias	str	无	已注册的别名

返回值：

类型：_AliasProxy

#控件别名

#控件别名注册

#API 参考

#控件别名（小白入门）

#两类注册

#常用 API 对照

#和直接 find 的对比

#✨register

#✨cfg

#✨find_cfg

#✨click_cfg

#✨input_cfg

#✨send_msg_cfg

#✨get_list_cfg

#✨click_list_cfg

#✨get_unread_cfg

#✨click_unread_cfg

#✨use

控件别名

控件别名注册

API 参考

控件别名（小白入门）

两类注册

常用 API 对照

和直接 `find` 的对比

✨register

✨cfg

✨find_cfg

✨click_cfg

✨input_cfg

✨send_msg_cfg

✨get_list_cfg

✨click_list_cfg

✨get_unread_cfg

✨click_unread_cfg

✨use