ms-vite-plugin 1.4.43 → 1.4.45

package/docs/apipython/node.md

@@ -111,16 +111,16 @@ list_page = node.createNodeSelector({"mode": 2})
 
 | 方法 | 说明 |
 | --- | --- |
-| `hittable()` | 当前是否可点击 |
-| `scrollToVisible()` | 滚动到可见区域 |
-| `tap()` | 单击（不可见时会先尝试滚到可见） |
-| `doubleTap()` | 双击 |
-| `press(duration=500)` | 长按，毫秒，默认 500 |
-| `clickCenter()` | 点击中心 |
-| `clickRandom()` | 范围内随机点击 |
-| `clearInput()` | 清空输入 |
-| `input(text)` | 追加输入（不先清空） |
-| `setValue(text)` | 设置值（见下方） |
+| `hittable()` | 当前是否可点击（可见且未被挡住） |
+| `scrollToVisible()` | 仅滚动到可见，不点击；一般不必手动调用 |
+| `tap()` | 单击；不可见时会先自动滚到可见 |
+| `doubleTap()` | 双击；不可见时会先自动滚到可见 |
+| `press(duration=500)` | 长按，毫秒，默认 500；不可见时会先自动滚到可见 |
+| `clickCenter()` | 点击中心（坐标点击，不会自动滚动） |
+| `clickRandom()` | 范围内随机点击（坐标点击，不会自动滚动） |
+| `clearInput()` | 清空输入（内部会先 `tap` 聚焦，因而也会自动滚到可见） |
+| `input(text)` | 追加输入（不先清空；内部会先 `tap` 聚焦） |
+| `setValue(text)` | 设置值（见下方；不可见时会先自动滚到可见） |
 | `parent()` / `child(i)` / `allChildren()` | 父 / 子 / 全部子节点 |
 | `siblings()` / `previousSiblings()` / `nextSiblings()` | 兄弟节点 |
 
@@ -173,17 +173,19 @@ selector.type("XCUIElementTypeTextField").enabled(True).getOneNodeInfo(3000)
 
 ### 是否可点 / 滚到可见
 
+`tap` / `doubleTap` / `press` / `setValue`（以及内部会先 `tap` 的 `clearInput` / `input`）在元素当前不可见时，会**自动**先滚到可见再操作，一般不用手写滚动：
+
 ```python
-if node.hittable():
-    node.tap()
-else:
-    node.scrollToVisible()
-    node.tap()
+# 推荐：直接操作，不可见时会自动滚到可见
+node.tap()
+node.doubleTap()
+node.press(800)
+node.setValue("hello")
 ```
 
-- `hittable()`：当前能否点到  
-- `scrollToVisible()`：手动滚到可见  
-- `tap` / `doubleTap` / `press`：不可见时会自动尝试滚到可见再操作  
+- `hittable()`：当前能否点到（可见且未被挡住），用于排查“点了没反应”
+- `scrollToVisible()`：只滚到可见、不点击；仅在你想先露出元素、稍后再操作时使用
+- `clickCenter()` / `clickRandom()`：按坐标点击，**不会**自动滚动
 
 ### 点击
 
@@ -194,10 +196,10 @@ btn = (
     .getOneNodeInfo(3000)
 )
 if btn:
-    btn.tap()
-    btn.doubleTap()
-    btn.press(800)
-    # btn.clickCenter()
+    btn.tap()        # 不可见时自动滚到可见
+    btn.doubleTap()  # 同上
+    btn.press(800)   # 同上
+    # btn.clickCenter()  # 坐标点击，不自动滚动
     # btn.clickRandom()
 ```
 
@@ -205,13 +207,13 @@ if btn:
 
 | 方法 | 说明 |
 | --- | --- |
-| `clearInput()` | 清空 |
-| `input(text)` | 追加输入 |
-| `setValue(text)` | 按类型设置 |
+| `clearInput()` | 清空（内部先 `tap` 聚焦，不可见时也会自动滚到可见） |
+| `input(text)` | 追加输入（内部先 `tap` 聚焦） |
+| `setValue(text)` | 按类型设置；不可见时会先自动滚到可见 |
 
 | 控件 | 传参 | 效果 |
 | --- | --- | --- |
-| `PickerWheel` | 选项文案，如 `"1小时"` | 滚到该选项 |
+| `PickerWheel` | 选项文案，如 `"1小时"` | 滚到该选项（控件本身不可见时也会先自动滚到可见） |
 | 文本框类 | 字符串 | 追加输入，不先清空 |
 
 ```python
@@ -220,6 +222,7 @@ field.setValue("hello")
 
 wheel = selector.type("XCUIElementTypePickerWheel").getOneNodeInfo(3000)
 if wheel:
+    # 不可见时会自动滚到可见，再调到目标选项
     wheel.setValue("1小时")
 ```