npm - ms-vite-plugin - Versions diffs - 1.4.41 → 1.4.43 - Mend

ms-vite-plugin 1.4.41 → 1.4.43

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/docs/api/node.md +238 -349
package/docs/apicn/node.md +241 -366
package/docs/apipython/node.md +184 -288
package/package.json +1 -1

package/docs/api/node.md CHANGED Viewed

@@ -1,439 +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 - 节点边界信息。
-```typescript
-interface NodeBoundsInfo {
-  x: number; // x坐标
-  y: number; // y坐标
-  width: number; // 宽度
-  height: number; // 高度
-  centerX: number; // 中心点x坐标
-  centerY: number; // 中心点y坐标
-}
-```
-#### NodeInfo - 节点详细信息。
-```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; // 节点是否可接收事件，用于判断节点是否在屏幕可见
-  tap(): boolean; // 无障碍点击
-  doubleTap(): boolean; // 无障碍双击
-  press(duration: number): boolean; // 无障碍长按，duration 单位毫秒
-  scrollToVisible(): boolean; // 将节点滚动到可见区域
-  clearInput(): boolean; // 清空输入
-  input(text: string): boolean; // 追加输入（聚焦后输入）
-  setValue(text: string): boolean; // 设置节点的值（见下方支持控件）
-  parent(): NodeInfo | null; // 获取父节点
-  child(index: number): NodeInfo | null; // 获取子节点
-  allChildren(): NodeInfo[]; // 获取所有子节点
-  siblings(): NodeInfo[]; // 获取兄弟节点
-  previousSiblings(): NodeInfo[]; // 获取前面的兄弟节点
-  nextSiblings(): NodeInfo[]; // 获取后面的兄弟节点
-}
-```
-### 选择器方法
-#### 获取节点
+| 参数 | 默认 | 说明 |
+| --- | --- | --- |
+| `maxDepth` | `50` | 抓取深度，深层控件抓不到时可调大 |
+| `mode` | `1` | 抓取模式，可选 `1` / `2` / `3`，默认 `1` |
 ```typescript
-// releaseNode - 释放内存
-releaseNode(): void;
-// xml - 获取当前页面的 XML 字符串
-xml(timeout?: number): string | null;
-// 获取多个节点
-getNodeInfo(timeout?: number): NodeInfo[]
-// 获取单个节点
-getOneNodeInfo(timeout?: number): NodeInfo | null
-// 加载节点数据
-loadNode(timeout?: number): NodeSelector;
-// 清除所有选择条件
-clearSelector(): NodeSelector;
+const selector = createNodeSelector();
+const shallow = createNodeSelector({ maxDepth: 15 });
+const listPage = createNodeSelector({ mode: 2 });
 ```
-**示例：**
+---
+## 节点信息
+### 位置 `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
 const selector = createNodeSelector();
-// 获取所有匹配的节点
-const allNodes = selector.getNodeInfo(5000);
-logi(`找到 ${allNodes.length} 个节点`);
-// 获取第一个匹配的节点
-const firstNode = selector.getOneNodeInfo(3000);
-if (firstNode) {
-  logi(`节点标签: ${firstNode.label}`);
-}
+const nodes = selector.label("确定").getNodeInfo(5000);
+const one = selector.getOneNodeInfo(3000);
+const xml = selector.xml();
 selector.releaseNode();
 ```
-#### 条件筛选
-##### 文本相关
+### 筛选条件
-```typescript
-// 精确匹配标签
-label(label: string): NodeSelector
-// 标签模糊匹配
-labelMatch(match: string): NodeSelector
+可链式调用，多个条件同时满足（并且关系）。
+带 `Match` 的为模糊/正则匹配。
-// 精确匹配名称
-title(title: string): NodeSelector
+**文本**
-// 名称模糊匹配
-titleMatch(match: string): NodeSelector
+| 方法 | 说明 |
+| --- | --- |
+| `label` / `labelMatch` | 标签 |
+| `title` / `titleMatch` | 标题 |
+| `identifier` / `identifierMatch` | 标识符 |
+| `value` / `valueMatch` | 值 |
+| `placeholderValue` / `placeholderValueMatch` | 占位文字 |
-// 精确匹配标识符
-identifier(identifier: string): NodeSelector
+**类型与状态**
-// 标识符模糊匹配
-identifierMatch(match: string): NodeSelector
+| 方法 | 说明 |
+| --- | --- |
+| `type` / `typeMatch` | 类型，如 `XCUIElementTypeButton` |
+| `enabled` | 是否启用 |
-// 精确匹配值
-value(value: string): NodeSelector
+**位置与结构**
-// 值模糊匹配
-valueMatch(match: string): NodeSelector
-```
-**示例：**
+| 方法 | 说明 |
+| --- | --- |
+| `index` | 序号 |
+| `depth` | 层级 |
+| `childCount` | 子节点数，支持数字或如 `">0"` |
+| `bounds(x, y, width, height)` | 区域 |
+| `xpath` | XPath |
+| `id` | 按节点 ID |
 ```typescript
