触动精灵开发手册

标签： TouchSprite TS 触动精灵

---

2015年4月 当前手册适用于 版本 2.1.0

目录

前言

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

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

用户在阅读本函数说明前,请参考 Lua 的官方手册以及相关资料,学习以下基本语法：

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

       本说明仅供初等文化水平以上的、了解计算机编程基本原理的个体学习与参考，并不适用于零基础的编程入门者学习编程基本知识。严禁用于商业以及非法目的，严禁转载、抄袭、未经许可地引用。
为了便于解释和描述，本说明中采用了一些非专业的描述与形容方法（如：整数型），敬请理解。因编写校对仓促，如有错误欢迎及时指正，本文中的示例仅供函数参考，不要直接用于脚本中。

重要提示：
Lua官方手册：http://www.lua.org/manual/5.2/
Lua中文开发手册：http://book.luaer.cn/
触动精灵的脚本开发、存储过程必须使用 UTF-8 文本编码，如果您出现脚本中文无法正常显示与处理，请在您使用的编辑器或 IDE 中设置文本编码为 UTF-8，谢谢。

安装触动精灵

通过Cydia源安装

【1】确保您的设备已越狱，点击桌面图标进入Cydia软件源，如图选择下方 “软件源” 按钮

【2】点击右上角 “编辑” 按钮

【3】点击编辑后，左边按钮会变为 “添加”，点 “添加”，在弹出窗口输入官方源地址：apt.touchsprite.com

【4】在Cydia首页 “软件源” 中，找到已添加好的官方源，猛戳

【5】在 “分类” 列表里，选择 “触动精灵” ，戳

【6】选择 “触动精灵” ，再戳！继续点击右上角 “安装” 并 “确认”，耐心等待安装完毕，如安装完毕未自动重启设备，请手动重启设备以完成最后安装步骤

通过命令行安装

首先确保您的iOS设备已越狱、并正确安装了 OpenSSH 及 Apple File Conduit "2"

【1】将下载好的DEB安装包使用第三方管理工具（PP助手、iTools、iFunbox等）拷贝至设备根目录，这里我们以iFunbox为例，其他工具操作类似。

PP助手：http://pro.25pp.com/
iTools: http://www.itools.cn/
iFunbox: http://www.ifunbox-cn.com/

       将设备通过数据线连接至电脑，打开iFunbox，点击左侧文件系统，为了方便安装，我们将DEB文件直接放入根目录（将文件直接拖入右边即可）

【2】在电脑上打开 Putty，下载地址：http://pan.baidu.com/s/1qWp3j7u
正确填写iOS设备的IP地址（可在设置 – WIFI – 当前连接无线网络详细信息中查看），填好后点击 Open

【3】连接上设备后依次输入下面命令：

root             （输入登陆用户 回车）
alpine           （alpine是root默认密码。如果您改了root密码请填写您修改后的。输入密码不显示）
cd /             （cd命令，进入根目录，注意cd后面有一个空格）
dpkg -i *.deb    （批量安装该目下所有deb）
或者dpkg -i TouchSprite_2.1.0.deb （你要安装的deb文件的完整名字）
最后安装完输入： reboot（重启）

---

学习前的准备

       工欲善其事，必先利其器，在学习触动精灵脚本编写前我们需要下载安装一些辅助工具来完成脚本编写，包含但不限于以下工具：

脚本编辑器：ZeroBrane Studio 版本 1.0
下载地址：http://pan.baidu.com/s/1sjwSLit

支持自动补全、函数提示、关键字高亮、自动缩进等常用功能，已内置所有至最新 2.1.0 版本触动精灵扩展函数，推荐使用。

抓色器：TSColorPicker 版本 1.4.2
下载地址：http://pan.baidu.com/s/1i33oXDj

一个趁手的抓色器可以让你的脚本开发过程变的轻松愉快，在此强烈推荐由苏泽制作的触动抓色器，快捷抓点、一键生成代码、远程抓屏，让你如虎添翼。具体使用方法请阅读压缩包内附带的说明（远程抓屏功能需使用触动精灵 2.1.0 以上版本）。

网络日志：TSLogConsole 版本 1.0
下载地址：http://pan.baidu.com/s/1gd5mKTX

配合触动精灵可将日志直接通过局域网发送到电脑端，帮助你在开发过程中对脚本进行调试，具体使用方法请参看 “函数：initLog” 一章。

---

函数：init

函数名称：初始化
函数功能：脚本使用触摸函数前必须调用，以指定应用程序以及坐标系。
函数方法：init(文本型 bid, 整数型 rotate);
返回值：无

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

脚本实例：

init("com.apple.weather", 0);   --以  "com.apple.weather"  竖屏初始化
init("0", 1);                   --以当前应用 Home 键在右边初始化

参考资料：
Bundle ID 的获取方法
1、在触动精灵右上角的”更多”、”应用ID查询”中能查看到应用程序的Bundle ID；
2、使用 iFile、PP助手等软件可查看应用文件夹下的 Info.plist，其中的 CFBundleIdentifier 即为该应用的Bundle ID。

函数：touchDown、touchMove、touchUp

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

参数	类型	说明
index	整数型	手指序号（可省略）
x,y	整数型	屏幕坐标

脚本实例：
示例 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循环从起始点连续横向移动到终止点
    touchMove(1, 150 + i, 550); 
    mSleep(150);        --延迟
end
touchUp(1, 150 + 200, 550); --在 (350, 550) 抬起

示例 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);   --抬起手指1
touchUp(2, 300 + 100, 500 + 100);   --抬起手指2

名词解析：

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

函数：inputText

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

参数	类型	说明
string	文本型	将输入的文本以及控制字符

脚本实例：
输入欢迎文本并发送

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

注意事项：

1. 使用该函数前，必须先点击输入框获取焦点（指使当前的输入光标停留在某一输入框中）。
2. 如果设备系统版本为IOS 7，\r无法使用，使用\b需安装触动精灵 1.6.9 及以上版本。
3. 仅在 iOS 7 上，可使用”#ENTER#”作为回车，相当于点击虚拟键盘上的”Done”，需要注意的是，并不是所有输入框都可以使用此功能，在某些应用当中可能导致目标应用崩溃。
4. 该函数不支持第三方输入法(指百度输入法、搜狗输入法等)，请切换到系统内置输入法方可使用。
   对于弹出的窗口，需要先初始化再使用该函数，例如 App Store登录窗口(该窗口Bundle ID 为”com.apple.springboard”)。
5. 控制字符包括 \b、\n、\r、#ENTER#。

函数：getColor、getColorRGB

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

参数	类型	说明
x，y	整数型	将获取颜色值的屏幕坐标

返回值	类型	说明
color	整数型	该点的十进制颜色值BGR
color_r, color_g, color_b	整数型	该点颜色的RGB值

脚本实例：
1.如果某点符合某颜色则点击

color = getColor(100, 100); --获取(100,100)的颜色值，赋值给color变量
if color == 0xffffff then   --如果该点的颜色值等于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）取色。
   取色工具可以在附录中找到下载地址。
   常见颜色表：http://www.114la.com/other/rgb.htm

