ms-vite-plugin 1.4.11 → 1.4.12

package/docs/apipython/pip.md

@@ -1,12 +1,14 @@
 # 悬浮窗模块 (PIP)
 
-悬浮窗模块提供画中画（Picture in Picture）日志窗口能力。
+悬浮窗模块提供 iOS 画中画（Picture in Picture）悬浮窗能力，可用于显示脚本日志、保活提示或脚本自定义文本。
 
 ## 功能特性
 
-- **模式切换**：切换日志、保活和关闭三种悬浮窗模式
+- **显示模式**：支持日志、保活和自定义三种显示模式
+- **关闭控制**：支持主动关闭悬浮窗
 - **状态查询**：判断悬浮窗是否正在显示
-- **识别标记**：日志窗口左上角默认显示高对比标记，可用于截图识别悬浮窗位置
+- **尺寸设置**：日志模式和自定义模式支持设置内容宽高，并按模式分别持久化
+- **自定义文本**：自定义模式支持文本、换行、文字颜色、背景色和文字大小
 
 ## API 参考
 
@@ -35,7 +37,7 @@ if pip.isPipActive():
 
 ### switchToLogMode - 切换到日志模式
 
-切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。
+切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。日志模式会恢复最近一次保存的日志窗口尺寸。
 
 ```python
 def switchToLogMode() -> bool
@@ -58,7 +60,7 @@ success = pip.switchToLogMode()
 
 ### switchToKeepAliveMode - 切换到保活模式
 
-切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。
+切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。保活模式不接受脚本尺寸设置。
 
 ```python
 def switchToKeepAliveMode() -> bool
@@ -79,12 +81,12 @@ utils.takeMeToFront()
 success = pip.switchToKeepAliveMode()
 ```
 
-### switchToOffMode - 切换到关闭模式
+### switchToCustomMode - 切换到自定义模式
 
-切换到关闭模式并关闭悬浮窗。
+切换到自定义模式并显示脚本设置的自定义文本。首次显示悬浮窗时 App 必须在前台。自定义模式会恢复最近一次保存的自定义窗口尺寸。
 
 ```python
-def switchToOffMode() -> bool
+def switchToCustomMode() -> bool
 ```
 
 **返回值：**
@@ -95,10 +97,185 @@ def switchToOffMode() -> bool
 
 **示例：**
 
+```python
+from kuaijs import pip, utils
+
+utils.takeMeToFront()
+pip.switchToCustomMode()
+pip.setCustomText("运行中\n进度 1/3")
+pip.setCustomTextColor("#34c759")
+pip.setCustomTextSize(18)
+```
+
+### closeWindow - 关闭悬浮窗
+
+关闭悬浮窗。
+
+```python
+def closeWindow() -> bool
+```
+
+**返回值：**
+
+| 类型   | 描述                  |
+| ------ | --------------------- |
+| `bool` | `True` 代表已提交请求 |
+
+**示例：**
+
+```python
+from kuaijs import pip
+
+success = pip.closeWindow()
+```
+
+### setContentSize - 设置内容尺寸
+
+设置日志模式或自定义模式的悬浮窗内容尺寸。宽度和高度都必须传入有效数字。日志模式和自定义模式会分别保存尺寸；悬浮窗关闭状态和保活模式不会生效。
+
+```python
+def setContentSize(width: float, height: float) -> bool
+```
+
+**参数：**
+
+| 参数     | 类型             | 必填 | 描述                          |
+| -------- | ---------------- | ---- | ----------------------------- |
+| `width`  | `float` | 是   | 目标内容宽度 |
+| `height` | `float` | 是   | 目标内容高度 |
+
+**返回值：**
+
+| 类型   | 描述                                                                |
+| ------ | ------------------------------------------------------------------- |
+| `bool` | `True` 代表尺寸已提交；`False` 代表当前模式不允许设置或宽高无效 |
+
+**示例：**
+
 ```python
 from kuaijs import pip
 
