ms-vite-plugin 1.1.1 → 1.1.3

package/docs/apipython/paddleocr.md

@@ -0,0 +1,211 @@
+# PaddleOCR 模块 (PaddleOCR)
+
+PaddleOCR 模块基于百度飞桨 PaddleOCR 技术，提供强大的光学字符识别（OCR）功能，支持中英文文本识别，可用于屏幕截图、图片文件等多种输入源的文字识别。
+
+## 功能概览
+
+- **模型管理**: PP-OCRv5 模型加载和资源管理
+- **多源识别**: 支持屏幕截图、图片文件、URL 等多种输入源
+- **区域识别**: 支持指定区域的精确文字识别
+- **结构化结果**: 提供详细的文本位置、置信度和方向信息
+- **资源控制**: 完整的模型生命周期管理
+
+## 类型定义
+
+### OCRResult
+
+识别结果的数据结构，包含完整的文本信息和位置数据。
+
+```python
+from typing import TypedDict, List
+
+class OCRResult(TypedDict):
+    text: str            # 识别的文本内容
+    confidence: float    # 识别置信度 (0-1)
+    x: int               # 文本区域左上角 x 坐标
+    y: int               # 文本区域左上角 y 坐标
+    ex: int              # 文本区域右下角 x 坐标
+    ey: int              # 文本区域右下角 y 坐标
+    width: int           # 文本区域宽度
+    height: int          # 文本区域高度
+    centerX: int         # 文本区域中心点 x 坐标
+    centerY: int         # 文本区域中心点 y 坐标
+    angle: float         # 文本区域角度 (-90 到 90 度)
+    orientation: int     # 文本区域方向 (0 横向，1 竖向)
+```
+
+## API 参考
+
+### 模型管理
+
+#### `loadV5` - 初始化 PP-OCRv5 模型
+
+初始化 PP-OCRv5 模型，这是使用 OCR 功能的前提。
+
+```python
+def loadV5(maxSideLen: int = 640) -> bool
+```
+
+**参数：**
+
+| 参数名       | 类型 | 是否必填 | 默认值 | 描述                             |
+| ------------ | ---- | -------- | ------ | -------------------------------- |
+| `maxSideLen` | int  | 否       | 640    | 输入图像的最大边长，默认值为 640 |
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| `bool` | 是否成功加载模型 |
+
+**示例：**
+
+```python
+from kuaijs import paddleocr
+
+# 使用默认参数加载模型
+loaded = paddleocr.loadV5()
+if loaded:
+    print("PP-OCRv5 模型加载成功")
+```
+
+### 文字识别
+
+#### `recognize` - 执行 OCR 文字识别
+
+执行 OCR 文字识别，支持多种输入源和指定识别区域。
+
+```python
+def recognize(
+    input: str,
+    x: int = 0,
+    y: int = 0,
+    ex: int = 0,
+    ey: int = 0,
+    confidenceThreshold: float = 0.6
+) -> List[OCRResult]
+```
+
+**参数：**
+
+| 参数名                | 类型  | 是否必填 | 默认值 | 描述                                                                                                                          |
+| --------------------- | ----- | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `input`               | str   | 是       | -      | 输入源，支持以下类型：<br>- `"screen"` - 当前屏幕截图<br>- 图片文件路径或 URL<br>- `imageId` - 图片 ID（通过 image 模块获取） |
+| `x`                   | int   | 否       | 0      | 识别区域左上角 x 坐标                                                                                                         |
+| `y`                   | int   | 否       | 0      | 识别区域左上角 y 坐标                                                                                                         |
+| `ex`                  | int   | 否       | 0      | 识别区域右下角 x 坐标                                                                                                         |
+| `ey`                  | int   | 否       | 0      | 识别区域右下角 y 坐标                                                                                                         |
+| `confidenceThreshold` | float | 否       | 0.6    | 置信度阈值，默认值为 0.6                                                                                                      |
+
+**返回值：**
+
+| 类型              | 描述                                                           |
+| ----------------- | -------------------------------------------------------------- |
+| `List[OCRResult]` | 识别结果数组，每个元素包含文本内容、位置信息和置信度等详细数据 |
+
+**示例：**
+
+```python
+from kuaijs import paddleocr
+
+# 首先加载模型
+if not paddleocr.loadV5():
+    print("模型加载失败")
+else:
+    # 识别整个屏幕
+    full_screen_results = paddleocr.recognize("screen", 0, 0, 0, 0)
+    print(f"识别到 {len(full_screen_results)} 个文本区域")
+    for r in full_screen_results:
+        print(f"文本: {r.text}, 置信度: {r.confidence}")
+
+    # 识别屏幕指定区域
+    region_results = paddleocr.recognize("screen", 100, 100, 500, 300)
+    if region_results:
+        top = region_results[0]
+        print(f"指定区域文本: {top.text}, 中心: ({top.centerX}, {top.centerY})")
+
+    # 识别图片文件
+    image_results = paddleocr.recognize("/path/to/image.png", 0, 0, 800, 600)
+    for r in image_results:
+        print(f"图片文字: {r.text}")
+
+    # 识别网络图片
+    url_results = paddleocr.recognize("https://example.com/image.jpg", 0, 0, 1000, 800)
+    print(f"网络图片识别结果数量: {len(url_results)}")
+```
+
+#### `findText` - 在识别结果中查找目标文本并返回对应子串坐标
+
+在 OCR 识别结果中查找指定文本，返回匹配文本的坐标和置信度等信息。
+
+```python
+def findText(
+    input: str,
+    targetTexts: List[str],
+    x: int = 0,
+    y: int = 0,
+    ex: int = 0,
+    ey: int = 0,
+    confidenceThreshold: float = 0.6
+) -> List[OCRResult]
+```
+
+**参数：**
+
+| 参数名                | 类型      | 是否必填 | 默认值 | 描述                                                                                                                          |
+| --------------------- | --------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `input`               | str       | 是       | -      | 输入源，支持以下类型：<br>- `"screen"` - 当前屏幕截图<br>- 图片文件路径或 URL<br>- `imageId` - 图片 ID（通过 image 模块获取） |
+| `targetTexts`         | List[str] | 是       | -      | 目标文本数组，例如 `["登录", "确定"]`                                                                                         |
+| `x`                   | int       | 否       | 0      | 查找区域左上角 x 坐标                                                                                                         |
+| `y`                   | int       | 否       | 0      | 查找区域左上角 y 坐标                                                                                                         |
+| `ex`                  | int       | 否       | 0      | 查找区域右下角 x 坐标                                                                                                         |
+| `ey`                  | int       | 否       | 0      | 查找区域右下角 y 坐标                                                                                                         |
+| `confidenceThreshold` | float     | 否       | 0.6    | 置信度阈值，默认值为 0.6                                                                                                      |
+
+**返回值：**
+
+| 类型              | 描述                                                                                                              |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `List[OCRResult]` | 匹配结果数组。每个元素为命中的文本片段坐标信息，`text` 字段为命中的目标文本，其他字段包含位置、方向和置信度等信息 |
+
+**示例：**
+
+```python
+from kuaijs import paddleocr
+
+# 首先加载模型
+if not paddleocr.loadV5():
+    print("模型加载失败")
+else:
+    # 在整个屏幕中查找目标文本
+    hit_results = paddleocr.findText("screen", ["登录", "确定"], 0, 0, 0, 0, 0.6)
+    if hit_results:
+        for i, r in enumerate(hit_results, 1):
+            print(f"命中{i}: {r.text}, 中心点=({r.centerX}, {r.centerY}), 置信度={r.confidence}")
+    else:
+        print("未命中目标文本")
+
+    # 在指定区域查找目标文本
+    region_hits = paddleocr.findText("screen", ["下一步"], 100, 100, 500, 400)
+    print(f"区域命中数量: {len(region_hits)}")
+```
+
+### 资源管理
+
+#### `free` - 释放 OCR 模型占用的内存资源
+
+释放 OCR 模型占用的内存资源。
+
+```python
+def free() -> None
+```
+
+**示例：**
+
+```python
+from kuaijs import paddleocr
+
+# 使用完毕后释放资源
+paddleocr.free()
+print("OCR 模型资源已释放")
+```

package/docs/apipython/pip.md

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