名词解析

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

函数：mSleep

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

参数	类型	说明
interval	整数型	单位为毫秒，脚本暂停执行的时间长度

脚本实例：
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 秒 (s) = 1000 毫秒 (ms)。

函数：findColorInRegionFuzzy

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

参数	类型	说明
color	整数型	将要找的十六进制颜色值
degree	整数型	寻找精度，范围：1 ~ 100，当是100时为完全匹配
x1，y1	整数型	欲寻找的区域左上角顶点屏幕坐标
x2，y2	整数型	欲寻找的区域右下角顶点屏幕坐标

返回值	类型	说明
x，y	整数型	找到的点坐标，如未找到则返回 -1，-1

脚本实例：
1.精确寻找指定区域中，指定颜色的坐标，并按下
–寻找符合条件的点

x, y = findColorInRegionFuzzy(0x112233, 100, 50, 50, 300, 300); 
if x ~= -1 and y ~= -1 then  --如果在指定区域找到某点符合条件
    touchDown(1, x, y);      --那么单击该点
    touchUp(1, x, y);
else                         --如果找不到符合条件的点
    dialog("未找到符合条件的坐标！",0);
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("未找到符合条件的坐标！",0);

注意事项：

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

函数：findImageInRegionFuzzy

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

参数	类型	说明
picpath	文本型	将要寻找的图片文件名
degree	整数型	寻找精度，范围：1 ~ 100，当是100时为完全匹配
x1，y1	整数型	欲寻找的区域左上角顶点屏幕坐标
x2，y2	整数型	欲寻找的区域右下角顶点屏幕坐标
alpha	整数型	忽略的颜色值（透明色） 若无请填 0

返回值	类型	说明
x，y	整数型	找到的图片的左上角顶点坐标，如未找到则返回 -1，-1

脚本实例：
1.精确寻找指定区域中，指定图片的位置
–寻找符合条件的图片（假设图片的背景颜色为白色）

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("未找到符合条件的坐标！",0);
end

注意事项：

1. 不推荐此函数，对于找小型图片精度较差。
2. 默认图片路径为 /var/mobile/Media/TouchSprite/res（参数中无需填写完整路径），自建目录请填写相对路径。
3. 忽略的颜色值指将要寻找的图片的背景颜色，即在屏幕画面上不匹配寻找对象的背景颜色。

函数：findMultiColorInRegionFuzzy

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

参数	类型	说明
color	整型	欲寻找的参照点颜色
posandcolor	文本型	周边点颜色参数
degree	整数型	寻找精度，范围：1 ~ 100，当是100时为完全匹配
x1, y1	整数型	欲寻找的区域左上角顶点屏幕坐标
x2，y2	整数型	欲寻找的区域右下角顶点屏幕坐标

返回值	类型	说明
x, y	整数型	返回符合条件的参照点的坐标，如未找到则返回 -1，-1

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

我们首先找到一个点：
这个点的颜色为 0x181F85，坐标为 (268, 802)。
记录下来，接着找这个按钮上的另外一个点：
这个点的颜色为 0x00BBFE，坐标为 (297, 803)，相对于第一个点的坐标为 (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)

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

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. 多点找色的代码可直接用触动精灵取色工具生成，其使用方法参见图文教程。
3. 颜色值的十六进制文本中，其顺序为BGR。
4. 相对于第一个点的坐标，即用这个点的横坐标、纵坐标分别减去第一个点的横坐标、纵坐标，可以为负数。

函数：snapshot

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

参数	类型	说明
picpath	文本型	将要寻找的图片文件名
x1，y1	整数型	欲截取的区域左上角顶点屏幕坐标
x2，y2	整数型	欲截取的区域右下角顶点屏幕坐标
quality	数字型	当截图格式选为jpg时，可用此参数控制图片质量，此参数值为大于0且小于等于1的值

脚本实例：
–全屏截图（iPhone 5, 5S），并以当前日期为文件名保存

current_time = os.date("%Y-%m-%d", os.time());
snapshot(current_time..".png", 0, 0, 639, 1135); --以时间戳命名进行截图
snapshot(current_time..".jpg", 0, 0, 639, 1135，0.5); --使用jpg格式截图，并设置图片质量为0.5

注意事项：

1. 保存图片的格式可为 bmp, jpg, png，因为 png 是 iOS 中最常见的格式，所以推荐选择 png。
2. 截图时，如使用全屏截图，右下角顶点坐标最大为 (639, 1135)，否则会出现越界错误。
3. 默认图片路径为 /var/mobile/Media/TouchSprite/res，自建目录请填写相对路径，文件相同将会被覆盖
4. 本文实例中 os.date 与 os.time 为 Lua 基本库函数，请查阅附录 Lua 操作系统函数库。
5. “..” 为字符串连接操作符，可以将字符串变量、常量连接在一起。
6. 本文实例中 640 * 1136 为 iPhone 5, 5S 等设备的分辨率，实际使用中请根据运行设备替换为对应值。
7. quality参数仅在触动精灵版本高于 2.0.9 时方可使用。

函数：dialog

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

参数	类型	说明
text	文本型	提示信息，将在设备屏幕上以弹窗形式显示
time	整数型	提示信息显示的时间，不限时间请填0

脚本实例：
1.欢迎使用

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

注意事项：

1. time 参数时间一般在 2 秒以上，否则出现时间太短看不清楚。
2. 该函数仅供呈现提示信息给用户，不可接收返回值。
3. 该函数所产生的提示窗口显示的时候会影响当前屏幕取色，请在合理的位置使用该函数。
4. 关于转义字符：\n 为换行，请查阅 Lua 转义字符表。

函数：dialogRet

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

参数	类型	说明
Text	文本型	提示信息
cbtn	文本型	默认按钮标题，不需要请填 “”
btn1	文本型	可选按钮 1，不需要请填 “” 或 0
btn2	文本型	可选按钮 2，不需要请填 “” 或 0
time	整数型	提示信息显示的时间，不限时间请填 0

返回值	类型	说明
choice	整数型	返回用户按下按钮的序号 cbtn == 0；btn1 == 1；btn2 == 2

脚本实例：
1.选择性别（双选）

choice = dialogRet("请选择您的性别：", "男", "女", "", 0);

2.选择性别（三选）

choice = dialogRet("请选择您的性别：", "男", "女", "人妖", 0);
if choice == 0 then      --男
    dialog("你好，帅哥。",0);
    mSleep(1000);
elseif choice == 1 then  --女
    dialog("你好，美女",0);
    mSleep(1000);
else                     --人妖
    dialog("人妖不允许使用该脚本。",0);
    mSleep(1000);
    lua_exit();          --退出脚本
end

3.请阅读许可协议

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

注意事项：

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

函数：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 返回用户输入的文本

参数	类型	说明
title	文本型	提示标题
format	文本型	编辑框中浅色的提示文字，如果需要两个编辑框，则将提示文字用”#”分割
btn	文本型	确认按钮标题

