ascript 1.3.27__py3-none-win_amd64.whl

ascript/windows/window/Selector.py

@@ -0,0 +1,1015 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import uiautomation as auto
+from PIL import Image
+
+from .Window import Window
+from .uia_runtime import prepare_comtypes_cache
+
+prepare_comtypes_cache()
+
+class UIElement:
+    """UI 元素封装类。
+
+    将 uiautomation 的 Control 对象封装为更易用的 UI 元素，
+    提供属性访问、坐标转换、点击、输入、截图等操作。
+    """
+
+    def __init__(self, node: auto.Control, window: Any, depth: int):
+        """初始化 UI 元素。
+
+        Args:
+            node: uiautomation 的 Control 控件对象
+            window: 所属的 Window 窗口对象
+            depth: 该元素在 UI 树中的深度层级
+        """
+        self.node = node
+        self.window = window
+        self.depth = depth
+        self.children: List['UIElement'] = []
+
+        # --- 1. 基础标识属性 (原生映射，不拼凑) ---
+        self.name: str = self._read(node, "Name", "")
+        self.type: str = self._read(node, "ControlTypeName", "")
+        self.class_name: str = self._read(node, "ClassName", "")
+        self.handle: int = self._read(node, "NativeWindowHandle", 0) or 0
+
+        # 资源 ID: 仅存储原生的 AutomationId
+        self.res_id: str = self._read(node, "AutomationId", "")
+
+        # 内存 ID: 仅存储对象在内存中的物理唯一地址 (Python Object ID)
+        self.memory_id: int = id(self.node)
+
+        # --- 2. 交互状态属性 ---
+        self.is_enabled: bool = bool(self._read(node, "IsEnabled", False))
+        self.is_visible: bool = not bool(self._read(node, "IsOffscreen", True))
+        self.is_clickable: bool = self._check_clickable(node)
+        self.is_password: bool = bool(self._read(node, "IsPassword", False))
+        self.is_focusable: bool = bool(self._read(node, "IsKeyboardFocusable", False))
+        self.is_focused: bool = bool(self._read(node, "HasKeyboardFocus", False))
+
+        toggle_pattern = self._get_pattern(node, "GetTogglePattern")
+        selection_pattern = self._get_pattern(node, "GetSelectionItemPattern")
+        value_pattern = self._get_pattern(node, "GetValuePattern")
+        self.is_checkable: bool = toggle_pattern is not None
+        self.is_checked: bool = bool(
+            self._read(toggle_pattern, "ToggleState", 0)
+        ) if toggle_pattern is not None else False
+        self.is_selected: bool = bool(
+            self._read(selection_pattern, "IsSelected", False)
+        ) if selection_pattern is not None else False
+        self.is_editable: bool = bool(
+            value_pattern is not None
+            and not bool(self._read(value_pattern, "IsReadOnly", True))
+        )
+
+        # 内容获取
+        self.value: str = self._get_node_value(node)
+        self.description: str = self._read(node, "HelpText", "")
+
+        # --- 3. 坐标转换 (窗口相对坐标) ---
+        try:
+            rect = node.BoundingRectangle
+            # Window.capture() returns the client area, so element overlays must
+            # use the same physical-coordinate origin rather than the outer frame.
+            w_rect = self.window.client_rect
+            win_l = w_rect.left if hasattr(w_rect, 'left') else w_rect[0]
+            win_t = w_rect.top if hasattr(w_rect, 'top') else w_rect[1]
+            self.relative_rect = (
+                rect.left - win_l, rect.top - win_t,
+                rect.right - win_l, rect.bottom - win_t,
+            )
+        except Exception:
+            self.relative_rect = (0, 0, 0, 0)
+
+    @staticmethod
+    def _read(node: auto.Control, attr: str, default):
+        try:
+            value = getattr(node, attr)
+            return default if value is None else value
+        except Exception:
+            return default
+
+    @staticmethod
+    def _get_pattern(node: auto.Control, method: str):
+        try:
+            getter = getattr(node, method, None)
+            return getter() if getter else None
+        except Exception:
+            return None
+
+    def _check_clickable(self, node: auto.Control) -> bool:
+        """检查控件节点是否支持点击交互。
+
+        通过检测 InvokePattern、TogglePattern、SelectionItemPattern 来判断。
+
+        Args:
+            node: uiautomation 的 Control 控件对象
+
+        Returns:
+            支持点击返回 True，否则返回 False
+        """
+        try:
+            return any([
+                hasattr(node, 'GetInvokePattern') and node.GetInvokePattern(),
+                hasattr(node, 'GetTogglePattern') and node.GetTogglePattern(),
+                hasattr(node, 'GetSelectionItemPattern') and node.GetSelectionItemPattern()
+            ])
+        except:
+            return False
+
+    def _get_node_value(self, node: auto.Control) -> str:
+        """获取控件的文本内容值。
+
+        优先通过 ValuePattern 获取，若失败则对 EditControl 类型回退到 Name 属性。
+
+        Args:
+            node: uiautomation 的 Control 控件对象
+
+        Returns:
+            控件的文本值，获取失败返回空字符串
+        """
+        try:
+            if hasattr(node, 'GetValuePattern'):
+                val = node.GetValuePattern().Value
+                if val and val != self.name:
+                    return val
+            if self.type == "EditControl":
+                return node.Name or ""
+        except:
+            pass
+        return ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        """将 UI 元素及其子元素递归转换为字典结构。
+
+        Returns:
+            包含元素所有属性和子元素的嵌套字典
+        """
+        return {
+            "name": self.name,
+            "type": self.type,
+            "res_id": self.res_id,  # 有就有，没有就是 ""
+            "memory_id": self.memory_id,  # 纯数字内存地址
+            "class_name": self.class_name,
+            "handle": self.handle,
+            "rect": {
+                "left": self.relative_rect[0],
+                "top": self.relative_rect[1],
+                "right": self.relative_rect[2],
+                "bottom": self.relative_rect[3]
+            },
+            "enabled": self.is_enabled,
+            "visible": self.is_visible,
+            "clickable": self.is_clickable,
+            "value": self.value,
+            "description": self.description,
+            "password": self.is_password,
+            "checkable": self.is_checkable,
+            "checked": self.is_checked,
+            "editable": self.is_editable,
+            "focusable": self.is_focusable,
+            "focused": self.is_focused,
+            "selected": self.is_selected,
+            "depth": self.depth,
+            "child_count": len(self.children),
+            "children": [child.to_dict() for child in self.children]
+        }
+
+    @property
+    def child_count(self) -> int:
+        """获取子节点数量。
+
+        Returns:
+            子元素的个数
+        """
+        return len(self.children)
+
+    @property
+    def center(self) -> Tuple[int, int]:
+        """获取元素相对于窗口的中心点坐标。
+
+        Returns:
+            (x, y) 形式的中心点坐标元组
+        """
+        l, t, r, b = self.relative_rect
+        return (l + r) // 2, (t + b) // 2
+
+    def click(self, simulate: bool = False):
+        """点击当前 UI 元素。
+
+        支持底层指令点击和物理模拟点击两种模式。底层指令点击不移动鼠标，
+        物理模拟点击会真实移动鼠标到元素位置。
+
+        Args:
+            simulate: True 为强制物理模拟点击，False 为优先使用底层指令点击（失败时自动降级）
+
+        Returns:
+            返回自身（UIElement），支持链式调用
+        """
+        if not simulate:
+            # 1. 尝试使用 InvokePattern (最通用的底层点击)
+            try:
+                pattern = self.node.GetInvokePattern()
+                if pattern:
+                    pattern.Invoke()
+                    return self
+            except:
+                pass
+
+            # 2. 尝试使用 TogglePattern (适用于复选框、某些开关按钮)
+            try:
+                pattern = self.node.GetTogglePattern()
+                if pattern:
+                    pattern.Toggle()
+                    return self
+            except:
+                pass
+
+        # 3. 降级方案：如果上述底层接口不支持，或者明确要求 simulate=True
+        # 使用物理模拟点击。
+        # 注意：uiautomation 的 Click 默认就是移动鼠标。
+        # 如果不想移动鼠标但还要发物理点击，基本不可能，除非用 PostMessage。
+        cx, cy = self.center
+        if simulate:
+            self.node.Click()  # 这里的 Click 会移动鼠标
+        else:
+            # 使用你 Window 封装的底层坐标点击逻辑
+            self.window.click(cx, cy)
+
+        return self
+
+    def input(self, text: str, simulate: bool = False):
+        """向当前 UI 元素输入文本。
+
+        支持底层直接赋值和模拟键盘敲击两种模式。
+
+        Args:
+            text: 要输入的文本字符串
+            simulate: False 为优先使用 ValuePattern 直接设值（静默且快），
+                True 为使用 SendKeys 模拟键盘敲击（适合需要触发监听事件的输入框）
+
+        Returns:
+            返回自身（UIElement），支持链式调用
+        """
+        if not simulate:
+            try:
+                # 1. 尝试 ValuePattern (最通用的设置文本方式)
+                pattern = self.node.GetValuePattern()
+                if pattern:
+                    pattern.SetValue(text)
+                    return self
+            except:
+                pass
+
+        # 2. 降级方案 或 强制模拟：先点击聚焦，再发送按键
+        # 注意：这里调用的是你已有的 click()
+        self.click(simulate=simulate)
+        self.node.SendKeys(text)
+        return self
+
+    def capture(self, save_path: str = None) -> Image:
+        """捕获当前 UI 元素的截图。
+
+        Args:
+            save_path: 图片保存路径，为 None 则不保存到文件
+
+        Returns:
+            Pillow Image 对象
+        """
+        # uiautomation 的 CaptureToImage 返回的是 Pillow 的 Image 对象
+        img = self.node.CaptureToImage()
+
+        if save_path:
+            img.save(save_path)
+
+        return img
+
+    def __repr__(self):
+        return f"<UIElement: [{self.type}] res_id: {self.res_id} memory_id: {self.memory_id}>"
+
+
+
+class Selector:
+    """UI 元素选择器，支持链式查询和操作。
+
+    提供类似 CSS 选择器的链式 API，可通过属性过滤、层级关系（子节点、父节点、兄弟节点）
+    组合定位 UI 元素，并支持在查询链中插入点击和输入动作。
+    """
+
+    def __init__(
+        self,
+        window: Any = None,
+        title: str = None,
+        depth: int = 0xFFFFFFFF,
+        *,
+        app: Optional[str] = None,
+        title_re: Optional[str] = None,
+        class_name: Optional[str] = None,
+        content: Optional[Union[bool, str]] = None,
+        timeout: float = 10,
+    ):
+        """初始化选择器。
+
+        Args:
+            window: 已存在的 Window 对象实例，作为搜索的根窗口
+            title: 窗口标题，当 window 为 None 时通过标题自动查找窗口
+            depth: 最大搜索深度，默认为 0xFFFFFFFF（不限制）
+            app: 进程名，例如 ``chrome.exe``，运行时动态查找窗口
+            title_re: 用于区分同进程窗口的标题正则表达式
+            class_name: 用于区分同进程窗口的窗口类名
+            content: True 自动进入 Chromium 内容窗口；字符串指定内容窗口类名；
+                None 时会自动识别 Chromium/Electron 窗口
+            timeout: 等待应用窗口和指定内容窗口的超时时间
+        """
+        self.window = window
+
+        if self.window is None and any((app, title_re, class_name)):
+            self.window = self._resolve_app_window(
+                process_name=app,
+                title_re=title_re,
+                class_name=class_name,
+                content=content,
+                timeout=timeout,
+            )
+        elif self.window is None and title:
+            try:
+                self.window = Window.find(title)
+            except:
+                pass
+
+        self._steps: List[Dict] = []
+        self._current_filters: Dict[str, Any] = {}
+        self._tree_depth = depth
+        self._max_depth = depth
+
+        self._attr_map = {
+            'name': 'Name',
+            'type': 'ControlTypeName',
+            'class_name': 'ClassName',
+            'handle': 'NativeWindowHandle',
+            'res_id': 'AutomationId',
+            'description': 'HelpText',
+            'is_enabled': 'IsEnabled',
+            'is_password': 'IsPassword',
+            'is_focusable': 'IsKeyboardFocusable',
+            'is_focused': 'HasKeyboardFocus',
+        }
+
+    @classmethod
+    def _resolve_app_window(
+        cls,
+        *,
+        process_name: Optional[str],
+        title_re: Optional[str],
+        class_name: Optional[str],
+        content: Optional[Union[bool, str]],
+        timeout: float,
+    ) -> Window:
+        if not any((process_name, title_re, class_name)):
+            raise ValueError("app, title_re or class_name is required")
+        window = Window.find(
+            title_re=title_re,
+            process_name=process_name,
+            class_name=class_name,
+            timeout=timeout,
+        )
+        if window is None:
+            raise LookupError("target application window was not found")
+
+        root_class = str(getattr(window, "class_name", "") or "")
+        auto_content = content is None and root_class.startswith("Chrome_WidgetWin_")
+        if content or auto_content:
+            child_class = "Chrome_RenderWidgetHostHWND" if content in (None, True) else str(content)
+            content_window = window.find_child(
+                class_name=child_class, visible_only=True, timeout=timeout,
+            )
+            if content_window is not None:
+                return content_window
+            if content:
+                raise LookupError(f"application content window was not found: {child_class}")
+        return window
+
+    @classmethod
+    def app(
+        cls,
+        process_name: Optional[str] = None,
+        *,
+        title_re: Optional[str] = None,
+        class_name: Optional[str] = None,
+        content: Union[bool, str] = False,
+        timeout: float = 10,
+        depth: int = 0xFFFFFFFF,
+    ) -> 'Selector':
+        """Create a selector scoped to an application instead of a volatile HWND.
+
+        ``content=True`` automatically enters the active Chromium/Electron
+        renderer window. A custom descendant class name may also be supplied.
+        """
+        return cls(
+            app=process_name,
+            title_re=title_re,
+            class_name=class_name,
+            content=content,
+            timeout=timeout,
+            depth=depth,
+        )
+
+    def _add_filter(self, key: str, value: Any):
+        """添加属性过滤条件到当前查询步骤。
+
+        如果上一步是关系跳转（child/parent/brother），则将过滤条件附加到该步骤；
+        否则添加到当前待提交的过滤条件集合。
+
+        Args:
+            key: 过滤属性名（如 'name'、'type'、'res_id' 等）
+            value: 过滤属性值
+        """
+        if self._steps and self._steps[-1]['method'] in ['child', 'parent', 'brother']:
+            self._steps[-1]['filters'][key] = value
+        else:
+            self._current_filters[key] = value
+
+    def _flush_to_step(self):
+        """将当前累积的过滤条件和深度设置提交为一个 find 查询步骤。
+
+        如果当前没有待提交的过滤条件且深度为默认值，则不执行任何操作。
+        """
+        if self._current_filters or self._max_depth != 0xFFFFFFFF:
+            self._steps.append({
+                'method': 'find',
+                'param': None,
+                'filters': self._current_filters.copy(),
+                'max_depth': self._max_depth
+            })
+            self._current_filters = {}
+            self._max_depth = 0xFFFFFFFF
+
+    def _add_relation(self, method: str, param: Any):
+        """添加关系跳转步骤（child/parent/brother）。
+
+        先提交当前累积的过滤条件，再添加一个关系跳转步骤。
+
+        Args:
+            method: 关系类型，可选 'child'、'parent'、'brother'
+            param: 跳转参数（索引值），None 表示获取全部
+        """
+        self._flush_to_step()
+        self._steps.append({
+            'method': method,
+            'param': param,
+            'filters': {},
+            'max_depth': 0xFFFFFFFF
+        })
+
+    # --- 属性链式调用 ---
+    def name(self, val: str) -> 'Selector':
+        """按控件名称过滤（支持正则匹配）。
+
+        Args:
+            val: 名称匹配模式（正则表达式）
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._add_filter('name', val); return self
+
+    def type(self, val: str) -> 'Selector':
+        """按控件类型过滤（如 'ButtonControl'、'EditControl'）。
+
+        Args:
+            val: 控件类型名称（支持正则匹配）
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._add_filter('type', val); return self
+
+    def class_name(self, val: str) -> 'Selector':
+        """按窗口类名过滤。
+
+        Args:
+            val: 窗口类名（支持正则匹配）
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._add_filter('class_name', val); return self
+
+    def res_id(self, val: str) -> 'Selector':
+        """按 AutomationId 资源 ID 过滤。
+
+        Args:
+            val: AutomationId 值（支持正则匹配）
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._add_filter('res_id', val); return self
+
+    def value(self, val: str) -> 'Selector':
+        """按控件的文本值过滤。
+
+        Args:
+            val: 文本值（支持正则匹配）
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._add_filter('value', val); return self
+
+    def description(self, val: str) -> 'Selector':
+        """按控件的帮助文本描述过滤。
+
+        Args:
+            val: 描述文本（支持正则匹配）
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._add_filter('description', val); return self
+
+    def handle(self, val: int) -> 'Selector':
+        """按原生窗口句柄过滤。
+
+        Args:
+            val: 窗口句柄值（精确匹配）
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._add_filter('handle', val); return self
+
+    def enabled(self, val: bool = True) -> 'Selector':
+        """按是否启用状态过滤。
+
+        Args:
+            val: True 为只匹配启用的控件，False 为只匹配禁用的控件
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._add_filter('is_enabled', val); return self
+
+    def visible(self, val: bool = True) -> 'Selector':
+        """按是否可见状态过滤。
+
+        Args:
+            val: True 为只匹配可见的控件，False 为只匹配不可见的控件
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._add_filter('is_visible', val); return self
+
+    def clickable(self, val: bool = True) -> 'Selector':
+        """按是否可点击状态过滤。
+
+        Args:
+            val: True 为只匹配可点击的控件，False 为只匹配不可点击的控件
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._add_filter('is_clickable', val); return self
+
+    def password(self, val: bool = True) -> 'Selector':
+        """按是否为密码输入框过滤。
+
+        Args:
+            val: True 为只匹配密码框，False 为只匹配非密码框
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._add_filter('is_password', val); return self
+
+    def checkable(self, val: bool = True) -> 'Selector':
+        """按控件是否支持 TogglePattern 过滤。"""
+        self._add_filter('is_checkable', val); return self
+
+    def checked(self, val: bool = True) -> 'Selector':
+        """按复选框或开关当前是否选中过滤。"""
+        self._add_filter('is_checked', val); return self
+
+    def editable(self, val: bool = True) -> 'Selector':
+        """按控件是否支持可写 ValuePattern 过滤。"""
+        self._add_filter('is_editable', val); return self
+
+    def focusable(self, val: bool = True) -> 'Selector':
+        """按控件是否可获取键盘焦点过滤。"""
+        self._add_filter('is_focusable', val); return self
+
+    def focused(self, val: bool = True) -> 'Selector':
+        """按控件当前是否拥有键盘焦点过滤。"""
+        self._add_filter('is_focused', val); return self
+
+    def selected(self, val: bool = True) -> 'Selector':
+        """按 SelectionItemPattern 的选择状态过滤。"""
+        self._add_filter('is_selected', val); return self
+
+    def child_count(self, count: int) -> 'Selector':
+        """按子节点数量过滤。
+
+        Args:
+            count: 精确匹配的子节点数量
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._add_filter('child_count', count); return self
+
+    def node_depth(self, depth: int) -> 'Selector':
+        """按元素在当前查询树中的实际深度过滤。"""
+        self._add_filter('_node_depth', int(depth)); return self
+
+    # --- 关系链式调用 ---
+    def depth(self, d: int) -> 'Selector':
+        """设置后续查找的最大搜索深度。
+
+        Args:
+            d: 最大搜索深度
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._max_depth = d; return self
+
+    def child(self, index: Any = None) -> 'Selector':
+        """跳转到子节点。
+
+        Args:
+            index: 子节点索引（正数从1开始，负数从末尾，float 为相对偏移，None 为全部子节点）
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._add_relation('child', index); return self
+
+    def parent(self, index: Any = None) -> 'Selector':
+        """跳转到父节点。
+
+        Args:
+            index: 向上跳转的层数，默认为 1 层
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._add_relation('parent', index); return self
+
+    def brother(self, index: Any = None) -> 'Selector':
+        """跳转到兄弟节点。
+
+        Args:
+            index: 兄弟节点索引（正数从1开始，负数从末尾，float 为相对偏移，None 为全部兄弟）
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._add_relation('brother', index); return self
+
+    # --- 动作插值 ---
+    def click(self, simulate: bool = False) -> 'Selector':
+        """在查询链中插入点击动作，对当前匹配的所有元素执行点击。
+
+        Args:
+            simulate: True 为物理模拟点击，False 为底层指令点击
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._flush_to_step()
+        self._steps.append({'method': 'action', 'action_type': 'click', 'param': simulate, 'filters': {}})
+        return self
+
+    def input(self, msg: str) -> 'Selector':
+        """在查询链中插入文本输入动作，对当前匹配的所有元素执行输入。
+
+        Args:
+            msg: 要输入的文本字符串
+
+        Returns:
+            Selector 自身，支持链式调用
+        """
+        self._flush_to_step()
+        self._steps.append({'method': 'action', 'action_type': 'input', 'param': msg, 'filters': {}})
+        return self
+
+    # --- 匹配内核 ---
+    def _match_node(self, node: auto.Control, filters: Dict, depth: Optional[int] = None) -> bool:
+        """检查控件节点是否满足所有过滤条件。
+
+        支持布尔精确匹配、整数精确匹配和字符串正则匹配（不区分大小写）。
+
+        Args:
+            node: uiautomation 的 Control 控件对象
+            filters: 过滤条件字典，键为属性名，值为期望匹配的值
+
+        Returns:
+            所有条件都满足返回 True，否则返回 False
+        """
+        if not filters: return True
+        for key, target in filters.items():
+            actual = None
+            if key == '_node_depth':
+                actual = depth
+            elif key == 'value':
+                try:
+                    p = node.GetValuePattern()
+                    v = p.Value if p else ""
+                    actual = v if (v and v != node.Name) else (
+                        "" if node.ControlTypeName != "EditControl" else node.Name)
+                except:
+                    actual = ""
+            elif key == 'is_clickable':
+                try:
+                    actual = any([hasattr(node, f'Get{p}Pattern') and getattr(node, f'Get{p}Pattern')()
+                                  for p in ['Invoke', 'Toggle', 'SelectionItem']])
+                except:
+                    actual = False
+            elif key in ('is_checkable', 'is_checked'):
+                pattern = UIElement._get_pattern(node, 'GetTogglePattern')
+                actual = pattern is not None if key == 'is_checkable' else bool(
+                    UIElement._read(pattern, 'ToggleState', 0)
+                ) if pattern is not None else False
+            elif key == 'is_selected':
+                pattern = UIElement._get_pattern(node, 'GetSelectionItemPattern')
+                actual = bool(UIElement._read(pattern, 'IsSelected', False)) if pattern else False
+            elif key == 'is_editable':
+                pattern = UIElement._get_pattern(node, 'GetValuePattern')
+                actual = bool(pattern and not bool(UIElement._read(pattern, 'IsReadOnly', True)))
+            elif key == 'child_count':
+                try:
+                    actual = len(node.GetChildren())
+                except:
+                    actual = 0
+            elif key == 'is_visible':
+                try:
+                    actual = not node.IsOffscreen
+                except:
+                    actual = False
+            else:
+                native_key = self._attr_map.get(key, key)
+                try:
+                    actual = getattr(node, native_key, None)
+                except Exception:
+                    actual = None
+
+            if isinstance(target, bool):
+                if bool(actual) != target: return False
+            elif isinstance(target, int):
+                if actual != target: return False
+            else:
+                try:
+                    if not re.search(str(target), str(actual or ""), re.IGNORECASE): return False
+                except:
+                    if str(target).lower() not in str(actual or "").lower(): return False
+        return True
+
+    # --- 执行引擎 ---
+    def _execute(self, first_only: bool = False) -> List[Any]:
+        """执行查询链，返回所有匹配的 UIElement 列表。
+
+        按照之前通过链式调用构建的查询步骤依次执行，
+        包括属性过滤、关系跳转和动作执行，最终返回去重后的结果。
+
+        Returns:
+            匹配的 UIElement 对象列表
+        """
+        self._flush_to_step()
+
+        if self.window and hasattr(self.window, 'hwnd') and self.window.hwnd:
+            root = auto.ControlFromHandle(self.window.hwnd)
+            current_pool = [(root, 0)]
+        else:
+            current_pool = [(auto.GetRootControl(), 0)]
+
+        for step_index, step in enumerate(self._steps):
+            next_pool = []
+            method = step['method']
+            param = step.get('param')
+            filters = step.get('filters', {})
+
+            if method == 'action':
+                action_type = step.get('action_type')
+                for node, d in current_pool:
+                    try:
+                        temp_el = UIElement(node, self.window, d)
+                        if action_type == 'click':
+                            temp_el.click(simulate=param)
+                        elif action_type == 'input':
+                            val_pat = node.GetValuePattern()
+                            if val_pat:
+                                val_pat.SetValue(param)
+                            else:
+                                node.SendKeys(param)
+                    except Exception as e:
+                        print(f"执行插值动作 {action_type} 失败: {e}")
+                continue
+
+            max_d = step.get('max_depth', 0xFFFFFFFF)
+
+            for node, d in current_pool:
+                if method == 'find':
+                    candidates = [(node, 0)]
+                    candidates.extend(self._walk_controls(node, max_d))
+                    for c, rel_d in candidates:
+                        if self._match_node(c, filters, d + rel_d):
+                            next_pool.append((c, d + rel_d))
+                            if first_only and step_index == len(self._steps) - 1:
+                                break
+                else:
+                    # --- 轴跳转逻辑 ---
+                    if method == 'child':
+                        try:
+                            candidates = node.GetChildren()
+                        except Exception:
+                            candidates = []
+                        new_d = d + 1
+                        if isinstance(param, float):
+                            picked = self._pick_by_float(candidates, node, param)
+                            next_pool.extend([(p, new_d) for p in picked if self._match_node(p, filters, new_d)])
+                        else:
+                            matched = [c for c in candidates if self._match_node(c, filters, new_d)]
+                            picked = self._pick_by_int(matched, param)
+                            next_pool.extend([(p, new_d) for p in picked])
+
+                    elif method == 'parent':
+                        # 修改后的 parent 逻辑：支持向上跳 n 层
+                        # param 为调用 .parent(n) 时传入的值
+                        up_level = param if (isinstance(param, int) and param > 0) else 1
+                        curr_p = node
+                        for _ in range(up_level):
+                            try:
+                                curr_p = curr_p.GetParentControl()
+                            except Exception:
+                                curr_p = None
+                            if not curr_p: break
+
+                        # 跳转完成后进行属性匹配，并计算新的深度
+                        parent_depth = max(0, d - up_level)
+                        if curr_p and self._match_node(curr_p, filters, parent_depth):
+                            next_pool.append((curr_p, parent_depth))
+
+                    elif method == 'brother':
+                        try:
+                            p = node.GetParentControl()
+                            candidates = p.GetChildren() if p else []
+                        except Exception:
+                            candidates = []
+                        new_d = d
+                        if isinstance(param, float):
+                            picked = self._pick_by_float(candidates, node, param)
+                            next_pool.extend([(p, new_d) for p in picked if self._match_node(p, filters, new_d)])
+                        else:
+                            matched = [c for c in candidates if not self._same_control(c, node) and self._match_node(c, filters, new_d)]
+                            picked = self._pick_by_int(matched, param)
+                            next_pool.extend([(p, new_d) for p in picked])
+
+            current_pool = next_pool
+            if not current_pool: break
+
+        final_list = []
+        seen_ids = set()
+        for node, depth in current_pool:
+            try:
+                rid = tuple(node.GetRuntimeId())
+                if rid in seen_ids: continue
+                seen_ids.add(rid)
+            except:
+                pass
+            final_list.append(UIElement(node, self.window, depth))
+
+        return final_list[:1] if first_only else final_list
+
+    def find_all(self) -> List[Any]:
+        """执行查询链，返回所有去重后的匹配元素。"""
+        return self._execute(first_only=False)
+
+    @staticmethod
+    def _same_control(left, right) -> bool:
+        try:
+            return bool(auto.CompareControl(left, right))
+        except Exception:
+            return left is right
+
+    @staticmethod
+    def _walk_controls(root, max_depth):
+        """Depth-first Raw View traversal with per-provider fault isolation."""
+        if max_depth <= 0:
+            return
+        depth = 0
+        try:
+            first = root.GetFirstChildControl()
+        except Exception:
+            first = None
+        levels = [first]
+        while depth >= 0:
+            current = levels[-1]
+            if current is None:
+                levels.pop()
+                depth -= 1
+                continue
+            yield current, depth + 1
+            try:
+                levels[depth] = current.GetNextSiblingControl()
+            except Exception:
+                levels[depth] = None
+            if depth + 1 < max_depth:
+                try:
+                    child = current.GetFirstChildControl()
+                except Exception:
+                    child = None
+                if child is not None:
+                    depth += 1
+                    levels.append(child)
+
+    def _pick_by_float(self, candidates, current, param) -> List[auto.Control]:
+        """通过浮点数相对偏移量从候选列表中选取控件。
+
+        以当前控件在候选列表中的位置为基准，按 param * 10 的偏移量选取目标。
+
+        Args:
+            candidates: 候选控件列表
+            current: 当前基准控件
+            param: 浮点数偏移量（如 0.1 表示偏移 1 位，-0.2 表示偏移 -2 位）
+
+        Returns:
+            选中的控件列表（0 或 1 个元素）
+        """
+        try:
+            curr_idx = -1
+            for i, c in enumerate(candidates):
+                if auto.CompareControl(c, current):
+                    curr_idx = i;
+                    break
+            if curr_idx == -1: return []
+            target_idx = curr_idx + int(round(param * 10))
+            return [candidates[target_idx]] if 0 <= target_idx < len(candidates) else []
+        except:
+            return []
+
+    def _pick_by_int(self, matched, param) -> List[auto.Control]:
+        """通过整数索引从已匹配的控件列表中选取。
+
+        Args:
+            matched: 已通过过滤条件匹配的控件列表
+            param: 整数索引（正数从1开始，负数从末尾），None 返回全部
+
+        Returns:
+            选中的控件列表
+        """
+        if param is None: return matched
+        try:
+            idx = int(param)
+            if idx > 0: return [matched[idx - 1]] if idx <= len(matched) else []
+            if idx < 0: return [matched[idx]] if abs(idx) <= len(matched) else []
+        except:
+            pass
+        return []
+
+    def find(self) -> Optional[Any]:
+        """执行查询链，返回第一个匹配的 UIElement。
+
+        Returns:
+            匹配的第一个 UIElement 对象，未找到则返回 None
+        """
+        res = self._execute(first_only=True)
+        return res[0] if res else None
+
+    def find_first(self) -> Optional[Any]:
+        """Compatibility alias used by generated inspector selectors."""
+        return self.find()
+
+    def get_uielement_tree(self, as_json: bool = False) -> Union[Any, str]:
+        """获取窗口的完整 UI 元素树。
+
+        遍历窗口下所有控件，构建层级化的 UIElement 树结构。
+
+        Args:
+            as_json: True 返回 JSON 字符串，False 返回根 UIElement 对象
+
+        Returns:
+            UI 元素树的根节点（UIElement）或其 JSON 字符串表示；窗口无效时返回 None 或空字符串
+        """
+        if not self.window.hwnd: return "" if as_json else None
+        root = auto.ControlFromHandle(self.window.hwnd)
+        if not root.Exists(0): return "" if as_json else None
+
+        root_element = UIElement(root, self.window, 0)
+        stack = {0: root_element}
+        for control, depth in self._walk_controls(root, self._tree_depth):
+            try:
+                new_el = UIElement(control, self.window, depth)
+                parent = stack.get(depth - 1)
+                if parent: parent.children.append(new_el)
+                stack[depth] = new_el
+            except Exception as e:
+                print(f"跳过异常 UIA 节点 depth={depth}: {e}")
+
+        if as_json: return json.dumps(root_element.to_dict(), ensure_ascii=False, indent=2)
+        return root_element