ms-vite-plugin 1.4.40 → 1.4.43

package/docs/api/dotocr.md

@@ -75,7 +75,7 @@ function recognizeAbs(
   y?: number,
   ex?: number,
   ey?: number,
-  confidenceThreshold?: number,
+  confidenceThreshold?: number
 ): OCRChar[];
 ```
 
@@ -85,7 +85,7 @@ function recognizeAbs(
 | `input`               | string | 是       |        | 输入源，支持 `"screen"`、图片文件路径、URL 或 imageId                                        |
 | `x`, `y`              | number | 否       | 0      | 裁剪区域左上角坐标                                                                           |
 | `ex`, `ey`            | number | 否       | 0      | 裁剪区域右下角坐标；`ex` 或 `ey` 为 0 时分别使用图像宽度或高度                               |
-| `confidenceThreshold` | number | 否       | 0.8    | 相似度下限；`<=0` 时按 `0.8`；低于阈值的字符会被过滤；`>0.95` 时要求模板与图像像素完全一致 |
+| `confidenceThreshold` | number  | 否       | 0.8     | 相似度下限；`<=0` 时按 `0.8`；低于阈值的字符会被过滤；`>0.95` 时要求像素完全一致 |
 
 **返回值：**`OCRChar[]`。按行从上到下、同一行从左到右排列。颜色按字库各字自带的前景色/偏色匹配，无需额外传色。
 
@@ -108,7 +108,7 @@ function findTextAbs(
   ex?: number,
   ey?: number,
   confidenceThreshold?: number,
-  exactMatch?: boolean,
+  exactMatch?: boolean
 ): OCRChar[];
 ```
 
