ms-vite-plugin 1.5.17 → 1.5.20

package/docs/api/system.md

@@ -37,7 +37,7 @@ function startApp(bundleId: string): boolean;
 
 | 参数名     | 类型   | 是否必填 | 默认值 | 描述             |
 | ---------- | ------ | -------- | ------ | ---------------- |
-| `bundleId` | string | 是       |        | 应用的 Bundle ID |
+| `bundleId` | string | 是       |        | Bundle ID，或已安装应用的显示名 `appName`。同名多个应用时失败 |
 
 **返回值:**
 
@@ -65,7 +65,7 @@ function stopApp(bundleId: string): boolean;
 
 | 参数名     | 类型   | 是否必填 | 默认值 | 描述             |
 | ---------- | ------ | -------- | ------ | ---------------- |
-| `bundleId` | string | 是       |        | 应用的 Bundle ID |
+| `bundleId` | string | 是       |        | Bundle ID，或已安装应用的显示名 `appName`。同名多个应用时失败 |
 
 **返回值:**
 
@@ -94,7 +94,7 @@ function activateApp(bundleId: string): boolean;
 
 | 参数名     | 类型   | 是否必填 | 默认值 | 描述             |
 | ---------- | ------ | -------- | ------ | ---------------- |
-| `bundleId` | string | 是       |        | 应用的 Bundle ID |
+| `bundleId` | string | 是       |        | Bundle ID，或已安装应用的显示名 `appName`。同名多个应用时失败 |
 
 **返回值:**
 

package/docs/apicn/global.md

@@ -312,7 +312,7 @@ $打印信息日志("应用已切换到前台");
 
 - `0` 标准：等待完整执行完成
 - `1` 快速：更快的执行速度
