完整 API

uitest-sdk 0.8.0 · hypium 6.1.0.210 · 118 个方法

DevEco Testing 的 hypium 驱动在设备上公开 118 个方法(OHOSDriver 106 个 + 兼容层 12 个)。dev.hypium 把它们逐个映射成 TypeScript 的同名 camelCase 方法,参数与返回值按设备实际行为定,不是照着文档猜的:每一条都在真机(BRA-AL00 / uitest 7.0.0.1)上跑过,状态标在表里。

import { Device, On, Gesture, UnsupportedError } from "uitest-sdk";

const dev = await Device.connect();
try {
  await dev.hypium.click(On.text("设置"));
  await dev.hypium.waitForComponent(On.text("WLAN"), { timeoutMs: 3000 });
} finally {
  await dev.dispose();
}

一眼看全

118 个方法 · 19 个类别 条长为该类的方法数,右侧是数量 屏幕、电源与锁屏 10 点击 4 滑动与路径 10 多指 3 鼠标 7 手写笔 7 文本与键盘 5 系统按键 6 控件 11 窗口 6 屏幕与坐标 4 图像识别 3 Toast 与 UI 事件 5 应用管理 7 hdc 与文件 5 等待 4 输入法 1 特殊硬件 3 设备信息、日志与钩子 17
同一份清单也被单元测试用来核对:目录里少一个方法、多一个方法、或方法名对不上驱动,测试都会失败。

调用路径

dev.hypium HypiumDriver AgentClient 一条 TCP · 串行队列 agent.so uitest daemon · :8012 设备 触摸 / 布局 / 截图 Gestures touchDown/Move/Up HdcRunner shell / file / fport hdc 命令行工具 设备 应用 / 文件 / 系统状态
点击、滑动与手势先落到 Gestures,再走 AgentClient 的同一条长连接——和 Session 共用,因此不会多开隧道,也不会互抢设备锁。应用管理、文件传输与系统状态才读 hdc。

坐标与目标

接受位置的参数统一叫 Target,四种写法可以互换:

绝对坐标 { x, y } 屏幕比例 [0.5, 0.5] 矩形 { x, y, width, height } 选择器 / 控件 On · ComponentHandle 解析成整数像素 比例 × 显示尺寸 控件取 bounds 中心 矩形取中心 + offset 显示坐标 1216 × 2688 点 (x, y)
比例坐标相对整个屏幕;给 opts.area 时相对那个区域。opts.offset 取控件内的相对位置,默认中心。

四种注入通道

同样是「点一下」,设备上有四条路。SDK 按动作类型选最快的可用通道,而不是统一调 Driver.swipe:

单指 touchDown/Move/Up click · swipe drag · fling longClick · slide 实测最快 8–30 ms / 次 PointerMatrix 多条同时轨迹 pinchIn / pinchOut multiFingerTouch twoFingerSwipe injectGesture 单指通道表达不了 鼠标 / 手写笔 Driver.mouse* / pen* mouseClick / Scroll penClick / penSwipe 带按键与压感 桌面形态专用 控件自身 Component.click 等 touch(On…) switchComponentStatus inputText(On…) 设备侧判定命中 不受遮挡影响
选择器(On)作为目标时,动作直接交给设备侧的控件对象:它知道自己被点在哪,而坐标点击只是往屏幕上打一个点。

状态含义

标记catalog数量含义
已验证verified106真机逐条跑过
已实现device4接口在,真机验收未覆盖
宿主侧host0主机上执行或别名,不单独发设备请求
需硬件hardware3手写笔 / 表冠 / 触控板,无硬件时明确报错
不可用unsupported5设备扩展无法提供,调用立即抛 UnsupportedError

状态不是宣传语。标「已验证」的每一条都在真机上执行并检查了结果;标「已实现」的接口存在、参数按设备行为校验,但还没有一次成功的真机验收(安装、卸载、清数据这三条属于破坏性操作)。标「不可用」的是实测走不通的路径,调用立即抛 UnsupportedError,不会挂起 30 秒再超时。

全部方法

下面按类别列出全部 118 个方法。第一列是 TypeScript 名,第二列是 hypium 的原名——两者除了大小写与下划线之外一一对应,方便对照官方 Python 示例。

屏幕、电源与锁屏10 个

