EasyClick iOS USB版：USB HID功能详解与实战指南

EasyClick iOS USB版：USB HID功能详解与实战指南

前言

在iOS自动化开发领域，EasyClick（EC）一直以其免越狱、易用性著称。今天我们要深入探讨的是EC iOS USB版中一个非常强大的功能------USB HID（Human Interface Device）。

如果你正在寻找一种无需蓝牙开发板、无需OTG设备，仅通过USB数据线就能实现iOS设备自动化操控的方案，那么这篇文章就是为你准备的。

---

什么是USB HID？

USB HID是EasyClick在10.7.0版本中引入的新功能，它允许你通过USB数据线直接模拟触摸、滑动、按键等操作。与传统的蓝牙HID和OTG HID不同，USB HID有以下特点：

核心优势

1. 无需额外硬件：不需要蓝牙开发板或OTG开发板
2. 即插即用：只需一根USB数据线
3. 坐标精确：坐标与投屏画面、截图像素坐标完全一致
4. 稳定性高：有线连接，不受无线干扰
5. 兼容性好：支持iOS 17+系统

与其他模式的对比

特性	USB HID	蓝牙HID	OTG HID	代理模式
硬件需求	仅USB线	蓝牙开发板	OTG开发板	无
连接方式	USB有线	蓝牙无线	USB有线	USB代理
稳定性	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
延迟	低	中	低	低
适用场景	通用	无USB口设备	高稳定性要求	开发调试

---

环境准备

硬件要求

• Mac/Windows电脑
• iPhone/iPad（建议iOS 17+）
• USB数据线（Lightning或Type-C）
• EasyClick iOS USB版 10.7.0+

软件要求

1. EasyClick IDE：安装最新版EC IDE
2. 代理IPA：在iOS设备上安装EC代理App
3. Xcode（Mac）：用于签名和安装代理IPA

连接步骤

1. 使用USB数据线连接iOS设备到电脑
2. 在iOS设备上信任此电脑
3. 打开EC代理App
4. 在EC IDE中确认设备连接成功

---

快速上手

基础示例

function main() {
    // 1. 开启USB HID会话
    let r = usbHidEvent.sessionStart(true)
    if (r != null && r !== "") {
        logw("开启USB HID失败: " + r)
        return
    }
    
    // 2. 设置屏幕尺寸（必须与设备实际分辨率一致）
    r = usbHidEvent.setScreenSize(1170, 2532)  // iPhone 14 Pro Max
    if (r != null && r !== "") {
        logw("设置屏幕尺寸失败: " + r)
        return
    }
    
    // 3. 执行点击操作
    r = usbHidEvent.clickPoint(200, 400)
    logd("点击: " + (r == null || r === "" ? "成功" : r))
    
    // 4. 输入文本
    r = usbHidEvent.typeText("hello")
    logd("英文打字: " + (r == null || r === "" ? "成功" : r))
    
    // 5. 中文输入（粘贴方式）
    r = usbHidEvent.inputText("中文测试")
    logd("中文粘贴: " + (r == null || r === "" ? "成功" : r))
    
    // 6. 按Home键
    r = usbHidEvent.systemKey("home")
    logd("Home: " + (r == null || r === "" ? "成功" : r))
    
    // 7. 关闭会话
    usbHidEvent.sessionStop()
}

main()

常用设备分辨率参考

设备型号	分辨率
iPhone 14/15	1170 × 2532
iPhone 14 Pro/15 Pro	1179 × 2556
iPhone 14 Pro Max/15 Pro Max	1290 × 2796
iPhone 13 mini	1080 × 2340
iPad Pro 11"	1668 × 2388
iPad Pro 12.9"	2048 × 2732

---

核心API详解

会话管理

// 开启会话（true=增强兼容模式）
let r = usbHidEvent.sessionStart(true)

// 关闭会话
usbHidEvent.sessionStop()

// 重置会话（断流时使用）
let r = usbHidEvent.sessionRestart(true)

触摸操作

// 单击
usbHidEvent.clickPoint(x, y)

// 长按（x, y, 毫秒数）
usbHidEvent.press(300, 500, 800)

// 双击
usbHidEvent.doubleClickPoint(200, 400)

// 手势操作（按下-移动-抬起）
usbHidEvent.touchDown(100, 200)
usbHidEvent.touchMove(150, 260)
usbHidEvent.touchUp(150, 260)

