屏幕画布
全屏透明画布，坐标使用物理像素（与截图/找图坐标一致），适合在屏幕上标记找图结果、调试坐标等。
from ascript.android.ui import Canvas
创建与显示
canvas = Canvas()
canvas.show()
show() 默认阻塞等待初始化完成（wait=True），确保后续绘制不会丢失。
| 参数 | 类型 | 必须 | 备注 |
|---|---|---|---|
| offset_y | int | 否 | Y轴偏移校准值（物理像素），默认自动使用状态栏高度 |
矩形
画矩形框，参数为左上角和右下角坐标。
Canvas.draw_rect(x1, y1, x2, y2, color="#ff00ff", stroke_width=2, duration=3000, label=None, font_size=12, id=None)
| 参数 | 类型 | 必须 | 备注 |
|---|---|---|---|
| x1, y1 | int | 是 | 左上角坐标（物理像素） |
| x2, y2 | int | 是 | 右下角坐标（物理像素） |
| color | str | 否 | 线条颜色 默认:#ff00ff |
| stroke_width | int | 否 | 线条宽度 默认:2 |
| duration | int | 否 | 显示时长(毫秒)，0为永久 默认:3000 |
| label | str | 否 | 矩形上方的标注文字 |
| font_size | int | 否 | 标注文字大小 默认:12 |
| id | str | 否 | 唯一标识，可用于更新或移除 |
-
返回值：
id（str） -
示例
from ascript.android.ui import Canvas
canvas = Canvas()
canvas.show()
# 画一个矩形框
canvas.draw_rect(100, 200, 400, 500, color="#ff00ff", duration=5000, label="目标区域")
圆
Canvas.draw_circle(x, y, radius, color="#00ff00", stroke_width=2, duration=3000, label=None, font_size=12, id=None)
| 参数 | 类型 | 必须 | 备注 |
|---|---|---|---|
| x, y | int | 是 | 圆心坐标（物理像素） |
| radius | int | 是 | 半径（物理像素） |
| color | str | 否 | 线条颜色 默认:#00ff00 |
| stroke_width | int | 否 | 线条宽度 默认:2 |
| duration | int | 否 | 显示时长(毫秒) 默认:3000 |
| label | str | 否 | 标注文字 |
| id | str | 否 | 唯一标识 |
- 示例
canvas.draw_circle(540, 960, 50, color="#00ff00", label="找到")
线
Canvas.draw_line(x1, y1, x2, y2, color="#65db79", stroke_width=1, duration=3000, id=None)
| 参数 | 类型 | 必须 | 备注 |
|---|---|---|---|
| x1, y1 | int | 是 | 起点坐标 |
| x2, y2 | int | 是 | 终点坐标 |
| color | str | 否 | 线条颜色 默认:#65db79 |
| stroke_width | int | 否 | 线条宽度 默认:1 |
| duration | int | 否 | 显示时长(毫秒) 默认:3000 |
| id | str | 否 | 唯一标识 |
文字
Canvas.draw_text(x, y, text, color="#ffffff", font_size=14, duration=3000, id=None)
| 参数 | 类型 | 必须 | 备注 |
|---|---|---|---|
| x, y | int | 是 | 文字位置坐标 |
| text | str | 是 | 文字内容 |
| color | str | 否 | 文字颜色 默认:#ffffff |
| font_size | int | 否 | 字体大小 默认:14 |
| duration | int | 否 | 显示时长(毫秒) 默认:3000 |
| id | str | 否 | 唯一标识 |
点
Canvas.draw_point(x, y, color="#ff0000", radius=5, duration=3000, id=None)
| 参数 | 类型 | 必须 | 备注 |
|---|---|---|---|
| x, y | int | 是 | 坐标 |
| color | str | 否 | 颜色 默认:#ff0000 |
| radius | int | 否 | 点的半径 默认:5 |
| duration | int | 否 | 显示时长(毫秒) 默认:3000 |
| id | str | 否 | 唯一标识 |
十字标记
在指定坐标画十字标记，适合标记找图/找色的命中位置。
Canvas.draw_cross(x, y, size=30, color="#ff0000", stroke_width=2, duration=3000, label=None, font_size=12, id=None)
| 参数 | 类型 | 必须 | 备注 |
|---|---|---|---|
| x, y | int | 是 | 十字中心坐标 |
| size | int | 否 | 十字臂长度 默认:30 |
| color | str | 否 | 颜色 默认:#ff0000 |
| label | str | 否 | 旁边的标注文字 |
| id | str | 否 | 唯一标识 |
- 示例
# 标记找图命中位置
canvas.draw_cross(320, 640, color="#ff0000", label="命中点")
箭头
画箭头，从起点指向终点，适合标记滑动方向。
Canvas.draw_arrow(x1, y1, x2, y2, color="#ffaa00", stroke_width=2, duration=3000, id=None)
| 参数 | 类型 | 必须 | 备注 |
|---|---|---|---|
| x1, y1 | int | 是 | 起点坐标 |
| x2, y2 | int | 是 | 终点坐标（箭头方向） |
| color | str | 否 | 颜色 默认:#ffaa00 |
| stroke_width | int | 否 | 线条宽度 默认:2 |
| duration | int | 否 | 显示时长(毫秒) 默认:3000 |
| id | str | 否 | 唯一标识 |
- 示例
# 标记从左往右的滑动
canvas.draw_arrow(200, 500, 800, 500, color="#ffaa00", duration=2000)
区域标记
画半透明区域，适合标记找图/OCR的搜索范围。
Canvas.draw_region(x1, y1, x2, y2, color="#ff00ff", fill="rgba(255,0,255,0.15)", stroke_width=1, duration=3000, label=None, font_size=12, id=None)
| 参数 | 类型 | 必须 | 备注 |
|---|---|---|---|
| x1, y1 | int | 是 | 左上角坐标 |
| x2, y2 | int | 是 | 右下角坐标 |
| color | str | 否 | 边框颜色 默认:#ff00ff |
| fill | str | 否 | 填充颜色（支持rgba透明度）默认:rgba(255,0,255,0.15) |
| label | str | 否 | 标注文字 |
| id | str | 否 | 唯一标识 |
- 示例
# 标记识别区域
canvas.draw_region(0, 200, 1080, 800, color="#00ff00", label="搜索范围")
多边形
Canvas.draw_polygon(points, color="#00ffff", stroke_width=2, duration=3000, close=True, id=None)
| 参数 | 类型 | 必须 | 备注 |
|---|---|---|---|
| points | list | 是 | 坐标列表，如 [(x1,y1),(x2,y2),...] |
| color | str | 否 | 颜色 默认:#00ffff |
| close | bool | 否 | 是否闭合 默认:True |
| id | str | 否 | 唯一标识 |
- 示例
canvas.draw_polygon([(100,100), (300,50), (500,100), (400,300), (200,300)])
椭圆
参数为外接矩形的左上角和右下角。
Canvas.draw_oval(x1, y1, x2, y2, color="#00ff00", stroke_width=2, duration=3000, id=None)
| 参数 | 类型 | 必须 | 备注 |
|---|---|---|---|
| x1, y1 | int | 是 | 外接矩形左上角 |
| x2, y2 | int | 是 | 外接矩形右下角 |
| color | str | 否 | 颜色 默认:#00ff00 |
| stroke_width | int | 否 | 线条宽度 默认:2 |
| duration | int | 否 | 显示时长(毫秒) 默认:3000 |
| id | str | 否 | 唯一标识 |
管理绘制对象
移除指定绘制
rid = canvas.draw_rect(100, 200, 400, 500)
canvas.remove(rid)
清除所有
canvas.clear()
关闭覆盖层
canvas.close()
完整示例
from ascript.android.ui import Canvas
import time
canvas = Canvas()
canvas.show()
# 标记搜索区域
canvas.draw_region(0, 200, 1080, 800, label="搜索区域", duration=5000)
# 标记命中位置
canvas.draw_cross(540, 500, color="#ff0000", label="命中", duration=5000)
# 标记滑动方向
canvas.draw_arrow(200, 960, 800, 960, duration=3000)
# 画一些辅助信息
canvas.draw_text(50, 150, "正在执行脚本...", color="#ffffff", font_size=16, duration=5000)
time.sleep(6)
canvas.close()