-success = pip.switchToOffMode()
+pip.switchToLogMode()
+pip.setContentSize(280, 120)
+
+pip.switchToCustomMode()
+pip.setContentSize(120, 180)
+```
+
+### setCustomText - 设置自定义文本
+
+设置自定义模式显示的纯文本内容。该方法只更新自定义文本数据，不会自动切换到自定义模式。
+
+```python
+def setCustomText(text: str) -> bool
+```
+
+**参数：**
+
+| 参数   | 类型  | 必填 | 描述                                        |
+| ------ | ----- | ---- | ------------------------------------------- |
+| `text` | `str` | 是   | 要显示的文本，支持真实换行和字符串中的 `\n` |
+
+**返回值：**
+
+| 类型   | 描述                  |
+| ------ | --------------------- |
+| `bool` | `True` 代表文本已提交 |
+
+**示例：**
+
+```python
+from kuaijs import pip
+
+pip.setCustomText("运行中\n进度 1/3")
+pip.switchToCustomMode()
+```
+
+### setCustomTextColor - 设置自定义文字颜色
+
+设置自定义模式显示文本的文字颜色。该方法只更新文字颜色数据，不会自动切换到自定义模式。
+
+```python
+def setCustomTextColor(color: str) -> bool
+```
+
+**参数：**
+
+| 参数    | 类型  | 必填 | 描述                                                       |
+| ------- | ----- | ---- | ---------------------------------------------------------- |
+| `color` | `str` | 是   | 文字颜色，支持 `RRGGBB`、`RRGGBBAA`，可带 `#` 前缀；末尾 AA 为透明度；无效值使用白色 |
+
+**返回值：**
+
+| 类型   | 描述                      |
+| ------ | ------------------------- |
+| `bool` | `True` 代表文字颜色已提交 |
+
+**示例：**
+
+```python
+from kuaijs import pip
+
+pip.setCustomTextColor("#34c759")
+pip.switchToCustomMode()
+```
+
+### setCustomTextSize - 设置自定义文字大小
+
+设置自定义模式显示文本的文字大小。该方法只更新文字大小数据，不会自动切换到自定义模式。
+
+```python
+def setCustomTextSize(fontSize: float) -> bool
+```
+
+**参数：**
+
+| 参数       | 类型    | 必填 | 描述                       |
+| ---------- | ------- | ---- | -------------------------- |
+| `fontSize` | `float` | 是   | 文字字号，必须是有效数字 |
+
+**返回值：**
+
+| 类型   | 描述                                                  |
+| ------ | ----------------------------------------------------- |
+| `bool` | `True` 代表文字大小已提交；`False` 代表字号无效 |
+
+**示例：**
+
+```python
+from kuaijs import pip
+
+pip.setCustomTextSize(18)
+pip.switchToCustomMode()
+```
+
+### setCustomBackgroundColor - 设置自定义背景色
+
+设置自定义模式显示区域的背景色。该方法只更新背景色数据，不会自动切换到自定义模式。
+
+```python
+def setCustomBackgroundColor(color: str) -> bool
+```
+
+**参数：**
+
+| 参数    | 类型  | 必填 | 描述                                                       |
+| ------- | ----- | ---- | ---------------------------------------------------------- |
+| `color` | `str` | 是   | 背景颜色，支持 `RRGGBB`、`RRGGBBAA`，可带 `#` 前缀；末尾 AA 为透明度；无效值使用黑色 |
+
+**返回值：**
+
+| 类型   | 描述                    |
+| ------ | ----------------------- |
+| `bool` | `True` 代表背景色已提交 |
+
+**示例：**
+
+```python
+from kuaijs import pip
+
+pip.setCustomBackgroundColor("#111111")
+pip.switchToCustomMode()
 ```
 
 ## 完整使用示例
@@ -107,15 +284,25 @@ success = pip.switchToOffMode()
 from kuaijs import pip, utils
 
 utils.takeMeToFront()
+
 pip.switchToLogMode()
+pip.setContentSize(280, 120)
+
+pip.setCustomText("任务运行中\n1/3")
+pip.setCustomTextColor("#34c759")
+pip.setCustomTextSize(18)
+pip.setCustomBackgroundColor("#111111")
+pip.switchToCustomMode()
+pip.setContentSize(120, 180)
 ```
 
 ## 注意事项
 
-1. **前台限制**：首次切换到日志模式或保活模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换日志/保活模式
+1. **前台限制**：首次切换到日志、保活或自定义显示模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换显示模式或关闭悬浮窗
 2. **设备兼容性**：仅支持 iOS 15+ 且具备画中画功能的设备
 3. **系统限制**：悬浮窗位置和实际显示尺寸由 iOS 管理
-4. **识别标记**：日志窗口左上角默认包含识别标记，便于通过截图识别悬浮窗位置
+4. **尺寸持久化**：日志模式和自定义模式分别保存尺寸，互不共用；保活模式不接受脚本尺寸
+5. **竖向文本**：自定义窗口高度大于宽度时，文本会按逐字符换行方式竖向显示
 
 ## 故障排除
 
@@ -124,3 +311,8 @@ pip.switchToLogMode()
 - 确认设备支持悬浮窗功能
 - 检查悬浮窗权限是否已开启
 - 确认应用当前在前台
+
+### setContentSize 返回 False
+
+- 确认当前模式是日志模式或自定义模式
+- 确认宽度和高度都传入了有效数字

package/docs/httpapi/api.md

@@ -936,7 +936,7 @@ GET /logger/download
 
 GET /logger/current/lines
 
-读取 LoggerModule 当前正在写入的日志文件最新输出行。单次最多返回 5000 行，超出时按 5000 行处理。接口会在读取前刷新当前日志缓冲区，返回的 `lines` 按日志原始输出顺序排列。
+读取 LoggerModule 当前已创建日志文件中已经写入的最新输出行。单次最多返回 5000 行，超出时按 5000 行处理。接口不会刷新当前日志缓冲区，也不会强制日志落盘，返回的 `lines` 按日志原始输出顺序排列。
 
 ### 请求参数
 

package/package.json

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