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