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