# FastGestures API 文档

## 概述

FastGestures可以执行cmd,powershell,lua脚本,当使用 Lua 编写扩展时，可以使用以下内置lua函数。

## FG 内置变量

在执行所有脚本之前会进行变量替换。

**使用格式：** `%y变量%` 或 `{变量}`

### 变量列表

| 变量名 | 说明 | 最低版本 |
|--------|------|----------|
| `fg_var_copytext` | 当前剪切板文本 | - |
| `fg_var_current_app_full_path` | 当前鼠标下应用的全路径 | - |
| `fg_var_current_app_dir_path` | 当前鼠标下应用所在目录 | - |
| `fg_var_pid` | 当前鼠标下应用进程 PID | - |
| `fg_var_hwnd` | 当前鼠标下应用窗口句柄 | - |
| `fg_var_dpi` | 当前屏幕缩放值百分比值 | - |
| `fg_var_first_x` | 手势键按下时的坐标 x | - |
| `fg_var_first_y` | 手势键按下时的坐标 y | - |
| `fg_var_selected_text` | 当前选中的文本 | - |
| `fg_var_selected_text_urlencode` | 当前选中的文本（URL 编码形式） | - |
| `fg_var_owner_pid` | 当前窗口最顶层拥有者的进程 PID | - |
| `fg_var_owner_hwnd` | 当前窗口最顶层拥有者的窗口句柄 | - |
| `fg_var_selected_files_path` | 当前选中的文件列表，多个路径使用 `\|` 分隔 | ≥ 2.2.9 |
| `fg_var_selected_files_path2` | 当前选中的文件列表，多个路径使用 `\|` 分隔 | ≥ 2.2.37 |

**使用示例：**
```cmd
:: 在 bat 脚本中使用
echo %yfg_var_copytext%
explorer {fg_var_current_app_dir_path}
```
关闭应用
```cmd
taskkill /f /pid %fg_var_pid%  
```

```lua
-- 在 Lua 脚本中使用变量（执行前会被替换）
local clipText = "{fg_var_copytext}"
local mouseX = {fg_var_first_x}
```

---

## 参数解析函数

### getParamToBoolean(name, default)

取扩展参数，并转为 boolean 类型。

**参数：**
- `name` - 参数名称
- `default` - 默认值

**返回：** boolean

---

### getParamToNumber(name, default)

取扩展参数，并转为 number 类型。

**参数：**
- `name` - 参数名称
- `default` - 默认值

**返回：** number

---

### getParamToString(name, default)

取扩展参数，并转为 string 类型。

**参数：**
- `name` - 参数名称
- `default` - 默认值

**返回：** string

---

## 窗口管理

### fg_active_main_winows()

激活手势主窗口。

**参数：** 无

**返回：** 无

---

### fg_show_msg(string)

显示一个消息提示。

**参数：**
- `string` - 要显示的消息内容

**返回：** 无

**示例：**
```lua
fg_show_msg("一个提示消息");
```

---

### fg_set_windows_top(int hwnd)

设置/切换窗口置顶或取消置顶,

**参数：**
- `hwnd` - 窗口句柄，传 0 时默认为当前鼠标下的窗口

**返回：** 无

---

### fg_get_mouse_windows_hwnd()

取当前鼠标下的窗口句柄。

**参数：** 无

**返回：** int - 窗口句柄

---

### fg_get_mouse_windows_path()

取当前鼠标下的窗口可执行文件路径。

**参数：** 无

**返回：** string - 窗口可执行文件路径

---

### fg_get_mouse_window_info()

取当前鼠标下的窗口信息。

**参数：** 无

**返回：** table - 窗口信息对象

**返回结构：**
```json
{
  "title": "标题",
  "path": "文件绝对路径",
  "fileDir": "文件所在目录绝对路径",
  "class": "类名",
  "hwnd": 0x12345798,// 窗口句柄
}
```

**示例：**
```lua
-- 取窗口信息 title hwnd path class
local info = fg_get_mouse_window_info();
-- 设置到剪切板
fg_set_clipboard_text(info["title"])
```

---

## 键盘和快捷键

### fg_send_shortcut_group(string json, int isUseKeybdEvet, int isCapsLock)

发送一组快捷键，参数为 JSON 格式。

**参数：**
- `json` - JSON 格式的按键序列
- `isUseKeybdEvet` - 是否使用 keybd_event 发送
- `isCapsLock` - 发送单个英文字母时使用大写锁定，防止被输入法捕获

