ms-vite-plugin 1.5.9 → 1.5.11

package/docs/apipython/overview.md

@@ -5,7 +5,7 @@
 - 导入方式：
 
 ```python
-from kuaijs import action, cloud, hid, image, appleocr, paddleocr, yolo, yolocls, system, device, file, mysql, netcard, ime, media, hotupdate, tomatoocr, tts, ui, utils, node, pip, logger
+from kuaijs import action, cloud, hid, image, appleocr, paddleocr, yolo, yolocls, system, device, file, mysql, netcard, ime, jbdylib, jbshell, media, hotupdate, tomatoocr, tts, ui, utils, node, pip, logger
 ```
 
 ## 标准库

package/docs/apipython/pip.md

@@ -1,13 +1,14 @@
 # 悬浮窗模块 (PIP)
 
-悬浮窗模块提供 iOS 画中画（Picture in Picture）悬浮窗能力，可用于显示脚本日志、保活提示或脚本自定义文本。
+悬浮窗模块提供 iOS 悬浮窗能力。免越狱包使用系统画中画（Picture in Picture），可用于显示脚本日志、保活提示或脚本自定义文本。越狱包使用同一套 `pip` API 控制全局悬浮球：保活只显示图标，日志显示图标和日志窗口，自定义显示图标和自定义文本窗口。
 
 ## 功能特性
 
-- **显示模式**：支持日志、保活和自定义三种显示模式；首次安装默认保活
+- **显示模式**：支持日志、保活和自定义三种显示模式；首次安装默认关闭
 - **关闭控制**：支持主动关闭悬浮窗
 - **状态查询**：判断悬浮窗是否正在显示
-- **尺寸设置**：日志模式和自定义模式支持设置内容宽高比（实际显示尺寸由系统决定），并按模式分别持久化
+- **尺寸设置**：日志模式和自定义模式支持设置尺寸并分别持久化。系统画中画为宽高比（实际显示尺寸由系统决定）；越狱包为窗口宽高（像素）
+- **位置设置**：越狱包可用 `setPosition` 设置日志窗口和自定义文本窗口位置；保活模式不接受；系统画中画位置由 iOS 管理
 - **日志显示**：日志模式支持设置日志文字大小
 - **自定义文本**：自定义模式支持文本、换行、文字颜色、背景色和文字大小
 
@@ -38,7 +39,7 @@ if pip.isPipActive():
 
 ### switchToLogMode - 切换到日志模式
 
-切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。日志模式会恢复最近一次保存的日志窗口尺寸。
+切换到日志模式并尝试显示悬浮窗日志窗口。首次显示系统画中画时 App 必须在前台。日志模式会恢复最近一次保存的日志窗口尺寸。越狱包显示悬浮球图标和日志窗口。
 
 ```python
 def switchToLogMode() -> bool
@@ -62,7 +63,7 @@ pip.setLogFontSize(10)
 
 ### switchToKeepAliveMode - 切换到保活模式
 
-切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。保活模式不接受脚本尺寸设置。
+切换到保活模式并尝试显示极小高度悬浮窗。首次显示系统画中画时 App 必须在前台。保活模式不接受脚本尺寸设置。越狱包只显示悬浮球图标。
 
 ```python
 def switchToKeepAliveMode() -> bool
@@ -85,7 +86,7 @@ success = pip.switchToKeepAliveMode()
 
 ### switchToCustomMode - 切换到自定义模式
 
-切换到自定义模式并显示脚本设置的自定义文本。首次显示悬浮窗时 App 必须在前台。自定义模式会恢复最近一次保存的自定义窗口尺寸。
+切换到自定义模式并显示脚本设置的自定义文本。首次显示系统画中画时 App 必须在前台。自定义模式会恢复最近一次保存的自定义窗口尺寸。越狱包显示悬浮球图标和自定义文本窗口。
 
 ```python
 def switchToCustomMode() -> bool
@@ -133,7 +134,7 @@ success = pip.closeWindow()
 
 ### setContentSize - 设置内容尺寸
 
-设置日志模式或自定义模式的悬浮窗内容尺寸。传入的宽高表示宽高比，不是最终像素尺寸；悬浮窗实际显示的宽高由系统决定。宽度和高度都必须传入有效数字。日志模式和自定义模式会分别保存尺寸；悬浮窗关闭状态和保活模式不会生效。
+设置日志模式或自定义模式的悬浮窗内容尺寸。系统画中画传入的宽高表示宽高比，不是最终像素尺寸，实际显示宽高由系统决定。越狱包传入的宽高是对应窗口的像素尺寸。宽度和高度都必须传入有效数字。日志模式和自定义模式会分别保存尺寸；关闭状态和保活模式不会生效。
 
 ```python
 def setContentSize(width: float, height: float) -> bool
