ms-vite-plugin 1.4.39 → 1.4.41

package/docs/apicn/dotocr.md

@@ -0,0 +1,161 @@
+# 点阵 OCR 模块（$点阵OCR）
+
+`$点阵OCR` 使用图色工具生成的固定像素点阵字库识别文字。字库保存在项目的 `res/fonts` 目录，使用方式与 YOLO 模型一致：先加载资源取得字库 ID，再复用该 ID 进行识别，使用完毕后释放。
+
+点阵模板按照制作时的原始像素尺寸匹配，不会自动缩放到其他分辨率。目标文字的字号、缩放比例或像素形状发生变化时，应制作对应的字库特征。
+
+## 功能概览
+
+- **字库管理**：加载、缓存和释放项目字库
+- **文字识别**：返回按阅读顺序排列的识别结果数组
+- **文本查找**：先识别再按行定位目标串，返回命中位置的绝对坐标
+- **多源输入**：支持 `"screen"`、图片文件路径、URL 或 imageId
+- **绝对坐标**：裁剪区域内的结果会映射回原图或全屏坐标
+
+## 数据类型
+
+### OCR字符
+
+```typescript
+interface OCR字符 {
+  text: 字符串;
+  confidence: 数字;
+  x: 数字;
+  y: 数字;
+  ex: 数字;
+  ey: 数字;
+  width: 数字;
+  height: 数字;
+  centerX: 数字;
+  centerY: 数字;
+}
+```
+
+| 字段名               | 类型   | 描述                                   |
+| -------------------- | ------ | -------------------------------------- |
+| `OCR字符.text`       | 字符串 | 识别文本；查找结果中为命中的目标字符串 |
+| `confidence`         | 数字   | 置信度，范围为 0-1                     |
+| `x`, `y`             | 数字   | 结果区域左上角绝对坐标                 |
+| `ex`, `ey`           | 数字   | 结果区域右下角绝对坐标                 |
+| `width`, `height`    | 数字   | 结果区域宽度和高度                     |
+| `centerX`, `centerY` | 数字   | 结果区域中心点绝对坐标                 |
+
+## API 参考
+
+### 字库管理
+
+#### 加载字库 - 加载并缓存字库
+
+```typescript
+function 加载字库(字库资源路径: 字符串): 字符串 | null;
+```
+
+| 参数名         | 类型   | 是否必填 | 默认值 | 描述                                                                        |
+| -------------- | ------ | -------- | ------ | --------------------------------------------------------------------------- |
+| `字库资源路径` | 字符串 | 是       |        | 资源路径，运行时会自动处理 `res` 目录解析；常见写法如 `/fonts/default.json` |
+
+**返回值：**加载成功返回字库 ID，失败返回 `null`。加载后的字库 ID 会复用到后续识别与释放流程。
+
+```javascript
+const 字库ID = $点阵OCR.加载字库("/fonts/default.json");
+if (!字库ID) throw new Error("字库加载失败");
+```
+
+建议在脚本初始化时加载一次并保存字库 ID，后续识别时复用，不要每次识别都重新加载。
+
+### 文字识别
+
+#### 识别绝对坐标 - 识别文字并返回绝对坐标
+
+```typescript
+function 识别绝对坐标(
+  字库ID: 字符串,
+  输入源: 字符串,
+  左?: 数字,
+  上?: 数字,
+  右?: 数字,
+  下?: 数字,
+  置信度阈值?: 数字,
+): 数组<OCR字符>;
+```
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述                                                                                         |
+| ------------ | ------ | -------- | ------ | -------------------------------------------------------------------------------------------- |
+| `字库ID`     | 字符串 | 是       |        | `加载字库` 返回的字库 ID                                                                     |
+| `输入源`     | 字符串 | 是       |        | 输入源，支持 `"screen"`、图片文件路径、URL 或 imageId                                        |
+| `左`, `上`   | 数字   | 否       | 0      | 裁剪区域左上角坐标                                                                           |
+| `右`, `下`   | 数字   | 否       | 0      | 裁剪区域右下角坐标；`右` 或 `下` 为 0 时分别使用图像宽度或高度                               |
+| `置信度阈值` | 数字   | 否       | 0.8     | 相似度下限；`<=0` 时按 `0.8`；低于阈值的字符会被过滤；`>0.95` 时要求像素完全一致 |
+
+**返回值：**`数组<OCR字符>`。按行从上到下、同一行从左到右排列。颜色按字库各字自带的前景色/偏色匹配，无需额外传色。
+
+```javascript
+const 结果 = $点阵OCR.识别绝对坐标(字库ID, "screen", 100, 200, 600, 280, 0.8);
+$打印信息日志(结果[0]?.text);
+$打印信息日志(`坐标: ${结果[0]?.x}, ${结果[0]?.y}`);
+```
+
+### 文本查找
+
+#### 查找文本绝对坐标 - 查找指定字符串并返回绝对坐标
+
+```typescript
+function 查找文本绝对坐标(
+  字库ID: 字符串,
+  输入源: 字符串,
+  目标文本: 数组<字符串>,
+  左?: 数字,
+  上?: 数字,
+  右?: 数字,
+  下?: 数字,
+  置信度阈值?: 数字,
+  完整匹配?: 布尔值,
+): 数组<OCR字符>;
+```
+
+| 参数名       | 类型          | 是否必填 | 默认值 | 描述                                                                  |
+| ------------ | ------------- | -------- | ------ | --------------------------------------------------------------------- |
+| `字库ID`     | 字符串        | 是       |        | `加载字库` 返回的字库 ID                                              |
+| `输入源`     | 字符串        | 是       |        | 输入源，支持 `"screen"`、图片文件路径、URL 或 imageId                 |
+| `目标文本`   | 数组<字符串>  | 是       |        | 要查找的字符串数组，例如 `["商店", "背包"]`                           |
+| `左`, `上`   | 数字          | 否       | 0      | 裁剪区域左上角坐标                                                    |
+| `右`, `下`   | 数字          | 否       | 0      | 裁剪区域右下角坐标；`右` 或 `下` 为 0 时分别使用图像宽度或高度        |
+| `置信度阈值` | 数字          | 否       | 0.8    | 单字符识别相似度下限；语义同 `识别绝对坐标`                           |
+| `完整匹配`   | 布尔值        | 否       | false   | `false` 为行内子串包含匹配；`true` 要求某一整行文本完全等于目标字符串 |
+
+**返回值：**命中结果数组。每个目标最多返回一次命中（最先匹配到的行）；每项的 `text` 是目标字符串。
+
+```javascript
+const 命中 = $点阵OCR.查找文本绝对坐标(
+  字库ID,
+  "screen",
+  ["商店", "背包"],
+  100,
+  200,
+  600,
+  280,
+  0.8,
+  false,
+);
+if (命中.length > 0) $动作.点击(命中[0].centerX, 命中[0].centerY);
+```
+
+### 资源管理
+
+#### 释放 - 释放指定字库
+
+```typescript
+function 释放(字库ID: 字符串): void;
+```
+
+#### 释放全部 - 释放全部点阵字库
+
+```typescript
+function 释放全部(): void;
+```
+
+```javascript
+$点阵OCR.释放(字库ID);
+// 或在需要清理全部已加载的点阵字库时：
+$点阵OCR.释放全部();
+```