返回值	类型	说明
text_a,text_b	文本型	返回用户输入的文本

脚本实例：
1.输入姓名

::getInfo:: --设置跳转标签
text_a = dialogInput("请输入您的姓名", "在这里输入姓名", "确认");
mSleep(1000);

2.输入姓名和年龄

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;                      --返回重新填写
end

注意事项：

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

名词解析：

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

函数：showUI

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

参数	类型	说明
ui_json	文本型	自定义界面json格式字符串调用时字符串需经过压缩与转义

返回值	类型	说明
ret	整数型	1 == 确认输入；0 == 取消输入
input_(*)	文本型	返回用户输入的多项数据

1. 什么是 json
json 就是一串字符串，在该函数中，我们用它来创建界面上的一系列会使用特定的符号标注的元素：
{} 双括号表示对象
[] 中括号表示数组
"" 双引号内是属性或值
： 冒号表示后者是前者的值
所以 {“name”: “Michael”} 可以理解为是一个包含 name 为 Michael 的对象，而 [{“name”: “Michael”},{“name”: “Jerry”}] 就表示包含两个对象的数组。
当然了，你也可以使用 {“name”:[“Michael”,”Jerry”]} 来简化上面一部分，这是一个拥有 name 数组的对象。
不管是键或文本型的值都要用双引号引起来，所以上面的代码就是 {“name”:”json”}。

2. 调用示例
为了便于 json 的书写，我们通常使用可读性较强的形式；但是为了便于脚本的调用，我们 需要将 json 进行压缩与转义。将上文中的 json 进行转义后，作为字符串放进 showUI 函数的参 数 ui_json 中，例如：

--[[ret, input_1, input_2, ... = showUI("");]]
ret, input_1, input_2, input_3 = showUI("{\"style\":"
.."\"default\",\"views\":[{\"type\":\"Label\",\"text\":"
.."\"settings\",\"size\":25,\"align\":\"center\",\"color\":"
.."\"0,0,255\"},{\"type\":\"RadioGroup\",\"list\":"
.."\"option1,option2,option3,option4,option5,option6,option7\","
.."\"select\":\"1\"},{\"type\":\"Edit\",\"prompt\":\"Test\","
.."\"text\":\"Custom Text\",\"size\":15,\"align\":\"left\","
.."\"color\":\"255,0,0\"},{\"type\":\"CheckBoxGroup\",\"list\":"
.."\"option1,option2,option3,option4,option5,option6,option7\","
.."\"select\":\"3@5\"}]}");

上面的代码看起来有些乱，可能会让新手无所适从，我们换一种形式来写：

MyJsonString = [[
{
  "style": "default",
  "config": "save_111.dat",
  "timer": 10,
  "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"
    }
  ]
}
]]

ret, input1, input2, input3 = showUI(MyJsonString);

json 在线校验格式化、压缩转义工具：http://www.bejson.com/

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

{
"style": "default", "config": "save_111.dat", "width": 400,
"height": 120, "bg": "a.png", "timer": 10, "cancelname": "取消", "okname": "开始",
"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"
},
{
"type": "Image",
"src": "http://www.baidu.com/img/bdlogo.png"
}
]
}

创建一个界面，需要包含 style 与 views 两个主键。
style 表示界面样式，views 数组则包含了界面上的控件；
width 与 height 分别指定了界面的宽和高（像素 pixels），请注意宽度不得低于 400 pixels，高度不得低于 120 pixels；
bg 指定界面的背景图片，相对路径为 res 资源目录，可填写绝对路径；
okname 指定底部确认按钮上显示的文字；
cancelname 指定底部取消按钮上显示的文字；

config表示自动配置文件名，如果存在此键名，则用户点击确认时保存配置到指定文件中。如果配置文件存在，调用该界面会自动载入该文件中的配置；
timer 指定界面在自动配置文件存在的情况下，自动确认UI输入。注意使用此属性必须要设定 config 属性，第一次存储配置文件不存在时，此属性不生效，当配置文件存在时，此属性会在生成UI上进行倒计时，同时用户也可以点击闹钟图标取消倒计时。

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

标签 Label 一共有四种属性：
文本/标题/text
必填，一般来用显示说明文字或者标题，该控件没有任何返回值，只用作显示。
数值/字体大小/size
如果不指定改属性，则默认值为 15。
文本/对齐方式/align
对齐方式 align 可取值为：左对齐 left，右对齐 right，居中 center。
文本/字体颜色/color
字体颜色 color 则使用RGB十进制数值，以英文半角逗号分割。
此类型可支持多行显示，在字符串中插入 \n 可以进行换行，例如：\”测试\n测试 1\n测试 2\”

单选框 RadioGroup 一共有两种属性：
文本/可选项目标题 /list
可选项目标题 list 用英⽂文半角逗号分割。
文本/默认选中项编号/select
默认选中项编号 select 只允许填写一个，序号从 0 开始，与可选项目标题中的顺序保持一致。

编辑框 Edit 一共有五种属性：
文/编辑框提示文本/prompt
编辑框提示文本prompt为编辑框中无任何内容时显示的底色文本。
文本/编辑框默认内容/text
界面载入时已经存在于编辑框中的文本。
数值/字体大小/size
文本/对齐方式/align
文本/字体颜色/color

多选框 CheckBoxGroup，又称作检查框，一共有两种属性：
文本/可选项目标题/list
文本/默认选中项编号/select
默认选中项编号 select 允许填写一个或多个，填写多个时以 @ 分割编号。

图片 Image，放置一个图片到 UI 上，属性：
路径/插入图片的路径/src 可以是本地路径或者网络路径
例如：\”type\”:\”Image\”,\”src\”:\”http://www.baidu.com/img/bdlogo.png\” 或者\”src\”:\”1.png\”

以上五种控件均可重复使用，这个界面的样式 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。

名词解析

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

函数：openURL

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

参数	类型	说明
url	文本型	需要打开的目标网址

脚本实例：
–调用系统浏览器打开触动精灵官方论坛

openURL("http://bbs.touchsprite.com");

注意事项：

1. 默认、正常情况下调用的浏览器为 Safari。
2. 欲打开的目标网址必须以 http:// 开头，一些特殊协议也是支持的，如：mailto://, sms://, tel://, ifile://, cydia:// 等等。

函数：initLog、wLog、closeLog

函数名称：初始化日志、写日志、关闭日志
函数功能：配置日志输出地址与方式、写出或发送日志、关闭日志输出连接。
函数方法：
                initLog(文本型 name, 整数型 flag);
                wLog(文本型 name, 文本型 contents);
                closeLog(文本型 name, 文本型 contents);
                输出方式：
                0 == 输出到文件名
                1 == 输出到带时间戳的文件名
                2 == 异步发送到服务器
                3 == 同步发送到服务器
返回值：无

参数	类型	说明
name	文本型	日志文件名或服务器地址与端口 不带后缀，自动添加.log
flag	整数型	可选输出方式
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. 此函数一般用于脚本开发阶段，若脚本开发完成，只需注释掉initLog即可。
4. 日志的编码为 UTF-8，请使用支持 UTF-8 编码的编辑器查看。