@@ -143,8 +144,8 @@ def setContentSize(width: float, height: float) -> bool
 
 | 参数     | 类型             | 必填 | 描述                          |
 | -------- | ---------------- | ---- | ----------------------------- |
-| `width`  | `float` | 是   | 宽度方向比例值（与 `height` 共同决定宽高比，不是像素） |
-| `height` | `float` | 是   | 高度方向比例值（与 `width` 共同决定宽高比，不是像素） |
+| `width`  | `float` | 是   | 宽度。系统画中画为比例值；越狱包为窗口宽度（像素） |
+| `height` | `float` | 是   | 高度。系统画中画为比例值；越狱包为窗口高度（像素） |
 
 **返回值：**
 
@@ -164,6 +165,36 @@ pip.switchToCustomMode()
 pip.setContentSize(120, 180)
 ```
 
+### setPosition - 设置位置
+
+设置悬浮窗位置。仅越狱包生效；系统画中画由 iOS 管理位置，调用返回 `False`。只对日志窗口和自定义文本窗口生效；保活模式不接受设置位置。
+
+```python
+def setPosition(x: float, y: float) -> bool
+```
+
+**参数：**
+
+| 参数 | 类型    | 必填 | 描述               |
+| ---- | ------- | ---- | ------------------ |
+| `x`  | `float` | 是   | 窗口左上角逻辑 X   |
+| `y`  | `float` | 是   | 窗口左上角逻辑 Y   |
+
+**返回值：**
+
+| 类型   | 描述                                                |
+| ------ | --------------------------------------------------- |
+| `bool` | `True` 代表位置已提交；`False` 代表当前不能设置位置 |
+
+**示例：**
+
+```python
+from kuaijs import pip
+
+pip.switchToLogMode()
+pip.setPosition(24, 120)
+```
+
 ### setLogFontSize - 设置日志文字大小
 
 设置日志模式显示文本的文字大小。该方法只更新日志字号，不会自动切换到日志模式。
@@ -330,9 +361,9 @@ pip.setContentSize(120, 180)
 
 ## 注意事项
 
-1. **前台限制**：首次切换到日志、保活或自定义显示模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换显示模式或关闭悬浮窗
-2. **设备兼容性**：仅支持 iOS 15+ 且具备画中画功能的设备
-3. **系统限制**：悬浮窗位置和实际显示尺寸由 iOS 管理
+1. **前台限制**：系统画中画首次切换到日志、保活或自定义显示模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换显示模式或关闭悬浮窗
+2. **设备兼容性**：系统画中画仅支持 iOS 15+ 且具备画中画功能的设备；越狱包全局悬浮球不依赖系统画中画
+3. **位置**：系统画中画位置由 iOS 管理；越狱包日志/自定义窗口可用 `setPosition`，保活模式不接受
 4. **尺寸持久化**：日志模式和自定义模式分别保存尺寸，互不共用；保活模式不接受脚本尺寸
 5. **日志字号**：日志字号只影响日志模式，保活模式和自定义模式不受影响
 6. **竖向文本**：自定义窗口高度大于宽度时，文本会按逐字符换行方式竖向显示
@@ -341,11 +372,17 @@ pip.setContentSize(120, 180)
 
 ### 悬浮窗无法显示
 
-- 确认设备支持悬浮窗功能
-- 检查悬浮窗权限是否已开启
-- 确认应用当前在前台
+- 确认当前已切换到日志、保活或自定义模式，且不是关闭状态
+- 系统画中画：确认设备支持悬浮窗功能，并检查悬浮窗权限是否已开启
+- 系统画中画：确认应用当前在前台
 
 ### setContentSize 返回 False
 
 - 确认当前模式是日志模式或自定义模式
 - 确认宽度和高度都传入了有效数字
+
+### setPosition 返回 False
+
+- 确认当前是越狱包，且已切换到日志或自定义模式，对应窗口已打开
+- 保活模式不支持设置位置
+- 确认 x、y 都传入了有效数字

package/docs/apipython/plist.md

@@ -0,0 +1,152 @@
+# 属性列表模块 (Plist)
+
+路径必须是绝对路径。
+
+## API 参考
+
+### read - 读取整个 plist
+
+```python
+from typing import Any, Optional
+
+def read(path: str) -> Optional[Any]
+```
+
+**参数:**
+
+| 参数名 | 类型  | 是否必填 | 描述         |
+| ------ | ----- | -------- | ------------ |
+| `path` | `str` | 是       | 文件绝对路径 |
+
+**返回值:**
+
+| 类型            | 描述   |
+| --------------- | ------ |
+| `Any` \| `None` | 根对象 |
+
+**示例:**
+
+```python
+from kuaijs import file, plist
+path = file.getInternalDir("documents") + "/info.plist"
+info = plist.read(path)
+```
+
+### write - 写成 plist
+
+```python
+from typing import Any, Optional
+
+def write(path: str, value: Any, format: Optional[str] = None) -> bool
+```
+
+**参数:**
+
+| 参数名   | 类型            | 是否必填 | 描述                           |
+| -------- | --------------- | -------- | ------------------------------ |
+| `path`   | `str`           | 是       | 文件绝对路径                   |
+| `value`  | `Any`           | 是       | dict、list、字符串、数字或布尔 |
+| `format` | `str` \| `None` | 否       | `xml` 或 `binary`，默认 xml    |
+
+**返回值:**
+
+| 类型   | 描述              |
+| ------ | ----------------- |
+| `bool` | 写入成功为 `True` |
+
+**示例:**
+
+```python
+from kuaijs import file, plist
+path = file.getInternalDir("documents") + "/info.plist"
+plist.write(path, {"name": "kuaijs", "count": 1})
+plist.write(path, {"name": "kuaijs"}, "binary")
+```
+
+### get - 按键读取
+
+```python
+from typing import Any, List, Optional, Union
+
+def get(path: str, key: Union[str, List[str]]) -> Optional[Any]
+```
+
+**参数:**
+
+| 参数名 | 类型                 | 是否必填 | 描述             |
+| ------ | -------------------- | -------- | ---------------- |
+| `path` | `str`                | 是       | 文件绝对路径     |
+| `key`  | `str` \| `List[str]` | 是       | 键，或嵌套键列表 |
+
+**返回值:**
+
+| 类型            | 描述     |
+| --------------- | -------- |
+| `Any` \| `None` | 该键的值 |
+
+**示例:**
+
+```python
+from kuaijs import plist
+plist.get(path, "name")
+plist.get(path, ["a", "b"])
+```
+
+### set - 按键写入
+
+```python
+from typing import Any, List, Union
+
+def set(path: str, key: Union[str, List[str]], value: Any) -> bool
+```
+
+**参数:**
+
+| 参数名  | 类型                 | 是否必填 | 描述             |
+| ------- | -------------------- | -------- | ---------------- |
+| `path`  | `str`                | 是       | 文件绝对路径     |
+| `key`   | `str` \| `List[str]` | 是       | 键，或嵌套键列表 |
+| `value` | `Any`                | 是       | 要写入的值       |
+
+**返回值:**
+
+| 类型   | 描述              |
+| ------ | ----------------- |
+| `bool` | 写入成功为 `True` |
+
+**示例:**
+
+```python
+from kuaijs import plist
+plist.set(path, "name", "kuaijs")
+plist.set(path, ["a", "b"], 1)
+```
+
+### remove - 按键删除
+
+```python
+from typing import List, Union
+
+def remove(path: str, key: Union[str, List[str]]) -> bool
+```
+
+**参数:**
+
+| 参数名 | 类型                 | 是否必填 | 描述             |
+| ------ | -------------------- | -------- | ---------------- |
+| `path` | `str`                | 是       | 文件绝对路径     |
+| `key`  | `str` \| `List[str]` | 是       | 键，或嵌套键列表 |
+
+**返回值:**
+
+| 类型   | 描述              |
+| ------ | ----------------- |
+| `bool` | 删除成功为 `True` |
+
+**示例:**
+
+```python
+from kuaijs import plist
+plist.remove(path, "name")
+plist.remove(path, ["a", "b"])
+```

package/docs/apipython/ui.md

@@ -125,6 +125,51 @@ ui.call("loadData", {
 })
 ```
 
