ms-vite-plugin 1.1.2 → 1.1.3

package/docs/api/thread.md

@@ -0,0 +1,269 @@
+# 多线程模块 (Thread)
+
+多线程模块提供了简单的多线程编程能力，允许您在后台执行任务而不阻塞主线程。配合 `sharedState` 全局对象，可以实现线程间的数据共享和通信。
+
+## 功能概览
+
+- **异步执行**: 使用 `thread.run` 快速启动新线程。
+- **线程控制**: 支持取消线程、检查线程状态。
+- **状态共享**: 使用 `sharedState` 在不同线程间共享数据。
+
+## 注意事项
+
+- **独立的执行环境**: 线程函数在独立的 JavaScript 环境中运行，无法访问主线程或其他作用域中的变量、函数或对象。
+- **闭包限制**: 即使线程函数是闭包形式，它也无法捕获外部变量。传递给 `thread.run` 的函数会被转换并在新的上下文中执行。
+- **数据通信**: 如果需要与主线程通信或使用外部数据，请使用 `sharedState` 全局对象。
+- **文件名限制**:执行的线程 js 文件名称必须以 `_thread.js` 结尾，例如 `worker_thread.js`。
+
+## API 参考
+
+### Thread 模块
+
+#### thread.run - 异步执行代码
+
+启动一个新的线程来执行指定的 JS 文件。
+
+```typescript
+function run(threadJsFileName: string): Thread;
+```
+
+**参数:**
+
+| 参数名             | 类型     | 描述             |
+| ------------------ | -------- | ---------------- |
+| `threadJsFileName` | `string` | 线程 js 文件路径 |
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `Thread` | 线程控制对象 |
+
+**示例:**
+
+```javascript
+// 启动一个简单的线程
+const t = thread.run("test_thread.js");
+```
+
+#### thread.stopAll - 停止所有线程
+
+停止当前所有正在运行的子线程。
+
+```typescript
+function stopAll(): boolean;
+```
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否停止成功 |
+
+**示例:**
+
+```javascript
+const stopped = thread.stopAll();
+logi("Stopped all threads: " + stopped);
+```
+
+---
+
+### Thread 对象
+
+`thread.run` 返回的对象，用于控制特定线程。
+
+#### 属性
+
+| 属性名 | 类型     | 描述     |
+| ------ | -------- | -------- |
+| `name` | `string` | 线程名称 |
+
+#### 方法
+
+##### cancel - 取消线程
+
+```typescript
+cancel(): boolean;
+```
+
+**返回值:** 是否取消成功。
+
+**示例:**
+
+```javascript
+// t is the object returned by thread.run
+t.cancel();
+```
+
+##### isCancelled - 检查是否已取消
+
+```typescript
+isCancelled(): boolean;
+```
+
+**返回值:** 如果线程已被取消则返回 `true`，否则返回 `false`。
+
+**示例:**
+
+```javascript
+if (t.isCancelled()) {
+  logi("此线程已被取消");
+}
+```
+
+##### isExecuting - 检查是否正在执行
+
+```typescript
+isExecuting(): boolean;
+```
+
+**返回值:** 如果线程正在运行则返回 `true`，否则返回 `false`。
+
+**示例:**
+
+```javascript
+if (t.isExecuting()) {
+  logi("此线程正在运行");
+}
+```
+
+---
+
+### SharedState (状态共享)
+
+`sharedState` 是一个全局对象，用于在主线程和子线程之间，或者不同子线程之间共享数据。
+
+#### sharedState.set - 设置状态
+
+设置一个共享状态值。
+
+```typescript
+set(key: string, value: any): void;
+```
+
+**参数:**
+
+| 参数名  | 类型     | 描述     |
+| ------- | -------- | -------- |
+| `key`   | `string` | 状态键名 |
+| `value` | `any`    | 状态值   |
+
+**示例:**
+
+```javascript
+sharedState.set("count", 1);
+```
+
+#### sharedState.get - 获取状态
+
+获取指定的共享状态值。
+
+```typescript
+get(key: string): any;
+```
+
+**参数:**
+
+| 参数名 | 类型     | 描述     |
+| ------ | -------- | -------- |
+| `key`  | `string` | 状态键名 |
+
+**返回值:** 对应的状态值。
+
+**示例:**
+
+```javascript
+const val = sharedState.get("count");
+```
+
+#### sharedState.withBatch - 批量操作
+
+在回调中执行一系列状态操作，保证操作的原子性（视具体实现而定，通常用于在一个锁周期内完成多个操作）。
+
+```typescript
+withBatch(block: () => void): void;
+```
+
+**参数:**
+
+| 参数名  | 类型         | 描述                 |
+| ------- | ------------ | -------------------- |
+| `block` | `() => void` | 包含状态操作的代码块 |
+
+**示例:**
+
+```javascript
+sharedState.withBatch(() => {
+  sharedState.set("a", 1);
+  sharedState.set("b", 2);
+});
+```
+
+#### sharedState.clear - 清除所有状态
+
+清除所有共享的状态数据。
+
+```typescript
+clear(): void;
+```
+
+**示例:**
+
+```javascript
+sharedState.clear();
+```
+
+## 综合示例：线程通信
+
+下面的示例展示了如何使用 `thread.run` 启动线程，并通过 `sharedState` 进行主线程与子线程之间的通信。
+
+### 1. 子线程代码 (worker_thread.js)
+
+```javascript
+// worker_thread.js
+logi("子线程开始工作");
+
+for (let i = 1; i <= 5; i++) {
+  // 检查是否需要提前停止
+  if (!sharedState.get("isRunning")) {
+    logi("子线程检测到停止信号，退出");
+    break; // 或 return
+  }
+
+  sleep(1000); // 模拟耗时操作
+
+  // 更新进度到共享状态
+  sharedState.set("progress", i * 20);
+  logi(`子线程更新进度: ${i * 20}%`);
+}
+
+logi("子线程工作完成");
+```
+
+### 2. 主线程代码 (main.js)
+
+```javascript
+// main.js
+
+// 1. 初始化状态
+sharedState.set("progress", 0);
+sharedState.set("isRunning", true);
+
+// 2. 启动子线程执行耗时任务
+const taskThread = thread.run("worker_thread.js");
+
+// 3. 主线程监控进度
+while (taskThread.isExecuting()) {
+  const progress = sharedState.get("progress");
+  logi(`主线程读取进度: ${progress}%`);
+
+  if (progress >= 100) {
+    break;
+  }
+
+  sleep(500);
+}
+
+logi("任务结束");
+```

