backend.context.context¶

context ¶

类：

名称	描述
`ContextGlobalVars`
`ContextStackVars`
`ContextOcr`
`ContextImage`
`ContextDevice`

函数：

名称	描述
`context`	用于标记 Context 类方法的装饰器。
`interruptible`	将函数包装为可中断函数。
`interruptible_class`	将类中的所有方法包装为可中断方法。
`sleep`	可中断和可暂停的 sleep 函数。
`warn_manual_screenshot_mode`	警告在手动截图模式下使用的方法。
`is_manual_screenshot_mode`	检查当前是否处于手动截图模式。
`check_flow_control`	统一的流程控制检查函数。
`rect_expand`	向四个方向扩展矩形区域。
`init_context`	初始化 Context 模块。
`manual_context`	默认情况下，Context* 类仅允许在 @task/@action 函数中使用。

属性：

名称	类型	描述
`device`	`ContextDevice`	当前正在执行任务的设备。
`input`	`InputManager`	当前正在执行任务的输入控制器。
`ocr`	`ContextOcr`	OCR 引擎。
`image`	`ContextImage`	图像识别。
`color`	`ContextColor`	颜色识别。
`vars`	`ContextGlobalVars`	全局变量。
`debug`	`ContextDebug`	调试工具。
`last_screenshot_time`	`float`	上一次截图的时间。

device `module-attribute` ¶

device: ContextDevice = cast(ContextDevice, Forwarded(name='device'))

当前正在执行任务的设备。

input `module-attribute` ¶

input: InputManager = cast(InputManager, Forwarded(name='input'))

当前正在执行任务的输入控制器。

ocr `module-attribute` ¶

ocr: ContextOcr = cast(ContextOcr, Forwarded(name='ocr'))

OCR 引擎。

image `module-attribute` ¶

image: ContextImage = cast(ContextImage, Forwarded(name='image'))

图像识别。

color `module-attribute` ¶

color: ContextColor = cast(ContextColor, Forwarded(name='color'))

颜色识别。

vars `module-attribute` ¶

vars: ContextGlobalVars = cast(ContextGlobalVars, Forwarded(name='vars'))

全局变量。

debug `module-attribute` ¶

debug: ContextDebug = cast(ContextDebug, Forwarded(name='debug'))

调试工具。

last_screenshot_time `module-attribute` ¶

last_screenshot_time: float = -1

上一次截图的时间。

ContextGlobalVars ¶

属性：

名称	类型	描述
`flow`	`FlowController`	流程控制器，负责停止、暂停、恢复等操作
`screenshot_data`	`MatLike \| None`	截图数据

flow `instance-attribute` ¶

flow: FlowController = FlowController()

流程控制器，负责停止、暂停、恢复等操作

screenshot_data `instance-attribute` ¶

screenshot_data: MatLike | None = None

截图数据

ContextStackVars ¶

属性：

名称	类型	描述
`screenshot_mode`	`ScreenshotMode`	截图模式。

screenshot_mode `instance-attribute` ¶

screenshot_mode: ScreenshotMode = 'auto'

截图模式。

auto 自动截图。即调用 color、image、ocr 上的方法时，会自动更新截图。
manual 完全手动截图，不自动截图。如果在没有截图数据的情况下调用 color 等的方法，会抛出异常。
~~manual-inherit~~：已废弃。

ContextOcr ¶

方法：

名称	描述
`raw`	返回 `kotonebot.backend.ocr` 中的 Ocr 对象。
`ocr`	OCR 当前设备画面或指定图像。
`find`	检查当前设备画面是否包含指定文本。
`expect`	检查当前设备画面是否包含指定文本。
`expect_wait`	等待指定文本出现。
`wait_for`	等待指定文本出现。

raw ¶

raw(lang: OcrLanguage | None = None) -> Ocr

返回 kotonebot.backend.ocr 中的 Ocr 对象。

Ocr 对象与此对象（ContextOcr）的区别是，此对象会自动截图，而 Ocr 对象需要手动传入图像参数。

