ms-vite-plugin 1.4.41 → 1.4.45

package/docs/apipython/node.md

@@ -1,15 +1,25 @@
 # 节点模块 (Node)
 
-节点模块提供了强大的 UI 元素访问和操作功能，可以通过各种条件选择和操作界面元素。
+用于查找和操作当前界面上的控件节点。
 
-**注意事项**
+**注意**
 
-- 此模块仅支持 快点 Agent 模式使用
+- 仅支持快点 Agent 模式
+- 通过 `from kuaijs import node` 使用
+
+**基本流程**
+
+```text
+createNodeSelector → 设置筛选条件 → getOneNodeInfo / getNodeInfo
+→ 点击 / 输入 / 设值等
+```
+
+---
 
 ## 类型定义
 
 ```python
-from typing import List, Literal, Optional, TypedDict, Union
+from typing import List, Optional, TypedDict
 
 class NodeBounds:
     x: int
@@ -52,361 +62,250 @@ class NodeInfo:
     def nextSiblings(self) -> List["NodeInfo"]: ...
 
 class NodeSelectorOptions(TypedDict, total=False):
-    maxDepth: int  # 最大层级深度，默认 50
-    mode: int  # 抓取模式：模式 1、模式 2、模式 3，默认模式 1
+    maxDepth: int  # 最大层级，默认 50
+    mode: int      # 抓取模式 1 | 2 | 3，默认 1
 ```
 
-## 节点选择器 (NodeSelector)
-
-节点选择器是访问 UI 元素的核心工具，提供了灵活的筛选和查找机制。
-
-### 创建节点选择器
-
-#### `createNodeSelector` - 创建节点选择器
+---
 
-创建一个新的节点选择器实例。
+## 创建选择器
 
 ```python
 def createNodeSelector(params: Optional[NodeSelectorOptions] = None) -> NodeSelector
 ```
 
-**参数说明：**
-
-| 参数名     | 类型 | 是否必填 | 默认值 | 描述                  |
-| ---------- | ---- | -------- | ------ | --------------------- |
-| `maxDepth` | int  | 否       | 50     | 最大层级深度，默认 50 |
-| `mode` | int  | 否       | 1      | 抓取模式。支持模式 1、模式 2、模式 3，默认模式 1 |
-
-**返回值：** `NodeSelector`
-
-**示例：**
+| 参数 | 默认 | 说明 |
+| --- | --- | --- |
+| `maxDepth` | `50` | 抓取深度，深层控件抓不到时可调大 |
+| `mode` | `1` | 抓取模式，可选 `1` / `2` / `3`，默认 `1` |
 
 ```python
 from kuaijs import node
 
-# 创建选择器
-selector = node.createNodeSelector({
-    "maxDepth": 20,  # 最大20层深度
-    "mode": 1  # 默认模式 1
-})
-```
-
-### 选择器方法
-
-#### 获取节点
-
-```python
-# 获取当前页面的 XML 字符串
-def xml(timeout: int = 5000) -> Optional[str]
-
-# 获取多个节点
-def getNodeInfo(timeout: int = 5000) -> List[NodeInfo]
-
-# 获取单个节点
-def getOneNodeInfo(timeout: int = 5000) -> Optional[NodeInfo]
-
-# 加载节点数据（通常内部自动调用）
-def loadNode(timeout: int = 5000) -> NodeSelector
-
-# 清除所有选择条件
-def clearSelector() -> NodeSelector
+selector = node.createNodeSelector()
+shallow = node.createNodeSelector({"maxDepth": 15})
+list_page = node.createNodeSelector({"mode": 2})
 ```
 
