触动精灵扩展函数

序言

触动精灵是一款模拟手机触摸、按键操作的软件，通过制作脚本，可以让触动精灵代替双手，自动执行一系列触摸、按键操作。触动精灵简单、易用，不需要掌握任何编程知识就可以录制出功能强大的脚本；还可以使用编程知识，编写出功能更为复杂，交互更为灵活的脚本；只要能够在手机上完成的人为操作，触动精灵都可以代替完成，不仅省力，而且高效。

触动精灵采用 Lua 脚本语言作为底层语言，支持 Lua 5.2.2 版本的所有语法与基本函数，并在其的基础上添加了一些扩展函数，用于取色、找色、找图、发送触摸事件等高级功能的实现。

用户在阅读本词条前，请参考 Lua 官方手册以及相关资料，学习以下基本语法。

• 注释
• 变量与类型
• 运算符
• 条件、循环控制
• 函数定义
• 库函数
• ……

为了便于解释和描述，本词条中采用了一些非专业的描述与形容方法（如：整数型），敬请理解。因编写校对仓促，如有错误欢迎及时指正，本词条中的示例仅供函数参考，不要直接用于脚本中。

由于设备平台限制，脚本的编码必须为 UTF-8，请发布脚本前注意。

初始化 init

调用方法

函数	init
函数名称	初始化
函数简介	脚本使用触摸类函数[1]前必须调用，以指定应用以及坐标系。
方法	init(文本型 bid, 整数型 rotate);
返回值	无

序号	名称	类型	说明
1	bid	文本型	目标程序的 Bundle ID 填写 "0" 时，自动使用当前运行的应用。
2	rotate	整数型	屏幕方向 0 - 竖屏，1 - Home 键在右边，2 - Home 键在左边。

调用示例

init("com.apple.weather", 0);	--以 "com.apple.weather" 竖屏初始化

init("0", 1);	--以当前应用 Home 键在右边初始化

参考资料

Bundle ID 的获取方法

1. 在触动精灵的"更多"、"应用"中能查看到用户应用程序的 Bundle ID；
2. 使用 iFile、PP助手等软件可查看应用文件夹下的 Info.plist，其中的 CFBundleIdentifier 即为该应用的 Bundle ID。

备注

^[1] 触摸类函数指 touchDown, touchMove, touchUp。

触摸按下 touchDown、触摸移动 touchMove、触摸抬起 touchUp

调用方法

函数	touchDown、touchMove、touchUp
函数名称	触摸按下、移动、抬起
函数简介	发送触摸事件。
方法	touchDown(整数型 index, 整数型 x, 整数型 y); touchMove(整数型 index, 整数型 x, 整数型 y); touchUp(整数型 index, 整数型 x, 整数型 y);
返回值	无

序号	名称	类型	说明
1	index	整数型	手指序号[1]
2~3	x, y	整数型	屏幕坐标[2]

调用示例

--示例 1：快速划动
touchDown(1, 150, 550);	--在 (150, 550) 按下
touchMove(1, 150, 600);	--移动到 (150, 600)
touchUp(1, 150, 600);	--在 (150, 600) 抬起

--示例 2：连续划动
touchDown(1, 150, 550);	--在 (150, 550) 按下
for i = 0, 200, 10 do	--使用 for 循环[3]从起始点连续横向移动到终止点
touchMove(1, 150 + i, 550);
mSleep(150);	--延迟[4]
end

--示例 3：多点触控
touchDown(1, 200, 400);	--手指 1 在 (200, 400) 按下
touchDown(2, 300, 500);	--手指 2 在 (300, 500) 按下
mSleep(50);
for i = 1, 100, 1 do	--使用 for 循环使两只手指同时分离
touchMove(1, 200 - i, 400 - i);
touchMove(2, 300 + i, 500 + i);
mSleep(50);
end
touchUp(1, 200 - 100, 400 - 100);	--手指
touchUp(2, 300 + 100, 500 + 100);

备注

^[1] 手指序号，用于多点触控的支持。标记多只手指，来分别控制它们的移动。
^[2] 屏幕坐标，横坐标为 x，纵坐标为 y，单位为像素。例如，iPhone 4 与 iPhone 4S 的屏幕分辨率为 640 * 960，则其最大横坐标为 640，最大纵坐标为 960。
^[3] for 循环是 Lua 基本语法，属于循环控制。
^[4] 请参阅"延迟"一章。

输入字符串 inputText

调用方法

函数	inputText
函数名称	输入字符串
函数简介	向输入框中输入文本 。
方法	inputText(文本型 string);
返回值	无

序号	名称	类型	说明
1	string	文本型	欲输入的文本以及控制字符[1]

调用示例

--示例 1：输入欢迎文本并发送
touchDown(1, 150, 150);	--点击输入框获取焦点（假设输入框坐标已知）
touchUp(1, 150, 150);
mSleep(1000);	--延迟 1 秒以便获取焦点
inputText("Welcome.#ENTER#");	--在输入框中输入字符串"Welcome."并回车

注意事项

1. 使用该函数前，必须先点击输入框获取焦点^[2]。
2. 如果设备系统版本为 iOS 7 ， \r 无法使用，使用 \b 需安装触动精灵 1.6.9 及以上版本方可支持。
3. 仅在 iOS 7 上，可使用"#ENTER#"作为回车，相当于点击虚拟键盘上的"Done"。
4. 该函数不支持第三方输入法^[3]，请切换到系统内置输入法方可使用。
5. 对于弹出的窗口，需要先初始化^[4]再使用该函数，例如 App Store 登录窗口^[5]。

备注

^[1] 控制字符包括 \b、\n、\r、#ENTER#。
^[2] 获取焦点，指使当前的输入光标停留在某一输入框中。
^[3] 第三方输入法，指越狱后安装的百度输入法、搜狗输入法等。
^[4] 请参阅"初始化"一章。
^[5] 该窗口的 Bundle ID 为"com.apple.springboard"。

获取颜色 getColor、获取颜色RGB getColorRGB

调用方法

函数	getColor、getColorRGB
函数名称	获取颜色、获取颜色RGB
函数简介	获取某一点的颜色值（BGR）、颜色 R, G, B 值[1]。
方法 1	color = getColor(整数型 x, 整数型 y);
返回值	整型[2] color
方法 2	color_r, color_g, color_b = getColorRGB(整数型 x, 整数型 y);
返回值	整型 color_r, color_g, color_b

序号	名称	类型	说明
1	color	整型	该点的颜色值（BGR）
1	color_r, color_g, color_b	整型	该点颜色的 R, G, B 值
2~3	x, y	整数型	欲获取颜色值的坐标

调用示例

--示例 1：如果某点符合某颜色则点击
color = getColor(100, 100);	--获取 (100, 100) 的颜色值，赋值[3]给 color 变量
if color == 0xffffff then	--如果该点的颜色值等于[4] 0xffffff
touchDown(1, 100, 100);	--那么点击该点
touchUp(1, 100, 100);
end

--亦可写作
if getColor(100, 100) == 0xffffff then
touchDown(1, 100, 100);
touchUp(1, 100, 100);
end

--示例 2：如果某点的颜色与某颜色相似则点击
r, g, b = getColorRGB(100, 100);	--获取 (100, 100) 的颜色值，赋值给 color 变量
if r > 200 and g < 150 then	--如果红色强度大于 200，绿色强度小于 150
touchDown(1, 100, 100);	--那么点击该点
touchUp(1, 100, 100);
end

注意事项

