文字识别

用系统的 Apple Vision 识别屏幕上的文字，在设备上完成，不联网、不上传截图。能用控件定位（clickElement）的地方优先用控件 —— 控件树是结构化的，快且准；OCR 的用武之地是画在图片、画布里，控件树里根本没有的文字。

功能概览

·识别语言、快慢用 ocrConfigure 设一次，整个任务都按它来
·中文需要 iOS 14 以上，日 / 韩 / 俄 / 泰 / 越需要 iOS 16 以上，Vision 不支持阿拉伯语
·返回的坐标是 point，可以直接给 client.click

ocr#

识别屏幕上的文字，按阅读顺序一行一项返回。

typescript

ocr(region?: [number, number, number, number] | null): Line[] & { text: string };

type Line = {
  text: string;
  confidence: number;
  x: number; y: number; width: number; height: number;
  centerX: number; centerY: number;
};

参数

参数名	类型	是否必填	默认值	描述
`region`	`[x, y, w, h] \| null`	否	—	只识别这块区域，不写是整屏；框小一点能快好几倍。写法同找色找图：四个数都在 0~1 之间按屏幕比例，否则按 point。

返回值

类型	描述
`{ text, confidence, x, y, width, height, centerX, centerY }[]`	一行一项，坐标是 point。数组还带一个 .text：所有行用换行连起来的整段文字。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数写错：keyword 为空、等待秒数不是数字或超过 600、区域不是 [x, y, 宽, 高]、照旧写了 {} 等。
`WDAError`OCR_LANG_UNSUPPORTED	这台设备的 Vision 不支持设定的识别语言。
`WDAError`FEATURE_UNAVAILABLE	设备上的 App 版本太旧，没有文字识别功能。

示例

javascript

var lines = ocr([0.05, 0.12, 0.9, 0.25]);
logi(lines.text);
for (var i = 0; i < lines.length; i++) {
  logi(lines[i].text + ' @' + lines[i].centerX + ',' + lines[i].centerY);
}

参见 findText、ocrConfigure

findText#

在屏幕上找一段文字，返回它所在的那一行。

typescript

findText(keyword: string | RegExp, timeoutSec?: number, region?: [number, number, number, number] | null, exact?: boolean): Line | null;

参数

参数名	类型	是否必填	默认值	描述
`keyword`	`string \| RegExp`	是	—	要找的文字（这一行包含它就算），或者正则表达式。不能是空字符串。
`timeoutSec`	`number`	否	`0`	最多等几秒。0 表示只看一眼；大于 0 时每隔 0.5 秒重新截图识别，直到找到或超时。
`region`	`[x, y, w, h] \| null`	否	—	只识别这块区域，不写是整屏；框小一点能快好几倍。写法同找色找图：四个数都在 0~1 之间按屏幕比例，否则按 point。
`exact`	`boolean`	否	`false`	写 true 要求整行完全一样，而不只是包含。

返回值

类型	描述
`{ text, confidence, x, y, width, height, centerX, centerY } \| null`	找到的那一行；没找到返回 null。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数写错：keyword 为空、等待秒数不是数字或超过 600、区域不是 [x, y, 宽, 高]、照旧写了 {} 等。
`WDAError`OCR_LANG_UNSUPPORTED	这台设备的 Vision 不支持设定的识别语言。
`WDAError`FEATURE_UNAVAILABLE	设备上的 App 版本太旧，没有文字识别功能。

示例

javascript

var hit = findText('余额', 5);
if (hit) {
  logi(hit.text);
}
var price = findText(/¥\s*[\d.]+/);

参见 clickText、ocr

clickText#

等一段文字出现并点它，落点在那一行的范围里随机偏一点。

typescript

clickText(keyword: string | RegExp, timeoutSec?: number, region?: [number, number, number, number] | null, exact?: boolean): boolean;

参数

参数名	类型	是否必填	默认值	描述
`keyword`	`string \| RegExp`	是	—	要找的文字（这一行包含它就算），或者正则表达式。不能是空字符串。
`timeoutSec`	`number`	否	`10`	最多等几秒。每隔 0.5 秒重新截图识别。
`region`	`[x, y, w, h] \| null`	否	—	只识别这块区域，不写是整屏；框小一点能快好几倍。写法同找色找图：四个数都在 0~1 之间按屏幕比例，否则按 point。
`exact`	`boolean`	否	`false`	写 true 要求整行完全一样，而不只是包含。

返回值

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

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数写错：keyword 为空、等待秒数不是数字或超过 600、区域不是 [x, y, 宽, 高]、照旧写了 {} 等。
`WDAError`OCR_LANG_UNSUPPORTED	这台设备的 Vision 不支持设定的识别语言。
`WDAError`FEATURE_UNAVAILABLE	设备上的 App 版本太旧，没有文字识别功能。

注意事项

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

示例

javascript

clickText('立即领取', 8);

参见 findText、clickElement

ocrConfigure#

设定本任务的识别语言和快慢，并提前校验语言可用。不调也行，默认是简体中文加英文。

typescript

ocrConfigure(languages?: string[] | string, level?: "accurate" | "fast", correction?: boolean): { ok: true; languages: string[]; level: string };

参数

参数名	类型	是否必填	默认值	描述
`languages`	`string[] \| string`	否	—	识别语言，例如 ['zh-Hans', 'en-US']、['ja-JP', 'en-US']；只有一种时可以直接写字符串。
`level`	`"accurate" \| "fast"`	否	`"accurate"`	accurate 准，fast 快。
`correction`	`boolean`	否	`false`	写 true 让系统按词典纠正识别结果。

返回值

类型	描述
`{ ok, languages, level }`	生效后的设置。

异常

异常类型	触发条件
`WDAError`OCR_LANG_UNSUPPORTED	这台设备的 Vision 不支持设定的识别语言。
`WDAError`INVALID_ARGUMENT	语言不是字符串数组、level 不是 accurate / fast、照旧写了 {}。
`WDAError`FEATURE_UNAVAILABLE	设备上的 App 版本太旧，没有文字识别功能。

注意事项

它的价值在于提前失败：不调的话，一台识别不了中文的设备要到循环深处才暴露问题。

示例

javascript

ocrConfigure(['zh-Hans', 'en-US'], 'accurate');

参见 ocrCapabilities、ocr

ocrCapabilities#

这台设备实际能识别哪些语言。

typescript

ocrCapabilities(): { engine: string; revision: number; accurate: string[]; fast: string[]; supportsChinese: boolean };

返回值

类型	描述
`{ engine, revision, accurate, fast, supportsChinese }`	accurate / fast 分别是两种模式下支持的语言代码。

异常

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

示例

javascript

logi(JSON.stringify(ocrCapabilities()));

参见 ocrConfigure