# 事件剧本 事件剧本可以依次执行文字、键盘、鼠标、等待和循环操作，支持 `text`、`stroke`、`event`、`wait`、`repeat`、`move` 和 `wheel`。 ## 文件与运行 将剧本保存为 UTF-8 文件（推荐 `.fsevent` ），放入软件“打开剧本目录”按钮打开的文件夹。便携版的该目录位于程序旁；安装版的位置见[安装与更新](../getting-started/installation.md#配置与剧本保存位置)。 页面只列出该目录第一层的 `.fsevent` 和 `.txt` 文件。选择文件时会自动检查；可以点击“编辑”用文本编辑器修改，保存后点击“刷新”。单个文件最多 1 MiB，允许 UTF-8 BOM。 保持软件停留在事件剧本页，切换到目标窗口后按启动热键（默认 `F8` ）。再次按下可停止。启动前软件会重新读取并检查文件；若有错误，会在状态栏提示，不会执行部分内容。运行期间也会检查按键配对和屏幕布局变化。 三项功能的热键仅在各自页面生效；设置和关于页不响应启动热键。运行中切页会先停止当前任务。 ## 参数单位 剧本的参数值不写单位。单位由所用参数决定： | 参数 | 固定单位 | 示例 | |------------------------------|-------------------|---------------------------------------------------| | 按压时间、字符间隔、等待时间 | 整数毫秒（ms） | `250` 表示 250 毫秒；仅按压时间和字符间隔允许 `0` | | 鼠标坐标 | 虚拟桌面物理像素 | `-1920, 100` | | 滚轮 | 整数步数 | `-1` 表示向下一步 | | 循环次数 | 正整数次，或 `-1` | `3` 表示执行三次，`-1` 表示无限循环 | 不写 `ms`、`s`、`px` 等后缀，不按数值大小自动判断单位。时间只接受整数毫秒，上限 86400000；按压时间与字符间隔允许 `0`，`wait(0)` 无效，`wait` 至少为 `1`。`0.5` 等小数无效。坐标、滚轮与次数也必须为整数。 ## 命令速查 以下是当前支持的全部命令；名称区分大小写。除 `repeat` 块外，每条命令均以 `;` 结束。 | 命令 | 作用与参数 | |------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| | `text("内容", press, interval);` | 逐字符输入 Unicode 文本；每个字符按压 `press` 毫秒，相邻字符间等待 `interval` 毫秒。两项均可为 `0`。 | | `stroke(target[, target...], press);` | 按顺序按下一个或多个 `Key.*`/`Mouse.*` 目标，保持 `press` 毫秒后逆序抬起；最多 32 个目标，同一目标不可重复。 | | `event(target, Down \| Up);` | 对单个 `Key.*`/`Mouse.*` 目标执行一次按下或抬起；不包含按压时长，必须配对，不得重复按下。 | | `wait(ms);` | 暂停指定的整数毫秒；必须为 `1`～`86400000`，不接受 `0`。 | | `repeat(count) { ... }` | 重复执行块内命令；`count` 为 `1`～`1000000000`，`-1` 表示无限循环。最多嵌套 16 层；无限循环必须包含时间推进。块后不加分号。 | | `move(x, y);` | 将鼠标移至虚拟桌面的绝对物理像素坐标；支持负坐标，必须位于任一实际显示器。 | | `wheel(steps);` | 在当前鼠标位置滚动；正数向上、负数向下，单次为 `-100`～`-1` 或 `1`～`100` 步。 | ## 命令详解 下列示例可直接写入 `.fsevent` 文件。时间参数均为整数毫秒，坐标为整个虚拟桌面的物理像素。 ### `text`：输入文字 格式：`text("内容", 按压时间, 字符间隔);`。逐字使用 Unicode 输入，不依赖当前输入法。字符间隔只发生在同一条 `text` 的相邻字符之间，首尾不额外等待。 ```text text("你好，Flori Input", 5, 20); ``` 两个时间参数均可为 `0`。要输入双引号，在文本中写成 `""`；反斜杠不表示转义，因此 `\n` 不会变成换行。换行请使用 `stroke(Key.Enter, 5);`。 ### `stroke`：完整按压动作 格式：`stroke(目标[, 目标...], 按压时间);`。按给定顺序按下键盘键或鼠标键，保持指定时间，再逆序抬起。单个目标相当于一次按键或点击；多个目标可组成组合键。 ```text stroke(Key.Ctrl, Key.A, 30); stroke(Mouse.Left, 5); ``` 目标必须写成 `Key.名称` 或 `Mouse.名称`，同一条命令不能重复目标，最多 32 个。按压时间可为 `0` ，表示立即提交按下和抬起。组合键不做“是否有意义”的白名单判断。 ### `event`：单次按下或抬起 格式：`event(目标, Down);` 或 `event(目标, Up);`。它只执行一步，不会自动等待或自动抬起，适合需要在按住期间穿插其他操作的场景。 ```text move(300, 300); event(Mouse.Left, Down); wait(100); move(600, 400); event(Mouse.Left, Up); ``` 每个 `Down` 都必须有对应的 `Up`；重复按下、无对应按下的抬起，或结束时仍有按住的目标，都会报错。停止或出错时软件会尝试释放已按下的输入。 ### `wait`：暂停 格式：`wait(毫秒);`。在两项操作之间加入明确的等待，取值为 `1`～`86400000`，不能写 `0` 或小数。 ```text stroke(Key.Enter, 5); wait(250); text("下一步", 5, 10); ``` ### `repeat`：重复一段操作 格式：`repeat(次数) { ... }`。次数为 `1`～`1000000000`；`-1` 表示持续循环，直到再次按启动热键停止。最多嵌套 16 层，右花括号后不加分号。 ```text repeat(3) { stroke(Mouse.Left, 5); wait(500); } ``` 无限循环必须包含实际耗时的操作，推荐明确写入 `wait`，避免无等待动作过多而被保护机制停止。循环次数不能为 `0`，除 `-1` 外也不能为负数。 ### `move`：移动鼠标 格式：`move(x, y);`。坐标以整个虚拟桌面为基准；左侧或上方的副屏可能出现负坐标。点击事件剧本页的“捕获坐标”，将鼠标移到目标位置后左键确认，坐标会以 `x, y` 形式复制到剪贴板，可粘贴到 `move(...)` 中；右键或 `Esc` 取消。 ```text move(400, 300); stroke(Mouse.Left, 5); ``` 请将示例坐标换成自己选取的位置。目标必须落在某块实际显示器内；若处于屏幕间空白区域，或运行时显示器布局已变化，剧本会报错，不会自动吸附到其他屏幕。 ### `wheel`：滚动鼠标滚轮 格式：`wheel(步数);`。正数向上，负数向下；单次允许 `-100`～`-1` 或 `1`～`100`，不能写 `0`。 ```text wheel(2); wait(100); wheel(-1); ``` ## 语法与安全提示 字符串之外可以使用空格、缩进、换行和 `//` 行注释。命令与目标名称区分大小写，不支持别名。`text` 不允许跨行或包含控制字符；换行、Tab 等请使用对应的 `Key.*` 按键。 键盘目标名称支持 `A`～`Z`、`0`～`9`、`F1`～`F24`，以及 `Ctrl`、`Shift`、`Alt`、`Win`、`Enter`、`Tab`、`Esc`、`Space`、`Backspace`、 `Delete`、`Insert`、`Home`、`End`、`PageUp`、`PageDown`、`ArrowLeft`、`ArrowRight`、`ArrowUp`、`ArrowDown`。鼠标目标名称仅支持 `Left`、`Middle`、`Right`。 为防止意外长时间运行，有限剧本默认最多执行 10 万步，连续没有正时间等待的动作默认最多 1000 步；超限时会停止并尝试释放输入。需要无限循环时，请在循环体中加入合理的 `wait`，并确认启动热键可随时停止。