ms-vite-plugin 1.4.7 → 1.4.9

package/docs/api/pip.md

@@ -1,81 +1,15 @@
 # 悬浮窗模块 (PIP)
 
-悬浮窗模块提供了画中画（Picture in Picture）功能，允许在应用中显示悬浮的日志窗口，支持自定义样式和控制脚本启停。
+悬浮窗模块提供画中画（Picture in Picture）日志窗口能力。
 
 ## 功能特性
 
-- 🖼️ **悬浮窗显示** - 支持在屏幕上显示悬浮的日志窗口
-- 🎨 **自定义样式** - 可配置窗口大小、字体、颜色等
-- 🎮 **脚本控制** - 支持通过悬浮窗控制脚本的启停
-
-## 接口定义
-
-### LogViewParams - 悬浮窗参数配置
-
-```typescript
-interface LogViewParams {
-  /**
-   * 悬浮窗宽度，不能小于 100
-   */
-  width: number;
-  /**
-   * 悬浮窗高度，不能小于 100
-   */
-  height: number;
-  /**
-   * 日志的字体大小
-   */
-  textSize: number;
-  /**
-   * 日志的文字颜色，格式如 #FFFFFF
-   */
-  textColor: string;
-  /**
-   * 日志的背景颜色，格式如 #000000
-   */
-  backgroundColor: string;
-}
-```
-
-**参数说明：**
-
-| 参数              | 类型   | 是否必填 | 默认值 | 描述                                    |
-| ----------------- | ------ | -------- | ------ | --------------------------------------- |
-| `width`           | number | 是       |        | 悬浮窗宽度（像素），最小值为 100        |
-| `height`          | number | 是       |        | 悬浮窗高度（像素），最小值为 100        |
-| `textSize`        | number | 是       |        | 日志文字大小（像素）                    |
-| `textColor`       | string | 是       |        | 文字颜色，十六进制格式（如：`#FFFFFF`） |
-| `backgroundColor` | string | 是       |        | 背景颜色，十六进制格式（如：`#000000`） |
+- **模式切换**：切换日志、保活和关闭三种悬浮窗模式
+- **状态查询**：判断悬浮窗是否正在显示
+- **识别标记**：日志窗口左上角默认显示高对比标记，可用于截图识别悬浮窗位置
 
 ## API 方法
 
-### setLogViewParams - 设置悬浮窗显示参数
-
-```typescript
-function setLogViewParams(params: LogViewParams): void;
-```
-
-设置悬浮窗日志窗口的显示参数，必须在显示日志窗口之前调用才会生效。
-
-**参数：**
-
-| 参数名   | 类型          | 是否必填 | 默认值 | 描述                   |
-| -------- | ------------- | -------- | ------ | ---------------------- |
-| `params` | LogViewParams | 是       |        | 包含显示参数的配置对象 |
-
-**示例：**
-
-```typescript
-// 配置悬浮窗参数
-pip.setLogViewParams({
-  width: 300,
-  height: 400,
-  textSize: 14,
-  textColor: "#FFFFFF",
-  backgroundColor: "#000000",
-});
-```
-
 ### isPipActive - 判断悬浮窗是否打开
 
 ```typescript
@@ -93,133 +27,87 @@ function isPipActive(): boolean;
 **示例：**
 
 ```typescript
-// 检查悬浮窗是否打开
 const isActive = pip.isPipActive();
 if (isActive) {
   logi("悬浮窗当前已打开");
-} else {
-  logi("悬浮窗当前未打开");
 }
 ```
 
-### showLogWindow - 显示日志窗口
+### switchToLogMode - 切换到日志模式
 
 ```typescript
-function showLogWindow(): boolean;
+function switchToLogMode(): boolean;
 ```
 
-显示悬浮窗日志窗口。应用必须在前台才可调用
+切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。
 
 **返回值：**
 
-| 类型      | 描述                              |
-| --------- | --------------------------------- |
-| `boolean` | `true` 代表成功，`false` 代表失败 |
+| 类型      | 描述                   |
+| --------- | ---------------------- |
+| `boolean` | `true` 代表已提交请求 |
 
 **示例：**
 
 ```typescript
-// 将应用切入前台
 takeMeToFront();
-// 显示悬浮窗
-const success = pip.showLogWindow();
-if (success) {
-  logi("悬浮窗显示成功");
-} else {
-  logi("悬浮窗显示失败，请检查权限设置");
-}
+const success = pip.switchToLogMode();
 ```
 
-### closeLogWindow - 关闭日志窗口
+### switchToKeepAliveMode - 切换到保活模式
 
 ```typescript