1. getColor 与 getColorRGB 的作用是一样的，只不过前者返回单变量，后者返回 R, G, B 三变量。
2. 如直接使用例子中的代码进行测试，请在全部代码之前，加入 2 ~ 3 秒延迟；或者使用循环语句。因为脚本开始运行时，会出现音量提示遮盖在前台，影响获取颜色。
3. 特别注意，getColor 函数获得的颜色值十六进制文本中，实际顺序为 BGR。

参考资料

如何获取屏幕上某点的颜色

1. 在你想取出颜色的界面，同时按一下电源键和 Home 键进行截图（此时屏幕会闪一下），在相机胶卷中可以看到该截图；
2. 使用 PP助手 等软件将截图导出到电脑，使用取色工具或带有取色功能的软件（如 PhotoShop）取色。

取色工具可以在附录中找到下载地址。

备注

^[1] R, G, B 值，即代表红（Red）、绿（Green）、蓝（Blue）三个通道的颜色强度。
^[2] 整型，指的是可以用十、十六、八进制指定的数据类型。使用十六进制符号，必须加上 0x。
^[3] 赋值是 Lua 基本语法，操作符为"="（一个等号）。
^[4] 等于是 Lua 基本语法，属于条件控制，操作符为"=="（两个等号）。新手常常将等于写作赋值，从而导致编译出现错误。

等待延迟 mSleep

调用方法

函数	mSleep
函数名称	等待延迟
函数简介	发送系统等待事件。
方法	mSleep(整数型 interval);
返回值	无

序号	名称	类型	说明
1	interval	整数型	单位：毫秒[1]，脚本暂停执行的时间长度

调用示例

--示例 1：我真的还想再延迟约 500 年
mSleep(500 * 365 * 12 * 30 * 24 * 60 * 60 * 1000);

--示例 2：按住 3 秒不松手
touchDown(1, 200, 300);	--按下
mSleep(3000);	--延迟 3 秒
touchUp(1, 200, 300);	--抬起

注意事项

1. 延迟函数的使用与各类函数的使用息息相关，尤其是触摸类函数。脚本一般是用来模拟人在界面上的操作，因此要考虑人在各种情况下的延迟、界面加载时的响应时间。
2. 延迟间隔不可过短，当 interval <= 50 ms 时，延迟精确度大幅下降，当 interval <= 16 ms 时，实际延迟约在 16 ms 左右。
3. 延迟间隔不可过长，不能用于定时运行等功能的实现，因为该函数会占用较大系统资源。

备注

^[1] 1 秒 (s) = 1000 毫秒 (ms)。

区域找色 findColorInRegionFuzzy

调用方法

函数	findColorInRegionFuzzy
函数名称	区域找色
函数简介	在指定区域中，寻找符合指定颜色的坐标，支持模糊查找。
方法	x, y = findColorInRegionFuzzy(整型 color, 整数型 degree, 整数型 x1, 整数型 y1, 整数型 x2, 整数型 y2);
返回值	整数型 x, y

序号	名称	类型	说明
1~2	x, y	整数型	找到的点坐标 若未找到，则返回 -1, -1
3	color	整型	欲寻找的颜色值
4	degree	整数型	寻找精度，范围： 1 ~ 100 100 为完全匹配
5~6	x1, y1	整数型	欲寻找的区域左上角顶点坐标 (x1, y1)
7~8	x2, y2	整数型	欲寻找的区域右下角顶点坐标 (x2, y2)

调用示例

--示例 1：精确寻找指定区域中，指定颜色的坐标，并按下
x, y = findColorInRegionFuzzy(0x112233, 100, 50, 50, 300, 300);	--寻找符合条件的点
if x ~= -1 and y ~= -1 then	--如果在指定区域找到某点符合条件[1]
touchDown(1, x, y);	--那么单击该点
touchUp(1, x, y);
else	--如果找不到符合条件的点
dialog("未找到符合条件的坐标！");
end

--示例 2：模糊查找指定区域中，尽可能接近[2]指定颜色的点，并按下
for deg = 100, 1, -1 do	--使用 for 循环不断降低精确度
x, y = findColorInRegionFuzzy(0xffffff, deg, 50, 50, 300, 300);
if x ~= -1 and y ~= -1 then	--如果在指定区域找到某点符合条件
touchDown(1, x, y);	--那么单击该点
touchUp(1, x, y);
break;	--并跳出循环
end
end
dialog("未找到符合条件的坐标！");

注意事项

• 该函数效率不高，需占用较多系统资源，使用时请减小搜寻区域或降低调用频率。

备注

^[1] 未找到则返回 (-1, -1) ，所以找到时 x, y 均不等于 -1，~= 为不等于操作符，是 Lua 基本语法，属于逻辑控制。
^[2] 通过不断降低模糊查找精确度的方法在指定区域查找到的不一定是最接近指定颜色的点，该代码应用过程中，建议使用"保持屏幕"减少性能损耗，参见"保持屏幕"一章。

区域找图 findImageInRegionFuzzy

调用方法

函数	findImageInRegionFuzzy
函数名称	区域找图
函数简介	在指定区域中，寻找指定的图案，返回其左上角顶点坐标，支持模糊查找。
方法	x, y = findImageInRegionFuzzy(文本型 picpath, 整数型 degree, 整数型 x1, 整数型 y1, 整数型 x2, 整数型 y2, 整型 alpha);
返回值	整数型 x, y

序号	名称	类型	说明
1~2	x, y	整数型	找到的图片左上角顶点坐标 若未找到，则返回 -1, -1
3	picpath	文本型	欲寻找的图片文件名[1]
4	degree	整数型	寻找精度，范围： 1 ~ 100 100 为完全匹配
5~6	x1, y1	整数型	欲寻找的区域左上角顶点坐标 (x1, y1)
7~8	x2, y2	整数型	欲寻找的区域右下角顶点坐标 (x2, y2)
9	alpha	整型	忽略的颜色值[2]（透明色） 若无请填 0

调用示例

--示例：精确寻找指定区域中，指定图片的位置
--寻找符合条件的图片（假设图片的背景颜色为白色）
x, y = findImageInRegionFuzzy("test_alpha.png", 100, 0, 0, 320, 480, 0xffffff);
if x ~= -1 and y ~= -1 then	--如果在指定区域找到某点符合条件
touchDown(1, x, y);	--那么单击该图片
touchUp(1, x, y);
else	--如果找不到符合条件的点
dialog("未找到符合条件的坐标！");
end

注意事项

• 不推荐此函数，对于找小型图片精度较差。

备注

^[1] 默认图片路径为 /var/mobile/Media/TouchSprite/res，自建目录请填写相对路径。
^[2] 忽略的颜色值指欲寻找的图片的背景颜色，即在屏幕画面上不匹配寻找对象的背景颜色。

截图 snapshot

调用方法

函数	snapshot
函数名称	截图
函数简介	截取屏幕中指定区域的图像并生成指定格式的图片文件。
方法	snapshot(文本型 picpath, 整数型 x1, 整数型 y1, 整数型 x2, 整数型 y2);
返回值	无

序号	名称	类型	说明
1	picpath	文本型	欲储存到的图片文件名[1] 支持的格式有：bmp, jpg, png
2~3	x1, y1	整数型	欲寻找的区域左上角顶点坐标 (x1, y1)
4~5	x2, y2	整数型	欲寻找的区域右下角顶点坐标

调用示例

--示例：全屏截图
--全屏截图（iPhone 5, 5S），并以当前日期为文件名保存
current_time = os.date("%Y-%m-%d", os.time()); --[2]
snapshot(current_time..".png", 0, 0, 639, 1135);

注意事项

1. 保存图片的格式可为 bmp, jpg, png，因为 png 是 iOS 中最常见的格式，所以推荐选择 png。
2. 截图时，右下角顶点坐标最大为 (639, 1135)，否则会出现越界错误。