ocr ¶

ocr(rect: Rect | None = None, lang: OcrLanguage | None = None) -> OcrResultList

OCR 当前设备画面或指定图像。

find ¶

find(pattern: str | Pattern | StringMatchFunction, *, hint: HintBox | None = None, rect: Rect | None = None, lang: OcrLanguage | None = None) -> OcrResult | None

检查当前设备画面是否包含指定文本。

expect ¶

expect(pattern: str | Pattern | StringMatchFunction, *, rect: Rect | None = None, hint: HintBox | None = None, lang: OcrLanguage | None = None) -> OcrResult

检查当前设备画面是否包含指定文本。

与 find() 的区别在于，expect() 未找到时会抛出异常。

expect_wait ¶

expect_wait(pattern: str | Pattern | StringMatchFunction, timeout: float = DEFAULT_TIMEOUT, *, interval: float = DEFAULT_INTERVAL, rect: Rect | None = None, hint: HintBox | None = None) -> OcrResult

等待指定文本出现。

wait_for ¶

wait_for(pattern: str | Pattern | StringMatchFunction, timeout: float = DEFAULT_TIMEOUT, *, interval: float = DEFAULT_INTERVAL, rect: Rect | None = None, hint: HintBox | None = None) -> OcrResult | None

等待指定文本出现。

ContextImage ¶

方法：

名称	描述
`wait_for`	等待指定图像出现。
`wait_for_any`	等待指定图像中的任意一个出现。
`expect_wait`	等待指定图像出现。
`expect_wait_any`	等待指定图像中的任意一个出现。

wait_for ¶

wait_for(template: MatLike | str | Image, mask: MatLike | str | None = None, threshold: float = 0.8, timeout: float = DEFAULT_TIMEOUT, colored: bool = False, *, rect: Rect | None = None, transparent: bool = False, interval: float = DEFAULT_INTERVAL, preprocessors: list[PreprocessorProtocol] | None = None) -> TemplateMatchResult | None

等待指定图像出现。

wait_for_any ¶

wait_for_any(templates: list[str | Image], masks: list[str | None] | None = None, threshold: float = 0.8, timeout: float = DEFAULT_TIMEOUT, colored: bool = False, *, rect: Rect | None = None, transparent: bool = False, interval: float = DEFAULT_INTERVAL, preprocessors: list[PreprocessorProtocol] | None = None)

等待指定图像中的任意一个出现。

expect_wait ¶

expect_wait(template: str | Image, mask: str | None = None, threshold: float = 0.8, timeout: float = DEFAULT_TIMEOUT, colored: bool = False, *, rect: Rect | None = None, transparent: bool = False, interval: float = DEFAULT_INTERVAL, preprocessors: list[PreprocessorProtocol] | None = None) -> TemplateMatchResult

等待指定图像出现。

expect_wait_any ¶

expect_wait_any(templates: list[str | Image], masks: list[str | None] | None = None, threshold: float = 0.8, timeout: float = DEFAULT_TIMEOUT, colored: bool = False, *, rect: Rect | None = None, transparent: bool = False, interval: float = DEFAULT_INTERVAL, preprocessors: list[PreprocessorProtocol] | None = None) -> TemplateMatchResult

等待指定图像中的任意一个出现。

ContextDevice ¶

Bases: Generic[T_Device], Device

方法：

名称	描述
`__init__`	:param device: 目标设备。
`screenshot`	截图。返回截图数据，同时更新当前上下文的截图数据。
`of_android`	确保此 ContextDevice 底层为 Android 平台。
`of_windows`	确保此 ContextDevice 底层为 Windows 平台。
`start`	启动设备并初始化组件。
`stop`	停止设备并清理组件。
`click_center`	点击屏幕中心。
`swipe`	滑动屏幕
`swipe_scaled`	滑动屏幕，参数为屏幕坐标的百分比。
`screenshot_raw`	截图，不调用任何 Hook。
`hook`	注册 Hook，在截图前将会调用此函数，对截图进行处理
`detect_orientation`	检测当前设备方向并设置 `self.orientation` 属性。

