ms-vite-plugin 1.1.2 → 1.1.3

package/docs/api/paddleocr.md

@@ -0,0 +1,246 @@
+# PaddleOCR 模块 (PaddleOCR)
+
+PaddleOCR 模块基于百度飞桨 PaddleOCR 技术，提供强大的光学字符识别（OCR）功能，支持中英文文本识别，可用于屏幕截图、图片文件等多种输入源的文字识别。
+
+## 功能概览
+
+- **模型管理**: PP-OCRv5 模型加载和资源管理
+- **多源识别**: 支持屏幕截图、图片文件、URL 等多种输入源
+- **区域识别**: 支持指定区域的精确文字识别
+- **结构化结果**: 提供详细的文本位置、置信度和方向信息
+- **资源控制**: 完整的模型生命周期管理
+
+## 数据类型
+
+### OCRResult 接口
+
+识别结果的数据结构，包含完整的文本信息和位置数据：
+
+```typescript
+interface OCRResult {
+  /** 识别的文本内容 */
+  text: string;
+  /** 识别置信度 (0-1) */
+  confidence: number;
+  /** 文本区域左上角 x 坐标 */
+  x: number;
+  /** 文本区域左上角 y 坐标 */
+  y: number;
+  /** 文本区域右下角 x 坐标 */
+  ex: number;
+  /** 文本区域右下角 y 坐标 */
+  ey: number;
+  /** 文本区域宽度 */
+  width: number;
+  /** 文本区域高度 */
+  height: number;
+  /** 文本区域中心点 x 坐标 */
+  centerX: number;
+  /** 文本区域中心点 y 坐标 */
+  centerY: number;
+  /** 文本区域角度 */
+  angle: number;
+  /** 文本区域方向 0 横向 1 竖向 */
+  orientation: number;
+}
+```
+
+**数据结构说明：**
+
+| 字段               | 类型   | 描述                                                  |
+| ------------------ | ------ | ----------------------------------------------------- |
+| `text`             | string | 识别出的文本内容                                      |
+| `confidence`       | number | 识别置信度，范围 0-1，值越高表示识别越准确            |
+| `x, y, ex, ey`     | number | 文本区域的坐标，分别为左上角和右下角的 x、y 坐标      |
+| `width, height`    | number | 文本区域的宽度和高度                                  |
+| `centerX, centerY` | number | 文本区域的中心点坐标                                  |
+| `angle`            | number | 文本区域的角度，范围 -90 到 90 度，正值表示逆时针旋转 |
+| `orientation`      | number | 文本区域的方向，0 表示横向，1 表示竖向                |
+
+## API 参考
+
+### 模型管理
+
+#### loadV5 - 初始化 PP-OCRv5 模型，这是使用 OCR 功能的前提。
+
+```typescript
+function loadV5(maxSideLen?: number): boolean;
+```
+
+**参数:**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述                             |
+| ------------ | ------ | -------- | ------ | -------------------------------- |
+| `maxSideLen` | number | 否       | 640    | 输入图像的最大边长，默认值为 640 |
+
+**返回值:**
+
+| 类型    | 描述             |
+| ------- | ---------------- |
+| boolean | 是否成功加载模型 |
+
+**示例:**
+
+```javascript
+// 使用默认参数加载模型
+const loaded = paddleOcr.loadV5();
+if (loaded) {
+  logi("PP-OCRv5 模型加载成功");
+}
+```
+
+### 文字识别
+
+#### recognize - 执行 OCR 文字识别，支持多种输入源和指定识别区域。
+
+```typescript
+function recognize(
+  input: string,
+  x?: number,
+  y?: number,
+  ex?: number,
+  ey?: number,
+  confidenceThreshold?: number,
+): OCRResult[];
+```
+
+**参数:**
+
+| 参数名                | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                     |
+| --------------------- | ------ | -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `input`               | string | 是       |        | 输入源，支持以下类型：<br>- `"screen"` - 当前屏幕截图<br>- `string` - 图片文件路径或 URL<br>- `imageId` - 图片 ID（通过 image 模块获取） |
+| `x`                   | number | 否       | 0      | 识别区域左上角 x 坐标                                                                                                                    |
+| `y`                   | number | 否       | 0      | 识别区域左上角 y 坐标                                                                                                                    |
+| `ex`                  | number | 否       | 0      | 识别区域右下角 x 坐标                                                                                                                    |
+| `ey`                  | number | 否       | 0      | 识别区域右下角 y 坐标                                                                                                                    |
+| `confidenceThreshold` | number | 否       | 0.6    | 置信度阈值，默认值为 0.6                                                                                                                 |
+
+**返回值:**
+
+| 类型          | 描述                                                                              |
+| ------------- | --------------------------------------------------------------------------------- |
+| `OCRResult[]` | 识别结果数组，每个元素为 OCRResult 对象，包含文本内容、位置信息和置信度等详细数据 |
+
+**示例:**
+
+```javascript
+// 首先加载模型
+if (!paddleOcr.loadV5()) {
+  logi("模型加载失败");
+  return;
+}
+
+// 识别整个屏幕
+const fullScreenResults = paddleOcr.recognize("screen", 0, 0, 0, 0);
+logi(`识别到 ${fullScreenResults.length} 个文本区域`);
+fullScreenResults.forEach((result, index) => {
+  logi(`文本 ${index + 1}: ${JSON.stringify(result)}`);
+});
+
+// 识别屏幕指定区域
+const regionResults = paddleOcr.recognize("screen", 100, 100, 500, 300);
+logi(`指定区域识别结果: ${JSON.stringify(regionResults)}`);
+
+// 识别图片文件
+const imageResults = paddleOcr.recognize("/path/to/image.png", 0, 0, 800, 600);
+if (imageResults.length > 0) {
+  logi("图片文字识别成功");
+  imageResults.forEach((result) => {
+    logi(`识别文字: ${JSON.stringify(result)}`);
+  });
+} else {
+  logi("图片中未识别到文字");
+}
+
+// 识别网络图片
+const urlResults = paddleOcr.recognize(
+  "https://example.com/image.jpg",
+  0,
+  0,
+  1000,
+  800,
+);
+logi(`网络图片识别结果: ${JSON.stringify(urlResults)}`);
+```
+
+#### findText - 在识别结果中查找目标文本并返回对应子串坐标。
+
+```typescript
+function findText(
+  input: string,
+  targetTexts: string[],
+  x?: number,
+  y?: number,
+  ex?: number,
+  ey?: number,
+  confidenceThreshold?: number,
+): OCRResult[];
+```
+
+**参数:**
+
+| 参数名                | 类型     | 是否必填 | 默认值 | 描述                                                                                                                                     |
+| --------------------- | -------- | -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `input`               | string   | 是       |        | 输入源，支持以下类型：<br>- `"screen"` - 当前屏幕截图<br>- `string` - 图片文件路径或 URL<br>- `imageId` - 图片 ID（通过 image 模块获取） |
+| `targetTexts`         | string[] | 是       |        | 目标文本数组，例如 `["你好", "确定"]`                                                                                                    |
+| `x`                   | number   | 否       | 0      | 查找区域左上角 x 坐标                                                                                                                    |
+| `y`                   | number   | 否       | 0      | 查找区域左上角 y 坐标                                                                                                                    |
+| `ex`                  | number   | 否       | 0      | 查找区域右下角 x 坐标                                                                                                                    |
+| `ey`                  | number   | 否       | 0      | 查找区域右下角 y 坐标                                                                                                                    |
+| `confidenceThreshold` | number   | 否       | 0.6    | 置信度阈值，默认值为 0.6                                                                                                                 |
+
+**返回值:**
+
+| 类型          | 描述                                                                                                        |
+| ------------- | ----------------------------------------------------------------------------------------------------------- |
+| `OCRResult[]` | 匹配结果数组。每个元素为命中的文本片段坐标信息，`text` 字段为命中的目标文本，其他字段包含位置和置信度等信息 |
+
+**示例:**
+
+```javascript
+// 首先加载模型
+if (!paddleOcr.loadV5()) {
+  logi("模型加载失败");
+  return;
+}
+
+// 在整个屏幕中查找目标文本
+const hitResults = paddleOcr.findText(
+  "screen",
+  ["登录", "确定"],
+  0,
+  0,
+  0,
+  0,
+  0.6,
+);
+if (hitResults.length > 0) {
+  hitResults.forEach((item, index) => {
+    logi(
+      `命中 ${index + 1}: ${item.text}, 中心点: (${item.centerX}, ${item.centerY})`,
+    );
+  });
+} else {
+  logi("未命中目标文本");
+}
+
+// 在指定区域查找目标文本
+const regionHits = paddleOcr.findText("screen", ["下一步"], 100, 100, 500, 400);
+logi(`区域命中数量: ${regionHits.length}`);
+```
+
+### 资源管理
+
+#### free - 释放 OCR 模型占用的内存资源。
+
+```typescript
+function free(): void;
+```
+
+**示例:**
+
+```javascript
+// 使用完毕后释放资源
+paddleOcr.free();
+logi("OCR 模型资源已释放");
+```