备注

^[1] 默认图片路径为 /var/mobile/Media/TouchSprite/res，自建目录请填写相对路径，文件相同将会被覆盖。
^[2] os.date 与 os.time 为 Lua 基本库函数，请查阅附录 - Lua 操作系统函数库。
^[3] ".." 为字符串连接操作符，可以将字符串变量、常量连接在一起；640 * 1136 为 iPhone 5, 5S 等设备的分辨率。

对话框 dialog

调用方法

函数	dialog
函数名称	对话框
函数简介	弹出提示信息。
方法	dialog(文本型 text, 整数型 time);
返回值	无

序号	名称	类型	说明
1	text	文本型	提示信息
2	time	整数型	提示信息显示的时间 不限时间请填 0

调用示例

--示例：欢迎使用
dialog("欢迎使用触动精灵！", 5);
mSleep(1000);
dialog("本脚本仅供演示对话框的用法。\n提示信息可以换行。", 0);	--[1]

注意事项

1. time 参数时间一般在 2 秒以上，否则出现时间太短看不清楚。
2. 该函数仅供呈现提示信息给用户，不可接收返回值。

备注

^[1] 关于转义字符：\n 为换行，请查阅 Lua 转义字符表。

带按钮的对话框 dialogRet

调用方法

函数	dialogRet
函数名称	带按钮的对话框
函数简介	弹出提示信息，并提供 1 ~ 3 个按钮给用户选择。
方法	choice = dialogRet(文本型 text, 文本型 cbtn, 文本型 btn1, 文本型 btn2, 整数型 time);
返回值	整数型 choice

序号	名称	类型	说明
1	choice	整数型	返回用户按下按钮的序号 cbtn == 0 btn1 == 1 btn2 == 2
2	text	文本型	提示信息
3	cbtn	文本型	默认按钮标题 不需要请填 ""
4	btn1	文本型	可选按钮 1 不需要请填 ""或 0[1]
5	btn2	文本型	可选按钮 2 不需要请填 ""或 0
6	time	整数型	提示信息显示的时间 不限时间请填 0

调用示例

--示例 1：选择性别（双选）
choice = dialogRet("请选择您的性别：", "男", "女", "", 0);

--示例 2：选择性别（三选）
choice = dialogRet("请选择您的性别：", "男", "女", "人妖", 0);

if choice == 0 then	--男
dialog("你好，帅哥。");
mSleep(1000);
elseif choice == 1 then	--女
dialog("你好，美女");
mSleep(1000);
else	--人妖
dialog("人妖不允许使用该脚本。");
mSleep(1000);
lua_exit();	--退出脚本[2]
end

--示例 3：请阅读许可协议
dialogRet("这里是许可协议或广告，强制阅读 30 秒不可消除。", "", "", "", 30);

注意事项

1. 请勿将三个按钮都设置为空，再将 time 参数设置为 0，这样将造成出现无法消失也没有按钮的对话框，造成设备无法进行其它操作，只能重启。
2. 值得一提的是，cbtn 总是对话框的最右边或者最下面的按钮。

备注

^[1] 这里的 0 是数字，不是文本 "0"。
^[2] 请参阅"退出脚本"一章。

带参数的对话框 dialogInput

调用方法

函数	dialogInput
函数名称	带参数的对话框
函数简介	弹出提示信息，并提供 1 ~ 2 个编辑框给用户输入。
方法 1	text_a = dialogInput(文本型 title, 文本型 format, 文本型 btn);
返回值 1	文本型 text_a
方法 2	text_a, text_b = dialogInput(文本型 title, 文本型 format, 文本型 btn);
返回值 2	文本型 text_a, text_b

序号	名称	类型	说明
1~2	text_a, text_b	文本型	返回用户输入的文本
3	title	文本型	提示标题
4	format	文本型	编辑框中浅色的提示文字 如果需要两个编辑框，则将提示文字用"#"分割
5	btn	文本型	确认按钮标题

调用示例

--示例：输入姓名与年龄
--一个输入框
::getInfo::	--设置跳转标签
text_a = dialogInput("请输入您的姓名", "在这里输入姓名", "确认");
mSleep(1000);

--两个输入框
text_a, text_b = dialogInput("请输入您的姓名和年龄", "在这里输入姓名#在这里输入年龄", "确认");
mSleep(1000);

if text_b ~= "" and text_a ~= "" then	--均已填写
dialog("你好，"..text_b.." 岁的 "..text_a.." 。", 5);
mSleep(1000);
elseif text_a ~= "" then	--只填写了姓名
dialog("你好，不知道年龄的 "..text_a.." 。", 5);
mSleep(1000);
else	--均未填写
dialog("请填写您的信息！", 5);
mSleep(1000);
goto getInfo;	--返回重新填写[1]
end

注意事项

1. 一般来说，使用该函数都要对用户输入的数据进行一定的检查，例如要求非空、长度不得少于。
2. 使用双编辑框时，函数返回的两个字符串顺序与 format 中的顺序相反，请注意。
3. 由于对话框事件需要响应时间，所以建议每次使用对话框，均应使用延迟。

备注

^[1] goto 是 Lua 基本语法，设置标签，然后使用 goto 函数跳转到代码的指定位置向下执行。该函数请谨慎使用，因为大量的跳转会造成代码编写的混乱。

自定义界面 showUI

调用方法

函数	showUI
函数名称	自定义界面
函数简介	显示一个自定义的界面，用来接收用户相关的自定义配置。
方法	ret, input_1, input_2, ... = showUI(文本型 ui_json);
返回值	整数型 ret, 文本型 input_(*)

序号	名称	类型	说明
1	ret	整数型	1 == 确认输入 0 == 取消输入
2	input_(*)	文本型	返回用户输入的多项数据
3	ui_json	文本型	自定义界面 json 格式字符串[1] 调用时字符串需经过压缩与转义[2]

详解 1 - 什么是 json

json 是一种轻量级的数据交换格式，其实就是一串字符串，在该函数中，我们用它来创建界面上的一系列会使用特定的符号标注的元素：

• {} 双括号表示对象
  
• [] 中括号表示数组
  
• "" 双引号内是属性或值
  
• : 冒号表示后者是前者的值^[3]
  

所以 {"name": "Michael"} 可以理解为是一个包含 name 为 Michael 的对象，而 [{"name": "Michael"},{"name": "Jerry"}] 就表示包含两个对象的数组。
当然了，你也可以使用 {"name":["Michael","Jerry"]} 来简化上面一部分，这是一个拥有 name 数组的对象。
不管是键或文本型的值都要用双引号引起来，所以上面的代码就是 {"name":"json"} 。

详解 2 - 调用示例

为了便于 json 的书写，我们通常使用可读性较强的形式；但是为了便于脚本的调用，我们需要将 json 进行压缩与转义。将 json 进行转义后，作为字符串放进 showUI 函数的参数 ui_json 中，我们先来看该函数如何调用 json 生成界面。

--样式：默认，是否保存配置（如果不需要保存就把 config 这段去掉 cfg.dat 为配置表的名称，需要区分）。
MyJsonString  = "{ \"style\":\"default\", \"config\":\"cfg.dat\", \"views\" : [";

--显示一个文字，控件，名字，大小，对齐方式，颜色。
MyJsonString = MyJsonString .. "{ \"type\":\"Label\", \"text\":\"设置\", \"size\":25, \"align\":\"left\", \"color\":\"0,0,255\"}" .. ",";

