ms-vite-plugin 1.1.2 → 1.1.3

package/docs/api/action.md

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