-// 查找标签为"确定"的按钮
-const confirmButton = selector.label("确定").getOneNodeInfo(3000);
-// 查找包含"登录"的元素
-const loginElements = selector.labelMatch(".*登录.*").getNodeInfo(3000);
+// 精确
+selector.label("确定").type("XCUIElementTypeButton").getOneNodeInfo(3000);
-// 查找名称包含"button"的元素
-const buttons = selector.titleMatch("button").getNodeInfo(3000);
+// 模糊
+selector.labelMatch(".*登录.*").getNodeInfo(3000);
+selector.identifierMatch("^login_").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);
+// 组合
+selector
+  .type("XCUIElementTypeTextField")
+  .enabled(true)
+  .getOneNodeInfo(3000);
 ```
-##### 类型和属性
+常见类型：`XCUIElementTypeButton`、`StaticText`、`TextField`、`SecureTextField`、`TextView`、`SearchField`、`Cell`、`Table`、`CollectionView`、`PickerWheel`、`Switch`、`Slider` 等。
-```typescript
-// 精确匹配类型
-type(type: string): NodeSelector
+---
-// 类型模糊匹配
-typeMatch(match: string): NodeSelector
+## 节点操作说明
-// 启用状态
-enabled(enabled: boolean): NodeSelector
-```
-**示例：**
+### 是否可点 / 滚到可见
 ```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);
-selector.releaseNode();
+if (node.hittable()) {
+  node.tap();
+} else {
+  node.scrollToVisible();
+  node.tap();
+}
 ```
-##### 位置和结构
+- `hittable()`：当前能否点到
+- `scrollToVisible()`：手动滚到可见
+- `tap` / `doubleTap` / `press`：不可见时会自动尝试滚到可见再操作
-```typescript
-// 索引位置
-index(index: number): NodeSelector
-// 层级深度
-depth(depth: number): NodeSelector
+### 点击
-// 子节点数量
-childCount(childCount: number | string): NodeSelector
+| 方法 | 说明 |
+| --- | --- |
+| `tap()` | 推荐，单击 |
+| `doubleTap()` | 双击 |
+| `press(ms?)` | 长按，默认 500ms |
+| `clickCenter()` | 点中心坐标 |
+| `clickRandom()` | 范围内随机点 |
-// 边界范围
-bounds(x: number, y: number, width: number, height: number): NodeSelector
+```typescript
+const btn = selector
+  .label("确定")
+  .type("XCUIElementTypeButton")
+  .getOneNodeInfo(3000);
-// XPath 路径
-xpath(path: string): NodeSelector
+if (btn) {
+  btn.tap();
+  btn.doubleTap();
+  btn.press(800);
+}
 ```
-**示例：**
-```typescript
-const selector = createNodeSelector();
-// 查找第一个元素
-const firstElement = selector.index(0).getOneNodeInfo(2000);
+### 输入与设值
-// 查找特定深度的元素
-const level3Elements = selector.depth(3).getNodeInfo(3000);
+| 方法 | 说明 |
+| --- | --- |
+| `clearInput()` | 清空 |
+| `input(text)` | 追加输入，不清空原内容 |
+| `setValue(text)` | 按控件类型设置 |
-// 查找有子节点的元素
-const parentElements = selector.childCount(">0").getNodeInfo(3000);
+**`setValue` 行为**
-// 查找特定区域的元素
-const regionElements = selector.bounds(100, 100, 200, 50).getNodeInfo(3000);
+| 控件类型 | 传参 | 效果 |
+| --- | --- | --- |
+| `PickerWheel` | 选项文案，如 `"1小时"` | 滚到该选项 |
+| 文本框类（TextField 等） | 字符串 | 聚焦后追加输入，不先清空 |
-// 使用 XPath 查找
-const xpathElements = selector.xpath("//*[@title='快点JS']").getNodeInfo(3000);
+覆盖原内容请先清空：
-selector.releaseNode();
+```typescript
+field.clearInput();
+field.setValue("hello");
+// 或
+field.clearInput();
+field.input("hello");
 ```
-### 节点操作
-#### 点击操作
 ```typescript
