client.device

device

类：

名称	描述
Device
AndroidDevice

Device

方法：

名称	描述
start	启动设备并初始化组件。
stop	停止设备并清理组件。
click_center	点击屏幕中心。
swipe	滑动屏幕
swipe_scaled	滑动屏幕，参数为屏幕坐标的百分比。
screenshot	截图
screenshot_raw	截图，不调用任何 Hook。
hook	注册 Hook，在截图前将会调用此函数，对截图进行处理
detect_orientation	检测当前设备方向并设置 self.orientation 属性。

属性：

名称	类型	描述
screenshot_hook_after	Callable[[MatLike], MatLike] | None	截图后调用的函数
screenshot_hook_before	Callable[[], MatLike | None] | None	截图前调用的函数。返回修改后的截图。
click_hooks_before	list[Callable[[int, int], tuple[int, int]]]	点击前调用的函数。返回修改后的点击坐标。
last_find	Rect | ClickableObjectProtocol | None	上次 image 对象或 ocr 对象的寻找结果
orientation	Literal['portrait', 'landscape']	设备当前方向。默认为竖屏。注意此属性并非用于检测设备方向。
input	InputManager	输入控制器接口，包含触摸、鼠标、键盘等输入方式。
platform	str	设备平台名称。
log_level	LogLevel	默认日志级别。
touch	Touchable	触摸接口。
screenshotable	Screenshotable	截图接口。
multi_touch	MultiTouchable	多点触控接口。
screen_size	tuple[int, int]	真实屏幕尺寸。格式为 (width, height)。

screenshot_hook_after instance-attribute

screenshot_hook_after: Callable[[MatLike], MatLike] | None = None

截图后调用的函数

screenshot_hook_before instance-attribute

screenshot_hook_before: Callable[[], MatLike | None] | None = None

截图前调用的函数。返回修改后的截图。

click_hooks_before instance-attribute

click_hooks_before: list[Callable[[int, int], tuple[int, int]]] = []

点击前调用的函数。返回修改后的点击坐标。

last_find instance-attribute

last_find: Rect | ClickableObjectProtocol | None = None

上次 image 对象或 ocr 对象的寻找结果

orientation instance-attribute

orientation: Literal['portrait', 'landscape'] = 'portrait'

设备当前方向。默认为竖屏。注意此属性并非用于检测设备方向。 如果需要检测设备方向，请使用 self.detect_orientation() 方法。

横屏时为 'landscape'，竖屏时为 'portrait'。

input instance-attribute

input: InputManager

输入控制器接口，包含触摸、鼠标、键盘等输入方式。

platform instance-attribute

platform: str = platform

设备平台名称。

log_level instance-attribute

log_level: LogLevel = 'debug'

默认日志级别。

touch property

touch: Touchable

触摸接口。

screenshotable property

screenshotable: Screenshotable

截图接口。

multi_touch property

multi_touch: MultiTouchable

多点触控接口。

引发：

类型	描述
CapabilityNotSupportedError	如果当前设备实现不支持多点触控，则抛出异常。

screen_size property

screen_size: tuple[int, int]

真实屏幕尺寸。格式为 (width, height)。

注意： 此属性返回的分辨率会随设备方向变化。 如果 self.orientation 为 landscape，则返回的分辨率是横屏下的分辨率， 否则返回竖屏下的分辨率。

self.orientation 属性默认为竖屏。如果需要自动检测， 调用 self.detect_orientation() 方法。 如果已知方向，也可以直接设置 self.orientation 属性。

即使设置了 self.target_resolution，返回的分辨率仍然是真实分辨率。

start

start() -> None

启动设备并初始化组件。

引发：

类型	描述
DeviceAlreadyStartedError	如果设备生命周期已经启动，则抛出异常。

stop

stop() -> None

停止设备并清理组件。

如果设备生命周期未启动，则此方法不会执行任何操作。

__log

__log(message: str, level: LogLevel | None = None, *args)

以指定的日志级别输出日志。

参数：

