XXTouch iOS 开发手册

XXTouch

Windows 平台按 Ctrl + F 可以输入文字搜索

Mac 平台按 command + F 可以输入文字搜索

关于 XXTouch

XXTouch 使用 Lua 作为脚本语言，支持 Lua 5.3 版的所有语法与基本函数，并于其基础之上添加了一些扩展功能， 用于取色、找色、发送触摸、键盘事件等高级功能的实现。XXTouch 仅支持 UTF-8 编码的脚本。

如何阅读本手册

• 入门需要拥有 Lua 基础，可以参考《Lua 5.3 中文手册》及《Lua 5.3 函数参考》
• 示例代码中使用 0x 开头的数字为 16 进制数 ( 什么是 16 进制数? )
• 参数描述中可选参数使用中括号包围
• 参数或返回值如果是表型固定结构值，则使用大括号表示表型结构
• 类型描述中 文本型 和 字符串型 都是 Lua 的 string 类型，但 文本型 一般是指可以打印的明文文字
• 章或节用叹号 ( ! ) 开头的说明这个函数或者这个模块的函数包含隐式 让出（在这个函数返回之前，其它的 线程 可能会得到运行机会）
• 若无额外说明，手册内示例代码均不处理边界情况，不应该直接复制到自己的脚本中用

如何使用 XXTouch

售前及安装答疑

• 前往查看

用户使用图文说明

• 前往查看

普通用户交流 QQ 群 （483853614）

• 与其它用户交流 483853614

开发相关及交流 QQ 群 （40898074）

• 开发及周边工具下载
• 与其它开发者交流 40898074

脚本及相关资源存在设备的哪个位置？

• 脚本存放目录为 /var/mobile/Media/1ferver/lua/scripts/
• 插件存放目录为 /var/mobile/Media/1ferver/lib/
• 资源存放目录为 /var/mobile/Media/1ferver/res/
• 日志存放目录为 /var/mobile/Media/1ferver/log/
• 文字识别字库存放目录为 /var/mobile/Media/1ferver/tessdata/
• 内置脚本模块存放目录为 /var/mobile/Media/1ferver/lua/

保护脚本，正确接受 require

• 为何 require 可能带来安全风险？

  • XXTouch 加密的脚本模块可以被其它脚本或者模块以 require 方式引用
  • 当您的加密脚本被 require 时，全局环境是不可信的，您的脚本调用的函数可能已经被替换

• 如何正确使用 require 呢？

  • XXTouch 保证部分模块的函数会在 require 之前恢复初始状态，这包括

    • os、io、string、device、http、file、table 模块所有函数
    • 您可以深拷贝全局环境到模块内局部环境以确保安全调用上述模块中所有函数

    • 示例

      -- 在脚本的最前面加上这个代码
      local _ENV = table.deep_copy(_ENV)
      -- 下面就是脚本的主体内容
      -- 最后您可能还需要返回一些导出函数或者常量

  • 并且保证当一个模块被 require 方式引用的时候，全局变量 been_require 会无条件置为 true

    • 您可以通过这个全局变量的状态来判断自己是不是正在被 require

    • 示例

      -- 在脚本的最前面加上这个代码
      if been_require then
          return -- 如果被 require 就直接退出
      end
      -- 下面就是脚本的主体内容

基本控制函数

• 结束脚本 (os.exit)

  • 声明

    os.exit()

  • 说明

    os.exit 是 lua 自带的结束进程的函数，在 XXTouch 是结束逻辑上的脚本进程
    在任意线程中调用都可以结束当前脚本进程，所有的线程、监听都会立即终止

  • 示例

    os.exit()

• 重启脚本 (os.restart)

  • 声明

    操作成败, 错误信息 = os.restart([ 脚本文件路径 ])

  • 参数及返回值

    • 脚本文件路径 *1.1.2-2 新增
      文本型，可选参数，当这里传入一个有效的脚本文件路径将会重启到目标脚本文件，默认为 ""
    • 操作成败
      布尔型，操作失败返回 false，只有传递了脚本文件路径的情况下才可能操作失败，操作成功则这个函数不会返回
    • 错误信息
      文本型，操作失败的情况下，会返回具体的错误信息

  • 说明

    在没有 脚本文件路径 参数的情况下这个函数调用会直接重启 当前脚本 进程，当前脚本会立即结束
    传入了有效的 脚本文件路径 参数的时脚本会结束并重新启动到 目标脚本文件
    操作失败的情况下，该函数会返回 false 并附带错误信息，操作失败通常是传入了非法参数

  • 需要注意

    • 当前脚本 的定义是启动的那份脚本，脚本文件被更改后使用 os.restart() 不会 启动更改之后的脚本文件
    • 如果可能，请 不要 在多线程环境使用该函数
    • 无延迟重启会导致的其它逻辑问题也需要作者规避
    • 当前函数暂 不支持 重启、启动 xpp 脚本包 脚本

  • 示例 1

    os.restart() -- 重启到 “当前脚本”（不是 “当前脚本文件”）

  • 示例 2

    os.restart(utils.launch_args().path) -- 重启到 “当前脚本文件”

    注：上述代码中使用了非本章函数 utils.launch_args

• 脚本被终止时执行一些代码的方法

  • 说明

    这不是一个函数
    而是利用 Lua 的垃圾回收机制实现的，用于在脚本结束（或被结束）时执行一些代码的方法

    • 原理
      定义一个全局对象（表型值），将其 析构函数 设为一个函数
      当 Lua 虚拟机结束之时，所有 Lua 对象（也包括你定义的这个）的 析构函数 会被调用
      Lua 中的 析构函数 是指对象的 __gc 元方法

  • 简易示例

    -- 关键词 脚本终止回调 脚本结束回调
    随便取个变量名 = {}
    setmetatable(随便取个变量名, {
        __gc = function(...)
            sys.toast('被终止了！')
            sys.msleep(500)
        end
    })
    while (true) do
        sys.toast("现在可尝试手动结束脚本\n\n"..os.date("%Y-%m-%d %H:%M:%S"))
        sys.msleep(1000)
    end

    注：上述代码中使用了非本章函数 sys.toast、sys.msleep、setmetatable

  • 完整封装示例

    function atexit(callback) -- 参数为一个函数，使用 atexit(一个函数) 注册一个函数在脚本结束时执行，建议不要耗时太长
        ____atexit_guard____ = ____atexit_guard____ or {}
        if type(____atexit_guard____) == 'table' then
            if not getmetatable(____atexit_guard____) then
                setmetatable(____atexit_guard____, {
                    __gc = function(self)
                        if type(self.callback) == 'function' then
                            pcall(self.callback)
                        end
                    end
                })
            end
            ____atexit_guard____.callback = callback
        else
            error('别用 `____atexit_guard____` 命名你的变量。')
        end
    end
    -- 以上代码可拷贝到你的脚本的开头，以下为使用示例
    -- 使用 atexit 注册一个终止回调函数
    atexit(function() 
        sys.toast('被终止了！')
        sys.msleep(500)
    end)
    while (true) do
        sys.toast("现在可尝试手动结束脚本\n\n"..os.date("%Y-%m-%d %H:%M:%S"))
        sys.msleep(1000)
    end

    注：上述代码中使用了非本章函数 sys.toast、sys.msleep、setmetatable

