控件查找器

from ascript.ios.node import Selector

控件查找器,通过约束方法,和查询方法,来获取屏幕中满足条件的控件.

坐标与等待

控件查找器里的 xy 使用屏幕物理像素坐标；find(timeout=...) 和 find_all(timeout=...) 的 timeout 单位是毫秒。不传或传 0 时只查一次，不会默认等待。

方法

常量

匹配模式：

常量	值	说明
`Selector.MODE_EQUAL`	0	完全相等
`Selector.MODE_CONTAINS`	1	包含
`Selector.MODE_MATCHES`	2	正则匹配
`Selector.MODE_GREATER`	3	大于
`Selector.MODE_LESS`	4	小于
`Selector.MODE_TRAIT`	5	AX traits 位包含

查找模式：

常量	说明
`Selector.SIMPLE`	默认智能模式，日常推荐，速度快
`Selector.POINT`	点探测模式，只取指定坐标所在窗口/控件
`Selector.COMPLEX`	复杂模式，多窗口合并，适合浮层和跨进程场景，速度较慢
`Selector.VISIBLE`	可见控件模式，适合大列表快速检索

动作模式：

常量	说明
`Selector.MODE_CLICK_ACCESS`	走无障碍点击
`Selector.MODE_CLICK_XY`	点击控件中心坐标，默认
`Selector.MODE_SCROLL_VISIBLE`	滚动到可见
`Selector.MODE_SCROLL_LEFT` / `RIGHT` / `UP` / `DOWN`	指定方向滚动

创建查找器

创建一个控件查找器

函数

#class
Selector(mode=Selector.SIMPLE, xy=None, maxDepth=0, maxChildren=30, step=0)

参数

参数	类型	是否必填	说明
mode	int/str	否	查找模式，默认 `Selector.SIMPLE`
xy	tuple	否	`POINT` 模式使用的坐标，如 `(100, 200)`
maxDepth	int	否	控件树最大深度，`0` 表示不限
maxChildren	int	否	每个节点最多取多少个子节点，默认30；传0表示不限
step	int	否	`VISIBLE` 模式网格探测步长，0表示使用默认值

示例

from ascript.ios.node import Selector
# 创建一个选择器
selector = Selector()

# 点探测：直接查坐标所在控件
node = Selector(Selector.POINT, xy=(300, 600)).find()

# 大列表：可见控件模式更快
items = Selector(Selector.VISIBLE).type("XCUIElementTypeCell").find_all()

查找一个控件

查找控件,返回一个满足条件的控件

函数

#class
Selector().find(timeout=None)

参数

参数	类型	是否必填	说明
timeout	int	否	等待控件出现的最长时间，单位毫秒。不传或0为单次查找

返回值

Node 控件对象

示例

#案例:查找出符合条件的第一个控件
from ascript.ios.node import Selector
node =  Selector().find()

if node:
    #找到了控件
    print(node)
    #打印控件属性,耗时操作
    print(node.info)
else:
    print('没有找到任何控件')

# 最多等待 3 秒
from ascript.ios.node import Selector
node = Selector().label("登录").find(timeout=3000)

查找所有控件

查找控件,返回满足条件的控件

函数

#class
Selector().find_all(timeout=None)

参数

参数	类型	是否必填	说明
timeout	int	否	等待至少一个控件出现的最长时间，单位毫秒。不传或0为单次查找

返回值

Node[] 控件对象列表

示例

#案例:查找出所有符合条件的控件
from ascript.ios.node import Selector
nodes =  Selector().find_all()

if nodes:
    #找到了一组控件
    print( len(nodes) )
else:
    print('没有找到任何控件')

获取所有控件xml信息

该方法一般不推荐使用

xml信息获取非常耗时,效率远低于xpath约束,或属性约束.

函数

Selector.xml()

返回值

当前app xml 控件树信息

示例

# 获取当前应用的 xml控件树信息. 控件越多,速度越慢.
from ascript.ios.node import Selector
xml_info = Selector.xml()
print(xml_info)

xpath约束

通过xpath检索控件

xpath约束使用后,属性约束,和关系约束将不再生效.

函数

Selector().xpath(value:str)

参数

参数	类型	是否必填	说明
value	str	是	xpath数据,xpath语法快速入门视频教程