-// 点击节点中心（坐标点击）
-node.clickCenter(): boolean;
-// 随机点击节点区域（坐标点击）
-node.clickRandom(): boolean;
-// 节点是否可接收事件（用于判断是否显示在屏幕上）
-node.hittable(): boolean;
-// 无障碍点击
-node.tap(): boolean;
-// 无障碍双击
-node.doubleTap(): boolean;
-// 无障碍长按，duration 单位毫秒
-node.press(duration: number): boolean;
-// 将节点滚动到可见区域
-node.scrollToVisible(): boolean;
-// 清空输入
-node.clearInput(): boolean;
-// 追加输入
-node.input(text: string): boolean;
-// 设置节点的值
-node.setValue(text: string): boolean;
+const wheel = selector.type("XCUIElementTypePickerWheel").getOneNodeInfo(3000);
+if (wheel) {
+  wheel.setValue("1小时");
+}
 ```
-#### tap / doubleTap / press - 无障碍手势
-通过无障碍 API 直接操作节点，不依赖坐标点击。
-| 方法 | 参数 | 说明 |
-| --- | --- | --- |
-| `tap()` | 无 | 无障碍单击 |
-| `doubleTap()` | 无 | 无障碍双击 |
-| `press(duration)` | `duration`：长按持续时间，单位毫秒 | 无障碍长按 |
-**示例：**
+### 树导航
 ```typescript
-const selector = createNodeSelector();
-const btn = selector.label("确定").type("XCUIElementTypeButton").getOneNodeInfo(3000);
-if (btn) {
-  // 无障碍单击
-  btn.tap();
-  // 无障碍双击
-  btn.doubleTap();
-  // 无障碍长按 800ms
-  btn.press(800);
+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);
 }
-selector.releaseNode();
 ```
-#### setValue - 设置节点的值
+---
-按控件类型自动处理，常用支持如下：
-| 控件类型 | 传参示例 | 说明 |
-| --- | --- | --- |
-| `XCUIElementTypePickerWheel` | `"1小时"` | 滚轮选到对应选项文案 |
-| `XCUIElementTypeTextField` | `"hello"` | 先聚焦再输入文本 |
-| `XCUIElementTypeSecureTextField` | `"123456"` | 同上 |
-| `XCUIElementTypeTextView` | `"多行内容"` | 同上 |
-| `XCUIElementTypeSearchField` | `"关键词"` | 同上 |
+## 示例
-文本类控件不会先清空已有内容；需要清空时先调用 `clearInput()`。
-**示例：**
+### 登录
 ```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");
+  }
-  confirmBtn.scrollToVisible();
-  // 优先使用无障碍点击；也可用 clickCenter / clickRandom 做坐标点击
-  const clicked = confirmBtn.tap();
-  if (clicked) {
-    logi("成功点击确定按钮");
+  const login = selector
+    .clearSelector()
+    .labelMatch(".*登录.*")
+    .type("XCUIElementTypeButton")
+    .getOneNodeInfo(3000);
+  if (login) {
+    login.tap();
   }
+} finally {
+  selector.releaseNode();
 }
+```
-// 文本框：可先清空再设值，或直接追加输入
-const field = selector.type("XCUIElementTypeTextField").getOneNodeInfo(3000);
-if (field) {
-  field.clearInput();
-  field.setValue("hello");
-}
+### 列表里靠后的项
-// 滚轮：传界面上的选项文案
-const wheel = selector.type("XCUIElementTypePickerWheel").getOneNodeInfo(3000);
-if (wheel) {
-  wheel.setValue("1小时");
+```typescript
+const selector = createNodeSelector({ mode: 2 });
+const item = selector.label("第 30 项").getOneNodeInfo(5000);
+if (item) {
+  item.tap(); // 不在可见区域时会自动滚动
 }
-// 随机点击避免检测
-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();
+const xml = selector.xml(8000);
+if (xml) {
+  logi(xml);
+}
+selector.releaseNode();
 ```
-**示例：**
-```typescript
-const selector = createNodeSelector();
+---
-// 查找输入框并获取其父容器
-const textField = selector
-  .type("XCUIElementTypeTextField")
-  .getOneNodeInfo(3000);
+## 常见问题
-if (textField) {
-  const container = textField.parent();
-  if (container) {
-    logi(`容器类型: ${container.type}`);
+**找不到节点**
+加大超时；减少条件或改用 `*Match`；换 `mode`；用 `xml()` 看实际文案和类型。
-    // 获取容器的所有子元素
-    const siblings = container.allChildren();
-    logi(`容器包含 ${siblings.length} 个子元素`);
+**点了没反应**
+先看 `hittable()`；确认点到的是目标控件；可对比 `clickCenter()`。
-    // 查找同级的按钮
-    const siblingButtons = siblings.filter(
-      (node) => node.type === "XCUIElementTypeButton",
-    );
-  }
-}
+**输入叠在旧文字后面**
+`input` / 文本类 `setValue` 是追加，先 `clearInput()`。
-selector.releaseNode();
-```
+**滚轮设不中**
+`setValue` 要传界面上显示的选项文案；确认类型是 `PickerWheel`；多列时选对那一列。