名称	类型	描述	默认
message	str	要输出的日志信息。	必需
level	LogLevel | None	要使用的日志级别。可以是 'info', 'debug', 'verbose', 'silent' 中的一个，或者是 None。 如果为 None，则使用实例的 log_level 属性。	None

click_center

click_center(*, log: LogLevel | None = None) -> None

点击屏幕中心。

此方法会受到 self.orientation 的影响。 调用前确保 orientation 属性与设备方向一致， 否则点击位置会不正确。

swipe

swipe(x1: int, y1: int, x2: int, y2: int, duration: float | None = None, *, log: LogLevel | None = None) -> None

滑动屏幕

swipe_scaled

swipe_scaled(x1: float, y1: float, x2: float, y2: float, duration: float | None = None, *, log: LogLevel | None = None) -> None

滑动屏幕，参数为屏幕坐标的百分比。

如果设置了 self.target_resolution，则参数为逻辑坐标百分比。 否则为真实坐标百分比。

参数：

名称	类型	描述	默认
x1	float	起始点 x 坐标百分比。范围 [0, 1]	必需
y1	float	起始点 y 坐标百分比。范围 [0, 1]	必需
x2	float	结束点 x 坐标百分比。范围 [0, 1]	必需
y2	float	结束点 y 坐标百分比。范围 [0, 1]	必需
duration	float | None	滑动持续时间，单位秒。None 表示使用默认值。	None

screenshot

screenshot() -> MatLike

截图

screenshot_raw

screenshot_raw() -> MatLike

截图，不调用任何 Hook。

hook

hook(func: Callable[[MatLike], MatLike]) -> HookContextManager

注册 Hook，在截图前将会调用此函数，对截图进行处理

detect_orientation

detect_orientation() -> Literal['portrait', 'landscape'] | None

检测当前设备方向并设置 self.orientation 属性。

返回：

类型	描述
Literal['portrait', 'landscape'] | None	检测到的方向，如果无法检测到则返回 None。

AndroidDevice

Bases: Device

方法：

名称	描述
current_package	获取前台 APP 的包名。
launch_app	根据包名启动 app
start	启动设备并初始化组件。
stop	停止设备并清理组件。
click_center	点击屏幕中心。
swipe	滑动屏幕
swipe_scaled	滑动屏幕，参数为屏幕坐标的百分比。
screenshot	截图
screenshot_raw	截图，不调用任何 Hook。
hook	注册 Hook，在截图前将会调用此函数，对截图进行处理
detect_orientation	检测当前设备方向并设置 self.orientation 属性。

属性：

名称	类型	描述
screenshot_hook_after	Callable[[MatLike], MatLike] | None	截图后调用的函数
screenshot_hook_before	Callable[[], MatLike | None] | None	截图前调用的函数。返回修改后的截图。
click_hooks_before	list[Callable[[int, int], tuple[int, int]]]	点击前调用的函数。返回修改后的点击坐标。
last_find	Rect | ClickableObjectProtocol | None	上次 image 对象或 ocr 对象的寻找结果
orientation	Literal['portrait', 'landscape']	设备当前方向。默认为竖屏。注意此属性并非用于检测设备方向。
input	InputManager	输入控制器接口，包含触摸、鼠标、键盘等输入方式。
platform	str	设备平台名称。
log_level	LogLevel	默认日志级别。
touch	Touchable	触摸接口。
screenshotable	Screenshotable	截图接口。
multi_touch	MultiTouchable	多点触控接口。
screen_size	tuple[int, int]	真实屏幕尺寸。格式为 (width, height)。

screenshot_hook_after instance-attribute

screenshot_hook_after: Callable[[MatLike], MatLike] | None = None

截图后调用的函数

screenshot_hook_before instance-attribute

screenshot_hook_before: Callable[[], MatLike | None] | None = None

截图前调用的函数。返回修改后的截图。

click_hooks_before instance-attribute

click_hooks_before: list[Callable[[int, int], tuple[int, int]]] = []

点击前调用的函数。返回修改后的点击坐标。

last_find instance-attribute

last_find: Rect | ClickableObjectProtocol | None = None

上次 image 对象或 ocr 对象的寻找结果

orientation instance-attribute