-function closeLogWindow(): boolean;
+function switchToKeepAliveMode(): boolean;
 ```
 
-关闭悬浮窗日志窗口。应用必须在前台才可调用。
+切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。
 
 **返回值：**
 
-| 类型      | 描述                              |
-| --------- | --------------------------------- |
-| `boolean` | `true` 代表成功，`false` 代表失败 |
+| 类型      | 描述                   |
+| --------- | ---------------------- |
+| `boolean` | `true` 代表已提交请求 |
 
 **示例：**
 
 ```typescript
-// 将应用切入前台
 takeMeToFront();
-// 关闭悬浮窗
-const success = pip.closeLogWindow();
-if (success) {
-  logi("悬浮窗关闭成功");
-} else {
-  logi("悬浮窗关闭失败");
-}
+const success = pip.switchToKeepAliveMode();
 ```
 
-### setPipCtrlScript - 设置脚本控制权限
+### switchToOffMode - 切换到关闭模式
 
 ```typescript
-function setPipCtrlScript(ctrl: boolean): boolean;
+function switchToOffMode(): boolean;
 ```
 
-设置是否允许悬浮窗控制脚本的启停。
-
-**参数：**
-
-| 参数名 | 类型    | 是否必填 | 默认值 | 描述                                        |
-| ------ | ------- | -------- | ------ | ------------------------------------------- |
-| `ctrl` | boolean | 是       |        | `true` 代表允许控制，`false` 代表不允许控制 |
-
-**示例：**
+切换到关闭模式并关闭悬浮窗。
 
 **返回值：**
 
-| 类型      | 描述                              |
-| --------- | --------------------------------- |
-| `boolean` | `true` 代表成功，`false` 代表失败 |
+| 类型      | 描述                   |
+| --------- | ---------------------- |
+| `boolean` | `true` 代表已提交请求 |
 
 **示例：**
 
 ```typescript
-// 允许悬浮窗控制脚本
-const ok1 = pip.setPipCtrlScript(true);
-// 禁止悬浮窗控制脚本
-const ok2 = pip.setPipCtrlScript(false);
+const success = pip.switchToOffMode();
 ```
 
 ## 完整使用示例
 
 ```typescript
-// 将应用切入前台
 takeMeToFront();
-// 1. 配置悬浮窗参数
-pip.setLogViewParams({
-  width: 350,
-  height: 500,
-  textSize: 16,
-  textColor: "#00FF00", // 绿色文字
-  backgroundColor: "#1A1A1A", // 深灰色背景
-});
-
-// 2. 允许悬浮窗控制脚本
-pip.setPipCtrlScript(true);
-
-// 3. 显示悬浮窗
-const showResult = pip.showLogWindow();
+pip.switchToLogMode();
 ```
 
 ## 注意事项
 
-1. **前台限制**：所有悬浮窗操作都必须在应用前台状态下进行
+1. **前台限制**：首次切换到日志模式或保活模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换日志/保活模式
 2. **设备兼容性**：仅支持 iOS 15+ 且具备画中画功能的设备
-3. **参数限制**：悬浮窗的宽度和高度都不能小于 100 像素
-4. **配置时机**：`setLogViewParams()` 必须在 `showLogWindow()` 之前调用
-5. **颜色格式**：颜色值必须使用十六进制格式（如：`#FFFFFF`）
-6. **尺寸适配**：iOS 系统会对画中画窗口的尺寸进行限制和自动调整，实际显示的画中画窗口大小可能与设置的 `width` 和 `height` 参数不完全一致
-7. **内容渲染**：画中画内容渲染会自动适配系统分配的实际窗口尺寸，而不是使用配置的尺寸参数
-8. **脚本控制**：如果已调用 `setPipCtrlScript(true)`，则可以通过悬浮窗控制脚本的启停
+3. **系统限制**：悬浮窗位置和实际显示尺寸由 iOS 管理
+4. **识别标记**：日志窗口左上角默认包含识别标记，便于通过截图识别悬浮窗位置
 
 ## 故障排除
 
@@ -227,16 +115,4 @@ const showResult = pip.showLogWindow();
 
 - 确认设备支持悬浮窗功能
 - 检查悬浮窗权限是否已开启
-- 确认参数配置是否正确（宽高不小于 100）
-
-### 悬浮窗显示异常
-
-- 检查颜色值格式是否正确
-- 确认字体大小设置是否合理
-- 验证窗口尺寸是否在有效范围内
-
-### 脚本控制无效
-
-- 确认已调用 `setPipCtrlScript(true)`
-- 检查悬浮窗是否正常显示
-- 验证脚本运行状态是否正常
+- 确认应用当前在前台

package/docs/apicn/pip.md

@@ -1,81 +1,15 @@
 # 悬浮窗模块 ($悬浮窗)
 