示例

# 找到 属性名name 值为 开发者的控件
from ascript.ios.node import Selector
node =  Selector().xpath("//*[@name='开发者']").find()
if node:
    #找到了控件
    print(node)
    #打印控件属性,比较耗时
    print(node.info)
else:
    print('没有找到任何控件')

属性约束

标签 label

通过 label 检索控件

label一般指显示在屏幕中的文字

函数

Selector().label(value:str,mode=0)

参数

参数	类型	是否必填	说明
value	str	是	控件label值
mode	int	是	匹配模式默认0:完全相同 1:包含在其中

返回值

Selector 返回控件查找器,用于链式编程

示例

# 查找label值“等于”Ascript文本的控件
from ascript.ios.node import Selector
node =  Selector().label("Keep").find()
if node:
    #找到了控件
    print(node)
    #打印控件属性,比较耗时
    print(node.info)
else:
    print('没有找到任何控件')

# 查找label值 “包含 ”Ascript文本的控件
from ascript.ios.node import Selector
node =  Selector().label("Kee",1).find()
if node:
    #找到了控件
    print(node)
    #打印控件属性,比较耗时
    print(node.info)
else:
    print('没有找到任何控件')

值 value

通过 value 检索控件

value 一般指控件的附加值,可通过控件查看器查找.

函数

Selector().value(value:str,mode=0)

参数

参数	类型	是否必填	说明
val	str	是	控件value值
mode	int	是	匹配模式默认0:完全相同 1:包含在其中

返回值

Selector 返回控件查找器,用于链式编程

示例

# 查找value值“等于”Ascript文本的控件
from ascript.ios.node import Selector
node =  Selector().value("在iCloud中").find()

if node:
    #找到了控件
    print(node)
    #打印控件所有属性,较为耗时
    print(node.info)
else:
    print('没有找到任何控件')

# 查找value值“包含”Ascript文本的控件
from ascript.ios.node import Selector
node =  Selector().value("iCloud",Selector.MODE_CONTAINS).find()

if node:
    #找到了控件
    print(node)
    #打印控件所有属性,较为耗时
    print(node.info)
else:
    print('没有找到任何控件')

名称 name

通过 name 检索控件

name 一般指控件的名称属性.

函数

Selector().name(value:str,mode=0)

参数

参数	类型	是否必填	说明
val	str	是	控件value值
mode	int	是	匹配模式默认0:完全相同 1:包含在其中

返回值

Selector 返回控件查找器,用于链式编程

示例

# 查找name值“等于”Ascript文本的控件
from ascript.ios.node import Selector
node =  Selector().value("name").find()

if node:
    #找到了控件
    print(node)
    #打印控件所有属性,较为耗时
    print(node.info)
else:
    print('没有找到任何控件')

# 查找name值“包含”Ascript文本的控件
from ascript.ios.node import Selector
node =  Selector().name("iCloud",Selector.MODE_CONTAINS).find()

if node:
    #找到了控件
    print(node)
    #打印控件所有属性,较为耗时
    print(node.info)
else:
    print('没有找到任何控件')

类型 type

通过 type 检索控件

函数

Selector().type(value:str,mode=0)

参数

参数	类型	是否必填	说明
value	str	是	控件type值
mode	int	是	匹配模式默认0:完全相同 1:包含在其中

返回值

Selector 返回控件查找器,用于链式编程

示例

# 查找value值等于Ascript文本的控件
from ascript.ios.node import Selector
node =  Selector().type("XCUIElementTypeWindow").find()

if node:
    #找到了控件
    print(node)
    #打印控件所有属性,较为耗时
    print(node.info)
else:
    print('没有找到任何控件')

标题 title

通过 title 检索控件。

函数

Selector().title(value: str, mode=0)

示例

from ascript.ios.node import Selector
node = Selector().title("完成", Selector.MODE_CONTAINS).find()
print(node)

无障碍特征 trait

通过 iOS AX traits 位检索控件，支持常用名称如 button、link、image、selected、statictext、disabled、header 等。

函数

Selector().trait(value)

示例

from ascript.ios.node import Selector

# 查找按钮控件
btn = Selector().trait("button").find()

子控件数量 childCount

按控件的子节点数量过滤。

函数

