ms-vite-plugin 1.5.12 → 1.5.14

package/docs/apicn/system.md

@@ -118,7 +118,7 @@ function 获取当前运行的应用(): {
   bundleId: 字符串;
   name: 字符串;
   pid: 数字;
-} | null;
+} | undefined;
 ```
 
 **返回值:**
@@ -334,14 +334,14 @@ if (set) {
 #### 获取剪切板内容 - 获取系统剪贴板内容。
 
 ```typescript
-function 获取剪切板内容(): 字符串 | null;
+function 获取剪切板内容(): 字符串;
 ```
 
 **返回值:**
 
 | 类型           | 描述                                      |
 | -------------- | ----------------------------------------- |
-| `字符串\|null` | 剪贴板文本内容 `null`剪贴板为空或获取失败 |
+| `字符串 \| undefined` | 剪贴板文本内容 `null`剪贴板为空或获取失败 |
 
 **示例:**
 

package/docs/apicn/thread.md

@@ -25,7 +25,7 @@
 启动一个新的线程来执行指定的 JS 文件。
 
 ```typescript
-function 运行(线程js文件名: 字符串, 启动参数?: 字典<任意类型>): 线程;
+function 运行(线程js文件名: 字符串, 启动参数?: 字典<任意类型>): 线程 | undefined;
 ```
 
 **参数:**
@@ -39,7 +39,7 @@ function 运行(线程js文件名: 字符串, 启动参数?: 字典<任意类型
 
 | 类型   | 描述         |
 | ------ | ------------ |
-| `线程` | 线程控制对象 |
+| `线程 \| undefined` | 线程控制对象；启动参数不是 Object 或启动失败时返回 undefined |
 
 **示例:**
 

package/docs/apicn/yolo.md

@@ -70,7 +70,7 @@ function 加载模型(
   标签数量?: 数字,
   模型版本?: 数字,
   useGpu?: 布尔值
-): 字符串 | null;
+): 字符串 | undefined;
 ```
 
 **参数:**
