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