完整 API
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();
}
一眼看全
调用路径
Gestures,再走 AgentClient 的同一条长连接——和 Session 共用,因此不会多开隧道,也不会互抢设备锁。应用管理、文件传输与系统状态才读 hdc。坐标与目标
接受位置的参数统一叫 Target,四种写法可以互换:
opts.area 时相对那个区域。opts.offset 取控件内的相对位置,默认中心。四种注入通道
同样是「点一下」,设备上有四条路。SDK 按动作类型选最快的可用通道,而不是统一调 Driver.swipe:
On)作为目标时,动作直接交给设备侧的控件对象:它知道自己被点在哪,而坐标点击只是往屏幕上打一个点。状态含义
| 标记 | catalog | 数量 | 含义 |
|---|---|---|---|
| 已验证 | verified | 106 | 真机逐条跑过 |
| 已实现 | device | 4 | 接口在,真机验收未覆盖 |
| 宿主侧 | host | 0 | 主机上执行或别名,不单独发设备请求 |
| 需硬件 | hardware | 3 | 手写笔 / 表冠 / 触控板,无硬件时明确报错 |
| 不可用 | unsupported | 5 | 设备扩展无法提供,调用立即抛 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
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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" });
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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),
);
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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]);
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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 });
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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 },
);
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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");
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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();
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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);
}
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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: "设置" }));
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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" }); // 存到主机
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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 });
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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");
}
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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");
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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"));
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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 会等这么久
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
wait |
wait |
已验证 | 宿主侧等待 N 秒 |
waitForIdle |
wait_for_idle |
已验证 | 设备侧等到画面静止 |
setImplicitWaitTime |
set_implicit_wait_time |
已验证 | 设置隐式等待秒数 |
getImplicitWaitTime |
get_implicit_wait_time |
已验证 | 读隐式等待秒数 |
输入法1 个
await dev.hypium.inputTextOnCurrentCursor("hello");
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
inputTextOnCurrentCursor |
input_text_on_current_cursor |
已验证 | 向当前光标输入 |
特殊硬件3 个
// 没有对应硬件时抛 UnsupportedError,而不是静默失败:
await dev.hypium.rotateCrown(2); // 手表表冠
await dev.hypium.touchpadSwipe("up"); // 二合一触控板
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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 });
| TypeScript | hypium 原名 | 状态 | 说明 |
|---|---|---|---|
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 的差异
sn()返回设备序列号的 8 位哈希(如6c585f5b),原始序列号不会出现在任何返回值、trace 或报告里。- Toast 与 UI 事件五个方法抛
UnsupportedError:设备侧的UIEventObserver会从start返回,但对getRecentUiEvent永不回复(实测 30 秒超时)。 findImage只有模板匹配(mode: "template",JPEG 模板);sift需要主机侧 OpenCV,传了会明确报错。setDisplayRotation只接受0/1/2/3;设备参数校验器拒绝字符串。ScreenLock.isLocked()读真实锁屏状态,而不是固定返回false。pushFile会把本地路径转成绝对路径再发:实测相对路径会被 hdc 当成目录树,在设备上建出一个同名文件夹。