-**示例：**
+---
+
+## 节点信息
+
+### 属性
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 节点 ID（内部定位用，不要改） |
+| `identifier` | 控件标识符 |
+| `label` | 标签文案 |
+| `type` | 类型，如 `XCUIElementTypeButton` |
+| `value` | 当前值 |
+| `placeholderValue` | 输入框占位文字 |
+| `title` | 标题 |
+| `enabled` | 是否启用 |
+| `bounds` | 位置大小 |
+| `depth` / `index` | 层级 / 序号 |
+| `parentId` / `childCount` | 父节点 ID / 子节点数 |
+
+### 方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `hittable()` | 当前是否可点击（可见且未被挡住） |
+| `scrollToVisible()` | 仅滚动到可见，不点击；一般不必手动调用 |
+| `tap()` | 单击；不可见时会先自动滚到可见 |
+| `doubleTap()` | 双击；不可见时会先自动滚到可见 |
+| `press(duration=500)` | 长按，毫秒，默认 500；不可见时会先自动滚到可见 |
+| `clickCenter()` | 点击中心（坐标点击，不会自动滚动） |
+| `clickRandom()` | 范围内随机点击（坐标点击，不会自动滚动） |
+| `clearInput()` | 清空输入（内部会先 `tap` 聚焦，因而也会自动滚到可见） |
+| `input(text)` | 追加输入（不先清空；内部会先 `tap` 聚焦） |
+| `setValue(text)` | 设置值（见下方；不可见时会先自动滚到可见） |
+| `parent()` / `child(i)` / `allChildren()` | 父 / 子 / 全部子节点 |
+| `siblings()` / `previousSiblings()` / `nextSiblings()` | 兄弟节点 |
+
+---
+
+## 选择器方法
+
+### 加载与结果
+
+| 方法 | 说明 |
+| --- | --- |
+| `loadNode(timeout=5000)` | 重新加载界面节点 |
+| `clearSelector()` | 清除筛选条件 |
+| `xml(timeout=5000)` | 获取界面 XML，失败返回 `None` |
+| `getNodeInfo(timeout=5000)` | 所有匹配节点 |
+| `getOneNodeInfo(timeout=5000)` | 第一个匹配节点，没有则 `None` |
+
+`timeout` 单位毫秒。
 
 ```python
 from kuaijs import node
 
 selector = node.createNodeSelector()
-
-# 获取所有匹配的节点
-all_nodes = selector.getNodeInfo(5000)
-print(f"找到 {len(all_nodes)} 个节点")
-
-# 获取第一个匹配的节点
-first_node = selector.getOneNodeInfo(3000)
-if first_node:
-    print(f"节点标签: {first_node.label}")
+nodes = selector.label("确定").getNodeInfo(5000)
+one = selector.getOneNodeInfo(3000)
+xml = selector.xml()
 ```
 
-#### 条件筛选
-
-##### 文本相关
-
-```python
-# 精确匹配标签
-def label(text: str) -> NodeSelector
-
-# 标签模糊匹配
-def labelMatch(pattern: str) -> NodeSelector
-
-# 精确匹配名称
-def title(text: str) -> NodeSelector
+### 筛选条件
 
-# 名称模糊匹配
-def titleMatch(pattern: str) -> NodeSelector
+可链式调用，多个条件同时满足。带 `Match` 的为模糊匹配。
 
-# 精确匹配标识符
-def identifier(text: str) -> NodeSelector
-
-# 标识符模糊匹配
-def identifierMatch(pattern: str) -> NodeSelector
-
-# 精确匹配值
-def value(text: str) -> NodeSelector
-
-# 值模糊匹配
-def valueMatch(pattern: str) -> NodeSelector
-```
-
-**示例：**
+| 分类 | 方法 |
+| --- | --- |
+| 文本 | `label` / `labelMatch`、`title` / `titleMatch`、`identifier` / `identifierMatch`、`value` / `valueMatch`、`placeholderValue` / `placeholderValueMatch` |
+| 类型状态 | `type` / `typeMatch`、`enabled` |
+| 结构位置 | `index`、`depth`、`childCount`（支持 `">0"`）、`bounds`、`xpath`、`id` |
 
 ```python
-# 查找标签为"确定"的按钮
-confirm_button = selector.label("确定").getOneNodeInfo(3000)
-
-# 查找包含"登录"的元素
-login_elements = selector.labelMatch(".*登录.*").getNodeInfo(3000)
-
-# 查找名称包含"button"的元素
-buttons = selector.titleMatch("button").getNodeInfo(3000)
-
-# 查找值为"submit"的元素
-submit_element = selector.value("submit").getOneNodeInfo(2000)
-
-# 通过标识符查找
-el_by_id = selector.identifier("login_btn").getOneNodeInfo(2000)
-fuzzy = selector.identifierMatch("^login_.*").getNodeInfo(3000)
+selector.label("确定").type("XCUIElementTypeButton").getOneNodeInfo(3000)
+selector.labelMatch(".*登录.*").getNodeInfo(3000)
+selector.type("XCUIElementTypeTextField").enabled(True).getOneNodeInfo(3000)
 ```
 