**JSON 格式说明：**
```json
[
  {
    "delay": 10,
    "type": 0,
    "text": "文本测试",
    "buttons": [
      {
        "vk_code": "0xA2",
        "vk_name": "Ctrl",
        "vk_flag": 0
      }
    ]
  }
]
```

**字段说明：**
- `delay` - 延时时间（毫秒）
- `msg_delay` - 每个按键之间的延时(毫秒),最大1000
- `type` - 0:按键，1:文本
- `text` - 当 type 为 1 时此项可用
- `buttons.vk_name` - 键名称(可忽略)
- `buttons.vk_code` - 键虚拟码（十六进制）见 [Windows 虚拟键码文档](https://learn.microsoft.com/zh-cn/windows/win32/inputdev/virtual-key-codes)
- `button.vk_flag` - 0:点击，1:按下，2:弹起，3:切换按下弹起，4:没按下时按下，5:没弹起时弹起

**示例：**
```lua
local keyList = [[
[
  {
    "delay": 10,
    "buttons": [
      {
        "vk_code": "0xA2",
        "vk_name": "Ctrl"
      },
      {
        "vk_code": "0x12",
        "vk_name": "Alt"
      },
      {
        "vk_code": "0x4C",
        "vk_name": "L"
      }
    ]
  },
  {
    "delay": 100,
    "buttons": [
      {
        "vk_code": "0xA2",
        "vk_name": "Ctrl"
      },
      {
        "vk_code": "0x53",
        "vk_name": "S"
      }
    ]
  }
]
]]
fg_send_shortcut_group(keyList);
```

---

### fg_send_text(string text)

发送文本输入。

**参数：**
- `text` - 要发送的文本内容

**返回：** 无

---

### fg_keybd(int virtualKey, int type, int isUseKeybdEvet, int isCapsLock)

发送单个键盘事件。

**参数：**
- `virtualKey` - 虚拟键码（如 Ctrl: 十六进制 0xA2 或十进制 162），见 [Windows 虚拟键码文档](https://learn.microsoft.com/zh-cn/windows/win32/inputdev/virtual-key-codes)
- `type` - 0:点击，1:按下，2:弹起，3:切换按下弹起，4:没按下时按下，5:没弹起时弹起
- `isUseKeybdEvet` - 是否使用 keybd_event 发送
- `isCapsLock` - 发送单个英文字母时使用大写锁定，防止被输入法捕获

**返回：** 无

---

## 剪切板操作

### fg_get_clipboard_text()

获取当前剪切板文本内容。

**参数：** 无

**返回：** string - 剪切板文本内容

---

### fg_set_clipboard_text(string text)

设置剪切板文本。

**参数：**
- `text` - 要设置的文本内容

**返回：** 无

---

## 应用程序和进程

### fg_active_application(string fullPath, int isRunAs)

打开或激活应用或目录。

**参数：**
- `fullPath` - 应用的全路径
- `isRunAs` - 是否使用管理员权限执行

**返回：** 无

---

### fg_run_cmd(string cmdStr, int isShow, int isReturn, string workPath)

执行命令行并取返回值。

**参数：**
- `cmdStr` - 命令字符串
- `isShow` - 是否显示命令行窗口
- `isReturn` - 是否取返回值
- `workPath` - 当前命令行工作的绝对路径

**返回：** string（当 isReturn 为 1 时）

**注意：** 取返回值时确保调用的程序会自动退出。

---

### fg_get_pid_by_name(string processName)

通过进程名字取 PID。

**参数：**
- `processName` - 进程名称（忽略大小写）

**返回：** int - 进程 PID（多个相同名字进程只取首个）

---

## 鼠标操作

### fg_mouse_left_click(int x, int y, int type)

发送鼠标左键事件。

**参数：**
- `x`, `y` - 坐标，全为 0 点时点击当前位置
- `type` - 0:点击，1:按下，2:弹起，3:切换按下弹起，4:没按下时按下，5:没弹起时弹起

**返回：** 无

---

### fg_mouse_middle_click(int x, int y, int type)

发送鼠标中键事件。

**参数：**
- `x`, `y` - 坐标，全为 0 点时点击当前位置
- `type` - 0:点击，1:按下，2:弹起，3:切换按下弹起，4:没按下时按下，5:没弹起时弹起

**返回：** 无

---

### fg_mouse_right_click(int x, int y, int type)

发送鼠标右键事件。

**参数：**
- `x`, `y` - 坐标，全为 0 点时点击当前位置
- `type` - 0:点击，1:按下，2:弹起，3:切换按下弹起，4:没按下时按下，5:没弹起时弹起

**返回：** 无

---

### fg_mouse_x1_click(int x, int y, int type)

发送鼠标 X1 键事件（侧键 1）。

**参数：**
- `x`, `y` - 坐标，全为 0 点时点击当前位置
- `type` - 0:点击，1:按下，2:弹起，3:切换按下弹起，4:没按下时按下，5:没弹起时弹起

**返回：** 无

---

### fg_mouse_x2_click(int x, int y, int type)

发送鼠标 X2 键事件（侧键 2）。

**参数：**
- `x`, `y` - 坐标，全为 0 点时点击当前位置
- `type` - 0:点击，1:按下，2:弹起，3:切换按下弹起，4:没按下时按下，5:没弹起时弹起

**返回：** 无

---

### fg_mouse_move(int x, int y, int isAbsolute)

移动鼠标位置。

**参数：**
- `x`, `y` - 坐标
- `isAbsolute` - 0:相对坐标（从当前位置移动指定的坐标距离），1:绝对坐标

**返回：** 无

---

### fg_mouse_wheel(int direction, int num, int times, int delay)

发送鼠标滚轮事件。

**参数：**
- `direction` - 0:向下滚动，1:向上滚动，2:向右滚动，3:向左滚动
- `num` - 每次滚动距离
- `times` - 滚动次数
- `delay` - 多次滚动时延时，默认 10 毫秒

**返回：** 无

---

## 系统控制

### fg_sleep(int time)

挂起/延时时间。

**参数：**
- `time` - 延时时间（毫秒）

**返回：** 无

---

### fg_volume_inc()

音量加。

**参数：** 无

**返回：** 无

---

### fg_volume_dec()

音量减。

**参数：** 无

**返回：** 无

---

### fg_volume_switch()

静音/关闭静音切换。

**参数：** 无

**返回：** 无

---

### fg_brightness_inc()

屏幕亮度加（部分屏幕不支持）。

**参数：** 无

**返回：** 无

---

### fg_brightness_dec()

屏幕亮度减（部分屏幕不支持）。

**参数：** 无

**返回：** 无

---

## 文件和目录操作

### fg_get_selected_files_path(int type)

获取选中的文件或目录路径。

**参数：**
- `type` - 0:返回选中所有的（文件/目录）路径，1:返回选中文件路径，2:返回选中目录路径

**返回：** table - 路径数组

**示例：**
```lua
-- 取选中的第一个文件路径
local fileList = fg_get_selected_files_path(1);
fg_show_msg(fileList[0]);
```

---

### fg_get_selected_text()

获取当前选中的文本。

**参数：** 无

**返回：** string - 选中的文本内容

---

### fg_open_dir(string path)

打开目录。如果入参为文件路径则打开文件所在目录且选中此文件。

**参数：**
- `path` - 目录或文件路径

**返回：** 无

---

### fg_path_file_exists(string path)

判断文件或目录是否存在。

**参数：**
- `path` - 文件或目录路径

**返回：** bool - 是否存在

---

### fg_mkdirs(string path)

自动创建多级目录。

**参数：**
- `path` - 目录路径

**返回：** bool - 是否创建成功

---

## 云备份

### fg_cloud_download()

下载云备份。

**参数：** 无

**返回：** 无

---

### fg_cloud_upload()

上传云备份。

**参数：** 无

**返回：** 无

---

## 浏览器集成

### fg_execute_javascript(string code)

在浏览器中执行 JavaScript 脚本代码。

**参数：**
- `code` - JavaScript 代码字符串

**返回：** string - 执行结果

**示例 1 - 取当前标签页标题：**
```lua
title = fg_execute_javascript("document.title")
fg_show_msg(title)
```

**示例 2 - 复制当前浏览器标签页地址：**
```lua
url = fg_execute_javascript("location.href")
fg_set_clipboard_text(url)
fg_show_msg("复制成功")
```

---

## 使用说明

1. 所有函数都以 `fg_` 前缀开头
2. 参数类型严格匹配（int, string, bool）
3. 虚拟键码可使用十六进制（0xA2）或十进制（162）格式
4. 坐标系统默认为屏幕绝对坐标
5. 延时单位统一为毫秒（ms）
6. 能用cmd脚本实现的,就不用要lua

更多信息请参考 Windows API 文档和项目源码。


上面是FastGestures的AI技能文档接口，理解文档后按对话要求实现脚本功能, 下面开始等待用户的需求,不要有多余的输出.