开发辅助函数

• 打印内容到缓冲区 (print)

  • 声明

    print([ 参数1, 参数2, ... ])

  • 参数及返回值

    • 参数1, 参数2, ...
      任意类型，可选参数，可变参数，将会转换成文本输出到缓冲区，参数之间用 "\t" 隔开

  • 说明

    print 是 lua 自带的打印输入函数，在 XXTouch 是将内容打印到缓冲区

  • 示例

    print("hello world")

• 将打印缓冲区的内容提出来 (print.out)

  • 声明

    缓冲区内容 = print.out()

  • 说明

    将 print 函数打印的缓冲区清空并返回缓冲区内容

  • 示例

    -- 使用一个弹窗显示 print 缓冲区内容
    sys.alert(print.out())

    注：上述代码中使用了非本章函数 sys.alert

• 网络日志 (nLog)

  • 声明

    nLog(日志内容)

  • 参数及返回值

    • 日志内容
      文本型，日志内容

  • 说明

    这个函数是协议函数（空函数），默认执行不会产生任何效果，实现细节由配套开发环境决定
    当使用配套开发环境进行调试的时候这个函数将会将日志发回开发环境的日志框

  • 示例

    -- 将 print 缓冲区内容发回开发开发工具的日志窗
    nLog(print.out())

  ---

  
  
  
  
  
  

屏幕模块（screen）

• 初始化旋转坐标系 (screen.init)

  • 声明

    原坐标系 = screen.init(坐标系)

  • 参数及返回值

    • 坐标系
      
      • 整数型，取值范围
        0 - 竖屏 home 在下
        1 - 横屏 home 在右
        2 - 横屏 home 在左
        3 - 竖屏 home 在上
    • 原坐标系
      
      • 整数型，返回这个函数调用之前使用的坐标系

  • 说明

    初始化取色或点击的坐标系
    使用以下别名调用也可以实现相同效果

    screen.init_home_on_bottom()    -- home 在下
    screen.init_home_on_right()     -- home 在右
    screen.init_home_on_left()      -- home 在左
    screen.init_home_on_top()       -- home 在上

  • 示例

    screen.init(0)    -- home 在下
    screen.init(1)    -- home 在右
    screen.init(2)    -- home 在左
    screen.init(3)    -- home 在上

• 坐标旋转转换 (screen.rotate_xy)

  • 声明

    旋转后的横坐标, 旋转后的纵坐标 = screen.rotate_xy(横坐标, 纵坐标, 旋转方向)

  • 参数及返回值

    • 横坐标, 纵坐标
      
      • 整数型，需要旋转的坐标
    • 旋转方向
      
      • 整数型，旋转选项
        0 - 不旋转
        1 - 往左 90 度旋转
        2 - 往右 90 度旋转
        3 - 180 度旋转
    • 旋转后的横坐标, 旋转后的纵坐标
      
      • 整数型，返回使用 旋转方向 作为选项旋转后的坐标

  • 说明

    坐标旋转转换，通常用于将竖屏坐标转换成横屏坐标
    这个函数在 1.1.1-1 版以上方可使用

  • 示例

    rx, ry = screen.rotate_xy(100, 200, 1)

• 获取屏幕尺寸 (screen.size)

  • 声明

    屏宽, 屏高 = screen.size()

  • 参数及返回值

    • 屏宽 整数型
    • 屏高 整数型

  • 说明

    这个函数的返回值不受当前设备的桌面或者应用的的横竖屏状态影响，也不受放大模式影响
    这个函数可以在 XUI 中使用

  • 示例

    -- 根据分辨率判断设备类型
    width, height = screen.size()
    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 == 750 and height == 1334 then
        -- iPhone 6, 6S, 7, 8
    elseif width == 1242 and height == 2208 then
        -- iPhone 6+, 6S+, 7+, 8+
    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
    elseif width == 320 and height == 480 then
        -- 这个应该不可能
    end

• 保持屏幕 (screen.keep)

  • 声明

    screen.keep()

  • 说明

    在脚本中保持当前屏幕内容不变，多次调用取色、找色、截图、找图等函数时，直接调用保持的内容。
    该函数为优化类函数，能够为大量的静态图像处理函数提供性能优化。
    调用仅会影响 XXTouch 取色逻辑，不会 导致屏幕画面卡住不动！！！

  • 示例

    -- 遍历屏幕区块
    screen.keep()
    for k = 1, 640, 10 do
        for j = 1, 960, 10 do
            --格式化为十六进制文本
            color = string.format("%X", screen.get_color(k, j));
            --输出到系统日志
            sys.log("("..k..", "..j..") Color: "..color..".");
        end
    end
    screen.unkeep()

    注：上述代码中使用了非本章函数 sys.log

  • 小知识

    • 针对同一位置两行连续单独的 screen.get_color 调用可能取到不同的值
    • screen.keep 的情况下 screen.get_color 单独调用耗时会超过一次 screen.keep 的耗时
    • 调用 screen.keep 之后，再连续调用 50 次 screen.get_color 耗时可以等同于调用一次 screen.keep

• 取消保持屏幕 (screen.unkeep)

  • 声明

    screen.unkeep()

  • 说明

    取消 screen.keep 函数的效果，释放内存中的屏幕图像

  • 示例
    参考 screen.keep 示例

• 获取屏幕上某点颜色 (screen.get_color)

  • 声明

    颜色值 = screen.get_color(横坐标, 纵坐标)

  • 参数及返回值

    • 横坐标, 纵坐标
      整数型，代表目标点的坐标
    • 颜色值
      整数型，返回目标点颜色的 RGB 值

  • 说明

    获取屏幕上某个坐标点的颜色

  • 示例

    local c = screen.get_color(512, 133)
    if c==0xffffff then
        sys.alert("512, 133 这个点是纯白色")
    end

    注：上述代码中使用了非本章函数 sys.alert

• 获取屏幕上某点颜色 RGB (screen.get_color_rgb)

  • 声明

    红, 绿, 蓝 = screen.get_color_rgb(横坐标, 纵坐标)

  • 参数及返回值

    • 横坐标, 纵坐标
      整数型，代表目标点的坐标
    • 红, 绿, 蓝
      整数型，返回目标点颜色的 红、绿、蓝 值，取值范围 0~255

  • 说明

    获取屏幕上某个坐标点的颜色并拆分成 红(R) 绿(G) 蓝(B) 形式

  • 示例

    local r, g, b = screen.get_color_rgb(512, 133)
    if r==0xff and g==0xff and b==0xff then
        sys.alert("512, 133 这个点是纯白色")
    end

    注：上述代码中使用了非本章函数 sys.alert