package/docs/api/tomatoocr.md

@@ -0,0 +1,425 @@
+# TomatoOCR 模块
+
+TomatoOCR 模块提供基于 TomatoOCR 框架的文字识别和 YOLO 目标检测功能，支持多种识别模式和配置选项。
+
+该 ocr 为付费插件, 具体资费请联系https://www.52tomato.com, 如果购买请选择插件版-快点 JS-IOS
+
+## 功能概览
+
+- **文字识别**: 支持多语言文字识别，包括中文、英文、数字、繁体、日语、韩语等
+- **多种输入源**: 支持屏幕截图、文件路径、图像 ID 等多种输入方式
+- **灵活配置**: 提供丰富的参数配置选项
+- **点击点查找**: 根据文字内容查找可点击的位置
+
+## API 参考
+
+### 初始化方法
+
+#### `initializeWithConfig`
+
+初始化 TomatoOCR 引擎并设置基本配置。
+
+```typescript
+function initializeWithConfig(
+  mode: string,
+  licenseData: string,
+  remark?: string
+): {
+  deviceId: string;
+  expiryTime: string;
+  message: string;
+  status: string;
+  versionName: string;
+} | null;
+```
+
+**参数:**
+
+| 参数名        | 类型   | 是否必填 | 默认值 | 描述                                                               |
+| ------------- | ------ | -------- | ------ | ------------------------------------------------------------------ |
+| `mode`        | string | 是       |        | 运行模式，debug：调试模型；删除或传别的任何值为正式模式            |
+| `licenseData` | string | 是       |        | 授权码 请传入你在 TomatoOCR 官网申请的授权码 购买依赖版-IOS 后获取 |
+| `remark`      | string | 否       |        | 备注信息                                                           |
+
+**返回值:**
+
+- 成功时返回包含设备信息的对象，失败时返回 null
+
+  | 参数名        | 类型   | 描述     |
+  | ------------- | ------ | -------- |
+  | `deviceId`    | string | 设备 ID  |
+  | `expiryTime`  | string | 过期时间 |
+  | `message`     | string | 消息     |
+  | `status`      | string | 状态     |
+  | `versionName` | string | 版本名称 |
+
+**示例:**
+
+```typescript
+// 不带备注
+const result1 = tomatoOcr.initializeWithConfig(
+  "online",
+  "请传入你在 TomatoOCR 官网申请的授权码"
+);
+// 带备注
+const result2 = tomatoOcr.initializeWithConfig(
+  "online",
+  "请传入你在 TomatoOCR 官网申请的授权码",
+  "测试环境"
+);
+logi(`结果1: ${JSON.stringify(result1)}, 结果2: ${JSON.stringify(result2)}`);
+```
+
+### 配置方法
+
+#### `setHttpIntervalTime`
+
+设置 HTTP 请求间隔时间。
+
+```typescript
+function setHttpIntervalTime(second: number): void;
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                                              |
+| -------- | ------ | -------- | ------ | ------------------------------------------------- |
+| `second` | number | 是       |        | 间隔秒数，设置网络请求间隔时间，非必设置。0-86400 |
+
+**示例:**
+
+```typescript
+tomatoOcr.setHttpIntervalTime(3600);
+```
+
+#### `setRecType`
+
+设置识别类型。
+
+```typescript
+function setRecType(recType: string): void;
+```
+
+**参数:**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述                                                                               |
+| --------- | ------ | -------- | ------ | ---------------------------------------------------------------------------------- |
+| `recType` | string | 是       |        | 识别类型，模型类型,默认 ch-3.0,除此之外还有 ch-2.0, ch, cht, japan, korean, number |
+
+**示例:**
+
+```typescript
+// 普通中英文识别，3.0版模型
+tomatoOcr.setRecType("ch-3.0");
+// 普通中英文识别，2.0版模型
+tomatoOcr.setRecType("ch-2.0");
+// 普通中英文识别，1.0版模型
+tomatoOcr.setRecType("ch");
+// 繁体
+tomatoOcr.setRecType("cht");
+// 日语
+tomatoOcr.setRecType("japan");
+// 韩语
+tomatoOcr.setRecType("korean");
+// 数字模型
+tomatoOcr.setRecType("number");
+```
+
+#### `setDetBoxType`
+
+设置检测框类型。
+
+```typescript
+function setDetBoxType(detBoxType: string): void;
+```
+
+**参数:**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述                                                                               |
+| ------------ | ------ | -------- | ------ | ---------------------------------------------------------------------------------- |
+| `detBoxType` | string | 是       |        | 检测框类型，默认"rect": 由于手机上截图文本均为矩形文本；"quad"：可准确检测倾斜文本 |
+
+**示例:**
+
+```typescript
+// 矩形文本
+tomatoOcr.setDetBoxType("rect");
+// 倾斜文本
+tomatoOcr.setDetBoxType("quad");
+```
+
+#### `setDetScaleRatio`
+
+设置输入图片缩放大小的参数，非必设置，默认为 1.0。值范围 0.1-10.0 之间，如果图太小，可能出现检测不到的情况，则尝试放大图片，如设置 2.0；如果图太大，可能出现检测不到一起的情况，则尝试缩小图片，如设置 0.5
+
+```typescript
+function setDetScaleRatio(detScaleRatio: number): void;
+```
+
+**参数:**
+
+| 参数名          | 类型   | 是否必填 | 默认值 | 描述           |
+| --------------- | ------ | -------- | ------ | -------------- |
+| `detScaleRatio` | number | 是       |        | 检测框缩放比例 |
+
+**示例:**
+
+```typescript
+tomatoOcr.setDetScaleRatio(0.5);
+```
+
+#### `setDetUnclipRatio`
+
+设置检测框展开比例。
+
+```typescript
+function setDetUnclipRatio(detUnclipRatio: number): void;
+```
+
+**参数:**
+
+| 参数名           | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                                                            |
+| ---------------- | ------ | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `detUnclipRatio` | number | 是       |        | 设置检测模型框选文本范围大小的参数，非必设置，默认为 1.9。值范围 1.6-2.5 之间，值越大框选范围越大，值越小框选范围越小；当框选到了，但识别得分较低，就可以调整该参数改善准确率。 |
+
+**示例:**
+
+```typescript
+tomatoOcr.setDetUnclipRatio(1.9);
+```
+
+#### `setRecScoreThreshold`
+
+设置识别分数阈值。
+
+```typescript
+function setRecScoreThreshold(recScoreThreshold: number): void;
+```
+
+**参数:**
+
+| 参数名              | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                                     |
+| ------------------- | ------ | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `recScoreThreshold` | number | 是       |        | 设置识别模型过滤得分的参数，非必设置，默认 0.1。由于返回的识别结果数据太多太乱，可以通过设置该参数，过滤一些得分较低不准的数据，使得结果看起来更加简练。 |
+
+**示例:**
+
+```typescript
+tomatoOcr.setRecScoreThreshold(0.1);
+```
+
+#### `setReturnType`
+
+设置返回类型。
+
+```typescript
+function setReturnType(returnType: string): void;
+```
+
+**参数:**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述                                                                                                                                                                                 |
+| ------------ | ------ | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `returnType` | string | 是       |        | 设置调用插件识别返回格式的参数，非必设置，默认为 json。默认"json": 包含得分、坐标和文字；"text"：纯文字；"num"：纯数字；自定义输入想要返回的文本：".￥ 1234567890"，仅只返回这些内容 |
+
+**示例:**
+
+```typescript
+tomatoOcr.setReturnType("json");
+```
+
+#### `setBinaryThresh`
+
+设置二值化阈值。
+
+```typescript
+function setBinaryThresh(binaryThresh: number): void;
+```
+
+**参数:**
+
+| 参数名         | 类型   | 是否必填 | 默认值 | 描述                                                                                                                 |
+| -------------- | ------ | -------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
+| `binaryThresh` | number | 是       |        | 设置图像二值化的参数，非必设置，默认 0，不进行二值化。二值化设定 0-255，常规情况下不需要设置，可配合中调试应用使用。 |
+
+**示例:**
+
+```typescript
+tomatoOcr.setBinaryThresh(0);
+```
+
+#### `setRunMode`
+
+设置运行模式。
+
+```typescript
+function setRunMode(runMode: string): void;
+```
+
+**参数:**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述                                                 |
+| --------- | ------ | -------- | ------ | ---------------------------------------------------- |
+| `runMode` | string | 是       |        | 运行模式，默认"fast": 快速模式；"accurate"：准确模式 |
+
+**示例:**
+
+```typescript
+tomatoOcr.setRunMode("fast");
+```
+
+#### `setFilterColor`
+
+设置图像滤色参数。
+
+```typescript
+function setFilterColor(filterColor: string, backgroundColor: string): void;
+```
+
+**参数:**
+
+| 参数名            | 类型   | 是否必填 | 默认值 | 描述                                                                                               |
+| ----------------- | ------ | -------- | ------ | -------------------------------------------------------------------------------------------------- |
+| `filterColor`     | string | 是       | \_     | 颜色过滤，通过逗号相互连，第一个是颜色值，第二个是负偏色，第三个是正偏色；不同颜色之间以" \| "连接 |
+| `backgroundColor` | string | 是       | \_     | 滤色后的背景色，传""或 black 的时候，背景是黑色，传"white"的时候，背景是白色                       |
+
+**示例:**
+
+```typescript
+tomatoOcr.setFilterColor("#41917A,38,38", "black");
+tomatoOcr.setFilterColor("#41917A,38,38|#E091A8,50,50", "white");
+```
+
+### OCR 识别方法
+
+#### `ocrImage`
+
+对图像执行 OCR 识别。
+
+```typescript
+function ocrImage(
+  input: string,
+  type: number,
+  x: number,
+  y: number,
+  ex: number,
+  ey: number
+): string;
+```
+
+**参数:**
+
+| 参数名  | 类型   | 是否必填 | 默认值 | 描述                                                                                |
+| ------- | ------ | -------- | ------ | ----------------------------------------------------------------------------------- |
+| `input` | string | 是       |        | 输入源（imageId、URL 字符串、文件路径或"screen"）                                   |
+| `type`  | number | 是       |        | 识别类型，默认 3: 检测 + 识别；0: 只检测；1: 方向分类+识别；2: 只识别；3: 检测+识别 |
+| `x`     | number | 是       |        | 边界框左上角 x 坐标                                                                 |
+| `y`     | number | 是       |        | 边界框左上角 y 坐标                                                                 |
+| `ex`    | number | 是       |        | 边界框右下角 x 坐标                                                                 |
+| `ey`    | number | 是       |        | 边界框右下角 y 坐标                                                                 |
+
+**返回值:**
+
+| 类型     | 描述                     |
+| -------- | ------------------------ |
+| `string` | OCR 识别结果 JSON 字符串 |
+
+**示例:**
+
+```typescript
+// 识别屏幕
+const result1 = tomatoOcr.ocrImage("screen", 0, 0, 0, 0, 0);
+logi(`识别屏幕结果：${result1}`);
+
+// 识别文件
+const result2 = tomatoOcr.ocrImage("/path/to/image.png", 0, 0, 0, 0, 0);
+logi(`识别文件结果：${result2}`);
+
+// 识别指定屏幕区域
+const result3 = tomatoOcr.ocrImage("screen", 0, 100, 500, 300);
+logi(`识别指定屏幕区域结果：${result3}`);
+```
+
+### 点击点查找方法
+
+#### `findTapPoint`
+
+查找点击点。
+
+```typescript
+function findTapPoint(data: string): string;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述       |
+| ------ | ------ | -------- | ------ | ---------- |
+| `data` | string | 是       |        | 要找的文字 |
+
+**返回值:**
+
+| 类型     | 描述                                        |
+| -------- | ------------------------------------------- |
+| `string` | 找"要找的文字"的中心点 没有找到返回空字符串 |
+
+**示例:**
+
+```typescript
+const result = tomatoOcr.findTapPoint(“确定”);
+logi(result);
+```
+
+#### `findTapPoints`
+
+查找多个点击点。
+
+```typescript
+function findTapPoints(data: string): string;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述       |
+| ------ | ------ | -------- | ------ | ---------- |
+| `data` | string | 是       |        | 要找的文字 |
+
+**返回值:**
+
+| 类型     | 描述                                                    |
+| -------- | ------------------------------------------------------- |
+| `string` | 找"要找的文字"的所有相匹配的中心点 没有找到返回空字符串 |
+
+**示例:**
+
+```typescript
+const result = tomatoOcr.findTapPoints(“确定”);
+logi(result);
+```
+
+## 完整示例
+
+```typescript
+// 初始化 TomatoOCR 并设置基本配置
+const initResult = tomatoOcr.initializeWithConfig(
+  "online",
+  "请传入你在 TomatoOCR 官网申请的授权码",
+  "测试环境" // 可选备注
+);
+logi("初始化结果:" + JSON.stringify(initResult));
+
+// 配置其他参数
+tomatoOcr.setRecType("ch-3.0");
+
+// 执行 OCR 识别
+const ocrResult = tomatoOcr.ocrImage("screen", 3, 0, 0, 0, 0); // 识别当前屏幕
+logi("识别结果:" + ocrResult);
+
+// 查找点击点
+const tapResult = tomatoOcr.findTapPoint("登录");
+logi("点击点坐标:" + tapResult);
+```
+
+## 注意事项
+
+1. **参数配置**: 根据实际需求调整各种阈值和配置参数
+2. **错误处理**: 建议对返回的 JSON 结果进行错误检查