--显示一个输入框体,控件名，提示信息，默认返回值，大小，对齐方式，颜色。
MyJsonString = MyJsonString .. "{ \"type\":\"Edit\", \"prompt\":\"测试三下\",\"text\":\"默认值\", \"size\":15, \"align\":\"left\", \"color\":\"255,0,0\"}" .. ",";

--显示一群单选，控件名，需要几个选项以及选项的名称，默认选项（0 开始）。
MyJsonString = MyJsonString .. "{ \"type\":\"RadioGroup\", \"list\":\"选项1,选项2,选项3,选项4,选项5,选项6,选项7\",\"select\":\"1\"}" .. ",";

--显示一群多选，控件名，需要几个选项以及选项的名称，默认选项（0 开始）。
MyJsonString = MyJsonString .. "{ \"type\":\"CheckBoxGroup\", \"list\":\"选项1,选项2,选项3,选项4,选项5,选项6,选项7\",\"select\":\"3@5\"}";

--结尾
MyJsonString = MyJsonString .. "] }";

--生成界面
ret,input1,input2,input3 = showUI(MyJsonString);

--弹出返回值
mSleep(1000);
dialog("ret="..ret.."\ninput1="..input1.."\ninput2="..input2.."\ninput3="..input3,0);

--对齐方式
--left：左对齐内容。
--right：右对齐内容。
--center：居中对齐内容。
--justify：对行进行伸展，这样每行都可以有相等的长度。

详解 3 - 用 json 创建界面

上面是调用的例子，但是我们首先我们要设计一个界面，并生成一段 json 字符串，再进行压缩转义。我们先看上图界面示例 json 原来的样子（非脚本代码，不可直接引用），再作解释：

{
    "style": "default",
    "config": "save_111.dat",
    "views": [
        {
            "type": "Label",
            "text": "设置",
            "size": 25,
            "align": "center",
            "color": "0,0,255"
        },
        {
            "type": "RadioGroup",
            "list": "选项1,选项2,选项3,选项4,选项5,选项6,选项7",
            "select": "1"
        },
        {
            "type": "Edit",
            "prompt": "测试三下",
            "text": "默认值",
            "size": 15,
            "align": "left",
            "color": "255,0,0"
        },
        {
            "type": "CheckBoxGroup",
            "list": "选项1,选项2,选项3,选项4,选项5,选项6,选项7",
            "select": "3@5"
        }
    ]
}

创建一个界面，需要包含 style 与 views 两个主键。
style 表示界面样式，views 数组则包含了界面上的控件；config 表示自动配置文件名，如果存在此键名，则用户点击确认时保存配置到指定文件中。如果配置文件存在，调用该界面会自动载入该文件中的配置。

详解 4 - 界面控件

我们可以看到，界面控件被定义在 views 数组中。而自定义界面一共有四种控件类型 type：标签 Label，单选框 RadioGroup，编辑框 Edit，多选框 CheckBoxGroup。

标签 Label 一共有四种属性：

类型	属性	键名	描述
文本	标题	text	必填，一般来用显示说明文字或者标题，该控件没有任何返回值，只用作显示。
数值	字体大小	size	如果不指定改属性，则默认值为 15。
文本	对齐方式	align	对齐方式 align 可取值为：左对齐 left，右对齐 right，居中 center。
文本	字体颜色	color	字体颜色 color 则使用 RGB 十进制数值，以英文半角逗号分割。

单选框 RadioGroup 一共有两种属性：

类型	属性	键名	描述
文本	可选项目标题	list	可选项目标题 list 用英文半角逗号分割。
文本	默认选中项编号	select	默认选中项编号 select 只允许填写一个，序号从 0 开始，与可选项目标题中的顺序保持一致。

编辑框 Edit 一共有五种属性：

类型	属性	键名	描述
文本	编辑框提示文本	prompt	编辑框提示文本 prompt 为编辑框中无任何内容时显示的底色文本。
文本	编辑框默认内容	text	界面载入时已经存在于编辑框中的文本。
数值	字体大小	size	如果不指定改属性，则默认值为 15。
文本	对齐方式	align	对齐方式 align 可取值为：左对齐 left，右对齐 right，居中 center。
文本	字体颜色	color	字体颜色 color 则使用 RGB 十进制数值，以英文半角逗号分割。

多选框 CheckBoxGroup，又称作检查框，一共有两种属性：

类型	属性	键名	描述
文本	可选项目标题	list	可选项目标题 list 用英文半角逗号分割。
文本	默认选中项编号	select	默认选中项编号 select 允许填写一个或多个，填写多个时以 @ 分割编号。

以上四种控件均可重复使用，这个界面的样式 style 为 default，即默认样式，这个样式下的控件将会自动排列，不需要指定其坐标。

详解 5 - 指定控件尺寸与位置

另一种界面样式为 custom，当界面样式被指定为这种，则必须指定每个控件的 rect 属性以调整控件的尺寸以及位置，例如：

{
    "type": "Edit",
    "size": 15,
    "align": "left",
    "prompt": "提示文字",
    "text": "默认文字",
    "color": "255,0,0",
    "rect": "0,0,100,40"
}

类型	属性	键名	描述
文本	尺寸与位置	rect	将控件的左上角顶点横坐标、纵坐标，控件宽度、高度分别以英文半角逗号分割。

该属性适用于全部四种控件。

详解 6 - 返回值

除了标签 Label，其余三种控件均存在文本型返回值，按照定义时的顺序依次返回给 input_1, input_2, input_3, ...。单选框返回当前选中项的编号；编辑框返回其中的内容；多选框返回当前选中项的编号（从 0 开始），多个选项以 @ 分割。如：3@5 表示多选框组编号为 3 和 5 的两个选项已被选中。
别忘记，该函数的第一个返回值为整数型 ret，用户单击右下角的“确认”时返回 1，单击左下角的“取消”时返回 0。

参考资料

Json 在线校验格式化、压缩转义工具。

备注

^[1] Json (JavaScript Object Notation) 是一种轻量级的数据交换格式，采用完全独立于语言的文本格式，易于人阅读和编写，同时也易于机器解析和生成。
^[2] 转义即取消某一些特定的、在编辑语言中被定义为特殊用途的字符。这些字符由于被定义为特殊用途，它们失去了原有的意义，如三种引号 " ' ` 、美元符号 $ 等等。当我们在被引号“括起来”的文本中，想表示出一个引号，就需要转义，如：dialog("\"",5);
^[3] 这个值可以是字符串、数字、也可以是另一个数组或对象。

打开网址 openURL

调用方法

函数	openURL
函数名称	打开网址
函数简介	调用系统浏览器[1]，打开一个指定网址。
方法	openURL(文本型 url);
返回值	无

序号	名称	类型	说明
1	url	文本型	欲打开的网址[2]

调用示例

--示例
openURL("...");
--调用系统浏览器打开...

备注

^[1] 默认、正常情况下为 Safari。
^[2] 欲打开的网址必须包含协议头，最常见的是 http://，一些特殊协议也是支持的，如：mailto://, sms://, tel://, ifile://, cydia:// 等等。

初始化日志 initLog、写日志 wLog、关闭日志 closeLog

调用方法

函数	initLog、wLog、closeLog
函数名称	初始化日志、写日志、关闭日志
函数简介	配置日志输出地址与方式、写出或发送日志、关闭日志输出连接。
方法 1	initLog(文本型 name, 整数型 flag);
方法 2	wLog(文本型 name, 文本型 contents);
方法 3	closeLog(文本型 name, 文本型 contents);
返回值	无