• 屏幕多点颜色匹配 (screen.is_colors)

  • 声明

    是否完全匹配 = screen.is_colors({
        {横坐标*, 纵坐标*, 颜色*},
        {横坐标*, 纵坐标*, 颜色*},
        ...
    }[, 颜色相似度])

  • 参数及返回值

    • 横坐标*, 纵坐标*
      整数型，代表其中某点坐标
    • 颜色*
      整数型，代表其中某点需要匹配的颜色值
    • 颜色相似度
      整数型，可选参数，代表需要的颜色的相似度，取值范围 1~100，默认 100
    • 是否完全匹配
      布尔型，所有点的颜色都匹配则返回 true，否则返回 false

  • 说明

    匹配屏幕上若干点的颜色

  • 示例

    if screen.is_colors({
        { 509, 488, 0xec1c23}, -- 如果坐标 (509, 488) 的颜色与 0xec1c23 相似度在 90% 以上
        { 514, 470, 0x00adee}, -- 同时坐标 (514, 470) 的颜色与 0x00adee 相似度在 90% 以上
        { 508, 478, 0xffc823}, -- 同时坐标 (508, 478) 的颜色与 0xffc823 相似度在 90% 以上
        { 511, 454, 0xa78217}, -- 同时坐标 (511, 454) 的颜色与 0xa78217 相似度在 90% 以上
        { 521, 433, 0xd0d2d2}, -- 同时坐标 (521, 433) 的颜色与 0xd0d2d2 相似度在 90% 以上
    }, 90) then                -- 则匹配
        sys.alert("匹配！")
    else
        sys.alert("不匹配！")
    end

    注：上述代码中使用了非本章函数 sys.alert

• 多点相似度模式找色 (screen.find_color)

  • 声明

    横坐标, 纵坐标 = screen.find_color({
        [find_all = 是否搜索多个结果],
        [max_results = 最大结果数],
        [max_miss = 允许最多未命中数],
        {起始点横坐标, 起始点纵坐标, 起始点颜色[, 起始点相似度]},
        {偏移点横坐标*, 偏移点纵坐标*, 偏移点颜色*[, 偏移点相似度*]},
        {偏移点横坐标*, 偏移点纵坐标*, 偏移点颜色*[, 偏移点相似度*]},
        ...
    } [, 全局相似度, 左, 上, 右, 下 ])

  • 参数及返回值

    • 是否搜索多个结果
      布尔型，可选参数，这个标签设置为 true 会返回范围内所有匹配位置的一个表，格式为 {{x1, y1}, {x2, y2}, ...}，默认 false
    • 最大结果数
      整数型，可选参数，当 find_all（是否搜索多个结果） 标签设置为 true 的时候，这个表示最多返回结果数，最多可以设为 1000，默认 100
    • 允许最多未命中数 *1.2-3 新增
      整数型，可选参数，可以允许最多的不匹配的点的数量，默认为 0，也就是全命中才算找到
    • 起始点横坐标, 起始点纵坐标
      整数型，代表起始坐标，它并不是限制找色的范围为固定这一点，而仅仅是给偏移位置一个相对坐标，不理解就填 0, 0
    • 起始点颜色
      整数型，代表需要搜索的那一点的颜色
    • 起始点相似度
      整数型，可选参数，需要搜索的那一点颜色的相似度，取值范围 1~100，默认 100
    • 偏移点横坐标*, 偏移点纵坐标*
      整数型，代表一个偏移位置坐标
    • 偏移点颜色*
      整数型，代表偏移位置需要匹配的颜色
    • 偏移点相似度*
      整数型，可选参数，偏移位置的颜色的相似度，取值范围 -100~100，默认 100，负相似度意味着匹配小于该绝对值的相似度
    • 全局相似度
      整数型，可选参数，如果没有给单个点设置相似度，那么每一点都会用这个相似度，取值范围 1~100，默认 100
    • 左, 上, 右, 下
      整数型，可选参数，代表搜索区域，默认 全屏
    • 横坐标, 纵坐标
      整数型，返回匹配色的第一个色的坐标，搜索失败返回 -1, -1

  • 说明

    使用相似度模式查找，获取区域中第一个完全匹配的多点颜色结构的位置

  • 示例

    x, y = screen.find_color({
        {  0,   0, 0xec1c23},
        { 12,  -3, 0xffffff, 85},
        {  5, -18, 0x00adee},
        { -1, -10, 0xffc823},
        {  2, -34, 0xa78217},
        { 12, -55, 0xd0d2d2},
    }, 90, 0, 0, 100, 100)
    --[[
        在左上为 0, 0 右下为 100, 100 的区域找到第一点与 0xec1c23 相似度大于 90 
        且它的相对坐标 (12, -3) 的位置的颜色与 0xffffff 相似度大于 85
        且它的相对坐标 (5, -18) 的位置的颜色与 0x00adee 相似度大于 90 
        且……（后面的同理）都能匹配的那个点
    --]]
    -- 等效代码如下：
    x, y = screen.find_color({
        { 509, 488, 0xec1c23},
        { 521, 485, 0xffffff, 85},
        { 514, 470, 0x00adee},
        { 508, 478, 0xffc823},
        { 511, 454, 0xa78217},
        { 521, 433, 0xd0d2d2},
    }, 90, 0, 0, 100, 100)
    --[[
        在左上为 0, 0 右下为 100, 100 的区域找到第一点与 0xec1c23 相似度大于 90 
        且它的相对坐标 (521-509, 485-488) 的位置的颜色与 0xffffff 相似度大于 85 
        且它的相对坐标 (514-509, 470-488) 的位置的颜色与 0x00adee 相似度大于 90 
        且……（后面的同理）都能匹配的那个点
    --]]
    -- 不换行无缩进就是这个效果：
    x, y = screen.find_color({{0,0,0xec1c23},{12,-3,0xffffff,85},{5,-18,0x00adee},{-1,-10,0xffc823},{2,-34,0xa78217},{12,-55,0xd0d2d2},},90,0,0,100,100)
    x, y = screen.find_color({ -- 反匹配演示，在 5C 主屏幕运行可获得结果
        { 516,  288, 0xffffff },
        { 519,  286, 0xffffff },
        { 521,  289, 0xffffff },
        { 516,  296, 0xffffff },
        { 522,  297, 0xffffff },
        { 520,  295, 0xffffff, -10 }, -- 这一点颜色与 0xffffff 相似度小于 10 才匹配，下同
        { 515,  291, 0xffffff, -10 },
        { 518,  284, 0xffffff, -10 },
        { 523,  298, 0xffffff, -10 },
        { 514,  298, 0xffffff, -10 },
        { 514,  296, 0xffffff, -10 },
    }, 90) -- 不写区域参数表示全屏找
    results = screen.find_color({ -- 范围匹配全输出演示
        {  527,  278, 0xde1d26 },
        {  524,  285, 0x007aff },
        {  555,  292, 0xe4ddc9 },
        {  536,  314, 0xffde02 },
        {  502,  291, 0xffde02 },
        {  502,  283, 0xe4ddc9 },
        find_all = true, -- 带这个标签将返回范围所有匹配的位置的一个表，格式为 {{x1, y1}, {x2, y2}, ...}
    }, 90) -- 不写区域参数表示全屏找