@@ -87,7 +87,7 @@ function 加载模型(
 
 | 类型             | 描述                                      |
 | ---------------- | ----------------------------------------- |
-| `字符串 \| null` | 加载成功返回模型 ID 字符串，失败返回 null |
+| `字符串 \| undefined` | 加载成功返回模型 ID 字符串，失败返回 undefined |
 
 **示例:**
 

package/docs/apicn/yolocls.md

@@ -25,9 +25,9 @@ YOLO 分类概率结果，字段命名与 Ultralytics `Probs` 保持一致。
 ```typescript
 interface Yolo分类概率结果 {
   data: 数组<数字>; // 所有类别概率，下标即类别 ID
-  top1: 数字 | null; // 概率最高的类别 ID
+  top1: 数字 | null; // 概率最高的类别 ID；分类失败时为 null
   top5: 数组<数字>; // 概率最高的 5 个类别 ID
-  top1conf: 数字 | null; // top1 对应的概率
+  top1conf: 数字 | null; // top1 对应的概率；分类失败时为 null
   top5conf: 数组<数字>; // top5 对应的概率
 }
 ```
@@ -37,9 +37,9 @@ interface Yolo分类概率结果 {
 | 字段名     | 类型             | 描述                                                       |
 | ---------- | ---------------- | ---------------------------------------------------------- |
 | `data`     | `数组<数字>`     | 所有类别概率数组，下标即类别 ID                            |
-| `top1`     | `数字 \| null`   | 概率最高的类别 ID；分类失败时为 `null`                     |
+| `top1`     | `数字 \| null`        | 概率最高的类别 ID；分类失败时为 `null`                          |
 | `top5`     | `数组<数字>`     | 概率最高的 5 个类别 ID，按概率从高到低排序                 |
-| `top1conf` | `数字 \| null`   | `top1` 对应的概率；分类失败时为 `null`                     |
+| `top1conf` | `数字 \| null`        | `top1` 对应的概率；分类失败时为 `null`                          |
 | `top5conf` | `数组<数字>`     | `top5` 对应的概率，顺序与 `top5` 一致                      |
 
 **结果说明:**
@@ -62,7 +62,7 @@ function 加载模型(
   ncnn模型的bin文件路径: 字符串,
   类别数量?: 数字,
   useGpu?: 布尔值
-): 字符串 | null;
+): 字符串 | undefined;
 ```
 
 **参数:**
@@ -78,7 +78,7 @@ function 加载模型(
 
 | 类型             | 描述                                      |
 | ---------------- | ----------------------------------------- |
-| `字符串 \| null` | 加载成功返回模型 ID 字符串，失败返回 null |
+| `字符串 \| undefined` | 加载成功返回模型 ID 字符串，失败返回 undefined |
 
 **示例:**
 

package/docs/apicn/zipFile.md

@@ -0,0 +1,113 @@
+# ZIP 模块 ($ZIP)
+
+路径必须是绝对路径。只压缩、解压 ZIP；`压缩` 只接受目录，不接受文件。
+
+## API 参考
+
+### 获取文件列表 - 获取 ZIP 内部文件列表。
+
+```typescript
+function 获取文件列表(路径: 字符串): 数组<字符串>;
+```
+
+**参数:**
+
+| 参数名 | 类型     | 是否必填 | 默认值 | 描述             |
+| ------ | -------- | -------- | ------ | ---------------- |
+| `路径` | `字符串` | 是       | -      | ZIP 文件绝对路径 |
+
+**返回值:**
+
+| 类型           | 描述                                                         |
+| -------------- | ------------------------------------------------------------ |
+| `数组<字符串>` | 包内文件路径；不含目录项。不是合法 ZIP 时返回空数组 |
+
+**示例:**
+
+```javascript
+const 路径 = $文件.获取内部目录("documents") + "/a.zip";
+const 列表 = $ZIP.获取文件列表(路径);
+```
+
+### 是否为ZIP - 检查是否为合法 ZIP。
+
+```typescript
+function 是否为ZIP(路径: 字符串): 布尔值;
+```
+
+**参数:**
+
+| 参数名 | 类型     | 是否必填 | 默认值 | 描述         |
+| ------ | -------- | -------- | ------ | ------------ |
+| `路径` | `字符串` | 是       | -      | 文件绝对路径 |
+
+**返回值:**
+
+| 类型     | 描述                      |
+| -------- | ------------------------- |
+| `布尔值` | 能作为 ZIP 打开为 `true` |
+
+**示例:**
+
+```javascript
+const 路径 = $文件.获取内部目录("documents") + "/a.zip";
+if ($ZIP.是否为ZIP(路径)) {
+  $打印信息日志("是 ZIP");
+}
+```
+
+### 解压 - 解压到指定目录。
+
+目标目录不存在会创建。包内路径必须落在目标目录内，否则失败。
+
+```typescript
+function 解压(压缩包路径: 字符串, 目标目录: 字符串): 布尔值;
+```
+
+**参数:**
+
+| 参数名       | 类型     | 是否必填 | 默认值 | 描述                 |
+| ------------ | -------- | -------- | ------ | -------------------- |
+| `压缩包路径` | `字符串` | 是       | -      | ZIP 文件绝对路径     |
+| `目标目录`   | `字符串` | 是       | -      | 解压目标目录绝对路径 |
+
+**返回值:**
+
+| 类型     | 描述              |
+| -------- | ----------------- |
+| `布尔值` | 解压成功为 `true` |
+
+**示例:**
+
+```javascript
+const 目录 = $文件.获取内部目录("documents");
+$ZIP.解压(目录 + "/a.zip", 目录 + "/out");
+```
+
+### 压缩 - 压缩目录为 ZIP。
+
+包内根条目是该目录名。已有同名 ZIP 文件会先删再写。源路径必须是目录，不能是文件。输出 ZIP 不能落在源目录内。
+
+```typescript
+function 压缩(目录路径: 字符串, 压缩包路径: 字符串): 布尔值;
+```
+
+**参数:**
+
+| 参数名       | 类型     | 是否必填 | 默认值 | 描述                                |
+| ------------ | -------- | -------- | ------ | ----------------------------------- |
+| `目录路径`   | `字符串` | 是       | -      | 要压缩的目录绝对路径                |
+| `压缩包路径` | `字符串` | 是       | -      | 输出 ZIP 绝对路径，不能落在源目录内 |
+
+**返回值:**
+
+| 类型     | 描述              |
+| -------- | ----------------- |
+| `布尔值` | 压缩成功为 `true` |
+
+**示例:**
+
+```javascript
+const 目录 = $文件.获取内部目录("documents");
+$ZIP.压缩(目录 + "/out", 目录 + "/out.zip");
+```

package/docs/apilua/jbdraw.md

@@ -0,0 +1,141 @@
+# 绘制模块 (JBDraw)
+
+模块表是内置全局 `jbdraw`，直接调用即可。不要 `require` 宿主模块。
+
+仅越狱包可用。免越狱包没有 `jbdraw`。
+
+在屏幕上画矩形和文字。每画一次返回一个 id，可用 `clear` 去掉这一条，或 `clearAll` 全部去掉。坐标为像素坐标。
+
+颜色只接受 `#RRGGBB` 和 `#RRGGBBAA`。需要字加底时先画填充矩形，再画文字。
+
+## 类型
+
+```lua
+---@class JbDrawRectOptions
+---@field color string|nil
+---@field lineWidth number|nil
+---@field fill string|nil
+
+---@class JbDrawTextOptions
+---@field color string|nil
+---@field fontSize number|nil
+```
+
+| 字段        | 类型          | 描述                                                         |
+| ----------- | ------------- | ------------------------------------------------------------ |
+| `color`     | string\|nil   | `#RRGGBB` 或 `#RRGGBBAA`。矩形默认 `#FF0000`，文字默认 `#FFFFFF` |
+| `lineWidth` | number\|nil   | 边框宽度。省略为 `2`。`<= 0` 不画边框                         |
+| `fill`      | string\|nil   | 填充颜色，同 `color` 格式。省略不填充                         |
+| `fontSize`  | number\|nil   | 系统字号。省略为 `16`。`<= 0` 时画字失败                      |
+
+## API 参考
+
+### rect - 在屏幕上画矩形。
+
+需要字加底时先画填充矩形，再 `text`。
+
+```lua
+---@param x number
+---@param y number
+---@param width number
+---@param height number
+---@param options JbDrawRectOptions|nil
+---@return integer
+function rect(x, y, width, height, options) end
+```
+
+**参数:**
+
+| 参数名    | 类型                    | 是否必填 | 默认值 | 描述                               |
+| --------- | ----------------------- | -------- | ------ | ---------------------------------- |
+| `x`       | number                  | 是       | -      | 左上角 x，像素坐标                 |
+| `y`       | number                  | 是       | -      | 左上角 y，像素坐标                 |
+| `width`   | number                  | 是       | -      | 宽度，必须大于 0                   |
+| `height`  | number                  | 是       | -      | 高度，必须大于 0                   |
+| `options` | JbDrawRectOptions\|nil  | 否       | -      | 颜色、边框、填充                   |
+
+**返回值:**
+
+| 类型    | 描述                           |
+| ------- | ------------------------------ |
+| integer | 成功为 id（从 1 起）；失败为 `0` |
+
+**示例:**
+
+```lua
+local box = jbdraw.rect(20, 80, 200, 40, { fill = "#000000AA", lineWidth = 0 })
+local frame = jbdraw.rect(20, 140, 120, 80, { color = "#FF0000", lineWidth = 2 })
+```
+
+### text - 在屏幕上画文字。
+
+左上角对齐，没有背景。
+
+```lua
+---@param x number
+---@param y number
+---@param text string
+---@param options JbDrawTextOptions|nil
+---@return integer
+function text(x, y, text, options) end
+```
+
+**参数:**
+
+| 参数名    | 类型                    | 是否必填 | 默认值 | 描述                               |
+| --------- | ----------------------- | -------- | ------ | ---------------------------------- |
+| `x`       | number                  | 是       | -      | 文字左上角 x，像素坐标             |
+| `y`       | number                  | 是       | -      | 文字左上角 y，像素坐标             |
+| `text`    | string                  | 是       | -      | 要画的字符串                       |
+| `options` | JbDrawTextOptions\|nil  | 否       | -      | 颜色和字号                         |
+
+**返回值:**
+
+| 类型    | 描述                           |
+| ------- | ------------------------------ |
+| integer | 成功为 id（从 1 起）；失败为 `0` |
+
+**示例:**
+
+```lua
+local box = jbdraw.rect(20, 80, 200, 40, { fill = "#000000AA", lineWidth = 0 })
+local label = jbdraw.text(28, 88, "hello", { color = "#FFFFFF", fontSize = 18 })
+```
+
+### clear - 去掉一个图形。
+
+```lua
+---@param id integer
+---@return boolean
+function clear(id) end
+```
+
+**参数:**
+
+| 参数名 | 类型    | 是否必填 | 默认值 | 描述                     |
+| ------ | ------- | -------- | ------ | ------------------------ |
+| `id`   | integer | 是       | -      | `rect` / `text` 返回的 id |
+
+**返回值:**
+
+| 类型    | 描述                |
+| ------- | ------------------- |
+| boolean | 找到并移除为 `true` |
+
+**示例:**
+
+```lua
+jbdraw.clear(label)
+```
+
+### clearAll - 去掉当前全部图形。
+
+```lua
+function clearAll() end
+```
+
+**示例:**
+
+```lua
+jbdraw.clearAll()
+```

package/docs/apilua/jbpower.md

@@ -0,0 +1,136 @@
+# 电源模块 (JBPower)
+
+模块表是内置全局 `jbpower`，直接调用即可。不要 `require` 宿主模块。
+
+仅越狱包可用。免越狱包没有 `jbpower`。
+
+`info` 读取电量百分比、电流、电压和充电状态。`stopCharging` 停止充电并保持，直到调用 `startCharging`。`setSmartCharging` 到上限停止充电，降到下限再充，中间保持。
+
+电流单位是毫安，正数表示正在进电。电压单位是毫伏。
+
+## API 参考
+
+### info - 读取当前电源信息。
+
+```lua
+function info()
+```
+
+**返回值:**
+
+| 类型          | 描述                 |
+| ------------- | -------------------- |
+| `JbPowerInfo` | 读到电池时的电源信息 |
+| `nil`         | 读不到电池           |
+
+`JbPowerInfo` 字段：
+
+| 字段                 | 类型      | 描述                                              |
+| -------------------- | --------- | ------------------------------------------------- |
+| `percentage`         | `integer` | 电量百分比                                        |
+| `amperage`           | `integer` | 电流，单位毫安，正数表示正在进电                  |
+| `voltage`            | `integer` | 电压，单位毫伏                                    |
+| `charging`           | `boolean` | 系统是否认为正在充电                              |
+| `plugged`            | `boolean` | 电源状态是否为交流电                              |
+| `powerState`         | `string`  | `AC Power` 或 `Battery Power`                     |
+| `rawExternal`        | `boolean` | 发布出去的外接位                                  |
+| `showChargingUI`     | `boolean` | 主屏是否显示充电                                  |
+| `appleRawExternal`   | `boolean` | 硬件是否还认这根线                                |
+| `chargeOverride`     | `boolean` | 系统自己的停充覆盖                                |
+| `adapterWatts`       | `integer` | 适配器功率，单位瓦，读不到时为 0                  |
+
+**示例:**
+
+```lua
+local power = jbpower.info()
+if power then
+  logd(power.percentage, power.amperage)
+end
+```
+
+### stopCharging - 停止充电。
+
+停止后会保持，直到 `startCharging`。
+
+```lua
+function stopCharging()
+```
+
+**返回值:**
+
+| 类型      | 描述            |
+| --------- | --------------- |
+| `boolean` | 写入成功为 `true` |
+
+**示例:**
+
+```lua
+jbpower.stopCharging()
+```
+
+### startCharging - 恢复充电。
+
+```lua
+function startCharging()
+```
+
+**返回值:**
+
+| 类型      | 描述            |
+| --------- | --------------- |
+| `boolean` | 写入成功为 `true` |
+
+**示例:**
+
+```lua
+jbpower.startCharging()
+```
+
+### setSmartCharging - 打开智能充电。
+
+电量到 `max` 停止充电，降到 `min` 再充。窗口中间保持上次的决定，不会在停充和充电之间来回切。
+
+上限会收到 2 到 100，下限至少为 1，并且必须小于上限。
+
+```lua
+function setSmartCharging(min, max)
+```
+
+**参数:**
+
+| 参数  | 类型      | 描述             |
+| ----- | --------- | ---------------- |
+| `min` | `integer` | 再充下限，百分比 |
+| `max` | `integer` | 停充上限，百分比 |
+
+**返回值:**
+
+| 类型      | 描述            |
+| --------- | --------------- |
+| `boolean` | 保存成功为 `true` |
+
+**示例:**
+
+```lua
+jbpower.setSmartCharging(20, 80)
+```
+
+### clearSmartCharging - 关掉智能充电。
+
+如果当前正按窗口停充，会恢复充电。
+
+```lua
+function clearSmartCharging()
+```
+
+**返回值:**
+
+| 类型      | 描述            |
+| --------- | --------------- |
+| `boolean` | 保存成功为 `true` |
+
+**示例:**
+
+```lua
+jbpower.clearSmartCharging()
+```

package/docs/apilua/netCard.md

@@ -2,18 +2,17 @@
 
 模块表是内置全局 `netcard`，直接调用即可。不要 `require` 宿主模块。
 
-卡密模块提供了卡密验证、备注设置以及键值对存储功能，用于管理网络卡密相关的操作。
+卡密模块提供了卡密验证和备注设置功能，用于管理网络卡密相关的操作。
 
 ## 功能概览
 
 - **卡密验证**: 验证卡密的有效性
 - **备注管理**: 设置和管理卡密备注信息
-- **云变量存储**: 提供键值对形式的数据存储和读取功能
 
 ## 注意事项
 
 1. **卡密安全**: 卡密信息应当妥善保管，避免在日志中明文输出
-2. **普通卡密模式**: 需要先调用 `netCard.verify(cardNo)` 验证卡密，验证通过后才能调用获取卡密信息、备注和云变量等接口
+2. **普通卡密模式**: 需要先调用 `netCard.verify(cardNo)` 验证卡密，验证通过后才能调用获取卡密信息和备注等接口
 3. **授权卡密模式**: App 打开加密 UI 或运行脚本前会完成授权和卡密验证，脚本中不需要重复让用户输入卡密，也不需要重复调用 `netCard.verify`
 4. **兼容旧脚本**: 授权卡密模式下调用 `netCard.verify` 会直接返回 `true`，用于兼容原来已经写了 `verify` 的脚本
 
@@ -58,7 +57,7 @@ function verify(cardNo) end
 
 **说明：**
 
-普通卡密模式下，该方法会请求普通卡密验证接口，验证成功后才能继续使用卡密信息、备注和云变量相关能力。
+普通卡密模式下，该方法会请求普通卡密验证接口，验证成功后才能继续使用卡密信息和备注相关能力。
 
 授权卡密模式下，App 层已经完成授权和卡密验证，脚本侧不需要重复调用该方法；如果旧脚本仍然调用，方法会直接返回 `true`。
 
@@ -145,76 +144,3 @@ else
   logger.error("备注设置失败")
 end
 ```
-
-### 云变量
-
-#### setValue - 设置键值对
-
-```lua
----@param key string
----@param value string
----@return string
-function setValue(key, value) end
-```
-
-**参数说明：**
-
-| 参数名  | 类型   | 是否必填 | 默认值 | 描述       |
-| ------- | ------ | -------- | ------ | ---------- |
-| `key`   | string | 是       |        | 存储的键名 |
-| `value` | string | 是       |        | 存储的值   |
-
-**返回值：**
-
-| 类型     | 描述                                          |
-| -------- | --------------------------------------------- |
-| `string` | 成功时返回设置的 value 值，失败时返回空字符串 |
-
-**示例：**
-
-```lua
--- 设置键值对
-local key = "userConfig"
-local value = "enableNotification"
-local result = netcard.setValue(key, value)
-
-if result == value then
-  print("成功设置 [" .. tostring(key) .. "] = " .. tostring(value))
-else
-  logger.error("设置失败")
-end
-```
-
-#### getValue - 获取键值对
-
-```lua
----@param key string
----@return string
-function getValue(key) end
-```
-
-**参数说明：**
-
-| 参数名 | 类型   | 是否必填 | 默认值 | 描述         |
-| ------ | ------ | -------- | ------ | ------------ |
-| `key`  | string | 是       |        | 要获取的键名 |
-
-**返回值：**
-
-| 类型     | 描述                                             |
-| -------- | ------------------------------------------------ |
-| `string` | 成功时返回对应的值，失败或键不存在时返回空字符串 |
-
-**示例：**
-
-```lua
--- 获取键值对
-local key = "userConfig"
-local value = netcard.getValue(key)
-
-if value then
-  print("获取到配置: " .. tostring(key) .. " = " .. tostring(value))
-else
-  print("配置 " .. tostring(key) .. " 不存在或获取失败")
-end
-```

package/docs/apilua/node.md

@@ -155,9 +155,11 @@ selector:releaseNode()  -- 手动释放
 | `depth` | 层级 |
 | `childCount` | 子节点数，支持数字或如 `">0"` |
 | `bounds(x, y, width, height)` | 区域 |
-| `xpath` | XPath |
+| `xpath` | XPath 1.0 路径 |
 | `id` | 按节点 ID |
 
+`xpath` 只支持 [XPath 1.0](https://www.w3.org/TR/1999/REC-xpath-19991116/)。`matches()` 等 XPath 2.0 函数不可用；属性上的正则用 `identifierMatch` 等带 `Match` 的方法。
+
 ```lua
 -- 精确
 selector:label("确定"):type("XCUIElementTypeButton"):getOneNodeInfo(3000)