-- `2` 真实点击：更接近真实手指触控
+- `2` 真实点击：带触摸面积
 
 ```typescript
 declare function $设置Agent触控模式(模式: 数字): 数字;

package/docs/apicn/image.md

@@ -12,12 +12,18 @@
 
 所有传递`图片ID`的函数都可以使用`"actionScreenshot"`作为参数，来表示指定 HID 快捷键系统截图
 
+所有传递`图片ID`的函数都可以使用`"vpnScreenshot"`作为参数，来表示指定VPN免自动化截图
+
 所有传递`图片ID`的函数都可以使用图片路径作为参数，来表示对指定图片进行操作，支持 res 目录文件，和手机文件路径。
 
+`截取屏幕` 默认按 `"screen"` 截图。免越狱调用 `设置默认截图` 后，改为按设置的图片 ID 截图。越狱版该设置不生效。
+
 ## 图片获取与管理
 
 ### 截取屏幕
 
+按 `设置默认截图` 设置的图片 ID 截取。未设置时为 `"screen"`。越狱版固定为 `"screen"`。
+
 ```typescript
 function 截取屏幕(
   区域左上角X坐标?: 数字,
@@ -38,8 +44,8 @@ function 截取屏幕(
 
 **返回值：**
 
-| 类型     | 描述                             |
-| -------- | -------------------------------- |
+| 类型     | 描述                                  |
+| -------- | ------------------------------------- |
 | `字符串` | 截图的图片 ID，失败时返回 `undefined` |
 
 **示例：**
@@ -70,6 +76,36 @@ if (图片ID) {
 }
 ```
 
+### 设置默认截图 - 设置截取屏幕使用的图片 ID。
+
+设置之后，`截取屏幕` 按这个图片 ID 截图。可传入与其它图片函数相同的图片 ID：`"screen"`、`"shortcut"`、`"actionScreenshot"`、`"vpnScreenshot"`、res 目录或手机绝对路径、已有图片 ID。未传入或空字符串不修改当前来源。越狱版调用后不改变来源。
+
+```typescript
+function 设置默认截图(图片ID: 字符串): 无返回值;
+```
+
+**参数：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                                              |
+| -------- | ------ | -------- | ------ | ------------------------------------------------- |
+| `图片ID` | 字符串 | 是       | -      | `截取屏幕` 使用的来源 |
+
+**示例：**
+
+```javascript
+// 之后的截取屏幕使用快捷指令截图
+$图片.设置默认截图("shortcut");
+const 图片ID = $图片.截取屏幕();
+const 文档目录 = $文件.获取内部目录("documents");
+if (图片ID) {
+  $图片.保存图片(图片ID, `${文档目录}/screenshot.jpg`);
+  $图片.释放图片(图片ID);
+}
+
+// 恢复为当前屏幕
+$图片.设置默认截图("screen");
+```
+
 ### 读取图片 - 从文件路径或图片ID读取图片。
 
 ```typescript
@@ -84,8 +120,8 @@ function 读取图片(图片路径: 字符串): 字符串 | undefined;
 
 **返回值：**
 
-| 类型     | 描述                       |
-| -------- | -------------------------- |
+| 类型     | 描述                            |
+| -------- | ------------------------------- |
 | `字符串` | 图片 ID，失败时返回 `undefined` |
 
 **示例：**
@@ -186,7 +222,9 @@ if (图片ID) {
 ### 获取图片大小 - 获取图片尺寸。
 
 ```typescript
-function 获取图片大小(图片ID: 字符串): { width: 数字; height: 数字 } | undefined;
+function 获取图片大小(
+  图片ID: 字符串,
+): { width: 数字; height: 数字 } | undefined;
 ```
 
 **参数：**
@@ -197,8 +235,8 @@ function 获取图片大小(图片ID: 字符串): { width: 数字; height: 数
 
 **返回值：**
 
-| 类型                                    | 描述                                                           |
-| --------------------------------------- | -------------------------------------------------------------- |
+| 类型                                         | 描述                                                                |
+| -------------------------------------------- | ------------------------------------------------------------------- |
 | `{ width: 数字; height: 数字 } \| undefined` | 图片尺寸对象，包含 `width` 和 `height` 属性，失败时返回 `undefined` |
 
 **示例：**
@@ -950,8 +988,8 @@ function 旋转图片(图片ID: 字符串, 角度: 数字): 字符串 | undefine
 
 **返回值：**
 
-| 类型             | 描述                                |
-| ---------------- | ----------------------------------- |
+| 类型                  | 描述                                     |
+| --------------------- | ---------------------------------------- |
 | `字符串 \| undefined` | 旋转后的新图片 ID 失败时返回 `undefined` |
 
 **示例：**
@@ -1091,8 +1129,8 @@ function 扫描条码(图片ID: 字符串): 字符串 | undefined;
 
 **返回值：**
 
-| 类型             | 描述                        |
-| ---------------- | --------------------------- |
+| 类型                  | 描述                             |
+| --------------------- | -------------------------------- |
 | `字符串 \| undefined` | 扫码结果，失败时返回 `undefined` |
 
 **示例：**

package/docs/apicn/system.md

@@ -37,7 +37,7 @@ function 启动应用(bundleId: 字符串): 布尔值;
 
 | 参数名     | 类型   | 是否必填 | 默认值 | 描述             |
 | ---------- | ------ | -------- | ------ | ---------------- |
-| `bundleId` | 字符串 | 是       |        | 应用的 Bundle ID |
+| `bundleId` | 字符串 | 是       |        | Bundle ID，或已安装应用的显示名 `appName`。同名多个应用时失败 |
 
 **返回值:**
 
@@ -65,7 +65,7 @@ function 停止应用(bundleId: 字符串): 布尔值;
 
 | 参数名     | 类型   | 是否必填 | 默认值 | 描述             |
 | ---------- | ------ | -------- | ------ | ---------------- |
-| `bundleId` | 字符串 | 是       |        | 应用的 Bundle ID |
+| `bundleId` | 字符串 | 是       |        | Bundle ID，或已安装应用的显示名 `appName`。同名多个应用时失败 |
 
 **返回值:**
 
@@ -94,7 +94,7 @@ function 把应用切入前台(bundleId: 字符串): 布尔值;
 
 | 参数名     | 类型   | 是否必填 | 默认值 | 描述             |
 | ---------- | ------ | -------- | ------ | ---------------- |
-| `bundleId` | 字符串 | 是       |        | 应用的 Bundle ID |
+| `bundleId` | 字符串 | 是       |        | Bundle ID，或已安装应用的显示名 `appName`。同名多个应用时失败 |
 
 **返回值:**
 

package/docs/apilua/global.md

@@ -4,7 +4,6 @@
 
 **全局模块无调用前缀，直接使用即可。不要 `require`。**
 
-
 ## 功能概览
 
 - **应用信息**: 获取应用版本、名称、包信息、运行模式、平台
@@ -254,7 +253,7 @@ print("应用已切换到前台")
 
 - `0` 标准：等待完整执行完成
 - `1` 快速：更快的执行速度
-- `2` 真实点击：更接近真实手指触控
+- `2` 真实点击：带触摸面积
 
 ```lua
 ---@param mode number
@@ -441,8 +440,8 @@ function SetStopCallback(callback) end
 
 **参数:**
 
-| 参数名     | 类型                       | 是否必填 | 默认值 | 描述                                       |
-| ---------- | -------------------------- | -------- | ------ | ------------------------------------------ |
+| 参数名     | 类型                       | 是否必填 | 默认值 | 描述                                        |
+| ---------- | -------------------------- | -------- | ------ | ------------------------------------------- |
 | `callback` | `fun(status: string)`\|nil | 否       | nil    | 停止回调；`status` 为 success/error/stopped |
 
 **示例:**
@@ -470,8 +469,8 @@ function SetExceptionCallback(callback) end
 
 **参数:**
 
-| 参数名     | 类型       | 是否必填 | 默认值 | 描述     |
-| ---------- | ---------- | -------- | ------ | -------- |
+| 参数名     | 类型         | 是否必填 | 默认值 | 描述     |
+| ---------- | ------------ | -------- | ------ | -------- |
 | `callback` | `fun()`\|nil | 否       | nil    | 异常回调 |
 
 **示例:**
@@ -549,8 +548,8 @@ function ShouldInterruptThread() end
 
 **返回值:**
 
-| 类型      | 描述     |
-| --------- | -------- |
+| 类型      | 描述       |
+| --------- | ---------- |
 | `boolean` | 是否应退出 |
 
 **示例:**
@@ -689,4 +688,3 @@ function loge(...) end
 loge("网络请求失败")
 loge("文件读取错误")
 ```
-

package/docs/apilua/image.md

@@ -14,12 +14,18 @@
 
 所有传递`imageId`的函数都可以使用`"actionScreenshot"`作为参数，来表示指定 HID 快捷键系统截图
 
+所有传递`imageId`的函数都可以使用`"vpnScreenshot"`作为参数，来表示指定VPN免自动化截图
+
 所有传递`imageId`的函数都可以使用图片路径作为参数，来表示对指定图片进行操作，支持 res 目录文件，和手机文件路径。
 
+`captureScreen` 默认按 `"screen"` 截图。免越狱调用 `setCaptureImageId` 后，改为按设置的 imageId 截图。越狱版该设置不生效。
+
 ## 图片获取与管理
 
 ### captureScreen - 截取屏幕。
 
+按 `setCaptureImageId` 设置的 imageId 截取。未设置时为 `"screen"`。越狱版固定为 `"screen"`。
+
 ```lua
 ---@param x number?
 ---@param y number?
@@ -64,6 +70,37 @@ if rectId then
 end
 ```
 
+### setCaptureImageId - 设置 captureScreen 的默认 imageId。
+
+设置之后，`captureScreen` 按这个 imageId 截图。可传入与其它 image 函数相同的 imageId：`"screen"`、`"shortcut"`、`"actionScreenshot"`、`"vpnScreenshot"`、res 目录或手机绝对路径、已有图片 ID。越狱版调用后不改变来源。
+
+```lua
+---@param imageId string
+function setCaptureImageId(imageId) end
+```
+
+**参数：**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                              |
+| ---------- | ------ | -------- | ------ | ------------------------------------------------- |
+| `imageId`  | string | 是       | -      | `captureScreen` 使用的来源 |
+
+**示例：**
+
+```lua
+-- 之后的 captureScreen 使用快捷指令截图
+image.setCaptureImageId("shortcut")
+local imageId = image.captureScreen()
+local dir = file.getInternalDir("documents")
+if imageId then
+  image.saveTo(imageId, dir .. "/screenshot.jpg")
+  image.release(imageId)
+end
+
+-- 恢复为当前屏幕
+image.setCaptureImageId("screen")
+```
+
 ### readImage - 从文件路径或imageId读取图片。
 
 ```lua

package/docs/apilua/jbsystem.md

@@ -8,6 +8,8 @@
 
 还可读写「允许 App 请求跟踪」「个性化广告」和定位服务总开关。不同 iOS 版本中，这些设置项的名称或位置可能略有不同。
 
+`jbroot` 把系统根下的路径映射成越狱根下的绝对路径。`rootfs` 把越狱根路径还原成系统根路径。已经是越狱根路径时再调用 `jbroot`，会再映射一次。
+
 ## API 参考
 
 ### respring - 重启 SpringBoard（Respring）。
@@ -223,3 +225,78 @@ function setLocationServices(enabled) end
 ```lua
 jbsystem.setLocationServices(false)
 ```
+
+### jbroot - 系统根路径映射为越狱根路径。
+
+```lua
+---@param path string
+---@return string
+function jbroot(path) end
+```
+
+**参数:**
+
+| 参数名 | 类型     | 是否必填 | 默认值 | 描述           |
+| ------ | -------- | -------- | ------ | -------------- |
+| `path` | `string` | 是       | -      | 系统根下的路径 |
+
+**返回值:**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `string` | 对应的越狱根路径 |
+
+**示例:**
+
+```lua
+-- 传入系统根下的路径，返回越狱根下的绝对路径。
+-- 隐根：
+--   jbsystem.jbroot("/")        -> /var/containers/Bundle/Application/.jbroot-XXXXXXXXXXXXXXXX/
+--   jbsystem.jbroot("/usr/bin") -> /var/containers/Bundle/Application/.jbroot-XXXXXXXXXXXXXXXX/usr/bin
+-- 无根：
+--   jbsystem.jbroot("/")        -> /var/jb
+--   jbsystem.jbroot("/usr/bin") -> /var/jb/usr/bin
+local bin = jbsystem.jbroot("/usr/bin")
+logi(bin)
+```
+
+### rootfs - 越狱根路径还原为系统根路径。
+
+把 `jbroot` 得到的越狱根路径还原成原来的系统根路径。
+
+```lua
+---@param path string
+---@return string
+function rootfs(path) end
+```
+
+**参数:**
+
+| 参数名 | 类型     | 是否必填 | 默认值 | 描述           |
+| ------ | -------- | -------- | ------ | -------------- |
+| `path` | `string` | 是       | -      | 越狱根下的路径 |
+
+**返回值:**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `string` | 对应的系统根路径 |
+
+**示例:**
+
+```lua
+-- 传入越狱根路径，返回对应的系统根路径。
+-- 隐根：
+--   jbsystem.rootfs("/var/containers/Bundle/Application/.jbroot-XXXXXXXXXXXXXXXX/")
+--     -> /
+--   jbsystem.rootfs("/var/containers/Bundle/Application/.jbroot-XXXXXXXXXXXXXXXX/usr/bin")
+--     -> /usr/bin
+-- 无根：
+--   jbsystem.rootfs("/var/jb")         -> /
+--   jbsystem.rootfs("/var/jb/usr/bin") -> /usr/bin
+-- 隐根上，系统根路径也会被 rootfs 指到 /rootfs：
+--   jbsystem.rootfs("/usr/bin") -> /rootfs/usr/bin
+local sysBin = jbsystem.rootfs(jbsystem.jbroot("/usr/bin"))
+logi(sysBin)
+-- /usr/bin
+```