• 多点色偏模式找色 (screen.find_color)

  • 声明

    横坐标, 纵坐标 = screen.find_color({
        [find_all = 是否搜索多个结果],
        [max_results = 最大结果数],
        [max_miss = 允许最多未命中数],
        {起始点横坐标, 起始点纵坐标, {起始点颜色[, 起始点色偏]}},
        {偏移点横坐标*, 偏移点纵坐标*, {偏移点颜色*, 偏移点色偏*}},
        {偏移点横坐标*, 偏移点纵坐标*, {偏移点颜色*, 偏移点色偏*}},
        ...
    } [, 左, 上, 右, 下 ])

  • 参数及返回值

    • 是否搜索多个结果
      布尔型，可选参数，这个标签设置为 true 会返回范围内所有匹配位置的一个表，格式为 {{x1, y1}, {x2, y2}, ...}，默认 false
    • 最大结果数
      整数型，可选参数，当 find_all（是否搜索多个结果） 标签设置为 true 的时候，这个表示最多返回结果数，最多可以设为 1000，默认 100
    • 允许最多未命中数 *1.2-3 新增
      整数型，可选参数，可以允许最多的不匹配的点的数量，默认为 0，也就是全命中才算找到
    • 起始点横坐标, 起始点纵坐标
      整数型，代表起始坐标，它并不是限制找色的范围为固定这一点，而仅仅是给偏移位置一个相对坐标，不理解就填 0, 0
    • 起始点颜色
      整数型，代表需要搜索的那一点的颜色
    • 起始点色偏
      整数型，需要搜索的颜色的最大色偏（或偏色），大于 0xff000000 则为反匹配模式
    • 偏移点横坐标*, 偏移点纵坐标*
      整数型，代表一个偏移位置坐标
    • 偏移点颜色*
      整数型，代表偏移位置需要匹配的颜色
    • 偏移点色偏*
      整数型，偏移位置的颜色的色偏（或偏色），大于 0xff000000 则为反匹配模式
    • 左, 上, 右, 下
      整数型，可选参数，代表搜索区域，默认 全屏
    • 横坐标, 纵坐标
      整数型，返回匹配色的第一个色的坐标，搜索失败返回 -1, -1

  • 说明

    使用色偏（或偏色）模式查找，获取区域中第一个完全匹配的多点颜色结构的位置

    色偏（或偏色）用于表示颜色偏差范围，一个颜色附带色偏（或偏色）是指该颜色的红、绿、蓝偏移范围内的所有颜色
    当 0x456789 色偏为 0x123456 的时候表示 0x456789 的红正负范围 0x12、绿正负范围 0x34、蓝正负范围 0x56
    也就是其红色范围为 0x45 ± 0x12、绿色范围为 0x67 ± 0x34、蓝色的范围为 0x89 ± 0x56，如下表所示

    负	正
    0x45 - 0x12 = 0x33	0x45 + 0x12 = 0x57
    0x67 - 0x34 = 0x33	0x45 + 0x12 = 0x9B
    0x89 - 0x56 = 0x33	0x45 + 0x12 = 0xDF

    上表所述 {0x456789, 0x123456} 实际上就是表示从 0x333333 到 0x579BDF 之间所有的颜色

    使用 0x 开头的数字为 16 进制数 ( 什么是 16 进制数? )

  • 示例

    x, y = screen.find_color({
        {  0,   0, {0xec1c23, 0x000000}},
        { 12,  -3, {0xffffff, 0x101010}},
        {  5, -18, {0x00adee, 0x123456}},
        { -1, -10, {0xffc823, 0x101001}},
        {  2, -34, {0xa78217, 0x101001}},
        { 12, -55, {0xd0d2d2, 0x101001}},
    }, 0, 0, 100, 100)
    --[[
        在左上为 0, 0 右下为 100, 100 的区域找到第一点与 0xec1c23 完全相似 (色偏为 0)
        且它的相对坐标 (12, -3) 的位置的颜色与 0xffffff 的色偏小于 0x101010
        且它的相对坐标 (5, -18) 的位置的颜色与 0x00adee 色偏小于 0x123456
        且……（后面的同理）都能匹配的那个点
    --]]
    -- 等效代码如下：
    x, y = screen.find_color({
        { 509, 488, {0xec1c23, 0x000000}},
        { 521, 485, {0xffffff, 0x101010}},
        { 514, 470, {0x00adee, 0x123456}},
        { 508, 478, {0xffc823, 0x101001}},
        { 511, 454, {0xa78217, 0x101001}},
        { 521, 433, {0xd0d2d2, 0x101001}},
    }, 0, 0, 100, 100)
    --[[
        在左上为 0, 0 右下为 100, 100 的区域找到第一点与 0xec1c23 完全相似 (色偏为 0)
        且它的相对坐标 (521-509, 485-488) 的位置的颜色与 0xffffff 的色偏小于 0x101010
        且它的相对坐标 (514-509, 470-488) 的位置的颜色与 0x00adee 色偏小于 0x123456
        且……（后面的同理）都能匹配的那个点
    --]]
    -- 不换行无缩进就是这个效果：
    x, y = screen.find_color({{0,0,{0xec1c23,0x000000}},{12,-3,{0xffffff,0x101010}},{5,-18,{0x00adee,0x123456}},{-1,-10,{0xffc823,0x101001}},{2,-34,{0xa78217,0x101001}},{12,-55,{0xd0d2d2,0x101001}},},0,0,100,100)
    x, y = screen.find_color({ -- 反匹配演示，在 5C 主屏幕运行可获得结果
        { 516,  288, {0xffffff, 0x101010} },
        { 519,  286, {0xffffff, 0x101010} },
        { 521,  289, {0xffffff, 0x101010} },
        { 516,  296, {0xffffff, 0x101010} },
        { 522,  297, {0xffffff, 0x101010} },
        { 520,  295, {0xffffff, 0xff101010} }, -- 这一点颜色与 0xffffff 色差大于 0x101010 才匹配，下同
        { 515,  291, {0xffffff, 0xff101010} },
        { 518,  284, {0xffffff, 0xff101010} },
        { 523,  298, {0xffffff, 0xff101010} },
        { 514,  298, {0xffffff, 0xff101010} },
        { 514,  296, {0xffffff, 0xff101010} },
    }) -- 不写区域参数表示全屏找
    results = screen.find_color({ -- 范围匹配全输出演示
        {  527,  278, {0xde1d26, 0x101010} },
        {  524,  285, {0x007aff, 0x101010} },
        {  555,  292, {0xe4ddc9, 0x101010} },
        {  536,  314, {0xffde02, 0x101010} },
        {  502,  291, {0xffde02, 0x101010} },
        {  502,  283, {0xe4ddc9, 0x101010} },
        find_all = true, -- 带这个标签将返回范围所有匹配的位置的一个表，格式为 {{x1, y1}, {x2, y2}, ...}
    }) -- 不写区域参数表示全屏找