orientation: Literal['portrait', 'landscape'] = 'portrait'

设备当前方向。默认为竖屏。注意此属性并非用于检测设备方向。 如果需要检测设备方向，请使用 self.detect_orientation() 方法。

横屏时为 'landscape'，竖屏时为 'portrait'。

input instance-attribute

input: InputManager

输入控制器接口，包含触摸、鼠标、键盘等输入方式。

platform instance-attribute

platform: str = platform

设备平台名称。

log_level instance-attribute

log_level: LogLevel = 'debug'

默认日志级别。

touch property

touch: Touchable

触摸接口。

screenshotable property

screenshotable: Screenshotable

截图接口。

multi_touch property

multi_touch: MultiTouchable

多点触控接口。

引发：

类型	描述
CapabilityNotSupportedError	如果当前设备实现不支持多点触控，则抛出异常。

screen_size property

screen_size: tuple[int, int]

真实屏幕尺寸。格式为 (width, height)。

注意： 此属性返回的分辨率会随设备方向变化。 如果 self.orientation 为 landscape，则返回的分辨率是横屏下的分辨率， 否则返回竖屏下的分辨率。

self.orientation 属性默认为竖屏。如果需要自动检测， 调用 self.detect_orientation() 方法。 如果已知方向，也可以直接设置 self.orientation 属性。

即使设置了 self.target_resolution，返回的分辨率仍然是真实分辨率。

current_package

current_package() -> str | None

获取前台 APP 的包名。

返回：

类型	描述
str | None	前台 APP 的包名。如果获取失败，则返回 None。

引发：

类型	描述
NotImplementedError	如果设备不支持此功能。

launch_app

launch_app(package_name: str) -> None

根据包名启动 app

start

start() -> None

启动设备并初始化组件。

引发：

类型	描述
DeviceAlreadyStartedError	如果设备生命周期已经启动，则抛出异常。

stop

stop() -> None

停止设备并清理组件。

如果设备生命周期未启动，则此方法不会执行任何操作。

__log

__log(message: str, level: LogLevel | None = None, *args)

以指定的日志级别输出日志。

参数：

名称	类型	描述	默认
message	str	要输出的日志信息。	必需
level	LogLevel | None	要使用的日志级别。可以是 'info', 'debug', 'verbose', 'silent' 中的一个，或者是 None。 如果为 None，则使用实例的 log_level 属性。	None

click_center

click_center(*, log: LogLevel | None = None) -> None

点击屏幕中心。

此方法会受到 self.orientation 的影响。 调用前确保 orientation 属性与设备方向一致， 否则点击位置会不正确。

swipe

swipe(x1: int, y1: int, x2: int, y2: int, duration: float | None = None, *, log: LogLevel | None = None) -> None

滑动屏幕

swipe_scaled

swipe_scaled(x1: float, y1: float, x2: float, y2: float, duration: float | None = None, *, log: LogLevel | None = None) -> None

滑动屏幕，参数为屏幕坐标的百分比。

如果设置了 self.target_resolution，则参数为逻辑坐标百分比。 否则为真实坐标百分比。

参数：

名称	类型	描述	默认
x1	float	起始点 x 坐标百分比。范围 [0, 1]	必需
y1	float	起始点 y 坐标百分比。范围 [0, 1]	必需
x2	float	结束点 x 坐标百分比。范围 [0, 1]	必需
y2	float	结束点 y 坐标百分比。范围 [0, 1]	必需
duration	float | None	滑动持续时间，单位秒。None 表示使用默认值。	None

screenshot

screenshot() -> MatLike

截图

screenshot_raw

screenshot_raw() -> MatLike

截图，不调用任何 Hook。

hook

hook(func: Callable[[MatLike], MatLike]) -> HookContextManager

注册 Hook，在截图前将会调用此函数，对截图进行处理

detect_orientation

detect_orientation() -> Literal['portrait', 'landscape'] | None

检测当前设备方向并设置 self.orientation 属性。

返回：

类型	描述
Literal['portrait', 'landscape'] | None	检测到的方向，如果无法检测到则返回 None。