找色找图

在屏幕上找颜色、找图片，识别画在图片或画布里、控件树里没有的东西。在设备上完成，不联网。参数按顺序写：找什么、最多等几秒、区域，再往后是不常改的门槛。返回的坐标都是 point，可以直接给 client.click。

功能概览

·不用自己截图：每次查找自己截一张、用完就释放
·同一个画面查好几样，用 keepScreen / releaseScreen 或 withScreen
·区域写 0~1 的屏幕比例，换分辨率不用改
·模板图走文件下发，脚本里只写文件名

keepScreen#

把当前画面定住：截一张留着，之后的找色、找图、识字都在这一张上查，不再每次截图，也不会等，直到 releaseScreen()。

typescript

keepScreen(): void;

异常

异常类型	触发条件
`WDAError`FEATURE_UNAVAILABLE	设备上的 App 版本太旧，没有图色功能。

注意事项

已经定住时再调一次会换成新截的一张 —— 在循环里每轮开头调一次就是「刷新画面」。
记得 releaseScreen()，不然后面的查找一直看的是旧画面。怕忘就用 withScreen。

示例

javascript

keepScreen();
var dot = findColor('0xFF3B30');
var btn = findImage('btn_login.png');
releaseScreen();

参见 releaseScreen、withScreen

releaseScreen#

放开 keepScreen() 定住的画面，之后又是每次查找都现截。没定住时什么也不做。

typescript

releaseScreen(): void;

示例

javascript

releaseScreen();

参见 keepScreen

withScreen#

定住画面跑一个函数，跑完自动放开（函数里出错也会放开），返回函数的返回值。和 keepScreen / releaseScreen 一样，只是不怕忘了放开。

typescript

withScreen<T>(fn: () => T): T;

参数

参数名	类型	是否必填	默认值	描述
`fn`	`() => T`	是	—	在定住的画面上执行的函数。

返回值

类型	描述
`T`	fn 的返回值。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	fn 不是函数。

示例

javascript

var hits = withScreen(function () {
  return [findColor('0xFF3B30'), findImage('btn_login.png')];
});

参见 keepScreen

findColor#

找第一个匹配颜色的点，从上到下、从左到右扫描。

typescript

findColor(color: string, timeoutSec?: number, region?: [number, number, number, number] | null): { x: number; y: number } | null;

参数

参数名	类型	是否必填	默认值	描述
`color`	`string`	是	—	'0xRRGGBB'，或 '0xRRGGBB-0xTTTTTT'（减号后是每个通道的容差）。
`timeoutSec`	`number`	否	`0`	最多等几秒。0 表示只看一眼；大于 0 时每隔 0.5 秒重新截图再找，直到找到或超时。
`region`	`[x, y, w, h] \| null`	否	—	只在这块区域里找，不写是整屏。四个数都在 0~1 之间按屏幕比例算（[0, 0.5, 1, 0.5] 是下半屏，换分辨率也通用），否则按 point 算。

返回值

类型	描述
`{ x, y } \| null`	找到的点（point）；没找到返回 null。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数写错：等待秒数不是数字或超过 600、区域不是 [x, y, 宽, 高]、门槛不在 0~1、照旧写了 {} 等。
`WDAError`FEATURE_UNAVAILABLE	设备上的 App 版本太旧，没有图色功能。

示例

javascript

var p = findColor('0xFF8E42-0x101010', 0, [0, 0.1, 1, 0.4]);
if (p) {
  client.click(p.x, p.y);
}

参见 findMultiColor、cmpColor

findMultiColor#

多点找色：先扫锚点颜色，再校验相对它偏移的一组点，适合认一个小图标。

typescript

findMultiColor(anchorColor: string, offsets: string, timeoutSec?: number, region?: [number, number, number, number] | null, similarity?: number): { x: number; y: number; score: number } | null;

参数

参数名	类型	是否必填	默认值	描述
`anchorColor`	`string`	是	—	锚点颜色，写法同 findColor。
`offsets`	`string`	是	—	偏移点：'dx\|dy\|0xRRGGBB-0xTTTTTT,dx\|dy\|0xRRGGBB'，dx / dy 是相对锚点的 point 偏移。截图工作台里取点后可以直接生成。
`timeoutSec`	`number`	否	`0`	最多等几秒。0 表示只看一眼；大于 0 时每隔 0.5 秒重新截图再找，直到找到或超时。
`region`	`[x, y, w, h] \| null`	否	—	只在这块区域里找，不写是整屏。四个数都在 0~1 之间按屏幕比例算（[0, 0.5, 1, 0.5] 是下半屏，换分辨率也通用），否则按 point 算。
`similarity`	`number`	否	`0.9`	偏移点里要对上的比例，0~1；0.9 表示允许一成对不上。不是颜色距离。

返回值

类型	描述
`{ x, y, score } \| null`	锚点的位置和得分；没找到返回 null。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数写错：等待秒数不是数字或超过 600、区域不是 [x, y, 宽, 高]、门槛不在 0~1、照旧写了 {} 等。
`WDAError`FEATURE_UNAVAILABLE	设备上的 App 版本太旧，没有图色功能。