-悬浮窗模块提供了画中画（Picture in Picture）功能，允许在应用中显示悬浮的日志窗口，支持自定义样式和控制脚本启停。
+悬浮窗模块提供画中画（Picture in Picture）日志窗口能力。
 
 ## 功能特性
 
-- 🖼️ **悬浮窗显示** - 支持在屏幕上显示悬浮的日志窗口
-- 🎨 **自定义样式** - 可配置窗口大小、字体、颜色等
-- 🎮 **脚本控制** - 支持通过悬浮窗控制脚本的启停
-
-## 接口定义
-
-### 日志窗口参数
-
-```typescript
-interface 日志窗口参数 {
-  /**
-   * 悬浮窗宽度，不能小于 100
-   */
-  width: 数字;
-  /**
-   * 悬浮窗高度，不能小于 100
-   */
-  height: 数字;
-  /**
-   * 日志的字体大小
-   */
-  textSize: 数字;
-  /**
-   * 日志的文字颜色，格式如 #FFFFFF
-   */
-  textColor: 字符串;
-  /**
-   * 日志的背景颜色，格式如 #000000
-   */
-  backgroundColor: 字符串;
-}
-```
-
-**参数说明：**
-
-| 参数              | 类型   | 是否必填 | 默认值 | 描述                                    |
-| ----------------- | ------ | -------- | ------ | --------------------------------------- |
-| `width`           | 数字   | 是       |        | 悬浮窗宽度（像素），最小值为 100        |
-| `height`          | 数字   | 是       |        | 悬浮窗高度（像素），最小值为 100        |
-| `textSize`        | 数字   | 是       |        | 日志文字大小（像素）                    |
-| `textColor`       | 字符串 | 是       |        | 文字颜色，十六进制格式（如：`#FFFFFF`） |
-| `backgroundColor` | 字符串 | 是       |        | 背景颜色，十六进制格式（如：`#000000`） |
+- **模式切换**：切换日志、保活和关闭三种悬浮窗模式
+- **状态查询**：判断悬浮窗是否正在显示
+- **识别标记**：日志窗口左上角默认显示高对比标记，可用于截图识别悬浮窗位置
 
 ## API 方法
 
-### 设置日志视图参数
-
-```typescript
-function 设置日志视图参数(参数: 日志窗口参数): 无返回值;
-```
-
-设置悬浮窗日志窗口的显示参数，必须在显示日志窗口之前调用才会生效。
-
-**参数：**
-
-| 参数名 | 类型         | 是否必填 | 默认值 | 描述                   |
-| ------ | ------------ | -------- | ------ | ---------------------- |
-| `参数` | 日志窗口参数 | 是       |        | 包含显示参数的配置对象 |
-
-**示例：**
-
-```typescript
-// 配置悬浮窗参数
-$悬浮窗.设置日志视图参数({
-  width: 300,
-  height: 400,
-  textSize: 14,
-  textColor: "#FFFFFF",
-  backgroundColor: "#000000",
-});
-```
-
 ### 是否显示 - 判断悬浮窗是否打开
 
 ```typescript
@@ -93,133 +27,87 @@ function 是否显示(): 布尔值;
 **示例：**
 
 ```typescript
-// 检查悬浮窗是否打开
 const 是否显示 = $悬浮窗.是否显示();
 if (是否显示) {
   $打印信息日志("悬浮窗当前已打开");
-} else {
-  $打印信息日志("悬浮窗当前未打开");
 }
 ```
 
-### 显示日志窗口
+### 切换到日志模式
 
 ```typescript
-function 显示日志窗口(): 布尔值;
+function 切换到日志模式(): 布尔值;
 ```
 
-显示悬浮窗日志窗口。应用必须在前台才可调用
+切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。
 
 **返回值：**
 
-| 类型     | 描述                              |
-| -------- | --------------------------------- |
-| `布尔值` | `true` 代表成功，`false` 代表失败 |
+| 类型     | 描述                   |
+| -------- | ---------------------- |
+| `布尔值` | `true` 代表已提交请求 |
 
 **示例：**
 
 ```typescript
-// 将应用切入前台
 $APP切入前台();
-// 显示悬浮窗
-const 是否成功 = $悬浮窗.显示日志窗口();
-if (是否成功) {
-  $打印信息日志("悬浮窗显示成功");
-} else {
-  $打印信息日志("悬浮窗显示失败，请检查权限设置");
-}
+const 是否成功 = $悬浮窗.切换到日志模式();
 ```
 
-### 关闭日志窗口
+### 切换到保活模式
 
 ```typescript