• 获取屏幕图像 (screen.image)

  • 声明

    图像 = screen.image([ 左, 上, 右, 下 ])

  • 参数及返回值

    • 左, 上, 右, 下
      整数型，可选参数，代表图像区域，默认 全屏
    • 图像
      图片对象，返回一个图片对象，用法参考 图片对象模块（image）

  • 说明

    获取屏幕上区域或全部图像
    该方法会产出一个新的图片对象，如需保证高效频繁使用请搭配 image:destroy 方法使用

  • 示例

    -- screen.image 的示例代码
    screen.image():save_to_album() -- 全屏截图并保存到相册
    screen.image():save_to_png_file("/User/1.png") -- 全屏截图并保存到文件 /User/1.png
    screen.image(100, 100, 200, 200):save_to_album() -- 截取左上坐标为 100, 100 右下坐标为 200, 200 的区域图像保存到相册
    pasteboard.write(screen.image(100, 100, 200, 200):png_data(), "public.png")
    -- 截取左上坐标为 100, 100 右下坐标为 200, 200 的区域图像写入到剪贴板

  注：上述代码中使用了非本章函数 :save_to_album、:save_to_png_file、:png_data、pasteboard.write

• 屏幕区域文字识别 (screen.ocr_text)

  • 声明

    识别结果, 结果详情 = screen.ocr_text(左, 上, 右, 下 [, 结果范围, 二值化选项 ])

  • 参数及返回值

    • 左, 上, 右, 下
      整数型，代表识别区域
    • 结果范围
      
      • 可以是 文本型 或 表型 参数
        详情可参考 对图片进行 ocr 识别
    • 二值化选项 *1.1.0-1 新增
      
      • 可以是 实数型 或 文本型 或 表型 参数，分别代表
        实数型，二值化阈值，可参考 图片自动二值化
        表型，自定义二值化色偏，参考 图片手动二值化
        文本型，自定义二值化色偏，参考 图片手动二值化
    • 识别结果
      文本型，识别返回的文字
    • 结果详情 *1.1.3-1 新增
      表型，识别结果的每个可见字符的位置描述

  • 说明

    识别屏幕区域上的文字，该函数会引用 image.tess_ocr 模块
    内置 OCR 识别库引擎为 tesseract 3.02 版，版本不对或者字库文件损坏会导致 XXTouch 脚本服务崩溃
    这里提供适用于 XXTouch 的 tesseract 引擎版本为 3.05 版的 OCR 识别库 tess_ocr_1.2_with_tesseract_3.05.01.zip-1853.9kB（点击下载）
    XXTouch 已内置 eng 识别库 [A-Za-z0-9] 能识别常规英文和数字
    如果需要做简体中文或是其它语言文字识别
    需要手动导入相关的字库文件到设备的 /var/mobile/Media/1ferver/tessdata/ 目录
    这里提供 简体中文字库（点击下载）
    二值化选项 手动二值化在 1.1.0-1 版以上方可使用
    结果详情 在 1.1.3-1 版以上方可使用
    如果想自己进行 tesseract 字库训练可以 百度搜索“tesseract 训练”

  • 示例

    -- 示例 1：
    local txt = screen.ocr_text(187, 882, 298, 914) -- 默认配置是使用英文数字模式识别文字
    sys.toast("识别结果："..txt:atrim())
    -- 示例 2（1.1.0-1 新增）：
    local txt = screen.ocr_text(465, 241, 505, 269, "eng", "9D5D39-0F1F26,D3D3D2-2C2C2D") -- 使用色偏二值化识别
    sys.toast("识别结果："..txt:atrim())
    -- 示例 3（1.1.0-1 新增）：
    local txt = screen.ocr_text(465, 241, 505, 269, "eng", {{0x9D5D39, 0x0F1F26},{0xD3D3D2, 0x2C2C2D}}) -- 使用色偏二值化识别，同上
    sys.toast("识别结果："..txt:atrim())
    -- 示例 4：
    local txt = screen.ocr_text(187, 882, 298, 914, {
      lang = "chi_sim",         -- 使用简体中文库识别（注意，简体中文库不是内置的）
      white_list = "你我他",      -- 白名单设为 "你我他"
    })
    sys.toast("识别结果："..txt:atrim())
    -- 示例 5（1.1.0-1 新增）：
    local txt = screen.ocr_text(187, 882, 298, 914, {
      lang = "eng",
      white_list = "1234567890",      -- 自定义使用白名单限制仅识别为数字
    }, "9D5D39-0F1F26,D3D3D2-2C2C2D") -- 使用色偏二值化识别
    sys.toast("识别结果："..txt:atrim())

    注：上述代码中使用了非本章函数 sys.toast、string.atrim

