ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/paddleocr.md

@@ -0,0 +1,324 @@
+# PaddleOCR 模块 (PaddleOCR)
+
+PaddleOCR 模块基于百度飞桨 PaddleOCR 技术，提供强大的光学字符识别（OCR）功能，支持中英文文本识别，可用于屏幕截图、图片文件等多种输入源的文字识别。
+
+## 功能概览
+
+- **自动加载**: 识别方法会自动加载所需模型，无需先手动加载
+- **PP-OCRv5**: 可通过 `loadV5` 手动加载 PP-OCRv5 模型
+- **多源识别**: 支持屏幕截图、图片文件、URL 等多种输入源
+- **区域识别**: 支持指定区域的精确文字识别
+- **结构化结果**: 提供详细的文本位置、置信度和方向信息
+- **资源释放**: 可在需要时释放 OCR 资源
+
+## 数据类型
+
+### OCRResult 接口
+
+识别结果的数据结构，包含完整的文本信息和位置数据：
+
+```lua
+---@class OCRResult
+---@field text string 识别的文本内容
+---@field confidence number 识别置信度 (0-1)
+---@field x number 文本区域左上角 x 坐标
+---@field y number 文本区域左上角 y 坐标
+---@field ex number 文本区域右下角 x 坐标
+---@field ey number 文本区域右下角 y 坐标
+---@field width number 文本区域宽度
+---@field height number 文本区域高度
+---@field centerX number 文本区域中心点 x 坐标
+---@field centerY number 文本区域中心点 y 坐标
+---@field angle number 文本区域角度
+---@field orientation number 文本区域方向 0 横向 1 竖向
+```
+
+**数据结构说明：**
+
+| 字段               | 类型   | 描述                                                  |
+| ------------------ | ------ | ----------------------------------------------------- |
+| `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 模型。
+
+识别方法默认自动加载模型。只有需要切换到 PP-OCRv5 或指定 GPU 参数时才调用 `loadV5`。PaddleOCR 同一时间只保留一个 active 模型，`loadV5` 加载成功后会替换已加载模型。
+
+```lua
+---@param maxSideLen number?
+---@param useGpu boolean?
+---@return boolean
+function loadV5(maxSideLen, useGpu) end
+```
+
+**参数:**
+
+| 参数名       | 类型    | 是否必填 | 默认值 | 描述                         |
+| ------------ | ------- | -------- | ------ | ---------------------------- |
+| `maxSideLen` | number  | 否       | 640    | 检测阶段输入最大边长         |
+| `useGpu`     | boolean | 否       | false  | 是否启用 GPU 加速            |
+
+**返回值:**
+
+| 类型    | 描述                                                        |
+| ------- | ----------------------------------------------------------- |
+| boolean | 加载成功或模型已加载返回 `true`，失败返回 `false`           |
+
+**示例:**
+
+```lua
+local paddleocr = require("paddleocr")
+
+-- 手动加载 PP-OCRv5 模型
+local loaded = paddleocr.loadV5(640, false)
+print("PP-OCRv5 加载结果: " .. tostring(loaded))
+```
+
+#### loadModel - 按模型 ID 手动加载内置 PaddleOCR 模型。
+
+识别和查找方法默认自动加载 `ppocr-v6-small`。只有需要切换模型或指定 GPU 参数时才调用 `loadModel`。同一时间只保留一个 active 模型；检测长边请使用 `setMaxSideLen`。
+
+```lua
+---@param modelId string
+---@param useGpu boolean?
+---@return boolean
+function loadModel(modelId, useGpu) end
+```
+
+**参数:**
+
+| 参数名    | 类型    | 是否必填 | 默认值 | 描述                                              |
+| --------- | ------- | -------- | ------ | ------------------------------------------------- |
+| `modelId` | string  | 是       |        | `"ppocr-v6-tiny"` / `"ppocr-v6-small"` / `"ppocr-v5"` |
+| `useGpu`  | boolean | 否       | false  | 是否启用 GPU 加速                                 |
+
+**返回值:**
+
+| 类型    | 描述                                                                  |
+| ------- | --------------------------------------------------------------------- |
+| boolean | 加载成功或目标模型已加载返回 `true`，模型 ID 不支持或加载失败返回 `false` |
+
+**示例:**
+
+```lua
+local paddleocr = require("paddleocr")
+paddleocr.loadModel("ppocr-v6-tiny", false)
+local loaded = paddleocr.loadModel("ppocr-v6-small", false)
+print("PP-OCRv6 small 加载结果: " .. tostring(loaded))
+```
+
+#### setMaxSideLen - 单独设置检测阶段输入最大边长。
+
+只调整后续检测输入缩放，不会重新加载已加载模型。传 `0` 或负数时使用 `768`。
+
+```lua
+---@param maxSideLen number?
+---@return boolean
+function setMaxSideLen(maxSideLen) end
+```
+
+**参数:**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述                                      |
+| ------------ | ------ | -------- | ------ | ----------------------------------------- |
+| `maxSideLen` | number | 否       | 768    | 输入图像的最大边长；传 0 或负数时使用 768 |
+
+**返回值:**
+
+| 类型    | 描述                |
+| ------- | ------------------- |
+| boolean | 设置成功返回 `true` |
+
+**示例:**
+
+```lua
+local paddleocr = require("paddleocr")
+paddleocr.setMaxSideLen(960)
+```
+
+### 文字识别
+
+#### recognize - 执行 OCR 识别。
+
+传入裁剪区域时，返回坐标相对于裁剪区域。全屏识别时 `x/y/ex/ey` 传 `0`。
+
+```lua
+---@param input string
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@param confidenceThreshold number?
+---@return OCRResult[]
+function recognize(input, x, y, ex, ey, confidenceThreshold) end
+```
+
+**参数:**
+
+| 参数名                | 类型   | 是否必填 | 默认值 | 描述                                                        |
+| --------------------- | ------ | -------- | ------ | ----------------------------------------------------------- |
+| `input`               | string | 是       |        | 输入源，支持 imageId、URL 字符串、文件路径或 `"screen"`      |
+| `x`                   | number | 否       | 0      | 裁剪区域左上角 x 坐标；全屏识别传 0                         |
+| `y`                   | number | 否       | 0      | 裁剪区域左上角 y 坐标；全屏识别传 0                         |
+| `ex`                  | number | 否       | 0      | 裁剪区域右下角 x 坐标；全屏识别传 0                         |
+| `ey`                  | number | 否       | 0      | 裁剪区域右下角 y 坐标；全屏识别传 0                         |
+| `confidenceThreshold` | number | 否       | 0.6    | 置信度阈值，低于该值的识别结果会被过滤                      |
+
+**返回值:**
+
+| 类型          | 描述                               |
+| ------------- | ---------------------------------- |
+| `OCRResult[]` | 识别结果数组，坐标相对于裁剪区域   |
+
+**示例:**
+
+```lua
+local paddleocr = require("paddleocr")
+local action = require("action")
+
+local results = paddleocr.recognize("screen", 100, 100, 500, 300)
+if #results > 0 then
+  action.click(results[1].centerX, results[1].centerY)
+end
+```
+
+#### recognizeAbs - 执行 OCR 识别，并将结果坐标映射为原图/全屏绝对坐标。
+
+传入裁剪区域时，返回坐标会映射回原图或全屏坐标，可直接用于点击。
+
+```lua
+---@param input string
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@param confidenceThreshold number?
+---@return OCRResult[]
+function recognizeAbs(input, x, y, ex, ey, confidenceThreshold) end
+```
+
+**参数:**
+
+| 参数名                | 类型   | 是否必填 | 默认值 | 描述                                                   |
+| --------------------- | ------ | -------- | ------ | ------------------------------------------------------ |
+| `input`               | string | 是       |        | 输入源，支持 imageId、URL 字符串、文件路径或 `"screen"` |
+| `x`                   | number | 否       | 0      | 裁剪区域左上角 x 坐标；全屏识别传 0                    |
+| `y`                   | number | 否       | 0      | 裁剪区域左上角 y 坐标；全屏识别传 0                    |
+| `ex`                  | number | 否       | 0      | 裁剪区域右下角 x 坐标；全屏识别传 0                    |
+| `ey`                  | number | 否       | 0      | 裁剪区域右下角 y 坐标；全屏识别传 0                    |
+| `confidenceThreshold` | number | 否       | 0.6    | 置信度阈值，低于该值的识别结果会被过滤                 |
+
+**返回值:**
+
+| 类型          | 描述                                   |
+| ------------- | -------------------------------------- |
+| `OCRResult[]` | 识别结果数组，坐标为原图或全屏绝对坐标 |
+
+**示例:**
+
+```lua
+local paddleocr = require("paddleocr")
+local action = require("action")
+local absResults = paddleocr.recognizeAbs("screen", 100, 100, 500, 300)
+if #absResults > 0 then
+  action.click(absResults[1].centerX, absResults[1].centerY)
+end
+```
+
+#### findText - 查找目标文本。
+
+传入裁剪区域时，返回坐标相对于裁剪区域。`targets` 可以是字符串数组或逗号分隔字符串。
+
+```lua
+---@param input string
+---@param targets string[]|string
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@param confidenceThreshold number?
+---@param exactMatch boolean?
+---@return OCRResult[]
+function findText(input, targets, x, y, ex, ey, confidenceThreshold, exactMatch) end
+```
+
+**参数:**
+
+| 参数名                | 类型              | 是否必填 | 默认值 | 描述                                                                     |
+| --------------------- | ----------------- | -------- | ------ | ------------------------------------------------------------------------ |
+| `input`               | string            | 是       |        | 输入源，支持 imageId、URL 字符串、文件路径或 `"screen"`                   |
+| `targets`             | string[] \| string | 是       |        | 目标文本数组或逗号分隔字符串                                             |
+| `x`                   | number            | 否       | 0      | 裁剪区域左上角 x 坐标；全屏识别传 0                                      |
+| `y`                   | number            | 否       | 0      | 裁剪区域左上角 y 坐标；全屏识别传 0                                      |
+| `ex`                  | number            | 否       | 0      | 裁剪区域右下角 x 坐标；全屏识别传 0                                      |
+| `ey`                  | number            | 否       | 0      | 裁剪区域右下角 y 坐标；全屏识别传 0                                      |
+| `confidenceThreshold` | number            | 否       | 0.6    | 置信度阈值，低于该值的识别结果会被过滤                                   |
+| `exactMatch`          | boolean           | 否       | false  | 是否完整匹配；`false` 表示包含匹配，`true` 要求整条 OCR 文本等于目标文本 |
+
+**返回值:**
+
+| 类型          | 描述                                 |
+| ------------- | ------------------------------------ |
+| `OCRResult[]` | 匹配到的结果数组，坐标相对于裁剪区域 |
+
+**示例:**
+
+```lua
+local paddleocr = require("paddleocr")
+local hits = paddleocr.findText("screen", { "确定" }, 100, 100, 500, 400, 0.6, false)
+```
+
+#### findTextAbs - 查找目标文本，并将结果坐标映射为原图/全屏绝对坐标。
+
+```lua
+---@param input string
+---@param targets string[]|string
+---@param x number?
+---@param y number?
+---@param ex number?
+---@param ey number?
+---@param confidenceThreshold number?
+---@param exactMatch boolean?
+---@return OCRResult[]
+function findTextAbs(input, targets, x, y, ex, ey, confidenceThreshold, exactMatch) end
+```
+
+**参数:** 与 `findText` 相同；返回坐标为原图或全屏绝对坐标。
+
+**示例:**
+
+```lua
+local paddleocr = require("paddleocr")
+local action = require("action")
+local absHits = paddleocr.findTextAbs("screen", { "确定" }, 100, 100, 500, 400, 0.6, false)
+if #absHits > 0 then
+  action.click(absHits[1].centerX, absHits[1].centerY)
+end
+```
+
+### 资源管理
+
+#### free - 释放 OCR 模型占用的内存资源。
+
+```lua
+function free() end
+```
+
+**示例:**
+
+```lua
+local paddleocr = require("paddleocr")
+
+-- 使用完毕后释放资源
+paddleocr.free()
+print("OCR 模型资源已释放")
+```

package/docs/apilua/pip.md

@@ -0,0 +1,359 @@
+# 悬浮窗模块 (PIP)
+
+悬浮窗模块提供 iOS 画中画（Picture in Picture）悬浮窗能力，可用于显示脚本日志、保活提示或脚本自定义文本。
+
+## 功能特性
+
+- **显示模式**：支持日志、保活和自定义三种显示模式；首次安装默认保活
+- **关闭控制**：支持主动关闭悬浮窗
+- **状态查询**：判断悬浮窗是否正在显示
+- **尺寸设置**：日志模式和自定义模式支持设置内容宽高比（实际显示尺寸由系统决定），并按模式分别持久化
+- **日志显示**：日志模式支持设置日志文字大小
+- **自定义文本**：自定义模式支持文本、换行、文字颜色、背景色和文字大小
+
+## API 方法
+
+### isPipActive - 判断悬浮窗是否打开
+
+```lua
+---@return boolean
+function isPipActive() end
+```
+
+判断悬浮窗是否当前打开。
+
+**返回值：**
+
+| 类型      | 描述                                          |
+| --------- | --------------------------------------------- |
+| `boolean` | `true` 代表开启了悬浮窗，`false` 代表没有开启 |
+
+**示例：**
+
+```lua
+local pip = require("pip")
+local isActive = pip.isPipActive()
+if isActive then
+  print("悬浮窗当前已打开")
+end
+```
+
+### switchToLogMode - 切换到日志模式
+
+```lua
+---@return boolean
+function switchToLogMode() end
+```
+
+切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。日志模式会恢复最近一次保存的日志窗口尺寸。
+
+**返回值：**
+
+| 类型      | 描述                   |
+| --------- | ---------------------- |
+| `boolean` | `true` 代表已提交请求 |
+
+**示例：**
+
+```lua
+local pip = require("pip")
+takeMeToFront()
+local success = pip.switchToLogMode()
+pip.setLogFontSize(10)
+```
+
+### switchToKeepAliveMode - 切换到保活模式
+
+```lua
+---@return boolean
+function switchToKeepAliveMode() end
+```
+
+切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。保活模式不接受脚本尺寸设置。
+
+**返回值：**
+
+| 类型      | 描述                   |
+| --------- | ---------------------- |
+| `boolean` | `true` 代表已提交请求 |
+
+**示例：**
+
+```lua
+local pip = require("pip")
+takeMeToFront()
+local success = pip.switchToKeepAliveMode()
+```
+
+### switchToCustomMode - 切换到自定义模式
+
+```lua
+---@return boolean
+function switchToCustomMode() end
+```
+
+切换到自定义模式并显示脚本设置的自定义文本。首次显示悬浮窗时 App 必须在前台。自定义模式会恢复最近一次保存的自定义窗口尺寸。
+
+**返回值：**
+
+| 类型      | 描述                   |
+| --------- | ---------------------- |
+| `boolean` | `true` 代表已提交请求 |
+
+**示例：**
+
+```lua
+local pip = require("pip")
+takeMeToFront()
+pip.switchToCustomMode()
+pip.setCustomText("运行中\n进度 1/3")
+pip.setCustomTextColor("#34c759")
+pip.setCustomTextSize(18)
+```
+
+### closeWindow - 关闭悬浮窗
+
+```lua
+---@return boolean
+function closeWindow() end
+```
+
+关闭悬浮窗。
+
+**返回值：**
+
+| 类型      | 描述                   |
+| --------- | ---------------------- |
+| `boolean` | `true` 代表已提交请求 |
+
+**示例：**
+
+```lua
+local pip = require("pip")
+local success = pip.closeWindow()
+```
+
+### setContentSize - 设置内容尺寸
+
+```lua
+---@param width number
+---@param height number
+---@return boolean
+function setContentSize(width, height) end
+```
+
+设置日志模式或自定义模式的悬浮窗内容尺寸。传入的宽高表示宽高比，不是最终像素尺寸；悬浮窗实际显示的宽高由系统决定。宽度和高度都必须传入有效数字。日志模式和自定义模式会分别保存尺寸；悬浮窗关闭状态和保活模式不会生效。
+
+**参数：**
+
+| 参数     | 类型             | 必填 | 描述                                           |
+| -------- | ---------------- | ---- | ---------------------------------------------- |
+| `width`  | `number` | 是   | 宽度方向比例值（与 `height` 共同决定宽高比，不是像素） |
+| `height` | `number` | 是   | 高度方向比例值（与 `width` 共同决定宽高比，不是像素） |
+
+**返回值：**
+
+| 类型      | 描述                                                                 |
+| --------- | -------------------------------------------------------------------- |
+| `boolean` | `true` 代表尺寸已提交；`false` 代表当前模式不允许设置或宽高无效 |
+
+**示例：**
+
+```lua
+local pip = require("pip")
+pip.switchToLogMode()
+pip.setContentSize(280, 120)
+
+pip.switchToCustomMode()
+pip.setContentSize(120, 180)
+```
+
+### setLogFontSize - 设置日志文字大小
+
+```lua
+---@param fontSize number
+---@return boolean
+function setLogFontSize(fontSize) end
+```
+
+设置日志模式显示文本的文字大小。该方法只更新日志字号，不会自动切换到日志模式。
+
+**参数：**
+
+| 参数       | 类型     | 必填 | 描述                     |
+| ---------- | -------- | ---- | ------------------------ |
+| `fontSize` | `number` | 是   | 日志字号，必须是有效数字 |
+
+**返回值：**
+
+| 类型      | 描述                                                       |
+| --------- | ---------------------------------------------------------- |
+| `boolean` | `true` 代表日志文字大小已提交；`false` 代表字号无效 |
+
+**示例：**
+
+```lua
+local pip = require("pip")
+pip.setLogFontSize(10)
+pip.switchToLogMode()
+```
+
+### setCustomText - 设置自定义文本
+
+```lua
+---@param text string
+---@return boolean
+function setCustomText(text) end
+```
+
+设置自定义模式显示的纯文本内容。该方法只更新自定义文本数据，不会自动切换到自定义模式。
+
+**参数：**
+
+| 参数   | 类型     | 必填 | 描述                                        |
+| ------ | -------- | ---- | ------------------------------------------- |
+| `text` | `string` | 是   | 要显示的文本，支持真实换行和字符串中的 `\n` |
+
+**返回值：**
+
+| 类型      | 描述                   |
+| --------- | ---------------------- |
+| `boolean` | `true` 代表文本已提交 |
+
+**示例：**
+
+```lua
+local pip = require("pip")
+pip.setCustomText("运行中\n进度 1/3")
+pip.switchToCustomMode()
+```
+
+### setCustomTextColor - 设置自定义文字颜色
+
+```lua
+---@param color string
+---@return boolean
+function setCustomTextColor(color) end
+```
+
+设置自定义模式显示文本的文字颜色。该方法只更新文字颜色数据，不会自动切换到自定义模式。
+
+**参数：**
+
+| 参数    | 类型     | 必填 | 描述                                                        |
+| ------- | -------- | ---- | ----------------------------------------------------------- |
+| `color` | `string` | 是   | 文字颜色，支持 `RRGGBB`、`RRGGBBAA`，可带 `#` 前缀；末尾 AA 为透明度；无效值使用白色 |
+
+**返回值：**
+
+| 类型      | 描述                       |
+| --------- | -------------------------- |
+| `boolean` | `true` 代表文字颜色已提交 |
+
+**示例：**
+
+```lua
+local pip = require("pip")
+pip.setCustomTextColor("#34c759")
+pip.switchToCustomMode()
+```
+
+### setCustomTextSize - 设置自定义文字大小
+
+```lua
+---@param fontSize number
+---@return boolean
+function setCustomTextSize(fontSize) end
+```
+
+设置自定义模式显示文本的文字大小。该方法只更新文字大小数据，不会自动切换到自定义模式。
+
+**参数：**
+
+| 参数       | 类型     | 必填 | 描述                       |
+| ---------- | -------- | ---- | -------------------------- |
+| `fontSize` | `number` | 是   | 文字字号，必须是有效数字 |
+
+**返回值：**
+
+| 类型      | 描述                                                   |
+| --------- | ------------------------------------------------------ |
+| `boolean` | `true` 代表文字大小已提交；`false` 代表字号无效 |
+
+**示例：**
+
+```lua
+local pip = require("pip")
+pip.setCustomTextSize(18)
+pip.switchToCustomMode()
+```
+
+### setCustomBackgroundColor - 设置自定义背景色
+
+```lua
+---@param color string
+---@return boolean
+function setCustomBackgroundColor(color) end
+```
+
+设置自定义模式显示区域的背景色。该方法只更新背景色数据，不会自动切换到自定义模式。
+
+**参数：**
+
+| 参数    | 类型     | 必填 | 描述                                                        |
+| ------- | -------- | ---- | ----------------------------------------------------------- |
+| `color` | `string` | 是   | 背景颜色，支持 `RRGGBB`、`RRGGBBAA`，可带 `#` 前缀；末尾 AA 为透明度；无效值使用黑色 |
+
+**返回值：**
+
+| 类型      | 描述                     |
+| --------- | ------------------------ |
+| `boolean` | `true` 代表背景色已提交 |
+
+**示例：**
+
+```lua
+local pip = require("pip")
+pip.setCustomBackgroundColor("#111111")
+pip.switchToCustomMode()
+```
+
+## 完整使用示例
+
+```lua
+local pip = require("pip")
+takeMeToFront()
+
+pip.switchToLogMode()
+pip.setContentSize(280, 120)
+pip.setLogFontSize(10)
+
+pip.setCustomText("任务运行中\n1/3")
+pip.setCustomTextColor("#34c759")
+pip.setCustomTextSize(18)
+pip.setCustomBackgroundColor("#111111")
+pip.switchToCustomMode()
+pip.setContentSize(120, 180)
+```
+
+## 注意事项
+
+1. **前台限制**：首次切换到日志、保活或自定义显示模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换显示模式或关闭悬浮窗
+2. **设备兼容性**：仅支持 iOS 15+ 且具备画中画功能的设备
+3. **系统限制**：悬浮窗位置和实际显示尺寸由 iOS 管理
+4. **尺寸持久化**：日志模式和自定义模式分别保存尺寸，互不共用；保活模式不接受脚本尺寸
+5. **日志字号**：日志字号只影响日志模式，保活模式和自定义模式不受影响
+6. **竖向文本**：自定义窗口高度大于宽度时，文本会按逐字符换行方式竖向显示
+
+## 故障排除
+
+### 悬浮窗无法显示
+
+- 确认设备支持悬浮窗功能
+- 检查悬浮窗权限是否已开启
+- 确认应用当前在前台
+
+### setContentSize 返回 false
+
+- 确认当前模式是日志模式或自定义模式
+- 确认宽度和高度都传入了有效数字