ms-vite-plugin 1.4.41 → 1.4.45

package/docs/apicn/node.md

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