• 屏幕找图 (screen.find_image)

  • 声明

    横坐标, 纵坐标 = screen.find_image(图片 [, 相似度, 左, 上, 右, 下 ])

  • 参数及返回值

    • 图片
      
      • 字符串型
        需要找的图片，可以是 png 或是 jpeg 格式的图片数据
      • 图片对象
        或是一个图片对象（可参考 图片对象模块（image））
      • 文本型 *1.1.2-1 新增
        需要找的图片文件路径，如果不是合法路径则会以数据方式解析
    • 相似度
      整数型，可选参数，需要找的图片的相似度，范围 1~100，默认为 95
    • 左, 上, 右, 下
      整数型，可选参数，搜索区域，默认 全屏
    • 横坐标, 纵坐标
      整数型，返回找到的图片的左上角坐标，搜索失败返回 -1, -1

  • 说明

    在屏幕上寻找一个图像的位置，该函数会引用 image.cv 模块
    注意： 如果需要做多分辨率兼容，那么建议是于分辨率最小的设备上截图；大分辨率上的截图会无法在小分辨率设备上找到

  • 示例
    XXT 取色器 1.0.12 Windows 版.zip-51.63MB

    -- 示例 1（使用 XXT 取色器 Shift + 鼠标左键框选图像上的区域 可直接生成这样的代码）：
    x, y = screen.find_image( -- 原图位置 左上: 354, 274 | 右下: 358, 284
    "\x89\x50\x4e\x47\x0d\x0a\x1a\x0a\x00\x00\x00\x0d\x49\x48\x44\x52\x00\x00\x00\x04\x00\x00\x00\x0a\x08\x02\x00\x00\x00\x1c\x99\x68\x59\x00\x00\x00\x61\x49\x44\x41\x54\x78\xda\x63\x78\xfd\xf4\xda\xff\xff\xff\xff\xfd\xfb\xf7\xed\xcb\x5b\x86\xf7\xaf\x1f\xfc\x87\x01\x86\x2f\x1f\x5f\x02\xa9\xef\xa7\xce\x7c\xdd\xb1\x9b\xe1\xe7\xf7\xcf\x40\xce\xeb\xb2\xea\x7b\xb2\x6a\x0c\x7f\xff\xfe\x01\x72\x9e\x78\x06\x82\x38\x20\xdd\xbf\x7e\xdd\x57\xd4\x82\x72\x7e\xdd\xba\x0d\x64\x41\x39\x08\xd3\x80\x38\x6b\xe3\x7f\x86\x2a\x30\x02\x72\x8c\xa6\x40\x39\x00\xd5\x7b\x5f\x2e\xfd\xba\xd5\x32\x00\x00\x00\x00\x49\x45\x4e\x44\xae\x42\x60\x82"
    , 95, 0, 0, 639, 1135)
    -- 示例 2：
    img = image.load_file("/User/1.png")
    x, y = screen.find_image(img)
    x, y = screen.find_image(img, 95)
    -- 示例 4（1.1.2-1 新增）：
    x, y = screen.find_image("/User/1.png", 95, 0, 0, 639, 1135)

    说明：在 Lua 源码中，字符串中 \x 开头，后面跟两位 16 进制数表示以该数字编码的单个字节。例如：\x58 表示 X 这个字符，可打印字符部分参考《ASCII 编码》

  • 复杂例子

    -- 从网上下载个小图片（一部分 XXTouch 图标）然后从屏幕上找到它并点击
    local c, h, r = http.get("https://www.xxtouch.com/img/find_image_test.png", 10)
    if (c == 200) then
        local img = image.load_data(r)
        if img then
            x, y = screen.find_image(img, 95)
            if x~=-1 then
                touch.tap(x, y)
            else
                sys.alert("没有在屏幕上找到 XXTouch 图标")
            end
        else
            sys.alert("可能下载到了一个假图片")
        end
    else
        sys.alert("下载失败")
    end

    注：上述代码中使用了非本章函数 sys.alert、image.load_data、touch.tap、http.get

模拟触摸模块（touch）

• ! 模拟手指轻触一次屏幕 (touch.tap)

  • 声明

    touch.tap(横坐标, 纵坐标 [, 延迟毫秒, 操作后等待毫秒 ])

  • 参数及返回值

    • 横坐标, 纵坐标
      整数型，需要轻触的点于当前旋转坐标系的坐标
    • 延迟毫秒
      整数型，可选参数，接触屏幕到离开屏幕之间的间隔时间，单位毫秒，默认 30
    • 操作后等待毫秒
      整数型，可选参数，轻触完成之后的等待时间，单位毫秒，默认 0

  • 说明

    模拟手指轻触一次屏幕指定位置
    这个方法可能会让出，在这个方法返回之前，其它的 线程 可能会得到运行机会
    注: 该方法在调用完成之前会自动分配并占用一个手指 id，手指 id 的数量是有限的（大约 30 个），超出限制再调用 touch.on 或 touch.tap 会抛出 finger pool overflow 错误，注意不要同时占用过多手指 id，及时调用 :off 方法释放手指

  • 示例

    touch.tap(100, 100) -- 点一下屏幕上 100, 100 这个位置
    touch.tap(100, 100, 300) -- 在屏幕上的 100, 100 这个位置按下，等待 0.3 秒再抬起
    touch.tap(100, 100, 300, 1000) -- 在屏幕上的 100, 100 这个位置按下，等待 0.3 秒再抬起，再等待 1 秒

• 模拟手指接触屏幕 (touch.on)

  • 声明

    触摸事件 = touch.on(横坐标, 纵坐标)

  • 参数及返回值

    • 横坐标, 纵坐标
      整数型，需要接触的点于当前旋转坐标系的坐标
    • 触摸事件
      触摸事件对象，通过调用 touch.on 函数可以并获得一个用于操控当前触摸的事件对象

  • 说明

    模拟手指接触屏幕指定位置，并返回一个用于操纵本次触摸过程的触摸事件对象
    注: 该函数会自动分配并占用一个手指 id，手指 id 的数量是有限的（大约 30 个），超出限制再调用 touch.on 或 touch.tap 会抛出 finger pool overflow 错误，注意不要同时占用过多手指 id，及时调用 :off 方法释放手指
    该函数可同时使用以下方式调用（其中手指ID必须是范围在 1 ~ 29 的任意数字，这种方式要自行管理手指 id）

    touch.on(手指ID, 横坐标, 纵坐标)

  • 示例

    -- 模拟一个手指于点 100, 100 的位置接触屏幕，然后匀速滑动到点 200, 200 的位置，然后松开
    touch.on(100, 100):move(200, 200):off()
    touch.on(1, 100, 100) -- 模拟编号为 1 的手指于点 100, 100 的位置接触屏幕
    touch.off(1)          -- 松开编号为 1 的手指

• ! 模拟手指在屏幕上移动 (:move)

  • 声明

    触摸事件 = 触摸事件:move(横坐标, 纵坐标)

  • 参数及返回值

    • 横坐标, 纵坐标
      整数型，需要移动至的点于当前旋转坐标系的坐标
    • 触摸事件
      触摸事件对象，通过调用 touch.on 函数可以获得一个用于操控当前触摸的事件对象

  • 说明

    模拟手指从当前位置移动到其它的位置
    这个方法可能会让出，在这个方法返回之前，其它的 线程 可能会得到运行机会
    该函数可同时使用以下方式调用（其中手指ID必须是范围在 1 ~ 29 的任意数字）

    touch.move(手指ID, 横坐标, 纵坐标)
    touch.move(手指ID, 横坐标, 纵坐标, 压力值)

    该调用方式与 :move 方法不同之处在于，它是立刻移动到目标位置，不能设置步进

  • 示例

    -- 模拟一个手指于点 100, 100 的位置接触屏幕，然后匀速滑动到点 200, 200 的位置，然后松开
    touch.on(100, 100):move(200, 200):off()
    -- 另外一个用法
    touch.on(1, 100, 100) -- 模拟编号为 1 的手指于点 100, 100 的位置接触屏幕
    for i=1, 100 do       -- 循环逐步移动编号为 1 的手指到点 100, 200 的位置
        touch.move(1, 100, 100 + i)
    end
    touch.off(1)          -- 松开编号为 1 的手指

• ! 模拟手指在屏幕上施加压力 (:press)

  • 声明

    触摸事件 = 触摸事件:press([ 压力, 速度 ])

  • 参数及返回值

    • 压力
      整数型，可选参数，压力，范围 1~10000，默认 1000
    • 速度
      整数型，可选参数，施加压力的速度，范围 1~100，默认 最快速
    • 触摸事件
      触摸事件对象，通过调用 touch.on 函数可以获得一个用于操控当前触摸的事件对象

  • 说明

    模拟手指在当前位置施加压力，该方法仅能用于支持 3D Touch 的设备
    这个方法可能会让出，在这个方法返回之前，其它的 线程 可能会得到运行机会

  • 示例

    touch.on(100, 100):press():off() -- 模拟一个手指于点 100, 100 的位置接触屏幕，然后用力按下去，然后松手
    touch.on(100, 100):press(2000):off() -- 上面例子改一点压力
    touch.on(100, 100):press(2000, 50):off() -- 上面例子改一点压力，按压速度放慢