序号	名称	类型	说明
1	name	文本型	日志文件名或服务器地址与端口 不带后缀，自动添加 .log
2	flag	整数型	输出方式 0 == 输出到文件名 1 == 输出到带时间戳的文件名 2 == 异步发送到服务器[1] 3 == 同步发送到服务器[2]
3	contents	文本型	日志内容 在该参数中，加入 [DATE] 自动替换为当前可读时间

调用示例

--示例 1 写到本地日志
initLog("test", 0);
--把 0 换成 1 即生成形似 test_1397679553.log 的日志文件
wLog("test","[DATE] Test_1 OK!!!");
mSleep(500);
wLog("test","[DATE] Test_2 OK!!!");
closeLog("test");

--示例 2 发送服务器日志
initLog("192.168.1.1", 2);
--初始化日志，并以异步方式发送；把 2 换成 3 即为同步发送
wLog("192.168.1.1", "[DATE] Test OK!!!");	--将日志发送到 192.168.1.1
closeLog("192.168.1.1");	--关闭服务器连接

--示例 3 多日志记录
initLog("test_1", 0);
initLog("test_2", 0);
wLog("test_1","[DATE] Test_1 OK!!!");
mSleep(500);
wLog("test_2","[DATE] Test_2 OK!!!");
closeLog("test_1");
closeLog("test_2");

注意事项

1. flag 参数设置为 2 和 3，需要触动精灵 1.7.0 及以上版本支持，并需要配合触动精灵日志服务端使用，要求设备与运行服务端的 PC 处于同一网段。
2. 该函数支持多日志记录，即可以定义并初始化多个日志用于分类存放。
3. 此函数一般用于脚本开发阶段，若脚本开发完成，只需注释^[3]掉 initLog 即可。
4. 日志的编码为 UTF-8，请使用支持 UTF-8 编码的编辑器查看。

参考资料

函数	syslog
函数名称	输出系统日志
函数简介	使用 NSLog 输出系统日志，该函数将日志输出到 iOS 系统级日志中，请使用 iTools 或 XCode[4] 查看。。
方法	syslog(文本型 contents);
返回值	无

序号	名称	类型	说明
1	contents	文本型	日志内容

• 日志工具下载地址可在附录中找到。

备注

^[1] 当使用同步消息传送时，脚本需等待日志已经到达服务端才继续执行下面的指令。
^[2] 当使用异步消息传送时，调用者在发送消息以后可以不用等待响应，可以接着处理其他任务。即发送日志无需等待发送完成即可继续执行。
^[3] 注释的操作符形式为 --...... 或 --...... ，可将用于说明的代码写入脚本以便开发时理解。
^[4] XCode 为 Apple 专为 Mac OS X 设计的开发平台。

播放音频 playAudio

调用方法

函数	playAudio
函数名称	播放音频
函数简介	在后台播放指定的声音文件。
方法	playAudio(文本型 filename);
返回值	无

序号	名称	类型	说明
1	filename	文本型	音频文件名[1] 支持 mp3, m4a, ogg, wav

调用示例

--示例
playAudio("test.mp3");	--播放 test.mp3

备注

^[1] 默认音频路径为 /var/mobile/Media/TouchSprite/res，自建目录请填写相对路径。

本地光学字符识别 ocrText

调用方法

函数	ocrText
函数名称	本地光学字符识别
函数简介	将指定区域的图像转换为其显示出的文字。
方法	text = ocrText(整数型 x1, 整数型 y1, 整数型 x2, 整数型 y2, 整数型 language);
返回值	文本型 text

序号	名称	类型	说明
1	text	文本型	返回的识别结果
2 ~ 3	x1, y1	整数型	欲识别的区域左上角顶点坐标 (x1, y1)
4 ~ 5	x2, y2	整数型	欲识别的区域右下角顶点坐标 (x2, y2)
6	language	整数型	语言 0 == 英文 1 == 中文

调用示例

--示例
recognize = ocrText(20, 120, 200, 140, 0);	--OCR 识别
mSleep(1000);
dialog("识别出的字符："..recognize, 0);

注意事项

• 该函数精确度较低，仅能准确识别白底黑正楷字，不推荐使用。
• 需要相应的识别库以及识别插件：

1. 将识别库（英文 eng.traineddata，简体中文 chi_sim.traineddata）放置于 /var/mobile/Media/TouchSprite/tessdata 目录下；
2. 将插件（OcrPlugin.dylib）放置于 /var/mobile/Media/TouchSprite/plugin 目录下；

参考资料

• OCR 识别库下载地址可在附录中找到。

保持屏幕 keepScreen

调用方法

函数	keepScreen
函数名称	保持屏幕
函数简介	在脚本中保持当前屏幕内容不变，多次调用取色、找色、截图、找图等函数时，直接调用保持的内容。该函数为优化类函数，能够为大量的静态图像处理[1]函数提供性能优化。
方法	keepScreen(逻辑型 flag);
返回值	无

序号	名称	类型	说明
1	flag	逻辑型	保持开关[2]

调用示例

--示例 遍历屏幕区块
keepScreen(true);
for k = 1, 640, 10 do
for j = 1, 960, 10 do
--格式化为十六进制文本
color = string.format("%X", getColor(k, j));
--输出到系统日志
syslog("("..k..", "..j..") Color: "..color..".");
end
end
keepScreen(false);

注意事项

1. 据不完全统计，使用该函数与不使用该函数，普通屏上脚本取色速率高达 100x ^[3]，高分屏上脚本取色速率高达 50x。在执行大量静态图像操作时，请务必使用该函数优化脚本性能。
2. 该函数一般用于画面变动节奏较慢，但需要根据大量取色、找色来完成计算和操作的脚本中，例如"天天爱消除"、"天天星连萌"这样的游戏。

参考资料

• "天天爱消除"、"天天星连萌"脚本开源范例。

备注

^[1] 静态图像处理，指可在某一状态下使屏幕内容保持到内存（不影响显示），对其进行进一步的多次分析。否则，每次使用图像类函数，都将截取一次屏幕内容。
^[2] 保持开关，逻辑型只有两种属性：true 为真，false 为假。
当使用 keepScreen(true); 时启用屏幕保持，运行到该函数时内存中的屏幕图像保持在这一时刻。
当使用 keepScreen(false); 时关闭屏幕保持，释放内存中的屏幕图像，以备下一次继续保持。
^[3] 与未使用该函数相比，下同。

运行应用 runApp、关闭应用 closeApp

调用方法

函数	runApp、closeApp
函数名称	运行应用、关闭应用
函数简介	打开或关闭一个应用程序。
方法 1	runApp(文本型 bid);
方法 2	closeApp(文本型 bid);
返回值	无

序号	名称	类型	说明
1	bid	文本型	应用程序的 Bundle ID

调用示例

--示例 打开内置天气应用，然后退出
runApp("com.apple.weather");	--启动应用
mSleep(10 * 1000);
closeApp("com.apple.weather");	--退出应用

注意事项

1. 该函数需要系统响应时间较长，注意做好延迟或判断。
2. 关于 Bundle ID 的获取方法，参见"初始化"一章。

获取分辨率 getScreenSize

调用方法

函数	getScreenSize
函数名称	获取屏幕分辨率
函数简介	获取设备屏幕的分辨率，用来判断坐标系的使用。
方法	width, height = getScreenSize();
返回值	整数型 width, height

序号	名称	类型	说明
1 ~ 2	width, height	整数型	获取到的屏幕宽度和高度

调用示例

--示例 根据分辨率判断设备类型
width, height = getScreenSize();
if width == 640 and height == 1136 then
--iPhone 5, 5S, iPod touch 5
elseif width == 640 and height == 960 then
--iPhone 4,4S, iPod touch 4
elseif width == 320 and height == 480 then
--iPhone 非高分屏
elseif width == 768 and height == 1024 then
--iPad 1,2, mini 1
elseif width == 1536 and height == 2048 then
--iPad 3,4,5, mini 2
end

