1# @ohos.UiTest 2 3UiTest提供模拟UI操作的能力，供开发者在测试场景使用，主要支持如点击、双击、长按、滑动等UI操作能力。 4 5该模块提供以下功能： 6 7- [On<sup>9+</sup>](#on9)：提供控件特征描述能力，用于控件筛选匹配查找。 8- [Component<sup>9+</sup>](#component9)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。 9- [Driver<sup>9+</sup>](#driver9)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能力。 10- [UiWindow<sup>9+</sup>](#uiwindow9)：入口类，提供窗口属性获取，窗口拖动、调整窗口大小等能力。 11- [By<sup>(deprecated)</sup>](#bydeprecated)：提供控件特征描述能力，用于控件筛选匹配查找。从API version 9开始不再维护，建议使用[On<sup>9+</sup>](#on9)。 12- [UiComponent<sup>(deprecated)</sup>](#uicomponentdeprecated)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。从API version 9开始不再维护，建议使用[Component<sup>9+</sup>](#component9)。 13- [UiDriver<sup>(deprecated)</sup>](#uidriverdeprecated)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能力。从API version 9开始不再维护，建议使用[Driver<sup>9+</sup>](#driver9)。 14 15> **说明：** 16 > - 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 17 > - 本模块接口在[自动化测试脚本](../../application-test/arkxtest-guidelines.md)中使用。 18 19 20## 导入模块 21 22```ts 23import {UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix, UiDirection, MouseButton, UIElementInfo, UIEventObserver} from '@ohos.UiTest'; 24``` 25 26## MatchPattern 27 28控件属性支持的匹配模式。 29 30**系统能力**：SystemCapability.Test.UiTest 31 32| 名称 | 值 | 说明 | 33| ----------- | ---- | -------------- | 34| EQUALS | 0 | 等于给定值。 | 35| CONTAINS | 1 | 包含给定值。 | 36| STARTS_WITH | 2 | 以给定值开始。 | 37| ENDS_WITH | 3 | 以给定值结束。 | 38 39## ResizeDirection<sup>9+</sup> 40 41窗口调整大小的方向。 42 43**系统能力**：SystemCapability.Test.UiTest 44 45| 名称 | 值 | 说明 | 46| ---------- | ---- | -------- | 47| LEFT | 0 | 左方。 | 48| RIGHT | 1 | 右方。 | 49| UP | 2 | 上方。 | 50| DOWN | 3 | 下方。 | 51| LEFT_UP | 4 | 左上方。 | 52| LEFT_DOWN | 5 | 左下方。 | 53| RIGHT_UP | 6 | 右上方。 | 54| RIGHT_DOWN | 7 | 右下方。 | 55 56## Point<sup>9+</sup> 57 58坐标点信息。 59 60**系统能力**：SystemCapability.Test.UiTest 61 62| 名称 | 类型 | 可读 | 可写 | 说明 | 63| ---- | ------ | ---- | ---- | ---------------- | 64| x | number | 是 | 否 | 坐标点的横坐标。 | 65| y | number | 是 | 否 | 坐标点的纵坐标。 | 66 67## Rect<sup>9+</sup> 68 69控件的边框信息。 70 71**系统能力**：SystemCapability.Test.UiTest 72 73| 名称 | 类型 | 可读 | 可写 | 说明 | 74| ------ | ------ | ---- | ---- | ------------------------- | 75| left | number | 是 | 否 | 控件边框的左上角的X坐标。 | 76| top | number | 是 | 否 | 控件边框的左上角的Y坐标。 | 77| right | number | 是 | 否 | 控件边框的右下角的X坐标。 | 78| bottom | number | 是 | 否 | 控件边框的右下角的Y坐标。 | 79 80## WindowMode<sup>9+</sup> 81 82窗口的窗口模式。 83 84**系统能力**：SystemCapability.Test.UiTest 85 86| 名称 | 值 | 说明 | 87| ---------- | ---- | ---------- | 88| FULLSCREEN | 0 | 全屏模式。 | 89| PRIMARY | 1 | 主窗口。 | 90| SECONDARY | 2 | 第二窗口。 | 91| FLOATING | 3 | 浮动窗口。 | 92 93## DisplayRotation<sup>9+</sup> 94 95设备显示器的显示方向。 96 97**系统能力**：SystemCapability.Test.UiTest 98 99| 名称 | 值 | 说明 | 100| ------------ | ---- | ---------------------------------------- | 101| ROTATION_0 | 0 | 设备显示器不旋转，初始形态垂直显示。 | 102| ROTATION_90 | 1 | 设备显示器顺时针旋转90°，水平显示。 | 103| ROTATION_180 | 2 | 设备显示器顺时针旋转180°，逆向垂直显示。 | 104| ROTATION_270 | 3 | 设备显示器顺时针旋转270°，逆向水平显示。 | 105 106## WindowFilter<sup>9+</sup> 107 108窗口的标志属性信息。 109 110**系统能力**：SystemCapability.Test.UiTest 111 112| 名称 | 类型 | 可读 | 可写 | 说明 | 113| -------------------- | ------- | ---- | ---- | ------------------------------------------------------------ | 114| bundleName | string | 是 | 否 | 窗口归属应用的包名。 | 115| title | string | 是 | 否 | 窗口的标题信息。 | 116| focused | boolean | 是 | 否 | 窗口是否处于获焦状态。 | 117| actived(deprecated) | boolean | 是 | 否 | 窗口是否正与用户进行交互。<br>从API11开始，名称变更为active。 | 118| active<sup>11+</sup> | boolean | 是 | 否 | 窗口是否正与用户进行交互。 | 119 120## UiDirection<sup>10+</sup> 121 122进行抛滑等UI操作时的方向。 123 124**系统能力**：SystemCapability.Test.UiTest 125 126| 名称 | 值 | 说明 | 127| ----- | ---- | ------ | 128| LEFT | 0 | 向左。 | 129| RIGHT | 1 | 向右。 | 130| UP | 2 | 向上。 | 131| DOWN | 3 | 向下。 | 132 133## MouseButton<sup>10+</sup> 134 135模拟注入的鼠标按钮。 136 137**系统能力**：SystemCapability.Test.UiTest 138 139| 名称 | 值 | 说明 | 140| ------------------- | ---- | ------------ | 141| MOUSE_BUTTON_LEFT | 0 | 鼠标左键。 | 142| MOUSE_BUTTON_RIGHT | 1 | 鼠标右键。 | 143| MOUSE_BUTTON_MIDDLE | 2 | 鼠标中间键。 | 144 145## UIElementInfo<sup>10+</sup> 146 147UI事件的相关信息。 148 149**系统能力**：SystemCapability.Test.UiTest 150 151| 名称 | 类型 | 可读 | 可写 | 说明 | 152| ---------- | ------ | ---- | ---- | --------------------- | 153| bundleName | string | 是 | 否 | 归属应用的包名。 | 154| type | string | 是 | 否 | 控件/窗口类型。 | 155| text | string | 是 | 否 | 控件/窗口的文本信息。 | 156 157## On<sup>9+</sup> 158 159UiTest框架在API 9中，通过On类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。<br> 160On提供的API能力具有以下几个特点:<br>1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。<br>2、控件属性支持多种匹配模式。<br>3、支持控件绝对定位，相对定位，可通过[ON.isBefore](#isbefore9)和[ON.isAfter](#isafter9)等API限定邻近控件特征进行辅助定位。<br>On类提供的所有API均为同步接口，建议使用者通过静态构造器ON来链式创建On对象。 161 162```ts 163import { ON } from '@ohos.UiTest'; 164ON.text('123').type('Button'); 165``` 166 167### text<sup>9+</sup> 168 169text(txt: string, pattern?: MatchPattern): On 170 171指定目标控件文本属性，支持多种匹配模式，返回On对象自身。 172 173**系统能力**：SystemCapability.Test.UiTest 174 175**参数：** 176 177| 参数名 | 类型 | 必填 | 说明 | 178| ------- | ----------------------------- | ---- | --------------------------------------------------- | 179| txt | string | 是 | 指定控件文本，用于匹配目标控件文本。 | 180| pattern | [MatchPattern](#matchpattern) | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 | 181 182**返回值：** 183 184| 类型 | 说明 | 185| ---------- | ---------------------------------- | 186| [On](#on9) | 返回指定目标控件文本属性的On对象。 | 187 188**示例：** 189 190```ts 191import { On, ON } from '@ohos.UiTest'; 192let on:On = ON.text('123'); // 使用静态构造器ON创建On对象，指定目标控件的text属性。 193``` 194 195### id<sup>9+</sup> 196 197id(id: string): On 198 199指定目标控件id属性，返回On对象自身。 200 201**系统能力**：SystemCapability.Test.UiTest 202 203**参数：** 204 205| 参数名 | 类型 | 必填 | 说明 | 206| ------ | ------ | ---- | ---------------- | 207| id | string | 是 | 指定控件的id值。 | 208 209**返回值：** 210 211| 类型 | 说明 | 212| ---------- | -------------------------------- | 213| [On](#on9) | 返回指定目标控件id属性的On对象。 | 214 215**示例：** 216 217```ts 218import { On, ON } from '@ohos.UiTest'; 219let on:On = ON.id('123'); // 使用静态构造器ON创建On对象，指定目标控件的id属性。 220``` 221 222 223### type<sup>9+</sup> 224 225type(tp: string): On 226 227指定目标控件的控件类型属性，返回On对象自身。 228 229**系统能力**：SystemCapability.Test.UiTest 230 231**参数：** 232 233| 参数名 | 类型 | 必填 | 说明 | 234| ------ | ------ | ---- | -------------- | 235| tp | string | 是 | 指定控件类型。 | 236 237**返回值：** 238 239| 类型 | 说明 | 240| ---------- | ---------------------------------------- | 241| [On](#on9) | 返回指定目标控件的控件类型属性的On对象。 | 242 243**示例：** 244 245```ts 246import { On, ON } from '@ohos.UiTest'; 247let on:On = ON.type('Button'); // 使用静态构造器ON创建On对象，指定目标控件的控件类型属性。 248``` 249 250 251### clickable<sup>9+</sup> 252 253clickable(b?: boolean): On 254 255指定目标控件的可点击状态属性，返回On对象自身。 256 257**系统能力**：SystemCapability.Test.UiTest 258 259**参数：** 260 261| 参数名 | 类型 | 必填 | 说明 | 262| ------ | ------- | ---- | ------------------------------------------------------------ | 263| b | boolean | 否 | 指定控件可点击状态，true：可点击，false：不可点击。默认为true。 | 264 265**返回值：** 266 267| 类型 | 说明 | 268| ---------- | ------------------------------------------ | 269| [On](#on9) | 返回指定目标控件的可点击状态属性的On对象。 | 270 271**示例：** 272 273```ts 274import { On, ON } from '@ohos.UiTest'; 275let on:On = ON.clickable(true); // 使用静态构造器ON创建On对象，指定目标控件的可点击状态属性。 276``` 277 278### longClickable<sup>9+</sup> 279 280longClickable(b?: boolean): On 281 282指定目标控件的可长按点击状态属性，返回On对象自身。 283 284**系统能力**：SystemCapability.Test.UiTest 285 286**参数：** 287 288| 参数名 | 类型 | 必填 | 说明 | 289| ------ | ------- | ---- | ------------------------------------------------------------ | 290| b | boolean | 否 | 指定控件可长按点击状态，true：可长按点击，false：不可长按点击。默认为true。 | 291 292**返回值：** 293 294| 类型 | 说明 | 295| ---------- | ---------------------------------------------- | 296| [On](#on9) | 返回指定目标控件的可长按点击状态属性的On对象。 | 297 298**示例：** 299 300```ts 301import { On, ON } from '@ohos.UiTest'; 302let on:On = ON.longClickable(true); // 使用静态构造器ON创建On对象，指定目标控件的可长按点击状态属性。 303``` 304 305 306### scrollable<sup>9+</sup> 307 308scrollable(b?: boolean): On 309 310指定目标控件的可滑动状态属性，返回On对象自身。 311 312**系统能力**：SystemCapability.Test.UiTest 313 314**参数：** 315 316| 参数名 | 类型 | 必填 | 说明 | 317| ------ | ------- | ---- | ----------------------------------------------------------- | 318| b | boolean | 否 | 控件可滑动状态，true：可滑动，false：不可滑动。默认为true。 | 319 320**返回值：** 321 322| 类型 | 说明 | 323| ---------- | ------------------------------------------ | 324| [On](#on9) | 返回指定目标控件的可滑动状态属性的On对象。 | 325 326**示例：** 327 328```ts 329import { On, ON } from '@ohos.UiTest'; 330let on:On = ON.scrollable(true); // 使用静态构造器ON创建On对象，指定目标控件的可滑动状态属性。 331``` 332 333### enabled<sup>9+</sup> 334 335enabled(b?: boolean): On 336 337指定目标控件的使能状态属性，返回On对象自身。 338 339**系统能力**：SystemCapability.Test.UiTest 340 341**参数：** 342 343| 参数名 | 类型 | 必填 | 说明 | 344| ------ | ------- | ---- | --------------------------------------------------------- | 345| b | boolean | 否 | 指定控件使能状态，true：使能，false：未使能。默认为true。 | 346 347**返回值：** 348 349| 类型 | 说明 | 350| ---------- | ---------------------------------------- | 351| [On](#on9) | 返回指定目标控件的使能状态属性的On对象。 | 352 353**示例：** 354 355```ts 356import { On, ON } from '@ohos.UiTest'; 357let on:On = ON.enabled(true); // 使用静态构造器ON创建On对象，指定目标控件的使能状态属性。 358``` 359 360### focused<sup>9+</sup> 361 362focused(b?: boolean): On 363 364指定目标控件的获焦状态属性，返回On对象自身。 365 366**系统能力**：SystemCapability.Test.UiTest 367 368**参数：** 369 370| 参数名 | 类型 | 必填 | 说明 | 371| ------ | ------- | ---- | ----------------------------------------------------- | 372| b | boolean | 否 | 控件获焦状态，true：获焦，false：未获焦。默认为true。 | 373 374**返回值：** 375 376| 类型 | 说明 | 377| ---------- | ---------------------------------------- | 378| [On](#on9) | 返回指定目标控件的获焦状态属性的On对象。 | 379 380**示例：** 381 382```ts 383import { On, ON } from '@ohos.UiTest'; 384let on:On = ON.focused(true); // 使用静态构造器ON创建On对象，指定目标控件的获焦状态属性。 385``` 386 387### selected<sup>9+</sup> 388 389selected(b?: boolean): On 390 391指定目标控件的被选中状态属性，返回On对象自身。 392 393**系统能力**：SystemCapability.Test.UiTest 394 395**参数：** 396 397| 参数名 | 类型 | 必填 | 说明 | 398| ------ | ------- | ---- | ------------------------------------------------------------ | 399| b | boolean | 否 | 指定控件被选中状态，true：被选中，false：未被选中。默认为true。 | 400 401**返回值：** 402 403| 类型 | 说明 | 404| ---------- | ------------------------------------------ | 405| [On](#on9) | 返回指定目标控件的被选中状态属性的On对象。 | 406 407**示例：** 408 409```ts 410import { On, ON } from '@ohos.UiTest'; 411let on:On = ON.selected(true); // 使用静态构造器ON创建On对象，指定目标控件的被选中状态属性。 412``` 413 414### checked<sup>9+</sup> 415 416checked(b?: boolean): On 417 418指定目标控件的被勾选状态属性，返回On对象自身。 419 420**系统能力**：SystemCapability.Test.UiTest 421 422**参数：** 423 424| 参数名 | 类型 | 必填 | 说明 | 425| ------ | ------- | ---- | ------------------------------------------------------------ | 426| b | boolean | 否 | 指定控件被勾选状态，true：被勾选，false：未被勾选。默认为false。 | 427 428**返回值：** 429 430| 类型 | 说明 | 431| ---------- | ------------------------------------------ | 432| [On](#on9) | 返回指定目标控件的被勾选状态属性的On对象。 | 433 434**示例：** 435 436```ts 437import { On, ON } from '@ohos.UiTest'; 438let on:On = ON.checked(true); // 使用静态构造器ON创建On对象，指定目标控件的被勾选状态属性 439``` 440 441### checkable<sup>9+</sup> 442 443checkable(b?: boolean): On 444 445指定目标控件能否被勾选状态属性，返回On对象自身。 446 447**系统能力**：SystemCapability.Test.UiTest 448 449**参数：** 450 451| 参数名 | 类型 | 必填 | 说明 | 452| ------ | ------- | ---- | ------------------------------------------------------------ | 453| b | boolean | 否 | 指定控件能否被勾选状态，true：能被勾选，false：不能被勾选。默认为false。 | 454 455**返回值：** 456 457| 类型 | 说明 | 458| ---------- | -------------------------------------------- | 459| [On](#on9) | 返回指定目标控件能否被勾选状态属性的On对象。 | 460 461**示例：** 462 463```ts 464import { On, ON } from '@ohos.UiTest'; 465let on:On = ON.checkable(true); // 使用静态构造器ON创建On对象，指定目标控件的能否被勾选状态属性。 466``` 467 468### isBefore<sup>9+</sup> 469 470isBefore(on: On): On 471 472指定目标控件位于给出的特征属性控件之前，返回On对象自身。 473 474**系统能力**：SystemCapability.Test.UiTest 475 476**参数：** 477 478| 参数名 | 类型 | 必填 | 说明 | 479| ------ | ---------- | ---- | -------------------- | 480| on | [On](#on9) | 是 | 特征控件的属性要求。 | 481 482**返回值：** 483 484| 类型 | 说明 | 485| ---------- | ---------------------------------------------------- | 486| [On](#on9) | 返回指定目标控件位于给出的特征属性控件之前的On对象。 | 487 488**示例：** 489 490```ts 491import { On, ON } from '@ohos.UiTest'; 492 493// 使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之前。 494let on:On = ON.type('Button').isBefore(ON.text('123')); // 查找text为123之前的第一个Button组件 495``` 496 497### isAfter<sup>9+</sup> 498 499isAfter(on: On): On 500 501指定目标控件位于给出的特征属性控件之后，返回On对象自身。 502 503**系统能力**：SystemCapability.Test.UiTest 504 505**参数：** 506 507| 参数名 | 类型 | 必填 | 说明 | 508| ------ | ---------- | ---- | -------------------- | 509| on | [On](#on9) | 是 | 特征控件的属性要求。 | 510 511**返回值：** 512 513| 类型 | 说明 | 514| ---------- | ---------------------------------------------------- | 515| [On](#on9) | 返回指定目标控件位于给出的特征属性控件之后的On对象。 | 516 517**示例：** 518 519```ts 520import { On, ON } from '@ohos.UiTest'; 521 522// 使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之后。 523let on:On = ON.type('Text').isAfter(ON.text('123')) // 查找 text为123之后的第一个Text组件 524``` 525 526### within<sup>10+</sup> 527 528within(on: On): On 529 530指定目标控件位于给出的特征属性控件之内，返回On对象自身。 531 532**系统能力**：SystemCapability.Test.UiTest 533 534**参数：** 535 536| 参数名 | 类型 | 必填 | 说明 | 537| ------ | ---------- | ---- | -------------------- | 538| on | [On](#on9) | 是 | 特征控件的属性要求。 | 539 540**返回值：** 541 542| 类型 | 说明 | 543| ---------- | -------------------------------------------------- | 544| [On](#on9) | 返回指定目标控件位于给出的特征属性控件内的On对象。 | 545 546**示例：** 547 548```ts 549import { On, ON } from '@ohos.UiTest'; 550// 使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之内。 551let on:On = ON.text('java').within(ON.type('Scroll')); // 查找Scroller里面的text为java的子组件 552``` 553 554### inWindow<sup>10+</sup> 555 556inWindow(bundleName: string): On; 557 558指定目标控件位于给出的应用窗口内，返回On对象自身。 559 560**系统能力**：SystemCapability.Test.UiTest 561 562**参数：** 563 564| 参数名 | 类型 | 必填 | 说明 | 565| ---------- | ------ | ---- | ---------------- | 566| bundleName | string | 是 | 应用窗口的包名。 | 567 568**返回值：** 569 570| 类型 | 说明 | 571| ---------- | ---------------------------------------------- | 572| [On](#on9) | 返回指定目标控件位于给出的应用窗口内的On对象。 | 573 574**示例：** 575 576```ts 577import { On, ON } from '@ohos.UiTest'; 578let on:On = ON.inWindow('com.uitestScene.acts'); // 使用静态构造器ON创建On对象，指定目标控件位于给出的应用窗口内。 579``` 580 581### description<sup>11+</sup> 582 583description(val: string, pattern?: MatchPattern): On 584 585指定目标控件的描述属性，支持多种匹配模式，返回On对象自身。 586 587**系统能力**：SystemCapability.Test.UiTest 588 589**参数：** 590 591| 参数名 | 类型 | 必填 | 说明 | 592| ------- | ----------------------------- | ---- | --------------------------------------------------- | 593| val | string | 是 | 控件的描述属性。 | 594| pattern | [MatchPattern](#matchpattern) | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 | 595 596**返回值：** 597 598| 类型 | 说明 | 599| ---------- | ----------------------------------------- | 600| [On](#on9) | 返回指定目标控件description属性的On对象。 | 601 602**示例：** 603 604```ts 605import { On, ON } from '@ohos.UiTest'; 606let on:On = ON.description('123'); // 使用静态构造器ON创建On对象，指定目标控件的description属性。 607``` 608 609## Component<sup>9+</sup> 610 611UiTest框架在API9中，Component类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。 612该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。 613 614### click<sup>9+</sup> 615 616click(): Promise\<void> 617 618控件对象进行点击操作。 619 620**系统能力**：SystemCapability.Test.UiTest 621 622**错误码：** 623 624以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 625 626| 错误码ID | 错误信息 | 627| -------- | ---------------------------------------- | 628| 17000002 | if the async function was not called with await. | 629| 17000004 | if the component is invisible or destroyed. | 630 631**示例：** 632 633```ts 634import { Driver, ON, Component } from '@ohos.UiTest'; 635async function demo() { 636 let driver:Driver = Driver.create(); 637 let button: Component = await driver.findComponent(ON.type('Button')); 638 await button.click(); 639} 640``` 641 642### doubleClick<sup>9+</sup> 643 644doubleClick(): Promise\<void> 645 646控件对象进行双击操作。 647 648**系统能力**：SystemCapability.Test.UiTest 649 650**错误码：** 651 652以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 653 654| 错误码ID | 错误信息 | 655| -------- | ---------------------------------------- | 656| 17000002 | if the async function was not called with await. | 657| 17000004 | if the component is invisible or destroyed. | 658 659**示例：** 660 661```ts 662import {Component, Driver, ON } from '@ohos.UiTest'; 663async function demo() { 664 let driver: Driver = Driver.create(); 665 let button: Component = await driver.findComponent(ON.type('Button')); 666 await button.doubleClick(); 667} 668``` 669 670### longClick<sup>9+</sup> 671 672longClick(): Promise\<void> 673 674控件对象进行长按操作。 675 676**系统能力**：SystemCapability.Test.UiTest 677 678**错误码：** 679 680以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 681 682| 错误码ID | 错误信息 | 683| -------- | ---------------------------------------- | 684| 17000002 | if the async function was not called with await. | 685| 17000004 | if the component is invisible or destroyed. | 686 687**示例：** 688 689```ts 690import { Component, Driver, ON } from '@ohos.UiTest'; 691async function demo() { 692 let driver: Driver = Driver.create(); 693 let button: Component = await driver.findComponent(ON.type('Button')); 694 await button.longClick(); 695} 696``` 697 698### getId<sup>9+</sup> 699 700getId(): Promise\<string> 701 702获取控件对象的id值。 703 704**系统能力**：SystemCapability.Test.UiTest 705 706**返回值：** 707 708| 类型 | 说明 | 709| ---------------- | ------------------------------- | 710| Promise\<string> | 以Promise形式返回的控件的id值。 | 711 712**错误码：** 713 714以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 715 716| 错误码ID | 错误信息 | 717| -------- | ---------------------------------------- | 718| 17000002 | if the async function was not called with await. | 719| 17000004 | if the component is invisible or destroyed. | 720 721**示例：** 722 723```ts 724import { Component, Driver, ON } from '@ohos.UiTest'; 725async function demo() { 726 let driver: Driver = Driver.create(); 727 let button: Component = await driver.findComponent(ON.type('Button')); 728 let id = await button.getId(); 729} 730``` 731 732### getText<sup>9+</sup> 733 734getText(): Promise\<string> 735 736获取控件对象的文本信息。 737 738**系统能力**：SystemCapability.Test.UiTest 739 740**返回值：** 741 742| 类型 | 说明 | 743| ---------------- | --------------------------------- | 744| Promise\<string> | 以Promise形式返回控件的文本信息。 | 745 746**错误码：** 747 748以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 749 750| 错误码ID | 错误信息 | 751| -------- | ---------------------------------------- | 752| 17000002 | if the async function was not called with await. | 753| 17000004 | if the component is invisible or destroyed. | 754 755**示例：** 756 757```ts 758import { Component, Driver, ON } from '@ohos.UiTest'; 759async function demo() { 760 let driver: Driver = Driver.create(); 761 let button: Component = await driver.findComponent(ON.type('Button')); 762 let text = await button.getText(); 763} 764``` 765 766### getType<sup>9+</sup> 767 768getType(): Promise\<string> 769 770获取控件对象的控件类型。 771 772**系统能力**：SystemCapability.Test.UiTest 773 774**返回值：** 775 776| 类型 | 说明 | 777| ---------------- | ----------------------------- | 778| Promise\<string> | 以Promise形式返回控件的类型。 | 779 780**错误码：** 781 782以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 783 784| 错误码ID | 错误信息 | 785| -------- | ---------------------------------------- | 786| 17000002 | if the async function was not called with await. | 787| 17000004 | if the component is invisible or destroyed. | 788 789**示例：** 790 791```ts 792import { Component, Driver, ON } from '@ohos.UiTest'; 793async function demo() { 794 let driver: Driver = Driver.create(); 795 let button: Component = await driver.findComponent(ON.type('Button')); 796 let type = await button.getType(); 797} 798``` 799 800### getBounds<sup>9+</sup> 801 802getBounds(): Promise\<Rect> 803 804获取控件对象的边框信息。 805 806**系统能力**：SystemCapability.Test.UiTest 807 808**返回值：** 809 810| 类型 | 说明 | 811| ------------------------ | ------------------------------------- | 812| Promise\<[Rect](#rect9)> | 以Promise形式返回控件对象的边框信息。 | 813 814**错误码：** 815 816以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 817 818| 错误码ID | 错误信息 | 819| -------- | ---------------------------------------- | 820| 17000002 | if the async function was not called with await. | 821| 17000004 | if the component is invisible or destroyed. | 822 823**示例：** 824 825```ts 826import { Component, Driver, ON } from '@ohos.UiTest'; 827async function demo() { 828 let driver: Driver = Driver.create(); 829 let button: Component = await driver.findComponent(ON.type('Button')); 830 let rect = await button.getBounds(); 831} 832``` 833 834### getBoundsCenter<sup>9+</sup> 835 836getBoundsCenter(): Promise\<Point> 837 838获取控件对象所占区域的中心点信息。 839 840**系统能力**：SystemCapability.Test.UiTest 841 842**返回值：** 843 844| 类型 | 说明 | 845| -------------------------- | ----------------------------------------------- | 846| Promise\<[Point](#point9)> | 以Promise形式返回控件对象所占区域的中心点信息。 | 847 848**错误码：** 849 850以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 851 852| 错误码ID | 错误信息 | 853| -------- | ---------------------------------------- | 854| 17000002 | if the async function was not called with await. | 855| 17000004 | if the component is invisible or destroyed. | 856 857**示例：** 858 859```ts 860import { Component, Driver, ON } from '@ohos.UiTest'; 861async function demo() { 862 let driver: Driver = Driver.create(); 863 let button: Component = await driver.findComponent(ON.type('Button')); 864 let point = await button.getBoundsCenter(); 865} 866``` 867 868### isClickable<sup>9+</sup> 869 870isClickable(): Promise\<boolean> 871 872获取控件对象可点击属性。 873 874**系统能力**：SystemCapability.Test.UiTest 875 876**返回值：** 877 878| 类型 | 说明 | 879| ----------------- | ------------------------------------------------------------ | 880| Promise\<boolean> | 以Promise形式返回控件对象是否可点击，true：可点击，false：不可点击。 | 881 882**错误码：** 883 884以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 885 886| 错误码ID | 错误信息 | 887| -------- | ---------------------------------------- | 888| 17000002 | if the async function was not called with await. | 889| 17000004 | if the component is invisible or destroyed. | 890 891**示例：** 892 893```ts 894import { Component, Driver, ON } from '@ohos.UiTest'; 895async function demo() { 896 let driver: Driver = Driver.create(); 897 let button: Component = await driver.findComponent(ON.type('Button')); 898 if(await button.isClickable()) { 899 console.info('This button can be Clicked'); 900 } else { 901 console.info('This button can not be Clicked'); 902 } 903} 904``` 905 906### isLongClickable<sup>9+</sup> 907 908isLongClickable(): Promise\<boolean> 909 910获取控件对象可长按点击属性。 911 912**系统能力**：SystemCapability.Test.UiTest 913 914**返回值：** 915 916| 类型 | 说明 | 917| ----------------- |--------------------------------------------------| 918| Promise\<boolean> | 以Promise形式返回控件对象是否可长按点击，true：可长按点击，false：不可长按点击。 | 919 920**错误码：** 921 922以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 923 924| 错误码ID | 错误信息 | 925| -------- | ---------------------------------------- | 926| 17000002 | if the async function was not called with await. | 927| 17000004 | if the component is invisible or destroyed. | 928 929**示例：** 930 931```ts 932import { Component, Driver, ON } from '@ohos.UiTest'; 933async function demo() { 934 let driver: Driver = Driver.create(); 935 let button: Component = await driver.findComponent(ON.type('Button')); 936 if(await button.isLongClickable()) { 937 console.info('This button can longClick'); 938 } else { 939 console.info('This button can not longClick'); 940 } 941} 942``` 943 944### isChecked<sup>9+</sup> 945 946isChecked(): Promise\<boolean> 947 948获取控件对象被勾选状态。 949 950**系统能力**：SystemCapability.Test.UiTest 951 952**返回值：** 953 954| 类型 | 说明 | 955| ----------------- | ------------------------------------------------------------ | 956| Promise\<boolean> | 以Promise形式返回控件对象被勾选状态，true：被勾选，false：未被勾选。 | 957 958**错误码：** 959 960以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 961 962| 错误码ID | 错误信息 | 963| -------- | ---------------------------------------- | 964| 17000002 | if the async function was not called with await. | 965| 17000004 | if the component is invisible or destroyed. | 966 967**示例：** 968 969```ts 970import { Component, Driver, ON } from '@ohos.UiTest'; 971async function demo() { 972 let driver: Driver = Driver.create(); 973 let checkBox: Component = await driver.findComponent(ON.type('Checkbox')); 974 if(await checkBox.isChecked()) { 975 console.info('This checkBox is checked'); 976 } else { 977 console.info('This checkBox is not checked'); 978 } 979} 980``` 981 982### isCheckable<sup>9+</sup> 983 984isCheckable(): Promise\<boolean> 985 986获取控件对象能否被勾选属性。 987 988**系统能力**：SystemCapability.Test.UiTest 989 990**返回值：** 991 992| 类型 | 说明 | 993| ----------------- | ------------------------------------------------------------ | 994| Promise\<boolean> | 以Promise形式返回控件对象能否可被勾选属性，true：可被勾选，false：不可被勾选。 | 995 996**错误码：** 997 998以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 999 1000| 错误码ID | 错误信息 | 1001| -------- | ---------------------------------------- | 1002| 17000002 | if the async function was not called with await. | 1003| 17000004 | if the component is invisible or destroyed. | 1004 1005**示例：** 1006 1007```ts 1008import { Component, Driver, ON } from '@ohos.UiTest'; 1009async function demo() { 1010 let driver: Driver = Driver.create(); 1011 let checkBox: Component = await driver.findComponent(ON.type('Checkbox')); 1012 if(await checkBox.isCheckable()) { 1013 console.info('This checkBox is checkable'); 1014 } else { 1015 console.info('This checkBox is not checkable'); 1016 } 1017} 1018``` 1019 1020### isScrollable<sup>9+</sup> 1021 1022isScrollable(): Promise\<boolean> 1023 1024获取控件对象可滑动属性。 1025 1026**系统能力**：SystemCapability.Test.UiTest 1027 1028**返回值：** 1029 1030| 类型 | 说明 | 1031| ----------------- | ------------------------------------------------------------ | 1032| Promise\<boolean> | 以Promise形式返回控件对象是否可滑动，true：可滑动，false：不可滑动。 | 1033 1034**错误码：** 1035 1036以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1037 1038| 错误码ID | 错误信息 | 1039| -------- | ---------------------------------------- | 1040| 17000002 | if the async function was not called with await. | 1041| 17000004 | if the component is invisible or destroyed. | 1042 1043**示例：** 1044 1045```ts 1046import { Component, Driver, ON } from '@ohos.UiTest'; 1047async function demo() { 1048 let driver: Driver = Driver.create(); 1049 let scrollBar: Component = await driver.findComponent(ON.scrollable(true)); 1050 if(await scrollBar.isScrollable()) { 1051 console.info('This scrollBar can be operated'); 1052 } else { 1053 console.info('This scrollBar can not be operated'); 1054 } 1055} 1056``` 1057 1058 1059### isEnabled<sup>9+</sup> 1060 1061isEnabled(): Promise\<boolean> 1062 1063获取控件使能状态。 1064 1065**系统能力**：SystemCapability.Test.UiTest 1066 1067**返回值：** 1068 1069| 类型 | 说明 | 1070| ----------------- | ---------------------------------------------------------- | 1071| Promise\<boolean> | 以Promise形式返回控件使能状态，true：使能，false：未使能。 | 1072 1073**错误码：** 1074 1075以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1076 1077| 错误码ID | 错误信息 | 1078| -------- | ---------------------------------------- | 1079| 17000002 | if the async function was not called with await. | 1080| 17000004 | if the component is invisible or destroyed. | 1081 1082**示例：** 1083 1084```ts 1085import { Component, Driver, ON } from '@ohos.UiTest'; 1086async function demo() { 1087 let driver: Driver = Driver.create(); 1088 let button: Component = await driver.findComponent(ON.type('Button')); 1089 if(await button.isEnabled()) { 1090 console.info('This button can be operated'); 1091 } else { 1092 console.info('This button can not be operated'); 1093 } 1094} 1095``` 1096 1097### isFocused<sup>9+</sup> 1098 1099isFocused(): Promise\<boolean> 1100 1101判断控件对象获焦状态。 1102 1103**系统能力**：SystemCapability.Test.UiTest 1104 1105**返回值：** 1106 1107| 类型 | 说明 | 1108| ----------------- | ------------------------------------------------------------ | 1109| Promise\<boolean> | 以Promise形式返回控件对象获焦状态，true：获焦，false：未获焦。 | 1110 1111**错误码：** 1112 1113以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1114 1115| 错误码ID | 错误信息 | 1116| -------- | ---------------------------------------- | 1117| 17000002 | if the async function was not called with await. | 1118| 17000004 | if the component is invisible or destroyed. | 1119 1120**示例：** 1121 1122```ts 1123import { Component, Driver, ON } from '@ohos.UiTest'; 1124async function demo() { 1125 let driver: Driver = Driver.create(); 1126 let button: Component = await driver.findComponent(ON.type('Button')); 1127 if(await button.isFocused()) { 1128 console.info('This button is focused'); 1129 } else { 1130 console.info('This button is not focused'); 1131 } 1132} 1133``` 1134 1135### isSelected<sup>9+</sup> 1136 1137isSelected(): Promise\<boolean> 1138 1139获取控件对象被选中状态。 1140 1141**系统能力**：SystemCapability.Test.UiTest 1142 1143**返回值：** 1144 1145| 类型 | 说明 | 1146| ----------------- | --------------------------------------------------- | 1147| Promise\<boolean> | 以Promise形式返回控件对象被选中状态，true：被选中，false：未被选中。 | 1148 1149**错误码：** 1150 1151以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1152 1153| 错误码ID | 错误信息 | 1154| -------- | ---------------------------------------- | 1155| 17000002 | if the async function was not called with await. | 1156| 17000004 | if the component is invisible or destroyed. | 1157 1158**示例：** 1159 1160```ts 1161import { Component, Driver, ON } from '@ohos.UiTest'; 1162async function demo() { 1163 let driver: Driver = Driver.create(); 1164 let button: Component = await driver.findComponent(ON.type('Button')); 1165 if(await button.isSelected()) { 1166 console.info('This button is selected'); 1167 } else { 1168 console.info('This button is not selected'); 1169 } 1170} 1171``` 1172 1173### inputText<sup>9+</sup> 1174 1175inputText(text: string): Promise\<void> 1176 1177向控件中输入文本(适用于文本框控件)。 1178 1179**系统能力**：SystemCapability.Test.UiTest 1180 1181**参数：** 1182 1183| 参数名 | 类型 | 必填 | 说明 | 1184| ------ | ------ | ---- | ---------------------------------------- | 1185| text | string | 是 | 输入的文本信息，当前支持英文和特殊字符。 | 1186 1187**错误码：** 1188 1189以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1190 1191| 错误码ID | 错误信息 | 1192| -------- | ---------------------------------------- | 1193| 17000002 | if the async function was not called with await. | 1194| 17000004 | if the component is invisible or destroyed. | 1195 1196**示例：** 1197 1198```ts 1199import { Component, Driver, ON } from '@ohos.UiTest'; 1200async function demo() { 1201 let driver: Driver = Driver.create(); 1202 let text: Component = await driver.findComponent(ON.text('hello world')); 1203 await text.inputText('123'); 1204} 1205``` 1206 1207### clearText<sup>9+</sup> 1208 1209clearText(): Promise\<void> 1210 1211清除控件的文本信息(适用于文本框控件)。 1212 1213**系统能力**：SystemCapability.Test.UiTest 1214 1215**错误码：** 1216以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1217 1218| 错误码ID | 错误信息 | 1219| -------- | ---------------------------------------- | 1220| 17000002 | if the async function was not called with await. | 1221| 17000004 | if the component is invisible or destroyed. | 1222 1223**示例：** 1224 1225```ts 1226import { Component, Driver, ON } from '@ohos.UiTest'; 1227async function demo() { 1228 let driver: Driver = Driver.create(); 1229 let text: Component = await driver.findComponent(ON.text('hello world')); 1230 await text.clearText(); 1231} 1232``` 1233 1234### scrollSearch<sup>9+</sup> 1235 1236scrollSearch(on: On): Promise\<Component> 1237 1238在控件上滑动查找目标控件(适用支持滑动的控件)。 1239 1240**系统能力**：SystemCapability.Test.UiTest 1241 1242**参数：** 1243 1244| 参数名 | 类型 | 必填 | 说明 | 1245| ------ | ---------- | ---- | -------------------- | 1246| on | [On](#on9) | 是 | 目标控件的属性要求。 | 1247 1248**返回值：** 1249 1250| 类型 | 说明 | 1251| ---------------------------------- | ------------------------------------- | 1252| Promise\<[Component](#component9)> | 以Promise形式返回找到的目标控件对象。 | 1253 1254**错误码：** 1255 1256以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1257 1258| 错误码ID | 错误信息 | 1259| -------- | ---------------------------------------- | 1260| 17000002 | if the async function was not called with await. | 1261| 17000004 | if the component is invisible or destroyed. | 1262 1263**示例：** 1264 1265```ts 1266import { Component, Driver, ON } from '@ohos.UiTest'; 1267async function demo() { 1268 let driver: Driver = Driver.create(); 1269 let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); 1270 let button = await scrollBar.scrollSearch(ON.text('next page')); 1271} 1272``` 1273 1274### scrollToTop<sup>9+</sup> 1275 1276scrollToTop(speed?: number): Promise\<void> 1277 1278在控件上滑动到顶部(适用支持滑动的控件)。 1279 1280**系统能力**：SystemCapability.Test.UiTest 1281 1282**参数：** 1283 1284| 参数名 | 类型 | 必填 | 说明 | 1285| ------ | ------ | ---- | ------------------------------------------------------------ | 1286| speed | number | 否 | 滑动速率，范围：200-40000，不在范围内设为默认值为600，单位：像素点/秒。 | 1287 1288**错误码：** 1289 1290以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1291 1292| 错误码ID | 错误信息 | 1293| -------- | ---------------------------------------- | 1294| 17000002 | if the async function was not called with await. | 1295| 17000004 | if the component is invisible or destroyed. | 1296 1297**示例：** 1298 1299```ts 1300import { Component, Driver, ON } from '@ohos.UiTest'; 1301async function demo() { 1302 let driver: Driver = Driver.create(); 1303 let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); 1304 await scrollBar.scrollToTop(); 1305} 1306``` 1307 1308### scrollToBottom<sup>9+</sup> 1309 1310scrollToBottom(speed?: number): Promise\<void> 1311 1312在控件上滑动到底部(适用支持滑动的控件)。 1313 1314**系统能力**：SystemCapability.Test.UiTest 1315 1316**参数：** 1317 1318| 参数名 | 类型 | 必填 | 说明 | 1319| ------ | ------ | ---- | ------------------------------------------------------------ | 1320| speed | number | 否 | 滑动速率，范围：200-40000，不在范围内设为默认值为600，单位：像素点/秒。 | 1321 1322**错误码：** 1323 1324以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1325 1326| 错误码ID | 错误信息 | 1327| -------- | ---------------------------------------- | 1328| 17000002 | if the async function was not called with await. | 1329| 17000004 | if the component is invisible or destroyed. | 1330 1331**示例：** 1332 1333```ts 1334import { Component, Driver, ON } from '@ohos.UiTest'; 1335async function demo() { 1336 let driver: Driver = Driver.create(); 1337 let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); 1338 await scrollBar.scrollToBottom(); 1339} 1340``` 1341 1342### dragTo<sup>9+</sup> 1343 1344dragTo(target: Component): Promise\<void> 1345 1346将控件拖拽至目标控件处。 1347 1348**系统能力**：SystemCapability.Test.UiTest 1349 1350**参数：** 1351 1352| 参数名 | 类型 | 必填 | 说明 | 1353| ------ | ------------------------ | ---- | ---------- | 1354| target | [Component](#component9) | 是 | 目标控件。 | 1355 1356**错误码：** 1357 1358以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1359 1360| 错误码ID | 错误信息 | 1361| -------- | ---------------------------------------- | 1362| 17000002 | if the async function was not called with await. | 1363| 17000004 | if the component is invisible or destroyed. | 1364 1365**示例：** 1366 1367```ts 1368import { Component, Driver, ON } from '@ohos.UiTest'; 1369async function demo() { 1370 let driver: Driver = Driver.create(); 1371 let button: Component = await driver.findComponent(ON.type('Button')); 1372 let text: Component = await driver.findComponent(ON.text('hello world')); 1373 await button.dragTo(text); 1374} 1375``` 1376 1377### pinchOut<sup>9+</sup> 1378 1379pinchOut(scale: number): Promise\<void> 1380 1381将控件按指定的比例进行捏合放大。 1382 1383**系统能力**：SystemCapability.Test.UiTest 1384 1385**参数：** 1386 1387| 参数名 | 类型 | 必填 | 说明 | 1388| ------ | ------ | ---- | ---------------- | 1389| scale | number | 是 | 指定放大的比例。 | 1390 1391**错误码：** 1392 1393以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1394 1395| 错误码ID | 错误信息 | 1396| -------- | ---------------------------------------- | 1397| 17000002 | if the async function was not called with await. | 1398| 17000004 | if the component is invisible or destroyed. | 1399 1400**示例：** 1401 1402```ts 1403import { Component, Driver, ON } from '@ohos.UiTest'; 1404async function demo() { 1405 let driver: Driver = Driver.create(); 1406 let image: Component = await driver.findComponent(ON.type('Image')); 1407 await image.pinchOut(1.5); 1408} 1409``` 1410 1411### pinchIn<sup>9+</sup> 1412 1413pinchIn(scale: number): Promise\<void> 1414 1415将控件按指定的比例进行捏合缩小。 1416 1417**系统能力**：SystemCapability.Test.UiTest 1418 1419**参数：** 1420 1421| 参数名 | 类型 | 必填 | 说明 | 1422| ------ | ------ | ---- | ---------------- | 1423| scale | number | 是 | 指定缩小的比例。 | 1424 1425**错误码：** 1426 1427以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1428 1429| 错误码ID | 错误信息 | 1430| -------- | ---------------------------------------- | 1431| 17000002 | if the async function was not called with await. | 1432| 17000004 | if the component is invisible or destroyed. | 1433 1434**示例：** 1435 1436```ts 1437import { Component, Driver, ON } from '@ohos.UiTest'; 1438async function demo() { 1439 let driver: Driver = Driver.create(); 1440 let image: Component = await driver.findComponent(ON.type('Image')); 1441 await image.pinchIn(0.5); 1442} 1443``` 1444 1445### getDescription<sup>11+</sup> 1446 1447getDescription(): Promise\<string> 1448 1449获取控件对象的描述信息，使用Promise异步回调。 1450 1451**系统能力**：SystemCapability.Test.UiTest 1452 1453**返回值：** 1454 1455| 类型 | 说明 | 1456| ---------------- | --------------------------------- | 1457| Promise\<string> | Promise对象，返回控件的描述信息。 | 1458 1459**错误码：** 1460 1461以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1462 1463| 错误码ID | 错误信息 | 1464| -------- | ------------------------------------------------ | 1465| 17000002 | if the async function was not called with await. | 1466| 17000004 | if the component is invisible or destroyed. | 1467 1468**示例：** 1469 1470```ts 1471import { Component, Driver, ON } from '@ohos.UiTest'; 1472async function demo() { 1473 let driver: Driver = Driver.create(); 1474 let button: Component = await driver.findComponent(ON.type('Button')); 1475 let description = await button.getDescription(); 1476} 1477``` 1478 1479## Driver<sup>9+</sup> 1480 1481Driver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能力。 1482该类提供的方法除Driver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await方式调用。 1483 1484### create<sup>9+</sup> 1485 1486static create(): Driver 1487 1488静态方法，构造一个Driver对象，并返回该对象。 1489 1490**系统能力**：SystemCapability.Test.UiTest 1491 1492**返回值：** 1493 1494| 类型 | 说明 | 1495| -------- | ---------------------- | 1496| Driver | 返回构造的Driver对象。 | 1497 1498**错误码：** 1499 1500以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1501 1502| 错误码ID | 错误信息 | 1503| -------- | ------------------ | 1504| 17000001 | if the test framework failed to initialize. | 1505 1506**示例：** 1507 1508```ts 1509import { Driver } from '@ohos.UiTest'; 1510async function demo() { 1511 let driver: Driver = Driver.create(); 1512} 1513``` 1514 1515### delayMs<sup>9+</sup> 1516 1517delayMs(duration: number): Promise\<void> 1518 1519Driver对象在给定的时间内延时。 1520 1521**系统能力**：SystemCapability.Test.UiTest 1522 1523**参数：** 1524 1525| 参数名 | 类型 | 必填 | 说明 | 1526| -------- | ------ | ---- | ---------------------- | 1527| duration | number | 是 | 给定的时间，单位：ms。 | 1528 1529**错误码：** 1530 1531以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1532 1533| 错误码ID | 错误信息 | 1534| -------- | ---------------------------------------- | 1535| 17000002 | if the async function was not called with await. | 1536 1537**示例：** 1538 1539```ts 1540import { Driver } from '@ohos.UiTest'; 1541async function demo() { 1542 let driver: Driver = Driver.create(); 1543 await driver.delayMs(1000); 1544} 1545``` 1546 1547### findComponent<sup>9+</sup> 1548 1549findComponent(on: On): Promise\<Component> 1550 1551在Driver对象中，根据给出的目标控件属性要求查找目标控件。 1552 1553**系统能力**：SystemCapability.Test.UiTest 1554 1555**参数：** 1556 1557| 参数名 | 类型 | 必填 | 说明 | 1558| ------ | ---------- | ---- | -------------------- | 1559| on | [On](#on9) | 是 | 目标控件的属性要求。 | 1560 1561**返回值：** 1562 1563| 类型 | 说明 | 1564| ---------------------------------- | --------------------------------- | 1565| Promise\<[Component](#component9)> | 以Promise形式返回找到的控件对象。 | 1566 1567**错误码：** 1568 1569以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1570 1571| 错误码ID | 错误信息 | 1572| -------- | ---------------------------------------- | 1573| 17000002 | if the async function was not called with await. | 1574 1575**示例：** 1576 1577```ts 1578import { Component, Driver, ON } from '@ohos.UiTest'; 1579async function demo() { 1580 let driver: Driver = Driver.create(); 1581 let button: Component = await driver.findComponent(ON.text('next page')); 1582} 1583``` 1584 1585### findComponents<sup>9+</sup> 1586 1587findComponents(on: On): Promise\<Array\<Component>> 1588 1589在Driver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。 1590 1591**系统能力**：SystemCapability.Test.UiTest 1592 1593**参数：** 1594 1595| 参数名 | 类型 | 必填 | 说明 | 1596| ------ | ---------- | ---- | -------------------- | 1597| on | [On](#on9) | 是 | 目标控件的属性要求。 | 1598 1599**返回值：** 1600 1601| 类型 | 说明 | 1602| ------------------------------------------ | --------------------------------------- | 1603| Promise\<Array\<[Component](#component9)>> | 以Promise形式返回找到的控件对象的列表。 | 1604 1605**错误码：** 1606 1607以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1608 1609| 错误码ID | 错误信息 | 1610| -------- | ---------------------------------------- | 1611| 17000002 | if the async function was not called with await. | 1612 1613**示例：** 1614 1615```ts 1616import { Component, Driver, ON } from '@ohos.UiTest'; 1617async function demo() { 1618 let driver: Driver = Driver.create(); 1619 let buttonList: Array<Component> = await driver.findComponents(ON.text('next page')); 1620} 1621``` 1622 1623### findWindow<sup>9+</sup> 1624 1625findWindow(filter: WindowFilter): Promise\<UiWindow> 1626 1627通过指定窗口的属性来查找目标窗口。 1628 1629**系统能力**：SystemCapability.Test.UiTest 1630 1631**参数：** 1632 1633| 参数名 | 类型 | 必填 | 说明 | 1634| ------ | ------------------------------ | ---- | ---------------- | 1635| filter | [WindowFilter](#windowfilter9) | 是 | 目标窗口的属性。 | 1636 1637**返回值：** 1638 1639| 类型 | 说明 | 1640| -------------------------------- | ------------------------------------- | 1641| Promise\<[UiWindow](#uiwindow9)> | 以Promise形式返回找到的目标窗口对象。 | 1642 1643**错误码：** 1644 1645以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1646 1647| 错误码ID | 错误信息 | 1648| -------- | ---------------------------------------- | 1649| 17000002 | if the async function was not called with await. | 1650 1651**示例：** 1652 1653```ts 1654import { Driver, UiWindow } from '@ohos.UiTest'; 1655async function demo() { 1656 let driver: Driver = Driver.create(); 1657 let window: UiWindow = await driver.findWindow({actived: true}); 1658} 1659``` 1660 1661### waitForComponent<sup>9+</sup> 1662 1663waitForComponent(on: On, time: number): Promise\<Component> 1664 1665在Driver对象中，在用户给定的时间内，持续查找满足控件属性要求的目标控件。 1666 1667**系统能力**：SystemCapability.Test.UiTest 1668 1669**参数：** 1670 1671| 参数名 | 类型 | 必填 | 说明 | 1672| ------ | ---------- | ---- | -------------------------------- | 1673| On | [On](#on9) | 是 | 目标控件的属性要求。 | 1674| time | number | 是 | 查找目标控件的持续时间。单位ms。 | 1675 1676**返回值：** 1677 1678| 类型 | 说明 | 1679| --------------------------------- | --------------------------------- | 1680| Promise\<[Component](#component9)> | 以Promise形式返回找到的控件对象。 | 1681 1682**错误码：** 1683 1684以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1685 1686| 错误码ID | 错误信息 | 1687| -------- | ---------------------------------------- | 1688| 17000002 | if the async function was not called with await. | 1689 1690**示例：** 1691 1692```ts 1693import { Component, Driver, ON } from '@ohos.UiTest'; 1694async function demo() { 1695 let driver: Driver = Driver.create(); 1696 let button: Component = await driver.waitForComponent(ON.text('next page'),500); 1697} 1698``` 1699 1700### assertComponentExist<sup>9+</sup> 1701 1702assertComponentExist(on: On): Promise\<void> 1703 1704断言API，用于断言当前界面是否存在满足给出的目标属性的控件。 1705 1706**系统能力**：SystemCapability.Test.UiTest 1707 1708**参数：** 1709 1710| 参数名 | 类型 | 必填 | 说明 | 1711| ------ | ---------- | ---- | -------------------- | 1712| on | [On](#on9) | 是 | 目标控件的属性要求。 | 1713 1714**错误码：** 1715 1716以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1717 1718| 错误码ID | 错误信息 | 1719| -------- | ---------------------------------------- | 1720| 17000002 | if the async function was not called with await. | 1721| 17000003 | if the assertion failed. | 1722 1723**示例：** 1724 1725```ts 1726import { Driver, ON } from '@ohos.UiTest'; 1727async function demo() { 1728 let driver: Driver = Driver.create(); 1729 await driver.assertComponentExist(ON.text('next page')); 1730} 1731``` 1732 1733### pressBack<sup>9+</sup> 1734 1735pressBack(): Promise\<void> 1736 1737Driver对象进行点击BACK键的操作。 1738 1739**系统能力**：SystemCapability.Test.UiTest 1740 1741**错误码：** 1742 1743以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1744 1745| 错误码ID | 错误信息 | 1746| -------- | ---------------------------------------- | 1747| 17000002 | if the async function was not called with await. | 1748 1749**示例：** 1750 1751```ts 1752import { Driver } from '@ohos.UiTest'; 1753async function demo() { 1754 let driver: Driver = Driver.create(); 1755 await driver.pressBack(); 1756} 1757``` 1758 1759### triggerKey<sup>9+</sup> 1760 1761triggerKey(keyCode: number): Promise\<void> 1762 1763Driver对象采取如下操作：传入key值实现模拟点击对应按键的效果。 1764 1765**系统能力**：SystemCapability.Test.UiTest 1766 1767**参数：** 1768 1769| 参数名 | 类型 | 必填 | 说明 | 1770| ------- | ------ | ---- | ------------- | 1771| keyCode | number | 是 | 指定的key值。 | 1772 1773**错误码：** 1774 1775以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1776 1777| 错误码ID | 错误信息 | 1778| -------- | ---------------------------------------- | 1779| 17000002 | if the async function was not called with await. | 1780 1781**示例：** 1782 1783```ts 1784import { Driver } from '@ohos.UiTest'; 1785async function demo() { 1786 let driver: Driver = Driver.create(); 1787 await driver.triggerKey(123); 1788} 1789``` 1790 1791### triggerCombineKeys<sup>9+</sup> 1792 1793triggerCombineKeys(key0: number, key1: number, key2?: number): Promise\<void> 1794 1795Driver对象通过给定的key值，找到对应组合键并点击。例如，Key值为(2072, 2019)时，Driver对象找到key值对应的组合键并点击，如ctrl+c。 1796 1797**系统能力**：SystemCapability.Test.UiTest 1798 1799**参数：** 1800 1801| 参数名 | 类型 | 必填 | 说明 | 1802| ------ | ------ | ---- | ------------------------------ | 1803| key0 | number | 是 | 指定的第一个key值。 | 1804| key1 | number | 是 | 指定的第二个key值。 | 1805| key2 | number | 否 | 指定的第三个key值。默认值为0。 | 1806 1807**错误码：** 1808 1809以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1810 1811| 错误码ID | 错误信息 | 1812| -------- | ---------------------------------------- | 1813| 17000002 | if the async function was not called with await. | 1814 1815**示例：** 1816 1817```ts 1818import { Driver } from '@ohos.UiTest'; 1819async function demo() { 1820 let driver: Driver = Driver.create(); 1821 await driver.triggerCombineKeys(2072, 2047, 2035); 1822} 1823``` 1824 1825 1826### click<sup>9+</sup> 1827 1828click(x: number, y: number): Promise\<void> 1829 1830Driver对象采取如下操作：在目标坐标点单击。 1831 1832**系统能力**：SystemCapability.Test.UiTest 1833 1834**参数：** 1835 1836| 参数名 | 类型 | 必填 | 说明 | 1837| ------ | ------ | ---- | -------------------------------------- | 1838| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | 1839| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | 1840 1841**错误码：** 1842 1843以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1844 1845| 错误码ID | 错误信息 | 1846| -------- | ---------------------------------------- | 1847| 17000002 | if the async function was not called with await. | 1848 1849**示例：** 1850 1851```ts 1852import { Driver } from '@ohos.UiTest'; 1853async function demo() { 1854 let driver: Driver = Driver.create(); 1855 await driver.click(100,100); 1856} 1857``` 1858 1859### doubleClick<sup>9+</sup> 1860 1861doubleClick(x: number, y: number): Promise\<void> 1862 1863Driver对象采取如下操作：在目标坐标点双击。 1864 1865**系统能力**：SystemCapability.Test.UiTest 1866 1867**参数：** 1868 1869| 参数名 | 类型 | 必填 | 说明 | 1870| ------ | ------ | ---- | -------------------------------------- | 1871| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | 1872| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | 1873 1874**错误码：** 1875 1876以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1877 1878| 错误码ID | 错误信息 | 1879| -------- | ---------------------------------------- | 1880| 17000002 | if the async function was not called with await. | 1881 1882**示例：** 1883 1884```ts 1885import { Driver } from '@ohos.UiTest'; 1886async function demo() { 1887 let driver: Driver = Driver.create(); 1888 await driver.doubleClick(100,100); 1889} 1890``` 1891 1892### longClick<sup>9+</sup> 1893 1894longClick(x: number, y: number): Promise\<void> 1895 1896Driver对象采取如下操作：在目标坐标点长按。 1897 1898**系统能力**：SystemCapability.Test.UiTest 1899 1900**参数：** 1901 1902| 参数名 | 类型 | 必填 | 说明 | 1903| ------ | ------ | ---- | -------------------------------------- | 1904| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | 1905| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | 1906 1907**错误码：** 1908 1909以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1910 1911| 错误码ID | 错误信息 | 1912| -------- | ---------------------------------------- | 1913| 17000002 | if the async function was not called with await. | 1914 1915**示例：** 1916 1917```ts 1918import { Driver } from '@ohos.UiTest'; 1919async function demo() { 1920 let driver: Driver = Driver.create(); 1921 await driver.longClick(100,100); 1922} 1923``` 1924 1925### swipe<sup>9+</sup> 1926 1927swipe(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\<void> 1928 1929Driver对象采取如下操作：从起始坐标点滑向目的坐标点。 1930 1931**系统能力**：SystemCapability.Test.UiTest 1932 1933**参数：** 1934 1935| 参数名 | 类型 | 必填 | 说明 | 1936| ------ | ------ | ---- | ------------------------------------------------------------ | 1937| startx | number | 是 | 以number的形式传入起始点的横坐标信息。 | 1938| starty | number | 是 | 以number的形式传入起始点的纵坐标信息。 | 1939| endx | number | 是 | 以number的形式传入目的点的横坐标信息。 | 1940| endy | number | 是 | 以number的形式传入目的点的纵坐标信息。 | 1941| speed | number | 否 | 滑动速率，范围：200-40000，不在范围内设为默认值为600，单位：像素点/秒。 | 1942 1943**错误码：** 1944 1945以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1946 1947| 错误码ID | 错误信息 | 1948| -------- | ---------------------------------------- | 1949| 17000002 | if the async function was not called with await. | 1950 1951**示例：** 1952 1953```ts 1954import { Driver } from '@ohos.UiTest'; 1955async function demo() { 1956 let driver: Driver = Driver.create(); 1957 await driver.swipe(100,100,200,200,600); 1958} 1959``` 1960 1961### drag<sup>9+</sup> 1962 1963drag(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\<void> 1964 1965Driver对象采取如下操作：从起始坐标点拖拽至目的坐标点。 1966 1967**系统能力**：SystemCapability.Test.UiTest 1968 1969**参数：** 1970 1971| 参数名 | 类型 | 必填 | 说明 | 1972| ------ | ------ | ---- | ------------------------------------------------------------ | 1973| startx | number | 是 | 以number的形式传入起始点的横坐标信息。 | 1974| starty | number | 是 | 以number的形式传入起始点的纵坐标信息。 | 1975| endx | number | 是 | 以number的形式传入目的点的横坐标信息。 | 1976| endy | number | 是 | 以number的形式传入目的点的纵坐标信息。 | 1977| speed | number | 否 | 滑动速率，范围：200-40000，不在范围内设为默认值为600，单位：像素点/秒。 | 1978 1979**错误码：** 1980 1981以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1982 1983| 错误码ID | 错误信息 | 1984| -------- | ---------------------------------------- | 1985| 17000002 | if the async function was not called with await. | 1986 1987**示例：** 1988 1989```ts 1990import { Driver } from '@ohos.UiTest'; 1991async function demo() { 1992 let driver: Driver = Driver.create(); 1993 await driver.drag(100,100,200,200,600); 1994} 1995``` 1996 1997### screenCap<sup>9+</sup> 1998 1999screenCap(savePath: string): Promise\<boolean> 2000 2001Driver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。 2002 2003**系统能力**：SystemCapability.Test.UiTest 2004 2005**参数：** 2006 2007| 参数名 | 类型 | 必填 | 说明 | 2008| -------- | ------ | ---- | -------------- | 2009| savePath | string | 是 | 文件保存路径。 | 2010 2011**返回值：** 2012 2013| 类型 | 说明 | 2014| ----------------- | -------------------------------------- | 2015| Promise\<boolean> | 以Promise形式返回截图操作是否成功完成。成功完成为true。 | 2016 2017**错误码：** 2018 2019以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2020 2021| 错误码ID | 错误信息 | 2022| -------- | ---------------------------------------- | 2023| 17000002 | if the async function was not called with await. | 2024 2025**示例：** 2026 2027```ts 2028import { Driver } from '@ohos.UiTest'; 2029async function demo() { 2030 let driver: Driver = Driver.create(); 2031 await driver.screenCap('/data/storage/el2/base/cache/1.png'); 2032} 2033``` 2034 2035### setDisplayRotation<sup>9+</sup> 2036 2037setDisplayRotation(rotation: DisplayRotation): Promise\<void> 2038 2039将设备的屏幕显示方向设置为指定的显示方向。 2040 2041**系统能力**：SystemCapability.Test.UiTest 2042 2043**参数：** 2044 2045| 参数名 | 类型 | 必填 | 说明 | 2046| -------- | ------------------------------------ | ---- | ---------------- | 2047| rotation | [DisplayRotation](#displayrotation9) | 是 | 设备的显示方向。 | 2048 2049**错误码：** 2050 2051以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2052 2053| 错误码ID | 错误信息 | 2054| -------- | ---------------------------------------- | 2055| 17000002 | if the async function was not called with await. | 2056 2057**示例：** 2058 2059```ts 2060import { Driver, DisplayRotation } from '@ohos.UiTest'; 2061async function demo() { 2062 let driver: Driver = Driver.create(); 2063 await driver.setDisplayRotation(DisplayRotation.ROTATION_180); 2064} 2065``` 2066 2067### getDisplayRotation<sup>9+</sup> 2068 2069getDisplayRotation(): Promise\<DisplayRotation> 2070 2071获取当前设备的屏幕显示方向。 2072 2073**系统能力**：SystemCapability.Test.UiTest 2074 2075**返回值：** 2076 2077| 类型 | 说明 | 2078| ---------------------------------------------- | --------------------------------------- | 2079| Promise\<[DisplayRotation](#displayrotation9)> | 以Promise的形式返回当前设备的显示方向。 | 2080 2081**错误码：** 2082 2083以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2084 2085| 错误码ID | 错误信息 | 2086| -------- | ---------------------------------------- | 2087| 17000002 | if the async function was not called with await. | 2088 2089**示例：** 2090 2091```ts 2092import { DisplayRotation, Driver } from '@ohos.UiTest'; 2093async function demo() { 2094 let driver: Driver = Driver.create(); 2095 let rotation: DisplayRotation = await driver.getDisplayRotation(); 2096} 2097``` 2098 2099### setDisplayRotationEnabled<sup>9+</sup> 2100 2101setDisplayRotationEnabled(enabled: boolean): Promise\<void> 2102 2103启用/禁用设备旋转屏幕的功能。 2104 2105**系统能力**：SystemCapability.Test.UiTest 2106 2107**参数：** 2108 2109| 参数名 | 类型 | 必填 | 说明 | 2110| ------- | ------- | ---- | ------------------------------------------------------- | 2111| enabled | boolean | 是 | 能否旋转屏幕的标识，true：可以旋转，false：不可以旋转。 | 2112 2113**错误码：** 2114 2115以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2116 2117| 错误码ID | 错误信息 | 2118| -------- | ---------------------------------------- | 2119| 17000002 | if the async function was not called with await. | 2120 2121**示例：** 2122 2123```ts 2124import { Driver } from '@ohos.UiTest'; 2125async function demo() { 2126 let driver: Driver = Driver.create(); 2127 await driver.setDisplayRotationEnabled(false); 2128} 2129``` 2130 2131### getDisplaySize<sup>9+</sup> 2132 2133getDisplaySize(): Promise\<Point> 2134 2135获取当前设备的屏幕大小。 2136 2137**系统能力**：SystemCapability.Test.UiTest 2138 2139**返回值：** 2140 2141| 类型 | 说明 | 2142| -------------------------- | --------------------------------------- | 2143| Promise\<[Point](#point9)> | 以Promise的形式返回当前设备的屏幕大小。 | 2144 2145**错误码：** 2146 2147以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2148 2149| 错误码ID | 错误信息 | 2150| -------- | ---------------------------------------- | 2151| 17000002 | if the async function was not called with await. | 2152 2153**示例：** 2154 2155```ts 2156import { Driver, } from '@ohos.UiTest'; 2157 2158async function demo() { 2159 let driver: Driver = Driver.create(); 2160 let size = await driver.getDisplaySize(); 2161} 2162``` 2163 2164### getDisplayDensity<sup>9+</sup> 2165 2166getDisplayDensity(): Promise\<Point> 2167 2168获取当前设备屏幕的分辨率。 2169 2170**系统能力**：SystemCapability.Test.UiTest 2171 2172**返回值：** 2173 2174| 类型 | 说明 | 2175| -------------------------- | ----------------------------------------- | 2176| Promise\<[Point](#point9)> | 以Promise的形式返回当前设备屏幕的分辨率。 | 2177 2178**错误码：** 2179 2180以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2181 2182| 错误码ID | 错误信息 | 2183| -------- | ---------------------------------------- | 2184| 17000002 | if the async function was not called with await. | 2185 2186**示例：** 2187 2188```ts 2189import { Driver } from '@ohos.UiTest'; 2190async function demo() { 2191 let driver: Driver = Driver.create(); 2192 let density = await driver.getDisplayDensity(); 2193} 2194``` 2195 2196### wakeUpDisplay<sup>9+</sup> 2197 2198wakeUpDisplay(): Promise\<void> 2199 2200唤醒当前设备即设备亮屏。 2201 2202**系统能力**：SystemCapability.Test.UiTest 2203 2204**错误码：** 2205 2206以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2207 2208| 错误码ID | 错误信息 | 2209| -------- | ---------------------------------------- | 2210| 17000002 | if the async function was not called with await. | 2211 2212**示例：** 2213 2214```ts 2215import { Driver } from '@ohos.UiTest'; 2216async function demo() { 2217 let driver: Driver = Driver.create(); 2218 await driver.wakeUpDisplay(); 2219} 2220``` 2221 2222### pressHome<sup>9+</sup> 2223 2224pressHome(): Promise\<void> 2225 2226设备返回到桌面。 2227 2228**系统能力**：SystemCapability.Test.UiTest 2229 2230**错误码：** 2231 2232以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2233 2234| 错误码ID | 错误信息 | 2235| -------- | ---------------------------------------- | 2236| 17000002 | if the async function was not called with await. | 2237 2238**示例：** 2239 2240```ts 2241import { Driver } from '@ohos.UiTest'; 2242async function demo() { 2243 let driver: Driver = Driver.create(); 2244 await driver.pressHome(); 2245} 2246``` 2247 2248### waitForIdle<sup>9+</sup> 2249 2250waitForIdle(idleTime: number, timeout: number): Promise\<boolean> 2251 2252判断当前界面的所有控件是否已经空闲。 2253 2254**系统能力**：SystemCapability.Test.UiTest 2255 2256**参数：** 2257 2258| 参数名 | 类型 | 必填 | 说明 | 2259| -------- | ------ | ---- | ------------------------------------------------------------ | 2260| idleTime | number | 是 | 空闲时间的阈值。在这个时间段控件不发生变化，视为该控件空闲，单位：毫秒。 | 2261| timeout | number | 是 | 等待空闲的最大时间，单位：毫秒。 | 2262 2263**返回值：** 2264 2265| 类型 | 说明 | 2266| ----------------- | --------------------------------------------------- | 2267| Promise\<boolean> | 以Promise的形式返回当前界面的所有控件是否已经空闲。 | 2268 2269**错误码：** 2270 2271以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2272 2273| 错误码ID | 错误信息 | 2274| -------- | ---------------------------------------- | 2275| 17000002 | if the async function was not called with await. | 2276 2277**示例：** 2278 2279```ts 2280import { Driver } from '@ohos.UiTest'; 2281async function demo() { 2282 let driver: Driver = Driver.create(); 2283 let idled:boolean = await driver.waitForIdle(4000,5000); 2284} 2285``` 2286 2287### fling<sup>9+</sup> 2288 2289fling(from: Point, to: Point, stepLen: number, speed: number): Promise\<void> 2290 2291模拟手指滑动后脱离屏幕的快速滑动操作。 2292 2293**系统能力**：SystemCapability.Test.UiTest 2294 2295**参数：** 2296 2297| 参数名 | 类型 | 必填 | 说明 | 2298| ------- | ---------------- | ---- | ------------------------------------------------------------ | 2299| from | [Point](#point9) | 是 | 手指接触屏幕的起始点坐标。 | 2300| to | [Point](#point9) | 是 | 手指离开屏幕时的坐标点。 | 2301| stepLen | number | 是 | 间隔距离，单位：像素点。 | 2302| speed | number | 是 | 滑动速率，范围：200-40000，不在范围内设为默认值为600，单位：像素点/秒。 | 2303 2304**错误码：** 2305 2306以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2307 2308| 错误码ID | 错误信息 | 2309| -------- | ---------------------------------------- | 2310| 17000002 | if the async function was not called with await. | 2311 2312**示例：** 2313 2314```ts 2315import { Driver } from '@ohos.UiTest'; 2316async function demo() { 2317 let driver: Driver = Driver.create(); 2318 await driver.fling({x: 500, y: 480},{x: 450, y: 480},5,600); 2319} 2320``` 2321 2322### injectMultiPointerAction<sup>9+</sup> 2323 2324injectMultiPointerAction(pointers: PointerMatrix, speed?: number): Promise\<boolean> 2325 2326向设备注入多指操作。 2327 2328**系统能力**：SystemCapability.Test.UiTest 2329 2330**参数：** 2331 2332| 参数名 | 类型 | 必填 | 说明 | 2333| -------- | -------------------------------- | ---- | ------------------------------------------------------------ | 2334| pointers | [PointerMatrix](#pointermatrix9) | 是 | 滑动轨迹，包括操作手指个数和滑动坐标序列。 | 2335| speed | number | 否 | 滑动速率，范围：200-40000，不在范围内设为默认值为600，单位：像素点/秒。 | 2336 2337**返回值：** 2338 2339| 类型 | 说明 | 2340| ----------------- | ------------------------------------- | 2341| Promise\<boolean> | 以Promise的形式返回操作是否成功完成。 | 2342 2343**错误码：** 2344 2345以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2346 2347| 错误码ID | 错误信息 | 2348| -------- | ---------------------------------------- | 2349| 17000002 | if the async function was not called with await. | 2350 2351**示例：** 2352 2353```ts 2354import { Driver, PointerMatrix } from '@ohos.UiTest'; 2355async function demo() { 2356 let driver: Driver = Driver.create(); 2357 let pointers: PointerMatrix = PointerMatrix.create(2,3); 2358 pointers.setPoint(0,0,{x:230,y:480}); 2359 pointers.setPoint(0,1,{x:250,y:380}); 2360 pointers.setPoint(0,2,{x:270,y:280}); 2361 pointers.setPoint(1,0,{x:230,y:680}); 2362 pointers.setPoint(1,1,{x:240,y:580}); 2363 pointers.setPoint(1,2,{x:250,y:480}); 2364 await driver.injectMultiPointerAction(pointers); 2365} 2366``` 2367 2368### fling<sup>10+</sup> 2369 2370fling(direction: UiDirection, speed: number): Promise\<void>; 2371 2372指定方向和速度，模拟手指滑动后脱离屏幕的快速滑动操作。 2373 2374**系统能力**：SystemCapability.Test.UiTest 2375 2376**参数：** 2377 2378| 参数名 | 类型 | 必填 | 说明 | 2379| --------- | ----------------------------- | ---- | ------------------------------------------------------------ | 2380| direction | [UiDirection](#uidirection10) | 是 | 进行抛滑的方向。 | 2381| speed | number | 是 | 滑动速率，范围：200-40000，不在范围内设为默认值为600，单位：像素点/秒。 | 2382 2383**错误码：** 2384 2385以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2386 2387| 错误码ID | 错误信息 | 2388| -------- | ---------------------------------------- | 2389| 17000002 | if the async function was not called with await. | 2390 2391**示例：** 2392 2393```ts 2394import { Driver, UiDirection } from '@ohos.UiTest'; 2395async function demo() { 2396 let driver: Driver = Driver.create(); 2397 await driver.fling(UiDirection.DOWN, 10000); 2398} 2399``` 2400 2401### screenCapture<sup>10+</sup> 2402 2403screenCapture(savePath: string, rect?: Rect): Promise\<boolean>; 2404 2405捕获当前屏幕的指定区域，并保存为PNG格式的图片至给出的保存路径中。 2406 2407**系统能力**：SystemCapability.Test.UiTest 2408 2409**参数：** 2410 2411| 参数名 | 类型 | 必填 | 说明 | 2412| -------- | -------------- | ---- | ---------------------- | 2413| savePath | string | 是 | 文件保存路径。 | 2414| rect | [Rect](#rect9) | 否 | 截图区域，默认为全屏。 | 2415 2416**返回值：** 2417 2418| 类型 | 说明 | 2419| ----------------- | -------------------------------------- | 2420| Promise\<boolean> | 以Promise形式返回截图操作是否成功完成。成功完成为true。 | 2421 2422**错误码：** 2423 2424以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2425 2426| 错误码ID | 错误信息 | 2427| -------- | ---------------------------------------- | 2428| 17000002 | if the async function was not called with await. | 2429 2430**示例：** 2431 2432```ts 2433import { Driver } from '@ohos.UiTest'; 2434async function demo() { 2435 let driver: Driver = Driver.create(); 2436 await driver.screenCapture('/data/storage/el2/base/cache/1.png', {left: 0, top: 0, right: 100, bottom: 100}); 2437} 2438``` 2439 2440### mouseClick<sup>10+</sup> 2441 2442mouseClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise\<void>; 2443 2444在指定坐标点注入鼠标点击动作，支持同时按下对应键盘组合键。例如，Key值为2072时，按下ctrl并进行鼠标点击动作。 2445 2446**系统能力**：SystemCapability.Test.UiTest 2447 2448**参数：** 2449 2450| 参数名 | 类型 | 必填 | 说明 | 2451| ------ | ----------------------------- | ---- | ------------------------------ | 2452| p | [Point](#point9) | 是 | 鼠标点击的坐标。 | 2453| btnId | [MouseButton](#mousebutton10) | 是 | 按下的鼠标按钮。 | 2454| key1 | number | 否 | 指定的第一个key值。默认值为0。 | 2455| key2 | number | 否 | 指定的第二个key值。默认值为0。 | 2456 2457**错误码：** 2458 2459以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2460 2461| 错误码ID | 错误信息 | 2462| -------- | ---------------------------------------- | 2463| 17000002 | if the async function was not called with await. | 2464 2465**示例：** 2466 2467```ts 2468import { Driver,MouseButton } from '@ohos.UiTest'; 2469async function demo() { 2470 let driver: Driver = Driver.create(); 2471 await driver.mouseClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072); 2472} 2473``` 2474 2475### mouseScroll<sup>10+</sup> 2476 2477mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number): Promise\<void>; 2478 2479在指定坐标点注入鼠标滚轮滑动动作，支持同时按下对应键盘组合键。例如，Key值为2072时，按下ctrl并进行鼠标滚轮滑动动作。 2480 2481**系统能力**：SystemCapability.Test.UiTest 2482 2483**参数：** 2484 2485| 参数名 | 类型 | 必填 | 说明 | 2486| ------ | ---------------- | ---- | ----------------------------------------------------------- | 2487| p | [Point](#point9) | 是 | 鼠标点击的坐标。 | 2488| down | boolean | 是 | 滚轮滑动方向是否向下，true表示向下滑动，false表示向上滚动。 | 2489| d | number | 是 | 鼠标滚轮滚动的格数，每格对应目标点位移120个像素点。 | 2490| key1 | number | 否 | 指定的第一个key值。默认值为0。 | 2491| key2 | number | 否 | 指定的第二个key值。默认值为0。 | 2492 2493**错误码：** 2494 2495以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2496 2497| 错误码ID | 错误信息 | 2498| -------- | ---------------------------------------- | 2499| 17000002 | if the async function was not called with await. | 2500 2501**示例：** 2502 2503```ts 2504import { Driver } from '@ohos.UiTest'; 2505async function demo() { 2506 let driver: Driver = Driver.create(); 2507 await driver.mouseScroll({x:360, y:640}, true, 30, 2072) 2508} 2509``` 2510 2511### mouseMoveTo<sup>10+</sup> 2512 2513mouseMoveTo(p: Point): Promise\<void>; 2514 2515将鼠标光标移到目标点。 2516 2517**系统能力**：SystemCapability.Test.UiTest 2518 2519**参数：** 2520 2521| 参数名 | 类型 | 必填 | 说明 | 2522| ------ | ---------------- | ---- | -------------- | 2523| p | [Point](#point9) | 是 | 目标点的坐标。 | 2524 2525**错误码：** 2526 2527以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2528 2529| 错误码ID | 错误信息 | 2530| -------- | ---------------------------------------- | 2531| 17000002 | if the async function was not called with await. | 2532 2533**示例：** 2534 2535```ts 2536import { Driver } from '@ohos.UiTest'; 2537async function demo() { 2538 let driver: Driver = Driver.create(); 2539 await driver.mouseMoveTo({x:100, y:100}) 2540} 2541``` 2542 2543### createUIEventObserver<sup>10+</sup> 2544 2545createUIEventObserver(): UIEventObserver; 2546 2547创建一个UI事件监听器。 2548 2549**系统能力**：SystemCapability.Test.UiTest 2550 2551**返回值：** 2552 2553| 类型 | 说明 | 2554| ------------------------------------ | ------------------------------------- | 2555|[UIEventObserver](#uieventobserver10) | 返回找到的目标窗口对象。 | 2556 2557**错误码：** 2558 2559以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2560 2561| 错误码ID | 错误信息 | 2562| -------- | ---------------------------------------- | 2563| 17000002 | if the async function was not called with await. | 2564 2565**示例：** 2566 2567```ts 2568import { Driver, UIEventObserver } from '@ohos.UiTest'; 2569async function demo() { 2570 let driver: Driver = Driver.create(); 2571 let observer: UIEventObserver = await driver.createUIEventObserver() 2572} 2573``` 2574 2575### mouseScroll<sup>11+</sup> 2576 2577mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number, speed?: number): Promise\<void> 2578 2579在指定坐标点注入鼠标滚轮滑动动作，支持同时按下对应键盘组合键并且指定滑动速度。 2580 2581**系统能力**：SystemCapability.Test.UiTest 2582 2583**参数：** 2584 2585| 参数名 | 类型 | 必填 | 说明 | 2586| ------ | ---------------- | ---- | ------------------------------------------------------------ | 2587| p | [Point](#point9) | 是 | 鼠标点击的坐标。 | 2588| down | boolean | 是 | 滚轮滑动方向是否向下，true表示向下滑动，false表示向上滚动。 | 2589| d | number | 是 | 鼠标滚轮滚动的格数，每格对应目标点位移120个像素点。 | 2590| key1 | number | 否 | 指定的第一个key值。默认值为0。 | 2591| key2 | number | 否 | 指定的第二个key值。默认值为0。 | 2592| speed | number | 否 | 鼠标滚轮滚动的速度，范围：1-500，不在范围内设为默认值为20，单位：格/秒。 | 2593 2594**错误码：** 2595 2596以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2597 2598| 错误码ID | 错误信息 | 2599| -------- | ------------------------------------------------ | 2600| 17000002 | if the async function was not called with await. | 2601 2602**示例：** 2603 2604```ts 2605import { Driver } from '@ohos.UiTest'; 2606async function demo() { 2607 let driver: Driver = Driver.create(); 2608 await driver.mouseScroll({x:360, y:640}, true, 30, 2072,20) 2609} 2610``` 2611 2612### mouseDoubleClick<sup>11+</sup> 2613 2614mouseDoubleClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise\<void> 2615 2616在指定坐标点注入鼠标双击动作，支持同时按下对应键盘组合键。例如，Key值为2072时，按下ctrl并进行鼠标双击动作。 2617 2618**系统能力**：SystemCapability.Test.UiTest 2619 2620**参数：** 2621 2622| 参数名 | 类型 | 必填 | 说明 | 2623| ------ | ----------------------------- | ---- | ------------------------------ | 2624| p | [Point](#point9) | 是 | 鼠标双击的坐标。 | 2625| btnId | [MouseButton](#mousebutton10) | 是 | 按下的鼠标按钮。 | 2626| key1 | number | 否 | 指定的第一个key值。默认值为0。 | 2627| key2 | number | 否 | 指定的第二个key值。默认值为0。 | 2628 2629**错误码：** 2630 2631以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2632 2633| 错误码ID | 错误信息 | 2634| -------- | ------------------------------------------------ | 2635| 17000002 | if the async function was not called with await. | 2636 2637**示例：** 2638 2639```ts 2640import { Driver,MouseButton } from '@ohos.UiTest'; 2641async function demo() { 2642 let driver: Driver = Driver.create(); 2643 await driver.mouseDoubleClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072); 2644} 2645``` 2646 2647### mouseLongClick<sup>11+</sup> 2648 2649mouseLongClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise\<void> 2650 2651在指定坐标点注入鼠标长按动作，支持同时按下对应键盘组合键。例如，Key值为2072时，按下ctrl并进行鼠标长按动作。 2652 2653**系统能力**：SystemCapability.Test.UiTest 2654 2655**参数：** 2656 2657| 参数名 | 类型 | 必填 | 说明 | 2658| ------ | ----------------------------- | ---- | ------------------------------ | 2659| p | [Point](#point9) | 是 | 鼠标长按的坐标。 | 2660| btnId | [MouseButton](#mousebutton10) | 是 | 按下的鼠标按钮。 | 2661| key1 | number | 否 | 指定的第一个key值。默认值为0。 | 2662| key2 | number | 否 | 指定的第二个key值。默认值为0。 | 2663 2664**错误码：** 2665 2666以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2667 2668| 错误码ID | 错误信息 | 2669| -------- | ------------------------------------------------ | 2670| 17000002 | if the async function was not called with await. | 2671 2672**示例：** 2673 2674```ts 2675import { Driver,MouseButton } from '@ohos.UiTest'; 2676async function demo() { 2677 let driver:Driver = Driver.create(); 2678 await driver.mouseLongClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072); 2679} 2680``` 2681 2682### mouseMoveWithTrack<sup>11+</sup> 2683 2684mouseMoveWithTrack(from: Point, to: Point, speed?: number): Promise\<void> 2685 2686鼠标从起始坐标点滑向终点坐标点。 2687 2688**系统能力**：SystemCapability.Test.UiTest 2689 2690**参数：** 2691 2692| 参数名 | 类型 | 必填 | 说明 | 2693| ------ | ---------------- | ---- | ------------------------------------------------------------ | 2694| from | [Point](#point9) | 是 | 起始点坐标。 | 2695| to | [Point](#point9) | 是 | 终点坐标。 | 2696| speed | number | 否 | 滑动速率，范围：200-40000，不在范围内设为默认值为600，单位：像素点/秒。 | 2697 2698**错误码：** 2699 2700以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2701 2702| 错误码ID | 错误信息 | 2703| -------- | ------------------------------------------------ | 2704| 17000002 | if the async function was not called with await. | 2705 2706**示例：** 2707 2708```ts 2709import { Driver } from '@ohos.UiTest'; 2710async function demo() { 2711 let driver: Driver = Driver.create(); 2712 await driver.mouseMoveWithTrack({x:100, y:100},{x:200, y:200},600); 2713} 2714``` 2715 2716### mouseDrag<sup>11+</sup> 2717 2718mouseDrag(from: Point, to: Point, speed?: number): Promise\<void> 2719 2720鼠标按住鼠标左键从起始坐标点拖拽至终点坐标点。 2721 2722**系统能力**：SystemCapability.Test.UiTest 2723 2724**参数：** 2725 2726| 参数名 | 类型 | 必填 | 说明 | 2727| ------ | ---------------- | ---- | ------------------------------------------------------------ | 2728| from | [Point](#point9) | 是 | 起始点坐标。 | 2729| to | [Point](#point9) | 是 | 终点坐标。 | 2730| speed | number | 否 | 滑动速率，范围：200-40000，不在范围内设为默认值为600，单位：像素点/秒。 | 2731 2732**错误码：** 2733 2734以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2735 2736| 错误码ID | 错误信息 | 2737| -------- | ------------------------------------------------ | 2738| 17000002 | if the async function was not called with await. | 2739 2740**示例：** 2741 2742```ts 2743import { Driver } from '@ohos.UiTest'; 2744async function demo() { 2745 let driver: Driver = Driver.create(); 2746 await driver.mouseDrag({x:100, y:100},{x:200, y:200},600); 2747} 2748``` 2749 2750### inputText<sup>11+</sup> 2751 2752inputText(p: Point, text: string): Promise\<void> 2753 2754在指定坐标点输入文本。 2755 2756**系统能力**：SystemCapability.Test.UiTest 2757 2758**参数：** 2759 2760| 参数名 | 类型 | 必填 | 说明 | 2761| ------ | ---------------- | ---- | ------------------ | 2762| p | [Point](#point9) | 是 | 输入文本的坐标点。 | 2763| text | string | 是 | 输入的文本信息。 | 2764 2765**错误码：** 2766 2767以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2768 2769| 错误码ID | 错误信息 | 2770| -------- | ------------------------------------------------ | 2771| 17000002 | if the async function was not called with await. | 2772 2773**示例：** 2774 2775```ts 2776import { Component, Driver, ON } from '@ohos.UiTest'; 2777async function demo() { 2778 let driver:Driver = Driver.create(); 2779 let text: Component = await driver.findComponent(ON.type('TextInput')); 2780 let point = await text.getBoundsCenter(); 2781 await driver.inputText(point, '123'); 2782} 2783``` 2784 2785## PointerMatrix<sup>9+</sup> 2786 2787存储多指操作中每根手指每一步动作的坐标点及其行为的二维数组。 2788 2789### create<sup>9+</sup> 2790 2791static create(fingers: number, steps: number): PointerMatrix 2792 2793静态方法，构造一个PointerMatrix对象，并返回该对象。 2794 2795**系统能力**：SystemCapability.Test.UiTest 2796 2797**参数：** 2798 2799| 参数名 | 类型 | 必填 | 说明 | 2800| ------- | ------ | ---- | ------------------------------------------ | 2801| fingers | number | 是 | 多指操作中注入的手指数，取值范围：[1,10]。 | 2802| steps | number | 是 | 每根手指操作的步骤数，取值范围：[1,1000]。 | 2803 2804**返回值：** 2805 2806| 类型 | 说明 | 2807| -------------------------------- | ----------------------------- | 2808| [PointerMatrix](#pointermatrix9) | 返回构造的PointerMatrix对象。 | 2809 2810**示例：** 2811 2812```ts 2813import { PointerMatrix } from '@ohos.UiTest'; 2814async function demo() { 2815 let pointerMatrix: PointerMatrix = PointerMatrix.create(2,3); 2816} 2817``` 2818 2819### setPoint<sup>9+</sup> 2820 2821setPoint(finger: number, step: number, point: Point): void 2822 2823设置PointerMatrix对象中指定手指和步骤对应动作的坐标点。 2824 2825**系统能力**：SystemCapability.Test.UiTest 2826 2827**参数：** 2828 2829| 参数名 | 类型 | 必填 | 说明 | 2830| ------ | ---------------- | ---- | ---------------- | 2831| finger | number | 是 | 手指的序号。 | 2832| step | number | 是 | 步骤的序号。 | 2833| point | [Point](#point9) | 是 | 该行为的坐标点。 | 2834 2835**示例：** 2836 2837```ts 2838import { PointerMatrix } from '@ohos.UiTest'; 2839async function demo() { 2840 let pointers: PointerMatrix = PointerMatrix.create(2,3); 2841 pointers.setPoint(0,0,{x:230,y:480}); 2842 pointers.setPoint(0,1,{x:250,y:380}); 2843 pointers.setPoint(0,2,{x:270,y:280}); 2844 pointers.setPoint(1,0,{x:230,y:680}); 2845 pointers.setPoint(1,1,{x:240,y:580}); 2846 pointers.setPoint(1,2,{x:250,y:480}); 2847} 2848``` 2849 2850## UiWindow<sup>9+</sup> 2851 2852UiWindow代表了UI界面上的一个窗口，提供窗口属性获取，窗口拖动、调整窗口大小等能力。 2853该类提供的所有方法都使用Promise方式作为异步方法，需使用await方式调用。 2854 2855### getBundleName<sup>9+</sup> 2856 2857getBundleName(): Promise\<string> 2858 2859获取窗口归属应用的包名信息。 2860 2861**系统能力**：SystemCapability.Test.UiTest 2862 2863**返回值：** 2864 2865| 类型 | 说明 | 2866| ---------------- | ----------------------------------------- | 2867| Promise\<string> | 以Promise形式返回窗口归属应用的包名信息。 | 2868 2869**错误码：** 2870 2871以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2872 2873| 错误码ID | 错误信息 | 2874| -------- | ---------------------------------------- | 2875| 17000002 | if the async function was not called with await. | 2876| 17000004 | if the window is invisible or destroyed. | 2877 2878**示例：** 2879 2880```ts 2881import { Driver, UiWindow } from '@ohos.UiTest'; 2882 2883async function demo() { 2884 let driver: Driver = Driver.create(); 2885 let window: UiWindow = await driver.findWindow({actived: true}); 2886 let name: string = await window.getBundleName(); 2887} 2888``` 2889 2890### getBounds<sup>9+</sup> 2891 2892getBounds(): Promise\<Rect> 2893 2894获取窗口的边框信息。 2895 2896**系统能力**：SystemCapability.Test.UiTest 2897 2898**返回值：** 2899 2900| 类型 | 说明 | 2901| ------------------------ | --------------------------------- | 2902| Promise\<[Rect](#rect9)> | 以Promise形式返回窗口的边框信息。 | 2903 2904**错误码：** 2905 2906以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2907 2908| 错误码ID | 错误信息 | 2909| -------- | ---------------------------------------- | 2910| 17000002 | if the async function was not called with await. | 2911| 17000004 | if the window is invisible or destroyed. | 2912 2913**示例：** 2914 2915```ts 2916import { Driver, UiWindow } from '@ohos.UiTest'; 2917async function demo() { 2918 let driver: Driver = Driver.create(); 2919 let window: UiWindow = await driver.findWindow({actived: true}); 2920 let rect = await window.getBounds(); 2921} 2922``` 2923 2924### getTitle<sup>9+</sup> 2925 2926getTitle(): Promise\<string> 2927 2928获取窗口的标题信息。 2929 2930**系统能力**：SystemCapability.Test.UiTest 2931 2932**返回值：** 2933 2934| 类型 | 说明 | 2935| ---------------- | --------------------------------- | 2936| Promise\<string> | 以Promise形式返回窗口的标题信息。 | 2937 2938**错误码：** 2939 2940以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2941 2942| 错误码ID | 错误信息 | 2943| -------- | ---------------------------------------- | 2944| 17000002 | if the async function was not called with await. | 2945| 17000004 | if the window is invisible or destroyed. | 2946 2947**示例：** 2948 2949```ts 2950import { Driver, UiWindow } from '@ohos.UiTest'; 2951async function demo() { 2952 let driver: Driver = Driver.create(); 2953 let window: UiWindow = await driver.findWindow({actived: true}); 2954 let rect = await window.getTitle(); 2955} 2956``` 2957 2958### getWindowMode<sup>9+</sup> 2959 2960getWindowMode(): Promise\<WindowMode> 2961 2962获取窗口的窗口模式信息。 2963 2964**系统能力**：SystemCapability.Test.UiTest 2965 2966**返回值：** 2967 2968| 类型 | 说明 | 2969| ------------------------------------ | ------------------------------------- | 2970| Promise\<[WindowMode](#windowmode9)> | 以Promise形式返回窗口的窗口模式信息。 | 2971 2972**错误码：** 2973 2974以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2975 2976| 错误码ID | 错误信息 | 2977| -------- | ---------------------------------------- | 2978| 17000002 | if the async function was not called with await. | 2979| 17000004 | if the window is invisible or destroyed. | 2980 2981**示例：** 2982 2983```ts 2984import { Driver, UiWindow } from '@ohos.UiTest'; 2985async function demo() { 2986 let driver: Driver = Driver.create(); 2987 let window: UiWindow = await driver.findWindow({actived: true}); 2988 let mode = await window.getWindowMode(); 2989} 2990``` 2991 2992### isFocused<sup>9+</sup> 2993 2994isFocused(): Promise\<boolean> 2995 2996判断窗口是否处于获焦状态。 2997 2998**系统能力**：SystemCapability.Test.UiTest 2999 3000**返回值：** 3001 3002| 类型 | 说明 | 3003| ----------------- | ------------------------------------------------------------ | 3004| Promise\<boolean> | 以Promise形式返回窗口对象是否获取获焦状态，true：获焦，false：未获焦。 | 3005 3006**错误码：** 3007 3008以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3009 3010| 错误码ID | 错误信息 | 3011| -------- | ---------------------------------------- | 3012| 17000002 | if the async function was not called with await. | 3013| 17000004 | if the window is invisible or destroyed. | 3014 3015**示例：** 3016 3017```ts 3018import { Driver, UiWindow } from '@ohos.UiTest'; 3019async function demo() { 3020 let driver: Driver = Driver.create(); 3021 let window: UiWindow = await driver.findWindow({actived: true}); 3022 let focused = await window.isFocused(); 3023} 3024``` 3025 3026### isActived<sup>(deprecated)</sup> 3027 3028isActived(): Promise\<boolean> 3029 3030判断窗口是否为用户正在交互窗口，使用Promise异步回调。 3031 3032从API version 9开始支持，从API version 11开始废弃，建议使用[isActive<sup>11+</sup>](#isactive11)替代。 3033 3034**系统能力**：SystemCapability.Test.UiTest 3035 3036**返回值：** 3037 3038| 类型 | 说明 | 3039| ----------------- | ------------------------------------------------------------ | 3040| Promise\<boolean> | 以Promise形式返回窗口对象是否为用户正在交互窗口，true表示是交互窗口，false表示非交互窗口。 | 3041 3042**错误码：** 3043 3044以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3045 3046| 错误码ID | 错误信息 | 3047| -------- | ---------------------------------------- | 3048| 17000002 | if the async function was not called with await. | 3049| 17000004 | if the window is invisible or destroyed. | 3050 3051**示例：** 3052 3053```ts 3054import { Driver, UiWindow } from '@ohos.UiTest'; 3055async function demo() { 3056 let driver: Driver = Driver.create(); 3057 let window: UiWindow = await driver.findWindow({actived: true}); 3058 let focused = await window.isActived(); 3059} 3060``` 3061 3062### focus<sup>9+</sup> 3063 3064focus(): Promise\<void> 3065 3066让窗口获焦。 3067 3068**系统能力**：SystemCapability.Test.UiTest 3069 3070**错误码：** 3071 3072以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3073 3074| 错误码ID | 错误信息 | 3075| -------- | ---------------------------------------- | 3076| 17000002 | if the async function was not called with await. | 3077| 17000004 | if the window is invisible or destroyed. | 3078 3079**示例：** 3080 3081```ts 3082import { Driver, UiWindow } from '@ohos.UiTest'; 3083async function demo() { 3084 let driver: Driver = Driver.create(); 3085 let window: UiWindow = await driver.findWindow({actived: true}); 3086 await window.focus(); 3087} 3088``` 3089 3090### moveTo<sup>9+</sup> 3091 3092moveTo(x: number, y: number): Promise\<void> 3093 3094将窗口移动到目标点。适用于支持移动的窗口。 3095 3096**系统能力**：SystemCapability.Test.UiTest 3097 3098**参数：** 3099 3100| 参数名 | 类型 | 必填 | 说明 | 3101| ------ | ------ | ---- | -------------------------------------- | 3102| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | 3103| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | 3104 3105**错误码：** 3106 3107以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3108 3109| 错误码ID | 错误信息 | 3110| -------- | ---------------------------------------- | 3111| 17000002 | if the async function was not called with await. | 3112| 17000004 | if the window is invisible or destroyed. | 3113| 17000005 | if the action is not supported on this window. | 3114 3115**示例：** 3116 3117```ts 3118import { Driver, UiWindow } from '@ohos.UiTest'; 3119async function demo() { 3120 let driver: Driver = Driver.create(); 3121 let window: UiWindow = await driver.findWindow({actived: true}); 3122 await window.moveTo(100, 100); 3123} 3124``` 3125 3126### resize<sup>9+</sup> 3127 3128resize(wide: number, height: number, direction: ResizeDirection): Promise\<void> 3129 3130根据传入的宽、高和调整方向来调整窗口的大小。适用于支持调整大小的窗口。 3131 3132**系统能力**：SystemCapability.Test.UiTest 3133 3134**参数：** 3135 3136| 参数名 | 类型 | 必填 | 说明 | 3137| --------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 3138| wide | number | 是 | 以number的形式传入调整后窗口的宽度。 | 3139| height | number | 是 | 以number的形式传入调整后窗口的高度。 | 3140| direction | [ResizeDirection](#resizedirection9) | 是 | 以[ResizeDirection](#resizedirection9)的形式传入窗口调整的方向。 | 3141 3142**错误码：** 3143 3144以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3145 3146| 错误码ID | 错误信息 | 3147| -------- | ---------------------------------------- | 3148| 17000002 | if the async function was not called with await. | 3149| 17000004 | if the window is invisible or destroyed. | 3150| 17000005 | if the action is not supported on this window. | 3151 3152**示例：** 3153 3154```ts 3155import { Driver, ResizeDirection, UiWindow } from '@ohos.UiTest'; 3156async function demo() { 3157 let driver: Driver = Driver.create(); 3158 let window: UiWindow = await driver.findWindow({actived: true}); 3159 await window.resize(100, 100, ResizeDirection.LEFT); 3160} 3161``` 3162 3163### split<sup>9+</sup> 3164 3165split(): Promise\<void> 3166 3167将窗口模式切换成分屏模式。适用于支持切换分屏模式的窗口。 3168 3169**系统能力**：SystemCapability.Test.UiTest 3170 3171**错误码：** 3172 3173以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3174 3175| 错误码ID | 错误信息 | 3176| -------- | ---------------------------------------- | 3177| 17000002 | if the async function was not called with await. | 3178| 17000004 | if the window is invisible or destroyed. | 3179| 17000005 | if the action is not supported on this window. | 3180 3181**示例：** 3182 3183```ts 3184import { Driver, UiWindow } from '@ohos.UiTest'; 3185async function demo() { 3186 let driver: Driver = Driver.create(); 3187 let window: UiWindow = await driver.findWindow({actived: true}); 3188 await window.split(); 3189} 3190``` 3191 3192### maximize<sup>9+</sup> 3193 3194maximize(): Promise\<void> 3195 3196将窗口最大化。适用于支持窗口最大化操作的窗口。 3197 3198**系统能力**：SystemCapability.Test.UiTest 3199 3200**错误码：** 3201 3202以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3203 3204| 错误码ID | 错误信息 | 3205| -------- | ---------------------------------------- | 3206| 17000002 | if the async function was not called with await. | 3207| 17000004 | if the window is invisible or destroyed. | 3208| 17000005 | if the action is not supported on this window. | 3209 3210**示例：** 3211 3212```ts 3213import { Driver, UiWindow } from '@ohos.UiTest'; 3214async function demo() { 3215 let driver: Driver = Driver.create(); 3216 let window: UiWindow = await driver.findWindow({actived: true}); 3217 await window.maximize(); 3218} 3219``` 3220 3221### minimize<sup>9+</sup> 3222 3223minimize(): Promise\<void> 3224 3225将窗口最小化。适用于支持窗口最小化操作的窗口。 3226 3227**系统能力**：SystemCapability.Test.UiTest 3228 3229**错误码：** 3230 3231以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3232 3233| 错误码ID | 错误信息 | 3234| -------- | ---------------------------------------- | 3235| 17000002 | if the async function was not called with await. | 3236| 17000004 | if the window is invisible or destroyed. | 3237| 17000005 | if the action is not supported on this window. | 3238 3239**示例：** 3240 3241```ts 3242import { Driver, UiWindow } from '@ohos.UiTest'; 3243async function demo() { 3244 let driver: Driver = Driver.create(); 3245 let window: UiWindow = await driver.findWindow({actived: true}); 3246 await window.minimize(); 3247} 3248``` 3249 3250### resume<sup>9+</sup> 3251 3252resume(): Promise\<void> 3253 3254将窗口恢复到之前的窗口模式。 3255 3256**系统能力**：SystemCapability.Test.UiTest 3257 3258**错误码：** 3259 3260以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3261 3262| 错误码ID | 错误信息 | 3263| -------- | ---------------------------------------- | 3264| 17000002 | if the async function was not called with await. | 3265| 17000004 | if the window is invisible or destroyed. | 3266| 17000005 | if the action is not supported on this window. | 3267 3268**示例：** 3269 3270```ts 3271import { Driver, UiWindow } from '@ohos.UiTest'; 3272async function demo() { 3273 let driver: Driver = Driver.create(); 3274 let window: UiWindow = await driver.findWindow({actived: true}); 3275 await window.resume(); 3276} 3277``` 3278 3279### close<sup>9+</sup> 3280 3281close(): Promise\<void> 3282 3283将窗口关闭。 3284 3285**系统能力**：SystemCapability.Test.UiTest 3286 3287**错误码：** 3288 3289以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3290 3291| 错误码ID | 错误信息 | 3292| -------- | ---------------------------------------- | 3293| 17000002 | if the async function was not called with await. | 3294| 17000004 | if the window is invisible or destroyed. | 3295| 17000005 | if the action is not supported on this window. | 3296 3297**示例：** 3298 3299```ts 3300import { Driver, UiWindow } from '@ohos.UiTest'; 3301async function demo() { 3302 let driver:Driver = Driver.create(); 3303 let window: UiWindow = await driver.findWindow({actived: true}); 3304 await window.close(); 3305} 3306``` 3307 3308### isActive<sup>11+</sup> 3309 3310isActive(): Promise\<boolean> 3311 3312判断窗口是否为用户正在交互窗口。 3313 3314**系统能力**：SystemCapability.Test.UiTest 3315 3316**返回值：** 3317 3318| 类型 | 说明 | 3319| ----------------- | ------------------------------------------------------------ | 3320| Promise\<boolean> | 以Promise形式返回窗口对象是否为用户正在交互窗口，true：交互窗口，false：非交互窗口。 | 3321 3322**错误码：** 3323 3324以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3325 3326| 错误码ID | 错误信息 | 3327| -------- | ------------------------------------------------ | 3328| 17000002 | if the async function was not called with await. | 3329| 17000004 | if the window is invisible or destroyed. | 3330 3331**示例：** 3332 3333```ts 3334import { Driver, UiWindow } from '@ohos.UiTest'; 3335async function demo() { 3336 let driver: Driver = Driver.create(); 3337 let window: UiWindow = await driver.findWindow({active: true}); 3338 let focused = await window.isActive(); 3339} 3340``` 3341 3342## UIEventObserver<sup>10+</sup> 3343 3344UI事件监听器。 3345 3346### once('toastShow') 3347 3348once(type: 'toastShow', callback: Callback\<UIElementInfo>): void; 3349 3350开始监听toast控件出现的事件，使用callback的形式返回结果。 3351 3352**系统能力**：SystemCapability.Test.UiTest 3353 3354**参数：** 3355 3356| 参数名 | 类型 | 必填 | 说明 | 3357| -------- | -------------------------------------------- | ---- | --------------------------------- | 3358| type | string | 是 | 订阅的事件类型，取值为'toastShow' | 3359| callback | Callback\<[UIElementInfo](#uielementinfo10)> | 是 | 事件发生时执行的回调函数 | 3360 3361**示例：** 3362 3363```ts 3364import { Driver, UIElementInfo, UIEventObserver } from '@ohos.UiTest'; 3365async function demo() { 3366 let driver: Driver = Driver.create(); 3367 let observer: UIEventObserver = await driver.createUIEventObserver() 3368 let callback = (UIElementInfo: UIElementInfo)=>{ 3369 console.info(UIElementInfo.bundleName) 3370 console.info(UIElementInfo.text) 3371 console.info(UIElementInfo.type) 3372 } 3373 observer.once('toastShow', callback) 3374} 3375``` 3376 3377### once('dialogShow') 3378 3379once(type: 'dialogShow', callback: Callback\<UIElementInfo>): void; 3380 3381开始监听dialog控件出现的事件，使用callback的形式返回结果。 3382 3383**系统能力**：SystemCapability.Test.UiTest 3384 3385**参数：** 3386 3387| 参数名 | 类型 | 必填 | 说明 | 3388| -------- | -------------------------------------------- | ---- | ---------------------------------- | 3389| type | string | 是 | 订阅的事件类型，取值为'dialogShow' | 3390| callback | Callback\<[UIElementInfo](#uielementinfo10)> | 是 | 事件发生时执行的回调函数 | 3391 3392**示例：** 3393 3394```ts 3395import { Driver, UIElementInfo, UIEventObserver } from '@ohos.UiTest'; 3396async function demo() { 3397 let driver: Driver = Driver.create(); 3398 let observer: UIEventObserver = await driver.createUIEventObserver() 3399 let callback = (UIElementInfo: UIElementInfo)=>{ 3400 console.info(UIElementInfo.bundleName) 3401 console.info(UIElementInfo.text) 3402 console.info(UIElementInfo.type) 3403 } 3404 observer.once('dialogShow', callback) 3405} 3406``` 3407 3408## By<sup>(deprecated)</sup> 3409 3410UiTest框架通过By类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。<br> 3411By提供的API能力具有以下几个特点:<br>1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。<br>2、控件属性支持多种匹配模式。<br>3、支持控件绝对定位，相对定位，可通过[By.isBefore<sup>(deprecated)</sup>](#isbeforedeprecated)和[By.isAfter<sup>(deprecated)</sup>](#isafterdeprecated)等API限定邻近控件特征进行辅助定位。<br>By类提供的所有API均为同步接口，建议使用者通过静态构造器BY来链式创建By对象。 3412 3413从API version 9开始不再维护，建议使用[On<sup>9+</sup>](#on9)。 3414 3415```ts 3416import { BY } from '@ohos.UiTest'; 3417BY.text('123').type('Button'); 3418``` 3419 3420### text<sup>(deprecated)</sup> 3421 3422text(txt: string, pattern?: MatchPattern): By 3423 3424指定目标控件文本属性，支持多种匹配模式，返回By对象自身。 3425 3426从API version 9开始不再维护，建议使用[text<sup>9+</sup>](#text9)。 3427 3428**系统能力**：SystemCapability.Test.UiTest 3429 3430**参数：** 3431 3432| 参数名 | 类型 | 必填 | 说明 | 3433| ------- | ----------------------------- | ---- | --------------------------------------------------- | 3434| txt | string | 是 | 指定控件文本，用于匹配目标控件文本。 | 3435| pattern | [MatchPattern](#matchpattern) | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 | 3436 3437**返回值：** 3438 3439| 类型 | 说明 | 3440| ------------------- | ---------------------------------- | 3441| [By](#bydeprecated) | 返回指定目标控件文本属性的By对象。 | 3442 3443**示例：** 3444 3445```ts 3446import { BY, By } from '@ohos.UiTest'; 3447let by: By = BY.text('123'); // 使用静态构造器BY创建by对象，指定目标控件的text属性。 3448``` 3449 3450 3451### key<sup>(deprecated)</sup> 3452 3453key(key: string): By 3454 3455指定目标控件key值属性，返回By对象自身。 3456 3457从API version 9开始不再维护，建议使用[id<sup>9+</sup>](#id9)。 3458 3459**系统能力**：SystemCapability.Test.UiTest 3460 3461**参数：** 3462 3463| 参数名 | 类型 | 必填 | 说明 | 3464| ------ | ------ | ---- | ----------------- | 3465| key | string | 是 | 指定控件的Key值。 | 3466 3467**返回值：** 3468 3469| 类型 | 说明 | 3470| ------------------- | ----------------------------------- | 3471| [By](#bydeprecated) | 返回指定目标控件key值属性的By对象。 | 3472 3473**示例：** 3474 3475```ts 3476import { By, BY } from '@ohos.UiTest'; 3477let by: By = BY.key('123'); // 使用静态构造器BY创建by对象，指定目标控件的key值属性。 3478``` 3479 3480 3481### id<sup>(deprecated)</sup> 3482 3483id(id: number): By 3484 3485指定目标控件id属性，返回By对象自身。 3486 3487从API version 9开始废弃。 3488 3489**系统能力**：SystemCapability.Test.UiTest 3490 3491**参数：** 3492 3493| 参数名 | 类型 | 必填 | 说明 | 3494| ------ | ------ | ---- | ---------------- | 3495| id | number | 是 | 指定控件的id值。 | 3496 3497**返回值：** 3498 3499| 类型 | 说明 | 3500| ------------------- | -------------------------------- | 3501| [By](#bydeprecated) | 返回指定目标控件id属性的By对象。 | 3502 3503**示例：** 3504 3505```ts 3506import { By, BY } from '@ohos.UiTest'; 3507let by: By = BY.id(123); // 使用静态构造器BY创建by对象，指定目标控件的id属性。 3508``` 3509 3510 3511### type<sup>(deprecated)</sup> 3512 3513type(tp: string): By 3514 3515指定目标控件的控件类型属性，返回By对象自身。 3516 3517从API version 9开始不再维护，建议使用[type<sup>9+</sup>](#type9)。 3518 3519**系统能力**：SystemCapability.Test.UiTest 3520 3521**参数：** 3522 3523| 参数名 | 类型 | 必填 | 说明 | 3524| ------ | ------ | ---- | -------------- | 3525| tp | string | 是 | 指定控件类型。 | 3526 3527**返回值：** 3528 3529| 类型 | 说明 | 3530| ------------------- | ---------------------------------------- | 3531| [By](#bydeprecated) | 返回指定目标控件的控件类型属性的By对象。 | 3532 3533**示例：** 3534 3535```ts 3536import { By, BY } from '@ohos.UiTest'; 3537let by: By = BY.type('Button'); // 使用静态构造器BY创建by对象，指定目标控件的控件类型属性。 3538``` 3539 3540 3541### clickable<sup>(deprecated)</sup> 3542 3543clickable(b?: boolean): By 3544 3545指定目标控件的可点击状态属性，返回By对象自身。 3546 3547从API version 9开始不再维护，建议使用[clickable<sup>9+</sup>](#clickable9)。 3548 3549**系统能力**：SystemCapability.Test.UiTest 3550 3551**参数：** 3552 3553| 参数名 | 类型 | 必填 | 说明 | 3554| ------ | ------- | ---- | ------------------------------------------------------------ | 3555| b | boolean | 否 | 指定控件可点击状态，true：可点击，false：不可点击。默认为true。 | 3556 3557**返回值：** 3558 3559| 类型 | 说明 | 3560| ------------------- | ------------------------------------------ | 3561| [By](#bydeprecated) | 返回指定目标控件的可点击状态属性的By对象。 | 3562 3563**示例：** 3564 3565```ts 3566import { By, BY } from '@ohos.UiTest'; 3567let by: By = BY.clickable(true); // 使用静态构造器BY创建by对象，指定目标控件的可点击状态属性。 3568``` 3569 3570 3571### scrollable<sup>(deprecated)</sup> 3572 3573scrollable(b?: boolean): By 3574 3575指定目标控件的可滑动状态属性，返回By对象自身。 3576 3577从API version 9开始不再维护，建议使用[scrollable<sup>9+</sup>](#scrollable9)。 3578 3579**系统能力**：SystemCapability.Test.UiTest 3580 3581**参数：** 3582 3583| 参数名 | 类型 | 必填 | 说明 | 3584| ------ | ------- | ---- | ----------------------------------------------------------- | 3585| b | boolean | 否 | 控件可滑动状态，true：可滑动，false：不可滑动。默认为true。 | 3586 3587**返回值：** 3588 3589| 类型 | 说明 | 3590| ------------------- | ------------------------------------------ | 3591| [By](#bydeprecated) | 返回指定目标控件的可滑动状态属性的By对象。 | 3592 3593**示例：** 3594 3595```ts 3596import { By, BY } from '@ohos.UiTest'; 3597let by: By = BY.scrollable(true); // 使用静态构造器BY创建by对象，指定目标控件的可滑动状态属性。 3598``` 3599 3600### enabled<sup>(deprecated)</sup> 3601 3602enabled(b?: boolean): By 3603 3604指定目标控件的使能状态属性，返回By对象自身。 3605 3606从API version 9开始不再维护，建议使用[enabled<sup>9+</sup>](#enabled9)。 3607 3608**系统能力**：SystemCapability.Test.UiTest 3609 3610**参数：** 3611 3612| 参数名 | 类型 | 必填 | 说明 | 3613| ------ | ------- | ---- | --------------------------------------------------------- | 3614| b | boolean | 否 | 指定控件使能状态，true：使能，false：未使能。默认为true。 | 3615 3616**返回值：** 3617 3618| 类型 | 说明 | 3619| ------------------- | ---------------------------------------- | 3620| [By](#bydeprecated) | 返回指定目标控件的使能状态属性的By对象。 | 3621 3622**示例：** 3623 3624```ts 3625import { By, BY } from '@ohos.UiTest'; 3626let by: By = BY.enabled(true); // 使用静态构造器BY创建by对象，指定目标控件的使能状态属性。 3627``` 3628 3629### focused<sup>(deprecated)</sup> 3630 3631focused(b?: boolean): By 3632 3633指定目标控件的获焦状态属性，返回By对象自身。 3634 3635从API version 9开始不再维护，建议使用[focused<sup>9+</sup>](#focused9)。 3636 3637**系统能力**：SystemCapability.Test.UiTest 3638 3639**参数：** 3640 3641| 参数名 | 类型 | 必填 | 说明 | 3642| ------ | ------- | ---- | ----------------------------------------------------- | 3643| b | boolean | 否 | 控件获焦状态，true：获焦，false：未获焦。默认为true。 | 3644 3645**返回值：** 3646 3647| 类型 | 说明 | 3648| ------------------- | ---------------------------------------- | 3649| [By](#bydeprecated) | 返回指定目标控件的获焦状态属性的By对象。 | 3650 3651**示例：** 3652 3653```ts 3654import { By, BY } from '@ohos.UiTest'; 3655let by: By = BY.focused(true); // 使用静态构造器BY创建by对象，指定目标控件的获焦状态属性。 3656``` 3657 3658### selected<sup>(deprecated)</sup> 3659 3660selected(b?: boolean): By 3661 3662指定目标控件的被选中状态属性，返回By对象自身。 3663 3664从API version 9开始不再维护，建议使用[selected<sup>9+</sup>](#selected9)。 3665 3666**系统能力**：SystemCapability.Test.UiTest 3667 3668**参数：** 3669 3670| 参数名 | 类型 | 必填 | 说明 | 3671| ------ | ------- | ---- | ------------------------------------------------------------ | 3672| b | boolean | 否 | 指定控件被选中状态，true：被选中，false：未被选中。默认为true。 | 3673 3674**返回值：** 3675 3676| 类型 | 说明 | 3677| ------------------- | ------------------------------------------ | 3678| [By](#bydeprecated) | 返回指定目标控件的被选中状态属性的By对象。 | 3679 3680**示例：** 3681 3682```ts 3683import { By, BY } from '@ohos.UiTest'; 3684let by: By = BY.selected(true); // 使用静态构造器BY创建by对象，指定目标控件的被选中状态属性。 3685``` 3686 3687### isBefore<sup>(deprecated)</sup> 3688 3689isBefore(by: By): By 3690 3691指定目标控件位于给出的特征属性控件之前，返回By对象自身。 3692 3693从API version 9开始不再维护，建议使用[isBefore<sup>9+</sup>](#isbefore9)。 3694 3695**系统能力**：SystemCapability.Test.UiTest 3696 3697**参数：** 3698 3699| 参数名 | 类型 | 必填 | 说明 | 3700| ------ | ------------------- | ---- | ---------------- | 3701| by | [By](#bydeprecated) | 是 | 特征控件的属性。 | 3702 3703**返回值：** 3704 3705| 类型 | 说明 | 3706| ------------------- | ---------------------------------------------------- | 3707| [By](#bydeprecated) | 返回指定目标控件位于给出的特征属性控件之前的By对象。 | 3708 3709**示例：** 3710 3711```ts 3712import { By, BY } from '@ohos.UiTest'; 3713 3714// 使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之前。 3715let by: By = BY.type('Button').isBefore(BY.text('123')); // 查找text为123之前的第一个Button组件 3716``` 3717 3718### isAfter<sup>(deprecated)</sup> 3719 3720isAfter(by: By): By 3721 3722指定目标控件位于给出的特征属性控件之后，返回By对象自身。 3723 3724从API version 9开始不再维护，建议使用[isAfter<sup>9+</sup>](#isafter9)。 3725 3726**系统能力**：SystemCapability.Test.UiTest 3727 3728**参数：** 3729 3730| 参数名 | 类型 | 必填 | 说明 | 3731| ------ | ------------------- | ---- | ---------------- | 3732| by | [By](#bydeprecated) | 是 | 特征控件的属性。 | 3733 3734**返回值：** 3735 3736| 类型 | 说明 | 3737| ------------------- | ---------------------------------------------------- | 3738| [By](#bydeprecated) | 返回指定目标控件位于给出的特征属性控件之后的By对象。 | 3739 3740**示例：** 3741 3742```ts 3743import { By, BY } from '@ohos.UiTest'; 3744 3745// 使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之后。 3746let by: By = BY.type('Text').isAfter(BY.text('123')); // 查找 text为123之后的第一个Text组件 3747``` 3748 3749## UiComponent<sup>(deprecated)</sup> 3750 3751UiTest中，UiComponent类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。 3752该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。 3753 3754从API version 9开始不再维护，建议使用[Component<sup>9+</sup>](#component9)。 3755 3756### click<sup>(deprecated)</sup> 3757 3758click(): Promise\<void> 3759 3760控件对象进行点击操作。 3761 3762从API version 9开始不再维护，建议使用[click<sup>9+</sup>](#click9)。 3763 3764**系统能力**：SystemCapability.Test.UiTest 3765 3766**示例：** 3767 3768```ts 3769import { UiDriver, BY, Driver, UiComponent } from '@ohos.UiTest'; 3770async function demo() { 3771 let driver: UiDriver = UiDriver.create(); 3772 let button: UiComponent = await driver.findComponent(BY.type('Button')); 3773 await button.click(); 3774} 3775``` 3776 3777### doubleClick<sup>(deprecated)</sup> 3778 3779doubleClick(): Promise\<void> 3780 3781控件对象进行双击操作。 3782 3783从API version 9开始不再维护，建议使用[doubleClick<sup>9+</sup>](#doubleclick9)。 3784 3785**系统能力**：SystemCapability.Test.UiTest 3786 3787**示例：** 3788 3789```ts 3790import { UiDriver, BY, UiComponent } from '@ohos.UiTest'; 3791async function demo() { 3792 let driver: UiDriver = UiDriver.create(); 3793 let button: UiComponent = await driver.findComponent(BY.type('Button')); 3794 await button.doubleClick(); 3795} 3796``` 3797 3798### longClick<sup>(deprecated)</sup> 3799 3800longClick(): Promise\<void> 3801 3802控件对象进行长按操作。 3803 3804从API version 9开始不再维护，建议使用[longClick<sup>9+</sup>](#longclick9)。 3805 3806**系统能力**：SystemCapability.Test.UiTest 3807 3808**示例：** 3809 3810```ts 3811import { UiDriver, BY, UiComponent } from '@ohos.UiTest'; 3812async function demo() { 3813 let driver: UiDriver = UiDriver.create(); 3814 let button: UiComponent = await driver.findComponent(BY.type('Button')); 3815 await button.longClick(); 3816} 3817``` 3818 3819### getId<sup>(deprecated)</sup> 3820 3821getId(): Promise\<number> 3822 3823获取控件对象的id值。 3824 3825从API version 9开始不再维护，被废弃。 3826 3827**系统能力**：SystemCapability.Test.UiTest 3828 3829**返回值：** 3830 3831| 类型 | 说明 | 3832| ---------------- | ------------------------------- | 3833| Promise\<number> | 以Promise形式返回的控件的id值。 | 3834 3835**示例：** 3836 3837```ts 3838import { UiDriver, BY, UiComponent } from '@ohos.UiTest'; 3839async function demo() { 3840 let driver: UiDriver = UiDriver.create(); 3841 let button: UiComponent = await driver.findComponent(BY.type('Button')); 3842 let id = await button.getId(); 3843} 3844``` 3845 3846### getKey<sup>(deprecated)</sup> 3847 3848getKey(): Promise\<string> 3849 3850获取控件对象的key值。 3851 3852从API version 9开始不再维护，建议使用[getId<sup>9+</sup>](#getid9) 3853 3854**系统能力**：SystemCapability.Test.UiTest 3855 3856**返回值：** 3857 3858| 类型 | 说明 | 3859| ---------------- | ------------------------------ | 3860| Promise\<string> | 以Promise形式返回控件的key值。 | 3861 3862**示例：** 3863 3864```ts 3865import { UiDriver, BY, UiComponent } from '@ohos.UiTest'; 3866async function demo() { 3867 let driver: UiDriver = UiDriver.create(); 3868 let button: UiComponent = await driver.findComponent(BY.type('Button')); 3869 let str_key = await button.getKey(); 3870} 3871``` 3872 3873### getText<sup>(deprecated)</sup> 3874 3875getText(): Promise\<string> 3876 3877获取控件对象的文本信息。 3878 3879从API version 9开始不再维护，建议使用[getText<sup>9+</sup>](#gettext9)。 3880 3881**系统能力**：SystemCapability.Test.UiTest 3882 3883**返回值：** 3884 3885| 类型 | 说明 | 3886| ---------------- | --------------------------------- | 3887| Promise\<string> | 以Promise形式返回控件的文本信息。 | 3888 3889**示例：** 3890 3891```ts 3892import { UiDriver, BY, UiComponent } from '@ohos.UiTest'; 3893async function demo() { 3894 let driver: UiDriver = UiDriver.create(); 3895 let button: UiComponent = await driver.findComponent(BY.type('Button')); 3896 let text = await button.getText(); 3897} 3898``` 3899 3900### getType<sup>(deprecated)</sup> 3901 3902getType(): Promise\<string> 3903 3904获取控件对象的控件类型。 3905 3906从API version 9开始不再维护，建议使用[getType<sup>9+</sup>](#gettype9)。 3907 3908**系统能力**：SystemCapability.Test.UiTest 3909 3910**返回值：** 3911 3912| 类型 | 说明 | 3913| ---------------- | ----------------------------- | 3914| Promise\<string> | 以Promise形式返回控件的类型。 | 3915 3916**示例：** 3917 3918```ts 3919import { UiDriver, BY, UiComponent } from '@ohos.UiTest'; 3920async function demo() { 3921 let driver: UiDriver = UiDriver.create(); 3922 let button: UiComponent = await driver.findComponent(BY.type('Button')); 3923 let type = await button.getType(); 3924} 3925``` 3926 3927### isClickable<sup>(deprecated)</sup> 3928 3929isClickable(): Promise\<boolean> 3930 3931获取控件对象可点击状态。 3932 3933从API version 9开始不再维护，建议使用[isClickable<sup>9+</sup>](#isclickable9)。 3934 3935**系统能力**：SystemCapability.Test.UiTest 3936 3937**返回值：** 3938 3939| 类型 | 说明 | 3940| ----------------- | ------------------------------------------------------------ | 3941| Promise\<boolean> | 以Promise形式返回控件对象可点击状态，true：可点击，false：不可点击。 | 3942 3943**示例：** 3944 3945```ts 3946import { UiDriver, BY, UiComponent } from '@ohos.UiTest'; 3947async function demo() { 3948 let driver: UiDriver = UiDriver.create(); 3949 let button: UiComponent = await driver.findComponent(BY.type('Button')); 3950 if(await button.isClickable()) { 3951 console.info('This button can be Clicked'); 3952 } else { 3953 console.info('This button can not be Clicked'); 3954 } 3955} 3956``` 3957 3958### isScrollable<sup>(deprecated)</sup> 3959 3960isScrollable(): Promise\<boolean> 3961 3962获取控件对象可滑动状态。 3963 3964从API version 9开始不再维护，建议使用[isScrollable<sup>9+</sup>](#isscrollable9)。 3965 3966**系统能力**：SystemCapability.Test.UiTest 3967 3968**返回值：** 3969 3970| 类型 | 说明 | 3971| ----------------- | ------------------------------------------------------------ | 3972| Promise\<boolean> | 以Promise形式返回控件对象可滑动状态，true：可滑动，false：不可滑动。 | 3973 3974**示例：** 3975 3976```ts 3977import { UiDriver, BY, UiComponent } from '@ohos.UiTest'; 3978async function demo() { 3979 let driver: UiDriver = UiDriver.create(); 3980 let scrollBar: UiComponent = await driver.findComponent(BY.scrollable(true)); 3981 if(await scrollBar.isScrollable()) { 3982 console.info('This scrollBar can be operated'); 3983 } else { 3984 console.info('This scrollBar can not be operated'); 3985 } 3986} 3987``` 3988 3989 3990### isEnabled<sup>(deprecated)</sup> 3991 3992isEnabled(): Promise\<boolean> 3993 3994获取控件使能状态。 3995 3996从API version 9开始不再维护，建议使用[isEnabled<sup>9+</sup>](#isenabled9)。 3997 3998**系统能力**：SystemCapability.Test.UiTest 3999 4000**返回值：** 4001 4002| 类型 | 说明 | 4003| ----------------- | ---------------------------------------------------------- | 4004| Promise\<boolean> | 以Promise形式返回控件使能状态，true：使能，false：未使能。 | 4005 4006**示例：** 4007 4008```ts 4009import { UiDriver, BY, UiComponent } from '@ohos.UiTest'; 4010async function demo() { 4011 let driver: UiDriver = UiDriver.create(); 4012 let button: UiComponent = await driver.findComponent(BY.type('Button')); 4013 if(await button.isEnabled()) { 4014 console.info('This button can be operated'); 4015 } else { 4016 console.info('This button can not be operated'); 4017 } 4018} 4019 4020``` 4021 4022### isFocused<sup>(deprecated)</sup> 4023 4024isFocused(): Promise\<boolean> 4025 4026判断控件对象是否获焦。 4027 4028从API version 9开始不再维护，建议使用[isFocused<sup>9+</sup>](#isfocused9)。 4029 4030**系统能力**：SystemCapability.Test.UiTest 4031 4032**返回值：** 4033 4034| 类型 | 说明 | 4035| ----------------- | ------------------------------------------------------------ | 4036| Promise\<boolean> | 以Promise形式返回控件对象是否获焦，true：获焦，false：未获焦。 | 4037 4038**示例：** 4039 4040```ts 4041import { UiDriver, BY, UiComponent } from '@ohos.UiTest'; 4042async function demo() { 4043 let driver: UiDriver = UiDriver.create(); 4044 let button: UiComponent = await driver.findComponent(BY.type('Button')); 4045 if(await button.isFocused()) { 4046 console.info('This button is focused'); 4047 } else { 4048 console.info('This button is not focused'); 4049 } 4050} 4051``` 4052 4053### isSelected<sup>(deprecated)</sup> 4054 4055isSelected(): Promise\<boolean> 4056 4057获取控件对象被选中状态。 4058 4059从API version 9开始不再维护，建议使用[isSelected<sup>9+</sup>](#isselected9)。 4060 4061**系统能力**：SystemCapability.Test.UiTest 4062 4063**返回值：** 4064 4065| 类型 | 说明 | 4066| ----------------- | ----------------------------------------------------- | 4067| Promise\<boolean> | 以Promise形式返回控件对象被选中的状态，true：被选中，false：未被选中。 | 4068 4069**示例：** 4070 4071```ts 4072import { UiDriver, BY, UiComponent } from '@ohos.UiTest'; 4073async function demo() { 4074 let driver: UiDriver = UiDriver.create(); 4075 let button: UiComponent = await driver.findComponent(BY.type('Button')); 4076 if(await button.isSelected()) { 4077 console.info('This button is selected'); 4078 } else { 4079 console.info('This button is not selected'); 4080 } 4081} 4082``` 4083 4084### inputText<sup>(deprecated)</sup> 4085 4086inputText(text: string): Promise\<void> 4087 4088向控件中输入文本(适用于文本框控件)。 4089 4090从API version 9开始不再维护，建议使用[inputText<sup>9+</sup>](#inputtext9)。 4091 4092**系统能力**：SystemCapability.Test.UiTest 4093 4094**参数：** 4095 4096| 参数名 | 类型 | 必填 | 说明 | 4097| ------ | ------ | ---- | ---------------- | 4098| text | string | 是 | 输入的文本信息。 | 4099 4100**示例：** 4101 4102```ts 4103import { UiDriver, BY, UiComponent } from '@ohos.UiTest'; 4104async function demo() { 4105 let driver: UiDriver = UiDriver.create(); 4106 let text: UiComponent = await driver.findComponent(BY.text('hello world')); 4107 await text.inputText('123'); 4108} 4109``` 4110 4111### scrollSearch<sup>(deprecated)</sup> 4112 4113scrollSearch(by: By): Promise\<UiComponent> 4114 4115在控件上滑动查找目标控件(适用于List等支持滑动的控件)。 4116 4117从API version 9开始不再维护，建议使用[scrollSearch<sup>9+</sup>](#scrollsearch9)。 4118 4119**系统能力**：SystemCapability.Test.UiTest 4120 4121**参数：** 4122 4123| 参数名 | 类型 | 必填 | 说明 | 4124| ------ | ------------------- | ---- | -------------------- | 4125| by | [By](#bydeprecated) | 是 | 目标控件的属性要求。 | 4126 4127**返回值：** 4128 4129| 类型 | 说明 | 4130| ----------------------------------------------- | ------------------------------------- | 4131| Promise\<[UiComponent](#uicomponentdeprecated)> | 以Promise形式返回找到的目标控件对象。 | 4132 4133**示例：** 4134 4135```ts 4136import { UiDriver, BY, UiComponent } from '@ohos.UiTest'; 4137async function demo() { 4138 let driver: UiDriver = UiDriver.create(); 4139 let scrollBar: UiComponent = await driver.findComponent(BY.type('Scroll')); 4140 let button = await scrollBar.scrollSearch(BY.text('next page')); 4141} 4142``` 4143 4144## UiDriver<sup>(deprecated)</sup> 4145 4146UiDriver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等API。 4147该类提供的方法除UiDriver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await调用。 4148 4149从API version 9开始不再维护，建议使用[Driver<sup>9+</sup>](#driver9)。 4150 4151### create<sup>(deprecated)</sup> 4152 4153static create(): UiDriver 4154 4155静态方法，构造一个UiDriver对象，并返回该对象。 4156 4157从API version 9开始不再维护，建议使用[create<sup>9+</sup>](#create9)。 4158 4159**系统能力**：SystemCapability.Test.UiTest 4160 4161**返回值：** 4162 4163| 类型 | 说明 | 4164| -------- | ------------------------ | 4165| UiDriver | 返回构造的UiDriver对象。 | 4166 4167**示例：** 4168 4169```ts 4170import { UiDriver } from '@ohos.UiTest'; 4171async function demo() { 4172 let driver: UiDriver = UiDriver.create(); 4173} 4174``` 4175 4176### delayMs<sup>(deprecated)</sup> 4177 4178delayMs(duration: number): Promise\<void> 4179 4180UiDriver对象在给定的时间内延时。 4181 4182从API version 9开始不再维护，建议使用[delayMs<sup>9+</sup>](#delayms9)。 4183 4184**系统能力**：SystemCapability.Test.UiTest 4185 4186**参数：** 4187 4188| 参数名 | 类型 | 必填 | 说明 | 4189| -------- | ------ | ---- | ------------ | 4190| duration | number | 是 | 给定的时间。 | 4191 4192**示例：** 4193 4194```ts 4195import { UiDriver } from '@ohos.UiTest'; 4196async function demo() { 4197 let driver: UiDriver = UiDriver.create(); 4198 await driver.delayMs(1000); 4199} 4200``` 4201 4202### findComponent<sup>(deprecated)</sup> 4203 4204findComponent(by: By): Promise\<UiComponent> 4205 4206在UiDriver对象中，根据给出的目标控件属性要求查找目标控件。 4207 4208从API version 9开始不再维护，建议使用[findComponent<sup>9+</sup>](#findcomponent9)。 4209 4210**系统能力**：SystemCapability.Test.UiTest 4211 4212**参数：** 4213 4214| 参数名 | 类型 | 必填 | 说明 | 4215| ------ | ------------------- | ---- | -------------------- | 4216| by | [By](#bydeprecated) | 是 | 目标控件的属性要求。 | 4217 4218**返回值：** 4219 4220| 类型 | 说明 | 4221| ----------------------------------------------- | --------------------------------- | 4222| Promise\<[UiComponent](#uicomponentdeprecated)> | 以Promise形式返回找到的控件对象。 | 4223 4224**示例：** 4225 4226```ts 4227import { UiDriver, BY, UiComponent } from '@ohos.UiTest'; 4228async function demo() { 4229 let driver: UiDriver = UiDriver.create(); 4230 let button: UiComponent = await driver.findComponent(BY.text('next page')); 4231} 4232``` 4233 4234### findComponents<sup>(deprecated)</sup> 4235 4236findComponents(by: By): Promise\<Array\<UiComponent>> 4237 4238在UiDriver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。 4239 4240从API version 9开始不再维护，建议使用[findComponents<sup>9+</sup>](#findcomponents9)。 4241 4242**系统能力**：SystemCapability.Test.UiTest 4243 4244**参数：** 4245 4246| 参数名 | 类型 | 必填 | 说明 | 4247| ------ | ------------------- | ---- | -------------------- | 4248| by | [By](#bydeprecated) | 是 | 目标控件的属性要求。 | 4249 4250**返回值：** 4251 4252| 类型 | 说明 | 4253| ------------------------------------------------------- | --------------------------------------- | 4254| Promise\<Array\<[UiComponent](#uicomponentdeprecated)>> | 以Promise形式返回找到的控件对象的列表。 | 4255 4256**示例：** 4257 4258```ts 4259import { UiDriver, BY, UiComponent } from '@ohos.UiTest'; 4260async function demo() { 4261 let driver: UiDriver = UiDriver.create(); 4262 let buttonList: Array<UiComponent> = await driver.findComponents(BY.text('next page')); 4263} 4264``` 4265 4266### assertComponentExist<sup>(deprecated)</sup> 4267 4268assertComponentExist(by: By): Promise\<void> 4269 4270断言API，用于断言当前界面存在满足给出的目标控件属性的控件; 如果控件不存在，该API将抛出JS异常，使当前测试用例失败。 4271 4272从API version 9开始不再维护，建议使用[assertComponentExist<sup>9+</sup>](#assertcomponentexist9)。 4273 4274**系统能力**：SystemCapability.Test.UiTest 4275 4276**参数：** 4277 4278| 参数名 | 类型 | 必填 | 说明 | 4279| ------ | ------------------- | ---- | -------------------- | 4280| by | [By](#bydeprecated) | 是 | 目标控件的属性要求。 | 4281 4282**错误码：** 4283 4284以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 4285 4286| 错误码ID | 错误信息 | 4287| -------- | ------------------------------------------------ | 4288| 17000002 | if the async function was not called with await. | 4289| 17000003 | if the assertion failed. | 4290 4291**示例：** 4292 4293```ts 4294import { UiDriver, BY } from '@ohos.UiTest'; 4295async function demo() { 4296 let driver: UiDriver = UiDriver.create(); 4297 await driver.assertComponentExist(BY.text('next page')); 4298} 4299``` 4300 4301### pressBack<sup>(deprecated)</sup> 4302 4303pressBack(): Promise\<void> 4304 4305UiDriver对象进行点击BACK键的操作。 4306 4307从API version 9开始不再维护，建议使用[pressBack<sup>9+</sup>](#pressback9)。 4308 4309**系统能力**：SystemCapability.Test.UiTest 4310 4311**示例：** 4312 4313```ts 4314import { UiDriver } from '@ohos.UiTest'; 4315async function demo() { 4316 let driver: UiDriver = UiDriver.create(); 4317 await driver.pressBack(); 4318} 4319``` 4320 4321### triggerKey<sup>(deprecated)</sup> 4322 4323triggerKey(keyCode: number): Promise\<void> 4324 4325UiDriver对象采取如下操作：通过key值找到对应键并点击。 4326 4327从API version 9开始不再维护，建议使用[triggerKey<sup>9+</sup>](#triggerkey9)。 4328 4329**系统能力**：SystemCapability.Test.UiTest 4330 4331**参数：** 4332 4333| 参数名 | 类型 | 必填 | 说明 | 4334| ------- | ------ | ---- | ------------- | 4335| keyCode | number | 是 | 指定的key值。 | 4336 4337**示例：** 4338 4339```ts 4340import { Driver, UiDriver } from '@ohos.UiTest'; 4341async function demo() { 4342 let driver: UiDriver = UiDriver.create(); 4343 await driver.triggerKey(123); 4344} 4345``` 4346 4347 4348### click<sup>(deprecated)</sup> 4349 4350click(x: number, y: number): Promise\<void> 4351 4352UiDriver对象采取如下操作：在目标坐标点单击。 4353 4354从API version 9开始不再维护，建议使用[click<sup>9+</sup>](#click9)。 4355 4356**系统能力**：SystemCapability.Test.UiTest 4357 4358**参数：** 4359 4360| 参数名 | 类型 | 必填 | 说明 | 4361| ------ | ------ | ---- | -------------------------------------- | 4362| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | 4363| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | 4364 4365**示例：** 4366 4367```ts 4368import { UiDriver } from '@ohos.UiTest'; 4369async function demo() { 4370 let driver: UiDriver = UiDriver.create(); 4371 await driver.click(100,100); 4372} 4373``` 4374 4375### doubleClick<sup>(deprecated)</sup> 4376 4377doubleClick(x: number, y: number): Promise\<void> 4378 4379UiDriver对象采取如下操作：在目标坐标点双击。 4380 4381从API version 9开始不再维护，建议使用[doubleClick<sup>9+</sup>](#doubleclick9)。 4382 4383**系统能力**：SystemCapability.Test.UiTest 4384 4385**参数：** 4386 4387| 参数名 | 类型 | 必填 | 说明 | 4388| ------ | ------ | ---- | -------------------------------------- | 4389| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | 4390| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | 4391 4392**示例：** 4393 4394```ts 4395import { UiDriver } from '@ohos.UiTest'; 4396async function demo() { 4397 let driver: UiDriver = UiDriver.create(); 4398 await driver.doubleClick(100,100); 4399} 4400``` 4401 4402### longClick<sup>(deprecated)</sup> 4403 4404longClick(x: number, y: number): Promise\<void> 4405 4406UiDriver对象采取如下操作：在目标坐标点长按下鼠标左键。 4407 4408从API version 9开始不再维护，建议使用[longClick<sup>9+</sup>](#longclick9)。 4409 4410**系统能力**：SystemCapability.Test.UiTest 4411 4412**参数：** 4413 4414| 参数名 | 类型 | 必填 | 说明 | 4415| ------ | ------ | ---- | -------------------------------------- | 4416| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | 4417| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | 4418 4419**示例：** 4420 4421```ts 4422import { UiDriver } from '@ohos.UiTest'; 4423async function demo() { 4424 let driver: UiDriver = UiDriver.create(); 4425 await driver.longClick(100,100); 4426} 4427``` 4428 4429### swipe<sup>(deprecated)</sup> 4430 4431swipe(startx: number, starty: number, endx: number, endy: number): Promise\<void> 4432 4433UiDriver对象采取如下操作：从给出的起始坐标点滑向给出的目的坐标点。 4434 4435从API version 9开始不再维护，建议使用[swipe<sup>9+</sup>](#swipe9)。 4436 4437**系统能力**：SystemCapability.Test.UiTest 4438 4439**参数：** 4440 4441| 参数名 | 类型 | 必填 | 说明 | 4442| ------ | ------ | ---- | -------------------------------------- | 4443| startx | number | 是 | 以number的形式传入起始点的横坐标信息。 | 4444| starty | number | 是 | 以number的形式传入起始点的纵坐标信息。 | 4445| endx | number | 是 | 以number的形式传入目的点的横坐标信息。 | 4446| endy | number | 是 | 以number的形式传入目的点的纵坐标信息。 | 4447 4448**示例：** 4449 4450```ts 4451import { UiDriver } from '@ohos.UiTest'; 4452async function demo() { 4453 let driver: UiDriver = UiDriver.create(); 4454 await driver.swipe(100,100,200,200); 4455} 4456``` 4457 4458### screenCap<sup>(deprecated)</sup> 4459 4460screenCap(savePath: string): Promise\<boolean> 4461 4462UiDriver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。 4463 4464从API version 9开始不再维护，建议使用[screenCap<sup>9+</sup>](#screencap9)。 4465 4466**系统能力**：SystemCapability.Test.UiTest 4467 4468**参数：** 4469 4470| 参数名 | 类型 | 必填 | 说明 | 4471| -------- | ------ | ---- | -------------- | 4472| savePath | string | 是 | 文件保存路径。 | 4473 4474**返回值：** 4475 4476| 类型 | 说明 | 4477| ----------------- | -------------------------------------- | 4478| Promise\<boolean> | 以Promise形式返回截图操作是否成功完成。成功完成为true。 | 4479 4480**示例：** 4481 4482```ts 4483import { UiDriver } from '@ohos.UiTest'; 4484async function demo() { 4485 let driver: UiDriver = UiDriver.create(); 4486 await driver.screenCap('/data/storage/el2/base/cache/1.png'); 4487} 4488```