示例

javascript

var p = findMultiColor('0xDD7A5F-0x101010',
  '29|25|0xBB454B-0x101010,58|44|0xA6363A-0x101010');
if (p) {
  client.click(p.x, p.y);
}

参见 findColor

cmpColor#

比色：校验几个固定坐标上的颜色。不扫描，很快，适合判断现在在哪个界面。

typescript

cmpColor(points: string, timeoutSec?: number, similarity?: number): boolean;

参数

参数名	类型	是否必填	默认值	描述
`points`	`string`	是	—	'x\|y\|0xRRGGBB-0xTTTTTT,x\|y\|0xRRGGBB'，坐标是 point。
`timeoutSec`	`number`	否	`0`	最多等几秒。0 表示只看一眼；大于 0 时每隔 0.5 秒重新截图再找，直到找到或超时。
`similarity`	`number`	否	`1.0`	要对上的点的比例，0~1；默认每个点都要对上。

返回值

类型	描述
`boolean`	对上了返回 true。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数写错：等待秒数不是数字或超过 600、区域不是 [x, y, 宽, 高]、门槛不在 0~1、照旧写了 {} 等。
`WDAError`FEATURE_UNAVAILABLE	设备上的 App 版本太旧，没有图色功能。

示例

javascript

if (cmpColor('205|376|0xff944b-0x101010,211|386|0xff8e42')) {
  logi('on the home tab');
}

参见 findColor、getColor

getColor#

读某一点的颜色。写脚本时用来取参考色、调容差。

typescript

getColor(x: number, y: number): { r: number; g: number; b: number; hex: string };

参数

参数名	类型	是否必填	默认值	描述
`x`	`number`	是	—	横坐标（point）。
`y`	`number`	是	—	纵坐标（point）。

返回值

类型	描述
`{ r, g, b, hex }`	颜色分量和 0xRRGGBB 形式的十六进制。

异常

异常类型	触发条件
`WDAError`FEATURE_UNAVAILABLE	设备上的 App 版本太旧，没有图色功能。

示例

javascript

logi(getColor(100, 200).hex);

参见 cmpColor

findImage#

找图（模板匹配），返回得分最高的一个。

typescript

findImage(template: string, timeoutSec?: number, region?: [number, number, number, number] | null, threshold?: number): Match | null;

type Match = { x: number; y: number; width: number; height: number; centerX: number; centerY: number; score: number };

参数

参数名	类型	是否必填	默认值	描述
`template`	`string`	是	—	模板图的文件名，例如 btn_login.png。模板挂在脚本下面，在控制台代码测试台里截图上传；第一次用到时自动下载到设备。不要直接传 base64。
`timeoutSec`	`number`	否	`0`	最多等几秒。0 表示只看一眼；大于 0 时每隔 0.5 秒重新截图再找，直到找到或超时。
`region`	`[x, y, w, h] \| null`	否	—	只在这块区域里找，不写是整屏。四个数都在 0~1 之间按屏幕比例算（[0, 0.5, 1, 0.5] 是下半屏，换分辨率也通用），否则按 point 算。
`threshold`	`number`	否	`0.9`	相似度门槛，0~1。用的是归一化互相关得分，对整体明暗不敏感，0.9 在深浅色界面上含义一致。

返回值

类型	描述
`{ x, y, width, height, centerX, centerY, score } \| null`	匹配到的位置、大小、中心点和得分（都是 point）；没找到返回 null。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数写错：等待秒数不是数字或超过 600、区域不是 [x, y, 宽, 高]、门槛不在 0~1、照旧写了 {} 等。
`WDAError`TPL_NOT_FOUND	拿不到这张模板：这个脚本没上传这个文件名的图，或者下载失败。错误信息里写明是哪一种。这是抛错而不是返回 null：静默返回 null 会让人以为只是没找到。
`WDAError`FEATURE_UNAVAILABLE	设备上的 App 版本太旧，没有图色功能。

示例

javascript

var hit = findImage('btn_login.png', 5);
if (hit) {
  client.click(hit.centerX, hit.centerY);
}

参见 clickImage、useTemplates、findImageAll

findImageAll#

找出模板的所有匹配位置，按得分从高到低排序。

typescript

findImageAll(template: string, timeoutSec?: number, region?: [number, number, number, number] | null, threshold?: number, max?: number): Match[];

参数

参数名	类型	是否必填	默认值	描述
`template`	`string`	是	—	模板图的文件名，例如 btn_login.png。模板挂在脚本下面，在控制台代码测试台里截图上传；第一次用到时自动下载到设备。不要直接传 base64。
`timeoutSec`	`number`	否	`0`	最多等几秒，等到至少找到一个。0 表示只看一眼。
`region`	`[x, y, w, h] \| null`	否	—	只在这块区域里找，不写是整屏。四个数都在 0~1 之间按屏幕比例算（[0, 0.5, 1, 0.5] 是下半屏，换分辨率也通用），否则按 point 算。
`threshold`	`number`	否	`0.9`	相似度门槛，0~1。用的是归一化互相关得分，对整体明暗不敏感，0.9 在深浅色界面上含义一致。
`max`	`number`	否	`10`	最多要几个，至少 1。