注意事项

• 统一为竖直（Home 键在下方时）屏幕的宽度和高度。

获取设备类型 getDeviceType

调用方法

函数	getDeviceType
函数名称	获取设备类型
函数简介	获取设备的类型，可使用获取屏幕分辨率代替。
方法	type = getDeviceType();
返回值	整数型 type

序号	名称	类型	说明
1	type	整数型	设备类型 0 == iPod Touch 1 == iPhone 2 == iPad

调用示例

--示例 示例 根据分辨率判断设备类型
type = getDeviceType();
if type == 0 then
--iPod Touch
elseif type == 1 then
--iPhone
elseif type == 2 then
--iPad
end

获取设备号 getDeviceID

调用方法

函数	getDeviceID
函数名称	获取设备号
函数简介	获取设备标识，每台设备的标识都是唯一的。
方法	id = getDeviceID();
返回值	文本型 id

序号	名称	类型	说明
1	id	文本型	触动精灵设备号

调用示例

--示例 获取设备号并输出到日志
id = getDeviceID();
syslog("Device ID: "..id);

注意事项

• 该函数返回的，并非 udid，而是触动精灵内部设备号，可用来鉴定设备唯一性。

退出脚本 lua_exit

调用方法

函数	lua_exit
函数名称	退出脚本
函数简介	直接终止脚本。
方法	lua_exit();
返回值	无

调用示例

--示例 弹出许可协议，若不同意则退出脚本
return = dialogRet("许可协议\n协议内容", "同意", "不同意", 0, 0);
if return == 0 then	--如果按下"同意"按钮
init("0",0);	--开始初始化
else
lua_exit();	--否则退出脚本
end

注意事项

• 调用该函数时，脚本立即终止执行，所有相关的资源得到释放。

模拟主屏幕按键 pressHomeKey

调用方法

函数	pressHomeKey
函数名称	模拟主屏幕按键
函数简介	模拟用户按下或抬起主屏幕按键的操作。
方法	pressHomeKey(整数型 flag);
返回值	无

序号	名称	类型	说明
1	flag	整数型	状态标识 0 == 按下 1 == 抬起（不兼容 iOS 7）

调用示例

--示例 1 返回主屏幕
pressHomeKey(0);	--按下 Home 键
pressHomeKey(1);	--抬起 Home 键

--示例 2 调出后台
pressHomeKey(0);	--按一次 Home 键
pressHomeKey(1);
mSleep(300);	--短暂延迟
pressHomeKey(0);	--再按一次
pressHomeKey(1);

--示例 3 调出 Siri （iPhone 4S 以上，iOS 6 及以下）
pressHomeKey(0);	--按下 Home 键
mSleep(3000);	--按住不放
pressHomeKey(1);	--抬起

注意事项

1. 在 iOS 6 下，状态标识为 0 时，调用该函数则开始按下 Home 键并按住不放，直到状态标识为 1 时重新调用该函数，抬起 Home 键。
2. 在 iOS 7 下，状态标识只能填写 0，代表按一次 Home 键，即按下并立即抬起 Home 键的操作。

是否为前台应用 isFrontApp

调用方法

函数	isFrontApp
函数名称	是否为前台应用
函数简介	根据应用的 Bundle ID 判断应用是否处于前台。
方法	flag = isFrontApp(文本型 bid);
返回值	整数型 flag

序号	名称	类型	说明
1	flag	整数型	状态标识 0 == 不在前台运行 1 == 在前台运行
2	bid	文本型	待检测的应用程序 Bundle ID

调用示例

--示例 监听应用状态
isfront = 1;
while isfront == 1 do	--如果应用处于前台则继续
mSleep(3000);	--此处放置代码块
isfront = isFrontApp("com.tencent.mqq");	--更新前台状态
end

注意事项

• Bundle ID 的获取方法参见"初始化"一章。

重置锁屏计时 resetIDLETimer

调用方法

函数	resetIDLETimer
函数名称	重置锁屏计时
函数简介	重置系统空闲时间，阻止自动锁屏，保持屏幕常亮。
方法	resetIDLETimer();
返回值	无

调用示例

--示例 保持屏幕常亮
while true do	--[1]
mSleep(30 * 1000);	--等待 30 秒
resetIDLETimer();	--重置锁屏计时
end

注意事项

• 该函数可能会减少屏幕、电池寿命，请谨慎使用。

备注

^[1] while true do ... end 为死循环代码，一般不建议这样使用。除非强行终止运行，否则该脚本不会自动停止，如果用户忘记终止脚本，将会缩减电池寿命。

手机振动 vibrator

调用方法

函数	vibrator
函数名称	手机振动
函数简介	使手机振动一次。
方法	vibrator();
返回值	无

调用示例

--示例 警报
for 1,5 do
playAudio("alert.mp3");	--播放警报铃声
vibrator();	--振动
mSleep(1000);	--延迟 1 秒
end

注意事项

• 频繁调用该函数可能会减少电池寿命，请谨慎使用。

锁定设备 lockDevice

调用方法

函数	lockDevice
函数名称	锁定设备
函数简介	锁定设备并关闭屏幕。
方法	lockDevice();
返回值	无

调用示例

--示例 结束并锁定设备
lockDevice();
lua_exit();

注意事项

• 无人值守的情况下，使用该函数可减少电池消耗。

获取网络时间 getNetTime

调用方法

函数	getNetTime
函数名称	获取网络时间
函数简介	从互联网上获取时间信息，返回从 1970 年 1 月 1 日到当前状态的秒数。
方法	time = getNetTime();
返回值	整数型 time

序号	名称	类型	说明
1	time	整数型	返回从 1970 年 1 月 1 日到当前状态的秒数

调用示例

--示例 获取网络时间并判断脚本过期
origin = 1404439947;
--代表北京时间 2014/7/4 10:12:27
origin_text = os.date("%Y/%m/%d %X", origin);	--格式化时间
current = getNetTime();	--获取网络时间
current_text = os.date("%Y/%m/%d %X", current);	--格式化时间
if origin >= current then
dialog("脚本尚未过期！", 5);
else
dialog("脚本已经过期！\n脚本使用期限："..origin_text.."\n当前时间："..current_text, 5);
lua_exit();
end

注意事项

• 该函数需要网络支持，且根据网络状况有所延迟。

写剪贴板 writePasteboard、读剪贴板 readPasteboard

调用方法

函数	writePasteboard、readPasteboard
函数名称	写剪贴板、读剪贴板
函数简介	读写系统剪贴板。
方法 1	writePasteboard(文本型 string);
返回值 1	无
方法 2	string = readPasteboard();
返回值 2	文本型 string

序号	名称	类型	说明
1	string	文本型	写入或读出的剪贴板字符串

调用示例

--示例 1 从剪贴板中写出到编辑框
string = readPasteboard();	--读出剪贴板内容
mSleep(500);	--延迟 0.5 秒
inputText(string);	--写出字符串

--示例 2 从文件中读入一行并储存到剪贴板
file = io.open("test.txt" ,"r");	--以只读方式打开文件
if file then	--如果打开成功
writePasteboard(file:read());	--储存到剪贴板
file:close();	--关闭文件
else
syslog("Cannot open: test.txt");
end

注意事项

• 该函数将覆盖系统剪贴板，如有重要数据储存在剪贴板请及时备份。

获取触动精灵版本号 getTSVer、获取系统版本号 getOSVer

调用方法