滑动操作

// 基础滑动（起始X, 起始Y, 结束X, 结束Y, 毫秒）
usbHidEvent.swipeToPoint(100, 600, 300, 200, 500)

// 多点触摸（复杂手势）
let touch1 = [
    {"action": 0, "x": 100, "y": 500, "delay": 20},  // 按下
    {"action": 2, "x": 100, "y": 300, "delay": 30},  // 移动
    {"action": 1, "x": 100, "y": 300, "delay": 20}   // 抬起
]
usbHidEvent.multiTouch(touch1, 10000)

系统按键

// Home键
usbHidEvent.systemKey("home")

// 最近应用
usbHidEvent.systemKey("recents")

// 锁屏
usbHidEvent.systemKey("lock")

// 音量控制
usbHidEvent.volumeUp()
usbHidEvent.volumeDown()
usbHidEvent.mute()

文本输入

// 英文打字（模拟键盘输入）
usbHidEvent.typeText("hello")

// 中文输入（剪贴板粘贴）
usbHidEvent.inputText("中文测试")

// 组合键
usbHidEvent.keyPressChar("gui", "v")        // Command+V
usbHidEvent.keyPressChar("ctrl", "c")       // Ctrl+C
usbHidEvent.keyPressChar("shift", "a")      // Shift+A

// 单个按键
usbHidEvent.keyPress("enter")
usbHidEvent.keyPress("shift")

// 清除所有按键
usbHidEvent.keyUp()

剪贴板操作

// 设置剪贴板
usbHidEvent.setClipboard("要粘贴的内容")
usbHidEvent.keyPressChar("gui", "v")  // 粘贴

// 读取剪贴板（已知不稳定）
let text = usbHidEvent.getClipboard()

---

实战案例

案例1：自动打开App并点击

function autoOpenAndClick() {
    // 开启USB HID
    let r = usbHidEvent.sessionStart(true)
    if (r != null && r !== "") {
        logw("开启失败: " + r)
        return
    }
    
    // 设置屏幕尺寸
    usbHidEvent.setScreenSize(1170, 2532)
    
    // 按Home键回到主屏幕
    usbHidEvent.systemKey("home")
    sleep(1000)
    
    // 点击某个App图标（假设在坐标300,500）
    usbHidEvent.clickPoint(300, 500)
    sleep(2000)
    
    // 等待App加载后点击某个按钮
    usbHidEvent.clickPoint(500, 800)
    
    // 关闭会话
    usbHidEvent.sessionStop()
}

autoOpenAndClick()

案例2：自动填写表单

function autoFillForm() {
    // 开启USB HID
    usbHidEvent.sessionStart(true)
    usbHidEvent.setScreenSize(1170, 2532)
    
    // 点击输入框
    usbHidEvent.clickPoint(400, 300)
    sleep(500)
    
    // 清空输入框（全选+删除）
    usbHidEvent.keyPressChar("gui", "a")
    usbHidEvent.keyPress("delete")
    sleep(300)
    
    // 输入用户名
    usbHidEvent.typeText("username123")
    sleep(500)
    
    // 点击密码框
    usbHidEvent.clickPoint(400, 400)
    sleep(500)
    
    // 输入密码
    usbHidEvent.typeText("password123")
    sleep(500)
    
    // 点击登录按钮
    usbHidEvent.clickPoint(400, 500)
    
    // 关闭会话
    usbHidEvent.sessionStop()
}

autoFillForm()

案例3：自动滑动浏览

function autoScroll() {
    // 开启USB HID
    usbHidEvent.sessionStart(true)
    usbHidEvent.setScreenSize(1170, 2532)
    
    // 向下滑动10次
    for (let i = 0; i < 10; i++) {
        usbHidEvent.swipeToPoint(500, 1500, 500, 500, 500)
        sleep(1000)
        logd("滑动次数: " + (i + 1))
    }
    
    // 关闭会话
    usbHidEvent.sessionStop()
}

autoScroll()

---

常见问题与解决方案

问题1：USB HID开启失败

错误信息 ：开启USB HID失败: xxx

解决方案：

1. 确认USB数据线连接正常
2. 确认iOS设备已信任此电脑
3. 确认代理App已打开并正常运行
4. 确认EC IDE版本 ≥ 10.7.0
5. 尝试重启代理App