Selector().childCount(value, mode=Selector.MODE_EQUAL)

示例

from ascript.ios.node import Selector

# 查找至少有 3 个子控件的节点
node = Selector().childCount(3, Selector.MODE_GREATER).find()

是否可访问 enabled

通过 enabled 检索控件

该方法推荐,和其他约束联合调用,否则速度会比较慢

函数

Selector().enabled(value:bool)

参数

参数	类型	是否必填	说明
value	bool	是	True:可访问, False:不可访问

返回值

Selector 返回控件查找器,用于链式编程

示例

# 查找value值等于Ascript文本的控件
from ascript.ios.node import Selector
node =  Selector().enabled(True).find()

if node:
    #找到了控件
    print(node)
    #打印控件所有属性,较为耗时
    print(node.info)
else:
    print('没有找到任何控件')

是否被选中 selected

通过 selected 检索控件。

from ascript.ios.node import Selector
node = Selector().selected(True).find()

是否获得焦点 focused

通过 focused 检索控件。

from ascript.ios.node import Selector
node = Selector().focused(True).find()

是否显示 visible

通过 visible 检索控件

该方法推荐,和其他约束联合调用,否则速度会比较慢

函数

Selector().visible(value:bool)

参数

参数	类型	是否必填	说明
value	bool	是	True:显示在页面的控件, False:没有显示在页面上的控件

返回值

Selector 返回控件查找器,用于链式编程

示例

# 查找value值等于Ascript文本的控件
from ascript.ios.node import Selector
node =  Selector().visible(False).find()

if node:
    #找到了控件
    print(node)
    #打印控件所有属性,较为耗时
    print(node.info)
else:
    print('没有找到任何控件')

是否支持无障碍 accessible

通过 accessible 检索控件

检索该控件 accessible 属性

函数

Selector().accessible(value:bool)

参数

参数	类型	是否必填	说明
accessible	bool	是	True:显示在页面的控件, False:没有显示在页面上的控件

返回值

Selector 返回控件查找器,用于链式编程

示例

# 查找accessible值为False的控件
from ascript.ios.node import Selector
node =  Selector().accessible(False).find()

if node:
    #找到了控件
    print(node)
    #打印控件所有属性,较为耗时
    print(node.info)
else:
    print('没有找到任何控件')

绘制排序 index

通过 index 检索控件,当前层级的第几个控件

该方法推荐,和其他约束联合调用,否则速度会比较慢

函数

Selector().index(value:int, mode:int = 0)

参数

参数	类型	是否必填	说明
value	int	是	要获取当前层级的第几个控件
mode	int	否	默认 0:完全匹配. 3:大于,4:小于

返回值

Selector 返回控件查找器,用于链式编程

示例

# 查找 绘制排序层级为3的控件
from ascript.ios.node import Selector
node =  Selector().index(3).find()

if node:
    #找到了控件
    print(node)
    #打印控件所有属性,较为耗时
    print(node.info)
else:
    print('没有找到任何控件')

坐标 x

约束控件 x属性.

这里的控件属性是经过缩放的值.并非真实值

函数

Selector().x(value:int, mode: int = 0)

参数

参数	类型	是否必填	说明
value	int	是	x坐标的值
mode	int	否	默认 0:完全匹配. 1:包含,3:大于,4:小于

返回值

Selector 返回控件查找器,用于链式编程

示例

# 查找 坐标x属性为301的控件
from ascript.ios.node import Selector
node =  Selector().x(301).find()

if node:
    #找到了控件
    print(node)
    #打印控件所有属性,较为耗时
    print(node.info)
else:
    print('没有找到任何控件')

坐标 y

约束控件 y属性.

这里的控件属性是经过缩放的值.并非真实值

函数

Selector().x(value:int, mode: int = 0)

参数

参数	类型	是否必填	说明
value	int	是	y坐标的值
mode	int	否	默认 0:完全匹配. 1:包含,3:大于,4:小于

返回值

Selector 返回控件查找器,用于链式编程

示例

# 查找 坐标y属性为260的控件
from ascript.ios.node import Selector
node =  Selector().y(260).find()

if node:
    #找到了控件
    print(node)
    #打印控件所有属性,较为耗时
    print(node.info)
else:
    print('没有找到任何控件')

宽度 width

约束控件width属性.