函数	getTSVer、getOSVer
函数名称	获取触动精灵版本号、获取系统版本号
方法 1	version = getTSVer();
方法 2	version = getOSVer();
返回值	文本型 version

序号	名称	类型	说明
1	version	文本型	返回的触动精灵版本号或系统版本号 如：1.8.0、7.1.1

调用示例

--示例 1 判断版本是否符合要求
tsver = getTSVer();	--获取触动精灵版本
tsint = tonumber(string.sub(version, 1, 1)..string.sub(version, 3, 3)..string.sub(version, 5, 5));	--转化为数字版本号[1]
sysver = getOSVer();	--获取系统版本
sysint = tonumber(string.sub(version, 1, 1)..string.sub(version, 3, 3)..string.sub(version, 5, 5));	--转化为数字版本号
if tsver >= 170 and sysver >= 701 then
init("0",0);
else
dialog("本脚本不支持您的触动精灵或系统版本，请尽快升级！", 5);
lua_exit();
end

备注

^[1]string.sub 为 Lua 基本函数，属于字符串处理函数库，详情请参阅相关文档。
tonumber 为 Lua 基本函数，属于类型转换函数库，详情请参阅官方文档。

获取前台应用 frontAppBid

调用方法

函数	frontAppBid
函数名称	获取前台应用
函数简介	获取前台应用的 Bundle ID。
方法	bid = frontAppBid();
返回值	文本型 bid

序号	名称	类型	说明
1	bid	文本型	返回前台应用程序的 Bundle ID 若无应用处于前台，则返回空字符串

调用示例

--示例 1 获取前台应用并初始化
bid = frontAppBid();
init(bid,0);
--亦可写作
init("0",0);

--示例 2 检查指定应用是否开启
bid = frontAppBid();
if bid ~= "com.apple.mobilesafari" then
dialog("请打开 Safari 再运行该脚本！", 5);
mSleep(3000);
lua_exit();
end

注意事项

• Bundle ID 的获取方法参见"初始化"一章。

设置来电暂停 luaExitIfCall

调用方法

函数	luaExitIfCall
函数名称	设置来电暂停
函数简介	设置电话拨入时停止脚本运行的标识。
方法	luaExitIfCall(逻辑型 flag);
返回值	无

序号	名称	类型	说明
1	flag	逻辑型	状态标识 true == 开启来电暂停 false == 关闭来电暂停

调用示例

--示例
luaExitIfCall(true);
init("0",0);

注意事项

1. 该函数在脚本中可使用多次，以调整配置。
2. 当有电话拨入时，检查来电暂停状态标识，若为 true，则立即终止脚本；若为 false，则继续运行脚本。
3. 该函数仅 iPhone 有效。

清除钥匙串 clearKeyChain

调用方法

函数	clearKeyChain
函数名称	清除钥匙串[1]
函数简介	清除指定应用储存在系统钥匙串中的信息。
方法	clearKeyChain(文本型 bid);
返回值	无

序号	名称	类型	说明
1	bid	文本型	返回欲清除钥匙串的应用程序的 Bundle ID

调用示例

--示例 清除前台应用的钥匙串
clearKeyChain(frontAppBid());

注意事项

• 钥匙串一经清除，不可恢复，请妥善保管您的隐私信息。

备注

^[1]钥匙串，是 iOS 提供给应用程序，允许自动记住密码以及重要信息的安全存储数据库，钥匙串一旦清除，该应用中记住的密码等机密信息全部清空。

多点找色 findMultiColorInRegionFuzzy

调用方法

函数	findMultiColorInRegionFuzzy
函数名称	多点找色
函数简介	在指定区域，根据颜色以及其周边点的颜色，寻找符合条件的点的坐标，支持模糊查找。
方法	x, y = findMultiColorInRegionFuzzy(整型 color, 文本型 posandcolor, 整数型 degree, 整数型 x1, 整数型 y1, 整数型 x2, 整数型 y2);
返回值	整数型 x, y

序号	名称	类型	说明
1 ~ 2	x, y	整数型	返回符合条件的点的坐标
3	color	整型	欲寻找的颜色
4	posandcolor	文本型	周边点颜色参数
5	degree	整数型	寻找精度，范围： 1 ~ 100 100 为完全匹配
6 ~ 7	x1, y1	整数型	欲寻找的区域左上角顶点坐标 (x1, y1)
8 ~ 9	x2, y2	整数型	欲寻找的区域右下角顶点坐标 (x2, y2)

进阶指导

当我们使用“区域模糊找色”函数时，常常会因为屏幕上有大量符合指定颜色的点而找不到需要的坐标。该函数通过在寻找到一个符合指定颜色 color 的坐标后，进一步确认其周边点坐标的方式，来确定准确目标。例如，现在我们在图像上找到了我们需要的一个按钮，这个按钮的图案是不变的，但是它的整体位置却会在整个屏幕上变化，现在我们想要在脚本运行时得到其坐标。
我们首先在该按钮上找到一个点。

这个点的颜色为 0x181F85^[1]，坐标为 (268, 802)。
记录下来，接着找这个按钮上的另外一个点。

这个点的颜色为 0x00BBFE，坐标为 (297, 803)，相对于第一个点的坐标^[2]为 (29, 1)。
记录下来，接着找这个按钮上的第三个点和第四个点。
第三个点的颜色为 0x0B6BBE，坐标为 (371, 798)，相对于第一个点的坐标为 (103, -4)。
第四个点的颜色为 0x150972，坐标为 (333, 811)，相对于第一个点的坐标为 (65, 9)。

现在我们找到了需要的四个点：

1. 0x181F85, (268, 802), (0, 0);
2. 0x00BBFE, (297, 803), (29, 1);
3. 0x0B6BBE, (371, 798), (103, -4);
4. 0x150972, (333, 811), (65, 9);

制作成表格就是：

序号	颜色	坐标	相对坐标
0	0x181F85	(268, 802)	(0, 0)
1	0x00BBFE	(297, 803)	(29, 1)
2	0x0B6BBE	(371, 798)	(103, -4)
3	0x150972	(333, 811)	(65, 9)

现在我们可以把它写成多点找色的格式了：

--示例 多点找色
x, y = findMultiColorInRegionFuzzy(0x851F18, "29|1|0x00BBFE,103|-4|0x0B6BBE,65|9|0x150972", 100, 0, 0, 640, 960);

按照这张图上的情况，返回的 (x, y) 就应该是 (268, 802) 了。
即使这个按钮平移了，这个点的坐标变了，也可以寻找到其准确位置。

注意事项

1. posandcolor 参数中的坐标为相对坐标。
2. 多点找色的代码可直接用触动精灵取色工具生成，其使用方法参见图文教程。

备注

^[1] 颜色值的十六进制文本中，其顺序为 BGR。
^[2] 相对于第一个点的坐标，即用这个点的横坐标、纵坐标分别减去第一个点的横坐标、纵坐标，可以为负数。

远程光学字符识别 cloudOcrText

调用方法

函数	cloudOcrText
函数名称	远程光学字符识别
函数简介	使用云端平台，识别指定区域所呈现的文字。
方法	text = cloudOcrText(文本型 ip, 整数型 length, 整数型 type, 整数型 x1, 整数型 y1, 整数型 x2, 整数型 y2);
返回值	文本型 text

序号	名称	类型	说明
1	text	文本型	返回的识别结果
2	ip	文本型	接口 IP 地址
3	length	整数型	文字长度
4	type	整数型	文字类型
5~6	x1, y1	整数型	欲寻找的区域左上角顶点坐标 (x1, y1)
7~8	x2, y2	整数型	欲寻找的区域右下角顶点坐标 (x2, y2)