函数：syslog

函数功能：输出系统日志 NSLog
函数方法：syslog(文本型 contents);
返回值：无

参数	类型	说明
content	文本型	需要显示的日志内容

注意事项：

1. 该函数将日志输出到 IOS 系统级日志中，请使用 iTools 或 XCode4 查看。 2.
2. 当使用同步消息传送时，脚本需等待日志已经到达服务端才继续执行下面的指令。
3. 当使用异步消息传送时，调用者在发送消息以后可以不用等待响应，可以接着处理其他任务。 即发送日志无需等待发送完成即可继续执行。
4. 注释的操作符形式为 –…… 或 –[[……]] ，可将用于说明的代码写入脚本以便开发时理解。
5. XCode 为 Apple 专为 Mac OS X 设计的开发平台。
6. 日志工具下载地址可在附录中找到。

函数：playAudio

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

参数	类型	说明
filename	文本型	音频文件名,支持 mp3、m4a、、m4r、ogg、wav

脚本实例：

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

注意事项：

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

函数：ocrText

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

参数	类型	说明
x1, y1	整数型	欲识别的区域左上角顶点屏幕坐标
x2, y2	整数型	欲识别的区域右下角顶点屏幕坐标
language	整数型	语言选择 0 == 英文 1 == 中文

返回值	类型	说明
text	文本型	返回的识别结果

脚本实例：

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

注意事项：

1. 该函数精确度较低，仅能准确识别白底黑正楷字，不推荐使用。
2. 需要相应的识别库以及识别插件：
   I. 将识别库（英文 eng.traineddata，简体中文 chi_sim.traineddata）放置于 /var/mobile/Media/ TouchSprite/tessdata 目录下；
   II. 将插件（OcrPlugin.dylib）放置于 /var/mobile/Media/TouchSprite/plugin 目录下；
3. OCR 识别库下载地址可在附录中找到。

函数：keepScreen

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

参数	类型	说明
flag	逻辑型	保持开关

脚本实例：
遍历屏幕区块

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 ，高分屏上脚本取色速率高达 50x。在执行大量静态图像操作时，请务必使用该函数优化脚本性能。
2. 该函数一般用于画面变动节奏较慢，但需要根据大量取色、找色来完成计算和操作的脚本中，例如”天天爱消除”、”天天星连萌”这样的游戏。

参考资料 “天天爱消除”、”天天星连萌”脚本开源范例：
http://bbs.touchsprite.com/forum.php?mod=viewthread&tid=1314

名词解析：

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

函数：runApp、closeApp

函数名称：运行应用、关闭应用
函数功能：打开或关闭一个应用程序。
函数方法：
                flag = runApp(文本型 bid);
                closeApp(文本型 bid);
返回值：无

参数	类型	说明
bid	文本型	应用程序的Bundle ID

返回值	类型	说明
flag	整数型	0 == 应用启动成功；非0 == 应用启动失败

脚本实例：
打开内置天气应用，然后退出

r = runApp("com.apple.weather");    --启动应用 
mSleep(10 * 1000);
if r == 0 then
    closeApp("com.apple.weather");  --退出应用
else
    dialog("启动失败",3);
end

注意事项：

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

函数：getScreenSize

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

返回值	类型	说明
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

注意事项：

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

函数：getDeviceType

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

返回值	类型	说明
type	整数型	设备类型 0 == iPod Touch；1 == iPhone；2 == iPad

脚本实例：
根据分辨率判断设备类型

types = getDeviceType(); 
if types == 0 then
    --iPod Touch
elseif types == 1 then
    --iPhone
elseif types == 2 then
-   -iPad
end

函数：getDeviceID

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

返回值	类型	说明
id	文本型	触动精灵32位设备号

脚本实例：
获取设备号并输出到日志

id = getDeviceID(); 
syslog("Device ID: "..id);

注意事项：

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

函数：lua_exit

函数名称：退出脚本、结束函数
函数功能：直接终止脚本。
函数方法：lua_exit();
返回值：无

脚本实例：
弹出许可协议，若不同意则退出脚本

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

注意事项：

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

函数：pressHomeKey

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

参数	类型	说明
flag	整数型	IOS6及其以下系统 0 ==按下；1 ==抬起；IOS7 只能填0

脚本实例：
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 键的操作。
3. 如需在 IOS 7 以上版本中使用双击功能请使用函数 doublePressHomeKey ，具体用法请参照对应章节。

函数：doublePressHomeKey

函数名称：双击HOME键
函数功能：模拟用户双击HOME键的操作。
函数方法：doublePressHomeKey();
返回值：无

脚本实例：
1.双击HOME键打开后台

doublePressHomeKey();

注意事项：

1. 此函数需触动精灵 2.x 以上版本支持
2. 此函数仅能用于 IOS 7 或以上版本

函数：isFrontApp

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

参数	类型	说明
bid	文本型	待检测的应用程序 Bundle ID

返回值	类型	说明
flag	整数型	0 == 不在前台运行；1 == 在前台运行

脚本实例：
1.监听应用状态

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

注意事项：

1. Bundle ID 的获取方法参见”初始化”一章。

函数：resetIDLETimer

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

函数实例：
保持屏幕常亮

while true do
    mSleep(30 * 1000);  --等待 30 秒
    resetIDLETimer();   --重置锁屏计时
end

注意事项：

1. 该函数可能会减少屏幕、电池寿命，请谨慎使用。
2. while true do … end 为死循环代码，一般不建议这样使用。除非强行终止运行，否则该脚本不会自动停止，如果用户忘记终止脚本，将会缩减电池寿命。

函数：vibrator

函数名称：手机振动，震动
函数功能：使手机振动一次。
函数方法：vibrator();
返回值：无

函数实例：
警报

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

注意事项：

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

函数：lockDevice

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

脚本实例：
结束并锁定设备

lockDevice(); 
lua_exit();

注意事项：

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

函数：deviceIsLock

函数名称：设备锁定状态
函数功能：判断当前设备的屏幕锁定状态。
函数方法：flag = deviceIsLock();
返回值：整数型 flag

返回值	类型	说明
flag	整数型	0 == 表示设备未锁定；非0 == 表示设备已锁定

脚本实例：
判断设备是否锁定

flag = deviceIsLock();
if flag == 0 then
    dialog("未锁定",3);
else
    unlockDevice(); --解锁屏幕
end

注意事项：

1. unlockDevice 函数功能是解除当前设备屏幕锁定状态，具体使用方法参照对应章节。

函数：unlockDevice

函数名称：解锁设备
函数功能：解除屏幕锁定状态。
函数方法：unlockDevice();
返回值：无

脚本实例：
解锁设备

flag = deviceIsLock(); --判断屏幕是否锁定
if flag == 0 then
    dialog("未锁定",3);
else
    unlockDevice();    --解锁屏幕
end

注意事项：