-##### 类型与属性
+常见类型：`Button`、`StaticText`、`TextField`、`SecureTextField`、`TextView`、`SearchField`、`Cell`、`Table`、`CollectionView`、`PickerWheel`、`Switch`、`Slider` 等（完整名为 `XCUIElementType...`）。
 
-```python
-# 精确匹配类型
-def type(type_title: str) -> NodeSelector
+---
 
-# 类型模糊匹配
-def typeMatch(pattern: str) -> NodeSelector
+## 节点操作说明
 
-# 启用状态
-def enabled(flag: bool) -> NodeSelector
-```
+### 是否可点 / 滚到可见
 
-**示例：**
+`tap` / `doubleTap` / `press` / `setValue`（以及内部会先 `tap` 的 `clearInput` / `input`）在元素当前不可见时，会**自动**先滚到可见再操作，一般不用手写滚动：
 
 ```python
-from kuaijs import node
-
-selector = node.createNodeSelector()
-
-# 查找所有按钮
-all_buttons = selector.type("XCUIElementTypeButton").getNodeInfo(3000)
-
-# 查找所有文本框
-text_fields = selector.typeMatch("XCUIElementTypeTextField").getNodeInfo(3000)
-
-# 查找启用的元素
-enabled_elements = selector.enabled(True).getNodeInfo(3000)
+# 推荐：直接操作，不可见时会自动滚到可见
+node.tap()
+node.doubleTap()
+node.press(800)
+node.setValue("hello")
 ```
 
-##### 位置与结构
-
-```python
-# 索引位置
-def index(idx: int) -> NodeSelector
-
-# 层级深度
-def depth(d: int) -> NodeSelector
-
-# 子节点数量（支持表达式，如 ">0"）
-def childCount(expr: Union[int, str]) -> NodeSelector
+- `hittable()`：当前能否点到（可见且未被挡住），用于排查“点了没反应”
+- `scrollToVisible()`：只滚到可见、不点击；仅在你想先露出元素、稍后再操作时使用
+- `clickCenter()` / `clickRandom()`：按坐标点击，**不会**自动滚动
 
-# 边界范围
-def bounds(x: int, y: int, width: int, height: int) -> NodeSelector
-
-# XPath 路径
-def xpath(path: str) -> NodeSelector
-```
-
-**说明：** `*_match` 支持正则/模糊匹配；`childCount` 支持表达式（如 `>0`）。
-
-**示例：**
+### 点击
 
 ```python
-from kuaijs import node
-
-selector = node.createNodeSelector()
-
-# 查找第一个元素
-first_element = selector.index(0).getOneNodeInfo(2000)
-
-# 查找特定深度的元素
-level3_elements = selector.depth(3).getNodeInfo(3000)
-
-# 查找有子节点的元素
-parent_elements = selector.childCount(">0").getNodeInfo(3000)
-
-# 查找特定区域的元素
-region_elements = selector.bounds(100, 100, 200, 50).getNodeInfo(3000)
-
-# 使用 XPath 查找
-xpath_elements = selector.xpath("//*[@title='快点JS']").getNodeInfo(3000)
+btn = (
+    selector.label("确定")
+    .type("XCUIElementTypeButton")
+    .getOneNodeInfo(3000)
+)
+if btn:
+    btn.tap()        # 不可见时自动滚到可见
+    btn.doubleTap()  # 同上
+    btn.press(800)   # 同上
+    # btn.clickCenter()  # 坐标点击，不自动滚动
+    # btn.clickRandom()
 ```
 
-## 节点操作
+### 输入与设值
 
-`NodeSelector` 查找得到的 `NodeInfo` 支持直接调用操作方法（点击、无障碍手势等）。
+| 方法 | 说明 |
+| --- | --- |
+| `clearInput()` | 清空（内部先 `tap` 聚焦，不可见时也会自动滚到可见） |
+| `input(text)` | 追加输入（内部先 `tap` 聚焦） |
+| `setValue(text)` | 按类型设置；不可见时会先自动滚到可见 |
 
-### 点击操作
+| 控件 | 传参 | 效果 |
+| --- | --- | --- |
+| `PickerWheel` | 选项文案，如 `"1小时"` | 滚到该选项（控件本身不可见时也会先自动滚到可见） |
+| 文本框类 | 字符串 | 追加输入，不先清空 |
 
 ```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
+field.clearInput()
+field.setValue("hello")
 
-# 清空输入
-def clearInput() -> bool
-
-# 追加输入
-def input(text: str) -> bool
-
-# 设置节点的值
-def setValue(text: str) -> bool
+wheel = selector.type("XCUIElementTypePickerWheel").getOneNodeInfo(3000)
+if wheel:
+    # 不可见时会自动滚到可见，再调到目标选项
+    wheel.setValue("1小时")
 ```
 
