basic-control · type — 工具介绍

简介

向目标控件或当前焦点输入文本，可选先清空、可选提交回车。

用于在输入框、编辑栏、搜索框等可编辑控件里写入内容。优先用 UIA 原生方式（无前台要求），失败时回退到剪贴板粘贴。

输入参数

ref 和 name 二选一。ref 优先；都没有时，文本会发给当前焦点控件。

输出参数

strategy 取值

返回示例

成功（UIA 原生方式）

{

  "ok": true,

  "action": "type",

  "strategy": "uia_setvalue_clear",

  "targetRef": "e14",

  "targetName": "",

  "textLength": 12,

  "cleared": true,

  "submitted": false,

  "rootHandle": 69352

}

成功（剪贴板粘贴 + 提交）

{

  "ok": true,

  "action": "type",

  "strategy": "clipboard_paste_element",

  "targetRef": "e6",

  "targetName": "",

  "textLength": 3,

  "cleared": false,

  "submitted": true,

  "rootHandle": 200638

}

失败

{

  "ok": false,

  "error": "exception",

  "message": "..."

}

典型用法

行为说明与边界

1. 优先 UIA 原生：clear=true 且控件支持 ValuePattern 时，走 SetValue，不依赖前台、不怕遮挡，这是最可靠路径。

2. 回退剪贴板：没有 ValuePattern（如自绘输入框、部分搜索框）时，通过剪贴板 + Ctrl+V 粘贴。此路径需要窗口在前台，工具会先尝试 SetForegroundWindow 激活目标窗口。

3. 中文安全：剪贴板路径对中文、特殊字符都安全，不依赖键盘布局。这一点比逐字符 SendKeys 强。

4. submit 发的是回车：SendKeys.SendWait("{ENTER}")。在命令搜索框、对话框默认按钮上都有效。

5. 可能的副作用：

   • 剪贴板路径会覆盖用户剪贴板内容
   • SendKeys 依赖前台焦点，若窗口被抢焦点可能发到别处
   • SetForegroundWindow 在某些系统限制下可能失败（Windows 前台锁定）

6. 失败排查：

   • strategy=clipboard_paste_focus 说明既没找到元素、也没法定位，文本发给了当前焦点——很可能发错了地方
   • 如果写进去的内容不对，检查 ref 是否已过期（窗口变化后 ref 失效，需重新 observe）

配合使用

observe / find  →  拿到目标控件的 ref 或 name

type            →  写入文本

click           →  提交按钮（若不用 submit 回车）

定位：basic-control 是通用兜底层，对所有暴露 UIA 的 Windows 桌面软件适用。type 优先走无前台依赖的 UIA 路径，遇到自绘控件才回退到剪贴板粘贴。