ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/action.md

@@ -0,0 +1,1013 @@
+# 动作模块 (Action)
+
+动作模块提供了丰富的触摸和按键操作功能，包括点击、滑动、长按滑动、返回首页、多点触摸等动作。
+
+**注意事项**
+
+- 此模块仅支持 快点 Agent 模式使用
+- HID 模式，请使用 HID 模块
+
+## 抖动值
+
+### setJitterValue - 设置动作抖动值
+
+默认抖动值为 5 像素，设置后有 jitter 参数的动作会在像素范围 `-value` 到 `value` 随机偏移。
+
+```lua
+---@param value number
+function setJitterValue(value) end
+```
+
+**参数说明：**
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| ---------- | ------- | -------- | ------ | ------------------------------------------------------- |
+| `value` | number | 是 | - | 抖动值，点击、滑动等动作会在像素范围 `-value` 到 `value` 随机偏移 |
+
+**示例：**
+
+```lua
+local action = require("action")
+-- 设置抖动值为5像素
+action.setJitterValue(5)
+```
+
+## 基础触摸操作
+
+### click - 点击操作
+
+```lua
+---@param x number
+---@param y number
+---@param duration number?
+---@param jitter boolean?
+---@return boolean
+function click(x, y, duration, jitter) end
+```
+
+**参数说明：**
+
+| 参数名     | 类型    | 是否必填 | 默认值 | 描述                   |
+| ---------- | ------- | -------- | ------ | ---------------------- |
+| `x`        | number  | 是       | -      | 点击的 x 坐标          |
+| `y`        | number  | 是       | -      | 点击的 y 坐标          |
+| `duration` | number  | 否       | 20     | 点击持续时间，单位毫秒 |
+| `jitter`   | boolean | 否       | false  | 启用随机抖动偏移       |
+
+**返回值：**
+| 类型 | 描述 |
+| ---------- | ------- |
+| `boolean` | 点击是否成功 |
+
+**示例：**
+
+```lua
+local action = require("action")
+-- 基础点击
+local success = action.click(100, 100, 20, false)
+if success then
+  print("点击成功")
+end
+-- 带抖动的点击（更自然，避免检测）
+action.click(200, 300, 50, true)
+-- 快速点击
+action.click(150, 250, 10, false)
+-- 长按效果（增加持续时间）
+action.click(100, 100, 800, true)
+```
+
+### clickRandom - 执行随机点击操作
+
+```lua
+---@param x1 number
+---@param y1 number
+---@param x2 number
+---@param y2 number
+---@param duration number?
+---@return boolean
+function clickRandom(x1, y1, x2, y2, duration) end
+```
+
+**参数说明：**
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| ---------- | ------- | -------- | ------ | ------------------------------------------------------- |
+| `x1` | number | 是 | - | 随机点击区域的左上角 x 坐标 |
+| `y1` | number | 是 | - | 随机点击区域的左上角 y 坐标 |
+| `x2` | number | 是 | - | 随机点击区域的右下角 x 坐标 |
+| `y2` | number | 是 | - | 随机点击区域的右下角 y 坐标 |
+| `duration` | number | 否 | 20 | 点击持续时间，单位毫秒 |
+
+**返回值：**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 随机点击是否成功 |
+
+**示例：**
+
+```lua
+local action = require("action")
+-- 在指定矩形区域内随机点击
+action.clickRandom(100, 100, 200, 200, 20)
+-- 在更大区域内随机点击
+action.clickRandom(50, 50, 400, 600, 50)
+-- 快速随机点击
+action.clickRandom(150, 150, 250, 250, 10)
+```
+
+### doubleClick - 执行双击操作
+
+```lua
+---@param x number
+---@param y number
+---@param duration number?
+---@param interval number?
+---@param jitter boolean?
+---@return boolean
+function doubleClick(x, y, duration, interval, jitter) end
+```
+
+**参数说明：**
+
+| 参数名     | 类型    | 是否必填 | 默认值 | 描述                             |
+| ---------- | ------- | -------- | ------ | -------------------------------- |
+| `x`        | number  | 是       | -      | 双击的 x 坐标                    |
+| `y`        | number  | 是       | -      | 双击的 y 坐标                    |
+| `duration` | number  | 否       | 20     | 每次点击的持续时间，单位毫秒     |
+| `interval` | number  | 否       | 20     | 两次点击之间的间隔时间，单位毫秒 |
+| `jitter`   | boolean | 否       | false  | 启用随机抖动偏移                 |
+
+**返回值：**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 双击是否成功 |
+
+**示例：**
+
+```lua
+local action = require("action")
+-- 基础双击
+local success = action.doubleClick(100, 100, 20, 20, false)
+if success then
+  print("双击成功")
+end
+-- 带抖动的双击（更自然，避免检测）
+action.doubleClick(200, 300, 50, 20, true)
+-- 慢速双击（增加间隔时间）
+action.doubleClick(100, 100, 30, 300, true)
+```
+
+### doubleClickRandom - 执行随机双击操作
+
+```lua
+---@param x1 number
+---@param y1 number
+---@param x2 number
+---@param y2 number
+---@param duration number?
+---@param interval number?
+---@return boolean
+function doubleClickRandom(x1, y1, x2, y2, duration, interval) end
+```
+
+**参数说明：**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                             |
+| ---------- | ------ | -------- | ------ | -------------------------------- |
+| `x1`       | number | 是       | -      | 随机双击区域的左上角 x 坐标      |
+| `y1`       | number | 是       | -      | 随机双击区域的左上角 y 坐标      |
+| `x2`       | number | 是       | -      | 随机双击区域的右下角 x 坐标      |
+| `y2`       | number | 是       | -      | 随机双击区域的右下角 y 坐标      |
+| `duration` | number | 否       | 20     | 每次点击的持续时间，单位毫秒     |
+| `interval` | number | 否       | 20     | 两次点击之间的间隔时间，单位毫秒 |
+
+**返回值：**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 随机双击是否成功 |
+
+**示例：**
+
+```lua
+local action = require("action")
+-- 在指定矩形区域内随机双击
+action.doubleClickRandom(100, 100, 200, 200, 20, 20)
+-- 慢速随机双击
+action.doubleClickRandom(100, 100, 300, 300, 30, 300)
+```
+
+### swipe - 执行滑动操作
+
+```lua
+---@param startX number
+---@param startY number
+---@param endX number
+---@param endY number
+---@param duration number?
+---@param jitter boolean?
+---@param steps number?
+---@return boolean
+function swipe(startX, startY, endX, endY, duration, jitter, steps) end
+```
+
+**参数说明：**
+
+| 参数名     | 类型    | 是否必填 | 默认值 | 描述                                                   |
+| ---------- | ------- | -------- | ------ | ------------------------------------------------------ |
+| `startX`   | number  | 是       | -      | 滑动起始坐标 x 坐标                                    |
+| `startY`   | number  | 是       | -      | 滑动起始坐标 y 坐标                                    |
+| `endX`     | number  | 是       | -      | 滑动结束坐标 x 坐标                                    |
+| `endY`     | number  | 是       | -      | 滑动结束坐标 y 坐标                                    |
+| `duration` | number  | 否       | 100    | 滑动持续时间，单位毫秒                                 |
+| `jitter`   | boolean | 否       | false  | 是否开启抖动，开启后会在滑动路径上随机偏移，默认 false |
+| `steps`    | number  | 否       | 6      | 生成抖动点的数量，影响滑动的平滑度，默认 6             |
+
+**返回值：**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 滑动是否成功 |
+
+**示例：**
+
+```lua
+local action = require("action")
+-- 基础滑动（从左到右）
+action.swipe(100, 300, 400, 300, 500, false, 10)
+-- 向上滑动（滚动页面）
+action.swipe(200, 600, 200, 200, 800, true, 15)
+-- 向下滑动
+action.swipe(200, 200, 200, 600, 800, true, 15)
+-- 对角线滑动
+action.swipe(100, 100, 300, 400, 1000, true, 20)
+-- 快速滑动
+action.swipe(150, 500, 150, 100, 300, false, 5)
+-- 慢速精确滑动
+action.swipe(100, 200, 300, 200, 1500, true, 30)
+```
+
+### pressAndSwipe - 执行长按滑动操作，适用于拖拽等场景
+
+```lua
+---@param startX number
+---@param startY number
+---@param endX number
+---@param endY number
+---@param touch_down_duration number?
+---@param touch_move_duration number?
+---@param touch_up_duration number?
+---@param jitter boolean?
+---@param steps number?
+---@return boolean
+function pressAndSwipe(startX, startY, endX, endY, touch_down_duration, touch_move_duration, touch_up_duration, jitter, steps) end
+```
+
+**参数说明：**
+
+| 参数名                | 类型    | 是否必填 | 默认值 | 描述                                                   |
+| --------------------- | ------- | -------- | ------ | ------------------------------------------------------ |
+| `startX`              | number  | 是       | -      | 长按起始坐标 x 坐标                                    |
+| `startY`              | number  | 是       | -      | 长按起始坐标 y 坐标                                    |
+| `endX`                | number  | 是       | -      | 拖拽结束坐标 x 坐标                                    |
+| `endY`                | number  | 是       | -      | 拖拽结束坐标 y 坐标                                    |
+| `touch_down_duration` | number  | 否       | 500    | 按下阶段的持续时间，单位毫秒，默认 500ms               |
+| `touch_move_duration` | number  | 否       | 1000   | 移动阶段的持续时间，单位毫秒，默认 1000ms              |
+| `touch_up_duration`   | number  | 否       | 500    | 松开阶段的持续时间，默认 500ms                         |
+| `jitter`              | boolean | 否       | false  | 是否开启抖动，开启后会在滑动路径上随机偏移，默认 false |
+| `steps`               | number  | 否       | 6      | 移动过程中的步数，影响滑动的平滑度，默认 6             |
+
+**返回值：**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 长按滑动是否成功 |
+
+**示例：**
+
+```lua
+local action = require("action")
+-- 拖拽元素
+action.pressAndSwipe(
+  100,
+  100, -- 起始位置
+  300,
+  400, -- 目标位置
+  500, -- 按下500ms
+  1000, -- 移动1000ms
+  200, -- 松开200ms
+  true, -- 开启抖动
+  20, -- 20个步数
+)
+-- 长按拖拽（更长的按下时间）
+action.pressAndSwipe(150, 200, 350, 500, 1000, 800, 300, true, 15)
+-- 精确拖拽（无抖动）
+action.pressAndSwipe(200, 300, 200, 100, 300, 600, 100, false, 25)
+```
+
+### swipeCurve - 执行 3 点曲线滑动操作（先快后慢）
+
+```lua
+---@param startX number
+---@param startY number
+---@param midX number
+---@param midY number
+---@param endX number
+---@param endY number
+---@param duration number?
+---@return boolean
+function swipeCurve(startX, startY, midX, midY, endX, endY, duration) end
+```
+
+**参数说明：**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                  |
+| ---------- | ------ | -------- | ------ | ------------------------------------- |
+| `startX`   | number | 是       | -      | 滑动起始坐标 x 坐标                   |
+| `startY`   | number | 是       | -      | 滑动起始坐标 y 坐标                   |
+| `midX`     | number | 是       | -      | 曲线中间控制点 x 坐标                 |
+| `midY`     | number | 是       | -      | 曲线中间控制点 y 坐标                 |
+| `endX`     | number | 是       | -      | 滑动结束坐标 x 坐标                   |
+| `endY`     | number | 是       | -      | 滑动结束坐标 y 坐标                   |
+| `duration` | number | 否       | 1000   | 总滑动持续时间，单位毫秒，默认 1000ms |
+
+**返回值：**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 曲线滑动是否成功 |
+
+**功能特点：**
+
+- 使用二次贝塞尔曲线算法生成平滑的滑动路径
+- 实现先快后慢的滑动效果，模拟真实的手势操作
+- 根据滑动距离自动调整路径点数量，确保滑动平滑度
+- **拟人化轨迹**：添加随机偏移和微抖动，模拟真实人手操作的不稳定性
+- **随机化时间**：每个路径点的时间间隔都有随机变化，避免机械化操作
+- **智能偏移**：中间路径点偏移更大，起点和终点保持精确，更符合人类操作习惯
+- 适用于需要更自然滑动轨迹场景
+
+**示例：**
+
+```lua
+local action = require("action")
+-- 基础曲线滑动
+action.swipeCurve(100, 100, 200, 150, 300, 200, 1000)
+-- 弧形向上滑动
+action.swipeCurve(200, 500, 150, 300, 200, 100, 800)
+-- S形曲线滑动
+action.swipeCurve(100, 200, 300, 100, 200, 400, 1200)
+-- 快速曲线滑动
+action.swipeCurve(150, 300, 250, 200, 350, 400, 600)
+-- 慢速精确曲线滑动
+action.swipeCurve(100, 100, 200, 50, 300, 100, 1500)
+```
+
+## 文本输入操作
+
+- 仅输入框聚焦可用，以下方法是在模拟键盘操作
+- 更多高级输入操作，请参考 [IME 模块](ime.md)
+
+### input - 输入文本
+
+```lua
+---@param text string
+---@return boolean
+function input(text) end
+```
+
+**参数说明：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述             |
+| ------ | ------ | -------- | ------ | ---------------- |
+| `text` | string | 是       | -      | 要输入的文本内容 |
+
+**返回值：**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 输入文本是否成功 |
+
+**示例：**
+
+```lua
+local action = require("action")
+-- 输入文本
+local success = action.input("hello 快点JS")
+if success then
+  print("成功输入文本")
+end
+```
+
+### inputSimple - 基础文本输入
+
+通过键盘按键事件输入基础文本，适合英文、数字和常见 ASCII 符号。需要输入中文时请使用 `action.input`。
+
+```lua
+---@param text string
+---@return boolean
+function inputSimple(text) end
+```
+
+**参数说明：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述 |
+| ------ | ------ | -------- | ------ | ---- |
+| `text` | string | 是       | -      | 要输入的基础文本（建议 ASCII） |
+
+**示例：**
+
+```lua
+local action = require("action")
+local success = action.inputSimple("hello_123")
+if success then
+  print("成功输入文本")
+end
+```
+
+### backspace - 删除文本
+
+```lua
+---@param count number?
+---@return boolean
+function backspace(count) end
+```
+
+**参数说明：**
+
+| 参数名  | 类型   | 是否必填 | 默认值 | 描述                        |
+| ------- | ------ | -------- | ------ | --------------------------- |
+| `count` | number | 否       | 1      | 删除数量，默认删除 1 个字符 |
+
+**返回值：**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 删除文本是否成功 |
+
+**示例：**
+
+```lua
+local action = require("action")
+-- 删除最后一个字符
+local success = action.backspace()
+if success then
+  print("成功删除最后一个字符")
+end
+-- 删除多个字符
+local success = action.backspace(3)
+if success then
+  print("成功删除 3 个字符")
+end
+```
+
+### enter - 调用回车
+
+```lua
+---@return boolean
+function enter() end
+```
+
+**返回值：**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 调用回车是否成功 |
+
+**示例：**
+
+```lua
+local action = require("action")
+-- 调用回车
+local success = action.enter()
+if success then
+  print("成功调用回车")
+end
+```
+
+## 系统按键操作
+
+### homeScreen - 返回到设备主屏幕
+
+```lua
+---@return boolean
+function homeScreen() end
+```
+
+**返回值：**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 返回首页是否成功 |
+
+**示例：**
+
+```lua
+local action = require("action")
+-- 返回主屏幕
+local success = action.homeScreen()
+if success then
+  print("成功返回主屏幕")
+end
+
+-- 在操作完成后返回主屏幕
+local function completeTaskAndGoHome()
+  action.click(200, 300, 100, true)
+  Sleep(1000)
+  action.homeScreen()
+end
+```
+
+### pressButton - 按下系统按钮
+
+```lua
+---@param button string
+---@return boolean
+function pressButton(button) end
+```
+
+**参数说明：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                                                                                       |
+| -------- | ------ | -------- | ------ | ------------------------------------------------------------------------------------------ |
+| `button` | string | 是       | -      | 按钮类型： <br>-`"home"` Home 键 <br>- `"volumeup"` 音量上键 <br>- `"volumedown"` 音量下键 <br>- `"brightnessup"` 调高屏幕亮度 <br>- `"brightnessdown"` 调低屏幕亮度 |
+
+**返回值：**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 按下按钮是否成功 |
+
+**示例：**
+
+```lua
+local action = require("action")
+-- 按下 Home 键
+action.pressButton("home")
+-- 调高音量
+action.pressButton("volumeup")
+-- 调低音量
+action.pressButton("volumedown")
+-- 连续调节音量
+for i = 1, 5 do
+  action.pressButton("volumeup")
+  Sleep(200)
+end
+```
+
+### sendKey - 发送键盘组合键
+
+Action 模块最终发送标准 USB HID Keyboard/Keypad usage。参数可以传标准 usage 数字、单个 ASCII 字符、按键名称字符串，或裸全局 `HidKey` 常量。
+
+```lua
+---@param key (string|integer)[]
+---@return boolean
+function sendKey(key) end
+```
+
+**示例：**
+
+```lua
+local action = require("action")
+action.sendKey({ "COMMAND", "c" })
+action.sendKey({ 0xe3, 0x06 })
+action.sendKey({ HidKey.COMMAND, "v" })
+```
+
+### w3cActions - 执行 W3C Actions JSON
+
+```lua
+---@param json table
+---@return boolean
+function w3cActions(json) end
+```
+
+**示例：**
+
+```lua
+local action = require("action")
+action.w3cActions({
+  actions = {
+    {
+      type = "pointer",
+      id = "finger1",
+      parameters = { pointerType = "touch" },
+      actions = {},
+    },
+  },
+})
+```
+
+## 动作构建器
+
+ActionBuilder 提供了更高级的多点触控操作能力，支持链式调用构建复杂的手势动作。
+
+### createBuilder - 创建 ActionBuilder 构建器
+
+```lua
+---@return ActionBuilder
+function createBuilder() end
+```
+
+**返回值：**
+
+| 类型          | 描述                     |
+| ------------- | ------------------------ |
+| ActionBuilder | ActionBuilder 构建器实例 |
+
+**示例：**
+
+```lua
+local action = require("action")
+-- 创建构建器
+local builder = action.createBuilder()
+```
+
+### ActionBuilder - ActionBuilder 构建器
+
+ActionBuilder 构建器支持链式调用，可以构建复杂的多点触控动作。
+
+#### addPointer - 添加指针（手指）
+
+```lua
+---@param id number
+---@return PointerBuilder
+function addPointer(id) end
+```
+
+**参数说明：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                                 |
+| ------ | ------ | -------- | ------ | ------------------------------------ |
+| `id`   | number | 是       | -      | 指针编号，1-10，对应设备上的手指编号 |
+
+**返回值：**
+
+| 类型             | 描述                             |
+| ---------------- | -------------------------------- |
+| `PointerBuilder` | 指针构建器，用于配置该指针的动作 |
+
+**示例：**
+
+```lua
+local action = require("action")
+local builder = action.createBuilder()
+-- 添加第一个手指
+local pointer1 = builder:addPointer(1)
+-- 添加第二个手指
+local pointer2 = builder:addPointer(2)
+```
+
+#### singleTap - 快速单点点击
+
+```lua
+---@param x number
+---@param y number
+---@param duration number?
+---@return ActionBuilder
+function singleTap(x, y, duration) end
+```
+
+**参数说明：**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                  |
+| ---------- | ------ | -------- | ------ | ------------------------------------- |
+| `x`        | number | 是       | -      | X 坐标                                |
+| `y`        | number | 是       | -      | Y 坐标                                |
+| `duration` | number | 否       | 20     | 点击持续时间，如果未定义则默认为 20ms |
+
+**返回值：**
+
+| 类型            | 描述                   |
+| --------------- | ---------------------- |
+| `ActionBuilder` | 返回自身，支持链式调用 |
+
+**示例：**
+
+```lua
+local action = require("action")
+local builder = action.createBuilder()
+-- 快速单点点击
+builder:singleTap(100, 100, 50):execute()
+-- 连续点击
+builder:singleTap(100, 100, 30):singleTap(200, 200, 30):execute()
+```
+
+#### multiTap - 快速多点点击
+
+```lua
+---@param points table
+---@param duration number?
+---@return ActionBuilder
+function multiTap(points, duration) end
+```
+
+**参数说明：**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                   |
+| ---------- | ------ | -------- | ------ | -------------------------------------- |
+| `points`   | array  | 是       | -      | 点击坐标数组，每个元素包含 x 和 y 坐标 |
+| `duration` | number | 否       | 20     | 点击持续时间，如果未定义则默认为 20ms  |
+
+**返回值：**
+
+| 类型            | 描述                   |
+| --------------- | ---------------------- |
+| `ActionBuilder` | 返回自身，支持链式调用 |
+
+**示例：**
+
+```lua
+local action = require("action")
+local builder = action.createBuilder()
+-- 多点同时点击
+local points = { { x = 100, y = 100 },
+  { x = 200, y = 200 },
+  { x = 300, y = 300 },
+]
+builder:multiTap(points, 50):execute()
+-- 双指点击
+builder
+  :multiTap(
+    { { x = 150, y = 300 },
+      { x = 250, y = 300 },
+    ],
+    100,
+  )
+  :execute()
+```
+
+#### execute - 执行动作
+
+```lua
+---@return boolean
+function execute() end
+```
+
+**返回值：**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 执行是否成功 |
+
+**示例：**
+
+```lua
+local action = require("action")
+local builder = action.createBuilder()
+-- 执行构建的动作
+local success = builder
+  :addPointer(1)
+  :moveTo(100, 100)
+  :tap(200, 200)
+  :done()
+  :execute()
+
+if success then
+  print("动作执行成功")
+end
+```
+
+### PointerBuilder - 指针构建器
+
+指针构建器用于配置单个指针（手指）的动作序列。
+
+#### moveTo - 移动到指定坐标
+
+```lua
+---@param x number
+---@param y number
+---@param duration number?
+---@return PointerBuilder
+function moveTo(x, y, duration) end
+```
+
+**参数说明：**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                 |
+| ---------- | ------ | -------- | ------ | ------------------------------------ |
+| `x`        | number | 是       | -      | X 坐标                               |
+| `y`        | number | 是       | -      | Y 坐标                               |
+| `duration` | number | 否       | 0      | 移动持续时间，如果未定义则默认为 0ms |
+
+**返回值：**
+
+| 类型             | 描述                   |
+| ---------------- | ---------------------- |
+| `PointerBuilder` | 返回自身，支持链式调用 |
+
+#### down - 按下手指
+
+```lua
+---@return PointerBuilder
+function down() end
+```
+
+**返回值：**
+
+| 类型           | 描述                   |
+| -------------- | ---------------------- |
+| PointerBuilder | 返回自身，支持链式调用 |
+
+#### up - 抬起手指
+
+```lua
+---@return PointerBuilder
+function up() end
+```
+
+**返回值：**
+
+| 类型             | 描述                   |
+| ---------------- | ---------------------- |
+| `PointerBuilder` | 返回自身，支持链式调用 |
+
+#### stay - 停留时间
+
+```lua
+---@param duration number?
+---@return PointerBuilder
+function stay(duration) end
+```
+
+**参数说明：**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                      |
+| ---------- | ------ | -------- | ------ | ----------------------------------------- |
+| `duration` | number | 否       | 20     | 停留时间（毫秒），如果未定义则默认为 20ms |
+
+**返回值：**
+
+| 类型             | 描述                   |
+| ---------------- | ---------------------- |
+| `PointerBuilder` | 返回自身，支持链式调用 |
+
+#### tap - 执行点击动作
+
+```lua
+---@param x number
+---@param y number
+---@param duration number?
+---@return PointerBuilder
+function tap(x, y, duration) end
+```
+
+**参数说明：**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                  |
+| ---------- | ------ | -------- | ------ | ------------------------------------- |
+| `x`        | number | 是       | -      | X 坐标                                |
+| `y`        | number | 是       | -      | Y 坐标                                |
+| `duration` | number | 否       | 20     | 按下持续时间，如果未定义则默认为 20ms |
+
+**返回值：**
+
+| 类型             | 描述                   |
+| ---------------- | ---------------------- |
+| `PointerBuilder` | 返回自身，支持链式调用 |
+
+**功能说明：**
+
+- 自动执行：移动 -> 按下 -> 暂停 -> 抬起的完整点击序列
+
+#### done - 完成指针配置
+
+```lua
+---@return ActionBuilder
+function done() end
+```
+
+**返回值：**
+
+| 类型            | 描述                               |
+| --------------- | ---------------------------------- |
+| `ActionBuilder` | 返回主构建器，可以继续添加其他指针 |
+
+## 高级使用示例
+
+### 单指滑动
+
+```lua
+local action = require("action")
+-- 单指从左到右滑动
+local builder = action.createBuilder()
+builder
+  :addPointer(1)
+  :moveTo(100, 300, 0) -- 移动到起始位置
+  :down() -- 按下
+  :moveTo(400, 300, 500) -- 滑动到结束位置
+  :up() -- 抬起
+  :done()
+  :execute()
+```
+
+### 双指缩放（放大）
+
+```lua
+local action = require("action")
+-- 双指从中心向外扩展
+local builder = action.createBuilder()
+builder
+  :addPointer(1)
+  :moveTo(200, 300, 0) -- 第一个手指起始位置
+  :down()
+  :moveTo(150, 250, 300) -- 向左上移动
+  :up()
+  :done()
+  :addPointer(2)
+  :moveTo(200, 300, 0) -- 第二个手指起始位置
+  :down()
+  :moveTo(250, 350, 300) -- 向右下移动
+  :up()
+  :done()
+  :execute()
+```
+
+### 双指缩放（缩小）
+
+```lua
+local action = require("action")
+-- 双指从外向中心收缩
+local builder = action.createBuilder()
+builder
+  :addPointer(1)
+  :moveTo(150, 250, 0) -- 第一个手指起始位置
+  :down()
+  :moveTo(200, 300, 300) -- 向中心移动
+  :up()
+  :done()
+  :addPointer(2)
+  :moveTo(250, 350, 0) -- 第二个手指起始位置
+  :down()
+  :moveTo(200, 300, 300) -- 向中心移动
+  :up()
+  :done()
+  :execute()
+```
+
+### 双指旋转
+
+```lua
+local action = require("action")
+-- 双指围绕中心点旋转
+local builder = action.createBuilder()
+local centerX = 200,
+  centerY = 300
+local radius = 50
+
+builder
+  :addPointer(1)
+  :moveTo(centerX - radius, centerY, 0) -- 左侧起始
+  :down()
+  :moveTo(centerX, centerY - radius, 200) -- 向上旋转
+  :moveTo(centerX + radius, centerY, 200) -- 向右旋转
+  :up()
+  :done()
+  :addPointer(2)
+  :moveTo(centerX + radius, centerY, 0) -- 右侧起始
+  :down()
+  :moveTo(centerX, centerY + radius, 200) -- 向下旋转
+  :moveTo(centerX - radius, centerY, 200) -- 向左旋转
+  :up()
+  :done()
+  :execute()
+```
+
+### 长按拖拽
+
+```lua
+local action = require("action")
+-- 长按后拖拽元素
+local builder = action.createBuilder()
+builder
+  :addPointer(1)
+  :moveTo(100, 100, 0) -- 移动到目标位置
+  :down() -- 按下
+  :stay(800) -- 长按 800ms
+  :moveTo(300, 400, 1000) -- 拖拽到新位置
+  :up() -- 抬起
+  :done()
+  :execute()
+```
+
+### 复杂手势组合
+
+```lua
+local action = require("action")
+-- 先点击，再滑动，最后双击
+local builder = action.createBuilder()
+-- 第一步：单击
+builder:singleTap(100, 100, 50)
+-- 第二步：滑动
+builder
+  :addPointer(1)
+  :moveTo(200, 200, 0)
+  :down()
+  :moveTo(400, 200, 600)
+  :up()
+  :done()
+-- 第三步：双击
+builder:multiTap({ { x = 300, y = 300 } }, 30)
+-- 执行所有动作
+builder:execute()
+```