+### callFloatingWindow - 调用越狱悬浮窗网页中的 JavaScript 函数
+
+```python
+def callFloatingWindow(key: str, data: dict) -> None
+```
+
+调用悬浮窗网页里 `registerUIFunc` 注册的函数。主界面 WebView 不受影响。没有悬浮窗网页时无效果。
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述                     |
+| ------ | ---- | -------- | ------ | ------------------------ |
+| `key`  | str  | 是       |        | 悬浮窗页面 JavaScript 方法名 |
+| `data` | dict | 是       |        | 传递给方法的参数         |
+
+**示例：**
+
+```python
+from kuaijs import ui
+
+ui.callFloatingWindow("updateStatus", {"status": "running", "progress": 50})
+```
+
+### evalFloatingWindow - 在越狱悬浮窗网页中执行 JavaScript
+
+```python
+def evalFloatingWindow(code: str) -> None
+```
+
+在悬浮窗网页中执行 JavaScript。主界面 WebView 不受影响。没有悬浮窗网页时无效果。
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述                 |
+| ------ | ---- | -------- | ------ | -------------------- |
+| `code` | str  | 是       |        | JavaScript 代码字符串 |
+
+**示例：**
+
+```python
+from kuaijs import ui
+
+ui.evalFloatingWindow("console.log('float')")
+```
+
 ### showToast - 显示 Toast 提示消息
 
 ```python
@@ -668,6 +713,30 @@ ms.getDeviceID()
   });
 ```
 