属性：

名称	类型	描述
`target_screenshot_interval`	`float \| None`	目标截图间隔，可用于限制截图速度。若两次截图实际间隔小于该值，则会自动等待。
`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)`。

target_screenshot_interval `instance-attribute` ¶

target_screenshot_interval: float | None = target_screenshot_interval

目标截图间隔，可用于限制截图速度。若两次截图实际间隔小于该值，则会自动等待。为 None 时不限制截图速度。

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，返回的分辨率仍然是真实分辨率。

init ¶

__init__(device: T_Device, target_screenshot_interval: float | None = None)

参数：

名称	类型	描述	默认
`device` ¶	`T_Device`	目标设备。	必需
`target_screenshot_interval` ¶	`float \| None`	见 `ContextDevice.target_screenshot_interval`。	`None`

screenshot ¶

screenshot(*, force: bool = False)

截图。返回截图数据，同时更新当前上下文的截图数据。

of_android ¶

of_android() -> ContextDevice | AndroidDevice

确保此 ContextDevice 底层为 Android 平台。同时通过返回的对象可以调用 Android 平台特有的方法。

of_windows ¶

of_windows() -> ContextDevice | WindowsDevice

确保此 ContextDevice 底层为 Windows 平台。同时通过返回的对象可以调用 Windows 平台特有的方法。

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_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。

context ¶

context(_: Callable[Concatenate[MatLike, P], T]) -> Callable[[Callable[Concatenate[ContextClass, P], T]], Callable[Concatenate[ContextClass, P], T]]

用于标记 Context 类方法的装饰器。此装饰器仅用于辅助类型标注，运行时无实际功能。

装饰器输入的函数类型为 (img: MatLike, a, b, c, ...) -> T，被装饰的函数类型为 (self: ContextClass, *args, **kwargs) -> T，结果类型为 (self: ContextClass, a, b, c, ...) -> T。

也就是说，@context 会把输入函数的第一个参数 img: MatLike 删除，然后再添加 self 作为第一个参数。

【例】

def find_image(
    img: MatLike,
    mask: MatLike,
    threshold: float = 0.9
) -> TemplateMatchResult | None:
    ...

class ContextImage:
    @context(find_image)
    def find_image(self, *args, **kwargs):
        return find_image(
            self.context.device.screenshot(),
            *args,
            **kwargs
        )

c = ContextImage()
c.find_image()
# 此函数类型推断为 (
#   self: ContextImage,
#   img: MatLike,
#   mask: MatLike,
#   threshold: float = 0.9
# ) -> TemplateMatchResult | None

interruptible ¶

interruptible(func: Callable[P, T]) -> Callable[P, T]

将函数包装为可中断函数。

在调用函数前，自动检查用户是否请求中断。如果用户请求中断，则抛出 KeyboardInterrupt 异常。

interruptible_class ¶

interruptible_class(cls: Type[T]) -> Type[T]

将类中的所有方法包装为可中断方法。

在调用方法前，自动检查用户是否请求中断。如果用户请求中断，则抛出 KeyboardInterrupt 异常。

sleep ¶

sleep(seconds: float)

可中断和可暂停的 sleep 函数。

建议使用本函数代替 time.sleep()，这样能以最快速度响应用户请求中断和暂停。

warn_manual_screenshot_mode ¶

warn_manual_screenshot_mode(name: str, alternative: str)

警告在手动截图模式下使用的方法。

is_manual_screenshot_mode ¶

is_manual_screenshot_mode() -> bool

检查当前是否处于手动截图模式。

check_flow_control ¶

check_flow_control()

统一的流程控制检查函数。

检查用户是否请求中断或暂停，如果是则相应处理： - 如果请求中断，抛出 KeyboardInterrupt 异常 - 如果请求暂停，等待直到恢复

rect_expand ¶