package/docs/api/pip.md

@@ -0,0 +1,242 @@
+# 悬浮窗模块 (PIP)
+
+悬浮窗模块提供了画中画（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
+function isPipActive(): boolean;
+```
+
+判断悬浮窗是否当前打开。
+
+**返回值：**
+
+| 类型      | 描述                                          |
+| --------- | --------------------------------------------- |
+| `boolean` | `true` 代表开启了悬浮窗，`false` 代表没有开启 |
+
+**示例：**
+
+```typescript
+// 检查悬浮窗是否打开
+const isActive = pip.isPipActive();
+if (isActive) {
+  logi("悬浮窗当前已打开");
+} else {
+  logi("悬浮窗当前未打开");
+}
+```
+
+### showLogWindow - 显示日志窗口
+
+```typescript
+function showLogWindow(): boolean;
+```
+
+显示悬浮窗日志窗口。应用必须在前台才可调用
+
+**返回值：**
+
+| 类型      | 描述                              |
+| --------- | --------------------------------- |
+| `boolean` | `true` 代表成功，`false` 代表失败 |
+
+**示例：**
+
+```typescript
+// 将应用切入前台
+takeMeToFront();
+// 显示悬浮窗
+const success = pip.showLogWindow();
+if (success) {
+  logi("悬浮窗显示成功");
+} else {
+  logi("悬浮窗显示失败，请检查权限设置");
+}
+```
+
+### closeLogWindow - 关闭日志窗口
+
+```typescript
+function closeLogWindow(): boolean;
+```
+
+关闭悬浮窗日志窗口。应用必须在前台才可调用。
+
+**返回值：**
+
+| 类型      | 描述                              |
+| --------- | --------------------------------- |
+| `boolean` | `true` 代表成功，`false` 代表失败 |
+
+**示例：**
+
+```typescript
+// 将应用切入前台
+takeMeToFront();
+// 关闭悬浮窗
+const success = pip.closeLogWindow();
+if (success) {
+  logi("悬浮窗关闭成功");
+} else {
+  logi("悬浮窗关闭失败");
+}
+```
+
+### setPipCtrlScript - 设置脚本控制权限
+
+```typescript
+function setPipCtrlScript(ctrl: boolean): boolean;
+```
+
+设置是否允许悬浮窗控制脚本的启停。
+
+**参数：**
+
+| 参数名 | 类型    | 是否必填 | 默认值 | 描述                                        |
+| ------ | ------- | -------- | ------ | ------------------------------------------- |
+| `ctrl` | boolean | 是       |        | `true` 代表允许控制，`false` 代表不允许控制 |
+
+**示例：**
+
+**返回值：**
+
+| 类型      | 描述                              |
+| --------- | --------------------------------- |
+| `boolean` | `true` 代表成功，`false` 代表失败 |
+
+**示例：**
+
+```typescript
+// 允许悬浮窗控制脚本
+const ok1 = pip.setPipCtrlScript(true);
+// 禁止悬浮窗控制脚本
+const ok2 = pip.setPipCtrlScript(false);
+```
+
+## 完整使用示例
+
+```typescript
+// 将应用切入前台
+takeMeToFront();
+// 1. 配置悬浮窗参数
+pip.setLogViewParams({
+  width: 350,
+  height: 500,
+  textSize: 16,
+  textColor: "#00FF00", // 绿色文字
+  backgroundColor: "#1A1A1A", // 深灰色背景
+});
+
+// 2. 允许悬浮窗控制脚本
+pip.setPipCtrlScript(true);
+
+// 3. 显示悬浮窗
+const showResult = pip.showLogWindow();
+```
+
+## 注意事项
+
+1. **前台限制**：所有悬浮窗操作都必须在应用前台状态下进行
+2. **设备兼容性**：仅支持 iOS 15+ 且具备画中画功能的设备
+3. **参数限制**：悬浮窗的宽度和高度都不能小于 100 像素
+4. **配置时机**：`setLogViewParams()` 必须在 `showLogWindow()` 之前调用
+5. **颜色格式**：颜色值必须使用十六进制格式（如：`#FFFFFF`）
+6. **尺寸适配**：iOS 系统会对画中画窗口的尺寸进行限制和自动调整，实际显示的画中画窗口大小可能与设置的 `width` 和 `height` 参数不完全一致
+7. **内容渲染**：画中画内容渲染会自动适配系统分配的实际窗口尺寸，而不是使用配置的尺寸参数
+8. **脚本控制**：如果已调用 `setPipCtrlScript(true)`，则可以通过悬浮窗控制脚本的启停
+
+## 故障排除
+
+### 悬浮窗无法显示
+
+- 确认设备支持悬浮窗功能
+- 检查悬浮窗权限是否已开启
+- 确认参数配置是否正确（宽高不小于 100）
+
+### 悬浮窗显示异常
+
+- 检查颜色值格式是否正确
+- 确认字体大小设置是否合理
+- 验证窗口尺寸是否在有效范围内
+
+### 脚本控制无效
+
+- 确认已调用 `setPipCtrlScript(true)`
+- 检查悬浮窗是否正常显示
+- 验证脚本运行状态是否正常