1. 如您的设备设备了锁屏密码，则此函数仅能唤醒屏幕。

函数：getNetTime

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

返回值	类型	说明
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

注意事项：

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

函数：writePasteboard、readPasteboard

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

返回值、参数	类型	说明
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

注意事项：

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

函数：getTSVer、getOSVer

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

返回值	类型	说明
version	文本型	返回的触动精灵版本号或系统版本号如：1.8.5、2.0.6

脚本实例：
1.判断版本是否符合要求

tsver = getTSVer();     --获取触动精灵版本
tsint = tonumber(string.sub(version, 1, 1)..string.sub(version, 3,3)..string.sub(version, 5,5));
--转化为数字版本号
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基本函数，属于字符串处理函数库，详情请参阅相关文档。
2. tonumber 为 Lua 基本函数，属于类型转换函数库，详情请参阅官方文档。

函数：frontAppBid

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

返回值	类型	说明
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

注意事项：

1. Bundle ID 的获取方法参见”初始化”一章。

函数：luaExitIfCall

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

参数	类型	说明
flag	逻辑型	状态标识 true == 开启来电暂停；false == 关闭来电暂停

脚本实例：

luaExitIfCall(true); 
init("0",0);

注意事项：

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

函数：clearKeyChain

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

参数	类型	说明
bid	文本型	需要清除的应用程序的 Bundle ID

脚本实例：
清除前台应用的钥匙串

clearKeyChain(frontAppBid());

注意事项：

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

名词解析：

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

函数：setWifiEnable

函数名称：设置无线局域网开关
函数方法：setWifiEnable(逻辑型 flag);
返回值：无

参数	类型	说明
flag	逻辑型	打开WIFI - true;关闭WIFI - false

脚本实例：

setWifiEnable(true);    --打开 Wifi
setWifiEnable(false);   --关闭 Wifi

函数：catchTouchPoint

函数名称：获取用户点击坐标
函数功能：调用该函数后，触动精灵将等待用户完成一次屏幕点击，并返回此次点击的坐标。
函数方法：x,y = catchTouchPoint();
返回值：整数型 x，y

返回值	类型	说明
x,y	整数型	用户点击屏幕的坐标

脚本实例：

dialog("一秒后接收用户一次点击", 0);
mSleep(1000);
x,y = catchTouchPoint(); 
dialog("x:"..x.." y:"..y, 0);

注意事项：

1. 此函数将一直等待用户完成屏幕点击并阻止脚本继续运行。
2. 此函数获取到的坐标为竖屏坐标，横屏情况请自行转换。
3. 本函数有较小的延迟，连续点击时，请勿点击过快。

函数：fakeGPS

函数名称：伪造 GPS 定位信息
函数功能：调用该函数以欺骗当前应用获取到的位置信息。
函数方法：fakeGPS(float x, float y);
返回值：浮点型 x，y

参数	类型	说明
x,y	浮点型	将要伪造位置的经纬度坐标

脚本实例：

a = runApp("com.baidu.map");   --启动百度地图
mSleep(2000);
if a == 0 then                 --启动成功
   fakeGPS(87.1478199292, 43.4912963982);
end

注意事项：

1. 多次调用该函数能多次伪造位置，参数为0, 0时调用该函数能取消伪造功能。
2. 调用此函数需先启动目标应用程序再执行伪装函数。

函数：appBundlePath

函数名称：获取应用程序安装路径
函数功能：调用该函数将返回应用程序的安装路径。
函数方法：path = appBundlePath(文本型 bid);
返回值：文本型 path

参数	类型	说明
bid	文本型	需要获取路径的应用程序的 Bundle ID

返回值	类型	说明
path	文本型	目标应用程序的安装路径

脚本实例：

appPath = appBundlePath("com.baidu.map");   --获取"百度地图"安装路径
dialog(appPath,0);

注意事项：

1. 触动精灵版本 2.0.7 以上方可使用此函数。

函数：appDataPath

函数名称：获取应用程序数据路径
函数功能：调用该函数将返回应用程序的数据路径。
函数方法：path = appDataPath(文本型 bid);
返回值：文本型 path

参数	类型	说明
bid	文本型	需要获取路径的应用程序的 Bundle ID

返回值	类型	说明
path	文本型	目标应用程序的数据路径

脚本实例：

dataPath = appDataPath("com.baidu.map");   --获取"百度地图"数据路径
if dataPath ~= nil then                    --如果获取到路径
    dialog(appPath,0);
end

注意事项：

1. iOS 8 下，并非所有应用都有 data 目录，如返回值为空，说明该应用没有data 目录。
2. 触动精灵版本 2.0.8 以上方可使用此函数。

函数：loadPlugin、callPlugin、unloadPlugin

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

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

脚本实例：
– httpGet 使用 Get 方式访问个网址，返回获取的网页数据

a = callPlugin("NetworkTools", "httpGet", "http://www.baidu.com")

– httpPost 使用 Post 方式访问网址，返回获取的网页数据，URL 和参数对用 $ 分割

a = callPlugin("NetworkTools", "httpPost", "http://www.xxx.com$a=1&b=2")

– 自定义 UA 和 Cookie，需要在 httpGet 和 httpPost 调用前调用

callPlugin("NetworkTools", "httpSetUA", "aaa") 
callPlugin("NetworkTools", "httpSetCookie", "bbb")

注意事项：

1. 插件必须放置在指定目录，文件名必须为#plugin_name#.dylib，作为参数被调用时，只需填写#plugin_name#。
2. 插件编写类名必须和插件文件名保持一致，如TSPlugin，且不和现有插件冲突。
3. params为函数传入的参数拼接字符串，参数只能是可字符串化的数字、文本、逻辑型等。即传递多个参数需要合并成一个字符串参数共同传递，由插件进行分离处理。
   
   • 例如：return = callPlugin(“TSMathPlugin”, “add”, “20, 40”);
   • 插件接收到单个参数 “20, 40” 后，分割处理成 “20” 和 “40”，相加返回结果为 “60”。
4. 插件使用完毕后必须使用释放函数，防止内存泄漏。
5. 插件放置路径：/var/mobile/Media/TouchSprite/plugin。

名词解析：

1. 内存泄漏也称作“存储渗漏”，用动态存储分配函数动态开辟的空间，在使用完毕后未释放，结果导致一直占据该内存单元，直到程序结束。

触动精灵云打码

“本地光学字符识别” 简称本地 OCR 由于特征库、性能的限制，识别速度慢、识别率也比较差。触动精灵提供云打码扩展库来解决这一问题。该扩展库支持如下打码平台：

1. http://www.dama2.com/
2. http://www.uudama.com/
3. http://www.hyocr.com/

使用方法

1. 下载扩展库，将 cloudOcr.so 放入 /User/Media/TouchSprite/lua 或 /User/Media/TouchSprite/plugin 目录，在脚本开头插入 local ocr = require "cloudOcr"; 即可。
2. 安装触动精灵 2.0.9 以上版本，在 更多 – 插件中在线安装，在脚本开头插入local ocr = require "cloudOcr";即可。

