ms-vite-plugin 1.4.8 → 1.4.9

package/docs/apipython/pip.md

@@ -1,61 +1,15 @@
 # 悬浮窗模块 (PIP)
 
-悬浮窗模块提供了画中画（Picture in Picture）功能，允许在应用中显示悬浮的日志窗口，支持自定义样式。
+悬浮窗模块提供画中画（Picture in Picture）日志窗口能力。
 
 ## 功能特性
 
-- **悬浮窗显示**: 支持在屏幕上显示悬浮的日志窗口
-- **自定义样式**: 可配置窗口大小、字体、颜色等
-- **脚本控制配置**: 保留脚本控制配置接口，Video Call PiP 链路不再提供播放/暂停按钮回调
-
-## 类型定义
-
-### LogViewParams
-
-悬浮窗参数配置。
-
-```python
-from typing import TypedDict
-
-class LogViewParams(TypedDict):
-    width: float          # 悬浮窗内容宽度，默认 300
-    height: float         # 悬浮窗内容高度，支持最低 0.1pt
-    textSize: int         # 日志的字体大小
-    textColor: str        # 日志的文字颜色，格式如 #FFFFFF
-    backgroundColor: str  # 日志的背景颜色，格式如 #000000
-```
+- **模式切换**：切换日志、保活和关闭三种悬浮窗模式
+- **状态查询**：判断悬浮窗是否正在显示
+- **识别标记**：日志窗口左上角默认显示高对比标记，可用于截图识别悬浮窗位置
 
 ## API 参考
 
-### setLogViewParams - 设置悬浮窗显示参数
-
-设置悬浮窗日志窗口的显示参数。显示前调用会影响首次高度；显示后再次调用会同步更新当前 Video Call PiP 内容尺寸。
-
-```python
-def setLogViewParams(params: LogViewParams) -> None
-```
-
-**参数：**
-
-| 参数名   | 类型            | 是否必填 | 默认值 | 描述                   |
-| -------- | --------------- | -------- | ------ | ---------------------- |
-| `params` | `LogViewParams` | 是       | -      | 包含显示参数的配置对象 |
-
-**示例：**
-
-```python
-from kuaijs import pip
-
-# 配置悬浮窗参数
-pip.setLogViewParams({
-    "width": 300,
-    "height": 400,
-    "textSize": 14,
-    "textColor": "#FFFFFF",
-    "backgroundColor": "#000000"
-})
-```
-
 ### isPipActive - 判断悬浮窗是否打开
 
 判断悬浮窗是否当前打开。
@@ -75,104 +29,76 @@ def isPipActive() -> bool
 ```python
 from kuaijs import pip
 
-# 检查悬浮窗是否打开
-is_active = pip.isPipActive()
-if is_active:
+if pip.isPipActive():
     print("悬浮窗当前已打开")
-else:
-    print("悬浮窗当前未打开")
 ```
 
-### showLogWindow - 显示日志窗口
+### switchToLogMode - 切换到日志模式
 
-显示悬浮窗日志窗口。应用必须在前台才可调用。
+切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。
 
 ```python
-def showLogWindow() -> bool
+def switchToLogMode() -> bool
 ```
 
 **返回值：**
 
-| 类型   | 描述                              |
-| ------ | --------------------------------- |
-| `bool` | `True` 代表成功，`False` 代表失败 |
+| 类型   | 描述                  |
+| ------ | --------------------- |
+| `bool` | `True` 代表已提交请求 |
 
 **示例：**
 
 ```python
 from kuaijs import pip, utils
 
-# 将应用切入前台
 utils.takeMeToFront()
-
-# 显示悬浮窗
-success = pip.showLogWindow()
-if success:
-    print("悬浮窗显示成功")
-else:
-    print("悬浮窗显示失败，请检查权限设置")
+success = pip.switchToLogMode()
 ```
 
-### closeLogWindow - 关闭日志窗口
+### switchToKeepAliveMode - 切换到保活模式
 
-关闭悬浮窗日志窗口。应用必须在前台才可调用。
+切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。
 
 ```python
-def closeLogWindow() -> bool
+def switchToKeepAliveMode() -> bool
 ```
 
 **返回值：**
 
