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