rect_expand(rect: Rect, left: int = 0, top: int = 0, right: int = 0, bottom: int = 0) -> Rect

向四个方向扩展矩形区域。

init_context ¶

init_context(*, force: bool = False, target_device: Device, target_screenshot_interval: float | None = None)

初始化 Context 模块。

参数：

名称	类型	描述	默认
`force` ¶	`bool`	是否强制重新初始化。若为 `True`，则忽略已存在的 Context 实例，并重新创建一个新的实例。	`False`
`target_device` ¶	`Device`	目标设备	必需
`target_screenshot_interval` ¶	`float \| None`	见 `ContextDevice.target_screenshot_interval`。	`None`

manual_context ¶

manual_context(screenshot_mode: ScreenshotMode = 'auto') -> ManualContextManager

默认情况下，Context* 类仅允许在 @task/@action 函数中使用。如果想要在其他地方使用，使用此函数手动创建一个上下文。

backend.context.context¶

context ¶

device module-attribute ¶

input module-attribute ¶

ocr module-attribute ¶

image module-attribute ¶

color module-attribute ¶

vars module-attribute ¶

debug module-attribute ¶

last_screenshot_time module-attribute ¶

ContextGlobalVars ¶

flow instance-attribute ¶

screenshot_data instance-attribute ¶

ContextStackVars ¶

screenshot_mode instance-attribute ¶

ContextOcr ¶

raw ¶

ocr ¶

find ¶

expect ¶

expect_wait ¶

wait_for ¶

ContextImage ¶

wait_for ¶

wait_for_any ¶

expect_wait ¶

expect_wait_any ¶

ContextDevice ¶

target_screenshot_interval instance-attribute ¶

screenshot_hook_after instance-attribute ¶

screenshot_hook_before instance-attribute ¶

click_hooks_before instance-attribute ¶

last_find instance-attribute ¶

orientation instance-attribute ¶

input instance-attribute ¶

platform instance-attribute ¶

log_level instance-attribute ¶

touch property ¶

screenshotable property ¶

multi_touch property ¶

screen_size property ¶

__init__ ¶

device ¶

target_screenshot_interval ¶

screenshot ¶

of_android ¶

of_windows ¶

start ¶

stop ¶

__log ¶

message ¶

level ¶

click_center ¶

swipe ¶

swipe_scaled ¶

x1 ¶

y1 ¶

x2 ¶

y2 ¶

duration ¶

screenshot_raw ¶

hook ¶

detect_orientation ¶

context ¶

interruptible ¶

interruptible_class ¶

sleep ¶

warn_manual_screenshot_mode ¶

is_manual_screenshot_mode ¶

check_flow_control ¶

rect_expand ¶

init_context ¶

force ¶

target_device ¶

target_screenshot_interval ¶

manual_context ¶

device `module-attribute` ¶

input `module-attribute` ¶

ocr `module-attribute` ¶

image `module-attribute` ¶

color `module-attribute` ¶

vars `module-attribute` ¶

debug `module-attribute` ¶

last_screenshot_time `module-attribute` ¶

flow `instance-attribute` ¶

screenshot_data `instance-attribute` ¶

screenshot_mode `instance-attribute` ¶

target_screenshot_interval `instance-attribute` ¶

screenshot_hook_after `instance-attribute` ¶

screenshot_hook_before `instance-attribute` ¶

click_hooks_before `instance-attribute` ¶

last_find `instance-attribute` ¶

orientation `instance-attribute` ¶

input `instance-attribute` ¶

platform `instance-attribute` ¶

log_level `instance-attribute` ¶

touch `property` ¶

screenshotable `property` ¶

multi_touch `property` ¶

screen_size `property` ¶

init ¶

`device` ¶

`target_screenshot_interval` ¶

`message` ¶

`level` ¶

`x1` ¶

`y1` ¶

`x2` ¶

`y2` ¶

`duration` ¶

`force` ¶

`target_device` ¶

`target_screenshot_interval` ¶