+#### getOrientation - 获取屏幕方向
+
+```typescript
+declare function getOrientation(): Promise<"PORTRAIT" | "LANDSCAPE">;
+```
+
+**返回值：**
+
+| 类型                                        | 描述                                                         |
+| ------------------------------------------- | ------------------------------------------------------------ |
+| `Promise<"PORTRAIT" \| "LANDSCAPE">` | `"PORTRAIT"` 竖屏，`"LANDSCAPE"` 横屏 |
+
+**说明：**
+
+获取当前屏幕方向。
+
+**网页端示例：**
+
+```javascript
+ms.getOrientation().then((orientation) => {
+  console.log(orientation);
+});
+```
+
 #### openURL - 调用浏览器打开 URL
 
 ```typescript
@@ -707,6 +776,55 @@ ms.openURL("https://www.baidu.com")
   });
 ```
 
+#### setWebWindowSize - 设置网页窗口宽高
+
+```typescript
+declare function setWebWindowSize(size: {
+  portraitWidth: number;
+  portraitHeight: number;
+  landscapeWidth: number;
+  landscapeHeight: number;
+}): Promise<boolean>;
+```
+
+**参数：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                     |
+| ------ | ------ | -------- | ------ | ------------------------ |
+| `size` | object | 是       |        | 横竖屏网页窗口像素尺寸   |
+
+**`size` 字段：**
+
+| 字段名            | 类型   | 是否必填 | 默认值 | 描述                   |
+| ----------------- | ------ | -------- | ------ | ---------------------- |
+| `portraitWidth`   | number | 是       |        | 竖屏窗口宽度（像素）   |
+| `portraitHeight`  | number | 是       |        | 竖屏窗口高度（像素）   |
+| `landscapeWidth`  | number | 是       |        | 横屏窗口宽度（像素）   |
+| `landscapeHeight` | number | 是       |        | 横屏窗口高度（像素）   |
+
+**返回值：**
+
+| 类型               | 描述                                  |
+| ------------------ | ------------------------------------- |
+| `Promise<boolean>` | 如果设置成功返回 true，否则返回 false |
+
+**说明：**
+
+仅越狱包可用。一次同时设置竖屏和横屏的网页窗口像素尺寸。未调用过时，横竖屏都默认使用对应朝向屏幕宽高的 60%。免越狱包调用返回 `false`。
+
+**网页端示例：**
+
+```javascript
+ms.setWebWindowSize({
+  portraitWidth: 700,
+  portraitHeight: 1200,
+  landscapeWidth: 1200,
+  landscapeHeight: 700,
+}).then((ok) => {
+  console.log(ok);
+});
+```
+
 ### 完整示例
 
 **完整的控制面板示例：**

package/docs/httpapi/api.md

@@ -787,7 +787,7 @@ GET /api/status
 | »» isHidConnected         | boolean                     | true | none | hid设备是否连接                 | none                                     |
 | »» isShowUI               | boolean                     | true | none | 实现显示了 UI                   | none                                     |
 | »» isLogin                | boolean                     | true | none | 是否登录                        | none                                     |
-| »» deviceId               | string                      | true | none | 设备 ID，应用唯一，卸载重装变化 | none                                     |
+| »» deviceId               | string                      | true | none | 设备 ID                         | 越狱包为芯片生成的固定 ID，免越狱包为 IDFV          |
 
 #### 枚举值
 
@@ -3378,7 +3378,7 @@ GET /mirror/image
 | isHidConnected         | boolean | true | none | hid设备是否连接                 | none                                     |
 | isShowUI               | boolean | true | none | 实现显示了 UI                   | none                                     |
 | isLogin                | boolean | true | none | 是否登录                        | none                                     |
-| deviceId               | string  | true | none | 设备 ID，应用唯一，卸载重装变化 | none                                     |
+| deviceId               | string  | true | none | 设备 ID                         | 越狱包为芯片生成的固定 ID，免越狱包为 IDFV          |
 
 #### 枚举值
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms-vite-plugin",
-  "version": "1.5.9",
+  "version": "1.5.11",
   "type": "commonjs",
   "license": "MIT",
   "publishConfig": {