源码教程：点击、输入、键盘与鼠标

本章解释定位如何转为动作。核心辅助方法是 resolveIndex、resolveActionTarget、clickWithMode 和输入执行逻辑；遮挡与重复提交的排障步骤见第 15 篇。

1. 索引、CSS 与语义定位

resolveActionTarget 先 count，0 个匹配立即报告不存在；多个匹配扫描前 20 个候选，通过可见性和中心点命中优先选前景控件。它不是业务语义解析器，仍应写能限定目标的选择器。

2. 点击执行不是无条件重试

auto 先尝试原生点击。在普通失败且未发现遮挡时，根据配置尝试真实鼠标和 JS；已发现遮挡则停止，避免点击背景提交按钮。原生调用遇到对象释放异常时不补点，因为先前操作可能已经生效。

显式 native、mouse、js 分别约束执行方式。鼠标坐标点击不能自动证明目标就是该元素，JS 事件也可能被框架拒绝。回执应记录实际 mode、命中对象与观察结果；不能把“派发成功”写成“业务成功”。

{"id":"1001","method":"click_element_by_selector","params":{"selector":"#preview-button","mode":"native","timeoutMs":3000}}

3. 输入与框架状态

真实输入会参与浏览器事件流程；JS 降级通过属性 setter 和 input/change 事件设置值，但不保证框架模型接受，因此有 committed 等说明。只读、禁用、隐藏及不可编辑是不同失败原因，不应全部换成 JS 强写。

{"id":"1001","method":"input_text_by_selector","params":{"selector":"#display-name","text":"示例用户","mode":"type"}}

输入后用 get_form_state 回读，尤其是在 Windows shell 传中文时。传参完整性与浏览器是否成功填值是两个问题。

4. 下拉框、滚动与拖拽

get_dropdown_options 从原生 select 的 options 读取文本；select_dropdown_option 按 label 选择。由 div 模拟的下拉框没有原生 options，应展开后对实际选项点击，不能硬套 select 接口。

scroll 的参数是 down、numPages 和可选 index。没有 index 时循环发 PageDown/PageUp；有 index 时对对应容器执行 scrollBy，距离按视口高度计算。它不是接收任意像素数的接口。scroll_to_text 则定位文字并滚动到可见范围。

drag_element_by_index 解析源索引和 targetIndex，调用拖拽操作。布局变化后要重取两端索引，不能只更新源元素。

5. 键盘与鼠标是更低层的工具

坐标按浏览器页面坐标使用，不能直接复制经过缩放的截图像素。窗口尺寸、页面视口与截图像素差异见第 10 篇。

6. 回归测试设计

准备背景提交按钮、覆盖层和前景按钮，分别记录点击次数。验证 auto 不触发背景按钮，重复选择器选到前景控件；再注入对象释放异常，确认没有第二次点击。输入测试应检查框架监听器收到的值，而不是仅检查 DOM attribute。原生 select 和自定义下拉框使用不同 fixture，避免错误实现只在一种控件上通过。

注册参数与 Java 入口

以下按 CommandTable 实际读取参数整理。* 表示注册层使用必填读取器；其余字段省略后由服务决定默认行为。带条件的入口仍需满足正文说明，例如上传文件来源、元素定位二选一。外层 id 不重复列出。