这里的控件属性是经过缩放的值.并非真实值

函数

Selector().width(value:int, mode: int = 0)

参数

参数	类型	是否必填	说明
value	int	是	控件的宽度值
mode	int	否	默认 0:完全匹配. 1:包含,3:大于,4:小于

返回值

Selector 返回控件查找器,用于链式编程

示例

# 查找 宽度width属性为260的控件
from ascript.ios.node import Selector
node =  Selector().width(260).find()

if node:
    #找到了控件
    print(node)
    #打印控件所有属性,较为耗时
    print(node.info)
else:
    print('没有找到任何控件')

高度 height

约束控件height属性.

这里的控件属性是经过缩放的值.并非真实值

函数

Selector().height(value:int, mode: int = 0)

参数

参数	类型	是否必填	说明
value	int	是	控件的高度值
mode	int	否	默认 0:完全匹配. 1:包含,3:大于,4:小于

返回值

Selector 返回控件查找器,用于链式编程

示例

# 查找 高度height属性为260的控件
from ascript.ios.node import Selector
node =  Selector().height(260).find()

if node:
    #找到了控件
    print(node)
    #打印控件所有属性,较为耗时
    print(node.info)
else:
    print('没有找到任何控件')

关系检索

子元素 child

获取当前元素的子元素

函数

Selector().child(value:float = 0)

参数

参数	类型	是否必填	说明
value	float	否	默认0:获取所有子元素. 1:获取第一个孩子,-1:获取倒数第二个孩子. 可填写2,3,4等数字

返回值

Selector 返回控件查找器,用于链式编程

示例

# 获取类型为 XCUIElementTypeOther 的所有孩子
from ascript.ios.node import Selector
nodes =  Selector().type("XCUIElementTypeOther").child().find()
print(nodes)

父元素 parent

获取当前元素的父元素

函数

Selector().parent(value:int = 0)

参数

参数	类型	是否必填	说明
value	int	否	默认0:获取所有父辈元素. 1:获取爸爸元素,2:获取爷爷元素

返回值

Selector 返回控件查找器,用于链式编程

示例

# 获取类型为 XCUIElementTypeOther 的所有父辈元素
from ascript.ios.node import Selector
nodes =  Selector().type("XCUIElementTypeOther").parent().find()
print(nodes)

# 获取类型为 XCUIElementTypeOther 的爸爸元素
from ascript.ios.node import Selector
nodes =  Selector().type("XCUIElementTypeOther").parent(1).find()
print(nodes)

兄弟元素 brother

获取当前元素的兄弟元素

函数

Selector().brother(value:float = 0)

参数

参数	类型	是否必填	说明
value	float	否	默认0:默认获取所有兄弟,1:大哥元素,2:二哥元素,-1:老小元素,0.1:最近的哥,-0.1:最近的弟

返回值

Selector 返回控件查找器,用于链式编程

示例

# 获取类型为 XCUIElementTypeOther 的所有兄弟元素
from ascript.ios.node import Selector
nodes =  Selector().type("XCUIElementTypeOther").brother().find()
print(nodes)

# 获取类型为 XCUIElementTypeOther 最近的哥哥元素
from ascript.ios.node import Selector
nodes =  Selector().type("XCUIElementTypeOther").brother(0.1).find()
print(nodes)

# 获取类型为 XCUIElementTypeOther 兄弟中的老大
from ascript.ios.node import Selector
nodes =  Selector().type("XCUIElementTypeOther").brother(1).find()
print(nodes)

动作追加

点击 click

找到元素后,点击该控件

函数

Selector().?().click(mode=1)

参数

参数	类型	是否必填	说明
mode	int	否	默认1:坐标点击,0:无障碍点击

返回值

Selector 返回控件查找器,用于链式编程

示例

# 获取类型为 XCUIElementTypeOther 的控件,并点击它
from ascript.ios.node import Selector
nodes =  Selector().type("XCUIElementTypeOther").click().find()
print(nodes)

滑动 scroll

找到可滑动的控件,执行滑动操作

函数

Selector().?().scroll(mode=MODE_SCROLL_VISIBLE, distance: float = 1.0)

参数

