ms-vite-plugin 1.4.11 → 1.4.13

package/docs/apicn/pip.md

@@ -1,12 +1,14 @@
 # 悬浮窗模块 ($悬浮窗)
 
-悬浮窗模块提供画中画（Picture in Picture）日志窗口能力。
+悬浮窗模块提供 iOS 画中画（Picture in Picture）悬浮窗能力，可用于显示脚本日志、保活提示或脚本自定义文本。
 
 ## 功能特性
 
-- **模式切换**：切换日志、保活和关闭三种悬浮窗模式
+- **显示模式**：支持日志、保活和自定义三种显示模式
+- **关闭控制**：支持主动关闭悬浮窗
 - **状态查询**：判断悬浮窗是否正在显示
-- **识别标记**：日志窗口左上角默认显示高对比标记，可用于截图识别悬浮窗位置
+- **尺寸设置**：日志模式和自定义模式支持设置内容宽高，并按模式分别持久化
+- **自定义文本**：自定义模式支持文本、换行、文字颜色、背景色和文字大小
 
 ## API 方法
 
@@ -39,7 +41,7 @@ if (是否显示) {
 function 切换到日志模式(): 布尔值;
 ```
 
-切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。
+切换到日志模式并尝试显示悬浮窗日志窗口。首次显示悬浮窗时 App 必须在前台。日志模式会恢复最近一次保存的日志窗口尺寸。
 
 **返回值：**
 
@@ -60,7 +62,7 @@ const 是否成功 = $悬浮窗.切换到日志模式();
 function 切换到保活模式(): 布尔值;
 ```
 
-切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。
+切换到保活模式并尝试显示极小高度悬浮窗。首次显示悬浮窗时 App 必须在前台。保活模式不接受脚本尺寸设置。
 
 **返回值：**
 
@@ -75,13 +77,13 @@ $APP切入前台();
 const 是否成功 = $悬浮窗.切换到保活模式();
 ```
 
-### 切换到关闭模式
+### 切换到自定义模式
 
 ```typescript
-function 切换到关闭模式(): 布尔值;
+function 切换到自定义模式(): 布尔值;
 ```
 
-切换到关闭模式并关闭悬浮窗。
+切换到自定义模式并显示脚本设置的自定义文本。首次显示悬浮窗时 App 必须在前台。自定义模式会恢复最近一次保存的自定义窗口尺寸。
 
 **返回值：**
 
@@ -92,22 +94,195 @@ function 切换到关闭模式(): 布尔值;
 **示例：**
 
 ```typescript
-const 是否成功 = $悬浮窗.切换到关闭模式();
+$APP切入前台();
+$悬浮窗.切换到自定义模式();
+$悬浮窗.设置自定义文本("运行中\n进度 1/3");
+$悬浮窗.设置自定义文字颜色("#34c759");
+$悬浮窗.设置自定义文字大小(18);
+```
+
+### 关闭悬浮窗
+
+```typescript
+function 关闭悬浮窗(): 布尔值;
+```
+
+关闭悬浮窗。
+
+**返回值：**
+
+| 类型     | 描述                   |
+| -------- | ---------------------- |
+| `布尔值` | `true` 代表已提交请求 |
+
+**示例：**
+
+```typescript
+const 是否成功 = $悬浮窗.关闭悬浮窗();
+```
+
+### 设置内容尺寸
+
+```typescript
+function 设置内容尺寸(宽度: 数字, 高度: 数字): 布尔值;
+```
+
+设置日志模式或自定义模式的悬浮窗内容尺寸。宽度和高度都必须传入有效数字。日志模式和自定义模式会分别保存尺寸；悬浮窗关闭状态和保活模式不会生效。
+
+**参数：**
+
+| 参数   | 类型          | 必填 | 描述                                           |
+| ------ | ------------- | ---- | ---------------------------------------------- |
+| `宽度` | `数字` | 是   | 目标内容宽度 |
+| `高度` | `数字` | 是   | 目标内容高度 |
+
+**返回值：**
+
+| 类型     | 描述                                                                 |
+| -------- | -------------------------------------------------------------------- |
+| `布尔值` | `true` 代表尺寸已提交；`false` 代表当前模式不允许设置或宽高无效 |
+
+**示例：**
+
+```typescript
+$悬浮窗.切换到日志模式();
+$悬浮窗.设置内容尺寸(280, 120);
+
+$悬浮窗.切换到自定义模式();
+$悬浮窗.设置内容尺寸(120, 180);
+```
+
+### 设置自定义文本
+
+```typescript
+function 设置自定义文本(文本: 字符串): 布尔值;
+```
+
+设置自定义模式显示的纯文本内容。该方法只更新自定义文本数据，不会自动切换到自定义模式。
+
+**参数：**
+
+| 参数   | 类型     | 必填 | 描述                                        |
+| ------ | -------- | ---- | ------------------------------------------- |
+| `文本` | `字符串` | 是   | 要显示的文本，支持真实换行和字符串中的 `\n` |
+
+**返回值：**
+
+| 类型     | 描述                   |
+| -------- | ---------------------- |
+| `布尔值` | `true` 代表文本已提交 |
+
+**示例：**
+
+```typescript
+$悬浮窗.设置自定义文本("运行中\n进度 1/3");
+$悬浮窗.切换到自定义模式();
+```
+
+### 设置自定义文字颜色
+
+```typescript
+function 设置自定义文字颜色(颜色: 字符串): 布尔值;
+```
+
+设置自定义模式显示文本的文字颜色。该方法只更新文字颜色数据，不会自动切换到自定义模式。
+
+**参数：**
+
+| 参数   | 类型     | 必填 | 描述                                                        |
+| ------ | -------- | ---- | ----------------------------------------------------------- |
+| `颜色` | `字符串` | 是   | 文字颜色，支持 `RRGGBB`、`RRGGBBAA`，可带 `#` 前缀；末尾 AA 为透明度；无效值使用白色 |
+
+**返回值：**
+
+| 类型     | 描述                       |
+| -------- | -------------------------- |
+| `布尔值` | `true` 代表文字颜色已提交 |
+
+**示例：**
+
+```typescript
+$悬浮窗.设置自定义文字颜色("#34c759");
+$悬浮窗.切换到自定义模式();
+```
+
+### 设置自定义文字大小
+
+```typescript
+function 设置自定义文字大小(字号: 数字): 布尔值;
+```
+
+设置自定义模式显示文本的文字大小。该方法只更新文字大小数据，不会自动切换到自定义模式。
+
+**参数：**
+
+| 参数   | 类型   | 必填 | 描述                     |
+| ------ | ------ | ---- | ------------------------ |
+| `字号` | `数字` | 是   | 文字字号，必须是有效数字 |
+
+**返回值：**
+
+| 类型     | 描述                                                 |
+| -------- | ---------------------------------------------------- |
+| `布尔值` | `true` 代表文字大小已提交；`false` 代表字号无效 |
+
+**示例：**
+
+```typescript
+$悬浮窗.设置自定义文字大小(18);
+$悬浮窗.切换到自定义模式();
+```
+
+### 设置自定义背景色
+
+```typescript
+function 设置自定义背景色(颜色: 字符串): 布尔值;
+```
+
+设置自定义模式显示区域的背景色。该方法只更新背景色数据，不会自动切换到自定义模式。
+
+**参数：**
+
+| 参数   | 类型     | 必填 | 描述                                                        |
+| ------ | -------- | ---- | ----------------------------------------------------------- |
+| `颜色` | `字符串` | 是   | 背景颜色，支持 `RRGGBB`、`RRGGBBAA`，可带 `#` 前缀；末尾 AA 为透明度；无效值使用黑色 |
+
+**返回值：**
+
+| 类型     | 描述                     |
+| -------- | ------------------------ |
+| `布尔值` | `true` 代表背景色已提交 |
+
+**示例：**
+
+```typescript
+$悬浮窗.设置自定义背景色("#111111");
+$悬浮窗.切换到自定义模式();
 ```
 
 ## 完整使用示例
 
 ```typescript
 $APP切入前台();
+
 $悬浮窗.切换到日志模式();
+$悬浮窗.设置内容尺寸(280, 120);
+
+$悬浮窗.设置自定义文本("任务运行中\n1/3");
+$悬浮窗.设置自定义文字颜色("#34c759");
+$悬浮窗.设置自定义文字大小(18);
+$悬浮窗.设置自定义背景色("#111111");
+$悬浮窗.切换到自定义模式();
+$悬浮窗.设置内容尺寸(120, 180);
 ```
 
 ## 注意事项
 
-1. **前台限制**：首次切换到日志模式或保活模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换日志/保活模式
+1. **前台限制**：首次切换到日志、保活或自定义显示模式并启动悬浮窗时，App 必须在前台；悬浮窗已启动后可以继续切换显示模式或关闭悬浮窗
 2. **设备兼容性**：仅支持 iOS 15+ 且具备画中画功能的设备
 3. **系统限制**：悬浮窗位置和实际显示尺寸由 iOS 管理
-4. **识别标记**：日志窗口左上角默认包含识别标记，便于通过截图识别悬浮窗位置
+4. **尺寸持久化**：日志模式和自定义模式分别保存尺寸，互不共用；保活模式不接受脚本尺寸
+5. **竖向文本**：自定义窗口高度大于宽度时，文本会按逐字符换行方式竖向显示
 
 ## 故障排除
 
@@ -116,3 +291,8 @@ $悬浮窗.切换到日志模式();
 - 确认设备支持悬浮窗功能
 - 检查悬浮窗权限是否已开启
 - 确认应用当前在前台
+
+### 设置内容尺寸返回 false
+
+- 确认当前模式是日志模式或自定义模式
+- 确认宽度和高度都传入了有效数字

package/docs/apipython/appleocr.md

@@ -227,7 +227,7 @@ if abs_number_results:
 
 #### findText
 
-执行指定文本查找，在识别结果中查找特定的文本内容。使用全字匹配模式，确保精确匹配目标文本。
+执行指定文本查找，在识别结果中查找目标子串，并返回目标子串的坐标。
 
 ```python
 def findText(
@@ -237,7 +237,8 @@ def findText(
     y: int = 0,
     ex: int = 0,
     ey: int = 0,
-    languages: Optional[List[str]] = ["zh-Hans", "en-US"]
+    languages: Optional[List[str]] = ["zh-Hans", "en-US"],
+    exactMatch: bool = False
 ) -> List[OCRResult]
 ```
 
@@ -246,26 +247,29 @@ def findText(
 | 参数名      | 类型      | 是否必填 | 默认值               | 描述                                                                                                                              |
 | ----------- | --------- | -------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
 | `input`     | str       | 是       | -                    | 输入源，支持以下类型： <br>-`"screen"` 当前屏幕截图 <br>- `str` 图片文件路径或 URL <br>- `imageId` 图片 ID（通过 image 模块获取） |
-| `texts`     | List[str] | 是       | -                    | 要查找的文本数组                                                                                                                  |
+| `texts`     | List[str] | 是       | -                    | 要查找的目标文本数组，支持匹配识别结果中的子串                                                                                    |
 | `x`         | int       | 否       | 0                    | 识别区域左上角 x 坐标                                                                                                             |
 | `y`         | int       | 否       | 0                    | 识别区域左上角 y 坐标                                                                                                             |
 | `ex`        | int       | 否       | 0                    | 识别区域右下角 x 坐标                                                                                                             |
 | `ey`        | int       | 否       | 0                    | 识别区域右下角 y 坐标                                                                                                             |
 | `languages` | List[str] | 否       | ["zh-Hans", "en-US"] | 可选，指定识别语言列表，如 `["zh-Hans", "en-US"]`                                                                                 |
+| `exactMatch` | bool     | 否       | False                | 是否完整匹配；`False` 表示包含匹配，`True` 表示整条 OCR 识别结果文本必须等于目标文本                                                       |
 
 **返回值:**
 
 | 类型              | 描述                   |
 | ----------------- | ---------------------- |
-| `List[OCRResult]` | 匹配的文本识别结果数组 |
+| `List[OCRResult]` | 命中子串的文本识别结果数组 |
 
 **使用示例:**
 
 ```python
 from kuaijs import appleocr
 
-# 识别屏幕中的文本
-text_results = appleocr.findText("screen", ["123", "456"], 0, 0, 100, 100)
+# 在“开始执行”中查找“开始”，返回“开始”子串区域
+text_results = appleocr.findText("screen", ["开始"], 0, 0, 100, 100)
+# 启用完整匹配时，只有整条 OCR 识别结果文本等于“开始”才返回结果
+exact_results = appleocr.findText("screen", ["开始"], 0, 0, 100, 100, None, True)
 print(f"识别到 {len(text_results)} 个文本区域")
 
 for i, result in enumerate(text_results):
@@ -274,7 +278,7 @@ for i, result in enumerate(text_results):
     print(f"中心点: ({result.centerX}, {result.centerY})")
 ```
 
-#### `findTextAbs` - 查找目标文本，并将结果坐标映射为原图/全屏绝对坐标
+#### `findTextAbs` - 查找目标子串，并将子串结果坐标映射为原图/全屏绝对坐标
 
 参数与 `findText` 相同。传入裁剪区域时，返回坐标可直接用于全屏点击。
 
@@ -286,7 +290,8 @@ def findTextAbs(
     y: int = 0,
     ex: int = 0,
     ey: int = 0,
-    languages: Optional[List[str]] = None
+    languages: Optional[List[str]] = None,
+    exactMatch: bool = False
 ) -> List[OCRResult]
 ```
 
@@ -295,7 +300,7 @@ def findTextAbs(
 ```python
 from kuaijs import appleocr, action
 
-abs_hits = appleocr.findTextAbs("screen", ["确定"], 100, 100, 500, 400)
+abs_hits = appleocr.findTextAbs("screen", ["开始"], 100, 100, 500, 400)
 if abs_hits:
     action.click(abs_hits[0]["centerX"], abs_hits[0]["centerY"])
 ```

package/docs/apipython/image.md

@@ -431,6 +431,51 @@ if imageId:
     image.release(imageId)
 ```
 
+### countColor - 统计颜色数量
+
+统计指定区域内命中目标颜色的像素数量。`colors` 可以传入一个或多个候选颜色，多个颜色使用 `|` 分隔，支持 `主色-偏色` 格式，如 `#0A0A0A-#101010|#FFFFFF-#101010`。同一个像素同时命中多个候选颜色时只统计一次。
+
+```python
+def countColor(id: str, colors: str, threshold: float, x: int, y: int, ex: int, ey: int) -> int
+```
+
+**参数：**
+
+| 参数名      | 类型  | 是否必填 | 默认值 | 描述                                                                                 |
+| ----------- | ----- | -------- | ------ | ------------------------------------------------------------------------------------ |
+| `id`        | str   | 是       | <br /> | 图片 ID，支持 `"screen"`、图片文件路径、HTTP 图片地址或已加载的图片 ID               |
+| `colors`    | str   | 是       | <br /> | 颜色列表，支持 `主色-偏色\|主色-偏色` 格式，如 `#0A0A0A-#101010\|#FFFFFF-#101010` |
+| `threshold` | float | 是       | <br /> | 颜色匹配阈值 (0.0-1.0)，数值越大匹配越严格                                           |
+| `x,y`       | int   | 是       | <br /> | 统计区域左上角坐标                                                                   |
+| `ex,ey`     | int   | 是       | <br /> | 统计区域右下角坐标；传 `0` 表示延伸到图片右侧或底部边界                              |
+
+**返回值：**
+
+| 类型  | 描述                                                                                 |
+| ----- | ------------------------------------------------------------------------------------ |
+| `int` | 命中目标颜色的像素数量；图片加载失败、颜色为空、颜色格式无效或区域不合法时返回 `0` |
+
+**示例：**
+
+```python
+from kuaijs import image
+
+imageId = image.captureFullScreen()
+if imageId:
+    count = image.countColor(
+        imageId,
+        "#0A0A0A-#101010|#FFFFFF-#101010",
+        0.92,
+        100,
+        200,
+        500,
+        700
+    )
+
+    print(f"目标区域命中颜色像素数量: {count}")
+    image.release(imageId)
+```
+
 ### cmpColor - 多点比色
 
 ```python

package/docs/apipython/paddleocr.md

@@ -172,7 +172,8 @@ def findText(
     y: int = 0,
     ex: int = 0,
     ey: int = 0,
-    confidenceThreshold: float = 0.6
+    confidenceThreshold: float = 0.6,
+    exactMatch: bool = False
 ) -> List[OCRResult]
 ```
 
@@ -187,6 +188,7 @@ def findText(
 | `ex`                  | int       | 否       | 0      | 查找区域右下角 x 坐标                                                                                                         |
 | `ey`                  | int       | 否       | 0      | 查找区域右下角 y 坐标                                                                                                         |
 | `confidenceThreshold` | float     | 否       | 0.6    | 置信度阈值，默认值为 0.6                                                                                                      |
+| `exactMatch`          | bool      | 否       | False  | 是否完整匹配；`False` 表示包含匹配，`True` 表示整条 OCR 识别结果文本必须等于目标文本                                                   |
 
 **返回值：**
 
@@ -204,7 +206,7 @@ if not paddleocr.loadV5():
     print("模型加载失败")
 else:
     # 在整个屏幕中查找目标文本
-    hit_results = paddleocr.findText("screen", ["登录", "确定"], 0, 0, 0, 0, 0.6)
+    hit_results = paddleocr.findText("screen", ["登录", "确定"], 0, 0, 0, 0, 0.6, False)
     if hit_results:
         for i, r in enumerate(hit_results, 1):
             print(f"命中{i}: {r.text}, 中心点=({r.centerX}, {r.centerY}), 置信度={r.confidence}")
@@ -228,14 +230,15 @@ def findTextAbs(
     y: int = 0,
     ex: int = 0,
     ey: int = 0,
-    confidenceThreshold: float = 0.6
+    confidenceThreshold: float = 0.6,
+    exactMatch: bool = False
 ) -> List[OCRResult]
 ```
 
 **示例：**
 
 ```python
-abs_hits = paddleocr.findTextAbs("screen", ["确定"], 100, 100, 500, 400, 0.6)
+abs_hits = paddleocr.findTextAbs("screen", ["确定"], 100, 100, 500, 400, 0.6, False)
 if abs_hits:
     print(f"绝对坐标中心点: ({abs_hits[0].centerX}, {abs_hits[0].centerY})")
 ```