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