-| 类型   | 描述                              |
-| ------ | --------------------------------- |
-| `bool` | `True` 代表成功，`False` 代表失败 |
+| 类型   | 描述                  |
+| ------ | --------------------- |
+| `bool` | `True` 代表已提交请求 |
 
 **示例：**
 
 ```python
 from kuaijs import pip, utils
 
-# 将应用切入前台
 utils.takeMeToFront()
-
-# 关闭悬浮窗
-success = pip.closeLogWindow()
-if success:
-    print("悬浮窗关闭成功")
-else:
-    print("悬浮窗关闭失败")
+success = pip.switchToKeepAliveMode()
 ```
 
-### setPipCtrlScript - 设置脚本控制权限
+### switchToOffMode - 切换到关闭模式
 
-设置是否允许悬浮窗控制脚本的启停。当前 Video Call PiP 链路仅保存配置，不再提供播放/暂停按钮回调。
+切换到关闭模式并关闭悬浮窗。
 
 ```python
-def setPipCtrlScript(ctrl: bool) -> bool
+def switchToOffMode() -> bool
 ```
 
-**参数：**
-
-| 参数名 | 类型   | 是否必填 | 默认值 | 描述                                        |
-| ------ | ------ | -------- | ------ | ------------------------------------------- |
-| `ctrl` | `bool` | 是       | -      | `True` 代表允许控制，`False` 代表不允许控制 |
-
 **返回值：**
 
-| 类型   | 描述                              |
-| ------ | --------------------------------- |
-| `bool` | `True` 代表成功，`False` 代表失败 |
+| 类型   | 描述                  |
+| ------ | --------------------- |
+| `bool` | `True` 代表已提交请求 |
 
 **示例：**
 
 ```python
 from kuaijs import pip
 
-# 允许悬浮窗控制脚本
-ok1 = pip.setPipCtrlScript(True)
-
-# 禁止悬浮窗控制脚本
-ok2 = pip.setPipCtrlScript(False)
+success = pip.switchToOffMode()
 ```
 
 ## 完整使用示例
@@ -180,35 +106,16 @@ ok2 = pip.setPipCtrlScript(False)
 ```python
 from kuaijs import pip, utils
 
-# 将应用切入前台
 utils.takeMeToFront()
-
-# 1. 配置悬浮窗参数
-pip.setLogViewParams({
-    "width": 350,
-    "height": 500,
-    "textSize": 16,
-    "textColor": "#00FF00",      # 绿色文字
-    "backgroundColor": "#1A1A1A" # 深灰色背景
-})
-
-# 2. 保存悬浮窗控制脚本配置
-pip.setPipCtrlScript(True)
-
-# 3. 显示悬浮窗
-pip.showLogWindow()
+pip.switchToLogMode()
 ```
 
 ## 注意事项
 
-1. **前台限制**：所有悬浮窗操作都必须在应用前台状态下进行
+1. **前台限制**：首次切换到日志模式或保活模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换日志/保活模式
 2. **设备兼容性**：仅支持 iOS 15+ 且具备画中画功能的设备
-3. **尺寸限制**：`height` 支持最低 0.1pt，内部最高限制为 220pt；实际悬浮窗显示仍由 iOS Video Call PiP 决定
-4. **配置时机**：`setLogViewParams()` 可在显示前或显示后调用，显示后会同步更新当前内容尺寸
-5. **颜色格式**：颜色值必须使用十六进制格式（如：`#FFFFFF`）
-6. **尺寸适配**：iOS 系统会对画中画窗口的尺寸进行限制和自动调整，实际显示的画中画窗口大小可能与设置的 `width` 和 `height` 参数不完全一致
-7. **内容渲染**：画中画内容渲染会自动适配系统分配的实际窗口尺寸，而不是使用配置的尺寸参数
-8. **脚本控制**：Video Call PiP 链路不再提供播放/暂停按钮回调，`setPipCtrlScript(True)` 当前仅保存配置
+3. **系统限制**：悬浮窗位置和实际显示尺寸由 iOS 管理
+4. **识别标记**：日志窗口左上角默认包含识别标记，便于通过截图识别悬浮窗位置
 
 ## 故障排除
 
@@ -216,15 +123,4 @@ pip.showLogWindow()
 
 - 确认设备支持悬浮窗功能
 - 检查悬浮窗权限是否已开启
-- 确认参数配置是否正确（高度不低于 0.1pt）
-
-### 悬浮窗显示异常
-
-- 检查颜色值格式是否正确
-- 确认字体大小设置是否合理
-- 验证窗口尺寸是否在有效范围内
-
-### 脚本控制无效
-
-- 当前 Video Call PiP 链路不再提供播放/暂停按钮回调
-- `setPipCtrlScript(True)` 仅保存配置，不会直接驱动脚本启停
+- 确认应用当前在前台