问题2：设置屏幕尺寸失败

错误信息 ：设置屏幕尺寸失败: xxx

解决方案：

1. 确认设备型号对应的分辨率正确
2. 确认设备当前是竖屏模式（横屏需要对调宽高）
3. 尝试使用sessionRestart(true)重置会话

问题3：点击无响应

可能原因：

1. 坐标设置错误
2. 屏幕尺寸设置不正确
3. 被控App界面未完全加载

解决方案：

1. 使用EC IDE的截图功能确认坐标
2. 确认屏幕尺寸与设备实际分辨率一致
3. 在点击前添加适当的等待时间

问题4：文本输入乱码

可能原因：

1. 使用了错误的输入方法
2. 中文输入未使用粘贴方式

解决方案：

1. 英文使用typeText()
2. 中文使用inputText()（粘贴方式）
3. 长文本建议先设置剪贴板再粘贴

---

最佳实践

1. 会话管理

// 好的做法：始终管理会话
function main() {
    try {
        let r = usbHidEvent.sessionStart(true)
        if (r != null && r !== "") {
            logw("开启失败: " + r)
            return
        }
        
        // 业务逻辑
        doBusiness()
        
    } catch (e) {
        loge("异常: " + e.message)
    } finally {
        // 确保会话关闭
        usbHidEvent.sessionStop()
    }
}

2. 错误处理

// 好的做法：检查每个操作的返回值
let r = usbHidEvent.clickPoint(200, 400)
if (r != null && r !== "") {
    logw("点击失败: " + r)
    // 尝试重置会话
    usbHidEvent.sessionRestart(true)
    // 重试操作
    r = usbHidEvent.clickPoint(200, 400)
}

3. 等待与延时

// 好的做法：关键操作后添加等待
usbHidEvent.clickPoint(300, 500)
sleep(1000)  // 等待界面响应

usbHidEvent.typeText("hello")
sleep(500)  // 等待输入完成

4. 坐标校准

// 好的做法：使用截图确认坐标
let img = imageAgent.captureScreen()
// 保存截图分析坐标
image.saveImage(img, "screenshot.png")
// 根据截图调整坐标

---

进阶技巧

1. 结合节点操作

USB HID可以与节点操作结合使用，实现更稳定的自动化：

// 先尝试节点操作
let node = nodeAgent.getNodeInfo(label("按钮"), 3000)
if (node) {
    // 节点存在，使用节点点击
    nodeAgent.click(node)
} else {
    // 节点不存在，使用USB HID点击预设坐标
    usbHidEvent.clickPoint(500, 800)
}

2. 结合图色识别

USB HID可以与图色识别结合，实现更智能的自动化：

// 截图识别
let img = imageAgent.captureScreen()
// 识别目标位置
let target = image.findImage(img, template, 0.8)
if (target) {
    // 使用USB HID点击识别到的位置
    usbHidEvent.clickPoint(target.x, target.y)
}

3. 混合模式使用

可以根据场景混合使用不同模式：

// 开发调试时使用代理模式
// 生产环境使用USB HID模式
function main() {
    if (isDevMode()) {
        // 代理模式
        nodeAgent.clickPoint(200, 400)
    } else {
        // USB HID模式
        usbHidEvent.sessionStart(true)
        usbHidEvent.setScreenSize(1170, 2532)
        usbHidEvent.clickPoint(200, 400)
        usbHidEvent.sessionStop()
    }
}

---

总结

EasyClick iOS USB版的USB HID功能为iOS自动化开发带来了新的可能性。它无需额外硬件，只需一根USB数据线就能实现稳定的自动化操控，非常适合以下场景：

1. 批量设备测试：快速测试多台iOS设备
2. 自动化脚本开发：快速原型开发和调试
3. 生产环境部署：稳定的自动化执行
4. 无蓝牙/OTG设备：资源受限环境下的自动化

通过本文的介绍，相信你已经掌握了USB HID的基本使用方法。在实际开发中，建议结合节点操作、图色识别等技术，构建更加强大和稳定的自动化解决方案。

---

参考资源

• EasyClick官方文档
• EC iOS USB版 API参考
• iOS设备分辨率速查表

---

作者注：本文基于EasyClick iOS USB版 10.7.0+版本编写，部分API可能在后续版本中有更新，请以官方文档为准。