ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/global.md

@@ -0,0 +1,654 @@
+# 全局定义 (Global)
+
+全局定义模块提供了应用运行时的全局常量和函数，包括应用信息、调试状态、线程控制等核心功能。
+
+**全局模块无调用前缀，直接使用即可。不要 `require`。**
+
+`StartThread` 是同一 Lua VM 里的协作协程，不是操作系统线程；协程只在 `Sleep` 时被调度。
+
+主脚本收到停止信号后，引擎会通过 instruction hook 和可中断的 `Sleep` 直接中断，不必在主循环里轮询 `ShouldInterruptThread`。
+
+
+## 功能概览
+
+- **应用信息**: 获取应用版本、名称、包信息、运行模式、平台
+- **运行状态**: 检查调试模式
+- **线程控制**: 可中断等待、协作协程、退出脚本
+- **脚本生命周期**: 停止回调、异常回调、重启脚本
+- **时间工具**: 获取时间戳
+- **应用控制**: 切换应用到前台
+- **Agent 设置**: 读取和设置 Agent 触控模式
+
+## 全局常量
+
+### 运行模式
+
+#### **RunMode**
+
+用户设置选择的运行模式，`"agent"` 或 `"hid"`。
+
+```lua
+---@type string
+RunMode = nil
+```
+
+**示例:**
+
+```lua
+print("运行模式: " .. tostring(RunMode))
+```
+
+### 调试和状态
+
+#### **IsDebug**
+
+当前是否为调试模式。
+
+```lua
+---@type boolean
+IsDebug = nil
+```
+
+**示例:**
+
+```lua
+print("调试模式: " .. tostring(IsDebug))
+```
+
+### 应用信息
+
+#### **Platform**
+
+平台信息，标识当前应用运行的平台，例如 `"ios"`、`"android"`。
+
+```lua
+---@type string
+Platform = nil
+```
+
+**示例:**
+
+```lua
+print("平台: " .. tostring(Platform))
+```
+
+#### **AppVersion**
+
+应用版本号，注意这是快点 JS 应用的版本号，不是脚本的版本号。
+
+```lua
+---@type string
+AppVersion = nil
+```
+
+**示例:**
+
+```lua
+print("应用版本: " .. tostring(AppVersion))
+```
+
+#### **AppBuildNumber**
+
+应用构建号，注意这是快点 JS 应用的构建号，不是脚本的构建号。
+
+```lua
+---@type number
+AppBuildNumber = nil
+```
+
+**示例:**
+
+```lua
+print("构建号: " .. tostring(AppBuildNumber))
+```
+
+#### **AppName**
+
+应用名称，注意这是快点 JS 应用的名称，不是脚本的名称。
+
+```lua
+---@type string
+AppName = nil
+```
+
+**示例:**
+
+```lua
+print("应用名称: " .. tostring(AppName))
+```
+
+#### **AppBundleId**
+
+应用的 Bundle ID，注意这是快点 JS 应用的 Bundle ID，不是脚本的 Bundle ID。
+
+```lua
+---@type string
+AppBundleId = nil
+```
+
+**示例:**
+
+```lua
+print("Bundle ID = " .. tostring(AppBundleId))
+```
+
+### 包（脚本）信息
+
+#### **PackageJson**
+
+应用包（脚本）的配置信息，package.json 的内容
+
+```lua
+---@class PackageJson
+---@field name string
+---@field appVersion string
+---@field appId string
+---@field [key string]: any
+PackageJson = {}
+```
+
+**属性:**
+
+- `name` - 脚本项目名称
+- `appVersion` - 脚本版本号
+- `appId` - 脚本 Id
+- `[key: string]: any` - 其他自定义属性
+
+**示例:**
+
+```lua
+print("脚本项目名称: " .. tostring(PackageJson.name))
+print("脚本版本号: " .. tostring(PackageJson.appVersion))
+-- 访问自定义属性
+if PackageJson.author then
+  print("作者: " .. tostring(PackageJson.author))
+end
+```
+
+## 全局函数
+
+### Sleep
+
+使当前线程睡眠指定的毫秒数。
+
+```lua
+---@param ms number
+function Sleep(ms) end
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述             |
+| ------ | ------ | -------- | ------ | ---------------- |
+| `ms`   | number | 是       | -      | 睡眠时间（毫秒） |
+
+**示例:**
+
+```lua
+print("开始等待...")
+Sleep(2000) -- 等待2秒
+print("等待结束")
+```
+
+### Exit
+
+退出当前脚本。Lua 只有一个 VM，效果与收到停止信号相同。
+
+```lua
+function Exit() end
+```
+
+**示例:**
+
+```lua
+print("脚本即将退出")
+Exit()
+```
+
+### Time
+
+获取当前时间戳。
+
+```lua
+---@return number
+function Time() end
+```
+
+**返回值:**
+
+| 类型     | 描述               |
+| -------- | ------------------ |
+| `number` | 当前时间戳（毫秒） |
+
+**示例:**
+
+```lua
+local startTime = Time()
+-- 执行一些操作
+Sleep(1000)
+local endTime = Time()
+print("操作耗时: " .. tostring(endTime - startTime) .. "ms")
+```
+
+### TakeMeToFront
+
+将快点 JS 应用切换到前台。
+
+快点 Agent 模式下调用-> `utils.TakeMeToFront()`
+
+HID 模式下调用-> `hid.TakeMeToFront()`
+
+```lua
+---@return boolean
+function TakeMeToFront() end
+```
+
+**示例:**
+
+```lua
+-- 当需要用户注意时，将应用切换到前台
+TakeMeToFront()
+print("应用已切换到前台")
+```
+
+### SetAgentFastMode
+
+设置 Agent 快速模式（兼容旧接口）。开启对应模式 `1`，关闭对应模式 `0`。推荐改用 `SetAgentTouchMode`。设置会持久化。
+
+```lua
+---@param enabled boolean
+---@return boolean
+function SetAgentFastMode(enabled) end
+```
+
+**参数:**
+
+| 参数名    | 类型      | 是否必填 | 默认值 | 描述             |
+| --------- | --------- | -------- | ------ | ---------------- |
+| `enabled` | `boolean` | 是       | -      | 是否开启快速模式 |
+
+**返回值:**
+
+| 类型      | 描述                 |
+| --------- | -------------------- |
+| `boolean` | 实际是否开启快速模式 |
+
+**示例:**
+
+```lua
+local enabled = SetAgentFastMode(true)
+print("Agent 快速模式: " .. tostring(enabled))
+```
+
+### GetAgentFastMode
+
+获取 Agent 快速模式当前状态（兼容旧接口）。
+
+```lua
+---@return boolean
+function GetAgentFastMode() end
+```
+
+**返回值:**
+
+| 类型      | 描述                 |
+| --------- | -------------------- |
+| `boolean` | 当前是否开启快速模式 |
+
+**示例:**
+
+```lua
+if GetAgentFastMode() then
+  print("Agent 快速模式已开启")
+end
+```
+
+### SetAgentTouchMode
+
+设置 Agent 触控模式。默认 `1`，设置会持久化。
+
+- `0` 标准：等待完整执行完成
+- `1` 快速：更快的执行速度
+- `2` 真实点击：更接近真实手指触控
+
+```lua
+---@param mode number
+---@return number
+function SetAgentTouchMode(mode) end
+```
+
+**参数:**
+
+| 参数名 | 类型     | 是否必填 | 默认值 | 描述                         |
+| ------ | -------- | -------- | ------ | ---------------------------- |
+| `mode` | `number` | 是       | -      | 0 标准 / 1 快速 / 2 真实点击 |
+
+**返回值:**
+
+| 类型     | 描述           |
+| -------- | -------------- |
+| `number` | 实际生效的模式 |
+
+**示例:**
+
+```lua
+local mode = SetAgentTouchMode(1)
+print("Agent 触控模式: " .. tostring(mode))
+```
+
+### GetAgentTouchMode
+
+获取 Agent 触控模式。默认 `1`，设置会持久化。
+
+```lua
+---@return number
+function GetAgentTouchMode() end
+```
+
+**返回值:**
+
+| 类型     | 描述              |
+| -------- | ----------------- |
+| `number` | 当前模式（0/1/2） |
+
+**示例:**
+
+```lua
+local mode = GetAgentTouchMode()
+print("当前触控模式: " .. tostring(mode))
+```
+
+### SetCpuAutoThrottle
+
+设置脚本 CPU 自动限流。默认开启。开启后，脚本 API 在 CPU 占用接近系统杀进程阈值时会轻微让步，降低被系统终止的风险。
+
+```lua
+---@param enabled boolean
+---@return boolean
+function SetCpuAutoThrottle(enabled) end
+```
+
+**参数:**
+
+| 参数名    | 类型      | 是否必填 | 默认值 | 描述             |
+| --------- | --------- | -------- | ------ | ---------------- |
+| `enabled` | `boolean` | 是       | -      | 是否开启自动限流 |
+
+**返回值:**
+
+| 类型      | 描述                 |
+| --------- | -------------------- |
+| `boolean` | 实际是否开启自动限流 |
+
+**示例:**
+
+```lua
+local enabled = SetCpuAutoThrottle(true)
+print("CPU 自动限流: " .. tostring(enabled))
+```
+
+### GetCpuAutoThrottle
+
+获取脚本 CPU 自动限流当前状态。默认开启。
+
+```lua
+---@return boolean
+function GetCpuAutoThrottle() end
+```
+
+**返回值:**
+
+| 类型      | 描述                 |
+| --------- | -------------------- |
+| `boolean` | 当前是否开启自动限流 |
+
+**示例:**
+
+```lua
+if GetCpuAutoThrottle() then
+  print("CPU 自动限流已开启")
+end
+```
+
+### SetCpuThrottleDelay
+
+设置 CPU 限流单次 Sleep 延迟范围（毫秒）。默认 `minMs=3`、`maxMs=30`。仅在 CPU 自动限流开启且触发限流时生效。
+
+```lua
+---@param minMs number
+---@param maxMs number
+---@return any
+function SetCpuThrottleDelay(minMs, maxMs) end
+```
+
+**参数:**
+
+| 参数名  | 类型     | 是否必填 | 默认值 | 描述                                    |
+| ------- | -------- | -------- | ------ | --------------------------------------- |
+| `minMs` | `number` | 是       | -      | 最低延迟（毫秒）                        |
+| `maxMs` | `number` | 是       | -      | 最高延迟（毫秒）；小于 minMs 时自动对齐 |
+
+**返回值:**
+
+| 类型                               | 描述               |
+| ---------------------------------- | ------------------ |
+| `{ minMs: number; maxMs: number }` | 实际生效的延迟范围 |
+
+**示例:**
+
+```lua
+local delay = SetCpuThrottleDelay(3, 30)
+print("CPU 限流延迟: " .. tostring(delay.minMs) .. "~" .. tostring(delay.maxMs) .. "ms")
+```
+
+### GetCpuThrottleDelay
+
+获取 CPU 限流延迟范围（毫秒）。
+
+```lua
+---@return any
+function GetCpuThrottleDelay() end
+```
+
+**返回值:**
+
+| 类型                               | 描述               |
+| ---------------------------------- | ------------------ |
+| `{ minMs: number; maxMs: number }` | 当前最低与最高延迟 |
+
+**示例:**
+
+```lua
+local delay = GetCpuThrottleDelay()
+print("CPU 限流延迟: " .. tostring(delay.minMs) .. "~" .. tostring(delay.maxMs) .. "ms")
+```
+
+### RestartScript
+
+重启脚本。
+
+```lua
+---@param delay number
+function RestartScript(delay) end
+```
+
+**参数:**
+
+| 参数名  | 类型   | 是否必填 | 默认值 | 描述                                     |
+| ------- | ------ | -------- | ------ | ---------------------------------------- |
+| `delay` | number | 是       | -      | 延迟时间（毫秒），建议不要低于 2000 毫秒 |
+
+**示例:**
+
+```lua
+-- 重启脚本，延迟2秒
+RestartScript(2000)
+```
+
+### SetStopCallback
+
+设置停止回调。只能在主脚本注册，不能在 `StartThread` 协程里注册。传入非函数则清除。
+
+```lua
+---@param callback fun(status: string)|nil
+function SetStopCallback(callback) end
+```
+
+**参数:**
+
+| 参数名     | 类型                       | 是否必填 | 默认值 | 描述                                       |
+| ---------- | -------------------------- | -------- | ------ | ------------------------------------------ |
+| `callback` | `fun(status: string)`\|nil | 否       | nil    | 停止回调；`status` 为 success/error/stopped |
+
+**示例:**
+
+```lua
+SetStopCallback(function(status)
+  if status == "success" then
+    print("脚本执行完成")
+  elseif status == "error" then
+    print("脚本执行异常")
+  else
+    print("脚本手动停止")
+  end
+end)
+```
+
+### SetExceptionCallback
+
+设置异常停止回调。只能在主脚本注册。传入非函数则清除。异常时会先于 `SetStopCallback` 调用。
+
+```lua
+---@param callback fun()|nil
+function SetExceptionCallback(callback) end
+```
+
+**参数:**
+
+| 参数名     | 类型       | 是否必填 | 默认值 | 描述     |
+| ---------- | ---------- | -------- | ------ | -------- |
+| `callback` | `fun()`\|nil | 否       | nil    | 异常回调 |
+
+**示例:**
+
+```lua
+SetExceptionCallback(function()
+  print("脚本执行异常")
+end)
+```
+
+### StartThread
+
+启动协作协程，返回协程名。传入的函数在同一 Lua VM 中运行，不是操作系统线程；协程只在 `Sleep` 时被调度。
+
+```lua
+---@param func function
+---@return string
+function StartThread(func) end
+```
+
+**参数:**
+
+| 参数名 | 类型     | 是否必填 | 默认值 | 描述         |
+| ------ | -------- | -------- | ------ | ------------ |
+| `func` | function | 是       | -      | 协程入口函数 |
+
+**返回值:**
+
+| 类型     | 描述     |
+| -------- | -------- |
+| `string` | 协程名称 |
+
+**示例:**
+
+```lua
+local name = StartThread(function()
+  while true do
+    print("tick")
+    Sleep(100)
+  end
+end)
+```
+
+`StopThread` 或整脚本停止后，协程会在下一次 `Sleep` / hook 处被中断，不必在协程里轮询。
+
+### StopThread
+
+请求停止指定协作协程。
+
+```lua
+---@param threadName string
+function StopThread(threadName) end
+```
+
+**参数:**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述     |
+| ------------ | ------ | -------- | ------ | -------- |
+| `threadName` | string | 是       | -      | 协程名称 |
+
+**示例:**
+
+```lua
+StopThread(name)
+```
+
+### ShouldInterruptThread
+
+当前协作协程是否应退出。
+
+主脚本**不必**调用本函数：停止按钮、`Exit()`、引擎 stop 都会让 hook 和 `Sleep` 直接中断主程序。
+
+仅当 `StartThread` 协程被 `StopThread` 之后还要自己做收尾（而不是靠抛错退出）时，才需要轮询。
+
+```lua
+---@return boolean
+function ShouldInterruptThread() end
+```
+
+**返回值:**
+
+| 类型      | 描述     |
+| --------- | -------- |
+| `boolean` | 是否应退出 |
+
+**示例:**
+
+```lua
+StartThread(function()
+  while not ShouldInterruptThread() do
+    -- 业务
+    Sleep(100)
+  end
+  print("协程自行收尾")
+end)
+```
+
+### ToJsonString
+
+将表转换为 JSON 字符串。参数必须是表。
+
+```lua
+---@param data table
+---@return string
+function ToJsonString(data) end
+```
+
+**参数:**
+
+| 参数名 | 类型  | 是否必填 | 默认值 | 描述 |
+| ------ | ----- | -------- | ------ | ---- |
+| `data` | table | 是       | -      | 表   |
+
+**返回值:**
+
+| 类型     | 描述        |
+| -------- | ----------- |
+| `string` | JSON 字符串 |
+
+**示例:**
+
+```lua
+print(ToJsonString({ a = 1, b = 2 }))
+```
+