跳到主要内容

模拟触摸模块

模拟触摸模块 - touch​

标有 🚥 的函数在 线程模块 中会发生 让出。在这些函数调用返回之前，其他的 线程 可能会得到运行机会。

设置触摸事件可视化显示 (touch.show_pose)​

声明​

touch.show_pose(是否显示)

参数及返回值​

  • 是否显示 布尔型

说明​

在屏幕上显示触摸事件的位置，方便调试。

性能

建议仅在开发、调试时调用此函数，因为它可能会影响生产脚本的稳定性。

示例​

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

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

声明​

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

参数及返回值​

  • 横坐标, 纵坐标
  • 延迟毫秒
    • 整数型，可选，接触屏幕到离开屏幕之间的间隔时间，单位毫秒，默认 30
  • 操作后等待毫秒
    • 整数型，可选，轻触完成之后的等待时间，单位毫秒，默认 0
备注

此方法在调用完成之前会自动分配并占用一个 手指ID。手指ID 的数量是有限的（大约 30 个），超出限制再调用 touch.on 或 touch.tap 会抛出 finger pool overflow 错误。注意不要 同时占用 过多 手指ID，或及时调用 touch:off 方法释放手指。

示例​

touch.tap
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(横坐标, 纵坐标)

参数及返回值​

  • 横坐标, 纵坐标
  • 触摸事件 触摸事件对象

说明​

模拟手指接触屏幕指定位置，并返回一个用于操纵本次触摸过程的 触摸事件对象。

备注

此方法在调用完成之前会自动分配并占用一个 手指ID。手指ID 的数量是有限的（大约 30 个），超出限制再调用 touch.on 或 touch.tap 会抛出 finger pool overflow 错误。注意不要 同时占用 过多 手指ID，或及时调用 touch:off 方法释放手指。

信息

此函数可同时使用以下方式调用（其中 手指ID 必须是范围在 1 ~ 29 的任意数字，这种方式要自行管理 手指ID）。

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

示例​

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

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

声明​

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

参数及返回值​

  • 横坐标, 纵坐标
    • 整数型，可选，手指离开屏幕的点于当前 旋转坐标系 的坐标，默认为当前 触摸事件对象 记录的坐标
  • 触摸事件
    • 触摸事件对象，通过调用 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 这个位置离开屏幕
--
-- 另外一个用法
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 的手指

模拟手指在屏幕上移动 (touch:move)​

声明​

触摸事件 = 触摸事件:move(横坐标, 纵坐标[, 压力, 角度, 选项标识位])

参数及返回值​

  • 横坐标, 纵坐标
  • 压力
    • 整数型，可选，手指在屏幕上的按压力度。取值范围为 0 ~ 1e4，默认为 0
  • 角度
    • 整数型，可选，手指在屏幕上施加压力的角度。取值范围为 -100 ~ 100，默认为 0
  • 选项标识位
    • 整数型，可选，通常在录制时使用，用于指定屏幕手势信息
  • 触摸事件
    • 触摸事件对象，通过调用 touch.on 函数可以获得一个用于操控当前触摸的事件对象

说明​

模拟手指从当前位置移动到其他的位置。

信息

此方法可同时使用以下方式调用（其中 手指ID 必须是范围在 1 ~ 29 的任意数字）。
此方法 touch.move 调用方式与 touch:move 方法不同之处在于，它是立刻移动到目标位置，不能设置步进。

touch.move(手指ID, 横坐标, 纵坐标)  -- 立刻移动到目标位置
--
touch.move(手指ID, 横坐标, 纵坐标[, 压力值, 角度, 选项标识位])  -- 立刻移动到目标位置，并设置压力值和角度
弃用

不推荐使用参数 压力值、角度。
因为 Apple 从 iPhone XR 和 iPhone 11 以后的设备中，移除了 3D Touch 硬件，上述参数也随之失效。

示例​

touch: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 的手指

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

声明​

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

参数及返回值​

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

说明​

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

示例​

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

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

声明​

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

参数及返回值​

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

说明​

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

示例​

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

🚥 毫秒级延迟 (touch:msleep)​

声明​

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

参数及返回值​

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

说明​

此方法调用不会对 触摸事件 有影响，仅仅起个阻塞当前线程的作用，此方法有个别名 touch:delay。

示例​

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

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

声明​

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

参数及返回值​

  • 压力
    • 整数型，可选，手指在屏幕上的按压力度。取值范围 0 ~ 1e4，默认 1e3
  • 角度
    • 整数型，可选，手指在屏幕上施加压力的角度。取值范围为 -100 ~ 100，默认为 0
  • 触摸事件
    • 触摸事件对象，通过调用 touch.on 函数可以获得一个用于操控当前触摸的事件对象

说明​

模拟手指在当前位置施加压力，此方法仅能用于支持 3D Touch 的设备。

示例​

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

示例代码​

-- 可以这样：
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()              -- 抬起手指