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