-#### 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)
+field = selector.type("XCUIElementTypeTextField").getOneNodeInfo(3000)
+if field:
+    parent = field.parent()
+    children = parent.allChildren() if parent else []
+    prev = field.previousSiblings()
+    next_ = field.nextSiblings()
 ```
 
-#### setValue - 设置节点的值
-
-按控件类型自动处理，常用支持如下：
-
-| 控件类型 | 传参示例 | 说明 |
-| --- | --- | --- |
-| `XCUIElementTypePickerWheel` | `"1小时"` | 滚轮选到对应选项文案 |
-| `XCUIElementTypeTextField` | `"hello"` | 先聚焦再输入文本 |
-| `XCUIElementTypeSecureTextField` | `"123456"` | 同上 |
-| `XCUIElementTypeTextView` | `"多行内容"` | 同上 |
-| `XCUIElementTypeSearchField` | `"关键词"` | 同上 |
+---
 
-文本类控件不会先清空已有内容；需要清空时先调用 `clearInput()`。
+## 示例
 
-**示例：**
+### 登录
 
 ```python
 from kuaijs import node
 
 selector = node.createNodeSelector()
 
-# 查找并点击确定按钮
-confirm_btn = selector.label("确定").type("XCUIElementTypeButton").getOneNodeInfo(3000)
-
-if confirm_btn:
-    print(f"是否可接收事件: {confirm_btn.hittable()}")
-
-    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小时")
+user = selector.type("XCUIElementTypeTextField").getOneNodeInfo(5000)
+if user:
+    user.clearInput()
+    user.setValue("demo_user")
+
+password = (
+    selector.clearSelector()
+    .type("XCUIElementTypeSecureTextField")
+    .getOneNodeInfo(3000)
+)
+if password:
+    password.clearInput()
+    password.setValue("password")
+
+login = (
+    selector.clearSelector()
+    .labelMatch(".*登录.*")
+    .type("XCUIElementTypeButton")
+    .getOneNodeInfo(3000)
+)
+if login:
+    login.tap()
 ```
 
-### 节点导航
+### 列表里靠后的项
 
 ```python
-# 获取父节点
-def parent() -> Optional[NodeInfo]
-
-# 获取指定索引的子节点
-def child(index: int) -> Optional[NodeInfo]
-
-# 获取所有子节点
-def allChildren() -> List[NodeInfo]
-
-# 获取兄弟节点
-def siblings() -> List[NodeInfo]
-
-# 获取前面的兄弟节点
-def previousSiblings() -> List[NodeInfo]
+from kuaijs import node
 
-# 获取后面的兄弟节点
-def nextSiblings() -> List[NodeInfo]
+selector = node.createNodeSelector({"mode": 2})
+item = selector.label("第 30 项").getOneNodeInfo(5000)
+if item:
+    item.tap()  # 不在可见区域时会自动滚动
 ```
 
-**示例：**
+### 查看界面结构
 
 ```python
 from kuaijs import node
 
 selector = node.createNodeSelector()
+xml = selector.xml(8000)
+if xml:
+    print(xml)
+```
 
-# 查找输入框并获取其父容器
-text_field = selector.type("XCUIElementTypeTextField").getOneNodeInfo(3000)
+---
 
-if text_field:
-    container = text_field.parent()
-    if container:
-        print(f"容器类型: {container.type}")
+## 常见问题
 
-        # 获取容器的所有子元素
-        children = container.allChildren()
-        print(f"容器包含 {len(children)} 个子元素")
+**找不到节点**  
+加大超时；减少条件或改用 `*Match`；换 `mode`；用 `xml()` 看实际文案和类型。
 
-        # 查找同级的按钮
-        sibling_buttons = [n for n in children if n.type == "XCUIElementTypeButton"]
-```
+**点了没反应**  
+先看 `hittable()`；确认点到的是目标控件；可对比 `clickCenter()`。
+
+**输入叠在旧文字后面**  
+`input` / 文本类 `setValue` 是追加，先 `clearInput()`。
+
+**滚轮设不中**  
+`setValue` 要传界面上显示的选项文案；确认类型是 `PickerWheel`；多列时选对那一列。