await dev.hypium.wakeUpDisplay();
if (await dev.hypium.isDisplayLocked()) await dev.hypium.unlock();
await dev.hypium.setDisplayRotationEnabled(true);
await dev.hypium.setDisplayRotation(1);   // 只接受 0/1/2/3
TypeScripthypium 原名状态说明
closeDisplay close_display 已验证 熄屏(power-shell suspend)
unlock unlock 已验证 上滑解锁;PIN 仍需人解
上滑解锁;设了 PIN 或图案时仍需人来解
setSleepTime set_sleep_time 已验证 设置休眠秒数
restoreSleepTime restore_sleep_time 已验证 恢复默认休眠时间
isDisplayOn is_display_on 已验证 读电源服务判断是否亮屏
isDisplayLocked is_display_locked 已验证 读锁屏服务判断是否上锁
wakeUpDisplay wake_up_display 已验证 点亮屏幕
getDisplayRotation get_display_rotation 已验证 读当前旋转 0–3
setDisplayRotation set_display_rotation 已验证 设旋转角度,只收整数
调用成功;这台手机的自动旋转关着,所以方向不变
setDisplayRotationEnabled set_display_rotation_enabled 已验证 开/关自动旋转

点击4 个

await dev.hypium.click({ x: 608, y: 1344 });        // 绝对坐标
await dev.hypium.click([0.5, 0.5]);                 // 屏幕比例
await dev.hypium.longClick(On.text("复制"), { pressTime: 1.2 });
await dev.hypium.touch(On.type("Button"), { mode: "double" });
TypeScripthypium 原名状态说明
click click 已验证 点一下;坐标或选择器
doubleClick double_click 已验证 连点两下
longClick long_click 已验证 按住 pressTime 秒
touch touch 已验证 按 mode 选点/长按/双击

滑动与路径10 个

await dev.hypium.swipe("up", { distance: 40, durationMs: 200 });
await dev.hypium.fling("up", { speed: "fast" });
await dev.hypium.drag(On.text("卡片"), { x: 900, y: 300 }, { pressMs: 800 });
await dev.hypium.pinchOut(On.type("Swiper"), { scale: 1.5 });
await dev.hypium.injectGesture(
  new Gesture().start([0.5, 0.8]).moveTo([0.5, 0.4], 0.2).pause(0.1),
);
TypeScripthypium 原名状态说明
drag drag 已验证 先按住再拖,用于排序
slide slide 已验证 两点之间匀速滑动
swipe swipe 已验证 按方向滑动,可给距离
fling fling 已验证 快速甩动,松手带惯性
swipeToHome swipe_to_home 已验证 上滑回桌面
swipeToBack swipe_to_back 已验证 从屏幕边缘滑回
swipeToRecentTask swipe_to_recent_task 已验证 上滑停住进多任务
pinchIn pinch_in 已验证 双指收拢缩小
pinchOut pinch_out 已验证 双指张开放大
injectGesture inject_gesture 已验证 回放自定义手势路径

多指3 个

await dev.hypium.multiFingerTouch([[0.3, 0.5], [0.7, 0.5]], { durationMs: 80 });
await dev.hypium.twoFingerSwipe([0.3, 0.7], [0.3, 0.4], [0.7, 0.7], [0.7, 0.4]);
TypeScripthypium 原名状态说明
injectMultiFingerGesture inject_multi_finger_gesture 已验证 多指同时回放不同路径
twoFingerSwipe two_finger_swipe 已验证 两指同向滑动
multiFingerTouch multi_finger_touch 已验证 多指同时点按

鼠标7 个

await dev.hypium.mouseClick({ x: 400, y: 300 }, { button: "right" });
await dev.hypium.mouseScroll({ x: 400, y: 300 }, "down", 3);
await dev.hypium.mouseMove({ x: 100, y: 100 }, { x: 400, y: 300 }, { speed: 3000 });
TypeScripthypium 原名状态说明
mouseDoubleClick mouse_double_click 已验证 鼠标双击
mouseLongClick mouse_long_click 已验证 鼠标长按
mouseClick mouse_click 已验证 鼠标点击,可带按键
mouseScroll mouse_scroll 已验证 滚轮上/下滚 N 格
mouseMoveTo mouse_move_to 已验证 鼠标移到某点
mouseMove mouse_move 已验证 鼠标沿轨迹移动
mouseDrag mouse_drag 已验证 按住鼠标拖动

手写笔7 个

await dev.hypium.penClick({ x: 300, y: 800 });
await dev.hypium.penLongClick({ x: 300, y: 800 }, { pressure: 0.4 });
await dev.hypium.penInjectGesture(
  new Gesture().start([0.3, 0.6]).moveTo([0.7, 0.6], 0.3),
  { pressure: 0.5 },
);
TypeScripthypium 原名状态说明
penClick pen_click 已验证 手写笔点一下
penDoubleClick pen_double_click 已验证 手写笔双击
penLongClick pen_long_click 已验证 手写笔长按,可带压感
penSwipe pen_swipe 已验证 手写笔按方向划
penSlide pen_slide 已验证 手写笔两点之间划
penDrag pen_drag 已验证 手写笔按住拖动
penInjectGesture pen_inject_gesture 已验证 回放手写笔手势,带压感

文本与键盘5 个