-function 关闭日志窗口(): 布尔值;
+function 切换到保活模式(): 布尔值;
 ```
 
-关闭悬浮窗日志窗口。应用必须在前台才可调用。
+切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。
 
 **返回值：**
 
-| 类型     | 描述                              |
-| -------- | --------------------------------- |
-| `布尔值` | `true` 代表成功，`false` 代表失败 |
+| 类型     | 描述                   |
+| -------- | ---------------------- |
+| `布尔值` | `true` 代表已提交请求 |
 
 **示例：**
 
 ```typescript
-// 将应用切入前台
 $APP切入前台();
-// 关闭悬浮窗
-const 是否成功 = $悬浮窗.关闭日志窗口();
-if (是否成功) {
-  $打印信息日志("悬浮窗关闭成功");
-} else {
-  $打印信息日志("悬浮窗关闭失败");
-}
+const 是否成功 = $悬浮窗.切换到保活模式();
 ```
 
-### 设置是否允许控制脚本启停
+### 切换到关闭模式
 
 ```typescript
-function 设置是否允许控制脚本启停(是否允许: 布尔值): 布尔值;
+function 切换到关闭模式(): 布尔值;
 ```
 
-设置是否允许悬浮窗控制脚本的启停。
-
-**参数：**
-
-| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                        |
-| ---------- | ------ | -------- | ------ | ------------------------------------------- |
-| `是否允许` | 布尔值 | 是       |        | `true` 代表允许控制，`false` 代表不允许控制 |
-
-**示例：**
+切换到关闭模式并关闭悬浮窗。
 
 **返回值：**
 
-| 类型     | 描述                              |
-| -------- | --------------------------------- |
-| `布尔值` | `true` 代表成功，`false` 代表失败 |
+| 类型     | 描述                   |
+| -------- | ---------------------- |
+| `布尔值` | `true` 代表已提交请求 |
 
 **示例：**
 
 ```typescript
-// 允许悬浮窗控制脚本
-const 是否成功1 = $悬浮窗.设置是否允许控制脚本启停(true);
-// 禁止悬浮窗控制脚本
-const 是否成功2 = $悬浮窗.设置是否允许控制脚本启停(false);
+const 是否成功 = $悬浮窗.切换到关闭模式();
 ```
 
 ## 完整使用示例
 
 ```typescript
-// 将应用切入前台
 $APP切入前台();
-// 1. 配置悬浮窗参数
-$悬浮窗.设置日志视图参数({
-  width: 350,
-  height: 500,
-  textSize: 16,
-  textColor: "#00FF00", // 绿色文字
-  backgroundColor: "#1A1A1A", // 深灰色背景
-});
-
-// 2. 允许悬浮窗控制脚本
-$悬浮窗.设置是否允许控制脚本启停(true);
-
-// 3. 显示悬浮窗
-const showResult = $悬浮窗.显示日志窗口();
+$悬浮窗.切换到日志模式();
 ```
 
 ## 注意事项
 
-1. **前台限制**：所有悬浮窗操作都必须在应用前台状态下进行
+1. **前台限制**：首次切换到日志模式或保活模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换日志/保活模式
 2. **设备兼容性**：仅支持 iOS 15+ 且具备画中画功能的设备
-3. **参数限制**：悬浮窗的宽度和高度都不能小于 100 像素
-4. **配置时机**：`设置日志视图参数()` 必须在 `显示日志窗口()` 之前调用
-5. **颜色格式**：颜色值必须使用十六进制格式（如：`#FFFFFF`）
-6. **尺寸适配**：iOS 系统会对画中画窗口的尺寸进行限制和自动调整，实际显示的画中画窗口大小可能与设置的 `width` 和 `height` 参数不完全一致
-7. **内容渲染**：画中画内容渲染会自动适配系统分配的实际窗口尺寸，而不是使用配置的尺寸参数
-8. **脚本控制**：如果已调用 `设置是否允许脚本控制(true)`，则可以通过悬浮窗控制脚本的启停
+3. **系统限制**：悬浮窗位置和实际显示尺寸由 iOS 管理
+4. **识别标记**：日志窗口左上角默认包含识别标记，便于通过截图识别悬浮窗位置
 
 ## 故障排除
 
@@ -227,16 +115,4 @@ const showResult = $悬浮窗.显示日志窗口();
 
 - 确认设备支持悬浮窗功能
 - 检查悬浮窗权限是否已开启
-- 确认参数配置是否正确（宽高不小于 100）
-
-### 悬浮窗显示异常
-
-- 检查颜色值格式是否正确
-- 确认字体大小设置是否合理
-- 验证窗口尺寸是否在有效范围内
-
-### 脚本控制无效
-
-- 确认已调用 `设置是否允许脚本控制(true)`
-- 检查悬浮窗是否正常显示
-- 验证脚本运行状态是否正常
+- 确认应用当前在前台