进阶指导

“本地光学字符识别”由于特征库、性能的限制，识别速度慢、识别率也比较差。该函数可以解决这一问题。

进阶指导 1

cloudOcrText 函数必须要安装 OCR 插件 CloudOcrPlugin.dylib，把插件放到 plugin 目录[1]下，另外必须要运行服务程序并保证手机和服务程序所在 PC 在同一局域网网段内。

--示例
yzm = cloudOcrText("192.168.0.1", 2, 40, 0, 0, 1024, 768);

1. 192.168.0.1 这块填写识别服务工具的服务器地址，在电脑上运行以后可以看到这个地址；
2. 2 这里是验证码的长度，是几就写几；
3. 40 这里是验证码的类型，具体需要去打码兔的官网查询。

后面就不用说了，是验证码出现的范围，左上角顶点坐标，右下角顶点坐标，形成一个矩形范围。
识别了以后会把结果赋值给 yzm 这个变量，后续我们可以调用 inputText 函数来输入这个识别的结果。

参数里既然要写服务器局域网地址，那么这里就会出现一个问题，很多同学会问了，作为一个专业脚本作者，如果把服务器地址写死在脚本里，那么如果加密以后出售给客户，那么客户的局域网地址变了怎么办，我是不是每次都要重新更改这个参数并且重新加密后再发给客户。这显然是非常不科学的，这里给大家介绍一个小技巧，这也是写这篇小教程的另一个目的。

我们可以把这个参数用一个变量来代替，然后把这个变量放在外部不加密的文件里，并且在加密的主文件里引用这个外部文件。

首先，我们先建立一个配置文件，我们把他命名为 CFG.lua，脚本内容如下：

Yzm_ip = "192.168.0.1";

写好这一行（没错，就只有一行），保存。再打开我们的主文件，在头部加入一行：

require "CFG";

再把刚才我们调用的云端 OCR 函数那里也改一下：

yzm = cloudOcrText(Yzm_ip, 2, 40, 0, 0, 1024, 768);

好了，大功告成，就这么简单，这样用户可以任意更改 CFG 里的 IP 地址而不用再喋喋不休的缠着你，让你为他提供修改服务端 IP 地址。

有心的同学可能就会举一反三了，我们可以很好的利用 require 来实现很酷的脚本，把一些用户经常需要更改的参数变量全部放到外部文件里，然后在主文件调用，方便用户，方便自己。

谨以此文献给那些还在手动输入验证码的朋友，献给那些还在纠结本地 OCR 的识别率是多么坑爹的兄弟。

进阶指导 2

本次触动精灵云 OCR 插件更新增加了对 HaoAi 打码平台的支持，本平台无需使用电脑端即可完成验证码的获取及发送，本次更新影响触动内置函数 cloudOcrText，下面说一下用法。

看一下原来的例子：

yzm = cloudOcrText("192.168.0.1", 2, 40,377,325,490,399);

• 192.168.0.1 这部分是使用打码兔平台，需要运行电脑端的IP地址；

现在如果使用新的好爱平台，因为不需要使用电脑端了，这里需要改为：

• ...#你在好爱注册的用户名|密码串

yzm = cloudOcrText("...#username|系统生成的上传密码串", 0, 40, 377, 325, 490, 399);	--密码串注册过后登录进去可以看到

1. 0 这里代表长度参数，如果使用好爱平台这个参数可以不用管，填 0 即可；
2. 40 代表类型，关于具体的类型参数请查阅好爱平台。

后面就是验证码区域的左上角顶点坐标和右下角顶点坐标。
本次更新以后，同时支持打码兔和好爱平台，用户可以根据自己的需要和喜好选择。

进阶指导 3

更新打码兔平台，不再需要电脑端。例子：

text = cloudOcrText("...#username#password", len, type, x1, y1, x2, y2);

1. username 打码兔登陆用户名（需用户自行注册）；
2. password 打码兔登陆密码；
3. len 识别验证码长度，不确定可以写 0；
4. type 验证码类型 ID；

验证码类型 ID 可在打码兔网站查询。

注意事项

1. 打码兔 获取验证码如返回"NET_ERROR" 则说明有错误，未能正确获取答案。
2. 好爱 获取验证码如返回"HAOI_ERROR" 则说明有错误，未能正确获取答案。
3. 小爱 获取验证码如返回"XIAOI_ERROR" 则说明有错误，未能正确获取答案。

参考资料

• 触动精灵云 OCR 工具可在附录中找到。

设置远程光学字符识别图片比例 cloudOcrImageScale

调用方法

函数	cloudOcrImageScale
函数名称	设置远程光学字符识别图片比例
函数简介	将发送给远程 OCR 平台的待识别图片以一定比例缩小，加快传输速率。
方法	cloudOcrImageScale(整数型 scale);
返回值	无

序号	名称	类型	说明
1	scale	整数型	缩放比例 100 为不缩放，最小值为 10

调用示例

--示例
cloudOcrImageScale(50);	--以 50% 比例缩放

注意事项

1. 在调用“远程光学字符识别”函数前调用，可将发送给平台的图片按比例缩小。
2. 一般用来解决 iPad 3 及以上的高分设备截图过大难以传输的问题。

载入插件 loadPlugin、执行插件函数 callPlugin、释放插件 unloadPlugin

调用方法

函数	loadPlugin、callPlugin、unloadPlugin
函数名称	载入插件、执行插件函数、释放插件
函数简介	调用外部插件完成指定任务。
方法 1	loadPlugin(文本型 plugin_name);
返回值 1	无
方法 2	return = callPlugin(文本型 plugin_name, 文本型 func_name, 文本型 params);
返回值 2	文本型 return
方法 3	unloadPlugin(文本型 plugin_name);
返回值 3	无

序号	名称	类型	说明
1	plugin_name	文本型	插件文件名 插件必须放置于 plugin 目录[1] 后缀名默认为 .dylib，不允许填写在参数中
2	func_name	文本型	插件中的函数名
3	params	文本型	传递给插件函数的单参数

调用示例

--示例
-- httpGet 使用 Get 方式访问个网址，返回获取的网页数据
a = callPlugin("NetworkTools", "httpGet", "...");

-- httpPost 使用 Post 方式访问网址，返回获取的网页数据，URL 和参数对用 $ 分割
a = callPlugin("NetworkTools", "httpPost", "...$a=1&b=2");

-- 自定义 UA 和 Cookie，需要在 httpGet 和 httpPost 调用前调用
callPlugin("NetworkTools", "httpSetUA", "aaa");
callPlugin("NetworkTools", "httpSetCookie", "bbb");

注意事项

• 插件必须放置在指定目录，文件名必须为 #plugin_name#.dylib，作为参数被调用时，只需填写 #plugin_name#。
• 插件编写类名必须和插件文件名保持一致，如 TSPlugin，且不和现有插件冲突。
• params 为函数传入的参数拼接字符串，参数只能是可字符串化的数字、文本、逻辑型等。即传递多个参数需要合并成一个字符串参数共同传递，由插件进行分离处理。

1. 例如：return = callPlugin("TSMathPlugin", "add", "20, 40");
2. 插件接收到单个参数 "20, 40" 后，分割处理成 "20" 和 "40"，相加返回结果为 "60"。

• 插件使用完毕后必须使用释放函数，防止内存泄漏^[2]。

备注

^[1] 路径：/var/mobile/Media/TouchSprite/plugin。
^[2] 内存泄漏也称作“存储渗漏”，用动态存储分配函数动态开辟的空间，在使用完毕后未释放，结果导致一直占据该内存单元，直到程序结束。