await dev.hypium.inputText(On.type("SearchField"), "wlan");
await dev.hypium.clearText(On.type("SearchField"));
await dev.hypium.pressKey("enter");
await dev.hypium.pressCombinationKey("ctrl_left", "a");
TypeScripthypium 原名状态说明
inputText input_text 已验证 向控件或坐标输入文本
clearText clear_text 已验证 清空输入框
moveCursor move_cursor 已验证 移动光标或跳到行首行尾
pressKey press_key 已验证 按一个键,可长按/连按
pressCombinationKey press_combination_key 已验证 组合键,如 Ctrl+A

系统按键6 个

await dev.hypium.pressBack();
await dev.hypium.goHome();
await dev.hypium.pressPower();
TypeScripthypium 原名状态说明
pressHome press_home 已验证 按 Home 键
goHome go_home 已验证 回桌面;桌面形态走 Meta+D
goBack go_back 已验证 返回;手机形态走边缘滑动
pressBack press_back 已验证 按返回键
pressPower press_power 已验证 按电源键
takeScreenshot take_screenshot 已实现 模拟截屏组合键
模拟音量下 + 电源;文件进媒体库,shell 读不到

控件11 个

const handle = await dev.hypium.findComponent(On.text("WLAN"));
if (handle) {
  console.log(await dev.hypium.getComponentProperty(handle, "bounds"));
  await dev.hypium.checkComponent(handle, { enabled: true });
  await dev.hypium.switchComponentStatus(handle, true);
}
TypeScripthypium 原名状态说明
getComponentPos get_component_pos 已验证 取控件中心点
getComponentBound get_component_bound 已验证 取控件矩形
getComponentProperty get_component_property 已验证 按属性名读值
findComponent find_component 已验证 按选择器找控件
findAllComponents find_all_components 已验证 找全部,可按序号取一个
switchComponentStatus switch_component_status 已验证 把勾选状态切到目标值
checkExist check_exist 已验证 断言控件存在与否
checkComponentExist check_component_exist 已验证 同上,可等可滚动查找
checkComponent check_component 已验证 断言多个属性值
waitForComponent wait_for_component 已验证 设备侧等到控件出现
waitForComponentDisappear wait_for_component_disappear 已验证 宿主轮询等到消失

窗口6 个

const win = await dev.hypium.findWindow({ bundleName: "com.huawei.hmos.settings" });
if (win) console.log(await dev.hypium.checkWindow(win, { title: "设置" }));
TypeScripthypium 原名状态说明
findWindow find_window 已验证 按标题/包名/焦点找窗口
getWindowSize get_window_size 已验证 取当前窗口尺寸
getCurrentWindow get_current_window 已验证 取激活窗口,退回焦点窗口
checkCurrentWindow check_current_window 已验证 断言当前窗口
checkWindow check_window 已验证 断言指定窗口的标题/包名
checkWindowExist check_window_exist 已验证 断言窗口存在与否

屏幕与坐标4 个

const { width, height } = await dev.hypium.getDisplaySize();
const jpeg = await dev.hypium.captureScreen({ scale: 0.5 });   // Buffer
await dev.hypium.captureScreen({ savePath: "shot.jpeg" });      // 存到主机
TypeScripthypium 原名状态说明
getDisplaySize get_display_size 已验证 显示尺寸,坐标基准
captureScreen capture_screen 已验证 截图;Buffer 或存文件
toAbsolutePosition to_absolute_position 已验证 比例坐标换成像素
toAbsPos to_abs_pos 已验证 同上

图像识别3 个

const rect = await dev.hypium.findImage("button.jpeg", { similarity: 0.92 });
await dev.hypium.touchImage("button.jpeg");
await dev.hypium.checkImageExist("toast.jpeg", { timeoutMs: 2000 });
TypeScripthypium 原名状态说明
findImage find_image 已验证 在截图里找模板,返回矩形
模板匹配;SIFT 需要主机侧 OpenCV
touchImage touch_image 已验证 找到模板并点击中心
模板匹配;SIFT 需要主机侧 OpenCV
checkImageExist check_image_exist 已验证 轮询断言图像是否出现
模板匹配;SIFT 需要主机侧 OpenCV

Toast 与 UI 事件5 个

// 设备侧的 UIEventObserver 在原始 RPC 上永不回复,下面这些调用立即抛错:
try {
  await dev.hypium.getLatestToast();
} catch (e) {
  if (e instanceof UnsupportedError) console.log("这台设备给不了 Toast");
}
TypeScripthypium 原名状态说明
startListenToast start_listen_toast 不可用 不可用:观察者不回复
UIEventObserver 在原始 RPC 上永不回复
getLatestToast get_latest_toast 不可用 不可用:观察者不回复
UIEventObserver 在原始 RPC 上永不回复
checkToast check_toast 不可用 不可用:观察者不回复
UIEventObserver 在原始 RPC 上永不回复
startListenUiEvent start_listen_ui_event 不可用 不可用:观察者不回复
UIEventObserver 在原始 RPC 上永不回复
getLatestUiEvent get_latest_ui_event 不可用 不可用:观察者不回复
UIEventObserver 在原始 RPC 上永不回复