@@ -120,7 +120,7 @@ function findTextAbs(
 | `x`, `y`              | number   | 否       | 0      | 裁剪区域左上角坐标                                                    |
 | `ex`, `ey`            | number   | 否       | 0      | 裁剪区域右下角坐标；`ex` 或 `ey` 为 0 时分别使用图像宽度或高度        |
 | `confidenceThreshold` | number   | 否       | 0.8    | 单字符识别相似度下限；语义同 `recognizeAbs`                           |
-| `exactMatch`          | boolean  | 否       | false  | `false` 为行内子串包含匹配；`true` 要求某一整行文本完全等于目标字符串 |
+| `exactMatch`          | boolean  | 否       | false   | `false` 为行内子串包含匹配；`true` 要求某一整行文本完全等于目标字符串 |
 
 **返回值：**命中结果数组。每个目标最多返回一次命中（最先匹配到的行）；每项的 `text` 是目标字符串。
 

package/docs/api/node.md

@@ -1,352 +1,328 @@
 # 节点模块 (Node)
 
-节点模块提供了强大的 UI 元素访问和操作功能，可以通过各种条件选择和操作界面元素。
+用于查找和操作当前界面上的控件节点。
 
-**注意事项**
+**注意**
 
-- 此模块仅支持 快点 Agent 模式使用
-- 节点用完需要调用 `releaseNode` 方法释放内存，找完节点就能释放，不需要点击后释放
+- 仅支持快点 Agent 模式
+- 用完调用 `releaseNode()` 释放；找完节点即可释放，不必等点击结束
 
-## 节点选择器 (NodeSelector)
+**基本流程**
 
-节点选择器是访问 UI 元素的核心工具，提供了灵活的筛选和查找机制。
-
-### 创建节点选择器
+```text
+createNodeSelector → 设置筛选条件 → getOneNodeInfo / getNodeInfo
+→ 点击 / 输入 / 设值等 → releaseNode
+```
 
-#### createNodeSelector - 创建节点选择器
+---
 
-创建一个新的节点选择器实例。
+## 创建选择器
 
 ```typescript
 function createNodeSelector(params?: {
-  maxDepth?: number; // 最大层级深度，默认 50
-  mode?: number; // 抓取模式：模式 1、模式 2、模式 3，默认模式 1
+  maxDepth?: number; // 最大层级，默认 50；越小通常越快
+  mode?: number; // 抓取模式 1 | 2 | 3，默认 1
 }): NodeSelector;
 ```
 
-**参数说明：**
-
-| 参数名     | 类型   | 是否必填 | 默认值 | 描述                        |
-| ---------- | ------ | -------- | ------ | --------------------------- |
-| `maxDepth` | number | 否       | 50     | 遍历的最大层级深度，默认 50 |
-| `mode` | number | 否       | 1      | 抓取模式。支持模式 1、模式 2、模式 3，默认模式 1 |
-
-**返回值：**
-
-| 类型           | 描述                   |
-| -------------- | ---------------------- |
-| `NodeSelector` | 新创建的节点选择器实例 |
-
-**示例：**
-
-```typescript
-// 创建选择器
-const selector = createNodeSelector({
-  maxDepth: 20, // 最大20层深度
-  mode: 1, // 默认模式 1
-});
-```
-
-### 节点信息接口
-
-#### NodeBoundsInfo - 节点边界信息。
+| 参数 | 默认 | 说明 |
+| --- | --- | --- |
+| `maxDepth` | `50` | 抓取深度，深层控件抓不到时可调大 |
+| `mode` | `1` | 抓取模式，可选 `1` / `2` / `3`，默认 `1` |
 
 ```typescript
-interface NodeBoundsInfo {
-  x: number; // x坐标
-  y: number; // y坐标
-  width: number; // 宽度
-  height: number; // 高度
-  centerX: number; // 中心点x坐标
-  centerY: number; // 中心点y坐标
-}
+const selector = createNodeSelector();
+const shallow = createNodeSelector({ maxDepth: 15 });
+const listPage = createNodeSelector({ mode: 2 });
 ```
 
-#### NodeInfo - 节点详细信息。
+---
+
+## 节点信息
+
+### 位置 `NodeBoundsInfo`
+
+| 字段 | 说明 |
+| --- | --- |
+| `x` / `y` | 左上角 |
+| `width` / `height` | 宽高 |
+| `centerX` / `centerY` | 中心点 |
+
+### 节点 `NodeInfo`
+
+**属性**
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 节点 ID（内部定位用，不要改） |
+| `identifier` | 控件标识符 |
+| `label` | 标签文案 |
+| `type` | 类型，如 `XCUIElementTypeButton` |
+| `value` | 当前值 |
+| `placeholderValue` | 输入框占位文字 |
+| `title` | 标题 |
+| `enabled` | 是否启用 |
+| `bounds` | 位置大小 |
+| `depth` | 层级 |
+| `index` | 在父节点下的序号 |
+| `parentId` | 父节点 ID |
+| `childCount` | 子节点数量 |
+
+**方法**
+
+| 方法 | 说明 |
+| --- | --- |
+| `hittable()` | 当前是否可点击（可见且未被挡住） |
+| `scrollToVisible()` | 滚动到可见区域 |
+| `tap()` | 单击（不可见时会先尝试滚到可见） |
+| `doubleTap()` | 双击 |
+| `press(duration?)` | 长按，`duration` 单位毫秒，默认 500 |
+| `clickCenter()` | 点击中心坐标 |
+| `clickRandom()` | 在节点范围内随机点击 |
+| `clearInput()` | 清空输入内容 |
+| `input(text)` | 追加输入（不先清空） |
+| `setValue(text)` | 设置值（见下方） |
+| `parent()` | 父节点 |
+| `child(index)` | 第 `index` 个子节点 |
+| `allChildren()` | 全部子节点 |
+| `siblings()` | 全部兄弟节点 |
+| `previousSiblings()` | 前面的兄弟 |
+| `nextSiblings()` | 后面的兄弟 |
+
+---
+
+## 选择器方法
+
+### 加载与结果
+
+| 方法 | 说明 |
+| --- | --- |
+| `releaseNode()` | 释放内存 |
+| `loadNode(timeout?)` | 重新加载界面节点，默认超时 5000ms |
+| `clearSelector()` | 清除已设置的筛选条件 |
+| `xml(timeout?)` | 获取界面 XML，失败返回 `null` |
+| `getNodeInfo(timeout?)` | 获取所有匹配节点 |
+| `getOneNodeInfo(timeout?)` | 获取第一个匹配节点，没有则 `null` |
+
+`timeout` 单位均为毫秒，默认 `5000`。
 
 ```typescript
-interface NodeInfo {
-  id: string; // 节点ID
-  identifier: string; // 节点标识符
-  label: string; // 节点标签
-  type: string; // 节点类型
-  value: string; // 节点值
-  placeholderValue: string; // 节点占位符值
-  title: string; // 节点名称
-  enabled: boolean; // 是否启用
-  bounds: NodeBoundsInfo; // 边界信息
-  depth: number; // 层级深度
-  index: number; // 索引
-  parentId: string; // 父节点ID
-  childCount: number; // 子节点数量
-
-  // 操作方法
-  clickCenter(): boolean; // 点击中心
-  clickRandom(): boolean; // 随机点击
-  hittable(): boolean; // 节点是否可接收事件，用于判断节点是否在屏幕可见
-  parent(): NodeInfo | null; // 获取父节点
-  child(index: number): NodeInfo | null; // 获取子节点
-  allChildren(): NodeInfo[]; // 获取所有子节点
-  siblings(): NodeInfo[]; // 获取兄弟节点
-  previousSiblings(): NodeInfo[]; // 获取前面的兄弟节点
-  nextSiblings(): NodeInfo[]; // 获取后面的兄弟节点
-}
+const selector = createNodeSelector();
+const nodes = selector.label("确定").getNodeInfo(5000);
+const one = selector.getOneNodeInfo(3000);
+const xml = selector.xml();
+selector.releaseNode();
 ```
 
-### 选择器方法
+### 筛选条件
 
-#### 获取节点
+可链式调用，多个条件同时满足（并且关系）。  
+带 `Match` 的为模糊/正则匹配。
 
-```typescript
-// releaseNode - 释放内存
-releaseNode(): void;
+**文本**
 
-// xml - 获取当前页面的 XML 字符串
-xml(timeout?: number): string | null;
+| 方法 | 说明 |
+| --- | --- |
+| `label` / `labelMatch` | 标签 |
+| `title` / `titleMatch` | 标题 |
+| `identifier` / `identifierMatch` | 标识符 |
+| `value` / `valueMatch` | 值 |
+| `placeholderValue` / `placeholderValueMatch` | 占位文字 |
 
-// 获取多个节点
-getNodeInfo(timeout?: number): NodeInfo[]
+**类型与状态**
 
-// 获取单个节点
-getOneNodeInfo(timeout?: number): NodeInfo | null
+| 方法 | 说明 |
+| --- | --- |
+| `type` / `typeMatch` | 类型，如 `XCUIElementTypeButton` |
+| `enabled` | 是否启用 |
 
-// 加载节点数据
-loadNode(timeout?: number): NodeSelector;
+**位置与结构**
 
-// 清除所有选择条件
-clearSelector(): NodeSelector;
-```
-
-**示例：**
+| 方法 | 说明 |
+| --- | --- |
+| `index` | 序号 |
+| `depth` | 层级 |
+| `childCount` | 子节点数，支持数字或如 `">0"` |
+| `bounds(x, y, width, height)` | 区域 |
+| `xpath` | XPath |
+| `id` | 按节点 ID |
 
 ```typescript
-const selector = createNodeSelector();
+// 精确
+selector.label("确定").type("XCUIElementTypeButton").getOneNodeInfo(3000);
 
-// 获取所有匹配的节点
-const allNodes = selector.getNodeInfo(5000);
-logi(`找到 ${allNodes.length} 个节点`);
+// 模糊
+selector.labelMatch(".*登录.*").getNodeInfo(3000);
+selector.identifierMatch("^login_").getNodeInfo(3000);
 
-// 获取第一个匹配的节点
-const firstNode = selector.getOneNodeInfo(3000);
-if (firstNode) {
-  logi(`节点标签: ${firstNode.label}`);
-}
-
-selector.releaseNode();
+// 组合
+selector
+  .type("XCUIElementTypeTextField")
+  .enabled(true)
+  .getOneNodeInfo(3000);
 ```
 
-#### 条件筛选
-
-##### 文本相关
-
-```typescript
-// 精确匹配标签
-label(label: string): NodeSelector
-
-// 标签模糊匹配
-labelMatch(match: string): NodeSelector
+常见类型：`XCUIElementTypeButton`、`StaticText`、`TextField`、`SecureTextField`、`TextView`、`SearchField`、`Cell`、`Table`、`CollectionView`、`PickerWheel`、`Switch`、`Slider` 等。
 
-// 精确匹配名称
-title(title: string): NodeSelector
+---
 
-// 名称模糊匹配
-titleMatch(match: string): NodeSelector
+## 节点操作说明
 
-// 精确匹配标识符
-identifier(identifier: string): NodeSelector
-
-// 标识符模糊匹配
-identifierMatch(match: string): NodeSelector
-
-// 精确匹配值
-value(value: string): NodeSelector
-
-// 值模糊匹配
-valueMatch(match: string): NodeSelector
-```
-
-**示例：**
+### 是否可点 / 滚到可见
 
 ```typescript
-// 查找标签为"确定"的按钮
-const confirmButton = selector.label("确定").getOneNodeInfo(3000);
-
-// 查找包含"登录"的元素
-const loginElements = selector.labelMatch(".*登录.*").getNodeInfo(3000);
-
-// 查找名称包含"button"的元素
-const buttons = selector.titleMatch("button").getNodeInfo(3000);
-
-// 查找值为"submit"的元素
-const submitElement = selector.value("submit").getOneNodeInfo(2000);
-
-// 通过标识符查找
-const elById = selector.identifier("login_btn").getOneNodeInfo(2000);
-const fuzzy = selector.identifierMatch("^login_.*").getNodeInfo(3000);
+if (node.hittable()) {
+  node.tap();
+} else {
+  node.scrollToVisible();
+  node.tap();
+}
 ```
 
-##### 类型和属性
+- `hittable()`：当前能否点到  
+- `scrollToVisible()`：手动滚到可见  
+- `tap` / `doubleTap` / `press`：不可见时会自动尝试滚到可见再操作  
 
-```typescript
-// 精确匹配类型
-type(type: string): NodeSelector
+### 点击
 
-// 类型模糊匹配
-typeMatch(match: string): NodeSelector
-
-// 启用状态
-enabled(enabled: boolean): NodeSelector
-```
-
-**示例：**
+| 方法 | 说明 |
+| --- | --- |
+| `tap()` | 推荐，单击 |
+| `doubleTap()` | 双击 |
+| `press(ms?)` | 长按，默认 500ms |
+| `clickCenter()` | 点中心坐标 |
+| `clickRandom()` | 范围内随机点 |
 
 ```typescript
-const selector = createNodeSelector();
-// 查找所有按钮
-const allButtons = selector.type("XCUIElementTypeButton").getNodeInfo(3000);
-
-// 查找所有文本框
-const textFields = selector
-  .typeMatch("XCUIElementTypeTextField")
-  .getNodeInfo(3000);
-
-// 查找启用的元素
-const enabledElements = selector.enabled(true).getNodeInfo(3000);
+const btn = selector
+  .label("确定")
+  .type("XCUIElementTypeButton")
+  .getOneNodeInfo(3000);
 
-selector.releaseNode();
+if (btn) {
+  btn.tap();
+  btn.doubleTap();
+  btn.press(800);
+}
 ```
 
-##### 位置和结构
+### 输入与设值
 
-```typescript
-// 索引位置
-index(index: number): NodeSelector
+| 方法 | 说明 |
+| --- | --- |
+| `clearInput()` | 清空 |
+| `input(text)` | 追加输入，不清空原内容 |
+| `setValue(text)` | 按控件类型设置 |
 
-// 层级深度
-depth(depth: number): NodeSelector
+**`setValue` 行为**
 
-// 子节点数量
-childCount(childCount: number | string): NodeSelector
+| 控件类型 | 传参 | 效果 |
+| --- | --- | --- |
+| `PickerWheel` | 选项文案，如 `"1小时"` | 滚到该选项 |
+| 文本框类（TextField 等） | 字符串 | 聚焦后追加输入，不先清空 |
 
-// 边界范围
-bounds(x: number, y: number, width: number, height: number): NodeSelector
+覆盖原内容请先清空：
 
-// XPath 路径
-xpath(path: string): NodeSelector
+```typescript
+field.clearInput();
+field.setValue("hello");
+// 或
+field.clearInput();
+field.input("hello");
 ```
 
-**示例：**
-
 ```typescript
-const selector = createNodeSelector();
-
-// 查找第一个元素
-const firstElement = selector.index(0).getOneNodeInfo(2000);
-
-// 查找特定深度的元素
-const level3Elements = selector.depth(3).getNodeInfo(3000);
-
-// 查找有子节点的元素
-const parentElements = selector.childCount(">0").getNodeInfo(3000);
-
-// 查找特定区域的元素
-const regionElements = selector.bounds(100, 100, 200, 50).getNodeInfo(3000);
-
-// 使用 XPath 查找
-const xpathElements = selector.xpath("//*[@title='快点JS']").getNodeInfo(3000);
-
-selector.releaseNode();
+const wheel = selector.type("XCUIElementTypePickerWheel").getOneNodeInfo(3000);
+if (wheel) {
+  wheel.setValue("1小时");
+}
 ```
 
-### 节点操作
-
-#### 点击操作
+### 树导航
 
 ```typescript
-// 点击节点中心
-node.clickCenter(): boolean;
+const field = selector.type("XCUIElementTypeTextField").getOneNodeInfo(3000);
+if (field) {
+  const parent = field.parent();
+  const children = parent?.allChildren() ?? [];
+  const prev = field.previousSiblings();
+  const next = field.nextSiblings();
+  const second = parent?.child(1);
+}
+```
 
-// 随机点击节点区域
-node.clickRandom(): boolean;
+---
 
-// 节点是否可接收事件（用于判断是否显示在屏幕上）
-node.hittable(): boolean;
-```
+## 示例
 
-**示例：**
+### 登录
 
 ```typescript
 const selector = createNodeSelector();
 
-// 查找并点击确定按钮
-const confirmBtn = selector
-  .label("确定")
-  .type("XCUIElementTypeButton")
-  .getOneNodeInfo(3000);
+try {
+  const user = selector.type("XCUIElementTypeTextField").getOneNodeInfo(5000);
+  if (user) {
+    user.clearInput();
+    user.setValue("demo_user");
+  }
 
-if (confirmBtn) {
-  const isHittable = confirmBtn.hittable();
-  logi(`是否可接收事件: ${isHittable}`);
+  const pass = selector
+    .clearSelector()
+    .type("XCUIElementTypeSecureTextField")
+    .getOneNodeInfo(3000);
+  if (pass) {
+    pass.clearInput();
+    pass.setValue("password");
+  }
 
-  const clicked = confirmBtn.clickCenter();
-  if (clicked) {
-    logi("成功点击确定按钮");
+  const login = selector
+    .clearSelector()
+    .labelMatch(".*登录.*")
+    .type("XCUIElementTypeButton")
+    .getOneNodeInfo(3000);
+  if (login) {
+    login.tap();
   }
+} finally {
+  selector.releaseNode();
 }
-
-// 随机点击避免检测
-const randomClick = confirmBtn?.clickRandom();
-
-selector.releaseNode();
 ```
 
-#### 节点导航
+### 列表里靠后的项
 
 ```typescript
-// 获取父节点
-node.parent(): NodeInfo | null
-
-// 获取指定索引的子节点
-node.child(index: number): NodeInfo | null
-
-// 获取所有子节点
-node.allChildren(): NodeInfo[]
-
-// 获取兄弟节点
-node.siblings(): NodeInfo[]
-
-// 获取前面的兄弟节点
-node.previousSiblings(): NodeInfo[]
-
-// 获取后面的兄弟节点
-node.nextSiblings(): NodeInfo[]
+const selector = createNodeSelector({ mode: 2 });
+const item = selector.label("第 30 项").getOneNodeInfo(5000);
+if (item) {
+  item.tap(); // 不在可见区域时会自动滚动
+}
+selector.releaseNode();
 ```
 
-**示例：**
+### 查看界面结构
 
 ```typescript
 const selector = createNodeSelector();
+const xml = selector.xml(8000);
+if (xml) {
+  logi(xml);
+}
+selector.releaseNode();
+```
 
-// 查找输入框并获取其父容器
-const textField = selector
-  .type("XCUIElementTypeTextField")
-  .getOneNodeInfo(3000);
+---
 
-if (textField) {
-  const container = textField.parent();
-  if (container) {
-    logi(`容器类型: ${container.type}`);
+## 常见问题
 
-    // 获取容器的所有子元素
-    const siblings = container.allChildren();
-    logi(`容器包含 ${siblings.length} 个子元素`);
+**找不到节点**  
+加大超时；减少条件或改用 `*Match`；换 `mode`；用 `xml()` 看实际文案和类型。
 
-    // 查找同级的按钮
-    const siblingButtons = siblings.filter(
-      (node) => node.type === "XCUIElementTypeButton",
-    );
-  }
-}
+**点了没反应**  
+先看 `hittable()`；确认点到的是目标控件；可对比 `clickCenter()`。
 
-selector.releaseNode();
-```
+**输入叠在旧文字后面**  
+`input` / 文本类 `setValue` 是追加，先 `clearInput()`。
+
+**滚轮设不中**  
+`setValue` 要传界面上显示的选项文案；确认类型是 `PickerWheel`；多列时选对那一列。