• 模拟手指离开屏幕 (:off)

  • 声明

    触摸事件:off([ 横坐标, 纵坐标 ])

  • 参数及返回值

    • 横坐标, 纵坐标
      整数型，可选参数，手指离开屏幕的点于当前旋转坐标系的坐标，默认 当前 te 事件记录的坐标
    • 触摸事件
      触摸事件对象，通过调用 touch.on 函数可以获得一个用于操控当前触摸的事件对象

  • 说明

    模拟手指从当前位置或指定位置离开屏幕，该方法调用会释放当前触摸事件对象
    该方法会释放掉 touch.on 返回的触摸事件对象所占用的手指 id
    该函数可同时使用以下方式调用（其中手指ID必须是范围在 1 ~ 29 的任意数字）

    touch.off(手指ID)
    touch.off(手指ID, 横坐标, 纵坐标)

  • 示例

    touch.on(100, 100):off() -- 模拟一个手指于点 100, 100 的位置接触屏幕，然后于当前位置离开屏幕
    touch.on(100, 100):off(105, 95) -- 模拟一个手指于点 100, 100 的位置接触屏幕，然后于 105, 95 这个位置离开屏幕

• 设置触摸事件对象移动步长 (:step_len)

  • 声明

    触摸事件 = 触摸事件:step_len(步长)

  • 参数及返回值

    • 步长
      整数型，可选参数，默认为 2
    • 触摸事件
      触摸事件对象，通过调用 touch.on 函数可以获得一个用于操控当前触摸的事件对象

  • 说明

    设置当前触摸事件对象使用 move 方法滑动的步长

  • 示例

    touch.on(100, 100):step_len(3):step_delay(0.2):move(200, 200):off() -- 模拟一个手指于点 100, 100 的位置接触屏幕，以步长为 3 、每步延迟为 0.2 毫秒的速度滑动到点 200, 200 的位置离开屏幕

• 设置触摸事件对象移动每步延迟 (:step_delay)

  • 声明

    触摸事件 = 触摸事件:step_delay(每步延迟)

  • 参数及返回值

    • 每步延迟毫秒
      实数型，可选参数，每步延迟时间，单位毫秒，默认 0.1
    • 触摸事件
      触摸事件对象，通过调用 touch.on 函数可以获得一个用于操控当前触摸的事件对象

  • 说明

    设置当前触摸事件对象使用 move 方法滑动的每步延迟

  • 示例

    touch.on(100, 100):step_len(3):step_delay(0.2):move(200, 200):off() -- 模拟一个手指于点 100, 100 的位置接触屏幕，以步长为 3 、每步延迟为 0.2 毫秒的速度滑动到点 200, 200 的位置离开屏幕

• ! 毫秒级延迟 (:msleep)

  • 声明

    触摸事件 = 触摸事件:msleep(毫秒数)

  • 参数及返回值

    • 毫秒数
      实数型，可选参数，延迟时间，单位毫秒，默认 0.1
    • 触摸事件
      触摸事件对象，通过调用 touch.on 函数可以获得一个用于操控当前触摸的事件对象

  • 说明

    延迟函数，这个函数不会对对象有影响，仅仅起个阻塞当前线程的作用，该方法有个别名 :delay
    这个方法可能会让出，在这个方法返回之前，其它的 线程 可能会得到运行机会

  • 示例

    touch.on(100, 100):msleep(300):off() -- 模拟一个手指于点 100, 100 的位置接触屏幕，等待 300 毫秒，离开屏幕

• 设置触摸圆点显示 (touch.show_pose)

  • 声明

    touch.show_pose(是否显示)

  • 参数及返回值

    • 是否显示
      布尔型，true 为显示；false 为不显示

  • 说明

    设置 touch 模块函数调用时是否显示圆点在屏幕上
    打开圆点显示会极大降低 touch 模块函数的效率，并且长时间使用会影响系统稳定性，建议仅用于调试环境

  • 示例

    touch.show_pose(true)
    touch.tap(100, 100)

• touch 示例代码

  -- 可以这样：
  touch.on(306, 300):step_len(2):step_delay(0):move(350, 800):msleep(1000):off()
  -- 上面那个例子也能写成这样：
  touch.on(306, 300)  -- 模拟手指在 306,300 这个坐标点接触屏幕
      :step_len(2)   -- 设置移动步长为 2
      :step_delay(0) -- 设置移动每步延迟为 0
      :move(350, 800) -- 以上面两个参数所设置移动到 350,800 这个坐标
      :msleep(1000)   -- 等 1000 毫秒（也就是 1 秒）
  :off()             -- 手指离开屏幕
  -- 或是这样：
  local te = touch.on(306,300)
  te:step_len(2)
  te:step_delay(0)
  te:move(350, 800)
  te:msleep(1000)
  te:off()
  -- 通常情况下，滑动代码可以写成这样
  touch.on(306, 300)
      :move(350, 800)
      :msleep(1000)
  :off()
  -- 等效于
  touch.on(306, 300):move(350, 800):msleep(1000):off()
  -- 也可以这样用于模拟轻触屏幕一次
  touch.on(306, 300):msleep(30):off()

• 精确滑动的实现示例

  -- 快速精确滑动可能需要一些技巧，看下面的例子以及注释
  touch.on(125, 2000) -- 在起始坐标按下
      :step_len(10)   -- 步长设长以便加速滑动
      :move(125, 555) -- 快速移动到接近目标位置
      :step_len(1)    -- 步长设短缓冲防止惯性
      :move(125, 505) -- 慢速移动目标位置
      :delay(100)     -- 抬起前等待一段时间
  :off()              -- 抬起手指

模拟按键模块（key）

• 模拟按一下物理按键 (key.press)

  • 声明

    key.press(按键码)

  • 参数及返回值

    • 按键码
      文本型，物理按键的按键码，键码在 示例及支持的键码列表 一节查看

  • 说明

    模拟按下物理按键然后松开它
    与此函数已知的冲突插件：Background Manager

  • 示例
    本章结尾

• 模拟按下物理按键 (key.down)

  • 声明

    key.down(按键码)

  • 参数及返回值

    • 按键码
      文本型，物理按键的按键码，键码在 示例及支持的键码列表 一节查看

  • 说明

    模拟按下物理按键
    注意 这个函数应当有对应的 key.up 调用，否则在脚本终止之后，会发生按键一直不释放的问题。
    与此函数已知的冲突插件：Background Manager

  • 示例
    本章结尾