应用管理7 个

await dev.hypium.startApp("com.huawei.hmos.settings");
console.log(await dev.hypium.currentApp());   // ["com.huawei.hmos.settings", "MainAbility"]
await dev.hypium.stopApp("com.huawei.hmos.settings");
TypeScripthypium 原名状态说明
startApp start_app 已验证 aa start 拉起应用
stopApp stop_app 已验证 强制结束应用
hasApp has_app 已验证 判断应用是否安装
currentApp current_app 已验证 取前台包名与 Ability
installApp install_app 已实现 hdc install 安装 hap
坏路径会被报出;未做过一次成功的安装
uninstallApp uninstall_app 已实现 bm uninstall 卸载
不存在的包会被报出;未做过一次成功的卸载
clearAppData clear_app_data 已实现 清除应用数据
破坏性操作,未在真实应用上执行

hdc 与文件5 个

await dev.hypium.pushFile("local.txt", "/data/local/tmp/local.txt");
console.log(await dev.hypium.hasFile("/data/local/tmp/local.txt"));
await dev.hypium.pullFile("/data/local/tmp/local.txt", "back.txt");
console.log(await dev.hypium.hdc("list targets"));
TypeScripthypium 原名状态说明
hdc hdc 已验证 执行任意 hdc 子命令
shell shell 已验证 在设备上执行 shell
pullFile pull_file 已验证 从设备取文件
pushFile push_file 已验证 向设备推文件
hasFile has_file 已验证 判断设备上文件存在

等待4 个

await dev.hypium.waitForIdle({ idleMs: 300, timeoutMs: 5000 });
await dev.hypium.waitForComponent(On.text("完成"), { timeoutMs: 3000 });
await dev.hypium.setImplicitWaitTime(2);   // findComponent 会等这么久
TypeScripthypium 原名状态说明
wait wait 已验证 宿主侧等待 N 秒
waitForIdle wait_for_idle 已验证 设备侧等到画面静止
setImplicitWaitTime set_implicit_wait_time 已验证 设置隐式等待秒数
getImplicitWaitTime get_implicit_wait_time 已验证 读隐式等待秒数

输入法1 个

await dev.hypium.inputTextOnCurrentCursor("hello");
TypeScripthypium 原名状态说明
inputTextOnCurrentCursor input_text_on_current_cursor 已验证 向当前光标输入

特殊硬件3 个

// 没有对应硬件时抛 UnsupportedError,而不是静默失败:
await dev.hypium.rotateCrown(2);       // 手表表冠
await dev.hypium.touchpadSwipe("up");  // 二合一触控板
TypeScripthypium 原名状态说明
touchpadSwipe touchpad_swipe 需硬件 触控板多指滑动
二合一设备的触控板
touchpadSwipeAndHold touchpad_swipe_and_hold 需硬件 触控板滑动并停住
二合一设备的触控板
rotateCrown rotate_crown 需硬件 转动手表表冠
手表表冠

设备信息、日志与钩子17 个

console.log(await dev.hypium.getDeviceType(), await dev.hypium.sn());
dev.hypium.addHook("ui_action_start", "log", (e) => console.log(e.operate_type));
await dev.hypium.click({ x: 10, y: 10 });
TypeScripthypium 原名状态说明
logDebug log_debug 已验证 打 debug 日志
logInfo log_info 已验证 打 info 日志
logWarning log_warning 已验证 打 warning 日志
logError log_error 已验证 打 error 日志
executeShellCommand execute_shell_command 已验证 同 shell,超时更长
executeConnectorCommand execute_connector_command 已验证 同 hdc,超时更长
deviceType device_type 已验证 设备形态,同 getDeviceType
sn sn 已验证 序列号的 8 位哈希
返回序列号的 8 位哈希,原始序列号不外泄
osType os_type 已验证 固定 OHOS
screenLock ScreenLock 已验证 锁屏对象,读 isLocked()
log log 已验证 日志器,可注入
getDeviceType get_device_type 已验证 读 product.devicetype
getOsType get_os_type 已验证 固定 OHOS
close close 已验证 清掉宿主侧钩子
addHook add_hook 已验证 注册动作前钩子
removeHook remove_hook 已验证 移除一个钩子
removeAllHooks remove_all_hooks 已验证 移除某类全部钩子

与 hypium 的差异

本页由 scripts/gen-api-page.mjs 从 src/hypium/catalog.ts 生成,清单与驱动方法的一致性由单元测试保证。数字来自 2026-11-16 的真机验收。