函数名称：ocr.cloudOcrText、ocr.cloudOcrReportError、ocr.version
函数功能：云端打码、自动纠错、获取扩展库版本号
函数方法：ret = ocr.cloudOcrText(op);
返回值：返回一个TABLE

参数	类型	说明
platform	文本型	平台类型，打码兔 - dama2；优优云 - uuwise；火眼 - hyocr
x1，y1	整数型	识别区域左上角顶点坐标
x2，y2	整数型	识别区域右下角顶点坐标
type	文本型	打码类型，可在对应平台官网查询
username	文本型	打码平台用户名，需用户去相应平台自行注册
password	文本型	打码平台密码，需用户去相应平台自行注册
length	整数型	打码长度（可选参数），默认为 0
timeout	整数型	超时时间（可选参数），默认为 10 秒
scale	整数型	缩放比例（可选参数），默认为 100，即不进行缩放

返回值	类型	说明
ret.success	布尔型	true 打码成功，false 失败
ret.text	文本型	返回的识别结果，在 success == true 时存在
ret.message	文本型	消息，在 success == fasle 时，返回错误原因
ret.id	TABLE型	打码标识，在 success == true 时存在，用于打码自动纠错

脚本实例：

local ocr = require "cloudOcr";
local op = {
--必填参数
["platform"]="dama2",       --平台类型，具体参数参照参数表
["x1"]=1848,                --需要识别区域左上角坐标
["y1"]=473,
["x2"]=2029,                --需要识别区域右下角坐标
["y2"]=561,
["type"]="52",              --打码类型，可在对应平台官网查询
["username"]="user",        --打码平台账号
["password"]="password",    --打码平台密码
--选填参数
["length"]=4,               --打码长度
["timeout"]=30,             --超时时间
["scale"]=50,               --缩放比例，范围10 - 200，在某些待识别区域过大的时候可设置此参数
};

local ret = ocr.cloudOcrText(op);
if ret.success then
    dialog(ret.text,0)
else
    dialog(ret.message,0)
end

--自动纠错
local ocr = require "cloudOcr";   --载入扩展库
local ret = ocr.cloudOcrText(op); --进行远程识别
if ret.success then               
    ret_1 = ocr.cloudOcrReportError(ret.id); --自动纠错，ret.id从ocr.cloudOcrText返回值中获取
end

local ocr = require "cloudOcr";
local ver = ocr.version(); --获取扩展库版本号

注意事项：

1. 最新打码扩展库下载地址：http://pan.baidu.com/s/1o6mPxHK
2. 打码函数传入的参数为TABLE类型，使用时请参照参数表中详细说明。
3. 如您使用火眼答题平台，用户名参数可以为空，密码串需要用户注册登陆后可以在火眼平台的后台查看到。

简易SMTP邮件发送库

函数名称：mail.send
函数功能：发送邮件
函数方法：a = mail.send(“send@gmail.com”, “receive@gmail.com”, “Hello”, “This is a test mail.”, “smtp.gmail.com”, “send@gmail.com”, “*“)
返回值：true 发送成功，其它字符串为失败原因

参数	类型	说明
参数 1	文本型	发送者邮件地址
参数 2	文本型	接收者邮件地址
参数 3	文本型	邮件主题
参数 4	文本型	邮件正文
参数 5	文本型	SMTP 服务器
参数 6	文本型	SMTP 鉴定用户名
参数 7	文本型	SMTP 鉴定密码

脚本实例：

local mail = require "mail"
a = mail.send("i.82@82flex.com", "357722984@qq.com", "Hello", "This is a test mail.", "smtp.mxhichina.com", "i.82@82flex.com", "***")
if a == true then         --发送成功
    dialog("Succeed!", 0)
else
    dialog(a, 0)
end

注意事项：

1. 扩展库下载地址：http://pan.baidu.com/s/1hqjCtVm 下载后将 mail.so 放入 /var/mobile/Media/TouchSprite/plugin 即可在脚本中引用。
2. 如安装触动版本高于 2.0.9 可直接在触动精灵内 – 更多 – 插件内直接安装此扩展库。

触动精灵扩展库

为了进一步降低脚本开发者门槛，触动精灵版本 2.x 以上集成了苏泽的扩展库，提供了一系列实用函数供开发者使用，在这里再次感谢苏泽为广大开发者及触动做出的杰出贡献。

使用方法：
请在脚本开头插入 local sz = require("sz") 即可调用扩展库中所有函数。

JSON 模块

函数名称：sz.json.encode、sz.json.decode
函数功能：json串编码、解码

脚本实例：

local sz = require("sz")
local json = sz.json
local tb = {
    ["我"] = "苏泽",
    ["爱"] = "娜娜",
    meme = {
        isArray = true,
        1,0,0,4,6,9,5,1,0,0,
    },
    nullvalue = null,
}

local jsonstring = json.encode(tb);
dialog(jsonstring, 0);

local tmp = json.decode(jsonstring);
dialog(tmp.meme[5], 0);
dialog(tostring(tmp.nullvalue), 0);

FTP 模块

函数名称：ftp.download、ftp.upload、ftp.cmd
函数功能：FTP上传、FTP下载、执行FTP命令

脚本实例：
1.FTP下载一个文件到本地

local sz = require("sz")
local ftp = sz.ftp
_, err = ftp.download("ftp://ftp用户名:ftp密码@ftp服务器ip地址/TsLib.lua", "/User/TsLiB.lua")
if err then
    dialog(err, 0)            
else
    dialog("文件已下载成功", 0)
end

2.FTP从本地上传一个文件到服务器

local sz = require("sz")
local ftp = sz.ftp
_, err = ftp.upload("/User/TsLiB.lua", "ftp://ftp用户名:ftp密码@ftp服务器ip地址/Games/")
if err then
    dialog(err, 0)
else
    dialog("文件已上传成功", 0)
end

3.从FTP服务器上删除一个文件

local sz = require("sz")
local ftp = sz.ftp
_, err = ftp.cmd("ftp://ftp用户名:ftp密码@ftp服务器ip地址/Games/", "DELE TsLiB.lua")
if err then
    dialog(err, 0)
else
    dialog("文件删除成功", 0)
end

4.列出指定FTP服务器路径下的文件

local sz = require("sz")
local ftp = sz.ftp
msg, err = ftp.cmd("ftp://ftp用户名:ftp密码@ftp服务器ip地址/Games/", "LIST")
if err then
    dialog(err, 0)
else
    dialog("文件列表\n"..msg, 0)
end

设备信息模块

函数功能：获取设备信息，具体请参照脚本实例使用

脚本实例：

local sz = require("sz")

dialog(sz.system.udid(), 0)            --获取设备的UDID
dialog(sz.system.serialnumber(), 0)    --获取设备的序列号
dialog(sz.system.wifimac(), 0)         --获取设备的WiFi MAC地址
dialog(sz.system.btmac(), 0)           --获取设备的蓝牙MAC地址
dialog(sz.system.osversion(), 0)       --获取设备的系统版本号
dialog(sz.system.localwifiaddr(), 0)   --获取设备的局域网IP地址
dialog(sz.system.mgcopyanswer("ProductType"),0) --获取设备详细型号
dialog(sz.system.mgcopyanswer("UserAssignedDeviceName"),0) --获取设备名称

