ms-vite-plugin 1.1.1 → 1.1.3

package/docs/apicn/paddleocr.md

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

package/docs/apicn/pip.md

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