参数	类型	是否必填	说明
mode	float	否	滑动模式默认"visible":滑动到显示为止,"left":左滑动,"right":右滑动,"up":上滑动,"down":下滑动
distance	float	否	滑动屏数,默认1.0:1屏

返回值

Selector 返回控件查找器,用于链式编程

示例

# 获取类型为 XCUIElementTypeOther 的控件,并向左滑动
from ascript.ios.node import Selector
nodes =  Selector().type("XCUIElementTypeOther").scroll("left").find()
print(nodes)

输入 input

找到可输入的控件,执行输入指令操作

函数

Selector().?().input(value)

参数

参数	类型	是否必填	说明
value	float	否	要输入的文字

返回值

Selector 返回控件查找器,用于链式编程

示例

# 获取类型为 XCUIElementTypeTextField 的控件,并向其中追加文字
from ascript.ios.node import Selector
node =  Selector().type("XCUIElementTypeTextField").input("自在老师").find()
print(node)

# 清空文字
from ascript.ios.node import Selector
node =  Selector().type("XCUIElementTypeTextField").input("").find()
print(node)

清除文字 clear_text

找到控件后,清空其文本内容

函数

Selector().?().clear_text()

返回值

Selector 返回控件查找器,用于链式编程

示例

from ascript.ios.node import Selector
node = Selector().type("XCUIElementTypeTextField").clear_text().find()
print(node)

过滤约束

包名过滤 package

仅在指定应用（bundle_id）时执行查找

函数

Selector().package(value, mode=0)

参数

参数	类型	是否必填	说明
value	str	是	应用的 bundle_id
mode	int	否	默认0:完全匹配,1:包含匹配

返回值

Selector 返回控件查找器,用于链式编程

示例

# 仅在微信中查找控件
from ascript.ios.node import Selector
node = Selector().package("com.tencent.xin").label("微信").find()
print(node)

NSPredicate 查询 predicate

通过 NSPredicate 表达式查询控件

函数

Selector().predicate(value)

参数

参数	类型	是否必填	说明
value	str	是	NSPredicate 表达式

返回值

Selector 返回控件查找器,用于链式编程

示例

from ascript.ios.node import Selector
node = Selector().predicate("label BEGINSWITH '设'").find()
print(node)

查找模式切换

mode / xy

构造后也可以通过 mode() 和 xy() 切换查找模式。

Selector().mode(m, xy=None)
Selector().xy(x, y=None)

示例

from ascript.ios.node import Selector

# 点探测模式，查找坐标所在控件
node = Selector().mode(Selector.POINT, xy=(300, 600)).find()

# 等价写法
node = Selector().mode(Selector.POINT).xy(300, 600).find()

Node.at

直接获取指定坐标所在控件。

from ascript.ios.node import Node

node = Node.at(300, 600)
if node:
    print(node.info)

控件查找器

方法​

常量​

创建查找器​

查找一个控件​

查找所有控件​

获取所有控件xml信息​

xpath约束​

属性约束​

标签 label​

值 value​

名称 name​

类型 type​

标题 title​

无障碍特征 trait​

子控件数量 childCount​

是否可访问 enabled​

是否被选中 selected​

是否获得焦点 focused​

是否显示 visible​

是否支持无障碍 accessible​

绘制排序 index​

坐标 x​

坐标 y​

宽度 width​

高度 height​

关系检索​

子元素 child​

父元素 parent​

兄弟元素 brother​

动作追加​

点击 click​

滑动 scroll​

输入 input​

清除文字 clear_text​

过滤约束​

包名过滤 package​

NSPredicate 查询 predicate​

查找模式切换​

mode / xy​

Node.at​

方法

常量

创建查找器

查找一个控件

查找所有控件

获取所有控件xml信息

xpath约束

属性约束

标签 label

值 value

名称 name

类型 type

标题 title

无障碍特征 trait

子控件数量 childCount

是否可访问 enabled

是否被选中 selected

是否获得焦点 focused

是否显示 visible

是否支持无障碍 accessible

绘制排序 index

坐标 x

坐标 y

宽度 width

高度 height

关系检索

子元素 child

父元素 parent

兄弟元素 brother

动作追加

点击 click

滑动 scroll

输入 input

清除文字 clear_text

过滤约束

包名过滤 package

NSPredicate 查询 predicate

查找模式切换

mode / xy

Node.at