字符串处理模块

函数名称：tohex；
                fromhex；
                md5；
                sha1；
                aes128_encrypt；
                base64_encode；
                base64_decode；
                aes128_decrypt；
                split；
                rtrim；
                ltrim；
                trim；
                atrim；
函数功能：字符串 十六进制编码转换、MD5计算、SHA1计算、AES128编解码、BASE64编解码、字符串分割、过滤
脚本实例：
1.十六进制编码转换、MD5计算、SHA1计算

local sz = require("sz")
local str = "sozereal"
dialog('"'..str..'" 的 16 进制编码为: <'..str:tohex()..'>', 0) 
dialog('<'..str:tohex()..'> 转换成明文为: "'..str:tohex():fromhex()..'"', 0)
dialog('"'..str..'" 的 MD5 值是: '..str:md5(), 0)
dialog('"'..str..'" 的 SHA1 值是: '..str:sha1(), 0)

local binstr = "\0\1\2\3\4\5"
dialog('<'..binstr:tohex()..'> 的 MD5 值是: '..binstr:md5(), 0)
dialog('<'..binstr:tohex()..'> 的 SHA1 值是: '..binstr:sha1(), 0)

2.AES128编解码、BASE64编解码

local sz = require("sz")
local msg = "\5\4\3\2\1\0"
local key = "sozereal"
local emsg = msg:aes128_encrypt(key)
local emsgb64 = emsg:base64_encode()

dialog('二进制数据<'..msg:tohex()..'> \n 使用 AES128 算法 密钥 "'..key..'" 加密 值是: <'..emsg:tohex()..'> \n base64 串为 "'..emsgb64..'"', 0)

local tmp = emsgb64:base64_decode()
msg = tmp:aes128_decrypt(key)
dialog('"'..emsgb64..'" base64 解码后的数据为 <'..tmp:tohex()..'> \n使用 AES128 算法 密钥 "'..key..'" 解密 值是: <'..msg:tohex()..'>', 0)

3.字符串分割及空白字符过滤

local sz = require("sz")
str = "  哈哈,he he,1,3,6  "
new = str:split(",") --将字符串str按照 `,` 分割并返回一个TABLE
dialog(new[2]，0)

dialog(str:rtrim(), 0) -- 结果 "  哈哈,he he,1,3,6" ,删除字符串尾部的空白字符
dialog(str:ltrim(), 0) -- 结果 "哈哈,he he,1,3,6  " ,删除字符串首部的空白字符
dialog(str:trim(), 0) -- 结果 "哈哈,he he,1,3,6"    ,删除字符串首尾的空白字符
dialog(str:atrim(), 0) -- 结果 "哈哈,hehe,1,3,6"    ,删除字符串所有的空白字符

名词解析：

1. 空白字符包括：空格、制表符 \t 、换行符 \n 、\r。

HTTP模块

