1# @ohos.UiTest 2 3<!--Kit: Test Kit--> 4<!--Subsystem: Test--> 5<!--Owner: @inter515--> 6<!--Designer: @inter515--> 7<!--Tester: @laonie666--> 8<!--Adviser: @Brilliantry_Rui--> 9 10 11UiTest提供模拟UI操作的能力，供开发者在测试场景使用，主要支持如点击、双击、长按、滑动等UI操作能力。 12 13该模块提供以下功能： 14 15- [On<sup>9+</sup>](#on9)：提供控件特征描述能力，用于控件筛选匹配查找。 16- [Component<sup>9+</sup>](#component9)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。 17- [Driver<sup>9+</sup>](#driver9)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能力。 18- [UiWindow<sup>9+</sup>](#uiwindow9)：入口类，提供窗口属性获取，窗口拖动、调整窗口大小等能力。 19- [By<sup>(deprecated)</sup>](#bydeprecated)：提供控件特征描述能力，用于控件筛选匹配查找。从API version 9开始不再维护，建议使用[On<sup>9+</sup>](#on9)。 20- [UiComponent<sup>(deprecated)</sup>](#uicomponentdeprecated)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。从API version 9开始不再维护，建议使用[Component<sup>9+</sup>](#component9)。 21- [UiDriver<sup>(deprecated)</sup>](#uidriverdeprecated)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能力。从API version 9开始不再维护，建议使用[Driver<sup>9+</sup>](#driver9)。 22 23> **说明：** 24> - 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 25> - 本模块接口在<!--RP1-->[自动化测试脚本](../../application-test/arkxtest-guidelines.md)<!--RP1End-->中使用。 26> - 本模块接口不支持并发调用。 27 28## 导入模块 29 30```ts 31import { Component, Driver, UiWindow, ON, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix, UiDirection, MouseButton, UIElementInfo, UIEventObserver, UiComponent, UiDriver, BY } from '@kit.TestKit'; 32``` 33 34## MatchPattern 35 36控件属性支持的匹配模式。 37 38**系统能力**：SystemCapability.Test.UiTest 39 40| 名称 | 值 | 说明 | 41|-----------------------|---|---------------------------------------------------------------------| 42| EQUALS | 0 | 等于给定值。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 43| CONTAINS | 1 | 包含给定值。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 44| STARTS_WITH | 2 | 以给定值开始。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 45| ENDS_WITH | 3 | 以给定值结束。 <br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 46| REG_EXP<sup>18+</sup> | 4 | 正则表达式匹配。<br />**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 47| REG_EXP_ICASE<sup>18+</sup> | 5 | 正则表达式匹配，忽略大小写。<br />**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 48## ResizeDirection<sup>9+</sup> 49 50窗口调整大小的方向。 51 52**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 53 54**系统能力**：SystemCapability.Test.UiTest 55 56| 名称 | 值 | 说明 | 57| ---------- | ---- | -------- | 58| LEFT | 0 | 左方。 | 59| RIGHT | 1 | 右方。 | 60| UP | 2 | 上方。 | 61| DOWN | 3 | 下方。 | 62| LEFT_UP | 4 | 左上方。 | 63| LEFT_DOWN | 5 | 左下方。 | 64| RIGHT_UP | 6 | 右上方。 | 65| RIGHT_DOWN | 7 | 右下方。 | 66 67## Point<sup>9+</sup> 68 69坐标点信息。 70 71**系统能力**：SystemCapability.Test.UiTest 72 73| 名称 | 类型 | 只读 | 可选 | 说明 | 74| ---- | ------ | ---- | ---- |-----------| 75| x | number | 否 | 否 | 坐标点的横坐标，取值大于0的整数。<br> **说明：** 从API version 20开始，该属性不再为只读属性。<br> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 76| y | number | 否 | 否 | 坐标点的纵坐标，取值大于0的整数。<br> **说明：** 从API version 20开始，该属性不再为只读属性。<br> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 77| displayId<sup>20+</sup> | number | 否 | 是 | 坐标点所属的屏幕ID，取值范围：大于等于0的整数。默认值为设备默认屏幕ID。<br> **原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。| 78 79## Rect<sup>9+</sup> 80 81控件的边框信息。 82 83**系统能力**：SystemCapability.Test.UiTest 84 85| 名称 | 类型 | 只读 | 可选 | 说明 | 86| ------ | ------ | ---- | ---- | ------------------------- | 87| left | number | 否 | 否 |控件边框的左上角的X坐标，取值大于0的整数。<br> **说明：** 从API version 20开始，该属性不再为只读属性。<br> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 88| top | number | 否 | 否 |控件边框的左上角的Y坐标，取值大于0的整数。<br> **说明：** 从API version 20开始，该属性不再为只读属性。<br> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 89| right | number | 否 | 否 |控件边框的右下角的X坐标，取值大于0的整数。<br> **说明：** 从API version 20开始，该属性不再为只读属性。<br> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 90| bottom | number | 否 | 否 |控件边框的右下角的Y坐标，取值大于0的整数。<br> **说明：** 从API version 20开始，该属性不再为只读属性。<br> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 91| displayId<sup>20+</sup> | number | 否 | 是 |控件边框所属的屏幕ID，取值大于或等于0的整数。默认值为设备默认屏幕ID。<br> **原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 92 93## WindowMode<sup>9+</sup> 94 95窗口的窗口模式。 96 97**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 98 99**系统能力**：SystemCapability.Test.UiTest 100 101| 名称 | 值 | 说明 | 102| ---------- | ---- | ---------- | 103| FULLSCREEN | 0 | 全屏模式。 | 104| PRIMARY | 1 | 主窗口。 | 105| SECONDARY | 2 | 第二窗口。 | 106| FLOATING | 3 | 浮动窗口。 | 107 108## DisplayRotation<sup>9+</sup> 109 110设备显示器的显示方向。 111 112**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 113 114**系统能力**：SystemCapability.Test.UiTest 115 116| 名称 | 值 | 说明 | 117| ------------ | ---- | ---------------------------------------- | 118| ROTATION_0 | 0 | 设备显示器不旋转，初始形态垂直显示。 | 119| ROTATION_90 | 1 | 设备显示器顺时针旋转90°，水平显示。 | 120| ROTATION_180 | 2 | 设备显示器顺时针旋转180°，逆向垂直显示。 | 121| ROTATION_270 | 3 | 设备显示器顺时针旋转270°，逆向水平显示。 | 122 123## WindowFilter<sup>9+</sup> 124 125窗口的标志属性信息。 126 127**系统能力**：SystemCapability.Test.UiTest 128 129| 名称 | 类型 | 只读 | 可选 | 说明 | 130| -------------------- | ------- | ---- | ---- |----------------------------------------------------------------------------------------| 131| bundleName | string | 否 | 是 | 窗口归属应用的包名，默认值为空。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 132| title | string | 否 | 是 | 窗口的标题信息，默认值为空。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 133| focused | boolean | 否 | 是 | 窗口是否处于获焦状态，true：获焦状态，false：未获焦状态，默认值为false。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 134| actived(deprecated) | boolean | 否 | 是 | 窗口是否正与用户进行交互，true：交互状态，false：未交互状态，默认值为false。<br>从API version 11开始废弃，建议使用active替代。 | 135| active<sup>11+</sup> | boolean | 否 | 是 | 窗口是否正与用户进行交互，true：交互状态，false：未交互状态，默认值为false。<br />**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 136| displayId<sup>20+</sup> | number | 否 | 是 | 窗口所属的屏幕ID。取值大于或等于0的整数。默认值为设备默认屏ID。<br> **原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 137 138## UiDirection<sup>10+</sup> 139 140进行抛滑等UI操作时的方向。 141 142**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 143 144**系统能力**：SystemCapability.Test.UiTest 145 146| 名称 | 值 | 说明 | 147| ----- | ---- | ------ | 148| LEFT | 0 | 向左。 | 149| RIGHT | 1 | 向右。 | 150| UP | 2 | 向上。 | 151| DOWN | 3 | 向下。 | 152 153## MouseButton<sup>10+</sup> 154 155模拟注入的鼠标按钮。 156 157**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 158 159**系统能力**：SystemCapability.Test.UiTest 160 161| 名称 | 值 | 说明 | 162| ------------------- | ---- | ------------ | 163| MOUSE_BUTTON_LEFT | 0 | 鼠标左键。 | 164| MOUSE_BUTTON_RIGHT | 1 | 鼠标右键。 | 165| MOUSE_BUTTON_MIDDLE | 2 | 鼠标中间键。 | 166 167## UIElementInfo<sup>10+</sup> 168 169UI事件的相关信息。 170 171**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 172 173**系统能力**：SystemCapability.Test.UiTest 174 175| 名称 | 类型 | 只读 | 可选 | 说明 | 176| ---------- | ------ | ---- | ---- | --------------------- | 177| bundleName | string | 是 | 否 | 归属应用的包名。 | 178| type | string | 是 | 否 | 控件/窗口类型。 | 179| text | string | 是 | 否 | 控件/窗口的文本信息。 | 180 181 182## TouchPadSwipeOptions<sup>18+</sup> 183 184触摸板多指滑动手势选项相关信息。 185 186**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 187 188**系统能力**：SystemCapability.Test.UiTest 189 190| 名称 | 类型 | 只读 | 可选 | 说明 | 191| ---------- | ------ |----|----|--------------------------------------------------------| 192| stay | boolean | 否 | 是 | 触摸板多指滑动结束是否停留1s后再抬起，默认为false（不停留1s），true：停留，false：不停留。 | 193| speed | number | 否 | 是 | 滑动速率，取值范围为200-40000的整数，默认值为2000，不在范围内设为默认值为2000，单位：px/s。 | 194 195 196## InputTextMode<sup>20+</sup> 197 198输入文本的方式。 199 200**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 201 202**系统能力**：SystemCapability.Test.UiTest 203 204| 名称 | 类型 | 只读 | 可选 | 说明 | 205| ---------- | ------ |----|----|----------------------------------------------------------| 206| paste | boolean | 否 | 是 | 输入文本时是否指定以复制粘贴方式输入。true：指定以复制粘贴方式输入。false：指定以逐字键入方式输入。默认为false。<br /> **说明：** 当输入文本中包含中文、特殊字符或文本长度超过200字符时，无论该参数取值为何，均以复制粘贴方式输入。| 207| addition | boolean | 否 | 是 | 输入文本时是否以追加的方式进行输入。true：以追加方式输入。false：不以追加方式输入。默认为false。| 208 209 210## On<sup>9+</sup> 211 212UiTest框架从API version 9开始，通过On类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。<br> 213On提供的API能力具有以下几个特点:<br>1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。<br>2、控件属性支持多种匹配模式。<br>3、支持控件绝对定位，相对定位，可通过[ON.isBefore](#isbefore9)和[ON.isAfter](#isafter9)等API限定邻近控件特征进行辅助定位。<br>On类提供的所有API均为同步接口，建议使用者通过静态构造器ON来链式创建On对象。 214 215```ts 216import { ON } from '@kit.TestKit'; 217 218ON.text('123').type('Button'); 219``` 220 221### text<sup>9+</sup> 222 223text(txt: string, pattern?: MatchPattern): On 224 225指定目标控件文本属性，支持多种匹配模式，返回On对象自身。 226 227> **说明** 228> 229> 如果控件的无障碍属性[accessibilityLevel](../apis-arkui/arkui-ts/ts-universal-attributes-accessibility.md#accessibilitylevel)设置为'no'或'no-hide-descendants'，无法使用本接口指定目标控件的文本属性用于查找控件，可以使用[On.originalText()](#originaltext20)接口实现。 230 231**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 232 233**系统能力**：SystemCapability.Test.UiTest 234 235**参数：** 236 237| 参数名 | 类型 | 必填 | 说明 | 238| ------- | ----------------------------- | ---- | --------------------------------------------------- | 239| txt | string | 是 | 指定控件文本，用于匹配目标控件文本。<!--RP2--><!--RP2End--> | 240| pattern | [MatchPattern](#matchpattern) | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 | 241 242**返回值：** 243 244| 类型 | 说明 | 245| ---------- | ---------------------------------- | 246| [On](#on9) | 返回指定目标控件文本属性的On对象。 | 247 248**错误码：** 249 250以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 251 252| 错误码ID | 错误信息 | 253| -------- | ------------------------------------------------------------ | 254| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 255 256**示例：** 257 258```ts 259import { On, ON } from '@kit.TestKit'; 260let on:On = ON.text('123'); // 使用静态构造器ON创建On对象，指定目标控件的text属性。 261``` 262 263### id<sup>9+</sup> 264 265id(id: string): On 266 267指定目标控件id属性，返回On对象自身。 268 269**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 270 271**系统能力**：SystemCapability.Test.UiTest 272 273**参数：** 274 275| 参数名 | 类型 | 必填 | 说明 | 276| ------ | ------ | ---- | ---------------- | 277| id | string | 是 | 指定控件的id值。<!--RP2--><!--RP2End--> | 278 279**返回值：** 280 281| 类型 | 说明 | 282| ---------- | -------------------------------- | 283| [On](#on9) | 返回指定目标控件id属性的On对象。 | 284 285**错误码：** 286 287以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 288 289| 错误码ID | 错误信息 | 290| -------- | ------------------------------------------------------------ | 291| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 292 293**示例：** 294 295```ts 296import { On, ON } from '@kit.TestKit'; 297 298let on:On = ON.id('123'); // 使用静态构造器ON创建On对象，指定目标控件的id属性。 299``` 300 301### id<sup>18+</sup> 302 303id(id: string, pattern: MatchPattern): On 304 305指定目标控件id属性，返回On对象自身。 306 307**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 308 309**系统能力**：SystemCapability.Test.UiTest 310 311**参数：** 312 313| 参数名 | 类型 | 必填 | 说明 | 314|-----------------------| ------ |----|---------------------------------------| 315| id | string | 是 | 指定控件的id值。<!--RP2--><!--RP2End--> | 316| pattern | [MatchPattern](#matchpattern) | 是 | 指定的文本匹配模式。 | 317 318**返回值：** 319 320| 类型 | 说明 | 321| ---------- | -------------------------------- | 322| [On](#on9) | 返回指定目标控件id属性的On对象。 | 323 324**错误码：** 325 326以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 327 328| 错误码ID | 错误信息 | 329| -------- | ------------------------------------------------------------ | 330| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 331 332**示例：** 333 334```ts 335import { MatchPattern, On, ON } from '@kit.TestKit'; 336 337let on:On = ON.id('id', MatchPattern.REG_EXP_ICASE); // 忽略大小写匹配控件的id属性值 338``` 339 340### type<sup>9+</sup> 341 342type(tp: string): On 343 344指定目标控件的控件类型属性，返回On对象自身。 345 346**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 347 348**系统能力**：SystemCapability.Test.UiTest 349 350**参数：** 351 352| 参数名 | 类型 | 必填 | 说明 | 353| ------ | ------ | ---- | -------------- | 354| tp | string | 是 | 指定控件类型。<!--RP2--><!--RP2End--> | 355 356**返回值：** 357 358| 类型 | 说明 | 359| ---------- | ---------------------------------------- | 360| [On](#on9) | 返回指定目标控件的控件类型属性的On对象。 | 361 362**错误码：** 363 364以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 365 366| 错误码ID | 错误信息 | 367| -------- | ------------------------------------------------------------ | 368| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 369 370**示例：** 371 372```ts 373import { On, ON } from '@kit.TestKit'; 374let on:On = ON.type('Button'); // 使用静态构造器ON创建On对象，指定目标控件的控件类型属性。 375``` 376 377### type<sup>18+</sup> 378 379type(tp: string, pattern: MatchPattern): On 380 381指定目标控件的控件类型属性，返回On对象自身。 382 383**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 384 385**系统能力**：SystemCapability.Test.UiTest 386 387**参数：** 388 389| 参数名 | 类型 | 必填 | 说明 | 390|-----------------------| ------ |----|---------------------------------------| 391| tp | string | 是 | 指定控件类型。<!--RP2--><!--RP2End--> | 392| pattern | [MatchPattern](#matchpattern) | 是 | 指定的文本匹配模式。 | 393 394**返回值：** 395 396| 类型 | 说明 | 397| ---------- | ---------------------------------------- | 398| [On](#on9) | 返回指定目标控件的控件类型属性的On对象。 | 399 400**错误码：** 401 402以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 403 404| 错误码ID | 错误信息 | 405| -------- | ------------------------------------------------------------ | 406| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 407 408**示例：** 409 410```ts 411import { On, ON, MatchPattern } from '@kit.TestKit'; 412let on:On = ON.type('Button', MatchPattern.EQUALS); // 使用静态构造器ON创建On对象，指定目标控件的控件类型属性。 413``` 414 415### clickable<sup>9+</sup> 416 417clickable(b?: boolean): On 418 419指定目标控件的可点击状态属性，返回On对象自身。 420 421**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 422 423**系统能力**：SystemCapability.Test.UiTest 424 425**参数：** 426 427| 参数名 | 类型 | 必填 | 说明 | 428| ------ | ------- | ---- | ------------------------------------------------------------ | 429| b | boolean | 否 | 指定控件可点击状态。true：可点击。false：不可点击。默认为true。<!--RP2--><!--RP2End--> | 430 431**返回值：** 432 433| 类型 | 说明 | 434| ---------- | ------------------------------------------ | 435| [On](#on9) | 返回指定目标控件的可点击状态属性的On对象。 | 436 437**错误码：** 438 439以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 440 441| 错误码ID | 错误信息 | 442| -------- | ------------------------------------------------------------ | 443| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 444 445**示例：** 446 447```ts 448import { On, ON } from '@kit.TestKit'; 449let on:On = ON.clickable(true); // 使用静态构造器ON创建On对象，指定目标控件的可点击状态属性。 450``` 451 452### longClickable<sup>9+</sup> 453 454longClickable(b?: boolean): On 455 456指定目标控件的可长按点击状态属性，返回On对象自身。 457 458**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 459 460**系统能力**：SystemCapability.Test.UiTest 461 462**参数：** 463 464| 参数名 | 类型 | 必填 | 说明 | 465| ------ | ------- | ---- | ------------------------------------------------------------ | 466| b | boolean | 否 | 指定控件可长按点击状态。true：可长按点击。false：不可长按点击。默认为true。<!--RP2--><!--RP2End--> | 467 468**返回值：** 469 470| 类型 | 说明 | 471| ---------- | ---------------------------------------------- | 472| [On](#on9) | 返回指定目标控件的可长按点击状态属性的On对象。 | 473 474**错误码：** 475 476以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 477 478| 错误码ID | 错误信息 | 479| -------- | ------------------------------------------------------------ | 480| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 481 482**示例：** 483 484```ts 485import { On, ON } from '@kit.TestKit'; 486let on:On = ON.longClickable(true); // 使用静态构造器ON创建On对象，指定目标控件的可长按点击状态属性。 487``` 488 489### scrollable<sup>9+</sup> 490 491scrollable(b?: boolean): On 492 493指定目标控件的可滑动状态属性，返回On对象自身。 494 495**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 496 497**系统能力**：SystemCapability.Test.UiTest 498 499**参数：** 500 501| 参数名 | 类型 | 必填 | 说明 | 502| ------ | ------- | ---- | ----------------------------------------------------------- | 503| b | boolean | 否 | 控件可滑动状态。true：可滑动。false：不可滑动。默认为true。<!--RP2--><!--RP2End--> | 504 505**返回值：** 506 507| 类型 | 说明 | 508| ---------- | ------------------------------------------ | 509| [On](#on9) | 返回指定目标控件的可滑动状态属性的On对象。 | 510 511**错误码：** 512 513以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 514 515| 错误码ID | 错误信息 | 516| -------- | ------------------------------------------------------------ | 517| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 518 519**示例：** 520 521```ts 522import { On, ON } from '@kit.TestKit'; 523let on:On = ON.scrollable(true); // 使用静态构造器ON创建On对象，指定目标控件的可滑动状态属性。 524``` 525 526### enabled<sup>9+</sup> 527 528enabled(b?: boolean): On 529 530指定目标控件的使能状态属性，返回On对象自身。 531 532**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 533 534**系统能力**：SystemCapability.Test.UiTest 535 536**参数：** 537 538| 参数名 | 类型 | 必填 | 说明 | 539| ------ | ------- | ---- | --------------------------------------------------------- | 540| b | boolean | 否 | 指定控件使能状态。true：使能。false：未使能。默认为true。<!--RP2--><!--RP2End--> | 541 542**返回值：** 543 544| 类型 | 说明 | 545| ---------- | ---------------------------------------- | 546| [On](#on9) | 返回指定目标控件的使能状态属性的On对象。 | 547 548**错误码：** 549 550以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 551 552| 错误码ID | 错误信息 | 553| -------- | ------------------------------------------------------------ | 554| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 555 556**示例：** 557 558```ts 559import { On, ON } from '@kit.TestKit'; 560let on:On = ON.enabled(true); // 使用静态构造器ON创建On对象，指定目标控件的使能状态属性。 561``` 562 563### focused<sup>9+</sup> 564 565focused(b?: boolean): On 566 567指定目标控件的获焦状态属性，返回On对象自身。 568 569**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 570 571**系统能力**：SystemCapability.Test.UiTest 572 573**参数：** 574 575| 参数名 | 类型 | 必填 | 说明 | 576| ------ | ------- | ---- | ----------------------------------------------------- | 577| b | boolean | 否 | 控件获焦状态。true：获焦。false：未获焦。默认为true。<!--RP2--><!--RP2End--> | 578 579**返回值：** 580 581| 类型 | 说明 | 582| ---------- | ---------------------------------------- | 583| [On](#on9) | 返回指定目标控件的获焦状态属性的On对象。 | 584 585**错误码：** 586 587以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 588 589| 错误码ID | 错误信息 | 590| -------- | ------------------------------------------------------------ | 591| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 592 593**示例：** 594 595```ts 596import { On, ON } from '@kit.TestKit'; 597let on:On = ON.focused(true); // 使用静态构造器ON创建On对象，指定目标控件的获焦状态属性。 598``` 599 600### selected<sup>9+</sup> 601 602selected(b?: boolean): On 603 604指定目标控件的被选中状态属性，返回On对象自身。 605 606**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 607 608**系统能力**：SystemCapability.Test.UiTest 609 610**参数：** 611 612| 参数名 | 类型 | 必填 | 说明 | 613| ------ | ------- | ---- | ------------------------------------------------------------ | 614| b | boolean | 否 | 指定控件被选中状态。true：被选中。false：未被选中。默认为true。<!--RP2--><!--RP2End--> | 615 616**返回值：** 617 618| 类型 | 说明 | 619| ---------- | ------------------------------------------ | 620| [On](#on9) | 返回指定目标控件的被选中状态属性的On对象。 | 621 622**错误码：** 623 624以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 625 626| 错误码ID | 错误信息 | 627| -------- | ------------------------------------------------------------ | 628| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 629 630**示例：** 631 632```ts 633import { On, ON } from '@kit.TestKit'; 634let on:On = ON.selected(true); // 使用静态构造器ON创建On对象，指定目标控件的被选中状态属性。 635``` 636 637### checked<sup>9+</sup> 638 639checked(b?: boolean): On 640 641指定目标控件的被勾选状态属性，返回On对象自身。 642 643**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 644 645**系统能力**：SystemCapability.Test.UiTest 646 647**参数：** 648 649| 参数名 | 类型 | 必填 | 说明 | 650| ------ | ------- | ---- | ------------------------------------------------------------ | 651| b | boolean | 否 | 指定控件被勾选状态。true：被勾选。false：未被勾选。默认为true。<!--RP2--><!--RP2End--> | 652 653**返回值：** 654 655| 类型 | 说明 | 656| ---------- | ------------------------------------------ | 657| [On](#on9) | 返回指定目标控件的被勾选状态属性的On对象。 | 658 659**错误码：** 660 661以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 662 663| 错误码ID | 错误信息 | 664| -------- | ------------------------------------------------------------ | 665| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 666 667**示例：** 668 669```ts 670import { On, ON } from '@kit.TestKit'; 671let on:On = ON.checked(true); // 使用静态构造器ON创建On对象，指定目标控件的被勾选状态属性 672``` 673 674### checkable<sup>9+</sup> 675 676checkable(b?: boolean): On 677 678指定目标控件能否被勾选状态属性，返回On对象自身。 679 680**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 681 682**系统能力**：SystemCapability.Test.UiTest 683 684**参数：** 685 686| 参数名 | 类型 | 必填 | 说明 | 687| ------ | ------- | ---- | ------------------------------------------------------------ | 688| b | boolean | 否 | 指定控件能否被勾选状态。true：能被勾选。false：不能被勾选。默认为true。<!--RP2--><!--RP2End--> | 689 690**返回值：** 691 692| 类型 | 说明 | 693| ---------- | -------------------------------------------- | 694| [On](#on9) | 返回指定目标控件能否被勾选状态属性的On对象。 | 695 696**错误码：** 697 698以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 699 700| 错误码ID | 错误信息 | 701| -------- | ------------------------------------------------------------ | 702| 401 | Parameter error. 1. Incorrect parameter types; 2. Parameter verification failed. | 703 704**示例：** 705 706```ts 707import { On, ON } from '@kit.TestKit'; 708let on:On = ON.checkable(true); // 使用静态构造器ON创建On对象，指定目标控件的能否被勾选状态属性。 709``` 710 711### isBefore<sup>9+</sup> 712 713isBefore(on: On): On 714 715指定目标控件位于给出的特征属性控件之前，返回On对象自身。 716 717**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 718 719**系统能力**：SystemCapability.Test.UiTest 720 721**参数：** 722 723| 参数名 | 类型 | 必填 | 说明 | 724| ------ | ---------- | ---- | -------------------- | 725| on | [On](#on9) | 是 | 特征控件的属性要求。 <!--RP3--><!--RP3End--> | 726 727**返回值：** 728 729| 类型 | 说明 | 730| ---------- | ---------------------------------------------------- | 731| [On](#on9) | 返回指定目标控件位于给出的特征属性控件之前的On对象。| 732 733**错误码：** 734 735以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 736 737| 错误码ID | 错误信息 | 738| -------- | ------------------------------------------------------------ | 739| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 740 741**示例：** 742 743```ts 744import { On, ON } from '@kit.TestKit'; 745 746// 使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之前。 747let on:On = ON.type('Button').isBefore(ON.text('123')); // 查找text为123之前的第一个Button组件 748``` 749 750### isAfter<sup>9+</sup> 751 752isAfter(on: On): On 753 754指定目标控件位于给出的特征属性控件之后，返回On对象自身。 755 756**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 757 758**系统能力**：SystemCapability.Test.UiTest 759 760**参数：** 761 762| 参数名 | 类型 | 必填 | 说明 | 763| ------ | ---------- | ---- | -------------------- | 764| on | [On](#on9) | 是 | 特征控件的属性要求。 <!--RP3--><!--RP3End--> | 765 766**返回值：** 767 768| 类型 | 说明 | 769| ---------- | ---------------------------------------------------- | 770| [On](#on9) | 返回指定目标控件位于给出的特征属性控件之后的On对象。 | 771 772**错误码：** 773 774以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 775 776| 错误码ID | 错误信息 | 777| -------- | ------------------------------------------------------------ | 778| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 779 780**示例：** 781 782```ts 783import { On, ON } from '@kit.TestKit'; 784 785// 使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之后。 786let on:On = ON.type('Text').isAfter(ON.text('123')); // 查找 text为123之后的第一个Text组件 787``` 788 789### within<sup>10+</sup> 790 791within(on: On): On 792 793指定目标控件位于给出的特征属性控件之内，返回On对象自身。 794 795**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 796 797**系统能力**：SystemCapability.Test.UiTest 798 799**参数：** 800 801| 参数名 | 类型 | 必填 | 说明 | 802| ------ | ---------- | ---- | -------------------- | 803| on | [On](#on9) | 是 | 特征控件的属性要求。<!--RP3--><!--RP3End--> | 804 805**返回值：** 806 807| 类型 | 说明 | 808| ---------- | -------------------------------------------------- | 809| [On](#on9) | 返回指定目标控件位于给出的特征属性控件内的On对象。 | 810 811**错误码：** 812 813以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 814 815| 错误码ID | 错误信息 | 816| -------- | ------------------------------------------------------------ | 817| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 818 819**示例：** 820 821```ts 822import { On, ON } from '@kit.TestKit'; 823// 使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之内。 824let on:On = ON.text('java').within(ON.type('Scroll')); // 查找Scroller里面的text为java的子组件 825``` 826 827### inWindow<sup>10+</sup> 828 829inWindow(bundleName: string): On 830 831指定目标控件位于给出的应用窗口内，返回On对象自身。 832 833**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 834 835**系统能力**：SystemCapability.Test.UiTest 836 837**参数：** 838 839| 参数名 | 类型 | 必填 | 说明 | 840| ---------- | ------ | ---- | ---------------- | 841| bundleName | string | 是 | 应用窗口的包名。<!--RP2--><!--RP2End--> | 842 843**返回值：** 844 845| 类型 | 说明 | 846| ---------- | ---------------------------------------------- | 847| [On](#on9) | 返回指定目标控件位于给出的应用窗口内的On对象。 | 848 849**错误码：** 850 851以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 852 853| 错误码ID | 错误信息 | 854| -------- | ------------------------------------------------------------ | 855| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 856 857**示例：** 858 859```ts 860import { On, ON } from '@kit.TestKit'; 861let on:On = ON.inWindow('com.uitestScene.acts'); // 使用静态构造器ON创建On对象，指定目标控件位于给出的应用窗口内。 862``` 863 864### description<sup>11+</sup> 865 866description(val: string, pattern?: MatchPattern): On 867 868指定目标控件的描述属性，支持多种匹配模式，返回On对象自身。 869 870**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 871 872**系统能力**：SystemCapability.Test.UiTest 873 874**参数：** 875 876| 参数名 | 类型 | 必填 | 说明 | 877| ------- | ----------------------------- | ---- | --------------------------------------------------- | 878| val | string | 是 | 控件的描述属性。 <!--RP2--><!--RP2End--> | 879| pattern | [MatchPattern](#matchpattern) | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 | 880 881**返回值：** 882 883| 类型 | 说明 | 884| ---------- | ----------------------------------------- | 885| [On](#on9) | 返回指定目标控件description属性的On对象。 | 886 887**错误码：** 888 889以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 890 891| 错误码ID | 错误信息 | 892| -------- | ------------------------------------------------------------ | 893| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 894 895**示例：** 896 897```ts 898import { On, ON } from '@kit.TestKit'; 899let on:On = ON.description('123'); // 使用静态构造器ON创建On对象，指定目标控件的description属性。 900``` 901 902### hint<sup>18+</sup> 903 904hint(val: string, pattern?: MatchPattern): On 905 906获取指定提示文本的控件对象，返回On对象自身。 907 908**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 909 910**系统能力**：SystemCapability.Test.UiTest 911 912**参数：** 913 914| 参数名 | 类型 | 必填 | 说明 | 915| ------ | ------ |----|---------------------------------------| 916| val | string | 是 | 指定控件提示文本。 <!--RP2--><!--RP2End--> | 917| pattern | [MatchPattern](#matchpattern) | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 | 918 919**返回值：** 920 921| 类型 | 说明 | 922| ---------- | ---------------------------------------- | 923| [On](#on9) | 返回指定提示文本控件的On对象。 | 924 925**错误码：** 926 927以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 928 929| 错误码ID | 错误信息 | 930| -------- | ------------------------------------------------------------ | 931| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 932 933**示例：** 934 935```ts 936 import { MatchPattern, On, ON } from '@kit.TestKit'; 937 938 let on:On = ON.hint('welcome', MatchPattern.EQUALS); // 使用静态构造器ON创建On对象，指定目标控件的提示文本属性。 939``` 940 941### belongingDisplay<sup>20+</sup> 942 943belongingDisplay(displayId: number): On 944 945获取指定屏幕内的控件对象，返回On对象自身。 946 947**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 948 949**系统能力**：SystemCapability.Test.UiTest 950 951**参数：** 952 953| 参数名 | 类型 | 必填 | 说明 | 954| ------ | ------ |----|---------------------------------------| 955| displayId | number | 是 | 指定控件所属屏幕ID，取值范围：大于等于0的整数。<br> **说明：** 传入displayId不存在时，将抛出17000007异常。可通过[getAllDisplays](../apis-arkui/js-apis-display.md#displaygetalldisplays9)获取当前所有的display对象，并由display对象获取对应的屏幕ID。<!--RP2--><!--RP2End--> | 956 957**返回值：** 958 959| 类型 | 说明 | 960| ---------- | ---------------------------------------- | 961| [On](#on9) | 返回指定控件所属屏幕的On对象。 | 962 963**错误码：** 964 965以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 966 967| 错误码ID | 错误信息 | 968| -------- | ------------------------------------------------------------ | 969| 17000007 | Parameter verification failed.| 970 971**示例：** 972 973```ts 974 import { On, ON } from '@kit.TestKit'; 975 976 let on:On = ON.belongingDisplay(0); // 使用静态构造器ON创建On对象，指定目标控件所属屏幕ID 977``` 978 979### originalText<sup>20+</sup> 980 981originalText(text: string, pattern?: MatchPattern): On 982 983指定目标控件的文本属性，支持多种匹配模式，返回On对象自身。 984 985> **说明** 986> 987> 如果控件的无障碍属性[accessibilityLevel](../apis-arkui/arkui-ts/ts-universal-attributes-accessibility.md#accessibilitylevel)设置为'no'或'no-hide-descendants'，可以使用本接口指定目标控件的文本属性用于查找控件，使用[On.text()](#text9)接口不生效。 988 989**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 990 991**系统能力**：SystemCapability.Test.UiTest 992 993**参数：** 994 995| 参数名 | 类型 | 必填 | 说明 | 996| ------- | ----------------------------- | ---- | --------------------------------------------------- | 997| text | string | 是 | 指定控件文本，用于匹配目标控件文本。 <!--RP2--><!--RP2End--> | 998| pattern | [MatchPattern](#matchpattern) | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 | 999 1000**返回值：** 1001 1002| 类型 | 说明 | 1003| ---------- | ---------------------------------- | 1004| [On](#on9) | 返回指定目标控件文本属性的On对象。 | 1005 1006**错误码：** 1007 1008以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1009 1010| 错误码ID | 错误信息 | 1011| -------- | ------------------------------------------------------------ | 1012| 17000007 | Parameter verification failed.| 1013 1014**示例：** 1015 1016```ts 1017import { On, ON } from '@kit.TestKit'; 1018 1019let on:On = ON.originalText('123'); // 使用静态构造器ON创建On对象，指定目标控件的originalText属性 1020``` 1021 1022## Component<sup>9+</sup> 1023 1024UiTest框架在API9中，Component类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。 1025该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。 1026 1027### click<sup>9+</sup> 1028 1029click(): Promise\<void> 1030 1031控件对象进行点击操作，使用Promise异步回调。 1032 1033**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1034 1035**系统能力**：SystemCapability.Test.UiTest 1036 1037**返回值：** 1038 1039| 类型 | 说明 | 1040|----------------|-----------------| 1041| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1042 1043**错误码：** 1044 1045以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1046 1047| 错误码ID | 错误信息 | 1048| -------- | ---------------------------------------- | 1049| 17000002 | The async function is not called with await. | 1050| 17000004 | The window or component is invisible or destroyed. | 1051 1052**示例：** 1053 1054```ts 1055import { Driver, ON, Component } from '@kit.TestKit'; 1056async function demo() { 1057 let driver:Driver = Driver.create(); 1058 let button: Component = await driver.findComponent(ON.type('Button')); 1059 await button.click(); 1060} 1061``` 1062 1063### doubleClick<sup>9+</sup> 1064 1065doubleClick(): Promise\<void> 1066 1067控件对象进行双击操作，使用Promise异步回调。 1068 1069**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1070 1071**系统能力**：SystemCapability.Test.UiTest 1072 1073**返回值：** 1074 1075| 类型 | 说明 | 1076|----------------|-----------------| 1077| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1078 1079**错误码：** 1080 1081以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1082 1083| 错误码ID | 错误信息 | 1084| -------- | ---------------------------------------- | 1085| 17000002 | The async function is not called with await. | 1086| 17000004 | The window or component is invisible or destroyed. | 1087 1088**示例：** 1089 1090```ts 1091import {Component, Driver, ON } from '@kit.TestKit'; 1092async function demo() { 1093 let driver: Driver = Driver.create(); 1094 let button: Component = await driver.findComponent(ON.type('Button')); 1095 await button.doubleClick(); 1096} 1097``` 1098 1099### longClick<sup>9+</sup> 1100 1101longClick(): Promise\<void> 1102 1103控件对象进行长按操作，使用Promise异步回调。 1104 1105**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1106 1107**系统能力**：SystemCapability.Test.UiTest 1108 1109**返回值：** 1110 1111| 类型 | 说明 | 1112|----------------|-----------------| 1113| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1114 1115**错误码：** 1116 1117以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1118 1119| 错误码ID | 错误信息 | 1120| -------- | ---------------------------------------- | 1121| 17000002 | The async function is not called with await. | 1122| 17000004 | The window or component is invisible or destroyed. | 1123 1124**示例：** 1125 1126```ts 1127import { Component, Driver, ON } from '@kit.TestKit'; 1128async function demo() { 1129 let driver: Driver = Driver.create(); 1130 let button: Component = await driver.findComponent(ON.type('Button')); 1131 await button.longClick(); 1132} 1133``` 1134 1135### getId<sup>9+</sup> 1136 1137getId(): Promise\<string> 1138 1139获取控件对象的id值，使用Promise异步回调。 1140 1141**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1142 1143**系统能力**：SystemCapability.Test.UiTest 1144 1145**返回值：** 1146 1147| 类型 | 说明 | 1148| ---------------- | ------------------------------- | 1149| Promise\<string> | Promise对象，返回控件的id值。 | 1150 1151**错误码：** 1152 1153以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1154 1155| 错误码ID | 错误信息 | 1156| -------- | ---------------------------------------- | 1157| 17000002 | The async function is not called with await. | 1158| 17000004 | The window or component is invisible or destroyed. | 1159 1160**示例：** 1161 1162```ts 1163import { Component, Driver, ON } from '@kit.TestKit'; 1164async function demo() { 1165 let driver: Driver = Driver.create(); 1166 let button: Component = await driver.findComponent(ON.type('Button')); 1167 let id = await button.getId(); 1168} 1169``` 1170 1171### getText<sup>9+</sup> 1172 1173getText(): Promise\<string> 1174 1175获取控件对象的文本信息，使用Promise异步回调。 1176 1177> **说明** 1178> 1179> 如果控件的无障碍属性[accessibilityLevel](../apis-arkui/arkui-ts/ts-universal-attributes-accessibility.md#accessibilitylevel)设置为'no'或'no-hide-descendants'，无法使用本接口获取控件的文本信息，可以使用[Component.getOriginalText()](#getoriginaltext20)获取控件的文本信息。 1180 1181**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1182 1183**系统能力**：SystemCapability.Test.UiTest 1184 1185**返回值：** 1186 1187| 类型 | 说明 | 1188| ---------------- | --------------------------------- | 1189| Promise\<string> | Promise对象，返回控件的文本信息。 | 1190 1191**错误码：** 1192 1193以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1194 1195| 错误码ID | 错误信息 | 1196| -------- | ---------------------------------------- | 1197| 17000002 | The async function is not called with await. | 1198| 17000004 | The window or component is invisible or destroyed. | 1199 1200**示例：** 1201 1202```ts 1203import { Component, Driver, ON } from '@kit.TestKit'; 1204async function demo() { 1205 let driver: Driver = Driver.create(); 1206 let button: Component = await driver.findComponent(ON.type('Button')); 1207 let text = await button.getText(); 1208} 1209``` 1210 1211### getType<sup>9+</sup> 1212 1213getType(): Promise\<string> 1214 1215获取控件对象的控件类型，使用Promise异步回调。 1216 1217**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1218 1219**系统能力**：SystemCapability.Test.UiTest 1220 1221**返回值：** 1222 1223| 类型 | 说明 | 1224| ---------------- | ----------------------------- | 1225| Promise\<string> | Promise对象，返回控件的类型。 | 1226 1227**错误码：** 1228 1229以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1230 1231| 错误码ID | 错误信息 | 1232| -------- | ---------------------------------------- | 1233| 17000002 | The async function is not called with await. | 1234| 17000004 | The window or component is invisible or destroyed. | 1235 1236**示例：** 1237 1238```ts 1239import { Component, Driver, ON } from '@kit.TestKit'; 1240async function demo() { 1241 let driver: Driver = Driver.create(); 1242 let button: Component = await driver.findComponent(ON.type('Button')); 1243 let type = await button.getType(); 1244} 1245``` 1246 1247### getBounds<sup>9+</sup> 1248 1249getBounds(): Promise\<Rect> 1250 1251获取控件对象的边框信息，使用Promise异步回调。 1252 1253**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1254 1255**系统能力**：SystemCapability.Test.UiTest 1256 1257**返回值：** 1258 1259| 类型 | 说明 | 1260| ------------------------ | ------------------------------------- | 1261| Promise\<[Rect](#rect9)> | Promise对象，返回控件对象的边框信息。 | 1262 1263**错误码：** 1264 1265以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1266 1267| 错误码ID | 错误信息 | 1268| -------- | ---------------------------------------- | 1269| 17000002 | The async function is not called with await. | 1270| 17000004 | The window or component is invisible or destroyed. | 1271 1272**示例：** 1273 1274```ts 1275import { Component, Driver, ON } from '@kit.TestKit'; 1276async function demo() { 1277 let driver: Driver = Driver.create(); 1278 let button: Component = await driver.findComponent(ON.type('Button')); 1279 let rect = await button.getBounds(); 1280} 1281``` 1282 1283### getBoundsCenter<sup>9+</sup> 1284 1285getBoundsCenter(): Promise\<Point> 1286 1287获取控件对象所占区域的中心点信息，使用Promise异步回调。 1288 1289**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1290 1291**系统能力**：SystemCapability.Test.UiTest 1292 1293**返回值：** 1294 1295| 类型 | 说明 | 1296| -------------------------- | ----------------------------------------------- | 1297| Promise\<[Point](#point9)> | Promise对象，返回控件对象所占区域的中心点信息。 | 1298 1299**错误码：** 1300 1301以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1302 1303| 错误码ID | 错误信息 | 1304| -------- | ---------------------------------------- | 1305| 17000002 | The async function is not called with await. | 1306| 17000004 | The window or component is invisible or destroyed. | 1307 1308**示例：** 1309 1310```ts 1311import { Component, Driver, ON } from '@kit.TestKit'; 1312async function demo() { 1313 let driver: Driver = Driver.create(); 1314 let button: Component = await driver.findComponent(ON.type('Button')); 1315 let point = await button.getBoundsCenter(); 1316} 1317``` 1318 1319### isClickable<sup>9+</sup> 1320 1321isClickable(): Promise\<boolean> 1322 1323获取控件对象可点击属性，使用Promise异步回调。 1324 1325**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1326 1327**系统能力**：SystemCapability.Test.UiTest 1328 1329**返回值：** 1330 1331| 类型 | 说明 | 1332| ----------------- | ------------------------------------------------------------ | 1333| Promise\<boolean> | Promise对象，返回控件对象是否可点击。true：可点击。false：不可点击。 | 1334 1335**错误码：** 1336 1337以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1338 1339| 错误码ID | 错误信息 | 1340| -------- | ---------------------------------------- | 1341| 17000002 | The async function is not called with await. | 1342| 17000004 | The window or component is invisible or destroyed. | 1343 1344**示例：** 1345 1346```ts 1347import { Component, Driver, ON } from '@kit.TestKit'; 1348async function demo() { 1349 let driver: Driver = Driver.create(); 1350 let button: Component = await driver.findComponent(ON.type('Button')); 1351 if(await button.isClickable()) { 1352 console.info('This button can be Clicked'); 1353 } else { 1354 console.info('This button can not be Clicked'); 1355 } 1356} 1357``` 1358 1359### isLongClickable<sup>9+</sup> 1360 1361isLongClickable(): Promise\<boolean> 1362 1363获取控件对象可长按点击属性，使用Promise异步回调。 1364 1365**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1366 1367**系统能力**：SystemCapability.Test.UiTest 1368 1369**返回值：** 1370 1371| 类型 | 说明 | 1372| ----------------- |--------------------------------------------------| 1373| Promise\<boolean> | Promise对象，返回控件对象是否可长按点击。true：可长按点击。false：不可长按点击。 | 1374 1375**错误码：** 1376 1377以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1378 1379| 错误码ID | 错误信息 | 1380| -------- | ---------------------------------------- | 1381| 17000002 | The async function is not called with await. | 1382| 17000004 | The window or component is invisible or destroyed. | 1383 1384**示例：** 1385 1386```ts 1387import { Component, Driver, ON } from '@kit.TestKit'; 1388async function demo() { 1389 let driver: Driver = Driver.create(); 1390 let button: Component = await driver.findComponent(ON.type('Button')); 1391 if(await button.isLongClickable()) { 1392 console.info('This button can longClick'); 1393 } else { 1394 console.info('This button can not longClick'); 1395 } 1396} 1397``` 1398 1399### isChecked<sup>9+</sup> 1400 1401isChecked(): Promise\<boolean> 1402 1403获取控件对象被勾选状态，使用Promise异步回调。 1404 1405**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1406 1407**系统能力**：SystemCapability.Test.UiTest 1408 1409**返回值：** 1410 1411| 类型 | 说明 | 1412| ----------------- | ------------------------------------------------------------ | 1413| Promise\<boolean> | Promise对象，返回控件对象被勾选状态。true：被勾选。false：未被勾选。 | 1414 1415**错误码：** 1416 1417以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1418 1419| 错误码ID | 错误信息 | 1420| -------- | ---------------------------------------- | 1421| 17000002 | The async function is not called with await. | 1422| 17000004 | The window or component is invisible or destroyed. | 1423 1424**示例：** 1425 1426```ts 1427import { Component, Driver, ON } from '@kit.TestKit'; 1428async function demo() { 1429 let driver: Driver = Driver.create(); 1430 let checkBox: Component = await driver.findComponent(ON.type('Checkbox')); 1431 if(await checkBox.isChecked()) { 1432 console.info('This checkBox is checked'); 1433 } else { 1434 console.info('This checkBox is not checked'); 1435 } 1436} 1437``` 1438 1439### isCheckable<sup>9+</sup> 1440 1441isCheckable(): Promise\<boolean> 1442 1443获取控件对象能否被勾选属性，使用Promise异步回调。 1444 1445**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1446 1447**系统能力**：SystemCapability.Test.UiTest 1448 1449**返回值：** 1450 1451| 类型 | 说明 | 1452| ----------------- | ------------------------------------------------------------ | 1453| Promise\<boolean> | Promise对象，返回控件对象能否可被勾选属性。true：可被勾选。false：不可被勾选。 | 1454 1455**错误码：** 1456 1457以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1458 1459| 错误码ID | 错误信息 | 1460| -------- | ---------------------------------------- | 1461| 17000002 | The async function is not called with await. | 1462| 17000004 | The window or component is invisible or destroyed. | 1463 1464**示例：** 1465 1466```ts 1467import { Component, Driver, ON } from '@kit.TestKit'; 1468async function demo() { 1469 let driver: Driver = Driver.create(); 1470 let checkBox: Component = await driver.findComponent(ON.type('Checkbox')); 1471 if(await checkBox.isCheckable()) { 1472 console.info('This checkBox is checkable'); 1473 } else { 1474 console.info('This checkBox is not checkable'); 1475 } 1476} 1477``` 1478 1479### isScrollable<sup>9+</sup> 1480 1481isScrollable(): Promise\<boolean> 1482 1483获取控件对象可滑动属性，使用Promise异步回调。 1484 1485**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1486 1487**系统能力**：SystemCapability.Test.UiTest 1488 1489**返回值：** 1490 1491| 类型 | 说明 | 1492| ----------------- | ------------------------------------------------------------ | 1493| Promise\<boolean> | Promise对象，返回控件对象是否可滑动。true：可滑动。false：不可滑动。 | 1494 1495**错误码：** 1496 1497以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1498 1499| 错误码ID | 错误信息 | 1500| -------- | ---------------------------------------- | 1501| 17000002 | The async function is not called with await. | 1502| 17000004 | The window or component is invisible or destroyed. | 1503 1504**示例：** 1505 1506```ts 1507import { Component, Driver, ON } from '@kit.TestKit'; 1508async function demo() { 1509 let driver: Driver = Driver.create(); 1510 let scrollBar: Component = await driver.findComponent(ON.scrollable(true)); 1511 if(await scrollBar.isScrollable()) { 1512 console.info('This scrollBar can be operated'); 1513 } else { 1514 console.info('This scrollBar can not be operated'); 1515 } 1516} 1517``` 1518 1519 1520### isEnabled<sup>9+</sup> 1521 1522isEnabled(): Promise\<boolean> 1523 1524获取控件使能状态，使用Promise异步回调。 1525 1526**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1527 1528**系统能力**：SystemCapability.Test.UiTest 1529 1530**返回值：** 1531 1532| 类型 | 说明 | 1533| ----------------- | ---------------------------------------------------------- | 1534| Promise\<boolean> | Promise对象，返回控件使能状态。true：使能。false：未使能。 | 1535 1536**错误码：** 1537 1538以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1539 1540| 错误码ID | 错误信息 | 1541| -------- | ---------------------------------------- | 1542| 17000002 | The async function is not called with await. | 1543| 17000004 | The window or component is invisible or destroyed. | 1544 1545**示例：** 1546 1547```ts 1548import { Component, Driver, ON } from '@kit.TestKit'; 1549async function demo() { 1550 let driver: Driver = Driver.create(); 1551 let button: Component = await driver.findComponent(ON.type('Button')); 1552 if(await button.isEnabled()) { 1553 console.info('This button can be operated'); 1554 } else { 1555 console.info('This button can not be operated'); 1556 } 1557} 1558``` 1559 1560### isFocused<sup>9+</sup> 1561 1562isFocused(): Promise\<boolean> 1563 1564判断控件对象获焦状态，使用Promise异步回调。 1565 1566**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1567 1568**系统能力**：SystemCapability.Test.UiTest 1569 1570**返回值：** 1571 1572| 类型 | 说明 | 1573| ----------------- | ------------------------------------------------------------ | 1574| Promise\<boolean> | Promise对象，返回控件对象获焦状态。true：获焦。false：未获焦。 | 1575 1576**错误码：** 1577 1578以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1579 1580| 错误码ID | 错误信息 | 1581| -------- | ---------------------------------------- | 1582| 17000002 | The async function is not called with await. | 1583| 17000004 | The window or component is invisible or destroyed. | 1584 1585**示例：** 1586 1587```ts 1588import { Component, Driver, ON } from '@kit.TestKit'; 1589async function demo() { 1590 let driver: Driver = Driver.create(); 1591 let button: Component = await driver.findComponent(ON.type('Button')); 1592 if(await button.isFocused()) { 1593 console.info('This button is focused'); 1594 } else { 1595 console.info('This button is not focused'); 1596 } 1597} 1598``` 1599 1600### isSelected<sup>9+</sup> 1601 1602isSelected(): Promise\<boolean> 1603 1604获取控件对象被选中状态，使用Promise异步回调。 1605 1606**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1607 1608**系统能力**：SystemCapability.Test.UiTest 1609 1610**返回值：** 1611 1612| 类型 | 说明 | 1613| ----------------- | --------------------------------------------------- | 1614| Promise\<boolean> | Promise对象，返回控件对象被选中状态。true：被选中。false：未被选中。 | 1615 1616**错误码：** 1617 1618以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1619 1620| 错误码ID | 错误信息 | 1621| -------- | ---------------------------------------- | 1622| 17000002 | The async function is not called with await. | 1623| 17000004 | The window or component is invisible or destroyed. | 1624 1625**示例：** 1626 1627```ts 1628import { Component, Driver, ON } from '@kit.TestKit'; 1629async function demo() { 1630 let driver: Driver = Driver.create(); 1631 let button: Component = await driver.findComponent(ON.type('Button')); 1632 if(await button.isSelected()) { 1633 console.info('This button is selected'); 1634 } else { 1635 console.info('This button is not selected'); 1636 } 1637} 1638``` 1639 1640### inputText<sup>9+</sup> 1641 1642inputText(text: string): Promise\<void> 1643 1644清空组件内原有文本并输入指定文本内容，仅针对可编辑的文本组件生效，使用Promise异步回调。 1645 1646**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1647 1648**系统能力**：SystemCapability.Test.UiTest 1649 1650**返回值：** 1651 1652| 类型 | 说明 | 1653|----------------|-----------------| 1654| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1655 1656**参数：** 1657 1658| 参数名 | 类型 | 必填 | 说明 | 1659| ------ | ------ | ---- | ---------------------------------------- | 1660| text | string | 是 | 输入的文本信息，当前支持英文、中文和特殊字符。 | 1661 1662**错误码：** 1663 1664以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 1665 1666| 错误码ID | 错误信息 | 1667| -------- | ---------------------------------------- | 1668| 17000002 | The async function is not called with await. | 1669| 17000004 | The window or component is invisible or destroyed. | 1670| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1671 1672**示例：** 1673 1674```ts 1675import { Component, Driver, ON } from '@kit.TestKit'; 1676async function demo() { 1677 let driver: Driver = Driver.create(); 1678 let text: Component = await driver.findComponent(ON.text('hello world')); 1679 await text.inputText('123'); 1680} 1681``` 1682 1683### inputText<sup>20+</sup> 1684 1685inputText(text: string, mode: InputTextMode): Promise\<void> 1686 1687向控件中输入文本，并支持指定文本输入方式，仅针对可编辑的文本组件生效，使用Promise异步回调。 1688 1689**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1690 1691**系统能力**：SystemCapability.Test.UiTest 1692 1693**参数：** 1694 1695| 参数名 | 类型 | 必填 | 说明 | 1696| ------ | ------ | ---- | ---------------------------------------- | 1697| text | string | 是 | 输入的文本信息，当前支持英文、中文和特殊字符。 | 1698| mode | [InputTextMode](#inputtextmode20) | 是 | 输入文本的方式，取值请参考[InputTextMode](#inputtextmode20)。<br> **说明：** InputTextMode.addition取值为ture时，在控件已有文本末尾后追加指定文本。取值为false时，指定文本将覆盖控件已有文本。| 1699 1700**返回值：** 1701 1702| 类型 | 说明 | 1703|----------------|-----------------| 1704| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1705 1706**错误码：** 1707 1708以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 1709 1710| 错误码ID | 错误信息 | 1711| -------- | ---------------------------------------- | 1712| 17000002 | The async function is not called with await. | 1713| 17000004 | The window or component is invisible or destroyed. | 1714| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1715| 801 | Capability not supported, function can not work correctly due to limited device capabilities.| 1716 1717**示例：** 1718```ts 1719import { Component, Driver, ON } from '@kit.TestKit'; 1720 1721async function mode_demo() { 1722 let driver: Driver = Driver.create(); 1723 let text: Component = await driver.findComponent(ON.text('hello world')); 1724 await text.inputText('123', { paste: true, addition: false }); 1725} 1726``` 1727 1728 1729### clearText<sup>9+</sup> 1730 1731clearText(): Promise\<void> 1732 1733清除控件的文本信息，仅针对可编辑的文本组件生效，使用Promise异步回调。 1734 1735**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1736 1737**系统能力**：SystemCapability.Test.UiTest 1738 1739**返回值：** 1740 1741| 类型 | 说明 | 1742|----------------|-----------------| 1743| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1744 1745**错误码：** 1746以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 1747 1748| 错误码ID | 错误信息 | 1749| -------- | ---------------------------------------- | 1750| 17000002 | The async function is not called with await. | 1751| 17000004 | The window or component is invisible or destroyed. | 1752 1753**示例：** 1754 1755```ts 1756import { Component, Driver, ON } from '@kit.TestKit'; 1757async function demo() { 1758 let driver: Driver = Driver.create(); 1759 let text: Component = await driver.findComponent(ON.text('hello world')); 1760 await text.clearText(); 1761} 1762``` 1763 1764### scrollSearch<sup>9+</sup> 1765 1766scrollSearch(on: On): Promise\<Component> 1767 1768在控件上滑动查找目标控件（适用支持滑动的控件），使用Promise异步回调。 1769 1770**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1771 1772**系统能力**：SystemCapability.Test.UiTest 1773 1774**参数：** 1775 1776| 参数名 | 类型 | 必填 | 说明 | 1777| ------ | ---------- | ---- | -------------------- | 1778| on | [On](#on9) | 是 | 目标控件的属性要求。 | 1779 1780**返回值：** 1781 1782| 类型 | 说明 | 1783| ---------------------------------- | ------------------------------------- | 1784| Promise\<[Component](#component9)> | Promise对象，返回目标控件对象。 | 1785 1786**错误码：** 1787 1788以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 1789 1790| 错误码ID | 错误信息 | 1791| -------- | ---------------------------------------- | 1792| 17000002 | The async function is not called with await. | 1793| 17000004 | The window or component is invisible or destroyed. | 1794| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1795 1796**示例：** 1797 1798```ts 1799import { Component, Driver, ON } from '@kit.TestKit'; 1800 1801async function demo() { 1802 let driver: Driver = Driver.create(); 1803 let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); 1804 let button = await scrollBar.scrollSearch(ON.text('next page')); 1805} 1806``` 1807 1808### scrollSearch<sup>18+</sup> 1809 1810scrollSearch(on: On, vertical?: boolean, offset?: number): Promise\<Component> 1811 1812在控件上滑动查找目标控件（适用支持滑动的控件），使用Promise异步回调。 1813 1814**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1815 1816**系统能力**：SystemCapability.Test.UiTest 1817 1818**参数：** 1819 1820| 参数名 | 类型 | 必填 | 说明 | 1821|------------------------| ---------- | ---- |-----------------------------------| 1822| on | [On](#on9) | 是 | 目标控件的属性要求。 | 1823| vertical | boolean | 否 | 默认为true，表示查找方向是纵向。false表示查找方向为横向。 | 1824| offset | number| 否 | 滑动起点/终点到组件边框的偏移，默认80，单位：px，取值范围：大于等于0的整数。 | 1825 1826**返回值：** 1827 1828| 类型 | 说明 | 1829| ---------------------------------- | ------------------------------------- | 1830| Promise\<[Component](#component9)> | Promise对象，返回目标控件对象。 | 1831 1832**错误码：** 1833 1834以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 1835 1836| 错误码ID | 错误信息 | 1837| -------- | ---------------------------------------- | 1838| 17000002 | The async function is not called with await. | 1839| 17000004 | The window or component is invisible or destroyed. | 1840| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1841 1842**示例：** 1843 1844```ts 1845import { Component, Driver, ON } from '@kit.TestKit'; 1846async function demo() { 1847 let driver: Driver = Driver.create(); 1848 let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); 1849 let button = await scrollBar.scrollSearch(ON.text('next page')); 1850} 1851``` 1852 1853### scrollToTop<sup>9+</sup> 1854 1855scrollToTop(speed?: number): Promise\<void> 1856 1857在控件上滑动到顶部（适用支持滑动的控件），使用Promise异步回调。 1858 1859**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1860 1861**系统能力**：SystemCapability.Test.UiTest 1862 1863**参数：** 1864 1865| 参数名 | 类型 | 必填 | 说明 | 1866| ------ | ------ | ---- |--------------------------------------------------------| 1867| speed | number | 否 | 滑动速率，取值范围为200-40000的整数，默认值为600，不在范围内设为默认值为600，单位：px/s。 | 1868 1869**返回值：** 1870 1871| 类型 | 说明 | 1872|----------------|-----------------| 1873| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1874 1875**错误码：** 1876 1877以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 1878 1879| 错误码ID | 错误信息 | 1880| -------- | ---------------------------------------- | 1881| 17000002 | The async function is not called with await. | 1882| 17000004 | The window or component is invisible or destroyed. | 1883| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 1884 1885**示例：** 1886 1887```ts 1888import { Component, Driver, ON } from '@kit.TestKit'; 1889async function demo() { 1890 let driver: Driver = Driver.create(); 1891 let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); 1892 await scrollBar.scrollToTop(); 1893} 1894``` 1895 1896### scrollToBottom<sup>9+</sup> 1897 1898scrollToBottom(speed?: number): Promise\<void> 1899 1900在控件上滑动到底部（适用支持滑动的控件），使用Promise异步回调。 1901 1902**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1903 1904**系统能力**：SystemCapability.Test.UiTest 1905 1906**参数：** 1907 1908| 参数名 | 类型 | 必填 | 说明 | 1909| ------ | ------ | ---- |--------------------------------------------------------| 1910| speed | number | 否 | 滑动速率，取值范围为200-40000的整数，默认值为600，不在范围内设为默认值为600，单位：px/s。 | 1911 1912**返回值：** 1913 1914| 类型 | 说明 | 1915|----------------|-----------------| 1916| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1917 1918**错误码：** 1919 1920以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 1921 1922| 错误码ID | 错误信息 | 1923| -------- | ---------------------------------------- | 1924| 17000002 | The async function is not called with await. | 1925| 17000004 | The window or component is invisible or destroyed. | 1926| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.| 1927 1928**示例：** 1929 1930```ts 1931import { Component, Driver, ON } from '@kit.TestKit'; 1932async function demo() { 1933 let driver: Driver = Driver.create(); 1934 let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); 1935 await scrollBar.scrollToBottom(); 1936} 1937``` 1938 1939### dragTo<sup>9+</sup> 1940 1941dragTo(target: Component): Promise\<void> 1942 1943将控件拖拽至目标控件处，使用Promise异步回调。 1944 1945**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1946 1947**系统能力**：SystemCapability.Test.UiTest 1948 1949**设备行为差异**：该接口在Phone、Tablet、PC/2in1、TV设备上生效，在其他设备中调用无效果。 1950 1951**参数：** 1952 1953| 参数名 | 类型 | 必填 | 说明 | 1954| ------ | ------------------------ | ---- | ---------- | 1955| target | [Component](#component9) | 是 | 目标控件。 | 1956 1957**返回值：** 1958 1959| 类型 | 说明 | 1960|----------------|-----------------| 1961| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 1962 1963**错误码：** 1964 1965以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 1966 1967| 错误码ID | 错误信息 | 1968| -------- | ---------------------------------------- | 1969| 17000002 | The async function is not called with await. | 1970| 17000004 | The window or component is invisible or destroyed. | 1971| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 1972 1973**示例：** 1974 1975```ts 1976import { Component, Driver, ON } from '@kit.TestKit'; 1977async function demo() { 1978 let driver: Driver = Driver.create(); 1979 let button: Component = await driver.findComponent(ON.type('Button')); 1980 let text: Component = await driver.findComponent(ON.text('hello world')); 1981 await button.dragTo(text); 1982} 1983``` 1984 1985### pinchOut<sup>9+</sup> 1986 1987pinchOut(scale: number): Promise\<void> 1988 1989将控件按指定的比例进行捏合放大，使用Promise异步回调。 1990 1991**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1992 1993**系统能力**：SystemCapability.Test.UiTest 1994 1995**参数：** 1996 1997| 参数名 | 类型 | 必填 | 说明 | 1998| ------ | ------ | ---- | ------------------------------- | 1999| scale | number | 是 | 指定放大的比例。取值范围大于1。 | 2000 2001**返回值：** 2002 2003| 类型 | 说明 | 2004|----------------|-----------------| 2005| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2006 2007**错误码：** 2008 2009以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 2010 2011| 错误码ID | 错误信息 | 2012| -------- | ---------------------------------------- | 2013| 17000002 | The async function is not called with await. | 2014| 17000004 | The window or component is invisible or destroyed. | 2015| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2016 2017**示例：** 2018 2019```ts 2020import { Component, Driver, ON } from '@kit.TestKit'; 2021async function demo() { 2022 let driver: Driver = Driver.create(); 2023 let image: Component = await driver.findComponent(ON.type('Image')); 2024 await image.pinchOut(1.5); 2025} 2026``` 2027 2028### pinchIn<sup>9+</sup> 2029 2030pinchIn(scale: number): Promise\<void> 2031 2032将控件按指定的比例进行捏合缩小，使用Promise异步回调。 2033 2034**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2035 2036**系统能力**：SystemCapability.Test.UiTest 2037 2038**参数：** 2039 2040| 参数名 | 类型 | 必填 | 说明 | 2041| ------ | ------ | ---- | ------------------------------- | 2042| scale | number | 是 | 指定缩小的比例。取值范围为0~1。 | 2043 2044**返回值：** 2045 2046| 类型 | 说明 | 2047|----------------|-----------------| 2048| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2049 2050**错误码：** 2051 2052以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 2053 2054| 错误码ID | 错误信息 | 2055| -------- | ---------------------------------------- | 2056| 17000002 | The async function is not called with await. | 2057| 17000004 | The window or component is invisible or destroyed. | 2058| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2059 2060**示例：** 2061 2062```ts 2063import { Component, Driver, ON } from '@kit.TestKit'; 2064async function demo() { 2065 let driver: Driver = Driver.create(); 2066 let image: Component = await driver.findComponent(ON.type('Image')); 2067 await image.pinchIn(0.5); 2068} 2069``` 2070 2071### getDescription<sup>11+</sup> 2072 2073getDescription(): Promise\<string> 2074 2075获取控件对象的描述信息，使用Promise异步回调。 2076 2077**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2078 2079**系统能力**：SystemCapability.Test.UiTest 2080 2081**返回值：** 2082 2083| 类型 | 说明 | 2084| ---------------- | --------------------------------- | 2085| Promise\<string> | Promise对象，返回控件的描述信息。 | 2086 2087**错误码：** 2088 2089以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2090 2091| 错误码ID | 错误信息 | 2092| -------- | ------------------------------------------------------------ | 2093| 17000002 | The async function is not called with await. | 2094| 17000004 | The window or component is invisible or destroyed. | 2095 2096**示例：** 2097 2098```ts 2099import { Component, Driver, ON } from '@kit.TestKit'; 2100async function demo() { 2101 let driver: Driver = Driver.create(); 2102 let button: Component = await driver.findComponent(ON.type('Button')); 2103 let description = await button.getDescription(); 2104} 2105``` 2106### getHint<sup>18+</sup> 2107 2108getHint(): Promise\<string> 2109 2110获取控件对象的提示文本，使用Promise异步回调。 2111 2112**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 2113 2114**系统能力**：SystemCapability.Test.UiTest 2115 2116**返回值：** 2117 2118| 类型 | 说明 | 2119| ---------------- |----------------------| 2120| Promise\<string> | Promise对象，返回控件的提示文本。 | 2121 2122**错误码：** 2123 2124以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2125 2126| 错误码ID | 错误信息 | 2127| -------- | ---------------------------------------- | 2128| 17000002 | The async function is not called with await. | 2129| 17000004 | The window or component is invisible or destroyed. | 2130 2131**示例：** 2132 2133```ts 2134import { Component, Driver, ON } from '@kit.TestKit'; 2135async function demo() { 2136 let driver: Driver = Driver.create(); 2137 let button: Component = await driver.findComponent(ON.type('TextInput')); 2138 let hints = await button.getHint(); 2139} 2140``` 2141### getDisplayId<sup>20+</sup> 2142 2143getDisplayId(): Promise\<number> 2144 2145获取控件对象所属的屏幕ID，使用Promise异步回调。 2146 2147**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 2148 2149**系统能力**：SystemCapability.Test.UiTest 2150 2151**返回值：** 2152 2153| 类型 | 说明 | 2154| ---------------- |----------------------| 2155| Promise\<number> | Promise对象，返回控件所属的屏幕ID。 | 2156 2157**错误码：** 2158 2159以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2160 2161| 错误码ID | 错误信息 | 2162| -------- | ---------------------------------------- | 2163| 17000002 | The async function is not called with await. | 2164| 17000004 | The window or component is invisible or destroyed. | 2165 2166**示例：** 2167 2168```ts 2169import { Component, Driver, ON } from '@kit.TestKit'; 2170 2171async function demo() { 2172 let driver: Driver = Driver.create(); 2173 let button: Component = await driver.findComponent(ON.type('TextInput')); 2174 let displayId = await button.getDisplayId(); 2175} 2176``` 2177 2178### getOriginalText<sup>20+</sup> 2179 2180getOriginalText(): Promise\<string> 2181 2182获取控件对象的文本信息，使用Promise异步回调。 2183 2184> **说明** 2185> 2186> 如果控件的无障碍属性[accessibilityLevel](../apis-arkui/arkui-ts/ts-universal-attributes-accessibility.md#accessibilitylevel)设置为'no'或'no-hide-descendants'，可以使用本接口获取控件的文本信息，无法使用[Component.getText()](#gettext9)获取控件的文本信息。 2187 2188**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 2189 2190**系统能力**：SystemCapability.Test.UiTest 2191 2192**返回值：** 2193 2194| 类型 | 说明 | 2195| ---------------- | --------------------------------- | 2196| Promise\<string> | Promise对象，返回控件的文本信息。 | 2197 2198**错误码：** 2199 2200以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2201 2202| 错误码ID | 错误信息 | 2203| -------- | ---------------------------------------- | 2204| 17000002 | The async function is not called with await. | 2205| 17000004 | The window or component is invisible or destroyed. | 2206 2207**示例：** 2208 2209```ts 2210import { Component, Driver, ON } from '@kit.TestKit'; 2211 2212async function demo() { 2213 let driver: Driver = Driver.create(); 2214 let button: Component = await driver.findComponent(ON.type('Button')); 2215 let text = await button.getOriginalText(); 2216} 2217``` 2218 2219## Driver<sup>9+</sup> 2220 2221Driver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能力。 2222该类提供的方法除Driver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await方式调用。 2223 2224### create<sup>9+</sup> 2225 2226static create(): Driver 2227 2228静态方法，构造一个Driver对象，并返回该对象。 2229 2230**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2231 2232**系统能力**：SystemCapability.Test.UiTest 2233 2234**返回值：** 2235 2236| 类型 | 说明 | 2237| -------- | ---------------------- | 2238| Driver | 返回构造的Driver对象。 | 2239 2240**错误码：** 2241 2242以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2243 2244| 错误码ID | 错误信息 | 2245| -------- | ---------------------- | 2246| 17000001 | Initialization failed. | 2247 2248**示例：** 2249 2250```ts 2251import { Driver } from '@kit.TestKit'; 2252async function demo() { 2253 let driver: Driver = Driver.create(); 2254} 2255``` 2256 2257### delayMs<sup>9+</sup> 2258 2259delayMs(duration: number): Promise\<void> 2260 2261在给定的时间内延时，使用Promise异步回调。 2262 2263**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2264 2265**系统能力**：SystemCapability.Test.UiTest 2266 2267**参数：** 2268 2269| 参数名 | 类型 | 必填 | 说明 | 2270| -------- | ------ | ---- | ------------------------------- | 2271| duration | number | 是 | 给定的时间，单位：ms，取值范围：大于等于0的整数。 | 2272 2273**返回值：** 2274 2275| 类型 | 说明 | 2276|----------------|-----------------| 2277| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2278 2279**错误码：** 2280 2281以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 2282 2283| 错误码ID | 错误信息 | 2284| -------- | ---------------------------------------- | 2285| 17000002 | The async function is not called with await. | 2286| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2287 2288**示例：** 2289 2290```ts 2291import { Driver } from '@kit.TestKit'; 2292async function demo() { 2293 let driver: Driver = Driver.create(); 2294 await driver.delayMs(1000); 2295} 2296``` 2297 2298### findComponent<sup>9+</sup> 2299 2300findComponent(on: On): Promise\<Component> 2301 2302根据给出的目标控件属性要求查找目标控件，使用Promise异步回调。 2303 2304**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2305 2306**系统能力**：SystemCapability.Test.UiTest 2307 2308**参数：** 2309 2310| 参数名 | 类型 | 必填 | 说明 | 2311| ------ | ---------- | ---- | -------------------- | 2312| on | [On](#on9) | 是 | 目标控件的属性要求。 | 2313 2314**返回值：** 2315 2316| 类型 | 说明 | 2317| ---------------------------------- | --------------------------------- | 2318| Promise\<[Component](#component9)> | Promise对象，返回控件对象。 | 2319 2320**错误码：** 2321 2322以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 2323 2324| 错误码ID | 错误信息 | 2325| -------- | ---------------------------------------- | 2326| 17000002 | The async function is not called with await. | 2327| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2328 2329**示例：** 2330 2331```ts 2332import { Component, Driver, ON } from '@kit.TestKit'; 2333async function demo() { 2334 let driver: Driver = Driver.create(); 2335 let button: Component = await driver.findComponent(ON.text('next page')); 2336} 2337``` 2338 2339### findComponents<sup>9+</sup> 2340 2341findComponents(on: On): Promise\<Array\<Component>> 2342 2343根据给出的目标控件属性要求查找出所有匹配控件，以列表保存，使用Promise异步回调。 2344 2345**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2346 2347**系统能力**：SystemCapability.Test.UiTest 2348 2349**参数：** 2350 2351| 参数名 | 类型 | 必填 | 说明 | 2352| ------ | ---------- | ---- | -------------------- | 2353| on | [On](#on9) | 是 | 目标控件的属性要求。 | 2354 2355**返回值：** 2356 2357| 类型 | 说明 | 2358| ------------------------------------------ | --------------------------------------- | 2359| Promise\<Array\<[Component](#component9)>> | Promise对象，返回控件对象的列表。 | 2360 2361**错误码：** 2362 2363以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 2364 2365| 错误码ID | 错误信息 | 2366| -------- | ---------------------------------------- | 2367| 17000002 | The async function is not called with await. | 2368| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2369 2370**示例：** 2371 2372```ts 2373import { Component, Driver, ON } from '@kit.TestKit'; 2374async function demo() { 2375 let driver: Driver = Driver.create(); 2376 let buttonList: Array<Component> = await driver.findComponents(ON.text('next page')); 2377} 2378``` 2379 2380### findWindow<sup>9+</sup> 2381 2382findWindow(filter: WindowFilter): Promise\<UiWindow> 2383 2384通过指定窗口的属性来查找目标窗口，使用Promise异步回调。 2385 2386**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2387 2388**系统能力**：SystemCapability.Test.UiTest 2389 2390**参数：** 2391 2392| 参数名 | 类型 | 必填 | 说明 | 2393| ------ | ------------------------------ | ---- | ---------------- | 2394| filter | [WindowFilter](#windowfilter9) | 是 | 目标窗口的属性。 | 2395 2396**返回值：** 2397 2398| 类型 | 说明 | 2399| -------------------------------- | ------------------------------------- | 2400| Promise\<[UiWindow](#uiwindow9)> | Promise对象，返回目标窗口对象。 | 2401 2402**错误码：** 2403 2404以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 2405 2406| 错误码ID | 错误信息 | 2407| -------- | ---------------------------------------- | 2408| 17000002 | The async function is not called with await. | 2409| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2410 2411**示例：** 2412 2413```ts 2414import { Driver, UiWindow } from '@kit.TestKit'; 2415async function demo() { 2416 let driver: Driver = Driver.create(); 2417 let window: UiWindow = await driver.findWindow({actived: true}); 2418} 2419``` 2420 2421### waitForComponent<sup>9+</sup> 2422 2423waitForComponent(on: On, time: number): Promise\<Component> 2424 2425在用户给定的时间内，持续查找满足控件属性要求的目标控件，使用Promise异步回调。 2426 2427**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2428 2429**系统能力**：SystemCapability.Test.UiTest 2430 2431**参数：** 2432 2433| 参数名 | 类型 | 必填 | 说明 | 2434| ------ | ---------- | ---- | ----------------------------------------- | 2435| on | [On](#on9) | 是 | 目标控件的属性要求。 | 2436| time | number | 是 | 查找目标控件的持续时间。单位ms，取值范围：大于等于0的整数。 | 2437 2438**返回值：** 2439 2440| 类型 | 说明 | 2441| --------------------------------- | --------------------------------- | 2442| Promise\<[Component](#component9)> | Promise对象，返回控件对象。 | 2443 2444**错误码：** 2445 2446以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 2447 2448| 错误码ID | 错误信息 | 2449| -------- | ---------------------------------------- | 2450| 17000002 | The async function is not called with await. | 2451| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2452 2453**示例：** 2454 2455```ts 2456import { Component, Driver, ON } from '@kit.TestKit'; 2457async function demo() { 2458 let driver: Driver = Driver.create(); 2459 let button: Component = await driver.waitForComponent(ON.text('next page'),500); 2460} 2461``` 2462 2463### assertComponentExist<sup>9+</sup> 2464 2465assertComponentExist(on: On): Promise\<void> 2466 2467断言API，用于断言当前界面是否存在满足给出的目标属性的控件，使用Promise异步回调。 2468 2469**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2470 2471**系统能力**：SystemCapability.Test.UiTest 2472 2473**参数：** 2474 2475| 参数名 | 类型 | 必填 | 说明 | 2476| ------ | ---------- | ---- | -------------------- | 2477| on | [On](#on9) | 是 | 目标控件的属性要求。 | 2478 2479**返回值：** 2480 2481| 类型 | 说明 | 2482|----------------|-----------------| 2483| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2484 2485**错误码：** 2486 2487以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 2488 2489| 错误码ID | 错误信息 | 2490| -------- | ---------------------------------------- | 2491| 17000002 | The async function is not called with await. | 2492| 17000003 | Assertion failed. | 2493| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2494 2495**示例：** 2496 2497```ts 2498import { Driver, ON } from '@kit.TestKit'; 2499async function demo() { 2500 let driver: Driver = Driver.create(); 2501 await driver.assertComponentExist(ON.text('next page')); 2502} 2503``` 2504 2505### pressBack<sup>9+</sup> 2506 2507pressBack(): Promise\<void> 2508 2509进行点击BACK键的操作，使用Promise异步回调。 2510 2511**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2512 2513**系统能力**：SystemCapability.Test.UiTest 2514 2515**返回值：** 2516 2517| 类型 | 说明 | 2518|----------------|-----------------| 2519| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2520 2521**错误码：** 2522 2523以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2524 2525| 错误码ID | 错误信息 | 2526| -------- | ---------------------------------------- | 2527| 17000002 | The async function is not called with await. | 2528 2529**示例：** 2530 2531```ts 2532import { Driver } from '@kit.TestKit'; 2533async function demo() { 2534 let driver: Driver = Driver.create(); 2535 await driver.pressBack(); 2536} 2537``` 2538 2539### pressBack<sup>20+</sup> 2540 2541pressBack(displayId: number): Promise\<void> 2542 2543对指定屏幕进行点击BACK键的操作，使用Promise异步回调。 2544 2545**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 2546 2547**系统能力**：SystemCapability.Test.UiTest 2548 2549**参数：** 2550 2551| 参数名 | 类型 | 必填 | 说明 | 2552| ------- | ------ | ---- | ------------- | 2553| displayId | number | 是 | 指定的屏幕ID，取值范围：大于等于0的整数。<br> **说明：** 传入displayId不存在时，将抛出17000007异常。 | 2554 2555**返回值：** 2556 2557| 类型 | 说明 | 2558|----------------|-----------------| 2559| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2560 2561**错误码：** 2562 2563以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2564 2565| 错误码ID | 错误信息 | 2566| -------- | ---------------------------------------- | 2567| 17000002 | The async function is not called with await. | 2568| 17000007 | Parameter verification failed. | 2569 2570**示例：** 2571 2572```ts 2573import { Driver } from '@kit.TestKit'; 2574async function demo() { 2575 let driver: Driver = Driver.create(); 2576 await driver.pressBack(0); 2577} 2578``` 2579 2580### triggerKey<sup>9+</sup> 2581 2582triggerKey(keyCode: number): Promise\<void> 2583 2584传入key值实现模拟点击对应按键的效果，使用Promise异步回调。 2585 2586**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2587 2588**系统能力**：SystemCapability.Test.UiTest 2589 2590**参数：** 2591 2592| 参数名 | 类型 | 必填 | 说明 | 2593| ------- | ------ | ---- | ------------- | 2594| keyCode | number | 是 | 指定的key值，取值范围：大于等于0的整数。取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)。 | 2595 2596**返回值：** 2597 2598| 类型 | 说明 | 2599|----------------|-----------------| 2600| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2601 2602**错误码：** 2603 2604以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 2605 2606| 错误码ID | 错误信息 | 2607| -------- | ---------------------------------------- | 2608| 17000002 | The async function is not called with await. | 2609| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2610 2611**示例：** 2612 2613```ts 2614import { Driver } from '@kit.TestKit'; 2615import { KeyCode } from '@kit.InputKit'; 2616 2617async function demo() { 2618 let driver: Driver = Driver.create(); 2619 await driver.triggerKey(KeyCode.KEYCODE_BACK); // 返回键 2620} 2621``` 2622 2623### triggerKey<sup>20+</sup> 2624 2625triggerKey(keyCode: number, displayId: number): Promise\<void> 2626 2627在指定屏幕，传入key值实现模拟点击对应按键的效果，使用Promise异步回调。 2628 2629**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 2630 2631**系统能力**：SystemCapability.Test.UiTest 2632 2633**参数：** 2634 2635| 参数名 | 类型 | 必填 | 说明 | 2636| ------- | ------ | ---- | ------------- | 2637| keyCode | number | 是 | 指定的key值，取值范围：大于等于0的整数。取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)。 | 2638| displayId | number | 是 | 指定的屏幕ID，取值范围：大于等于0的整数。<br> **说明：** 传入displayId不存在时，将抛出17000007异常。 | 2639 2640**返回值：** 2641 2642| 类型 | 说明 | 2643|----------------|-----------------| 2644| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2645 2646**错误码：** 2647 2648以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 2649 2650| 错误码ID | 错误信息 | 2651| -------- | ---------------------------------------- | 2652| 17000002 | The async function is not called with await. | 2653| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2654 2655**示例：** 2656 2657```ts 2658import { Driver } from '@kit.TestKit'; 2659import { KeyCode } from '@kit.InputKit'; 2660 2661async function demo() { 2662 let driver: Driver = Driver.create(); 2663 await driver.triggerKey(KeyCode.KEYCODE_BACK, 0); // 返回键 2664} 2665``` 2666 2667### triggerCombineKeys<sup>9+</sup> 2668 2669triggerCombineKeys(key0: number, key1: number, key2?: number): Promise\<void> 2670 2671通过给定的key值，找到对应组合键并点击，使用Promise异步回调。例如，Key值为(2072, 2019)时，找到key值对应的组合键并点击，如Ctrl+c。 2672 2673**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2674 2675**系统能力**：SystemCapability.Test.UiTest 2676 2677**参数：** 2678 2679| 参数名 | 类型 | 必填 | 说明 | 2680| ------ | ------ | ---- | ------------------------------ | 2681| key0 | number | 是 | 指定的第一个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)。 | 2682| key1 | number | 是 | 指定的第二个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)。 | 2683| key2 | number | 否 | 指定的第三个key值，取值范围：大于等于0的整数。取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)，默认值为0。 | 2684 2685**返回值：** 2686 2687| 类型 | 说明 | 2688|----------------|-----------------| 2689| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2690 2691**错误码：** 2692 2693以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 2694 2695| 错误码ID | 错误信息 | 2696| -------- | ---------------------------------------- | 2697| 17000002 | The async function is not called with await. | 2698| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2699 2700**示例：** 2701 2702```ts 2703import { Driver } from '@kit.TestKit'; 2704async function demo() { 2705 let driver: Driver = Driver.create(); 2706 await driver.triggerCombineKeys(2072, 2047, 2035); 2707} 2708``` 2709 2710### triggerCombineKeys<sup>20+</sup> 2711 2712triggerCombineKeys(key0: number, key1: number, key2?: number, displayId?: number): Promise\<void> 2713 2714通过给定的key值，找到对应组合键，并在指定屏幕下进行点击，使用Promise异步回调。例如，Key值为(2072, 2019)时，找到key值对应的组合键并点击，如Ctrl+c。 2715 2716**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 2717 2718**系统能力**：SystemCapability.Test.UiTest 2719 2720**参数：** 2721 2722| 参数名 | 类型 | 必填 | 说明 | 2723| ------ | ------ | ---- | ------------------------------ | 2724| key0 | number | 是 | 指定的第一个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)。 | 2725| key1 | number | 是 | 指定的第二个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)。 | 2726| key2 | number | 否 | 指定的第三个key值，取值范围：大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)，默认值为0。 | 2727| displayId | number | 否 | 指定的屏幕ID，取值范围：大于等于0的整数，默认值为设备默认屏幕ID。 | 2728 2729**返回值：** 2730 2731| 类型 | 说明 | 2732|----------------|-----------------| 2733| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2734 2735**错误码：** 2736 2737以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 2738 2739| 错误码ID | 错误信息 | 2740| -------- | ---------------------------------------- | 2741| 17000002 | The async function is not called with await. | 2742| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2743 2744**示例：** 2745 2746```ts 2747import { Driver } from '@kit.TestKit'; 2748 2749async function demo() { 2750 let driver: Driver = Driver.create(); 2751 await driver.triggerCombineKeys(2072, 2047, 2035, 0); 2752} 2753``` 2754 2755### click<sup>9+</sup> 2756 2757click(x: number, y: number): Promise\<void> 2758 2759在目标坐标点单击，使用Promise异步回调。 2760 2761**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2762 2763**系统能力**：SystemCapability.Test.UiTest 2764 2765**参数：** 2766 2767| 参数名 | 类型 | 必填 | 说明 | 2768| ------ | ------ | ---- | ----------------------------------------------- | 2769| x | number | 是 | 以number的形式传入目标点的横坐标信息，取值范围：大于等于0的整数。 | 2770| y | number | 是 | 以number的形式传入目标点的纵坐标信息，取值范围：大于等于0的整数。 | 2771 2772**返回值：** 2773 2774| 类型 | 说明 | 2775|----------------|-----------------| 2776| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2777 2778**错误码：** 2779 2780以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 2781 2782| 错误码ID | 错误信息 | 2783| -------- | ---------------------------------------- | 2784| 17000002 | The async function is not called with await. | 2785| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2786 2787**示例：** 2788 2789```ts 2790import { Driver } from '@kit.TestKit'; 2791async function demo() { 2792 let driver: Driver = Driver.create(); 2793 await driver.click(100,100); 2794} 2795``` 2796 2797### clickAt<sup>20+</sup> 2798 2799clickAt(point: Point): Promise\<void> 2800 2801在目标坐标点进行单击，使用Promise异步回调。 2802 2803**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 2804 2805**系统能力**：SystemCapability.Test.UiTest 2806 2807**参数：** 2808 2809| 参数名 | 类型 | 必填 | 说明 | 2810| ------ | ------ | ---- | ----------------------------------------------- | 2811| point | [Point](#point9) | 是 | 以Point对象的形式传入目标点信息。 | 2812 2813**返回值：** 2814 2815| 类型 | 说明 | 2816|----------------|-----------------| 2817| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2818 2819**错误码：** 2820 2821以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2822 2823| 错误码ID | 错误信息 | 2824| -------- | ---------------------------------------- | 2825| 17000002 | The async function is not called with await. | 2826| 17000007 | Parameter verification failed. | 2827 2828**示例：** 2829 2830```ts 2831import { Driver } from '@kit.TestKit'; 2832 2833async function demo() { 2834 let driver: Driver = Driver.create(); 2835 await driver.clickAt({ x: 100, y: 100, displayId: 0 }); 2836} 2837``` 2838 2839### doubleClick<sup>9+</sup> 2840 2841doubleClick(x: number, y: number): Promise\<void> 2842 2843在目标坐标点双击，使用Promise异步回调。 2844 2845**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2846 2847**系统能力**：SystemCapability.Test.UiTest 2848 2849**参数：** 2850 2851| 参数名 | 类型 | 必填 | 说明 | 2852| ------ | ------ | ---- | ----------------------------------------------- | 2853| x | number | 是 | 以number的形式传入目标点的横坐标信息，取值范围：大于等于0的整数。 | 2854| y | number | 是 | 以number的形式传入目标点的纵坐标信息，取值范围：大于等于0的整数。 | 2855 2856**返回值：** 2857 2858| 类型 | 说明 | 2859|----------------|-----------------| 2860| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2861 2862**错误码：** 2863 2864以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 2865 2866| 错误码ID | 错误信息 | 2867| -------- | ---------------------------------------- | 2868| 17000002 | The async function is not called with await. | 2869| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2870 2871**示例：** 2872 2873```ts 2874import { Driver } from '@kit.TestKit'; 2875async function demo() { 2876 let driver: Driver = Driver.create(); 2877 await driver.doubleClick(100,100); 2878} 2879``` 2880 2881### doubleClickAt<sup>20+</sup> 2882 2883doubleClickAt(point: Point): Promise\<void> 2884 2885对目标坐标进行双击，使用Promise异步回调。 2886 2887**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 2888 2889**系统能力**：SystemCapability.Test.UiTest 2890 2891**参数：** 2892 2893| 参数名 | 类型 | 必填 | 说明 | 2894| ------ | ------ | ---- | ----------------------------------------------- | 2895| point | [Point](#point9) | 是 | 以Point对象的形式传入目标点信息。 | 2896 2897**返回值：** 2898 2899| 类型 | 说明 | 2900|----------------|-----------------| 2901| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2902 2903**错误码：** 2904 2905以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2906 2907| 错误码ID | 错误信息 | 2908| -------- | ---------------------------------------- | 2909| 17000002 | The async function is not called with await. | 2910| 17000007 | Parameter verification failed. | 2911 2912**示例：** 2913 2914```ts 2915import { Driver } from '@kit.TestKit'; 2916 2917async function demo() { 2918 let driver: Driver = Driver.create(); 2919 await driver.doubleClickAt({ x: 100, y: 100, displayId: 0 }); 2920} 2921``` 2922 2923### longClick<sup>9+</sup> 2924 2925longClick(x: number, y: number): Promise\<void> 2926 2927在目标坐标点长按，使用Promise异步回调。 2928 2929**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2930 2931**系统能力**：SystemCapability.Test.UiTest 2932 2933**参数：** 2934 2935| 参数名 | 类型 | 必填 | 说明 | 2936| ------ | ------ | ---- | ----------------------------------------------- | 2937| x | number | 是 | 以number的形式传入目标点的横坐标信息，取值范围：大于等于0的整数。 | 2938| y | number | 是 | 以number的形式传入目标点的纵坐标信息，取值范围：大于等于0的整数。 | 2939 2940**返回值：** 2941 2942| 类型 | 说明 | 2943|----------------|-----------------| 2944| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2945 2946**错误码：** 2947 2948以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 2949 2950| 错误码ID | 错误信息 | 2951| -------- | ---------------------------------------- | 2952| 17000002 | The async function is not called with await. | 2953| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 2954 2955**示例：** 2956 2957```ts 2958import { Driver } from '@kit.TestKit'; 2959async function demo() { 2960 let driver: Driver = Driver.create(); 2961 await driver.longClick(100,100); 2962} 2963``` 2964 2965### longClickAt<sup>20+</sup> 2966 2967longClickAt(point: Point, duration?: number): Promise\<void> 2968 2969长按目标坐标点，支持指定长按时长，使用Promise异步回调。 2970 2971**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 2972 2973**系统能力**：SystemCapability.Test.UiTest 2974 2975**参数：** 2976 2977| 参数名 | 类型 | 必填 | 说明 | 2978| ------ | ------ | ---- | ----------------------------------------------- | 2979| point | [Point](#point9) | 是 | 以Point对象的形式传入目标点信息。 | 2980| duration | number | 否 | 长按持续的时间，取值范围为大于等于1500的整数，默认值为1500，单位：ms。 | 2981 2982**返回值：** 2983 2984| 类型 | 说明 | 2985|----------------|-----------------| 2986| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 2987 2988**错误码：** 2989 2990以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 2991 2992| 错误码ID | 错误信息 | 2993| -------- | ---------------------------------------- | 2994| 17000002 | The async function is not called with await. | 2995| 17000007 | Parameter verification failed. | 2996 2997**示例：** 2998 2999```ts 3000import { Driver } from '@kit.TestKit'; 3001 3002async function demo() { 3003 let driver: Driver = Driver.create(); 3004 await driver.longClickAt({ x: 100, y: 100, displayId: 0 }, 1500); 3005} 3006``` 3007 3008### swipe<sup>9+</sup> 3009 3010swipe(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\<void> 3011 3012从起始坐标点滑向目的坐标点，使用Promise异步回调。 3013 3014**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3015 3016**系统能力**：SystemCapability.Test.UiTest 3017 3018**参数：** 3019 3020| 参数名 | 类型 | 必填 | 说明 | 3021| ------ | ------ | ---- |------------------------------------------------------| 3022| startx | number | 是 | 以number的形式传入起始点的横坐标信息，取值范围：大于等于0的整数。 | 3023| starty | number | 是 | 以number的形式传入起始点的纵坐标信息，取值范围：大于等于0的整数。 | 3024| endx | number | 是 | 以number的形式传入目的点的横坐标信息，取值范围：大于等于0的整数。 | 3025| endy | number | 是 | 以number的形式传入目的点的纵坐标信息，取值范围：大于等于0的整数。 | 3026| speed | number | 否 | 滑动速率，取值范围为200-40000的整数，默认值为600，不在范围内设为默认值为600，单位：px/s。 | 3027 3028**返回值：** 3029 3030| 类型 | 说明 | 3031|----------------|-----------------| 3032| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3033 3034**错误码：** 3035 3036以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 3037 3038| 错误码ID | 错误信息 | 3039| -------- | ---------------------------------------- | 3040| 17000002 | The async function is not called with await. | 3041| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3042 3043**示例：** 3044 3045```ts 3046import { Driver } from '@kit.TestKit'; 3047async function demo() { 3048 let driver: Driver = Driver.create(); 3049 await driver.swipe(100,100,200,200,600); 3050} 3051``` 3052 3053### swipeBetween<sup>20+</sup> 3054 3055swipeBetween(from: Point, to: Point, speed?: number): Promise\<void> 3056 3057从起始坐标点滑向目标坐标点，使用Promise异步回调。 3058 3059**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 3060 3061**系统能力**：SystemCapability.Test.UiTest 3062 3063**参数：** 3064 3065| 参数名 | 类型 | 必填 | 说明 | 3066| ------ | ------ | ---- |------------------------------------------------------| 3067| from | [Point](#point9) | 是 | 以Point对象的形式传入起始点的坐标信息和所属屏幕ID。 | 3068| to | [Point](#point9) | 是 | 以Point对象的形式传入终止点的坐标信息和所属屏幕ID。<br> **说明：** 应与起始点属于同一个屏幕，否则将抛出17000007异常。 | 3069| speed | number | 否 | 滑动速率，取值范围为200-40000的整数，默认值为600，不在范围内设为默认值为600，单位：px/s。| 3070 3071**返回值：** 3072 3073| 类型 | 说明 | 3074|----------------|-----------------| 3075| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3076 3077**错误码：** 3078 3079以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3080 3081| 错误码ID | 错误信息 | 3082| -------- | ---------------------------------------- | 3083| 17000002 | The async function is not called with await. | 3084| 17000007 | Parameter verification failed. | 3085 3086**示例：** 3087 3088```ts 3089import { Driver } from '@kit.TestKit'; 3090 3091async function demo() { 3092 let driver: Driver = Driver.create(); 3093 await driver.swipeBetween({x: 100, y: 100, displayId: 0}, {x: 1000, y: 1000, displayId: 0}, 800); 3094} 3095``` 3096 3097### drag<sup>9+</sup> 3098 3099drag(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\<void> 3100 3101从起始坐标点拖拽至目的坐标点，使用Promise异步回调。 3102 3103**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3104 3105**系统能力**：SystemCapability.Test.UiTest 3106 3107**设备行为差异**：该接口在Phone、Tablet、PC/2in1、TV设备上生效，在其他设备中调用无效果。 3108 3109**参数：** 3110 3111| 参数名 | 类型 | 必填 | 说明 | 3112| ------ | ------ | ---- | ------------------------------------------------------------ | 3113| startx | number | 是 | 以number的形式传入起始点的横坐标信息，取值范围：大于等于0的整数。 | 3114| starty | number | 是 | 以number的形式传入起始点的纵坐标信息，取值范围：大于等于0的整数。 | 3115| endx | number | 是 | 以number的形式传入目的点的横坐标信息，取值范围：大于等于0的整数。 | 3116| endy | number | 是 | 以number的形式传入目的点的纵坐标信息，取值范围：大于等于0的整数。 | 3117| speed | number | 否 | 滑动速率，取值范围为200-40000的整数，默认值为600，不在范围内设为默认值为600，单位：px/s。| 3118 3119**返回值：** 3120 3121| 类型 | 说明 | 3122|----------------|-----------------| 3123| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3124 3125**错误码：** 3126 3127以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 3128 3129| 错误码ID | 错误信息 | 3130| -------- | ---------------------------------------- | 3131| 17000002 | The async function is not called with await. | 3132| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3133 3134**示例：** 3135 3136```ts 3137import { Driver } from '@kit.TestKit'; 3138 3139async function demo() { 3140 let driver: Driver = Driver.create(); 3141 await driver.drag(100, 100, 200, 200, 600); 3142} 3143``` 3144 3145### dragBetween<sup>20+</sup> 3146 3147dragBetween(from: Point, to: Point, speed?: number, duration?: number): Promise\<void> 3148 3149从起始坐标点拖拽至目标坐标点，支持指定拖拽速度和拖拽前长按时间，使用Promise异步回调。 3150 3151**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 3152 3153**系统能力**：SystemCapability.Test.UiTest 3154 3155**设备行为差异**：该接口在Phone、Tablet、PC/2in1、TV设备上生效，在其他设备中调用无效果。 3156 3157**参数：** 3158 3159| 参数名 | 类型 | 必填 | 说明 | 3160| ------ | ------ | ---- |--------------------------------------------------------| 3161| from | [Point](#point9) | 是 | 以Point对象的形式传入起始点的坐标信息和所属屏幕ID。 | 3162| to | [Point](#point9) | 是 | 以Point对象的形式传入终止点的坐标信息和所属屏幕ID。<br> **说明：** 应与起始点属于同一个屏幕，否则将抛出17000007异常。 | 3163| speed | number | 否 | 滑动速率，取值范围为200-40000的整数，默认值为600，不在范围内设为默认值为600，单位：px/s。| 3164| duration | number | 否 | 拖拽前长按持续的时间，取值范围为大于等于1500的整数，默认值为1500，单位：ms。 | 3165 3166**返回值：** 3167 3168| 类型 | 说明 | 3169|----------------|-----------------| 3170| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3171 3172**错误码：** 3173 3174以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3175 3176| 错误码ID | 错误信息 | 3177| -------- | ---------------------------------------- | 3178| 17000002 | The async function is not called with await. | 3179| 17000007 | Parameter verification failed. | 3180 3181**示例：** 3182 3183```ts 3184import { Driver } from '@kit.TestKit'; 3185 3186async function demo() { 3187 let driver: Driver = Driver.create(); 3188 await driver.dragBetween( {x: 100, y: 100, displayId: 0}, {x: 1000, y: 1000, displayId: 0}, 800, 1500); 3189} 3190``` 3191 3192### screenCap<sup>9+</sup> 3193 3194screenCap(savePath: string): Promise\<boolean> 3195 3196捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中，使用Promise异步回调。适用于支持截屏的场景。 3197 3198**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3199 3200**系统能力**：SystemCapability.Test.UiTest 3201 3202**参数：** 3203 3204| 参数名 | 类型 | 必填 | 说明 | 3205| -------- | ------ | ---- | ------------------------------------------ | 3206| savePath | string | 是 | 文件保存路径。路径需为当前应用的[沙箱路径](../../file-management/app-sandbox-directory.md)。 | 3207 3208**返回值：** 3209 3210| 类型 | 说明 | 3211| ----------------- |-------------------------------------------| 3212| Promise\<boolean> | Promise对象，返回截图操作是否成功完成。true：完成，false：未完成。 | 3213 3214**错误码：** 3215 3216以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 3217 3218| 错误码ID | 错误信息 | 3219| -------- | ---------------------------------------- | 3220| 17000002 | The async function is not called with await. | 3221| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3222 3223**示例：** 3224 3225```ts 3226import { Driver } from '@kit.TestKit'; 3227async function demo() { 3228 let driver: Driver = Driver.create(); 3229 await driver.screenCap('/data/storage/el2/base/cache/1.png'); 3230} 3231``` 3232 3233### screenCap<sup>20+</sup> 3234 3235screenCap(savePath: string, displayId: number): Promise\<boolean> 3236 3237捕获指定屏幕，并保存为PNG格式的图片至给出的保存路径中，使用Promise异步回调。适用于支持截屏的场景。 3238 3239**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 3240 3241**系统能力**：SystemCapability.Test.UiTest 3242 3243**参数：** 3244 3245| 参数名 | 类型 | 必填 | 说明 | 3246| -------- | ------ | ---- | ------------------------------------------ | 3247| savePath | string | 是 | 文件保存路径。路径需为当前应用的[沙箱路径](../../file-management/app-sandbox-directory.md)。 | 3248| displayId | number | 是 | 指定设备屏幕ID。取值范围：大于等于0的整数。 <br> **说明：** 传入displayId不存在时，将抛出17000007异常。 | 3249 3250**返回值：** 3251 3252| 类型 | 说明 | 3253| ----------------- |-------------------------------------------| 3254| Promise\<boolean> | Promise对象，返回截图操作是否成功完成。true：完成。false：未完成。 | 3255 3256**错误码：** 3257 3258以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 3259 3260| 错误码ID | 错误信息 | 3261| -------- | ---------------------------------------- | 3262| 17000002 | The async function is not called with await. | 3263| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3264 3265**示例：** 3266 3267```ts 3268import { Driver } from '@kit.TestKit'; 3269 3270async function demo() { 3271 let driver: Driver = Driver.create(); 3272 await driver.screenCap('/data/storage/el2/base/cache/1.png', 0); 3273} 3274``` 3275 3276### setDisplayRotation<sup>9+</sup> 3277 3278setDisplayRotation(rotation: DisplayRotation): Promise\<void> 3279 3280将当前场景的显示方向设置为指定的显示方向，使用Promise异步回调。适用于可旋转的应用场景。 3281 3282**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3283 3284**系统能力**：SystemCapability.Test.UiTest 3285 3286**设备行为差异**：该接口在Phone、Tablet、PC/2in1、TV设备上生效，在其他设备中调用无效果。 3287 3288**参数：** 3289 3290| 参数名 | 类型 | 必填 | 说明 | 3291| -------- | ------------------------------------ | ---- | ---------------- | 3292| rotation | [DisplayRotation](#displayrotation9) | 是 | 设备的显示方向。 | 3293 3294**返回值：** 3295 3296| 类型 | 说明 | 3297|----------------|-----------------| 3298| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3299 3300**错误码：** 3301 3302以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 3303 3304| 错误码ID | 错误信息 | 3305| -------- | ---------------------------------------- | 3306| 17000002 | The async function is not called with await. | 3307| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3308 3309**示例：** 3310 3311```ts 3312import { Driver, DisplayRotation } from '@kit.TestKit'; 3313async function demo() { 3314 let driver: Driver = Driver.create(); 3315 await driver.setDisplayRotation(DisplayRotation.ROTATION_180); 3316} 3317``` 3318 3319### getDisplayRotation<sup>9+</sup> 3320 3321getDisplayRotation(): Promise\<DisplayRotation> 3322 3323获取当前设备的屏幕显示方向，使用Promise异步回调。 3324 3325**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3326 3327**系统能力**：SystemCapability.Test.UiTest 3328 3329**返回值：** 3330 3331| 类型 | 说明 | 3332| ---------------------------------------------- | --------------------------------------- | 3333| Promise\<[DisplayRotation](#displayrotation9)> | Promise对象，返回当前设备的显示方向。 | 3334 3335**错误码：** 3336 3337以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3338 3339| 错误码ID | 错误信息 | 3340| -------- | ---------------------------------------- | 3341| 17000002 | The async function is not called with await. | 3342 3343**示例：** 3344 3345```ts 3346import { DisplayRotation, Driver } from '@kit.TestKit'; 3347async function demo() { 3348 let driver: Driver = Driver.create(); 3349 let rotation: DisplayRotation = await driver.getDisplayRotation(); 3350} 3351``` 3352 3353### getDisplayRotation<sup>20+</sup> 3354 3355getDisplayRotation(displayId: number): Promise\<DisplayRotation> 3356 3357获取当前设备指定屏幕的显示方向，使用Promise异步回调。 3358 3359**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 3360 3361**系统能力**：SystemCapability.Test.UiTest 3362 3363**参数：** 3364 3365| 参数名 | 类型 | 必填 | 说明 | 3366| -------- | ------ | ---- | ------------------------------------------ | 3367| displayId | number | 是 | 指定设备屏幕ID。取值范围：大于等于0的整数。 <br> **说明：** 传入displayId不存在时，将抛出17000007异常。 | 3368 3369**返回值：** 3370 3371| 类型 | 说明 | 3372| ---------------------------------------------- | --------------------------------------- | 3373| Promise\<[DisplayRotation](#displayrotation9)> | Promise对象，返回指定屏幕的显示方向。 | 3374 3375**错误码：** 3376 3377以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3378 3379| 错误码ID | 错误信息 | 3380| -------- | ---------------------------------------- | 3381| 17000002 | The async function is not called with await. | 3382| 17000007 | Parameter verification failed. | 3383 3384**示例：** 3385 3386```ts 3387import { DisplayRotation, Driver } from '@kit.TestKit'; 3388 3389async function demo() { 3390 let driver: Driver = Driver.create(); 3391 let rotation: DisplayRotation = await driver.getDisplayRotation(0); 3392} 3393``` 3394 3395### setDisplayRotationEnabled<sup>9+</sup> 3396 3397setDisplayRotationEnabled(enabled: boolean): Promise\<void> 3398 3399启用/禁用设备旋转屏幕的功能，使用Promise异步回调。 3400 3401**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3402 3403**系统能力**：SystemCapability.Test.UiTest 3404 3405**设备行为差异**：该接口在Phone、Tablet、PC/2in1、TV设备上生效，在其他设备中调用无效果。 3406 3407**参数：** 3408 3409| 参数名 | 类型 | 必填 | 说明 | 3410| ------- | ------- | ---- | ------------------------------------------------------- | 3411| enabled | boolean | 是 | 能否旋转屏幕的标识。true：可以旋转。false：不可以旋转。 | 3412 3413**返回值：** 3414 3415| 类型 | 说明 | 3416|----------------|-----------------| 3417| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3418 3419**错误码：** 3420 3421以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 3422 3423| 错误码ID | 错误信息 | 3424| -------- | ---------------------------------------- | 3425| 17000002 | The async function is not called with await. | 3426| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3427 3428**示例：** 3429 3430```ts 3431import { Driver } from '@kit.TestKit'; 3432async function demo() { 3433 let driver: Driver = Driver.create(); 3434 await driver.setDisplayRotationEnabled(false); 3435} 3436``` 3437 3438### getDisplaySize<sup>9+</sup> 3439 3440getDisplaySize(): Promise\<Point> 3441 3442获取当前设备的屏幕大小，使用Promise异步回调。 3443 3444**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3445 3446**系统能力**：SystemCapability.Test.UiTest 3447 3448**返回值：** 3449 3450| 类型 | 说明 | 3451| -------------------------- | --------------------------------------- | 3452| Promise\<[Point](#point9)> | Promise对象，返回Point对象，当前设备屏幕的大小为Point.x * Point.y。 | 3453 3454**错误码：** 3455 3456以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3457 3458| 错误码ID | 错误信息 | 3459| -------- | ---------------------------------------- | 3460| 17000002 | The async function is not called with await. | 3461 3462**示例：** 3463 3464```ts 3465import { Driver } from '@kit.TestKit'; 3466 3467async function demo() { 3468 let driver: Driver = Driver.create(); 3469 let size = await driver.getDisplaySize(); 3470} 3471``` 3472 3473### getDisplaySize<sup>20+</sup> 3474 3475getDisplaySize(displayId: number): Promise\<Point> 3476 3477获取当前设备指定屏幕的大小，使用Promise异步回调。 3478 3479**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 3480 3481**系统能力**：SystemCapability.Test.UiTest 3482 3483**参数：** 3484 3485| 参数名 | 类型 | 必填 | 说明 | 3486| -------- | ------ | ---- | ------------------------------------------ | 3487| displayId | number | 是 | 指定设备屏幕ID。取值范围：大于等于0的整数。 <br> **说明：** 传入displayId不存在时，将抛出17000007异常。 | 3488 3489**返回值：** 3490 3491| 类型 | 说明 | 3492| -------------------------- | --------------------------------------- | 3493| Promise\<[Point](#point9)> | Promise对象，返回Point对象，当前设备指定屏幕的大小为Point.x * Point.y。 | 3494 3495**错误码：** 3496 3497以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3498 3499| 错误码ID | 错误信息 | 3500| -------- | ---------------------------------------- | 3501| 17000002 | The async function is not called with await. | 3502| 17000007 | Parameter verification failed. | 3503 3504**示例：** 3505 3506```ts 3507import { Driver } from '@kit.TestKit'; 3508 3509async function demo() { 3510 let driver: Driver = Driver.create(); 3511 let size = await driver.getDisplaySize(0); 3512} 3513``` 3514 3515### getDisplayDensity<sup>9+</sup> 3516 3517getDisplayDensity(): Promise\<Point> 3518 3519获取当前设备屏幕的分辨率，使用Promise异步回调。 3520 3521**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3522 3523**系统能力**：SystemCapability.Test.UiTest 3524 3525**返回值：** 3526 3527| 类型 | 说明 | 3528| -------------------------- | ----------------------------------------- | 3529| Promise\<[Point](#point9)> | Promise对象，返回Point对象，当前设备屏幕的分辨率为Point.x*Point.y。 | 3530 3531**错误码：** 3532 3533以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3534 3535| 错误码ID | 错误信息 | 3536| -------- | ---------------------------------------- | 3537| 17000002 | The async function is not called with await. | 3538 3539**示例：** 3540 3541```ts 3542import { Driver } from '@kit.TestKit'; 3543async function demo() { 3544 let driver: Driver = Driver.create(); 3545 let density = await driver.getDisplayDensity(); 3546} 3547``` 3548 3549### getDisplayDensity<sup>20+</sup> 3550 3551getDisplayDensity(displayId: number): Promise\<Point> 3552 3553获取当前设备指定屏幕的分辨率，使用Promise异步回调。 3554 3555**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 3556 3557**系统能力**：SystemCapability.Test.UiTest 3558 3559**参数：** 3560 3561| 参数名 | 类型 | 必填 | 说明 | 3562| -------- | ------ | ---- | ------------------------------------------ | 3563| displayId | number | 是 | 指定设备屏幕ID。取值范围：大于等于0的整数。 <br> **说明：** 传入displayId不存在时，将抛出17000007异常。 | 3564 3565**返回值：** 3566 3567| 类型 | 说明 | 3568| -------------------------- | ----------------------------------------- | 3569| Promise\<[Point](#point9)> | Promise对象，返回Point对象，当前设备指定屏幕的分辨率为Point.x*Point.y。 | 3570 3571**错误码：** 3572 3573以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3574 3575| 错误码ID | 错误信息 | 3576| -------- | ---------------------------------------- | 3577| 17000002 | The async function is not called with await. | 3578| 17000007 | Parameter verification failed. | 3579 3580**示例：** 3581 3582```ts 3583import { Driver } from '@kit.TestKit'; 3584 3585async function demo() { 3586 let driver: Driver = Driver.create(); 3587 let density = await driver.getDisplayDensity(0); 3588} 3589``` 3590 3591### wakeUpDisplay<sup>9+</sup> 3592 3593wakeUpDisplay(): Promise\<void> 3594 3595唤醒当前设备即设备亮屏，使用Promise异步回调。 3596 3597**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3598 3599**系统能力**：SystemCapability.Test.UiTest 3600 3601**返回值：** 3602 3603| 类型 | 说明 | 3604|----------------|-----------------| 3605| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3606 3607**错误码：** 3608 3609以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3610 3611| 错误码ID | 错误信息 | 3612| -------- | ---------------------------------------- | 3613| 17000002 | The async function is not called with await. | 3614 3615**示例：** 3616 3617```ts 3618import { Driver } from '@kit.TestKit'; 3619async function demo() { 3620 let driver: Driver = Driver.create(); 3621 await driver.wakeUpDisplay(); 3622} 3623``` 3624 3625### pressHome<sup>9+</sup> 3626 3627pressHome(): Promise\<void> 3628 3629设备注入返回桌面操作，使用Promise异步回调。 3630 3631**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3632 3633**系统能力**：SystemCapability.Test.UiTest 3634 3635**设备行为差异**：该接口在Phone、Tablet、PC/2in1、TV设备上生效，在其他设备中调用无效果。 3636 3637**返回值：** 3638 3639| 类型 | 说明 | 3640|----------------|-----------------| 3641| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3642 3643**错误码：** 3644 3645以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3646 3647| 错误码ID | 错误信息 | 3648| -------- | ---------------------------------------- | 3649| 17000002 | The async function is not called with await. | 3650 3651**示例：** 3652 3653```ts 3654import { Driver } from '@kit.TestKit'; 3655async function demo() { 3656 let driver: Driver = Driver.create(); 3657 await driver.pressHome(); 3658} 3659``` 3660 3661### pressHome<sup>20+</sup> 3662 3663pressHome(displayId: number): Promise\<void> 3664 3665设备指定屏幕上注入返回桌面操作，使用Promise异步回调。 3666 3667**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 3668 3669**系统能力**：SystemCapability.Test.UiTest 3670 3671**设备行为差异**：该接口在Phone、Tablet、PC/2in1、TV设备上生效，在其他设备中调用无效果。 3672 3673**参数：** 3674 3675| 参数名 | 类型 | 必填 | 说明 | 3676| -------- | ------ | ---- | ------------------------------------------ | 3677| displayId | number | 是 | 指定设备屏幕ID。取值范围：大于等于0的整数。 <br> **说明：** 传入displayId不存在时，将抛出17000007异常。 | 3678 3679**返回值：** 3680 3681| 类型 | 说明 | 3682|----------------|-----------------| 3683| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3684 3685**错误码：** 3686 3687以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 3688 3689| 错误码ID | 错误信息 | 3690| -------- | ---------------------------------------- | 3691| 17000002 | The async function is not called with await. | 3692| 17000007 | Parameter verification failed. | 3693 3694**示例：** 3695 3696```ts 3697import { Driver } from '@kit.TestKit'; 3698 3699async function demo() { 3700 let driver: Driver = Driver.create(); 3701 await driver.pressHome(0); 3702} 3703``` 3704 3705### waitForIdle<sup>9+</sup> 3706 3707waitForIdle(idleTime: number, timeout: number): Promise\<boolean> 3708 3709判断当前界面的所有控件是否已经空闲，使用Promise异步回调。 3710 3711**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3712 3713**系统能力**：SystemCapability.Test.UiTest 3714 3715**参数：** 3716 3717| 参数名 | 类型 | 必填 | 说明 | 3718| -------- | ------ | ---- | ------------------------------------------------------------ | 3719| idleTime | number | 是 | 空闲时间的阈值。在这个时间段控件不发生变化，视为该控件空闲，单位：毫秒，取值范围：大于等于0的整数。 | 3720| timeout | number | 是 | 等待空闲的最大时间，单位：毫秒，取值范围：大于等于0的整数。 | 3721 3722**返回值：** 3723 3724| 类型 | 说明 | 3725| ----------------- |---------------------------------------------------| 3726| Promise\<boolean> | Promise对象，返回当前界面的所有控件是否已经空闲。true：已经空闲，false：不空闲。 | 3727 3728**错误码：** 3729 3730以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 3731 3732| 错误码ID | 错误信息 | 3733| -------- | ---------------------------------------- | 3734| 17000002 | The async function is not called with await. | 3735| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3736 3737**示例：** 3738 3739```ts 3740import { Driver } from '@kit.TestKit'; 3741async function demo() { 3742 let driver: Driver = Driver.create(); 3743 let idled:boolean = await driver.waitForIdle(4000,5000); 3744} 3745``` 3746 3747### fling<sup>9+</sup> 3748 3749fling(from: Point, to: Point, stepLen: number, speed: number): Promise\<void> 3750 3751模拟手指滑动后脱离屏幕的快速滑动操作，使用Promise异步回调。 3752 3753**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3754 3755**系统能力**：SystemCapability.Test.UiTest 3756 3757**参数：** 3758 3759| 参数名 | 类型 | 必填 | 说明 | 3760| ------- | ---------------- | ---- |------------------------------------------------------| 3761| from | [Point](#point9) | 是 | 手指接触屏幕的起始点坐标。 | 3762| to | [Point](#point9) | 是 | 手指离开屏幕时的坐标点。 | 3763| stepLen | number | 是 | 间隔距离，取值大于等于0的整数，单位：px。 | 3764| speed | number | 是 | 滑动速率，取值范围为200-40000的整数，默认值为600，不在范围内设为默认值为600，单位：px/s。 | 3765 3766**返回值：** 3767 3768| 类型 | 说明 | 3769|----------------|-----------------| 3770| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3771 3772**错误码：** 3773 3774以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 3775 3776| 错误码ID | 错误信息 | 3777| -------- | ---------------------------------------- | 3778| 17000002 | The async function is not called with await. | 3779| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3780 3781**示例：** 3782 3783```ts 3784import { Driver } from '@kit.TestKit'; 3785 3786async function demo() { 3787 let driver: Driver = Driver.create(); 3788 await driver.fling({x: 500, y: 480},{x: 450, y: 480}, 5, 600); 3789} 3790``` 3791 3792### injectMultiPointerAction<sup>9+</sup> 3793 3794injectMultiPointerAction(pointers: PointerMatrix, speed?: number): Promise\<boolean> 3795 3796向设备注入多指操作，使用Promise异步回调。 3797 3798**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3799 3800**系统能力**：SystemCapability.Test.UiTest 3801 3802**参数：** 3803 3804| 参数名 | 类型 | 必填 | 说明 | 3805| -------- | -------------------------------- | ---- |--------------------------------------------------------| 3806| pointers | [PointerMatrix](#pointermatrix9) | 是 | 滑动轨迹，包括操作手指个数和滑动坐标序列。 | 3807| speed | number | 否 | 滑动速率，取值范围为200-40000的整数，默认值为600，不在范围内设为默认值为600，单位：px/s。 | 3808 3809**返回值：** 3810 3811| 类型 | 说明 | 3812| ----------------- | ------------------------------------- | 3813| Promise\<boolean> | Promise对象，返回操作是否成功完成。true：完成，false：未完成。 | 3814 3815**错误码：** 3816 3817以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 3818 3819| 错误码ID | 错误信息 | 3820| -------- | ---------------------------------------- | 3821| 17000002 | The async function is not called with await. | 3822| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3823 3824**示例：** 3825 3826```ts 3827import { Driver, PointerMatrix } from '@kit.TestKit'; 3828 3829async function demo() { 3830 let driver: Driver = Driver.create(); 3831 let pointers: PointerMatrix = PointerMatrix.create(2, 5); 3832 pointers.setPoint(0, 0, {x:250, y:480}); 3833 pointers.setPoint(0, 1, {x:250, y:440}); 3834 pointers.setPoint(0, 2, {x:250, y:400}); 3835 pointers.setPoint(0, 3, {x:250, y:360}); 3836 pointers.setPoint(0, 4, {x:250, y:320}); 3837 pointers.setPoint(1, 0, {x:250, y:480}); 3838 pointers.setPoint(1, 1, {x:250, y:440}); 3839 pointers.setPoint(1, 2, {x:250, y:400}); 3840 pointers.setPoint(1, 3, {x:250, y:360}); 3841 pointers.setPoint(1, 4, {x:250, y:320}); 3842 await driver.injectMultiPointerAction(pointers); 3843} 3844``` 3845 3846### fling<sup>10+</sup> 3847 3848fling(direction: UiDirection, speed: number): Promise\<void>; 3849 3850指定方向和速度，模拟手指滑动后脱离屏幕的快速滑动操作，使用Promise异步回调。 3851 3852**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3853 3854**系统能力**：SystemCapability.Test.UiTest 3855 3856**参数：** 3857 3858| 参数名 | 类型 | 必填 | 说明 | 3859| --------- | ----------------------------- | ---- |--------------------------------------------------------| 3860| direction | [UiDirection](#uidirection10) | 是 | 进行抛滑的方向。 | 3861| speed | number | 是 | 滑动速率，取值范围为200-40000的整数，默认值为600，不在范围内设为默认值为600，单位：px/s。 | 3862 3863**返回值：** 3864 3865| 类型 | 说明 | 3866|----------------|-----------------| 3867| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3868 3869**错误码：** 3870 3871以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 3872 3873| 错误码ID | 错误信息 | 3874| -------- | ------------------------------------------------------------ | 3875| 17000002 | The async function is not called with await. | 3876| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3877 3878**示例：** 3879 3880```ts 3881import { Driver, UiDirection } from '@kit.TestKit'; 3882async function demo() { 3883 let driver: Driver = Driver.create(); 3884 await driver.fling(UiDirection.DOWN, 10000); 3885} 3886``` 3887 3888### fling<sup>20+</sup> 3889 3890fling(direction: UiDirection, speed: number, displayId: number): Promise\<void> 3891 3892指定方向和速度，模拟手指滑动后脱离屏幕的快速滑动操作，使用Promise异步回调。 3893 3894**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 3895 3896**系统能力**：SystemCapability.Test.UiTest 3897 3898**参数：** 3899 3900| 参数名 | 类型 | 必填 | 说明 | 3901| --------- | ----------------------------- | ---- |--------------------------------------------------------| 3902| direction | [UiDirection](#uidirection10) | 是 | 进行抛滑的方向。 | 3903| speed | number | 是 | 滑动速率，取值范围为200-40000，默认值为600，不在范围内设为默认值为600，单位：px/s。 | 3904| displayId | number | 是 | 指定设备屏幕ID。取值范围：大于等于0的整数。 <br> **说明：** 传入displayId不存在时，将抛出17000007异常。 | 3905 3906**返回值：** 3907 3908| 类型 | 说明 | 3909|----------------|-----------------| 3910| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3911 3912**错误码：** 3913 3914以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 3915 3916| 错误码ID | 错误信息 | 3917| -------- | ------------------------------------------------------------ | 3918| 17000002 | The async function is not called with await. | 3919| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3920 3921**示例：** 3922 3923```ts 3924import { Driver, UiDirection } from '@kit.TestKit'; 3925 3926async function demo() { 3927 let driver: Driver = Driver.create(); 3928 await driver.fling(UiDirection.DOWN, 10000, 0); 3929} 3930``` 3931 3932### screenCapture<sup>10+</sup> 3933 3934screenCapture(savePath: string, rect?: Rect): Promise\<boolean>; 3935 3936捕获当前屏幕的指定区域，并保存为PNG格式的图片至给出的保存路径中，使用Promise异步回调。适用于支持截屏的场景。 3937 3938**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3939 3940**系统能力**：SystemCapability.Test.UiTest 3941 3942**参数：** 3943 3944| 参数名 | 类型 | 必填 | 说明 | 3945| -------- | -------------- | ---- | ------------------------------------------ | 3946| savePath | string | 是 | 文件保存路径。路径需为当前应用的[沙箱路径](../../file-management/app-sandbox-directory.md)。 | 3947| rect | [Rect](#rect9) | 否 | 截图区域，默认为全屏。 | 3948 3949**返回值：** 3950 3951| 类型 | 说明 | 3952| ----------------- |---------------------------------------------| 3953| Promise\<boolean> | Promise对象，返回截图操作是否成功完成。true：成功完成，false：未成功完成。 | 3954 3955**错误码：** 3956 3957以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 3958 3959| 错误码ID | 错误信息 | 3960| -------- | ------------------------------------------------------------ | 3961| 17000002 | The async function is not called with await. | 3962| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 3963 3964**示例：** 3965 3966```ts 3967import { Driver } from '@kit.TestKit'; 3968async function demo() { 3969 let driver: Driver = Driver.create(); 3970 await driver.screenCapture('/data/storage/el2/base/cache/1.png', {left: 0, top: 0, right: 100, bottom: 100}); 3971} 3972``` 3973 3974### mouseClick<sup>10+</sup> 3975 3976mouseClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise\<void>; 3977 3978在指定坐标点注入鼠标点击动作，支持同时按下对应键盘组合键，使用Promise异步回调。例如，Key值为2072时，按下Ctrl并进行鼠标点击动作。 3979 3980**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3981 3982**系统能力**：SystemCapability.Test.UiTest 3983 3984**参数：** 3985 3986| 参数名 | 类型 | 必填 | 说明 | 3987| ------ | ----------------------------- | ---- | ------------------------------ | 3988| p | [Point](#point9) | 是 | 鼠标点击的坐标。 | 3989| btnId | [MouseButton](#mousebutton10) | 是 | 按下的鼠标按钮。 | 3990| key1 | number | 否 | 指定的第一个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)，默认值为0。 | 3991| key2 | number | 否 | 指定的第二个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)，默认值为0。 | 3992 3993**返回值：** 3994 3995| 类型 | 说明 | 3996|----------------|-----------------| 3997| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3998 3999**错误码：** 4000 4001以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4002 4003| 错误码ID | 错误信息 | 4004| -------- | ------------------------------------------------------------ | 4005| 17000002 | The async function is not called with await. | 4006| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4007 4008**示例：** 4009 4010```ts 4011import { Driver,MouseButton } from '@kit.TestKit'; 4012async function demo() { 4013 let driver: Driver = Driver.create(); 4014 await driver.mouseClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072); 4015} 4016``` 4017 4018### mouseScroll<sup>10+</sup> 4019 4020mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number): Promise\<void>; 4021 4022在指定坐标点注入鼠标滚轮滑动动作，支持同时按下对应键盘组合键，使用Promise异步回调。例如，Key值为2072时，按下Ctrl并进行鼠标滚轮滑动动作。 4023 4024**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4025 4026**系统能力**：SystemCapability.Test.UiTest 4027 4028**参数：** 4029 4030| 参数名 | 类型 | 必填 | 说明 | 4031| ------ | ---------------- | ---- | ----------------------------------------------------------- | 4032| p | [Point](#point9) | 是 | 鼠标点击的坐标。 | 4033| down | boolean | 是 | 滚轮滑动方向是否向下。true表示向下滑动。false表示向上滚动。 | 4034| d | number | 是 | 鼠标滚轮滚动的格数，取值大于等于0的整数，每格对应目标点位移120px。 | 4035| key1 | number | 否 | 指定的第一个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)，默认值为0。 | 4036| key2 | number | 否 | 指定的第二个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)，默认值为0。 | 4037 4038**返回值：** 4039 4040| 类型 | 说明 | 4041|----------------|-----------------| 4042| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4043 4044**错误码：** 4045 4046以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4047 4048| 错误码ID | 错误信息 | 4049| -------- | ------------------------------------------------------------ | 4050| 17000002 | The async function is not called with await. | 4051| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4052 4053**示例：** 4054 4055```ts 4056import { Driver } from '@kit.TestKit'; 4057 4058async function demo() { 4059 let driver: Driver = Driver.create(); 4060 await driver.mouseScroll({x:360, y:640}, true, 30, 2072); 4061} 4062``` 4063 4064### mouseMoveTo<sup>10+</sup> 4065 4066mouseMoveTo(p: Point): Promise\<void>; 4067 4068将鼠标光标移到目标点，使用Promise异步回调。 4069 4070**系统能力**：SystemCapability.Test.UiTest 4071 4072**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4073 4074**参数：** 4075 4076| 参数名 | 类型 | 必填 | 说明 | 4077| ------ | ---------------- | ---- | -------------- | 4078| p | [Point](#point9) | 是 | 目标点的坐标。 | 4079 4080**返回值：** 4081 4082| 类型 | 说明 | 4083|----------------|-----------------| 4084| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4085 4086**错误码：** 4087 4088以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4089 4090| 错误码ID | 错误信息 | 4091| -------- | ------------------------------------------------------------ | 4092| 17000002 | The async function is not called with await. | 4093| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4094 4095**示例：** 4096 4097```ts 4098import { Driver } from '@kit.TestKit'; 4099 4100async function demo() { 4101 let driver: Driver = Driver.create(); 4102 await driver.mouseMoveTo({x:100, y:100}); 4103} 4104``` 4105 4106### createUIEventObserver<sup>10+</sup> 4107 4108createUIEventObserver(): UIEventObserver; 4109 4110创建一个UI事件监听器。 4111 4112**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4113 4114**系统能力**：SystemCapability.Test.UiTest 4115 4116**返回值：** 4117 4118| 类型 | 说明 | 4119| ------------------------------------ | ------------------------------------- | 4120|[UIEventObserver](#uieventobserver10) | 返回找到的目标窗口对象。 | 4121 4122**错误码：** 4123 4124以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 4125 4126| 错误码ID | 错误信息 | 4127| -------- | ---------------------------------------- | 4128| 17000002 | The async function is not called with await. | 4129 4130**示例：** 4131 4132```ts 4133import { Driver, UIEventObserver } from '@kit.TestKit'; 4134 4135async function demo() { 4136 let driver: Driver = Driver.create(); 4137 let observer: UIEventObserver = await driver.createUIEventObserver(); 4138} 4139``` 4140 4141### mouseScroll<sup>11+</sup> 4142 4143mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number, speed?: number): Promise\<void> 4144 4145在指定坐标点注入鼠标滚轮滑动动作，支持同时按下对应键盘组合键并且指定滑动速度，使用Promise异步回调。 4146 4147**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4148 4149**系统能力**：SystemCapability.Test.UiTest 4150 4151**参数：** 4152 4153| 参数名 | 类型 | 必填 | 说明 | 4154| ------ | ---------------- | ---- | ------------------------------------------------------------ | 4155| p | [Point](#point9) | 是 | 鼠标点击的坐标。 | 4156| down | boolean | 是 | 滚轮滑动方向是否向下。true表示向下滑动。false表示向上滚动。 | 4157| d | number | 是 | 鼠标滚轮滚动的格数，取值大于等于0的整数，每格对应目标点位移120px。 | 4158| key1 | number | 否 | 指定的第一个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)，默认值为0。 | 4159| key2 | number | 否 | 指定的第二个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)，默认值为0。 | 4160| speed | number | 否 | 鼠标滚轮滚动的速度，范围：1-500的整数，不在范围内设为默认值为20，单位：格/秒。 | 4161 4162**返回值：** 4163 4164| 类型 | 说明 | 4165|----------------|-----------------| 4166| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4167 4168**错误码：** 4169 4170以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4171 4172| 错误码ID | 错误信息 | 4173| -------- | ------------------------------------------------------------ | 4174| 17000002 | The async function is not called with await. | 4175| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4176 4177**示例：** 4178 4179```ts 4180import { Driver } from '@kit.TestKit'; 4181 4182async function demo() { 4183 let driver: Driver = Driver.create(); 4184 await driver.mouseScroll({x:360, y:640}, true, 30, 2072,20); 4185} 4186``` 4187 4188### mouseDoubleClick<sup>11+</sup> 4189 4190mouseDoubleClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise\<void> 4191 4192在指定坐标点注入鼠标双击动作，支持同时按下对应键盘组合键，使用Promise异步回调。例如，Key值为2072时，按下Ctrl并进行鼠标双击动作。 4193 4194**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4195 4196**系统能力**：SystemCapability.Test.UiTest 4197 4198**参数：** 4199 4200| 参数名 | 类型 | 必填 | 说明 | 4201| ------ | ----------------------------- | ---- | ------------------------------ | 4202| p | [Point](#point9) | 是 | 鼠标双击的坐标。 | 4203| btnId | [MouseButton](#mousebutton10) | 是 | 按下的鼠标按钮。 | 4204| key1 | number | 否 | 指定的第一个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)，默认值0。 | 4205| key2 | number | 否 | 指定的第二个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)，默认值0。 | 4206 4207**返回值：** 4208 4209| 类型 | 说明 | 4210|----------------|-----------------| 4211| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4212 4213**错误码：** 4214 4215以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4216 4217| 错误码ID | 错误信息 | 4218| -------- | ------------------------------------------------------------ | 4219| 17000002 | The async function is not called with await. | 4220| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4221 4222**示例：** 4223 4224```ts 4225import { Driver,MouseButton } from '@kit.TestKit'; 4226async function demo() { 4227 let driver: Driver = Driver.create(); 4228 await driver.mouseDoubleClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072); 4229} 4230``` 4231 4232### mouseLongClick<sup>11+</sup> 4233 4234mouseLongClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise\<void> 4235 4236在指定坐标点注入鼠标长按动作，支持同时按下对应键盘组合键，使用Promise异步回调。例如，Key值为2072时，按下Ctrl并进行鼠标长按动作。 4237 4238**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4239 4240**系统能力**：SystemCapability.Test.UiTest 4241 4242**参数：** 4243 4244| 参数名 | 类型 | 必填 | 说明 | 4245| ------ | ----------------------------- | ---- | ------------------------------ | 4246| p | [Point](#point9) | 是 | 鼠标长按的坐标。 | 4247| btnId | [MouseButton](#mousebutton10) | 是 | 按下的鼠标按钮。 | 4248| key1 | number | 否 | 指定的第一个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)，默认值为0。 | 4249| key2 | number | 否 | 指定的第二个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)，默认值为0。 | 4250 4251**返回值：** 4252 4253| 类型 | 说明 | 4254|----------------|-----------------| 4255| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4256 4257**错误码：** 4258 4259以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4260 4261| 错误码ID | 错误信息 | 4262| -------- | ------------------------------------------------------------ | 4263| 17000002 | The async function is not called with await. | 4264| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4265 4266**示例：** 4267 4268```ts 4269import { Driver,MouseButton } from '@kit.TestKit'; 4270async function demo() { 4271 let driver:Driver = Driver.create(); 4272 await driver.mouseLongClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072); 4273} 4274``` 4275 4276### mouseLongClick<sup>20+</sup> 4277 4278mouseLongClick(p: Point, btnId: MouseButton, key1?: number, key2?: number, duration?: number): Promise\<void> 4279 4280在指定坐标点注入鼠标长按动作，支持同时按下对应键盘组合键，支持指定长按时长，使用Promise异步回调。例如，Key值为2072时，按下Ctrl并进行鼠标长按动作。 4281 4282**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 4283 4284**系统能力**：SystemCapability.Test.UiTest 4285 4286**参数：** 4287 4288| 参数名 | 类型 | 必填 | 说明 | 4289| -------- | ----------------------------- | ---- | ------------------------------ | 4290| p | [Point](#point9) | 是 | 鼠标长按的坐标。 | 4291| btnId | [MouseButton](#mousebutton10) | 是 | 按下的鼠标按钮。 | 4292| key1 | number | 否 | 指定的第一个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)，默认值为0。 | 4293| key2 | number | 否 | 指定的第二个key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)，默认值为0。 | 4294| duration | number | 否 | 长按持续的时间，取值范围为大于等于1500的整数，默认值为1500，单位：ms。 | 4295 4296**返回值：** 4297 4298| 类型 | 说明 | 4299|----------------|-----------------| 4300| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4301 4302**错误码：** 4303 4304以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4305 4306| 错误码ID | 错误信息 | 4307| -------- | ------------------------------------------------------------ | 4308| 17000002 | The async function is not called with await. | 4309| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4310 4311**示例：** 4312 4313```ts 4314import { Driver,MouseButton } from '@kit.TestKit'; 4315 4316async function demo() { 4317 let driver:Driver = Driver.create(); 4318 await driver.mouseLongClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072, 0, 2000); 4319} 4320``` 4321 4322### mouseMoveWithTrack<sup>11+</sup> 4323 4324mouseMoveWithTrack(from: Point, to: Point, speed?: number): Promise\<void> 4325 4326鼠标从起始坐标点滑向终点坐标点，使用Promise异步回调。 4327 4328**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4329 4330**系统能力**：SystemCapability.Test.UiTest 4331 4332**参数：** 4333 4334| 参数名 | 类型 | 必填 | 说明 | 4335| ------ | ---------------- | ---- |--------------------------------------------------------| 4336| from | [Point](#point9) | 是 | 起始点坐标。 | 4337| to | [Point](#point9) | 是 | 终点坐标。 | 4338| speed | number | 否 | 滑动速率，取值范围为200-40000的整数，默认值为600，不在范围内设为默认值为600，单位：px/s。 | 4339 4340**返回值：** 4341 4342| 类型 | 说明 | 4343|----------------|-----------------| 4344| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4345 4346**错误码：** 4347 4348以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4349 4350| 错误码ID | 错误信息 | 4351| -------- | ------------------------------------------------------------ | 4352| 17000002 | The async function is not called with await. | 4353| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4354 4355**示例：** 4356 4357```ts 4358import { Driver } from '@kit.TestKit'; 4359 4360async function demo() { 4361 let driver: Driver = Driver.create(); 4362 await driver.mouseMoveWithTrack({x:100, y:100}, {x:200, y:200}, 600); 4363} 4364``` 4365 4366### mouseDrag<sup>11+</sup> 4367 4368mouseDrag(from: Point, to: Point, speed?: number): Promise\<void> 4369 4370鼠标按住鼠标左键从起始坐标点拖拽至终点坐标点，使用Promise异步回调。 4371 4372**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4373 4374**系统能力**：SystemCapability.Test.UiTest 4375 4376**设备行为差异**：该接口在Phone、Tablet、PC/2in1、TV设备上生效，在其他设备中调用无效果。 4377 4378**参数：** 4379 4380| 参数名 | 类型 | 必填 | 说明 | 4381| ------ | ---------------- | ---- |--------------------------------------------------------| 4382| from | [Point](#point9) | 是 | 起始点坐标。 | 4383| to | [Point](#point9) | 是 | 终点坐标。 | 4384| speed | number | 否 | 滑动速率，取值范围为200-40000的整数，默认值为600，不在范围内设为默认值为600，单位：px/s。 | 4385 4386**返回值：** 4387 4388| 类型 | 说明 | 4389|----------------|-----------------| 4390| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4391 4392**错误码：** 4393 4394以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4395 4396| 错误码ID | 错误信息 | 4397| -------- | ------------------------------------------------------------ | 4398| 17000002 | The async function is not called with await. | 4399| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4400 4401**示例：** 4402 4403```ts 4404import { Driver } from '@kit.TestKit'; 4405 4406async function demo() { 4407 let driver: Driver = Driver.create(); 4408 await driver.mouseDrag({x:100, y:100},{x:200, y:200}, 600); 4409} 4410``` 4411 4412### mouseDrag<sup>20+</sup> 4413 4414mouseDrag(from: Point, to: Point, speed?: number, duration?: number): Promise\<void> 4415 4416鼠标按住鼠标左键从起始坐标点拖拽至终点坐标点，支持指定拖拽速度和拖拽前长按时间，使用Promise异步回调。 4417 4418**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 4419 4420**系统能力**：SystemCapability.Test.UiTest 4421 4422**设备行为差异**：该接口在Phone、Tablet、PC/2in1、TV设备上生效，在其他设备中调用无效果。 4423 4424**参数：** 4425 4426| 参数名 | 类型 | 必填 | 说明 | 4427| --------- | ---------------- | ---- |--------------------------------------------------------| 4428| from | [Point](#point9) | 是 | 起始点坐标。 | 4429| to | [Point](#point9) | 是 | 终点坐标。 | 4430| speed | number | 否 | 滑动速率，取值范围为200-40000的整数，默认值为600，不在范围内设为默认值为600，单位：px/s。 | 4431| duration | number | 否 | 拖拽前长按持续的时间，取值范围为大于等于1500的整数，默认值为1500，单位：ms。 | 4432 4433**返回值：** 4434 4435| 类型 | 说明 | 4436|----------------|-----------------| 4437| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4438 4439**错误码：** 4440 4441以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4442 4443| 错误码ID | 错误信息 | 4444| -------- | ------------------------------------------------------------ | 4445| 17000002 | The async function is not called with await. | 4446| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4447 4448**示例：** 4449 4450```ts 4451import { Driver } from '@kit.TestKit'; 4452 4453async function demo() { 4454 let driver: Driver = Driver.create(); 4455 await driver.mouseDrag({x:100, y:100},{x:200, y:200}, 600, 2000); 4456} 4457``` 4458 4459### inputText<sup>11+</sup> 4460 4461inputText(p: Point, text: string): Promise\<void> 4462 4463在指定坐标点输入文本，不清空组件内原有文本，直接在坐标处追加输入，使用Promise异步回调。 4464 4465**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4466 4467**系统能力**：SystemCapability.Test.UiTest 4468 4469**参数：** 4470 4471| 参数名 | 类型 | 必填 | 说明 | 4472| ------ | ---------------- | ---- | ------------------ | 4473| p | [Point](#point9) | 是 | 输入文本的坐标点。 | 4474| text | string | 是 |输入的文本信息，当前支持英文、中文和特殊字符。| 4475 4476**返回值：** 4477 4478| 类型 | 说明 | 4479|----------------|-----------------| 4480| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4481 4482**错误码：** 4483 4484以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4485 4486| 错误码ID | 错误信息 | 4487| -------- | ------------------------------------------------------------ | 4488| 17000002 | The async function is not called with await. | 4489| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4490 4491**示例：** 4492 4493```ts 4494import { Component, Driver, ON } from '@kit.TestKit'; 4495async function demo() { 4496 let driver:Driver = Driver.create(); 4497 let text: Component = await driver.findComponent(ON.type('TextInput')); 4498 let point = await text.getBoundsCenter(); 4499 await driver.inputText(point, '123'); 4500} 4501``` 4502 4503### inputText<sup>20+</sup> 4504 4505inputText(p: Point, text: string, mode: InputTextMode): Promise\<void> 4506 4507在指定坐标点输入文本，支持指定文本输入方式，使用Promise异步回调。 4508 4509**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 4510 4511**系统能力**：SystemCapability.Test.UiTest 4512 4513**参数：** 4514 4515| 参数名 | 类型 | 必填 | 说明 | 4516| ------ | ---------------- | ---- | ------------------ | 4517| p | [Point](#point9) | 是 | 输入文本的坐标点。 | 4518| text | string | 是 |输入的文本信息，当前支持英文、中文和特殊字符。 | 4519| mode | [InputTextMode](#inputtextmode20) | 是 | 输入文本的方式，取值请参考[InputTextMode](#inputtextmode20)。 <br> **说明：** <br> InputTextMode.addition取值为ture时，将光标移动至文本末尾后输入指定文本。取值为false时，将在坐标点位置输入指定文本。 | 4520 4521**返回值：** 4522 4523| 类型 | 说明 | 4524|----------------|-----------------| 4525| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4526 4527**错误码：** 4528 4529以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4530 4531| 错误码ID | 错误信息 | 4532| -------- | ------------------------------------------------------------ | 4533| 17000002 | The async function is not called with await. | 4534| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4535| 801 | Capability not support, function can not work correctly due to limited device capabilities.| 4536 4537**示例：** 4538 4539```ts 4540import { Component, Driver, ON } from '@kit.TestKit'; 4541 4542async function demo() { 4543 let driver: Driver = Driver.create(); 4544 let text: Component = await driver.findComponent(ON.type('TextInput')); 4545 let point = await text.getBoundsCenter(); 4546 await driver.inputText(point, '123', {paste: true, addition: false}); 4547} 4548 4549async function demo_Chinese() { 4550 let driver: Driver = Driver.create(); 4551 let text: Component = await driver.findComponent(ON.type('TextInput')); 4552 let point = await text.getBoundsCenter(); 4553 await driver.inputText(point, '中文&', { paste: false, addition: true }); 4554 // 以复制粘贴方式输入中文、特殊符号， 指定文本追加到指定坐标所在文本段的末尾。 4555} 4556``` 4557 4558### touchPadMultiFingerSwipe<sup>18+</sup> 4559 4560touchPadMultiFingerSwipe(fingers: number, direction: UiDirection, options?: TouchPadSwipeOptions): Promise\<void> 4561 4562模拟触摸板多指滑动手势，使用Promise异步回调。 4563 4564**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 4565 4566**系统能力**：SystemCapability.Test.UiTest 4567 4568**设备行为差异**：该接口在PC/2in1设备中可正常调用，在其他设备中返回17000005错误码。 4569 4570**参数：** 4571 4572| 参数名 | 类型 | 必填 | 说明 | 4573| ------ |-----------------------------------------------|----|-----------------------| 4574| fingers | number | 是 | 触摸板多指滑动的手指数。取值为3或者4。 | 4575| direction | [UiDirection](#uidirection10) | 是 | 触摸板多指滑动的方向。 | 4576| options | [TouchPadSwipeOptions](#touchpadswipeoptions18) | 否 | 触摸板多指滑动手势附加选项。 | 4577 4578**返回值：** 4579 4580| 类型 | 说明 | 4581|----------------|-----------------| 4582| Promise\<void> | Promise对象，返回无结果的Promise对象。 | 4583 4584**错误码：** 4585 4586以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4587 4588| 错误码ID | 错误信息 | 4589| -------- | ------------------------------------------------------------ | 4590| 17000002 | The async function is not called with await. | 4591| 17000005 | This operation is not supported. | 4592| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4593 4594**示例：** 4595 4596```ts 4597import { Driver, UiDirection } from '@kit.TestKit'; 4598async function demo() { 4599 let driver:Driver = Driver.create(); 4600 await driver.touchPadMultiFingerSwipe(3, UiDirection.UP); 4601} 4602``` 4603 4604### penClick<sup>18+</sup> 4605 4606penClick(point: Point): Promise\<void> 4607 4608模拟手写笔点击操作，使用Promise异步回调。 4609 4610**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 4611 4612**系统能力**：SystemCapability.Test.UiTest 4613 4614**参数：** 4615 4616| 参数名 | 类型 | 必填 | 说明 | 4617| ------ |-----------------------------------------------|----|---------| 4618| point | [Point](#point9) | 是 | 点击的坐标点。 | 4619 4620**返回值：** 4621 4622| 类型 | 说明 | 4623|----------------|-----------------| 4624| Promise\<void> | Promise对象，返回无结果的Promise对象。 | 4625 4626**错误码：** 4627 4628以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4629 4630| 错误码ID | 错误信息 | 4631| -------- | ------------------------------------------------------------ | 4632| 17000002 | The async function is not called with await. | 4633| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4634 4635**示例：** 4636 4637```ts 4638import { Driver } from '@kit.TestKit'; 4639async function demo() { 4640 let driver: Driver = Driver.create(); 4641 await driver.penClick({x: 100, y: 100}); 4642} 4643``` 4644 4645### penLongClick<sup>18+</sup> 4646 4647penLongClick(point: Point, pressure?: number): Promise\<void> 4648 4649模拟手写笔长按操作，使用Promise异步回调。 4650 4651**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 4652 4653**系统能力**：SystemCapability.Test.UiTest 4654 4655**参数：** 4656 4657| 参数名 | 类型 | 必填 | 说明 | 4658| ------ |-----------------------------------------------|----|-------------------------------| 4659| point | [Point](#point9) | 是 | 长按的坐标点。 | 4660| pressure | number | 否 | 手写笔滑动操作的压力，默认为1.0，取值范围为0.0到1.0。 | 4661 4662**返回值：** 4663 4664| 类型 | 说明 | 4665|----------------|-----------------| 4666| Promise\<void> | Promise对象，返回无结果的Promise对象。 | 4667 4668**错误码：** 4669 4670以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4671 4672| 错误码ID | 错误信息 | 4673| -------- | ------------------------------------------------------------ | 4674| 17000002 | The async function is not called with await. | 4675| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4676 4677**示例：** 4678 4679```ts 4680import { Driver } from '@kit.TestKit'; 4681async function demo() { 4682 let driver: Driver = Driver.create(); 4683 await driver.penLongClick({x: 100, y: 100}, 0.5); 4684} 4685``` 4686 4687### penDoubleClick<sup>18+</sup> 4688 4689penDoubleClick(point: Point): Promise\<void> 4690 4691模拟手写笔双击操作，使用Promise异步回调。 4692 4693**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 4694 4695**系统能力**：SystemCapability.Test.UiTest 4696 4697**参数：** 4698 4699| 参数名 | 类型 | 必填 | 说明 | 4700| ------ |-----------------------------------------------|----|---------| 4701| point | [Point](#point9) | 是 | 双击的坐标点。 | 4702 4703 4704**返回值：** 4705 4706| 类型 | 说明 | 4707|----------------|-----------------| 4708| Promise\<void> | Promise对象，返回无结果的Promise对象。 | 4709 4710**错误码：** 4711 4712以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4713 4714| 错误码ID | 错误信息 | 4715| -------- | ------------------------------------------------------------ | 4716| 17000002 | The async function is not called with await. | 4717| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4718 4719**示例：** 4720 4721```ts 4722import { Driver } from '@kit.TestKit'; 4723async function demo() { 4724 let driver: Driver = Driver.create(); 4725 await driver.penDoubleClick({x: 100, y: 100}); 4726} 4727``` 4728 4729### penSwipe<sup>18+</sup> 4730 4731penSwipe(startPoint: Point, endPoint: Point, speed?: number, pressure?: number): Promise\<void> 4732 4733模拟手写笔的滑动操作，使用Promise异步回调。 4734 4735**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 4736 4737**系统能力**：SystemCapability.Test.UiTest 4738 4739**参数：** 4740 4741| 参数名 | 类型 | 必填 | 说明 | 4742| ------ |-----------------------------------------------|----|--------------------------------------------------------| 4743| startPoint | [Point](#point9) | 是 | 起始位置的坐标点。 | 4744| endPoint | [Point](#point9) | 是 | 结束位置的坐标点。 | 4745| speed | number | 否 | 滑动速率，取值范围为200-40000的整数，默认值为600，不在范围内设为默认值为600，单位：px/s。 | 4746| pressure | number | 否 | 手写笔滑动操作的压力，默认为1.0，取值范围为0.0到1.0。 | 4747 4748**返回值：** 4749 4750| 类型 | 说明 | 4751|----------------|-----------------| 4752| Promise\<void> | Promise对象，返回无结果的Promise对象。 | 4753 4754**错误码：** 4755 4756以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4757 4758| 错误码ID | 错误信息 | 4759| -------- | ------------------------------------------------------------ | 4760| 17000002 | The async function is not called with await. | 4761| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4762 4763**示例：** 4764 4765```ts 4766 import { Driver } from '@kit.TestKit'; 4767async function demo() { 4768 let driver: Driver = Driver.create(); 4769 await driver.penSwipe({x: 100, y: 100}, {x: 100, y: 500}, 600, 0.5); 4770} 4771``` 4772 4773### injectPenPointerAction<sup>18+</sup> 4774 4775injectPenPointerAction(pointers: PointerMatrix, speed?: number, pressure?: number): Promise\<void> 4776 4777模拟手写笔多点连续注入操作，使用Promise异步回调。 4778 4779**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 4780 4781**系统能力**：SystemCapability.Test.UiTest 4782 4783**参数：** 4784 4785| 参数名 | 类型 | 必填 | 说明 | 4786| ------ |-----------------------------------------------|----|-------------------------------------------------------------------| 4787| pointers | [PointerMatrix](#pointermatrix9) | 是 |滑动轨迹，包括操作手指个数和滑动坐标序列。当前仅支持单指操作，PointerMatrix中的操作手指个数fingers必须设置为1。 | 4788| speed | number| 否 | 滑动速率，取值范围为200-40000的整数，默认值为600，不在范围内设为默认值为600，单位：px/s。 | 4789| pressure | number | 否 | 手写笔多点连续注入的压力，默认为1.0，取值范围为0.0到1.0。 | 4790 4791 4792**返回值：** 4793 4794| 类型 | 说明 | 4795|----------------|-----------------| 4796| Promise\<void> | Promise对象，返回无结果的Promise对象。 | 4797 4798**错误码：** 4799 4800以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4801 4802| 错误码ID | 错误信息 | 4803| -------- | ------------------------------------------------------------ | 4804| 17000002 | The async function is not called with await. | 4805| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4806 4807**示例：** 4808 4809```ts 4810import { Driver, PointerMatrix } from '@kit.TestKit'; 4811async function demo() { 4812 let driver: Driver = Driver.create(); 4813 let pointer = PointerMatrix.create(1, 8); 4814 for (let step = 0; step < 8; step++) { 4815 pointer.setPoint(0, step, {x: 500, y: 1100 - 100 *step}); 4816 } 4817 await driver.injectPenPointerAction(pointer, 600, 0.5); 4818} 4819``` 4820 4821### crownRotate<sup>20+</sup> 4822 4823crownRotate(d: number, speed?: number): Promise\<void> 4824 4825注入手表表冠旋转事件，可指定旋转速度，使用Promise异步回调。 4826 4827**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 4828 4829**系统能力**：SystemCapability.Test.UiTest 4830 4831**设备行为差异**：该接口在Wearable设备中可正常调用，在其他设备中返回801错误码。 4832 4833**参数：** 4834 4835| 参数名 | 类型 | 必填 | 说明 | 4836| ------ |-----------------------------------------------|----|-------------------------------------------------------------------| 4837| d | number | 是 | 手表表冠旋转的格数，正值表示顺时针旋转，负值表示逆时针旋转，取值需为整数。 | 4838| speed | number | 否 | 手表表冠旋转的速度，取值范围：1-500的整数，默认值为20，单位：格/秒。<br> **说明：** 参数取值超出合法范围时，设为默认值20。 | 4839 4840**返回值：** 4841 4842| 类型 | 说明 | 4843|----------------|-----------------| 4844| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 4845 4846**错误码：** 4847 4848以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 4849 4850| 错误码ID | 错误信息 | 4851| -------- | ------------------------------------------------------------ | 4852| 17000002 | The async function is not called with await. | 4853| 17000007 | Parameter verification failed. | 4854| 801 | Capability not support, function can not work correctly due to limited device capabilities. | 4855 4856**示例：** 4857 4858```ts 4859import { Driver } from '@kit.TestKit'; 4860 4861async function demo() { 4862 let driver: Driver = Driver.create(); 4863 // 顺时针旋转50格，旋转速度为30格/秒 4864 await driver.crownRotate(50, 30); 4865 // 逆时针旋转20格，旋转速度为30格/秒 4866 await driver.crownRotate(-20, 30); 4867} 4868``` 4869 4870## PointerMatrix<sup>9+</sup> 4871 4872存储多指操作中每根手指每一步动作的坐标点及其行为的二维数组。 4873 4874### create<sup>9+</sup> 4875 4876static create(fingers: number, steps: number): PointerMatrix 4877 4878静态方法，构造一个PointerMatrix对象，并返回该对象。 4879 4880**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4881 4882**系统能力**：SystemCapability.Test.UiTest 4883 4884**参数：** 4885 4886| 参数名 | 类型 | 必填 | 说明 | 4887| ------- | ------ | ---- | ------------------------------------------ | 4888| fingers | number | 是 | 多指操作中注入的手指数，取值范围：[1,10]的整数。 | 4889| steps | number | 是 | 每根手指操作的步骤数，取值范围：[1,1000]的整数。 | 4890 4891**返回值：** 4892 4893| 类型 | 说明 | 4894| -------------------------------- | ----------------------------- | 4895| [PointerMatrix](#pointermatrix9) | 返回构造的PointerMatrix对象。 | 4896 4897**错误码：** 4898 4899以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 4900 4901| 错误码ID | 错误信息 | 4902| -------- | ------------------------------------------------------------ | 4903| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4904 4905**示例：** 4906 4907```ts 4908import { PointerMatrix } from '@kit.TestKit'; 4909 4910async function demo() { 4911 let pointerMatrix: PointerMatrix = PointerMatrix.create(2, 3); 4912} 4913``` 4914 4915### setPoint<sup>9+</sup> 4916 4917setPoint(finger: number, step: number, point: Point): void 4918 4919设置PointerMatrix对象中指定手指和步骤对应动作的坐标点。 4920 4921**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4922 4923**系统能力**：SystemCapability.Test.UiTest 4924 4925**参数：** 4926 4927| 参数名 | 类型 | 必填 | 说明 | 4928| ------ | ---------------- | ---- | ---------------------------------------------------------- | 4929| finger | number | 是 | 手指的序号，取值大于等于0的整数，且不超过构造PointerMatrix对象时设置的手指数。 | 4930| step | number | 是 | 步骤的序号，取值大于等于0的整数，且不超过构造PointerMatrix对象时设置的操作的步骤数。 | 4931| point | [Point](#point9) | 是 | 该行为的坐标点。建议相邻的坐标点距离在10px至80px范围内。 | 4932 4933**错误码：** 4934 4935以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 4936 4937| 错误码ID | 错误信息 | 4938| -------- | ------------------------------------------------------------ | 4939| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 4940 4941**示例：** 4942 4943```ts 4944import { PointerMatrix } from '@kit.TestKit'; 4945 4946async function demo() { 4947 let pointers: PointerMatrix = PointerMatrix.create(2, 5); 4948 pointers.setPoint(0, 0, {x:250, y:480}); 4949 pointers.setPoint(0, 1, {x:250, y:440}); 4950 pointers.setPoint(0, 2, {x:250, y:400}); 4951 pointers.setPoint(0, 3, {x:250, y:360}); 4952 pointers.setPoint(0, 4, {x:250, y:320}); 4953 pointers.setPoint(1, 0, {x:250, y:480}); 4954 pointers.setPoint(1, 1, {x:250, y:440}); 4955 pointers.setPoint(1, 2, {x:250, y:400}); 4956 pointers.setPoint(1, 3, {x:250, y:360}); 4957 pointers.setPoint(1, 4, {x:250, y:320}); 4958} 4959``` 4960 4961## UiWindow<sup>9+</sup> 4962 4963UiWindow代表了UI界面上的一个窗口，提供窗口属性获取，窗口拖动、调整窗口大小等能力。 4964该类提供的所有方法都使用Promise方式作为异步方法，需使用await方式调用。 4965 4966### getBundleName<sup>9+</sup> 4967 4968getBundleName(): Promise\<string> 4969 4970获取窗口归属应用的包名信息，使用Promise异步回调。 4971 4972**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 4973 4974**系统能力**：SystemCapability.Test.UiTest 4975 4976**返回值：** 4977 4978| 类型 | 说明 | 4979| ---------------- | ----------------------------------------- | 4980| Promise\<string> | Promise对象，返回窗口归属应用的包名信息。 | 4981 4982**错误码：** 4983 4984以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 4985 4986| 错误码ID | 错误信息 | 4987| -------- | ---------------------------------------- | 4988| 17000002 | The async function is not called with await. | 4989| 17000004 | The window or component is invisible or destroyed. | 4990 4991**示例：** 4992 4993```ts 4994import { Driver, UiWindow } from '@kit.TestKit'; 4995 4996async function demo() { 4997 let driver: Driver = Driver.create(); 4998 let window: UiWindow = await driver.findWindow({actived: true}); 4999 let name: string = await window.getBundleName(); 5000} 5001``` 5002 5003### getBounds<sup>9+</sup> 5004 5005getBounds(): Promise\<Rect> 5006 5007获取窗口的边框信息，使用Promise异步回调。 5008 5009**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5010 5011**系统能力**：SystemCapability.Test.UiTest 5012 5013**返回值：** 5014 5015| 类型 | 说明 | 5016| ------------------------ | --------------------------------- | 5017| Promise\<[Rect](#rect9)> | Promise对象，返回窗口的边框信息。 | 5018 5019**错误码：** 5020 5021以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 5022 5023| 错误码ID | 错误信息 | 5024| -------- | ---------------------------------------- | 5025| 17000002 | The async function is not called with await. | 5026| 17000004 | The window or component is invisible or destroyed. | 5027 5028**示例：** 5029 5030```ts 5031import { Driver, UiWindow } from '@kit.TestKit'; 5032async function demo() { 5033 let driver: Driver = Driver.create(); 5034 let window: UiWindow = await driver.findWindow({actived: true}); 5035 let rect = await window.getBounds(); 5036} 5037``` 5038 5039### getTitle<sup>9+</sup> 5040 5041getTitle(): Promise\<string> 5042 5043获取窗口的标题信息，使用Promise异步回调。 5044 5045**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5046 5047**系统能力**：SystemCapability.Test.UiTest 5048 5049**返回值：** 5050 5051| 类型 | 说明 | 5052| ---------------- | --------------------------------- | 5053| Promise\<string> | Promise对象，返回窗口的标题信息。 | 5054 5055**错误码：** 5056 5057以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 5058 5059| 错误码ID | 错误信息 | 5060| -------- | ---------------------------------------- | 5061| 17000002 | The async function is not called with await. | 5062| 17000004 | The window or component is invisible or destroyed. | 5063 5064**示例：** 5065 5066```ts 5067import { Driver, UiWindow } from '@kit.TestKit'; 5068async function demo() { 5069 let driver: Driver = Driver.create(); 5070 let window: UiWindow = await driver.findWindow({actived: true}); 5071 let title = await window.getTitle(); 5072} 5073``` 5074 5075### getWindowMode<sup>9+</sup> 5076 5077getWindowMode(): Promise\<WindowMode> 5078 5079获取窗口的窗口模式信息，使用Promise异步回调。 5080 5081**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5082 5083**系统能力**：SystemCapability.Test.UiTest 5084 5085**返回值：** 5086 5087| 类型 | 说明 | 5088| ------------------------------------ | ------------------------------------- | 5089| Promise\<[WindowMode](#windowmode9)> | Promise对象，返回窗口的窗口模式信息。 | 5090 5091**错误码：** 5092 5093以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 5094 5095| 错误码ID | 错误信息 | 5096| -------- | ---------------------------------------- | 5097| 17000002 | The async function is not called with await. | 5098| 17000004 | The window or component is invisible or destroyed. | 5099 5100**示例：** 5101 5102```ts 5103import { Driver, UiWindow } from '@kit.TestKit'; 5104async function demo() { 5105 let driver: Driver = Driver.create(); 5106 let window: UiWindow = await driver.findWindow({actived: true}); 5107 let mode = await window.getWindowMode(); 5108} 5109``` 5110 5111### isFocused<sup>9+</sup> 5112 5113isFocused(): Promise\<boolean> 5114 5115判断窗口是否处于获焦状态，使用Promise异步回调。 5116 5117**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5118 5119**系统能力**：SystemCapability.Test.UiTest 5120 5121**返回值：** 5122 5123| 类型 | 说明 | 5124| ----------------- | ------------------------------------------------------------ | 5125| Promise\<boolean> | Promise对象，返回窗口对象是否获取获焦状态。true：获焦。false：未获焦。 | 5126 5127**错误码：** 5128 5129以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 5130 5131| 错误码ID | 错误信息 | 5132| -------- | ---------------------------------------- | 5133| 17000002 | The async function is not called with await. | 5134| 17000004 | The window or component is invisible or destroyed. | 5135 5136**示例：** 5137 5138```ts 5139import { Driver, UiWindow } from '@kit.TestKit'; 5140async function demo() { 5141 let driver: Driver = Driver.create(); 5142 let window: UiWindow = await driver.findWindow({actived: true}); 5143 let focused = await window.isFocused(); 5144} 5145``` 5146 5147### isActived<sup>(deprecated)</sup> 5148 5149isActived(): Promise\<boolean> 5150 5151判断窗口是否为用户正在交互窗口，使用Promise异步回调。 5152 5153从API version 9开始支持，从API version 11开始废弃，建议使用[isActive<sup>11+</sup>](#isactive11)替代。 5154 5155**系统能力**：SystemCapability.Test.UiTest 5156 5157**返回值：** 5158 5159| 类型 | 说明 | 5160| ----------------- | ------------------------------------------------------------ | 5161| Promise\<boolean> | Promise对象，返回窗口对象是否为用户正在交互窗口。true表示是交互窗口。false表示非交互窗口。 | 5162 5163**错误码：** 5164 5165以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 5166 5167| 错误码ID | 错误信息 | 5168| -------- | ---------------------------------------- | 5169| 17000002 | The async function is not called with await. | 5170| 17000004 | The window or component is invisible or destroyed. | 5171 5172**示例：** 5173 5174```ts 5175import { Driver, UiWindow } from '@kit.TestKit'; 5176async function demo() { 5177 let driver: Driver = Driver.create(); 5178 let window: UiWindow = await driver.findWindow({actived: true}); 5179 let focused = await window.isActived(); 5180} 5181``` 5182 5183### focus<sup>9+</sup> 5184 5185focus(): Promise\<void> 5186 5187让窗口获焦，使用Promise异步回调。 5188 5189**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5190 5191**系统能力**：SystemCapability.Test.UiTest 5192 5193**返回值：** 5194 5195| 类型 | 说明 | 5196|----------------|-----------------| 5197| Promise\<void> | Promise对象，返回无结果的Promise对象。 | 5198 5199**错误码：** 5200 5201以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 5202 5203| 错误码ID | 错误信息 | 5204| -------- | ---------------------------------------- | 5205| 17000002 | The async function is not called with await. | 5206| 17000004 | The window or component is invisible or destroyed. | 5207 5208**示例：** 5209 5210```ts 5211import { Driver, UiWindow } from '@kit.TestKit'; 5212async function demo() { 5213 let driver: Driver = Driver.create(); 5214 let window: UiWindow = await driver.findWindow({actived: true}); 5215 await window.focus(); 5216} 5217``` 5218 5219### moveTo<sup>9+</sup> 5220 5221moveTo(x: number, y: number): Promise\<void> 5222 5223将窗口移动到目标点，使用Promise异步回调。适用于支持移动的窗口。 5224 5225**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5226 5227**系统能力**：SystemCapability.Test.UiTest 5228 5229**设备行为差异**：该接口在PC/2in1、Tablet设备中可正常调用，在其他设备中返回17000005错误码。 5230 5231**参数：** 5232 5233| 参数名 | 类型 | 必填 | 说明 | 5234| ------ | ------ | ---- | ----------------------------------------------- | 5235| x | number | 是 | 以number的形式传入目标点的横坐标信息，取值范围：大于等于0的整数。 | 5236| y | number | 是 | 以number的形式传入目标点的纵坐标信息，取值范围：大于等于0的整数。 | 5237 5238**返回值：** 5239 5240| 类型 | 说明 | 5241|----------------|-----------------| 5242| Promise\<void> | Promise对象，返回无结果的Promise对象。 | 5243 5244**错误码：** 5245 5246以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 5247 5248| 错误码ID | 错误信息 | 5249| -------- | ---------------------------------------- | 5250| 17000002 | The async function is not called with await. | 5251| 17000004 | The window or component is invisible or destroyed. | 5252| 17000005 | This operation is not supported. | 5253| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 5254 5255**示例：** 5256 5257```ts 5258import { Driver, UiWindow } from '@kit.TestKit'; 5259async function demo() { 5260 let driver: Driver = Driver.create(); 5261 let window: UiWindow = await driver.findWindow({actived: true}); 5262 await window.moveTo(100, 100); 5263} 5264``` 5265 5266### resize<sup>9+</sup> 5267 5268resize(wide: number, height: number, direction: ResizeDirection): Promise\<void> 5269 5270根据传入的宽、高和调整方向来调整窗口的大小，使用Promise异步回调。适用于支持调整大小的窗口。 5271 5272**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5273 5274**系统能力**：SystemCapability.Test.UiTest 5275 5276**参数：** 5277 5278| 参数名 | 类型 | 必填 | 说明 | 5279| --------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 5280| wide | number | 是 | 以number的形式传入调整后窗口的宽度，取值范围：大于等于0的整数。 | 5281| height | number | 是 | 以number的形式传入调整后窗口的高度，取值范围：大于等于0的整数。 | 5282| direction | [ResizeDirection](#resizedirection9) | 是 | 以[ResizeDirection](#resizedirection9)的形式传入窗口调整的方向。 | 5283 5284**返回值：** 5285 5286| 类型 | 说明 | 5287|----------------|-----------------| 5288| Promise\<void> | Promise对象，返回无结果的Promise对象。 | 5289 5290**错误码：** 5291 5292以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 5293 5294| 错误码ID | 错误信息 | 5295| -------- | ---------------------------------------- | 5296| 17000002 | The async function is not called with await. | 5297| 17000004 | The window or component is invisible or destroyed. | 5298| 17000005 | This operation is not supported. | 5299| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 5300 5301**示例：** 5302 5303```ts 5304import { Driver, ResizeDirection, UiWindow } from '@kit.TestKit'; 5305async function demo() { 5306 let driver: Driver = Driver.create(); 5307 let window: UiWindow = await driver.findWindow({actived: true}); 5308 await window.resize(100, 100, ResizeDirection.LEFT); 5309} 5310``` 5311 5312### split<sup>9+</sup> 5313 5314split(): Promise\<void> 5315 5316将窗口模式切换成分屏模式，使用Promise异步回调。适用于支持切换分屏模式的窗口。 5317 5318**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5319 5320**系统能力**：SystemCapability.Test.UiTest 5321 5322**设备行为差异**：该接口在PC/2in1、Tablet设备中可正常调用，在其他设备中返回17000005错误码。 5323 5324**返回值：** 5325 5326| 类型 | 说明 | 5327|----------------|-----------------| 5328| Promise\<void> | Promise对象，返回无结果的Promise对象。 | 5329 5330**错误码：** 5331 5332以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 5333 5334| 错误码ID | 错误信息 | 5335| -------- | ---------------------------------------- | 5336| 17000002 | The async function is not called with await. | 5337| 17000004 | The window or component is invisible or destroyed. | 5338| 17000005 | This operation is not supported. | 5339 5340**示例：** 5341 5342```ts 5343import { Driver, UiWindow } from '@kit.TestKit'; 5344async function demo() { 5345 let driver: Driver = Driver.create(); 5346 let window: UiWindow = await driver.findWindow({actived: true}); 5347 await window.split(); 5348} 5349``` 5350 5351### maximize<sup>9+</sup> 5352 5353maximize(): Promise\<void> 5354 5355将窗口最大化，使用Promise异步回调。适用于支持窗口最大化操作的窗口。 5356 5357**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5358 5359**系统能力**：SystemCapability.Test.UiTest 5360 5361**设备行为差异**：该接口在PC/2in1、Tablet设备中可正常调用，在其他设备中返回17000005错误码。 5362 5363**返回值：** 5364 5365| 类型 | 说明 | 5366|----------------|-----------------| 5367| Promise\<void> | Promise对象，返回无结果的Promise对象。 | 5368 5369**错误码：** 5370 5371以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 5372 5373| 错误码ID | 错误信息 | 5374| -------- | ---------------------------------------- | 5375| 17000002 | The async function is not called with await. | 5376| 17000004 | The window or component is invisible or destroyed. | 5377| 17000005 | This operation is not supported. | 5378 5379**示例：** 5380 5381```ts 5382import { Driver, UiWindow } from '@kit.TestKit'; 5383async function demo() { 5384 let driver: Driver = Driver.create(); 5385 let window: UiWindow = await driver.findWindow({actived: true}); 5386 await window.maximize(); 5387} 5388``` 5389 5390### minimize<sup>9+</sup> 5391 5392minimize(): Promise\<void> 5393 5394将窗口最小化，使用Promise异步回调。适用于支持窗口最小化操作的窗口。 5395 5396**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5397 5398**系统能力**：SystemCapability.Test.UiTest 5399 5400**设备行为差异**：该接口在PC/2in1、Tablet设备中可正常调用，在其他设备中返回17000005错误码。 5401 5402**返回值：** 5403 5404| 类型 | 说明 | 5405|----------------|-----------------| 5406| Promise\<void> | Promise对象，返回无结果的Promise对象。 | 5407 5408**错误码：** 5409 5410以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 5411 5412| 错误码ID | 错误信息 | 5413| -------- | ---------------------------------------- | 5414| 17000002 | The async function is not called with await. | 5415| 17000004 | The window or component is invisible or destroyed. | 5416| 17000005 | This operation is not supported. | 5417 5418**示例：** 5419 5420```ts 5421import { Driver, UiWindow } from '@kit.TestKit'; 5422async function demo() { 5423 let driver: Driver = Driver.create(); 5424 let window: UiWindow = await driver.findWindow({actived: true}); 5425 await window.minimize(); 5426} 5427``` 5428 5429### resume<sup>9+</sup> 5430 5431resume(): Promise\<void> 5432 5433将窗口恢复到之前的窗口模式，使用Promise异步回调。 5434 5435**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5436 5437**系统能力**：SystemCapability.Test.UiTest 5438 5439**设备行为差异**：该接口在PC/2in1、Tablet设备中可正常调用，在其他设备中返回17000005错误码。 5440 5441**返回值：** 5442 5443| 类型 | 说明 | 5444|----------------|-----------------| 5445| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 5446 5447**错误码：** 5448 5449以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 5450 5451| 错误码ID | 错误信息 | 5452| -------- | ---------------------------------------- | 5453| 17000002 | The async function is not called with await. | 5454| 17000004 | The window or component is invisible or destroyed. | 5455| 17000005 | This operation is not supported. | 5456 5457**示例：** 5458 5459```ts 5460import { Driver, UiWindow } from '@kit.TestKit'; 5461async function demo() { 5462 let driver: Driver = Driver.create(); 5463 let window: UiWindow = await driver.findWindow({actived: true}); 5464 await window.resume(); 5465} 5466``` 5467 5468### close<sup>9+</sup> 5469 5470close(): Promise\<void> 5471 5472将窗口关闭，使用Promise异步回调。 5473 5474**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5475 5476**系统能力**：SystemCapability.Test.UiTest 5477 5478**设备行为差异**：该接口在PC/2in1、Tablet设备中可正常调用，在其他设备中返回17000005错误码。 5479 5480**返回值：** 5481 5482| 类型 | 说明 | 5483|----------------|-----------------| 5484| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 5485 5486**错误码：** 5487 5488以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 5489 5490| 错误码ID | 错误信息 | 5491| -------- | ---------------------------------------- | 5492| 17000002 | The async function is not called with await. | 5493| 17000004 | The window or component is invisible or destroyed. | 5494| 17000005 | This operation is not supported. | 5495 5496**示例：** 5497 5498```ts 5499import { Driver, UiWindow } from '@kit.TestKit'; 5500async function demo() { 5501 let driver:Driver = Driver.create(); 5502 let window: UiWindow = await driver.findWindow({actived: true}); 5503 await window.close(); 5504} 5505``` 5506 5507### isActive<sup>11+</sup> 5508 5509isActive(): Promise\<boolean> 5510 5511判断窗口是否为用户正在交互窗口，使用Promise异步回调。 5512 5513**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5514 5515**系统能力**：SystemCapability.Test.UiTest 5516 5517**返回值：** 5518 5519| 类型 | 说明 | 5520| ----------------- | ------------------------------------------------------------ | 5521| Promise\<boolean> | Promise对象，返回窗口对象是否为用户正在交互窗口。true：交互窗口。false：非交互窗口。 | 5522 5523**错误码：** 5524 5525以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 5526 5527| 错误码ID | 错误信息 | 5528| -------- | ------------------------------------------------ | 5529| 17000002 | The async function is not called with await. | 5530| 17000004 | The window or component is invisible or destroyed. | 5531 5532**示例：** 5533 5534```ts 5535import { Driver, UiWindow } from '@kit.TestKit'; 5536async function demo() { 5537 let driver: Driver = Driver.create(); 5538 let window: UiWindow = await driver.findWindow({active: true}); 5539 let focused = await window.isActive(); 5540} 5541``` 5542 5543### getDisplayId<sup>20+</sup> 5544 5545getDisplayId(): Promise\<number> 5546 5547获取窗口所属的屏幕ID，使用Promise异步回调。 5548 5549**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 5550 5551**系统能力**：SystemCapability.Test.UiTest 5552 5553**返回值：** 5554 5555| 类型 | 说明 | 5556| ---------------- |----------------------| 5557| Promise\<number> | Promise对象，返回窗口所属的屏幕ID。 | 5558 5559**错误码：** 5560 5561以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 5562 5563| 错误码ID | 错误信息 | 5564| -------- | ---------------------------------------- | 5565| 17000002 | The async function is not called with await. | 5566| 17000004 | The window or component is invisible or destroyed. | 5567 5568**示例：** 5569 5570```ts 5571import { UiWindow, Driver } from '@kit.TestKit'; 5572 5573async function demo() { 5574 let driver: Driver = Driver.create(); 5575 let window: UiWindow = await driver.findWindow({active: true}); 5576 let id = await window.getDisplayId(); 5577} 5578``` 5579 5580## UIEventObserver<sup>10+</sup> 5581 5582UI事件监听器。 5583 5584### once('toastShow')<sup>10+</sup> 5585 5586once(type: 'toastShow', callback: Callback\<UIElementInfo>): void; 5587 5588开始监听toast控件出现的事件，使用callback的形式返回结果。 5589 5590**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5591 5592**系统能力**：SystemCapability.Test.UiTest 5593 5594**参数：** 5595 5596| 参数名 | 类型 | 必填 | 说明 | 5597| -------- | -------------------------------------------- | ---- | --------------------------------- | 5598| type | string | 是 | 订阅的事件类型，取值为'toastShow'。 | 5599| callback | Callback\<[UIElementInfo](#uielementinfo10)> | 是 | 事件发生时执行的回调函数。 | 5600 5601**错误码：** 5602 5603以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 5604 5605| 错误码ID | 错误信息 | 5606| -------- | ------------------------------------------------------------ | 5607| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 5608 5609**示例：** 5610 5611```ts 5612import { Driver, UIElementInfo, UIEventObserver } from '@kit.TestKit'; 5613 5614async function demo() { 5615 let driver: Driver = Driver.create(); 5616 let observer: UIEventObserver = await driver.createUIEventObserver(); 5617 let callback = (UIElementInfo: UIElementInfo)=>{ 5618 console.info(UIElementInfo.bundleName); 5619 console.info(UIElementInfo.text); 5620 console.info(UIElementInfo.type); 5621 } 5622 observer.once('toastShow', callback); 5623} 5624``` 5625 5626### once('dialogShow')<sup>10+</sup> 5627 5628once(type: 'dialogShow', callback: Callback\<UIElementInfo>): void; 5629 5630开始监听dialog控件出现的事件，使用callback的形式返回结果。 5631 5632**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 5633 5634**系统能力**：SystemCapability.Test.UiTest 5635 5636**参数：** 5637 5638| 参数名 | 类型 | 必填 | 说明 | 5639| -------- | -------------------------------------------- | ---- | ---------------------------------- | 5640| type | string | 是 | 订阅的事件类型，取值为'dialogShow'。 | 5641| callback | Callback\<[UIElementInfo](#uielementinfo10)> | 是 | 事件发生时执行的回调函数。 | 5642 5643**错误码：** 5644 5645以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 5646 5647| 错误码ID | 错误信息 | 5648| -------- | ------------------------------------------------------------ | 5649| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.| 5650 5651**示例：** 5652 5653```ts 5654import { Driver, UIElementInfo, UIEventObserver } from '@kit.TestKit'; 5655 5656async function demo() { 5657 let driver: Driver = Driver.create(); 5658 let observer: UIEventObserver = await driver.createUIEventObserver(); 5659 let callback = (UIElementInfo: UIElementInfo)=>{ 5660 console.info(UIElementInfo.bundleName); 5661 console.info(UIElementInfo.text); 5662 console.info(UIElementInfo.type); 5663 } 5664 observer.once('dialogShow', callback); 5665} 5666``` 5667 5668## By<sup>(deprecated)</sup> 5669 5670UiTest框架通过By类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。<br> 5671By提供的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对象。 5672 5673从API version 9开始不再维护，建议使用[On<sup>9+</sup>](#on9)。 5674 5675```ts 5676import { BY } from '@kit.TestKit'; 5677BY.text('123').type('Button'); 5678``` 5679 5680### text<sup>(deprecated)</sup> 5681 5682text(txt: string, pattern?: MatchPattern): By 5683 5684指定目标控件文本属性，支持多种匹配模式，返回By对象自身。 5685 5686从API version 9开始不再维护，建议使用[text<sup>9+</sup>](#text9)。 5687 5688**系统能力**：SystemCapability.Test.UiTest 5689 5690**参数：** 5691 5692| 参数名 | 类型 | 必填 | 说明 | 5693| ------- | ----------------------------- | ---- | --------------------------------------------------- | 5694| txt | string | 是 | 指定控件文本，用于匹配目标控件文本。 | 5695| pattern | [MatchPattern](#matchpattern) | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 | 5696 5697**返回值：** 5698 5699| 类型 | 说明 | 5700| ------------------- | ---------------------------------- | 5701| [By](#bydeprecated) | 返回指定目标控件文本属性的By对象。 | 5702 5703**示例：** 5704 5705```ts 5706import { BY, By } from '@kit.TestKit'; 5707let by: By = BY.text('123'); // 使用静态构造器BY创建by对象，指定目标控件的text属性。 5708``` 5709 5710 5711### key<sup>(deprecated)</sup> 5712 5713key(key: string): By 5714 5715指定目标控件key值属性，返回By对象自身。 5716 5717从API version 9开始不再维护，建议使用[id<sup>9+</sup>](#id9)。 5718 5719**系统能力**：SystemCapability.Test.UiTest 5720 5721**参数：** 5722 5723| 参数名 | 类型 | 必填 | 说明 | 5724| ------ | ------ | ---- | ----------------- | 5725| key | string | 是 | 指定控件的Key值。 | 5726 5727**返回值：** 5728 5729| 类型 | 说明 | 5730| ------------------- | ----------------------------------- | 5731| [By](#bydeprecated) | 返回指定目标控件key值属性的By对象。 | 5732 5733**示例：** 5734 5735```ts 5736import { By, BY } from '@kit.TestKit'; 5737let by: By = BY.key('123'); // 使用静态构造器BY创建by对象，指定目标控件的key值属性。 5738``` 5739 5740 5741### id<sup>(deprecated)</sup> 5742 5743id(id: number): By 5744 5745指定目标控件id属性，返回By对象自身。 5746 5747从API version 9开始废弃。 5748 5749**系统能力**：SystemCapability.Test.UiTest 5750 5751**参数：** 5752 5753| 参数名 | 类型 | 必填 | 说明 | 5754| ------ | ------ | ---- | ---------------- | 5755| id | number | 是 | 指定控件的id值。 | 5756 5757**返回值：** 5758 5759| 类型 | 说明 | 5760| ------------------- | -------------------------------- | 5761| [By](#bydeprecated) | 返回指定目标控件id属性的By对象。 | 5762 5763**示例：** 5764 5765```ts 5766import { By, BY } from '@kit.TestKit'; 5767let by: By = BY.id(123); // 使用静态构造器BY创建by对象，指定目标控件的id属性。 5768``` 5769 5770 5771### type<sup>(deprecated)</sup> 5772 5773type(tp: string): By 5774 5775指定目标控件的控件类型属性，返回By对象自身。 5776 5777从API version 9开始不再维护，建议使用[type<sup>9+</sup>](#type9)。 5778 5779**系统能力**：SystemCapability.Test.UiTest 5780 5781**参数：** 5782 5783| 参数名 | 类型 | 必填 | 说明 | 5784| ------ | ------ | ---- | -------------- | 5785| tp | string | 是 | 指定控件类型。 | 5786 5787**返回值：** 5788 5789| 类型 | 说明 | 5790| ------------------- | ---------------------------------------- | 5791| [By](#bydeprecated) | 返回指定目标控件的控件类型属性的By对象。 | 5792 5793**示例：** 5794 5795```ts 5796import { By, BY } from '@kit.TestKit'; 5797let by: By = BY.type('Button'); // 使用静态构造器BY创建by对象，指定目标控件的控件类型属性。 5798``` 5799 5800 5801### clickable<sup>(deprecated)</sup> 5802 5803clickable(b?: boolean): By 5804 5805指定目标控件的可点击状态属性，返回By对象自身。 5806 5807从API version 9开始不再维护，建议使用[clickable<sup>9+</sup>](#clickable9)。 5808 5809**系统能力**：SystemCapability.Test.UiTest 5810 5811**参数：** 5812 5813| 参数名 | 类型 | 必填 | 说明 | 5814| ------ | ------- | ---- | ------------------------------------------------------------ | 5815| b | boolean | 否 | 指定控件可点击状态。true：可点击。false：不可点击。默认为true。 | 5816 5817**返回值：** 5818 5819| 类型 | 说明 | 5820| ------------------- | ------------------------------------------ | 5821| [By](#bydeprecated) | 返回指定目标控件的可点击状态属性的By对象。 | 5822 5823**示例：** 5824 5825```ts 5826import { By, BY } from '@kit.TestKit'; 5827let by: By = BY.clickable(true); // 使用静态构造器BY创建by对象，指定目标控件的可点击状态属性。 5828``` 5829 5830 5831### scrollable<sup>(deprecated)</sup> 5832 5833scrollable(b?: boolean): By 5834 5835指定目标控件的可滑动状态属性，返回By对象自身。 5836 5837从API version 9开始不再维护，建议使用[scrollable<sup>9+</sup>](#scrollable9)。 5838 5839**系统能力**：SystemCapability.Test.UiTest 5840 5841**参数：** 5842 5843| 参数名 | 类型 | 必填 | 说明 | 5844| ------ | ------- | ---- | ----------------------------------------------------------- | 5845| b | boolean | 否 | 控件可滑动状态。true：可滑动。false：不可滑动。默认为true。 | 5846 5847**返回值：** 5848 5849| 类型 | 说明 | 5850| ------------------- | ------------------------------------------ | 5851| [By](#bydeprecated) | 返回指定目标控件的可滑动状态属性的By对象。 | 5852 5853**示例：** 5854 5855```ts 5856import { By, BY } from '@kit.TestKit'; 5857let by: By = BY.scrollable(true); // 使用静态构造器BY创建by对象，指定目标控件的可滑动状态属性。 5858``` 5859 5860### enabled<sup>(deprecated)</sup> 5861 5862enabled(b?: boolean): By 5863 5864指定目标控件的使能状态属性，返回By对象自身。 5865 5866从API version 9开始不再维护，建议使用[enabled<sup>9+</sup>](#enabled9)。 5867 5868**系统能力**：SystemCapability.Test.UiTest 5869 5870**参数：** 5871 5872| 参数名 | 类型 | 必填 | 说明 | 5873| ------ | ------- | ---- | --------------------------------------------------------- | 5874| b | boolean | 否 | 指定控件使能状态。true：使能。false：未使能。默认为true。 | 5875 5876**返回值：** 5877 5878| 类型 | 说明 | 5879| ------------------- | ---------------------------------------- | 5880| [By](#bydeprecated) | 返回指定目标控件的使能状态属性的By对象。 | 5881 5882**示例：** 5883 5884```ts 5885import { By, BY } from '@kit.TestKit'; 5886let by: By = BY.enabled(true); // 使用静态构造器BY创建by对象，指定目标控件的使能状态属性。 5887``` 5888 5889### focused<sup>(deprecated)</sup> 5890 5891focused(b?: boolean): By 5892 5893指定目标控件的获焦状态属性，返回By对象自身。 5894 5895从API version 9开始不再维护，建议使用[focused<sup>9+</sup>](#focused9)。 5896 5897**系统能力**：SystemCapability.Test.UiTest 5898 5899**参数：** 5900 5901| 参数名 | 类型 | 必填 | 说明 | 5902| ------ | ------- | ---- | ----------------------------------------------------- | 5903| b | boolean | 否 | 控件获焦状态。true：获焦。false：未获焦。默认为true。 | 5904 5905**返回值：** 5906 5907| 类型 | 说明 | 5908| ------------------- | ---------------------------------------- | 5909| [By](#bydeprecated) | 返回指定目标控件的获焦状态属性的By对象。 | 5910 5911**示例：** 5912 5913```ts 5914import { By, BY } from '@kit.TestKit'; 5915let by: By = BY.focused(true); // 使用静态构造器BY创建by对象，指定目标控件的获焦状态属性。 5916``` 5917 5918### selected<sup>(deprecated)</sup> 5919 5920selected(b?: boolean): By 5921 5922指定目标控件的被选中状态属性，返回By对象自身。 5923 5924从API version 9开始不再维护，建议使用[selected<sup>9+</sup>](#selected9)。 5925 5926**系统能力**：SystemCapability.Test.UiTest 5927 5928**参数：** 5929 5930| 参数名 | 类型 | 必填 | 说明 | 5931| ------ | ------- | ---- | ------------------------------------------------------------ | 5932| b | boolean | 否 | 指定控件被选中状态。true：被选中。false：未被选中。默认为true。 | 5933 5934**返回值：** 5935 5936| 类型 | 说明 | 5937| ------------------- | ------------------------------------------ | 5938| [By](#bydeprecated) | 返回指定目标控件的被选中状态属性的By对象。 | 5939 5940**示例：** 5941 5942```ts 5943import { By, BY } from '@kit.TestKit'; 5944let by: By = BY.selected(true); // 使用静态构造器BY创建by对象，指定目标控件的被选中状态属性。 5945``` 5946 5947### isBefore<sup>(deprecated)</sup> 5948 5949isBefore(by: By): By 5950 5951指定目标控件位于给出的特征属性控件之前，返回By对象自身。 5952 5953从API version 9开始不再维护，建议使用[isBefore<sup>9+</sup>](#isbefore9)。 5954 5955**系统能力**：SystemCapability.Test.UiTest 5956 5957**参数：** 5958 5959| 参数名 | 类型 | 必填 | 说明 | 5960| ------ | ------------------- | ---- | ---------------- | 5961| by | [By](#bydeprecated) | 是 | 特征控件的属性。 | 5962 5963**返回值：** 5964 5965| 类型 | 说明 | 5966| ------------------- | ---------------------------------------------------- | 5967| [By](#bydeprecated) | 返回指定目标控件位于给出的特征属性控件之前的By对象。 | 5968 5969**示例：** 5970 5971```ts 5972import { By, BY } from '@kit.TestKit'; 5973 5974// 使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之前。 5975let by: By = BY.type('Button').isBefore(BY.text('123')); // 查找text为123之前的第一个Button组件 5976``` 5977 5978### isAfter<sup>(deprecated)</sup> 5979 5980isAfter(by: By): By 5981 5982指定目标控件位于给出的特征属性控件之后，返回By对象自身。 5983 5984从API version 9开始不再维护，建议使用[isAfter<sup>9+</sup>](#isafter9)。 5985 5986**系统能力**：SystemCapability.Test.UiTest 5987 5988**参数：** 5989 5990| 参数名 | 类型 | 必填 | 说明 | 5991| ------ | ------------------- | ---- | ---------------- | 5992| by | [By](#bydeprecated) | 是 | 特征控件的属性。 | 5993 5994**返回值：** 5995 5996| 类型 | 说明 | 5997| ------------------- | ---------------------------------------------------- | 5998| [By](#bydeprecated) | 返回指定目标控件位于给出的特征属性控件之后的By对象。 | 5999 6000**示例：** 6001 6002```ts 6003import { By, BY } from '@kit.TestKit'; 6004 6005// 使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之后。 6006let by: By = BY.type('Text').isAfter(BY.text('123')); // 查找 text为123之后的第一个Text组件 6007``` 6008 6009## UiComponent<sup>(deprecated)</sup> 6010 6011UiTest中，UiComponent类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。 6012该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。 6013 6014从API version 9开始不再维护，建议使用[Component<sup>9+</sup>](#component9)。 6015 6016### click<sup>(deprecated)</sup> 6017 6018click(): Promise\<void> 6019 6020控件对象进行点击操作。 6021 6022从API version 9开始不再维护，建议使用[click<sup>9+</sup>](#click9)。 6023 6024**系统能力**：SystemCapability.Test.UiTest 6025 6026**返回值：** 6027 6028| 类型 | 说明 | 6029|----------------|-----------------| 6030| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6031 6032**示例：** 6033 6034```ts 6035import { UiDriver, BY, Driver, UiComponent } from '@kit.TestKit'; 6036async function demo() { 6037 let driver: UiDriver = UiDriver.create(); 6038 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6039 await button.click(); 6040} 6041``` 6042 6043### doubleClick<sup>(deprecated)</sup> 6044 6045doubleClick(): Promise\<void> 6046 6047控件对象进行双击操作。 6048 6049从API version 9开始不再维护，建议使用[doubleClick<sup>9+</sup>](#doubleclick9)。 6050 6051**系统能力**：SystemCapability.Test.UiTest 6052 6053**返回值：** 6054 6055| 类型 | 说明 | 6056|----------------|-----------------| 6057| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6058 6059**示例：** 6060 6061```ts 6062import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6063async function demo() { 6064 let driver: UiDriver = UiDriver.create(); 6065 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6066 await button.doubleClick(); 6067} 6068``` 6069 6070### longClick<sup>(deprecated)</sup> 6071 6072longClick(): Promise\<void> 6073 6074控件对象进行长按操作。 6075 6076从API version 9开始不再维护，建议使用[longClick<sup>9+</sup>](#longclick9)。 6077 6078**系统能力**：SystemCapability.Test.UiTest 6079 6080**返回值：** 6081 6082| 类型 | 说明 | 6083|----------------|-----------------| 6084| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6085 6086**示例：** 6087 6088```ts 6089import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6090async function demo() { 6091 let driver: UiDriver = UiDriver.create(); 6092 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6093 await button.longClick(); 6094} 6095``` 6096 6097### getId<sup>(deprecated)</sup> 6098 6099getId(): Promise\<number> 6100 6101获取控件对象的id值。 6102 6103从API version 9开始不再维护，被废弃。 6104 6105**系统能力**：SystemCapability.Test.UiTest 6106 6107**返回值：** 6108 6109| 类型 | 说明 | 6110| ---------------- | ------------------------------- | 6111| Promise\<number> | Promise对象，返回控件的id值。 | 6112 6113**示例：** 6114 6115```ts 6116import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6117async function demo() { 6118 let driver: UiDriver = UiDriver.create(); 6119 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6120 let id = await button.getId(); 6121} 6122``` 6123 6124### getKey<sup>(deprecated)</sup> 6125 6126getKey(): Promise\<string> 6127 6128获取控件对象的key值。 6129 6130从API version 9开始不再维护，建议使用[getId<sup>9+</sup>](#getid9) 6131 6132**系统能力**：SystemCapability.Test.UiTest 6133 6134**返回值：** 6135 6136| 类型 | 说明 | 6137| ---------------- | ------------------------------ | 6138| Promise\<string> | Promise对象，返回控件的key值。 | 6139 6140**示例：** 6141 6142```ts 6143import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6144async function demo() { 6145 let driver: UiDriver = UiDriver.create(); 6146 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6147 let str_key = await button.getKey(); 6148} 6149``` 6150 6151### getText<sup>(deprecated)</sup> 6152 6153getText(): Promise\<string> 6154 6155获取控件对象的文本信息。 6156 6157从API version 9开始不再维护，建议使用[getText<sup>9+</sup>](#gettext9)。 6158 6159**系统能力**：SystemCapability.Test.UiTest 6160 6161**返回值：** 6162 6163| 类型 | 说明 | 6164| ---------------- | --------------------------------- | 6165| Promise\<string> | Promise对象，返回控件的文本信息。 | 6166 6167**示例：** 6168 6169```ts 6170import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6171async function demo() { 6172 let driver: UiDriver = UiDriver.create(); 6173 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6174 let text = await button.getText(); 6175} 6176``` 6177 6178### getType<sup>(deprecated)</sup> 6179 6180getType(): Promise\<string> 6181 6182获取控件对象的控件类型。 6183 6184从API version 9开始不再维护，建议使用[getType<sup>9+</sup>](#gettype9)。 6185 6186**系统能力**：SystemCapability.Test.UiTest 6187 6188**返回值：** 6189 6190| 类型 | 说明 | 6191| ---------------- | ----------------------------- | 6192| Promise\<string> | Promise对象，返回控件的类型。 | 6193 6194**示例：** 6195 6196```ts 6197import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6198async function demo() { 6199 let driver: UiDriver = UiDriver.create(); 6200 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6201 let type = await button.getType(); 6202} 6203``` 6204 6205### isClickable<sup>(deprecated)</sup> 6206 6207isClickable(): Promise\<boolean> 6208 6209获取控件对象可点击状态。 6210 6211从API version 9开始不再维护，建议使用[isClickable<sup>9+</sup>](#isclickable9)。 6212 6213**系统能力**：SystemCapability.Test.UiTest 6214 6215**返回值：** 6216 6217| 类型 | 说明 | 6218| ----------------- | ------------------------------------------------------------ | 6219| Promise\<boolean> | Promise对象，返回控件对象可点击状态。true：可点击。false：不可点击。 | 6220 6221**示例：** 6222 6223```ts 6224import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6225async function demo() { 6226 let driver: UiDriver = UiDriver.create(); 6227 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6228 if (await button.isClickable()) { 6229 console.info('This button can be Clicked'); 6230 } else { 6231 console.info('This button can not be Clicked'); 6232 } 6233} 6234``` 6235 6236### isScrollable<sup>(deprecated)</sup> 6237 6238isScrollable(): Promise\<boolean> 6239 6240获取控件对象可滑动状态。 6241 6242从API version 9开始不再维护，建议使用[isScrollable<sup>9+</sup>](#isscrollable9)。 6243 6244**系统能力**：SystemCapability.Test.UiTest 6245 6246**返回值：** 6247 6248| 类型 | 说明 | 6249| ----------------- | ------------------------------------------------------------ | 6250| Promise\<boolean> | Promise对象，返回控件对象可滑动状态。true：可滑动。false：不可滑动。 | 6251 6252**示例：** 6253 6254```ts 6255import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6256async function demo() { 6257 let driver: UiDriver = UiDriver.create(); 6258 let scrollBar: UiComponent = await driver.findComponent(BY.scrollable(true)); 6259 if (await scrollBar.isScrollable()) { 6260 console.info('This scrollBar can be operated'); 6261 } else { 6262 console.info('This scrollBar can not be operated'); 6263 } 6264} 6265``` 6266 6267 6268### isEnabled<sup>(deprecated)</sup> 6269 6270isEnabled(): Promise\<boolean> 6271 6272获取控件使能状态。 6273 6274从API version 9开始不再维护，建议使用[isEnabled<sup>9+</sup>](#isenabled9)。 6275 6276**系统能力**：SystemCapability.Test.UiTest 6277 6278**返回值：** 6279 6280| 类型 | 说明 | 6281| ----------------- | ---------------------------------------------------------- | 6282| Promise\<boolean> | Promise对象，返回控件使能状态。true：使能。false：未使能。 | 6283 6284**示例：** 6285 6286```ts 6287import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6288async function demo() { 6289 let driver: UiDriver = UiDriver.create(); 6290 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6291 if (await button.isEnabled()) { 6292 console.info('This button can be operated'); 6293 } else { 6294 console.info('This button can not be operated'); 6295 } 6296} 6297 6298``` 6299 6300### isFocused<sup>(deprecated)</sup> 6301 6302isFocused(): Promise\<boolean> 6303 6304判断控件对象是否获焦。 6305 6306从API version 9开始不再维护，建议使用[isFocused<sup>9+</sup>](#isfocused9)。 6307 6308**系统能力**：SystemCapability.Test.UiTest 6309 6310**返回值：** 6311 6312| 类型 | 说明 | 6313| ----------------- | ------------------------------------------------------------ | 6314| Promise\<boolean> | Promise对象，返回控件对象是否获焦。true：获焦。false：未获焦。 | 6315 6316**示例：** 6317 6318```ts 6319import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6320async function demo() { 6321 let driver: UiDriver = UiDriver.create(); 6322 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6323 if (await button.isFocused()) { 6324 console.info('This button is focused'); 6325 } else { 6326 console.info('This button is not focused'); 6327 } 6328} 6329``` 6330 6331### isSelected<sup>(deprecated)</sup> 6332 6333isSelected(): Promise\<boolean> 6334 6335获取控件对象被选中状态。 6336 6337从API version 9开始不再维护，建议使用[isSelected<sup>9+</sup>](#isselected9)。 6338 6339**系统能力**：SystemCapability.Test.UiTest 6340 6341**返回值：** 6342 6343| 类型 | 说明 | 6344| ----------------- | ----------------------------------------------------- | 6345| Promise\<boolean> | Promise对象，返回控件对象被选中的状态。true：被选中。false：未被选中。 | 6346 6347**示例：** 6348 6349```ts 6350import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6351async function demo() { 6352 let driver: UiDriver = UiDriver.create(); 6353 let button: UiComponent = await driver.findComponent(BY.type('Button')); 6354 if (await button.isSelected()) { 6355 console.info('This button is selected'); 6356 } else { 6357 console.info('This button is not selected'); 6358 } 6359} 6360``` 6361 6362### inputText<sup>(deprecated)</sup> 6363 6364inputText(text: string): Promise\<void> 6365 6366向控件中输入文本，仅针对可编辑的文本组件生效。 6367 6368从API version 9开始不再维护，建议使用[inputText<sup>9+</sup>](#inputtext9)。 6369 6370**系统能力**：SystemCapability.Test.UiTest 6371 6372**参数：** 6373 6374| 参数名 | 类型 | 必填 | 说明 | 6375| ------ | ------ | ---- | ---------------- | 6376| text | string | 是 | 输入的文本信息。 | 6377 6378**返回值：** 6379 6380| 类型 | 说明 | 6381|----------------|-----------------| 6382| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6383 6384**示例：** 6385 6386```ts 6387import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6388async function demo() { 6389 let driver: UiDriver = UiDriver.create(); 6390 let text: UiComponent = await driver.findComponent(BY.text('hello world')); 6391 await text.inputText('123'); 6392} 6393``` 6394 6395### scrollSearch<sup>(deprecated)</sup> 6396 6397scrollSearch(by: By): Promise\<UiComponent> 6398 6399在控件上滑动查找目标控件（适用于List等支持滑动的控件）。 6400 6401从API version 9开始不再维护，建议使用[scrollSearch<sup>9+</sup>](#scrollsearch9)。 6402 6403**系统能力**：SystemCapability.Test.UiTest 6404 6405**参数：** 6406 6407| 参数名 | 类型 | 必填 | 说明 | 6408| ------ | ------------------- | ---- | -------------------- | 6409| by | [By](#bydeprecated) | 是 | 目标控件的属性要求。 | 6410 6411**返回值：** 6412 6413| 类型 | 说明 | 6414| ----------------------------------------------- | ------------------------------------- | 6415| Promise\<[UiComponent](#uicomponentdeprecated)> | Promise对象，返回目标控件对象。 | 6416 6417**示例：** 6418 6419```ts 6420import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6421async function demo() { 6422 let driver: UiDriver = UiDriver.create(); 6423 let scrollBar: UiComponent = await driver.findComponent(BY.type('Scroll')); 6424 let button = await scrollBar.scrollSearch(BY.text('next page')); 6425} 6426``` 6427 6428## UiDriver<sup>(deprecated)</sup> 6429 6430UiDriver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等API。 6431该类提供的方法除UiDriver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await调用。 6432 6433从API version 9开始不再维护，建议使用[Driver<sup>9+</sup>](#driver9)。 6434 6435### create<sup>(deprecated)</sup> 6436 6437static create(): UiDriver 6438 6439静态方法，构造一个UiDriver对象，并返回该对象。 6440 6441从API version 9开始不再维护，建议使用[create<sup>9+</sup>](#create9)。 6442 6443**系统能力**：SystemCapability.Test.UiTest 6444 6445**返回值：** 6446 6447| 类型 | 说明 | 6448| -------- | ------------------------ | 6449| UiDriver | 返回构造的UiDriver对象。 | 6450 6451**示例：** 6452 6453```ts 6454import { UiDriver } from '@kit.TestKit'; 6455async function demo() { 6456 let driver: UiDriver = UiDriver.create(); 6457} 6458``` 6459 6460### delayMs<sup>(deprecated)</sup> 6461 6462delayMs(duration: number): Promise\<void> 6463 6464UiDriver对象在给定的时间内延时。 6465 6466从API version 9开始不再维护，建议使用[delayMs<sup>9+</sup>](#delayms9)。 6467 6468**系统能力**：SystemCapability.Test.UiTest 6469 6470**参数：** 6471 6472| 参数名 | 类型 | 必填 | 说明 | 6473| -------- | ------ | ---- | ------------ | 6474| duration | number | 是 | 给定的时间。 | 6475 6476**返回值：** 6477 6478| 类型 | 说明 | 6479|----------------|-----------------| 6480| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6481 6482**示例：** 6483 6484```ts 6485import { UiDriver } from '@kit.TestKit'; 6486async function demo() { 6487 let driver: UiDriver = UiDriver.create(); 6488 await driver.delayMs(1000); 6489} 6490``` 6491 6492### findComponent<sup>(deprecated)</sup> 6493 6494findComponent(by: By): Promise\<UiComponent> 6495 6496在UiDriver对象中，根据给出的目标控件属性要求查找目标控件。 6497 6498从API version 9开始不再维护，建议使用[findComponent<sup>9+</sup>](#findcomponent9)。 6499 6500**系统能力**：SystemCapability.Test.UiTest 6501 6502**参数：** 6503 6504| 参数名 | 类型 | 必填 | 说明 | 6505| ------ | ------------------- | ---- | -------------------- | 6506| by | [By](#bydeprecated) | 是 | 目标控件的属性要求。 | 6507 6508**返回值：** 6509 6510| 类型 | 说明 | 6511| ----------------------------------------------- | --------------------------------- | 6512| Promise\<[UiComponent](#uicomponentdeprecated)> | Promise对象，返回控件对象。 | 6513 6514**示例：** 6515 6516```ts 6517import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6518async function demo() { 6519 let driver: UiDriver = UiDriver.create(); 6520 let button: UiComponent = await driver.findComponent(BY.text('next page')); 6521} 6522``` 6523 6524### findComponents<sup>(deprecated)</sup> 6525 6526findComponents(by: By): Promise\<Array\<UiComponent>> 6527 6528在UiDriver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。 6529 6530从API version 9开始不再维护，建议使用[findComponents<sup>9+</sup>](#findcomponents9)。 6531 6532**系统能力**：SystemCapability.Test.UiTest 6533 6534**参数：** 6535 6536| 参数名 | 类型 | 必填 | 说明 | 6537| ------ | ------------------- | ---- | -------------------- | 6538| by | [By](#bydeprecated) | 是 | 目标控件的属性要求。 | 6539 6540**返回值：** 6541 6542| 类型 | 说明 | 6543| ------------------------------------------------------- | --------------------------------------- | 6544| Promise\<Array\<[UiComponent](#uicomponentdeprecated)>> | Promise对象，返回控件对象的列表。 | 6545 6546**示例：** 6547 6548```ts 6549import { UiDriver, BY, UiComponent } from '@kit.TestKit'; 6550async function demo() { 6551 let driver: UiDriver = UiDriver.create(); 6552 let buttonList: Array<UiComponent> = await driver.findComponents(BY.text('next page')); 6553} 6554``` 6555 6556### assertComponentExist<sup>(deprecated)</sup> 6557 6558assertComponentExist(by: By): Promise\<void> 6559 6560断言API，用于断言当前界面存在满足给出的目标控件属性的控件; 如果控件不存在，该API将抛出JS异常，使当前测试用例失败。 6561 6562从API version 9开始不再维护，建议使用[assertComponentExist<sup>9+</sup>](#assertcomponentexist9)。 6563 6564**系统能力**：SystemCapability.Test.UiTest 6565 6566**参数：** 6567 6568| 参数名 | 类型 | 必填 | 说明 | 6569| ------ | ------------------- | ---- | -------------------- | 6570| by | [By](#bydeprecated) | 是 | 目标控件的属性要求。 | 6571 6572**返回值：** 6573 6574| 类型 | 说明 | 6575|----------------|-----------------| 6576| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6577 6578**错误码：** 6579 6580以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 6581 6582| 错误码ID | 错误信息 | 6583| -------- | ------------------------------------------------ | 6584| 401 | if the input parameters are invalid. | 6585| 17000002 | if the async function was not called with await. | 6586| 17000003 | if the assertion failed. | 6587 6588**示例：** 6589 6590```ts 6591import { UiDriver, BY } from '@kit.TestKit'; 6592async function demo() { 6593 let driver: UiDriver = UiDriver.create(); 6594 await driver.assertComponentExist(BY.text('next page')); 6595} 6596``` 6597 6598### pressBack<sup>(deprecated)</sup> 6599 6600pressBack(): Promise\<void> 6601 6602UiDriver对象进行点击BACK键的操作。 6603 6604从API version 9开始不再维护，建议使用[pressBack<sup>9+</sup>](#pressback9)。 6605 6606**系统能力**：SystemCapability.Test.UiTest 6607 6608**返回值：** 6609 6610| 类型 | 说明 | 6611|----------------|-----------------| 6612| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6613 6614**示例：** 6615 6616```ts 6617import { UiDriver } from '@kit.TestKit'; 6618async function demo() { 6619 let driver: UiDriver = UiDriver.create(); 6620 await driver.pressBack(); 6621} 6622``` 6623 6624### triggerKey<sup>(deprecated)</sup> 6625 6626triggerKey(keyCode: number): Promise\<void> 6627 6628UiDriver对象采取如下操作：通过key值找到对应键并点击。 6629 6630从API version 9开始不再维护，建议使用[triggerKey<sup>9+</sup>](#triggerkey9)。 6631 6632**系统能力**：SystemCapability.Test.UiTest 6633 6634**参数：** 6635 6636| 参数名 | 类型 | 必填 | 说明 | 6637| ------- | ------ | ---- | ------------- | 6638| keyCode | number | 是 | 指定的key值，取值大于等于0的整数，取值范围：[KeyCode键码值](../apis-input-kit/js-apis-keycode.md#keycode)。 | 6639 6640**返回值：** 6641 6642| 类型 | 说明 | 6643|----------------|-----------------| 6644| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6645 6646**示例：** 6647 6648```ts 6649import { Driver, UiDriver } from '@kit.TestKit'; 6650import { KeyCode } from '@kit.InputKit'; 6651 6652async function demo() { 6653 let driver: UiDriver = UiDriver.create(); 6654 await driver.triggerKey(KeyCode.KEYCODE_BACK); // 返回键 6655} 6656``` 6657 6658 6659### click<sup>(deprecated)</sup> 6660 6661click(x: number, y: number): Promise\<void> 6662 6663UiDriver对象采取如下操作：在目标坐标点单击。 6664 6665从API version 9开始不再维护，建议使用[click<sup>9+</sup>](#click9)。 6666 6667**系统能力**：SystemCapability.Test.UiTest 6668 6669**参数：** 6670 6671| 参数名 | 类型 | 必填 | 说明 | 6672| ------ | ------ | ---- | -------------------------------------- | 6673| x | number | 是 | 以number的形式传入目标点的横坐标信息，取值范围：大于等于0的整数。 | 6674| y | number | 是 | 以number的形式传入目标点的纵坐标信息，取值范围：大于等于0的整数。 | 6675 6676**返回值：** 6677 6678| 类型 | 说明 | 6679|----------------|-----------------| 6680| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6681 6682**示例：** 6683 6684```ts 6685import { UiDriver } from '@kit.TestKit'; 6686 6687async function demo() { 6688 let driver: UiDriver = UiDriver.create(); 6689 await driver.click(100, 100); 6690} 6691``` 6692 6693### doubleClick<sup>(deprecated)</sup> 6694 6695doubleClick(x: number, y: number): Promise\<void> 6696 6697UiDriver对象采取如下操作：在目标坐标点双击。 6698 6699从API version 9开始不再维护，建议使用[doubleClick<sup>9+</sup>](#doubleclick9)。 6700 6701**系统能力**：SystemCapability.Test.UiTest 6702 6703**参数：** 6704 6705| 参数名 | 类型 | 必填 | 说明 | 6706| ------ | ------ | ---- | -------------------------------------- | 6707| x | number | 是 | 以number的形式传入目标点的横坐标信息，取值范围：大于等于0的整数。 | 6708| y | number | 是 | 以number的形式传入目标点的纵坐标信息，取值范围：大于等于0的整数。 | 6709 6710**返回值：** 6711 6712| 类型 | 说明 | 6713|----------------|-----------------| 6714| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6715 6716**示例：** 6717 6718```ts 6719import { UiDriver } from '@kit.TestKit'; 6720 6721async function demo() { 6722 let driver: UiDriver = UiDriver.create(); 6723 await driver.doubleClick(100, 100); 6724} 6725``` 6726 6727### longClick<sup>(deprecated)</sup> 6728 6729longClick(x: number, y: number): Promise\<void> 6730 6731UiDriver对象采取如下操作：在目标坐标点长按下鼠标左键。 6732 6733从API version 9开始不再维护，建议使用[longClick<sup>9+</sup>](#longclick9)。 6734 6735**系统能力**：SystemCapability.Test.UiTest 6736 6737**参数：** 6738 6739| 参数名 | 类型 | 必填 | 说明 | 6740| ------ | ------ | ---- | -------------------------------------- | 6741| x | number | 是 | 以number的形式传入目标点的横坐标信息，取值范围：大于等于0的整数。 | 6742| y | number | 是 | 以number的形式传入目标点的纵坐标信息，取值范围：大于等于0的整数。 | 6743 6744**返回值：** 6745 6746| 类型 | 说明 | 6747|----------------|-----------------| 6748| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6749 6750**示例：** 6751 6752```ts 6753import { UiDriver } from '@kit.TestKit'; 6754async function demo() { 6755 let driver: UiDriver = UiDriver.create(); 6756 await driver.longClick(100, 100); 6757} 6758``` 6759 6760### swipe<sup>(deprecated)</sup> 6761 6762swipe(startx: number, starty: number, endx: number, endy: number): Promise\<void> 6763 6764UiDriver对象采取如下操作：从给出的起始坐标点滑向给出的目的坐标点。 6765 6766从API version 9开始不再维护，建议使用[swipe<sup>9+</sup>](#swipe9)。 6767 6768**系统能力**：SystemCapability.Test.UiTest 6769 6770**参数：** 6771 6772| 参数名 | 类型 | 必填 | 说明 | 6773| ------ | ------ | ---- | -------------------------------------- | 6774| startx | number | 是 | 以number的形式传入起始点的横坐标信息，取值范围：大于等于0的整数。 | 6775| starty | number | 是 | 以number的形式传入起始点的纵坐标信息，取值范围：大于等于0的整数。 | 6776| endx | number | 是 | 以number的形式传入目的点的横坐标信息，取值范围：大于等于0的整数。 | 6777| endy | number | 是 | 以number的形式传入目的点的纵坐标信息，取值范围：大于等于0的整数。 | 6778 6779**返回值：** 6780 6781| 类型 | 说明 | 6782|----------------|-----------------| 6783| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6784 6785**示例：** 6786 6787```ts 6788import { UiDriver } from '@kit.TestKit'; 6789 6790async function demo() { 6791 let driver: UiDriver = UiDriver.create(); 6792 await driver.swipe(100, 100, 200, 200); 6793} 6794``` 6795 6796### screenCap<sup>(deprecated)</sup> 6797 6798screenCap(savePath: string): Promise\<boolean> 6799 6800UiDriver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。 6801 6802从API version 9开始不再维护，建议使用[screenCap<sup>9+</sup>](#screencap9)。 6803 6804**系统能力**：SystemCapability.Test.UiTest 6805 6806**参数：** 6807 6808| 参数名 | 类型 | 必填 | 说明 | 6809| -------- | ------ | ---- | -------------- | 6810| savePath | string | 是 | 文件保存路径。 | 6811 6812**返回值：** 6813 6814 6815| 类型 | 说明 | 6816| ----------------- |-----------------------------------------------| 6817| Promise\<boolean> | Promise对象，返回截图操作是否成功完成。true：成功完成，false：未成功完成。 | 6818 6819**示例：** 6820 6821```ts 6822import { UiDriver } from '@kit.TestKit'; 6823async function demo() { 6824 let driver: UiDriver = UiDriver.create(); 6825 await driver.screenCap('/data/storage/el2/base/cache/1.png'); 6826} 6827``` 6828
