ms-vite-plugin 1.1.2 → 1.1.4

package/docs/apicn/action.md

@@ -0,0 +1,919 @@
+# 动作模块 ($动作)
+
+动作模块提供了丰富的触摸和按键操作功能，包括点击、滑动、长按滑动、返回首页、多点触摸等动作。
+
+**注意事项**
+
+- 此模块仅支持 快点 Agent 模式使用
+- HID 模式，请使用 HID 模块
+
+## 抖动值
+
+### 设置抖动值 - 设置动作抖动值
+
+默认抖动值为 5 像素，设置后有 jitter 参数的动作会在像素范围 `-抖动值` 到 `抖动值` 随机偏移。
+
+```typescript
+function 设置抖动值(抖动值: 数字): 无返回值;
+```
+
+**参数说明：**
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| ---------- | ------- | -------- | ------ | ------------------------------------------------------- |
+| `抖动值` | 数字 | 是 | - | 抖动值，点击、滑动等动作会在像素范围 `-抖动值` 到 `抖动值` 随机偏移 |
+
+**示例：**
+
+```javascript
+// 设置抖动值为5像素
+$动作.设置抖动值(5);
+```
+
+## 基础触摸操作
+
+### 点击
+
+```typescript
+function 点击(
+  坐标x: 数字,
+  坐标y: 数字,
+  按下持续时间?: 数字,
+  抖动?: 布尔值,
+): 布尔值;
+```
+
+**参数说明：**
+
+| 参数名         | 类型   | 是否必填 | 默认值 | 描述                   |
+| -------------- | ------ | -------- | ------ | ---------------------- |
+| `坐标x`        | 数字   | 是       | -      | 点击的 x 坐标          |
+| `坐标y`        | 数字   | 是       | -      | 点击的 y 坐标          |
+| `按下持续时间` | 数字   | 否       | 20     | 点击持续时间，单位毫秒 |
+| `抖动`         | 布尔值 | 否       | false  | 启用随机抖动偏移       |
+
+**返回值：**
+| 类型 | 描述 |
+| ---------- | ------- |
+| `布尔值` | 点击是否成功 |
+
+**示例：**
+
+```typescript
+// 基础点击
+$动作.点击(100, 100, 20, false);
+
+// 带抖动的点击（更自然，避免检测）
+$动作.点击(200, 300, 50, true);
+
+// 长按效果（增加持续时间）
+$动作.点击(100, 100, 800, true);
+```
+
+### 点击随机范围
+
+```typescript
+function 点击随机范围(
+  区域左上角x坐标: 数字,
+  区域左上角y坐标: 数字,
+  区域右下角x坐标: 数字,
+  区域右下角y坐标: 数字,
+  按下持续时间?: 数字,
+): 布尔值;
+```
+
+**参数说明：**
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| ---------- | ------- | -------- | ------ | ------------------------------------------------------- |
+| `区域左上角x坐标` | 数字 | 是 | - | 随机点击区域的左上角 x 坐标 |
+| `区域左上角y坐标` | 数字 | 是 | - | 随机点击区域的左上角 y 坐标 |
+| `区域右下角x坐标` | 数字 | 是 | - | 随机点击区域的右下角 x 坐标 |
+| `区域右下角y坐标` | 数字 | 是 | - | 随机点击区域的右下角 y 坐标 |
+| `按下持续时间` | 数字 | 否 | 20 | 点击持续时间，单位毫秒 |
+
+**返回值：**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `布尔值` | 随机点击是否成功 |
+
+**示例：**
+
+```typescript
+// 在指定矩形区域内随机点击
+$动作.点击随机范围(100, 100, 200, 200, 20);
+
+// 在更大区域内随机点击
+$动作.点击随机范围(50, 50, 400, 600, 50);
+
+// 快速随机点击
+$动作.点击随机范围(150, 150, 250, 250, 10);
+```
+
+### 双击
+
+```typescript
+function 双击(
+  坐标x: 数字,
+  坐标y: 数字,
+  按下持续时间?: 数字,
+  间隔时间?: 数字,
+  抖动?: 布尔值,
+): 布尔值;
+```
+
+**参数说明：**
+
+| 参数名         | 类型   | 是否必填 | 默认值 | 描述                             |
+| -------------- | ------ | -------- | ------ | -------------------------------- |
+| `坐标x`        | 数字   | 是       | -      | 双击的 x 坐标                    |
+| `坐标y`        | 数字   | 是       | -      | 双击的 y 坐标                    |
+| `按下持续时间` | 数字   | 否       | 20     | 每次点击的持续时间，单位毫秒     |
+| `间隔时间`     | 数字   | 否       | 20     | 两次点击之间的间隔时间，单位毫秒 |
+| `抖动`         | 布尔值 | 否       | false  | 启用随机抖动偏移                 |
+
+**返回值：**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 双击是否成功 |
+
+**示例：**
+
+```typescript
+// 基础双击
+$动作.双击(100, 100, 20, 20, false);
+
+// 带抖动的双击（更自然，避免检测）
+$动作.双击(200, 300, 50, 20, true);
+
+// 慢速双击（增加间隔时间）
+$动作.双击(100, 100, 30, 300, true);
+```
+
+### 双击随机范围
+
+```typescript
+function 双击随机范围(
+  区域左上角x坐标: 数字,
+  区域左上角y坐标: 数字,
+  区域右下角x坐标: 数字,
+  区域右下角y坐标: 数字,
+  按下持续时间?: 数字,
+  间隔时间?: 数字,
+): 布尔值;
+```
+
+**参数说明：**
+
+| 参数名            | 类型 | 是否必填 | 默认值 | 描述                             |
+| ----------------- | ---- | -------- | ------ | -------------------------------- |
+| `区域左上角x坐标` | 数字 | 是       | -      | 随机双击区域的左上角 x 坐标      |
+| `区域左上角y坐标` | 数字 | 是       | -      | 随机双击区域的左上角 y 坐标      |
+| `区域右下角x坐标` | 数字 | 是       | -      | 随机双击区域的右下角 x 坐标      |
+| `区域右下角y坐标` | 数字 | 是       | -      | 随机双击区域的右下角 y 坐标      |
+| `按下持续时间`    | 数字 | 否       | 20     | 每次点击的持续时间，单位毫秒     |
+| `间隔时间`        | 数字 | 否       | 20     | 两次点击之间的间隔时间，单位毫秒 |
+
+**返回值：**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `布尔值` | 随机双击是否成功 |
+
+**示例：**
+
+```typescript
+// 在指定矩形区域内随机双击
+$动作.双击随机范围(100, 100, 200, 200, 20, 20);
+
+// 慢速随机双击
+$动作.双击随机范围(100, 100, 300, 300, 30, 300);
+```
+
+### 滑动
+
+```typescript
+function 滑动(
+  起始x坐标: 数字,
+  起始y坐标: 数字,
+  目标x坐标: 数字,
+  目标y坐标: 数字,
+  滑动持续时间?: 数字,
+  抖动?: 布尔值,
+  步数?: 数字,
+): 布尔值;
+```
+
+**参数说明：**
+
+| 参数名         | 类型   | 是否必填 | 默认值 | 描述                                                   |
+| -------------- | ------ | -------- | ------ | ------------------------------------------------------ |
+| `起始x坐标`    | 数字   | 是       | -      | 滑动起始坐标 x 坐标                                    |
+| `起始y坐标`    | 数字   | 是       | -      | 滑动起始坐标 y 坐标                                    |
+| `目标x坐标`    | 数字   | 是       | -      | 滑动结束坐标 x 坐标                                    |
+| `目标y坐标`    | 数字   | 是       | -      | 滑动结束坐标 y 坐标                                    |
+| `滑动持续时间` | 数字   | 否       | 100    | 滑动持续时间，单位毫秒                                 |
+| `抖动`         | 布尔值 | 否       | false  | 是否开启抖动，开启后会在滑动路径上随机偏移，默认 false |
+| `步数`         | 数字   | 否       | 6      | 生成抖动点的数量，影响滑动的平滑度，默认 6             |
+
+**返回值：**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 滑动是否成功 |
+
+**示例：**
+
+```typescript
+// 基础滑动（从左到右）
+$动作.滑动(100, 300, 400, 300, 500, false, 10);
+
+// 向上滑动（滚动页面）
+$动作.滑动(200, 600, 200, 200, 800, true, 15);
+
+// 向下滑动
+$动作.滑动(200, 200, 200, 600, 800, true, 15);
+
+// 对角线滑动
+$动作.滑动(100, 100, 300, 400, 1000, true, 20);
+
+// 快速滑动
+$动作.滑动(150, 500, 150, 100, 300, false, 5);
+
+// 慢速精确滑动
+$动作.滑动(100, 200, 300, 200, 1500, true, 30);
+```
+
+### 长按并滑动
+
+```typescript
+function 长按并滑动(
+  起始x坐标: 数字,
+  起始y坐标: 数字,
+  目标x坐标: 数字,
+  目标y坐标: 数字,
+  按下持续时间?: 数字,
+  移动持续时间?: 数字,
+  松开持续时间?: 数字,
+  抖动?: 布尔值,
+  步数?: 数字,
+): 布尔值;
+```
+
+**参数说明：**
+
+| 参数名         | 类型   | 是否必填 | 默认值 | 描述                                                   |
+| -------------- | ------ | -------- | ------ | ------------------------------------------------------ |
+| `起始x坐标`    | 数字   | 是       | -      | 长按起始坐标 x 坐标                                    |
+| `起始y坐标`    | 数字   | 是       | -      | 长按起始坐标 y 坐标                                    |
+| `目标x坐标`    | 数字   | 是       | -      | 长按滑动目标坐标 x 坐标                                |
+| `目标y坐标`    | 数字   | 是       | -      | 长按滑动目标坐标 y 坐标                                |
+| `按下持续时间` | 数字   | 否       | 500    | 按下阶段的持续时间，单位毫秒，默认 500ms               |
+| `移动持续时间` | 数字   | 否       | 1000   | 移动阶段的持续时间，单位毫秒，默认 1000ms              |
+| `松开持续时间` | 数字   | 否       | 500    | 松开阶段的持续时间，默认 500ms                         |
+| `抖动`         | 布尔值 | 否       | false  | 是否开启抖动，开启后会在滑动路径上随机偏移，默认 false |
+| `步数`         | 数字   | 否       | 6      | 移动过程中的步数，影响滑动的平滑度，默认 6             |
+
+**返回值：**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `布尔值` | 长按滑动是否成功 |
+
+**示例：**
+
+```typescript
+// 拖拽元素
+$动作.长按并滑动(
+  100,
+  100, // 起始位置
+  300,
+  400, // 目标位置
+  500, // 按下500ms
+  1000, // 移动1000ms
+  200, // 松开200ms
+  true, // 开启抖动
+  20, // 20个步数
+);
+
+// 长按拖拽（更长的按下时间）
+$动作.长按并滑动(150, 200, 350, 500, 1000, 800, 300, true, 15);
+
+// 精确拖拽（无抖动）
+$动作.长按并滑动(200, 300, 200, 100, 300, 600, 100, false, 25);
+```
+
+### 曲线滑动 - 执行 3 点曲线滑动操作（先快后慢）
+
+```typescript
+function 曲线滑动(
+  起始x坐标: 数字,
+  起始y坐标: 数字,
+  中间点x坐标: 数字,
+  中间点y坐标: 数字,
+  目标x坐标: 数字,
+  目标y坐标: 数字,
+  滑动持续时间?: 数字,
+): 布尔值;
+```
+
+**参数说明：**
+
+| 参数名         | 类型 | 是否必填 | 默认值 | 描述                                  |
+| -------------- | ---- | -------- | ------ | ------------------------------------- |
+| `起始x坐标`    | 数字 | 是       | -      | 滑动起始坐标 x 坐标                   |
+| `起始y坐标`    | 数字 | 是       | -      | 滑动起始坐标 y 坐标                   |
+| `中间点x坐标`  | 数字 | 是       | -      | 曲线中间控制点 x 坐标                 |
+| `中间点y坐标`  | 数字 | 是       | -      | 曲线中间控制点 y 坐标                 |
+| `目标x坐标`    | 数字 | 是       | -      | 滑动结束坐标 x 坐标                   |
+| `目标y坐标`    | 数字 | 是       | -      | 滑动结束坐标 y 坐标                   |
+| `滑动持续时间` | 数字 | 否       | 1000   | 总滑动持续时间，单位毫秒，默认 1000ms |
+
+**返回值：**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `布尔值` | 曲线滑动是否成功 |
+
+**功能特点：**
+
+- 使用二次贝塞尔曲线算法生成平滑的滑动路径
+- 实现先快后慢的滑动效果，模拟真实的手势操作
+- 根据滑动距离自动调整路径点数量，确保滑动平滑度
+- **拟人化轨迹**：添加随机偏移和微抖动，模拟真实人手操作的不稳定性
+- **随机化时间**：每个路径点的时间间隔都有随机变化，避免机械化操作
+- **智能偏移**：中间路径点偏移更大，起点和终点保持精确，更符合人类操作习惯
+- 适用于需要更自然滑动轨迹场景
+
+**示例：**
+
+```typescript
+// 基础曲线滑动
+$动作.曲线滑动(100, 100, 200, 150, 300, 200, 1000);
+
+// 弧形向上滑动
+$动作.曲线滑动(200, 500, 150, 300, 200, 100, 800);
+
+// S形曲线滑动
+$动作.曲线滑动(100, 200, 300, 100, 200, 400, 1200);
+
+// 快速曲线滑动
+$动作.曲线滑动(150, 300, 250, 200, 350, 400, 600);
+
+// 慢速精确曲线滑动
+$动作.曲线滑动(100, 100, 200, 50, 300, 100, 1500);
+```
+
+## 文本输入操作
+
+- 仅输入框聚焦可用，以下方法是在模拟键盘操作
+- 更多高级输入操作，请参考 [IME 模块](ime.md)
+
+### 输入文本
+
+```typescript
+function 输入文本(文本: 字符串): 布尔值;
+```
+
+**参数说明：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述             |
+| ------ | ------ | -------- | ------ | ---------------- |
+| `文本` | 字符串 | 是       | -      | 要输入的文本内容 |
+
+**返回值：**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `布尔值` | 输入文本是否成功 |
+
+**示例：**
+
+```javascript
+// 输入文本
+const 是否成功 = $动作.输入文本("hello 快点JS");
+if (是否成功) {
+  $打印信息日志("成功输入文本");
+}
+```
+
+### 删除文本
+
+```typescript
+function 删除文本(删除数量?: 数字): 布尔值;
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                        |
+| ---------- | ---- | -------- | ------ | --------------------------- |
+| `删除数量` | 数字 | 否       | 1      | 删除数量，默认删除 1 个字符 |
+
+**返回值：**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `布尔值` | 删除文本是否成功 |
+
+**示例：**
+
+```typescript
+// 删除最后一个字符
+const 是否成功 = $动作.删除文本();
+if (是否成功) {
+  $打印信息日志("成功删除最后一个字符");
+}
+
+// 删除多个字符
+const 是否成功 = $动作.删除文本(3);
+if (是否成功) {
+  $打印信息日志("成功删除 3 个字符");
+}
+```
+
+### 回车
+
+```typescript
+function 回车(): 布尔值;
+```
+
+**返回值：**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `布尔值` | 调用回车是否成功 |
+
+**示例：**
+
+```typescript
+// 调用回车
+const 是否成功 = $动作.回车();
+if (是否成功) {
+  $打印信息日志("成功调用回车");
+}
+```
+
+## 系统按键操作
+
+### 回到主页
+
+```typescript
+function 回到主页(): 布尔值;
+```
+
+**返回值：**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `布尔值` | 返回首页是否成功 |
+
+**示例：**
+
+```typescript
+// 返回主屏幕
+const 是否成功 = $动作.回到主页();
+if (是否成功) {
+  $打印信息日志("成功返回主屏幕");
+}
+
+// 在操作完成后返回主屏幕
+function completeTaskAndGoHome() {
+  // 执行一些操作...
+  $动作.点击(200, 300, 100, true);
+  sleep(1000);
+
+  // 返回主屏幕
+  $动作.回到主页();
+}
+```
+
+### 按键 - 按下系统按钮
+
+```typescript
+function 按键(按键: "home" | "volumeup" | "volumedown"): 布尔值;
+```
+
+**参数说明：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                                                                                       |
+| ------ | ------ | -------- | ------ | ------------------------------------------------------------------------------------------ |
+| `按键` | 字符串 | 是       | -      | 按钮类型： <br>-`"home"` Home 键 <br>- `"volumeup"` 音量上键 <br>- `"volumedown"` 音量下键 |
+
+**返回值：**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `布尔值` | 按下按钮是否成功 |
+
+**示例：**
+
+```typescript
+// 按下 Home 键
+$动作.按键("home");
+
+// 调高音量
+$动作.按键("volumeup");
+
+// 调低音量
+$动作.按键("volumedown");
+
+// 连续调节音量
+for (let i = 0; i < 5; i++) {
+  const 是否成功 = $动作.按键("volumeup");
+  if (是否成功) {
+    $打印信息日志("成功调高音量");
+  }
+  $延时(200);
+}
+```
+
+## 动作构建器
+
+动作构建器 提供了更高级的多点触控操作能力，支持链式调用构建复杂的手势动作。
+
+### 创建动作构建器
+
+```typescript
+function 创建动作构建器(): $动作构建器;
+```
+
+**返回值：**
+
+| 类型          | 描述           |
+| ------------- | -------------- |
+| `$动作构建器` | 动作构建器实例 |
+
+**示例：**
+
+```javascript
+// 创建构建器
+const 动作构建器 = $动作.创建动作构建器();
+```
+
+### 动作构建器
+
+动作构建器 支持链式调用，可以构建复杂的多点触控动作。
+
+#### 添加手指
+
+```typescript
+function 添加手指(手指: 数字): $指针构建器;
+```
+
+**参数说明：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述                                 |
+| ------ | ---- | -------- | ------ | ------------------------------------ |
+| `手指` | 数字 | 是       | -      | 指针编号，1-10，对应设备上的手指编号 |
+
+**返回值：**
+
+| 类型          | 描述                             |
+| ------------- | -------------------------------- |
+| `$指针构建器` | 指针构建器，用于配置该指针的动作 |
+
+**示例：**
+
+```javascript
+const 动作构建器 = $动作.创建动作构建器();
+// 添加第一个手指
+const 指针1 = 动作构建器.添加手指(1);
+
+// 添加第二个手指
+const 指针2 = 动作构建器.添加手指(2);
+```
+
+#### 单指点击
+
+```typescript
+function 单指点击(坐标x: 数字, 坐标y: 数字, 持续时间?: 数字): $动作构建器;
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                                  |
+| ---------- | ---- | -------- | ------ | ------------------------------------- |
+| `坐标x`    | 数字 | 是       | -      | X 坐标                                |
+| `坐标y`    | 数字 | 是       | -      | Y 坐标                                |
+| `持续时间` | 数字 | 否       | 20     | 点击持续时间，如果未定义则默认为 20ms |
+
+**返回值：**
+
+| 类型          | 描述                   |
+| ------------- | ---------------------- |
+| `$指针构建器` | 返回自身，支持链式调用 |
+
+**示例：**
+
+```javascript
+const 动作构建器 = $动作.创建动作构建器();
+// 快速单点点击
+动作构建器.单指点击(100, 100, 50).执行();
+
+// 连续点击
+动作构建器.单指点击(100, 100, 30).单指点击(200, 200, 30).执行();
+```
+
+#### 多指点击
+
+```typescript
+function 多指点击(
+  坐标数组: Array<{ x: 数字; y: 数字 }>,
+  持续时间?: 数字,
+): $动作构建器;
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                                   |
+| ---------- | ---- | -------- | ------ | -------------------------------------- |
+| `坐标数组` | 数组 | 是       | -      | 点击坐标数组，每个元素包含 x 和 y 坐标 |
+| `持续时间` | 数字 | 否       | 20     | 点击持续时间，如果未定义则默认为 20ms  |
+
+**返回值：**
+
+| 类型          | 描述                   |
+| ------------- | ---------------------- |
+| `$动作构建器` | 返回自身，支持链式调用 |
+
+**示例：**
+
+```javascript
+const 动作构建器 = $动作.创建动作构建器();
+// 多点同时点击
+const 点击坐标数组 = [
+  { x: 100, y: 100 },
+  { x: 200, y: 200 },
+  { x: 300, y: 300 },
+];
+动作构建器.多指点击(点击坐标数组, 50).执行();
+
+// 双指点击
+动作构建器
+  .多指点击(
+    [
+      { x: 150, y: 300 },
+      { x: 250, y: 300 },
+    ],
+    100,
+  )
+  .执行();
+```
+
+#### 执行
+
+```typescript
+function 执行(): 布尔值;
+```
+
+**返回值：**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 执行是否成功 |
+
+**示例：**
+
+```javascript
+const 动作构建器 = $动作.创建动作构建器();
+// 执行构建的动作
+const 执行成功 = 动作构建器
+  .添加手指(1)
+  .移动到(100, 100)
+  .点击(200, 200)
+  .完成()
+  .执行();
+
+if (执行成功) {
+  $打印信息日志("动作执行成功");
+}
+```
+
+### 指针构建器
+
+指针构建器用于配置单个指针（手指）的动作序列。
+
+#### 移动到
+
+```typescript
+function 移动到(坐标x: 数字, 坐标y: 数字, 持续时间?: 数字): $指针构建器;
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                                 |
+| ---------- | ---- | -------- | ------ | ------------------------------------ |
+| `坐标x`    | 数字 | 是       | -      | X 坐标                               |
+| `坐标y`    | 数字 | 是       | -      | Y 坐标                               |
+| `持续时间` | 数字 | 否       | 0      | 移动持续时间，如果未定义则默认为 0ms |
+
+**返回值：**
+
+| 类型          | 描述                   |
+| ------------- | ---------------------- |
+| `$指针构建器` | 返回自身，支持链式调用 |
+
+#### 按下
+
+```typescript
+function 按下(): $指针构建器;
+```
+
+**返回值：**
+
+| 类型          | 描述                   |
+| ------------- | ---------------------- |
+| `$指针构建器` | 返回自身，支持链式调用 |
+
+#### 抬起
+
+```typescript
+function 抬起(): $指针构建器;
+```
+
+**返回值：**
+
+| 类型          | 描述                   |
+| ------------- | ---------------------- |
+| `$指针构建器` | 返回自身，支持链式调用 |
+
+#### 停留
+
+```typescript
+function 停留(持续时间?: 数字): $指针构建器;
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                                      |
+| ---------- | ---- | -------- | ------ | ----------------------------------------- |
+| `持续时间` | 数字 | 否       | 20     | 停留时间（毫秒），如果未定义则默认为 20ms |
+
+**返回值：**
+
+| 类型          | 描述                   |
+| ------------- | ---------------------- |
+| `$指针构建器` | 返回自身，支持链式调用 |
+
+#### 点击
+
+```typescript
+function 点击(坐标x: 数字, 坐标y: 数字, 持续时间?: 数字): $指针构建器;
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                                  |
+| ---------- | ---- | -------- | ------ | ------------------------------------- |
+| `坐标x`    | 数字 | 是       | -      | X 坐标                                |
+| `坐标y`    | 数字 | 是       | -      | Y 坐标                                |
+| `持续时间` | 数字 | 否       | 20     | 按下持续时间，如果未定义则默认为 20ms |
+
+**返回值：**
+
+| 类型          | 描述                   |
+| ------------- | ---------------------- |
+| `$指针构建器` | 返回自身，支持链式调用 |
+
+**功能说明：**
+
+- 自动执行：移动 -> 按下 -> 暂停 -> 抬起的完整点击序列
+
+#### 完成
+
+```typescript
+function 完成(): $动作构建器;
+```
+
+**返回值：**
+
+| 类型          | 描述                               |
+| ------------- | ---------------------------------- |
+| `$动作构建器` | 返回主构建器，可以继续添加其他指针 |
+
+## 高级使用示例
+
+### 单指滑动
+
+```javascript
+// 单指从左到右滑动
+const 动作构建器 = $动作.创建动作构建器();
+动作构建器
+  .添加手指(1)
+  .移动到(100, 300, 0) // 移动到起始位置
+  .按下() // 按下
+  .移动到(400, 300, 500) // 滑动到结束位置
+  .抬起() // 抬起
+  .完成()
+  .执行();
+```
+
+### 双指缩放（放大）
+
+```javascript
+// 双指从中心向外扩展
+const 动作构建器 = $动作.创建动作构建器();
+动作构建器
+  .添加手指(1)
+  .移动到(200, 300, 0) // 第一个手指起始位置
+  .按下() // 按下
+  .移动到(150, 250, 300) // 向左上移动
+  .抬起() // 抬起
+  .完成()
+  .添加手指(2)
+  .移动到(200, 300, 0) // 第二个手指起始位置
+  .按下() // 按下
+  .移动到(250, 350, 300) // 向右下移动
+  .抬起() // 抬起
+  .完成()
+  .执行();
+```
+
+### 双指缩放（缩小）
+
+```javascript
+// 双指从外向中心收缩
+const 动作构建器 = $动作.创建动作构建器();
+动作构建器
+  .添加手指(1)
+  .移动到(150, 250, 0) // 第一个手指起始位置
+  .按下() // 按下
+  .移动到(200, 300, 300) // 向中心移动
+  .抬起() // 抬起
+  .完成()
+  .添加手指(2)
+  .移动到(250, 350, 0) // 第二个手指起始位置
+  .按下() // 按下
+  .移动到(200, 300, 300) // 向中心移动
+  .抬起() // 抬起
+  .完成()
+  .执行();
+```
+
+### 双指旋转
+
+```javascript
+// 双指围绕中心点旋转
+const 动作构建器 = $动作.创建动作构建器();
+const centerX = 200,
+  centerY = 300;
+const radius = 50;
+
+动作构建器
+  .添加手指(1)
+  .移动到(centerX - radius, centerY, 0) // 左侧起始
+  .按下() // 按下
+  .移动到(centerX, centerY - radius, 200) // 向上旋转
+  .移动到(centerX + radius, centerY, 200) // 向右旋转
+  .抬起() // 抬起
+  .完成()
+  .添加手指(2)
+  .移动到(centerX + radius, centerY, 0) // 右侧起始
+  .按下() // 按下
+  .移动到(centerX, centerY + radius, 200) // 向下旋转
+  .移动到(centerX - radius, centerY, 200) // 向左旋转
+  .抬起() // 抬起
+  .完成()
+  .执行();
+```
+
+### 长按拖拽
+
+```javascript
+// 长按后拖拽元素
+const 动作构建器 = $动作.创建动作构建器();
+动作构建器
+  .添加手指(1)
+  .移动到(100, 100, 0) // 移动到目标位置
+  .按下() // 按下
+  .停留(800) // 长按 800ms
+  .移动到(300, 400, 1000) // 拖拽到新位置
+  .抬起() // 抬起
+  .完成()
+  .执行();
+```
+
+### 复杂手势组合
+
+```javascript
+// 先点击，再滑动，最后双击
+const 动作构建器 = $动作.创建动作构建器();
+
+// 第一步：单击
+动作构建器.点击(100, 100, 50);
+
+// 第二步：滑动
+动作构建器
+  .添加手指(1)
+  .移动到(200, 200, 0) // 移动到起始位置
+  .按下() // 按下
+  .移动到(400, 200, 600) // 滑动到结束位置
+  .抬起() // 抬起
+  .完成();
+
+// 第三步：双击
+动作构建器.双击(300, 300, 30);
+
+// 执行所有动作
+动作构建器.执行();
+```