函数名称：http.get、http.post、http.header、http.build_request
函数功能：发送 http GET 请求、发送 http POST 请求
函数方法：
               status_resp, headers_resp, body_resp = http.get(“http://82flex.com“, 5, headers_send)；
               status_resp, headers_resp, body_resp = http.post(“http://www.touchsprite.net/site/login“, 3, headers_send, post_escaped)

参数	类型	说明
url	文本型	请求URL (必须填写)
time_out	整数型	超时时间（秒）
headers_send	文本型	请求头部 json
post_escaped	文本型	请求内容

返回值	类型	说明
status_resp	整数型	HTTP 状态码
headers_resp	文本型	响应头部 json
body_resp	文本型	响应内容

脚本实例：

--采用 cjson 构造请求头部 json
local sz = require("sz")
local cjson = sz.json
local http = sz.i82.http

headers = {}
headers['User-Agent'] = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.111 Safari/537.36'
headers['Referer'] = 'http://www.82flex.com'
headers_send = cjson.encode(headers)
dialog(headers_send,0)

status_resp, headers_resp, body_resp = http.get("http://82flex.com", 5, headers_send)
if status_resp ~= nil then
    dialog(status_resp,0)
    dialog(headers_resp,0)
    if status_resp == 200 then
        dialog(string.len(body_resp),0)
    end
end

--采用 cjson 构造请求头部 json
local sz = require("sz")
local cjson = sz.json
local http = sz.i82.http

headers = {}
headers['User-Agent'] = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.111 Safari/537.36'
headers['Referer'] = 'http://www.touchsprite.net/site/login'
headers_send = cjson.encode(headers)
dialog(headers_send,0)

--采用 cjson 构造请求内容，并进行 escape
post = {}
post['username'] = "i_82"
post['password'] = '12345678'
post['text'] = '触动精灵'
post_send = cjson.encode(post)
dialog(post_send,0)
post_escaped = http.build_request(post_send)
dialog(post_escaped,0)

status_resp, headers_resp, body_resp = http.post("http://www.touchsprite.net/site/login", 3, headers_send, post_escaped)
dialog(status_resp,0)
dialog(headers_resp,0)
if status_resp ~= nil then
    dialog(status_resp,0)
    dialog(headers_resp,0)
    if status_resp == 200 then
        dialog(string.len(body_resp),0)
    end

    --获取响应信息头部指定字段
    --方法一
    server = http.header(headers_resp, "Server")
    dialog(server,0)

    --方法二
    servers = cjson.decode(headers_resp)
    dialog(servers["Server"],0)
end

--用http.get实现下载文件功能
local sz = require("sz")
local cjson = sz.json
local http = sz.i82.http

function downFile(url, path)
    status, headers, body = http.get(url)
    if status == 200 then
        file = io.open(path, "wb")
        if file then
            file:write(body)
            file:close()
            return status;
        else
            return -1;
        end
    else
        return status;
    end
end

downFile("http://www.touchsprite.com/img/headline-new.png", "/User/Media/TouchSprite/res/1.png")

SOCKET模块

函数名称：sz.socket.connect、asyncsend、send、recv、setopts、disconnect
函数功能：与服务器建立socket连接、异步发送数据、发送数据、接收数据、设置连接属性、断开连接
函数方法：
               c = sz.socket.connect(ip,port,time);
               c:send(“GET /HTTP/1.1 \r\n”);
               tmp = c:recv(1);
               c:disconnect();

参数	类型	说明
ip	文本型	服务器IP地址
port	文本型	连接服务器端口
time	整数型	超时时间（秒）

脚本实例：
1.用socket实现日志发送

local sz = require("sz")

function sendLog(log,ip,port)
    local c = sz.socket.connect(ip,port,1);
    if c then
        c:setopts(sz.socket.SO_LINGER,{1,0});
        c:setopts(sz.socket.SO_SNDTIMEO,1);
        c:send(log);
        return 1
    end
    return 0
end

2.发送接收数据

local sz = require("sz")
local c = sz.socket.connect("192.168.1.1","80",1);
c:send("GET / HTTP/1.1 \r\n"); --模拟httpget发送数据

local r = ""
while 1 do
    local tmp = c:recv(1)      --每次1字节接收数据
    if not tmp then
        break;
    end
    r = r..tmp
end

注意事项：

1. 实例中的日志发送需配合服务器端使用，服务器端下载地址: http://pan.baidu.com/s/1qWJViPI

PLIST 文件操作

函数名称：plist.read、plist.write
函数功能：PLIST文件读取、写入
函数方法：
               tmp2 = plist.read(plfilename)；
               返回值 TABLE
               plist.write(plfilename, tmp2)；

脚本实例：

--读取键值
local sz = require("sz")
local plist = sz.plist
local plfilename = "/var/mobile/Library/Caches/com.apple.mobile.installation.plist" --设置plist路径
local tmp2 = plist.read(plfilename)           --读取plist文件内容并返回一个TABLE
dialog(tmp2.Metadata.ProductBuildVersion, 0)  --显示ProductBuildVersion的键值

--写入键值
local sz = require("sz")
local plist = sz.plist
local plfilename = "/var/mobile/Library/Caches/com.apple.mobile.installation.plist" --设置plist路径
local tmp2 = plist.read(plfilename)           --读取plist文件内容并返回一个TABLE
tmp2.Metadata.ProductBuildVersion = "havonz"  --将表中ProductBuildVersion键值改为havonz
plist.write(plfilename, tmp2)                 --将修改后的表写入PLIST文件

注意事项：

1. 实例代码仅做为参考，实际调试中请将文件路径替换为实际存在的文件路径。
2. 对于个别重要的PLIST文件，请谨慎使用写入功能或在运行脚本前进行备份。

POS 模块

函数名称：click、dbclick、touchMoveTo、angleBetween、distanceBetween、polarProjection、cmpColor
函数名称：单击、双击、精确滑动、计算角度、计算距离、根据角度和距离找点、计算颜色相似度

脚本实例：

local sz = require("sz")
local pos = sz.pos
local p0 = pos(100, 150, 0x123456)
local p1 = pos(556, 400, 0x654321)

p0:click() -- 单击点 p0
p0:click(100) -- 单击点 p0 按下 100 毫秒延迟 弹起
p0:dbclick(100, 200) -- 双击点 p0 按下 100毫秒延迟 弹起 延迟 200 毫秒 重复第一步
p0:touchMoveTo(p1, 2, 500, 1) -- 从点 p0 滑动到 p1 , 后面三个可选参数依次为：步长、弹起延迟、每步延迟

dialog(" p0 到 p1 的角度为: "..p0:angleBetween(p1), 0)
dialog(" p0 到 p1 的距离为: "..p0:distanceBetween(p1), 0)
dialog(" p0 往 30 度方向前进 200 距离单位的另一个点: "..tostring(p0:polarProjection(200, 30)), 0)

dialog("颜色 0x102030 与颜色 0x122232 的相似度为: "..pos.cmpColor( 0x102030, 0x122232), 0)
dialog("p0 结构的颜色与颜色 0x123456 相似度为: "..p0:cmpColor(0x123456), 0)

IOS 设备分辨率一览表

设备	屏幕尺寸	分辨率 (pt)	Render	分辨率 (px)	PPI
iPhone4(S)/iPod Touch4G	3.5	320x480	@2x	640x960	330
iPhone 5(S/C)/iPod Touch5G	4.0	320x568	@2x	640x1136	326
iPhone 6	4.7	375x667	@2x	750x1334	326
iPhone 6 Plus	5.5	414x736	@3x	1242x2208	401
iPad 1/2	9.7	768x1024	@1x	768x1024	163
iPad mini	7.9	768x1024	@1x	768x1024	163
TheNewiPad/iPad 4/Air/Air2	9.7	768x1024	@2x	1536x2048	264
iPad mini 2/mini 3	7.9	768x1024	@2x	1536x2048	324

注意事项：
触动精灵制作脚本时，涉及屏幕坐标的操作均采用分辨率(px)，其中iPhone 6 Plus 的分辨率采用物理分辨率 1242 * 2208。

附录

下载、安装触动精灵，试用免费脚本，欢迎添加官方推荐软件源

1. Bigboss 源（内置）
2. 触动精灵官方源：http://apt.touchsprite.com
3. 触动精灵脚本威锋源：http://apt.so/tsscript
4. 82Flex 中文源：http://apt.82flex.com
5. 178 中文源：http://apt.178.com

脚本编辑器

1. （推荐）LuaEditor：http://pan.baidu.com/s/1pJwiZNH
2. 触动精灵关键字配置（直接替换）：http://pan.baidu.com/s/1qW9EpA0
3. Sublime Text 2：http://pan.baidu.com/s/1o6jtP6U
4. NotePad 2：http://pan.baidu.com/s/1ntkbRfj
5. NotePad ++：http://pan.baidu.com/s/1hqzLhWw
6. LuaIDE：http://pan.baidu.com/s/11tnno
7. （测试）Lua 全自动排版缩进工具：http://pan.baidu.com/s/1c0CK2Dq

取色、图像工具

1. （推荐）触动精灵抓色工具（更新 V1.3）：http://pan.baidu.com/s/1gdAC5YN
2. 图文使用教程：http://pan.baidu.com/s/1i3vFzcL
3. PhotoShop 迷你版（7M）：http://pan.baidu.com/s/1c0d88hy

脚本加密工具

1. （推荐）触动脚本加密工具：http://pan.baidu.com/s/1c0zTnEg
2. 图文使用教程：http://pan.baidu.com/s/1qWwhdLE

网络工具

1. （推荐）触动局域网日志工具：http://pan.baidu.com/s/1gd5mKTX

设备 SSH 连接工具

1. （推荐）WinSCP：http://pan.baidu.com/s/1o6jtP7G
2. 简体中文语言包：http://pan.baidu.com/s/15xaEy
3. Putty：http://pan.baidu.com/s/1mgslwX6
4. 局域网批量发送工具：http://bbs.touchsprite.com/forum.php?mod=viewthread&tid=1414
5. Lo 的脚本工具包：http://bbs.touchsprite.com/forum.php?mod=viewthread&tid=1385

相关工具运行库

1. VCredist 2010：http://pan.baidu.com/s/1sjjTFQH
2. NET Framework 4：http://www.microsoft.com/zh-cn/download/details.aspx?id=17718

OCR（光学字符识别）相关

1. 触动精灵云OCR工具：http://pan.baidu.com/s/1c009n5e
2. 触动精灵云OCR插件：http://pan.baidu.com/s/1i3JvVbZ
3. 触动精灵本地OCR插件：http://pan.baidu.com/s/1gdux64V
4. 触动精灵本地OCR简体中文识别库：http://pan.baidu.com/s/1qW2mDWC
5. 触动精灵本地OCR英文数字识别库：http://pan.baidu.com/s/1eQ3nbZs