觸動精靈擴展函數

序言

觸動精靈是一款模擬手機觸摸、按鍵操作的軟體，通過製作腳本，可以讓觸動精靈代替雙手，自動執行一系列觸摸、按鍵操作。觸動精靈簡單、易用，不需要掌握任何編程知識就可以錄製出功能強大的腳本；還可以使用編程知識，編寫出功能更為複雜，交互更為靈活的腳本；只要能夠在手機上完成的人為操作，觸動精靈都可以代替完成，不僅省力，而且高效。

觸動精靈採用 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] 內存洩漏也稱作「存儲滲漏」，用動態存儲分配函數動態開闢的空間，在使用完畢後未釋放，結果導致一直佔據該內存單元，直到程序結束。