返回值

类型	描述
`{ x, y, width, height, centerX, centerY, score }[]`	匹配数组，没有就是空数组。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数写错：等待秒数不是数字或超过 600、区域不是 [x, y, 宽, 高]、门槛不在 0~1、照旧写了 {} 等。
`WDAError`FEATURE_UNAVAILABLE	设备上的 App 版本太旧，没有图色功能。

示例

javascript

var stars = findImageAll('star.png', 0, null, 0.85, 5);
logi('stars: ' + stars.length);

参见 findImage

clickImage#

等模板出现并点它，落点在模板范围里随机偏一点，不会每次都点同一个点。

typescript

clickImage(template: string, timeoutSec?: number, region?: [number, number, number, number] | null, threshold?: number): boolean;

参数

参数名	类型	是否必填	默认值	描述
`template`	`string`	是	—	模板图的文件名，例如 btn_login.png。模板挂在脚本下面，在控制台代码测试台里截图上传；第一次用到时自动下载到设备。不要直接传 base64。
`timeoutSec`	`number`	否	`10`	最多等几秒。每隔 0.5 秒重新截图再找，直到找到或超时。
`region`	`[x, y, w, h] \| null`	否	—	只在这块区域里找，不写是整屏。四个数都在 0~1 之间按屏幕比例算（[0, 0.5, 1, 0.5] 是下半屏，换分辨率也通用），否则按 point 算。
`threshold`	`number`	否	`0.9`	相似度门槛，0~1。用的是归一化互相关得分，对整体明暗不敏感，0.9 在深浅色界面上含义一致。

返回值

类型	描述
`boolean`	点到返回 true，等不到返回 false。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数写错：等待秒数不是数字或超过 600、区域不是 [x, y, 宽, 高]、门槛不在 0~1、照旧写了 {} 等。
`WDAError`FEATURE_UNAVAILABLE	设备上的 App 版本太旧，没有图色功能。

注意事项

默认会把「点击图片 xxx」或「没有找到图片 xxx」记进任务日志，不想记用 setClickLog(false) 关掉。

示例

javascript

if (!clickImage('btn_login.png')) {
  return false;
}

参见 findImage、clickText

useTemplates#

提前把模板图备好。可选：不写的话 findImage 第一次用到时也会自动下载。写在脚本开头的好处是缺图在开跑时就知道，第一次找图也不会多卡一下。

typescript

useTemplates(names: string[] | string): boolean;

参数

参数名	类型	是否必填	默认值	描述
`names`	`string[] \| string`	是	—	文件名数组（只有一张时可以直接写文件名）。名字对应这个脚本上传的模板：每个脚本各有各的，不同脚本里同名的图不会串。

返回值

类型	描述
`boolean`	全部就位返回 true；缺任何一张返回 false，并在错误日志里写明缺哪张、为什么（没上传还是下载失败）。设备上缓存过的同一张图不会重复下载。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	传的不是文件名（比如照旧写了 [{ name, url }]）。要从别的地址下载用 downloadTemplate。
`WDAError`FEATURE_UNAVAILABLE	设备上的 App 版本太旧，没有图色功能。

示例

javascript

if (!useTemplates(['btn_login.png', 'btn_close.png'])) {
  return false;
}

参见 downloadTemplate、hasTemplate

hasTemplate#

这张模板在这次运行里是否已经备好（用过，或者 useTemplates 备过）。

typescript

hasTemplate(name: string): boolean;

参数

参数名	类型	是否必填	默认值	描述
`name`	`string`	是	—	文件名。

返回值

类型	描述
`boolean`	备好了返回 true。

示例

javascript

if (!hasTemplate('btn_login.png')) {
  loge('template missing');
}

参见 useTemplates

downloadTemplate#

从任意地址下载一张图当模板，起个名字，这次运行里 findImage 就能用这个名字。这个脚本自己上传的模板不需要它，直接写文件名就行。

typescript

downloadTemplate(url: string, name: string): boolean;

参数

参数名	类型	是否必填	默认值	描述
`url`	`string`	是	—	下载地址，以 / 开头的会自动补上服务器地址。
`name`	`string`	是	—	给这张图起的名字，findImage 里用它。只在这次运行里有效。

返回值

类型	描述
`boolean`	就位返回 true；下载失败返回 false 并写错误日志。

异常

异常类型	触发条件
`WDAError`FEATURE_UNAVAILABLE	设备上的 App 版本太旧，没有图色功能。

示例

javascript

downloadTemplate('https://example.com/btn_login.png', 'btn_login.png');

参见 useTemplates