• 松开按下的物理按键 (key.up)

  • 声明

    key.up(按键码)

  • 参数及返回值

    • 按键码
      文本型，物理按键的按键码，键码在 示例及支持的键码列表 一节查看

  • 说明

    模拟松开按下物理按键
    与此函数已知的冲突插件：Background Manager

  • 示例
    本章结尾

• 模拟键入文本 (key.send_text)

  • 声明

    key.send_text(文本 [, 每键延迟 ])

  • 参数及返回值

    • 文本
      文本型，待输入的文字，只能是英文数字和半角字符还有 "\b" "\r" "\t"
    • 每键延迟
      整数型，输入每次按键延迟，默认没有延迟以设备性能极限输入

  • 说明

    该函数可用于所有的 input_text 函数都无效的情况下，强行模拟键盘键入
    亲测可以输入支付宝的支付密码
    与此函数已知的冲突插件：Background Manager

  • 示例

    key.send_text("AbC12#") -- 尽可能快的键入文本
    key.send_text("AbC12#", 300) -- 每键入一次延迟 0.3 秒

示例及支持的键码列表

• 模拟按 HOME 键

  key.press("HOMEBUTTON")

• 模拟长按 HOME 键

  key.down("HOMEBUTTON") -- 按下 HOME 键
  sys.msleep(1000) -- 等待 1 秒
  key.up("HOMEBUTTON") -- 松开 HOME 键

• 模拟双击 HOME 键

  key.press("HOMEBUTTON")
  key.press("HOMEBUTTON")

• 模拟按锁屏键（电源键）

  key.press("LOCK")

• 模拟按回车键

  key.press("RETURN")

• 其它模拟

  -- 下面这个例子是模拟组合键 [command + v] 粘贴剪贴板的文本（不是 windows 上的 control + v ）
  key.down("LEFTCOMMAND") -- 按下 command 键
  sys.msleep(20) -- 等待 20 毫秒
  key.press("V") -- 按一下 v 键
  sys.msleep(20) -- 等待 20 毫秒
  key.up("LEFTCOMMAND") -- 松开 command 键
  key.press("VOLUMEUP") -- 按一下音量 + 键
  key.press("VOLUMEDOWN") -- 按一下音量 - 键
  key.down("VOLUMEUP") -- 按下音量 + 键
  sys.msleep(1000) -- 等待 1 秒
  key.up("VOLUMEUP") -- 松开音量 + 键
  key.down("LOCK") -- 按下锁屏键（电源键）
  sys.msleep(3000) -- 等待 3 秒
  key.up("LOCK") -- 松开锁屏键（电源键）
  key.press("SHOW_HIDE_KEYBOARD") -- 按一下[隐藏/显示键盘键]隐藏虚拟键盘
  key.press("SHOW_HIDE_KEYBOARD") -- 再按一下[隐藏/显示键盘键]显示虚拟键盘
  -- 下面这个例子是模拟组合键 [锁屏键 + HOME键] 实现截屏到相册
  key.down("LOCK") -- 按下锁屏键（电源键）
  sys.msleep(100) -- 等待 100 毫秒
  key.press("HOMEBUTTON") -- 按一下 HOME 键
  sys.msleep(100) -- 等待 100 毫秒
  key.up("LOCK") -- 松开锁屏键（电源键）
  -- iOS7、iOS8 切换输入法的组合键
  key.down("LEFTCOMMAND")
  sys.msleep(50)
  key.press(" ")
  sys.msleep(50)
  key.up("LEFTCOMMAND")
  -- iOS9 切换输入法的组合键
  key.down("LEFTCONTROL")
  sys.msleep(50)
  key.press("SPACE")
  sys.msleep(50)
  key.up("LEFTCONTROL")
  

  注：上述代码中使用了非本章函数 sys.msleep

• 支持的键码列表

  -- 字母键：
  "A" "B" "C" "D" "E" "F" "G" "H" "I" "J" "K" "L" "M" "N" "O" "P" "Q" "R" "S" "T" "U" "V" "W" "X" "Y" "Z"
  -- 数字键：
  "1" "2" "3" "4" "5" "6" "7" "8" "9" "0"
  -- 功能键：
  "F1" "F2" "F3" "F4" "F5" "F6" "F7" "F8" "F9" "F10" "F11" "F12"
  -- 其它键：
  "RETURN"        --< 回车键
  "ESCAPE"        --< ESC键
  "BACKSPACE"     --< 退格键
  "TAB"           --< 制表符键
  "SPACE"         --< 空格键
  "HYPHEN"        --< "-" 或 "_" 键
  "EQUAL"         --< "=" 或 "+" 键
  "BRACKETOPEN"   --< "[" 或 "{" 键
  "BRACKETCLOSE"  --< "]" 或 "}" 键
  "BACKSLASH"     --< "\" 或 "|" 键
  "SEMICOLON"     --< ";" 或 ":" 键
  "QUOTATION"     --< 单引号或双引号键
  "ACCENT"        --< "`" 或 "~" 键
  "COMMA"         --< "," 或 "<" 键
  "DOT"           --< "." 或 ">" 键
  "SLASH"         --< "/" 或 "?" 键
  "CAPSLOCK"      --< 大小写锁定键
  "PAUSE"
  "INSERT"
  "HOME"          --< 这个不完全等于 iOS 设备的 HOME 键
  "PAGEUP"
  "DELETE"
  "END"
  "PAGEDOWN"
  "RIGHTARROW"    --< 向右箭头键
  "LEFTARROW"     --< 向左箭头键
  "DOWNARROW"     --< 向下箭头键
  "UPARROW"       --< 向上箭头键
  "LEFTCONTROL"   --< 左侧 Ctrl 键
  "LEFTSHIFT"     --< 左侧 Shift 键
  "LEFTALT"       --< 左侧 Alt 键
  "LEFTCOMMAND"   --< 左侧 Command 键
  "RIGHTCONTROL"  --< 右侧 Ctrl 键
  "RIGHTSHIFT"    --< 右侧 Shift 键
  "RIGHTALT"      --< 右侧 Alt 键
  "RIGHTCOMMAND"  --< 右侧 Command 键
  "LOCK"          --< 锁屏键，或电源键
  "HOMEBUTTON"    --< 这个才等于 iOS 设备的 HOME 键
  "FORWARD"       --< 多媒体下一首
  "REWIND"        --< 多媒体上一首
  "FORWARD2"      --< 多媒体下一首2
  "REWIND2"       --< 多媒体上一首2
  "EJECT"
  "PLAYPAUSE"     --< 多媒体暂停键
  "MUTE"          --< 静音键
  "VOLUMEUP"      --< 音量 + 键
  "VOLUMEDOWN"    --< 音量 - 键
  "SPOTLIGHT"     --< Spotlight 键
  "BRIGHTUP"      --< 屏幕亮度 + 键
  "BRIGHTDOWN"    --< 屏幕亮度 - 键
  "SHOW_HIDE_KEYBOARD" --< 隐藏/显示键盘键