package/docs/apicn/node.md

@@ -90,6 +90,13 @@ interface $节点信息 {
   点击中心(): 布尔值; // 点击中心
   点击随机范围(): 布尔值; // 随机点击
   hittable(): 布尔值; // 节点是否可接收事件，用于判断节点是否在屏幕可见
+  tap(): 布尔值; // 无障碍点击
+  doubleTap(): 布尔值; // 无障碍双击
+  press(duration: 数字): 布尔值; // 无障碍长按，duration 单位毫秒
+  scrollToVisible(): 布尔值; // 将节点滚动到可见区域
+  clearInput(): 布尔值; // 清空输入
+  input(text: 字符串): 布尔值; // 追加输入（聚焦后输入）
+  setValue(text: 字符串): 布尔值; // 设置节点的值（见下方支持控件）
   parent(): $节点信息 | null; // 获取父节点
   child(index: 数字): $节点信息 | null; // 获取子节点
   allChildren(): $节点信息[]; // 获取所有子节点
@@ -274,16 +281,82 @@ const xpathElements = 选择器.xpath("//*[@title='快点JS']").获取所有节
 #### 点击操作
 
 ```typescript
-// 点击节点中心
+// 点击节点中心（坐标点击）
 node.点击中心(): 布尔值;
 
-// 随机点击节点区域
+// 随机点击节点区域（坐标点击）
 node.点击随机范围(): 布尔值;
 
 // 节点是否可接收事件（用于判断是否显示在屏幕上）
 node.hittable(): 布尔值;
+
+// 无障碍点击
+node.tap(): 布尔值;
+
+// 无障碍双击
+node.doubleTap(): 布尔值;
+
+// 无障碍长按，duration 单位毫秒
+node.press(duration: 数字): 布尔值;
+
+// 将节点滚动到可见区域
+node.scrollToVisible(): 布尔值;
+
+// 清空输入
+node.clearInput(): 布尔值;
+
+// 追加输入
+node.input(text: 字符串): 布尔值;
+
+// 设置节点的值
+node.setValue(text: 字符串): 布尔值;
 ```
 
+#### tap / doubleTap / press - 无障碍手势
+
+通过无障碍 API 直接操作节点，不依赖坐标点击。
+
+| 方法 | 参数 | 说明 |
+| --- | --- | --- |
+| `tap()` | 无 | 无障碍单击 |
+| `doubleTap()` | 无 | 无障碍双击 |
+| `press(duration)` | `duration`：长按持续时间，单位毫秒 | 无障碍长按 |
+
+**示例：**
+
+```typescript
+const 选择器 = $创建节点选择器();
+
+const btn = 选择器.label("确定").type("XCUIElementTypeButton").获取一个节点(3000);
+if (btn) {
+  // 无障碍单击
+  btn.tap();
+
+  // 无障碍双击
+  btn.doubleTap();
+
+  // 无障碍长按 800ms
+  btn.press(800);
+}
+
+// 释放选择器内存
+选择器.释放内存();
+```
+
+#### setValue - 设置节点的值
+
+按控件类型自动处理，常用支持如下：
+
+| 控件类型 | 传参示例 | 说明 |
+| --- | --- | --- |
+| `XCUIElementTypePickerWheel` | `"1小时"` | 滚轮选到对应选项文案 |
+| `XCUIElementTypeTextField` | `"hello"` | 先聚焦再输入文本 |
+| `XCUIElementTypeSecureTextField` | `"123456"` | 同上 |
+| `XCUIElementTypeTextView` | `"多行内容"` | 同上 |
+| `XCUIElementTypeSearchField` | `"关键词"` | 同上 |
+
+文本类控件不会先清空已有内容；需要清空时先调用 `clearInput()`。
+
 **示例：**
 
 ```typescript
@@ -298,12 +371,25 @@ if (confirmBtn) {
   const isHittable = confirmBtn.hittable();
   $打印信息日志(`是否可接收事件: ${isHittable}`);
 
-  const clicked = confirmBtn.点击中心();
+  confirmBtn.scrollToVisible();
+  // 优先使用无障碍点击；也可用 点击中心 / 点击随机范围 做坐标点击
+  const clicked = confirmBtn.tap();
   if (clicked) {
     $打印信息日志("成功点击确定按钮");
   }
 }
 
+const field = 选择器.type("XCUIElementTypeTextField").获取一个节点(3000);
+if (field) {
+  field.clearInput();
+  field.setValue("hello");
+}
+
+const wheel = 选择器.type("XCUIElementTypePickerWheel").获取一个节点(3000);
+if (wheel) {
+  wheel.setValue("1小时");
+}
+
 // 随机点击避免检测
 const randomClick = confirmBtn?.点击随机范围();
 if (randomClick) {

package/docs/apipython/dotocr.md

@@ -0,0 +1,148 @@
+# 点阵 OCR 模块（dotocr）
+
+`dotocr` 使用图色工具生成的固定像素点阵字库识别文字。字库保存在项目的 `res/fonts` 目录，使用方式与 YOLO 模型一致：先加载资源取得字库 ID，再复用该 ID 进行识别，使用完毕后释放。
+
+点阵模板按照制作时的原始像素尺寸匹配，不会自动缩放到其他分辨率。目标文字的字号、缩放比例或像素形状发生变化时，应制作对应的字库特征。
+
+## 数据类型
+
+### OCRChar
+
+```python
+from kuaijs._types import KuaiJSNamespace
+
+class OCRChar(KuaiJSNamespace):
+    text: str
+    confidence: float
+    x: int
+    y: int
+    ex: int
+    ey: int
+    width: int
+    height: int
+    centerX: int
+    centerY: int
+```
+
+| 字段名               | 类型  | 描述                                   |
+| -------------------- | ----- | -------------------------------------- |
+| `OCRChar.text`       | str   | 识别文本；查找结果中为命中的目标字符串 |
+| `confidence`         | float | 置信度，范围为 0-1                     |
+| `x`, `y`             | int   | 结果区域左上角绝对坐标                 |
+| `ex`, `ey`           | int   | 结果区域右下角绝对坐标                 |
+| `width`, `height`    | int   | 结果区域宽度和高度                     |
+| `centerX`, `centerY` | int   | 结果区域中心点绝对坐标                 |
+
+## API 参考
+
+### 字库管理
+
+#### `loadFont` - 加载并缓存字库
+
+```python
+def loadFont(fontPath: str) -> Optional[str]
+```
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                                                                        |
+| ---------- | ---- | -------- | ------ | --------------------------------------------------------------------------- |
+| `fontPath` | str  | 是       |        | 资源路径，运行时会自动处理 `res` 目录解析；常见写法如 `/fonts/default.json` |
+
+**返回值：**加载成功返回 `fontId`，失败返回 `None`。加载后的字库 ID 会复用到后续识别与释放流程。
+
+```python
+from kuaijs import dotocr
+
+font_id = dotocr.loadFont("/fonts/default.json")
+if not font_id:
+    raise RuntimeError("字库加载失败")
+```
+
+建议在脚本初始化时加载一次并保存 `font_id`，后续识别时复用，不要每次识别都重新加载。
+
+### 文字识别
+
+#### `recognizeAbs` - 识别文字并返回绝对坐标
+
+```python
+def recognizeAbs(
+    fontId: str,
+    input: str,
+    x: int = 0,
+    y: int = 0,
+    ex: int = 0,
+    ey: int = 0,
+    confidenceThreshold: float = 0.8,
+) -> List[OCRChar]
+```
+
+| 参数名                | 类型  | 是否必填 | 默认值 | 描述                                                                                         |
+| --------------------- | ----- | -------- | ------ | -------------------------------------------------------------------------------------------- |
+| `fontId`              | str   | 是       |        | `loadFont` 返回的字库 ID                                                                     |
+| `input`               | str   | 是       |        | 输入源，支持 `"screen"`、图片文件路径、URL 或 imageId                                        |
+| `x`, `y`              | int   | 否       | 0      | 裁剪区域左上角坐标                                                                           |
+| `ex`, `ey`            | int   | 否       | 0      | 裁剪区域右下角坐标；`ex` 或 `ey` 为 0 时分别使用图像宽度或高度                               |
+| `confidenceThreshold` | float   | 否       | 0.8     | 相似度下限；`<=0` 时按 `0.8`；低于阈值的字符会被过滤；`>0.95` 时要求像素完全一致 |
+
+**返回值：**`List[OCRChar]`。按行从上到下、同一行从左到右排列。颜色按字库各字自带的前景色/偏色匹配，无需额外传色。
+
+```python
+chars = dotocr.recognizeAbs(font_id, "screen", 100, 200, 600, 280, 0.8)
+if chars:
+    print(chars[0].text, chars[0].x, chars[0].width)
+```
+
+### 文本查找
+
+#### `findTextAbs` - 查找指定字符串并返回绝对坐标
+
+```python
+def findTextAbs(
+    fontId: str,
+    input: str,
+    targetTexts: List[str],
+    x: int = 0,
+    y: int = 0,
+    ex: int = 0,
+    ey: int = 0,
+    confidenceThreshold: float = 0.8,
+    exactMatch: bool = False,
+) -> List[OCRChar]
+```
+
+| 参数名                | 类型      | 是否必填 | 默认值 | 描述                                                                  |
+| --------------------- | --------- | -------- | ------ | --------------------------------------------------------------------- |
+| `fontId`              | str       | 是       |        | `loadFont` 返回的字库 ID                                              |
+| `input`               | str       | 是       |        | 输入源，支持 `"screen"`、图片文件路径、URL 或 imageId                 |
+| `targetTexts`         | List[str] | 是       |        | 要查找的字符串数组，例如 `["商店", "背包"]`                           |
+| `x`, `y`              | int       | 否       | 0      | 裁剪区域左上角坐标                                                    |
+| `ex`, `ey`            | int       | 否       | 0      | 裁剪区域右下角坐标；`ex` 或 `ey` 为 0 时分别使用图像宽度或高度        |
+| `confidenceThreshold` | float     | 否       | 0.8    | 单字符识别相似度下限；语义同 `recognizeAbs`                           |
+| `exactMatch`          | bool      | 否       | false   | `false` 为行内子串包含匹配；`true` 要求某一整行文本完全等于目标字符串 |
+
+**返回值：**命中结果数组。每个目标最多返回一次命中（最先匹配到的行）；每项的 `text` 是目标字符串。
+
+```python
+hits = dotocr.findTextAbs(font_id, "screen", ["商店", "背包"], 100, 200, 600, 280, 0.8, False)
+if hits:
+    action.click(hits[0].centerX, hits[0].centerY)
+```
+
+### 资源管理
+
+#### `free` - 释放指定字库
+
+```python
+def free(fontId: str) -> None
+```
+
+#### `freeAll` - 释放全部点阵字库
+
+```python
+def freeAll() -> None
+```
+
+```python
+dotocr.free(font_id)
+# 或在需要清理全部已加载的点阵字库时：
+dotocr.freeAll()
+```

package/docs/apipython/node.md

@@ -37,6 +37,13 @@ class NodeInfo:
     def clickCenter(self) -> bool: ...
     def clickRandom(self) -> bool: ...
     def hittable(self) -> bool: ...
+    def tap(self) -> bool: ...
+    def doubleTap(self) -> bool: ...
+    def press(self, duration: int = 500) -> bool: ...
+    def scrollToVisible(self) -> bool: ...
+    def clearInput(self) -> bool: ...
+    def input(self, text: str) -> bool: ...
+    def setValue(self, text: str) -> bool: ...
     def parent(self) -> Optional["NodeInfo"]: ...
     def child(self, index: int) -> Optional["NodeInfo"]: ...
     def allChildren(self) -> List["NodeInfo"]: ...
@@ -253,16 +260,80 @@ xpath_elements = selector.xpath("//*[@title='快点JS']").getNodeInfo(3000)
 ### 点击操作
 
 ```python
-# 点击节点中心
+# 点击节点中心（坐标点击）
 def clickCenter() -> bool
 
-# 随机点击节点区域
+# 随机点击节点区域（坐标点击）
 def clickRandom() -> bool
 
 # 节点是否可接收事件（用于判断是否显示在屏幕上）
 def hittable() -> bool
+
+# 无障碍点击
+def tap() -> bool
+
+# 无障碍双击
+def doubleTap() -> bool
+
+# 无障碍长按，duration 单位毫秒，默认 500
+def press(duration: int = 500) -> bool
+
+# 将节点滚动到可见区域
+def scrollToVisible() -> bool
+
+# 清空输入
+def clearInput() -> bool
+
+# 追加输入
+def input(text: str) -> bool
+
+# 设置节点的值
+def setValue(text: str) -> bool
 ```
 
+#### tap / doubleTap / press - 无障碍手势
+
+通过无障碍 API 直接操作节点，不依赖坐标点击。
+
+| 方法 | 参数 | 说明 |
+| --- | --- | --- |
+| `tap()` | 无 | 无障碍单击 |
+| `doubleTap()` | 无 | 无障碍双击 |
+| `press(duration=500)` | `duration`：长按持续时间，单位毫秒，默认 500 | 无障碍长按 |
+
+**示例：**
+
+```python
+from kuaijs import node
+
+selector = node.createNodeSelector()
+
+btn = selector.label("确定").type("XCUIElementTypeButton").getOneNodeInfo(3000)
+if btn:
+    # 无障碍单击
+    btn.tap()
+
+    # 无障碍双击
+    btn.doubleTap()
+
+    # 无障碍长按 800ms
+    btn.press(800)
+```
+
+#### setValue - 设置节点的值
+
+按控件类型自动处理，常用支持如下：
+
+| 控件类型 | 传参示例 | 说明 |
+| --- | --- | --- |
+| `XCUIElementTypePickerWheel` | `"1小时"` | 滚轮选到对应选项文案 |
+| `XCUIElementTypeTextField` | `"hello"` | 先聚焦再输入文本 |
+| `XCUIElementTypeSecureTextField` | `"123456"` | 同上 |
+| `XCUIElementTypeTextView` | `"多行内容"` | 同上 |
+| `XCUIElementTypeSearchField` | `"关键词"` | 同上 |
+
+文本类控件不会先清空已有内容；需要清空时先调用 `clearInput()`。
+
 **示例：**
 
 ```python
@@ -276,12 +347,23 @@ confirm_btn = selector.label("确定").type("XCUIElementTypeButton").getOneNodeI
 if confirm_btn:
     print(f"是否可接收事件: {confirm_btn.hittable()}")
 
-    clicked = confirm_btn.clickCenter()
+    confirm_btn.scrollToVisible()
+    # 优先使用无障碍点击；也可用 clickCenter / clickRandom 做坐标点击
+    clicked = confirm_btn.tap()
     if clicked:
         print("成功点击确定按钮")
 
-    # 随机点击避免检测
+    # 随机坐标点击避免检测
     confirm_btn.clickRandom()
+
+field = selector.type("XCUIElementTypeTextField").getOneNodeInfo(3000)
+if field:
+    field.clearInput()
+    field.setValue("hello")
+
+wheel = selector.type("XCUIElementTypePickerWheel").getOneNodeInfo(3000)
+if wheel:
+    wheel.setValue("1小时")
 ```
 
 ### 节点导航

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms-vite-plugin",
-  "version": "1.4.39",
+  "version": "1.4.41",
   "type": "commonjs",
   "license": "MIT",
   "publishConfig": {