# UiTest
UiTest提供模拟UI操作的能力，供开发者在测试场景使用，主要支持如点击、双击、长按、滑动等UI操作能力。
该模块提供以下功能：
- [On9+](#on9)：提供控件特征描述能力，用于控件筛选匹配查找。
- [Component9+](#component9)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。
- [Driver9+](#driver9)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能能力。
- [UiWindow9+](#uiwindow9)：入口类，提供窗口属性获取，窗口拖动、调整窗口大小等能能力。
- [By](#by)：提供控件特征描述能力，用于控件筛选匹配查找。从API version9开始不再维护，建议使用[[On9+](#on9)](#driver9)。
- [UiComponent](#uicomponent)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。从API version9开始不再维护，建议使用[Component9+](#component9)。
- [UiDriver](#uidriver)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能能力。从API version9开始不再维护，建议使用[Driver9+](#driver9)。
>**说明：**
>
>本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
## 导入模块
```js
import {UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix} from '@ohos.uitest'
```
## On9+
UiTest框架在API9中，通过On类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。
On提供的API能力具有以下几个特点:
1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。
2、控件属性支持多种匹配模式。
3、支持控件绝对定位，相对定位，可通过[ON.isBefore](#isbefore)和[ON.isAfter](#isafter)等API限定邻近控件特征进行辅助定位。
On类提供的所有API均为同步接口，建议使用者通过静态构造器ON来链式创建On对象。
```js
ON.text('123').type('button')
```
### text9+
text(txt: string, pattern?: MatchPattern): On
指定目标控件文本属性，支持多种匹配模式，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ----------------------------- | ---- | --------------------------------------------------- |
| txt | string | 是 | 指定控件文本，用于匹配目标控件文本。 |
| pattern | [MatchPattern](#matchpattern) | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 |
**返回值：**
| 类型 | 说明 |
| ---------- | ---------------------------------- |
| [On](#on9) | 返回指定目标控件文本属性的On对象。 |
**示例：**
```js
let on = ON.text('123') //使用静态构造器ON创建On对象，指定目标控件的text属性。
```
### id9+
id(id: string): On
指定目标控件id属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------------- |
| id | string | 是 | 指定控件的id值。 |
**返回值：**
| 类型 | 说明 |
| ---------- | -------------------------------- |
| [On](#on9) | 返回指定目标控件id属性的On对象。 |
**示例：**
```js
let on = ON.id(123) //使用静态构造器ON创建On对象，指定目标控件的id属性。
```
### type9+
type(tp: string): On
指定目标控件的控件类型属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------------- |
| tp | string | 是 | 指定控件类型。 |
**返回值：**
| 类型 | 说明 |
| ---------- | ---------------------------------------- |
| [On](#on9) | 返回指定目标控件的控件类型属性的On对象。 |
**示例：**
```js
let on = ON.type('button') //使用静态构造器ON创建On对象，指定目标控件的控件类型属性。
```
### clickable9+
clickable(b?: boolean): On
指定目标控件的可点击状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | 否 | 指定控件可点击状态，true：可点击，false：不可点击。默认为true。 |
**返回值：**
| 类型 | 说明 |
| ---------- | ------------------------------------------ |
| [On](#on9) | 返回指定目标控件的可点击状态属性的On对象。 |
**示例：**
```js
let on = ON.clickable(true) //使用静态构造器ON创建On对象，指定目标控件的可点击状态属性。
```
### longClickable9+
longClickable(b?: boolean): On
指定目标控件的可长按点击状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | 否 | 指定控件可长按点击状态，true：可长按点击，false：不可长按点击。默认为true。 |
**返回值：**
| 类型 | 说明 |
| ---------- | ---------------------------------------------- |
| [On](#on9) | 返回指定目标控件的可长按点击状态属性的On对象。 |
**示例：**
```js
let on = ON.longClickable(true) //使用静态构造器ON创建On对象，指定目标控件的可长按点击状态属性。
```
### scrollable9+
scrollable(b?: boolean): On
指定目标控件的可滑动状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ----------------------------------------------------------- |
| b | boolean | 否 | 控件可滑动状态，true：可滑动，false：不可滑动。默认为true。 |
**返回值：**
| 类型 | 说明 |
| ---------- | ------------------------------------------ |
| [On](#on9) | 返回指定目标控件的可滑动状态属性的On对象。 |
**示例：**
```js
let on = ON.scrollable(true) //使用静态构造器ON创建On对象，指定目标控件的可滑动状态属性。
```
### enabled9+
enabled(b?: boolean): On
指定目标控件的使能状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | --------------------------------------------------------- |
| b | boolean | 否 | 指定控件使能状态，true：使能，false：未使能。默认为true。 |
**返回值：**
| 类型 | 说明 |
| ---------- | ---------------------------------------- |
| [On](#on9) | 返回指定目标控件的使能状态属性的On对象。 |
**示例：**
```js
let on = ON.enabled(true) //使用静态构造器ON创建On对象，指定目标控件的使能状态属性。
```
### focused9+
focused(b?: boolean): On
指定目标控件的获焦状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ----------------------------------------------------- |
| b | boolean | 否 | 控件获焦状态，true：获焦，false：未获焦。默认为true。 |
**返回值：**
| 类型 | 说明 |
| ---------- | ---------------------------------------- |
| [On](#on9) | 返回指定目标控件的获焦状态属性的On对象。 |
**示例：**
```js
let on = ON.focused(true) //使用静态构造器ON创建On对象，指定目标控件的获焦状态属性。
```
### selected9+
selected(b?: boolean): On
指定目标控件的被选中状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | 否 | 指定控件被选中状态，true：被选中，false：未被选中。默认为true。 |
**返回值：**
| 类型 | 说明 |
| ---------- | ------------------------------------------ |
| [On](#on9) | 返回指定目标控件的被选中状态属性的On对象。 |
**示例：**
```js
let on = ON.selected(true) //使用静态构造器ON创建On对象，指定目标控件的被选中状态属性。
```
### checked9+
checked(b?: boolean): On
指定目标控件的被勾选状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | 否 | 指定控件被勾选状态，true：被勾选，false：未被勾选。默认为false。 |
**返回值：**
| 类型 | 说明 |
| ---------- | ------------------------------------------ |
| [On](#on9) | 返回指定目标控件的被勾选状态属性的On对象。 |
**示例：**
```js
let on = ON.checked(true) //使用静态构造器ON创建On对象，指定目标控件的被勾选状态属性
```
### checkable9+
checkable(b?: boolean): On
指定目标控件能否被勾选状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | 否 | 指定控件能否被勾选状态，true：能被勾选，false：不能被勾选。默认为false。 |
**返回值：**
| 类型 | 说明 |
| ---------- | -------------------------------------------- |
| [On](#on9) | 返回指定目标控件能否被勾选状态属性的On对象。 |
**示例：**
```js
let on = ON.checkable(true) //使用静态构造器ON创建On对象，指定目标控件的能否被勾选状态属性。
```
### isBefore9+
isBefore(on: On): On
指定目标控件位于给出的特征属性控件之前，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | 是 | 特征控件的属性要求。 |
**返回值：**
| 类型 | 说明 |
| ---------- | ---------------------------------------------------- |
| [On](#on9) | 返回指定目标控件位于给出的特征属性控件之前的On对象。 |
**示例：**
```js
let on = ON.isBefore(ON.text('123')) //使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之前。
```
### isAfter9+
isAfter(on: On): On
指定目标控件位于给出的特征属性控件之后，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | 是 | 特征控件的属性要求。 |
**返回值：**
| 类型 | 说明 |
| ---------- | ---------------------------------------------------- |
| [On](#on9) | 返回指定目标控件位于给出的特征属性控件之后的On对象。 |
**示例：**
```js
let on = ON.isAfter(ON.text('123')) //使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之后。
```
## Component9+
UiTest框架在API9中，Component类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。
该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。
### click9+
click(): Promise\
控件对象进行点击操作。
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
await button.click()
}
```
### doubleClick9+
doubleClick(): Promise\
控件对象进行双击操作。
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
await button.doubleClick()
}
```
### longClick9+
longClick(): Promise\
控件对象进行长按操作。
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
await button.longClick()
}
```
### getId9+
getId(): Promise\
获取控件对象的id值。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ---------------- | ------------------------------- |
| Promise\ | 以Promise形式返回的控件的id值。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
let num = await button.getId()
}
```
### getText9+
getText(): Promise\
获取控件对象的文本信息。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ---------------- | --------------------------------- |
| Promise\ | 以Promise形式返回控件的文本信息。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
let text = await button.getText()
}
```
### getType9+
getType(): Promise\
获取控件对象的控件类型。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ---------------- | ----------------------------- |
| Promise\ | 以Promise形式返回控件的类型。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
let type = await button.getType()
}
```
### getBounds9+
getBounds(): Promise\
获取控件对象的边框信息。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ------------------------ | ------------------------------------- |
| Promise\<[Rect](#rect9)> | 以Promise形式返回控件对象的边框信息。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
let rect = await button.getBounds()
}
```
### getBoundsCenter9+
getBoundsCenter(): Promise\
获取控件对象的中心点信息。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| -------------------------- | --------------------------------------- |
| Promise\<[Point](#point9)> | 以Promise形式返回控件对象的中心点信息。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
let point = await button.getBoundsCenter()
}
```
### isClickable9+
isClickable(): Promise\
获取控件对象可点击状态。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 以Promise形式返回控件对象可点击状态，true：可点击，false：不可点击。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
if(await button.isClickable()) {
console.info('This button can be Clicked')
}
else{
console.info('This button can not be Clicked')
}
}
```
### isLongClickable9+
isLongClickable(): Promise\
获取控件对象可长按点击状态。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 以Promise形式返回控件对象能否长按点击状态，true：可长按点击，false：不可长按点击。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
if(await button.isLongClickable()) {
console.info('This button can longClick')
}
else{
console.info('This button can not longClick')
}
}
```
### isChecked9+
isChecked(): Promise\
获取控件对象被勾选状态。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 以Promise形式返回控件对象被勾选状态，true：被勾选，false：未被勾选。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('Checkbox'))
if(await checkBox.isChecked) {
console.info('This checkBox is checked')
}
else{
console.info('This checkBox is not checked')
}
}
```
### isCheckable9+
isCheckable(): Promise\
获取控件对象能否被勾选的属性。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 错误码ID | 错误码信息 |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 以Promise形式返回控件对象能否被勾选的属性，true：可被勾选，false：不可被勾选。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 类型 | 说明 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('Checkbox'))
if(await checkBox.isCheckable) {
console.info('This checkBox is checkable')
}
else{
console.info('This checkBox is not checkable')
}
}
```
### isScrollable9+
isScrollable(): Promise\
获取控件对象可滑动状态。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 以Promise形式返回控件对象可滑动状态，true：可滑动，false：不可滑动。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.scrollable(true))
if(await scrollBar.isScrollable()) {
console.info('This scrollBar can be operated')
}
else{
console.info('This scrollBar can not be operated')
}
}
```
### isEnabled9+
isEnabled(): Promise\
获取控件使能状态。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ---------------------------------------------------------- |
| Promise\ | 以Promise形式返回控件使能状态，true：使能，false：未使能。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
if(await button.isEnabled()) {
console.info('This button can be operated')
}
else{
console.info('This button can not be operated')
}
}
```
### isFocused9+
isFocused(): Promise\
判断控件对象是否获焦。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 以Promise形式返回控件对象是否获焦，true：获焦，false：未获焦。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
if(await button.isFocused()) {
console.info('This button is focused')
}
else{
console.info('This button is not focused')
}
}
```
### isSelected9+
isSelected(): Promise\
获取控件对象被选中状态。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ----------------------------------------------------- |
| Promise\ | 控件对象被选中的状态，true：被选中，false：未被选中。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
if(await button.isSelected()) {
console.info('This button is selected')
}
else{
console.info('This button is not selected')
}
}
```
### inputText9+
inputText(text: string): Promise\
向控件中输入文本(适用于文本框控件)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------------- |
| text | string | 是 | 输入的文本信息。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.text('hello world'))
await text.inputText('123')
}
```
### clearText9+
clearText(): Promise\
清除控件的文本信息(适用于文本框控件)。
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.text('hello world'))
await text.clearText()
}
```
### scrollSearch9+
scrollSearch(on: ON): Promise\
在控件上滑动查找目标控件(适用于List等支持滑动的控件)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | 是 | 目标控件的属性要求。 |
**返回值：**
| 类型 | 说明 |
| ---------------------------------- | ------------------------------------- |
| Promise\<[Component](#component9)> | 以Promise形式返回找到的目标控件对象。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('Scroll'))
let button = await scrollBar.scrollSearch(ON.text('next page'))
}
```
### scrollToTop9+
scrollToTop(speed?: number): Promise\
在控件上滑动到顶部(适用于List等支持滑动的控件)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| speed | number | 否 | 滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('Scroll'))
await scrollBar.scrollToTop()
}
```
### scrollToBottom9+
scrollToBottom(speed?: number): Promise\
在控件上滑动到底部(适用于List等支持滑动的控件)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| speed | number | 否 | 滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('Scroll'))
await scrollBar.scrollToBottom()
}
```
### dragTo9+
dragTo(target: Component): Promise\
将控件拖拽至目标控件处。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------------------------ | ---- | ---------- |
| target | [Component](#component9) | 是 | 目标控件。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
let text = await driver.findComponent(ON.text('hello world'))
await button.dragTo(text)
}
```
### pinchOut9+
pinchOut(scale: number): Promise\
将控件按指定的比例进行捏合放大。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------------- |
| scale | number | 是 | 指定放大的比例。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('image'))
await image.pinchOut(1.5)
}
```
### pinchIn9+
pinchIn(scale: number): Promise\
将控件按指定的比例进行捏合缩小。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------------- |
| scale | number | 是 | 指定缩小的比例。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.type('image'))
await image.pinchIn(0.5)
}
```
## Driver9+
UiTest框架在API9中，Driver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等API。
该类提供的方法除Driver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await调用。
### create9+
static create(): Driver
静态方法，构造一个Driver对象，并返回该对象。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 错误码ID | 错误码信息 |
| -------- | ---------------------- |
| Driver | 返回构造的Driver对象。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 类型 | 说明 |
| -------- | ------------------ |
| 17000001 | Initialize failed. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
}
```
### delayMs9+
delayMs(duration: number): Promise\
Driver对象在给定的时间内延时。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ---------------------- |
| duration | number | 是 | 给定的时间，单位：ms。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.delayMs(1000)
}
```
### findComponent9+
findComponent(on: On): Promise\
在Driver对象中，根据给出的目标控件属性要求查找目标控件。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | 是 | 目标控件的属性要求。 |
**返回值：**
| 类型 | 说明 |
| ---------------------------------- | --------------------------------- |
| Promise\<[Component](#component9)> | 以Promise形式返回找到的控件对象。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.findComponent(ON.text('next page'))
}
```
### findComponents9+
findComponents(on: On): Promise\>
在Driver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | 是 | 目标控件的属性要求。 |
**返回值：**
| 类型 | 说明 |
| ------------------------------------------ | --------------------------------------- |
| Promise\> | 以Promise形式返回找到的控件对象的列表。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let buttonList = await driver.findComponents(ON.text('next page'))
}
```
### findWindow9+
findWindow(filter: WindowFilter): Promise\
通过指定窗口的属性来查找目标窗口。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------------------------------ | ---- | ---------------- |
| filter | [WindowFilter](#windowfilter9) | 是 | 目标窗口的属性。 |
**返回值：**
| 类型 | 说明 |
| -------------------------------- | ------------------------------------- |
| Promise\<[UiWindow](#uiwindow9)> | 以Promise形式返回找到的目标窗口对象。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
}
```
### waitForComponent9+
waitForComponent(on: On, time: number): Promise\
在Driver对象中，在用户给定的时间内，持续查找满足控件属性要求的目标控件。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------- | ---- | -------------------------------- |
| On | [On](#on9) | 是 | 目标控件的属性要求。 |
| time | number | 是 | 查找目标控件的持续时间。单位ms。 |
**返回值：**
| 类型 | 说明 |
| --------------------------------- | --------------------------------- |
| Promise\<[Component](#component)> | 以Promise形式返回找到的控件对象。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let button = await driver.waitForComponent(ON.text('next page'),500)
}
```
### assertComponentExist9+
assertComponentExist(on: On): Promise\
断言API，用于断言当前界面存在满足给出的目标控件属性的控件。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | 是 | 目标控件的属性要求。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000003 | Component existence assertion failed. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.assertComponentExist(ON.text('next page'))
}
```
### pressBack9+
pressBack(): Promise\
Driver对象进行点击BACK键的操作。
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.pressBack()
}
```
### triggerKey9+
triggerKey(keyCode: number): Promise\
Driver对象采取如下操作：通过key值找到对应键并点击。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------ | ---- | ------------- |
| keyCode | number | 是 | 指定的key值。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.triggerKey(123)
}
```
### triggerCombineKeys9+
triggerCombineKeys(key0: number, key1: number, key2?: number): Promise\
Driver对象通过给定的key值，找到对应组合键并点击。例如，Key值为(2072, 2019)时，Driver对象找到组合键并点击ctrl+c。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------- |
| key0 | number | 是 | 指定的第一个key值。 |
| key1 | number | 是 | 指定的第二个key值。 |
| key2 | number | 否 | 指定的第三个key值。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.triggerCombineKeys(2072, 2047, 2035)
}
```
### click9+
click(x: number, y: number): Promise\
Driver对象采取如下操作：在目标坐标点单击。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | 是 | 以number的形式传入目标点的横坐标信息。 |
| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.click(100,100)
}
```
### doubleClick9+
doubleClick(x: number, y: number): Promise\
Driver对象采取如下操作：在目标坐标点双击。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | 是 | 以number的形式传入目标点的横坐标信息。 |
| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.doubleClick(100,100)
}
```
### longClick9+
longClick(x: number, y: number): Promise\
Driver对象采取如下操作：在目标坐标点长按下。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | 是 | 以number的形式传入目标点的横坐标信息。 |
| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.longClick(100,100)
}
```
### swipe9+
swipe(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\
Driver对象采取如下操作：从给出的起始坐标点滑向给出的目的坐标点。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| startx | number | 是 | 以number的形式传入起始点的横坐标信息。 |
| starty | number | 是 | 以number的形式传入起始点的纵坐标信息。 |
| endx | number | 是 | 以number的形式传入目的点的横坐标信息。 |
| endy | number | 是 | 以number的形式传入目的点的纵坐标信息。 |
| speed | number | 否 | 滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.swipe(100,100,200,200,600)
}
```
### drag9+
drag(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\
Driver对象采取如下操作：从给出的起始坐标点拖拽至给出的目的坐标点。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| startx | number | 是 | 以number的形式传入起始点的横坐标信息。 |
| starty | number | 是 | 以number的形式传入起始点的纵坐标信息。 |
| endx | number | 是 | 以number的形式传入目的点的横坐标信息。 |
| endy | number | 是 | 以number的形式传入目的点的纵坐标信息。 |
| speed | number | 否 | 滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.drag(100,100,200,200,600)
}
```
### screenCap9+
screenCap(savePath: string): Promise\
Driver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | -------------- |
| savePath | string | 是 | 文件保存路径。 |
**返回值：**
| 类型 | 说明 |
| ----------------- | -------------------------------------- |
| Promise\ | 截图操作是否成功完成。成功完成为true。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.screenCap('/local/tmp/')
}
```
### setDisplayRotation9+
setDisplayRotation(rotation: DisplayRotation): Promise\
将设备的屏幕显示方向设置为指定的显示方向。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------ | ---- | ---------------- |
| rotation | [DisplayRotation](#displayrotation9) | 是 | 设备的显示方向。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.setDisplayRotation(DisplayRotation.ROTATION_180)
}
```
### getDisplayRotation9+
getDisplayRotation(): Promise\
获取当前设备的屏幕显示方向。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ---------------------------------------------- | --------------------------------------- |
| Promise\<[DisplayRotation](#displayrotation9)> | 以Promise的形式返回当前设备的显示方向。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let rotation = await driver.getDisplayRotation()
}
```
### setDisplayRotationEnabled9+
setDisplayRotationEnabled(enabled: boolean): Promise\
启用/禁用设备旋转屏幕的功能。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------- | ---- | ------------------------------------------------------- |
| enabled | boolean | 是 | 能否旋转屏幕的标识，true：可以旋转，false：不可以旋转。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.setDisplayRotationEnabled(false)
}
```
### getDisplaySize9+
getDisplaySize(): Promise\
获取当前设备的屏幕大小。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| -------------------------- | --------------------------------------- |
| Promise\<[Point](#point9)> | 以Promise的形式返回当前设备的屏幕大小。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let size = await driver.getDisplaySize()
}
```
### getDisplayDensity9+
getDisplayDensity(): Promise\
获取当前设备的屏幕的分辨率。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| -------------------------- | ------------------------------------------- |
| Promise\<[Point](#point9)> | 以Promise的形式返回当前设备的屏幕的分辨率。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let density = await driver.getDisplayDensity()
}
```
### wakeUpDisplay9+
wakeUpDisplay(): Promise\
唤醒当前设备的屏幕。
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.wakeUpDisplay()
}
```
### pressHome9+
pressHome(): Promise\
设备返回到桌面。
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.pressHome()
}
```
### waitForIdle9+
waitForIdle(idleTime: number, timeout: number): Promise\
判断当前界面的所有控件是否已经空闲。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| idleTime | number | 是 | 空闲时间的阈值。在这个时间段控件不发生变化，视为该控件空闲，单位：毫秒。 |
| timeout | number | 是 | 等待空闲的最大时间，单位：毫秒。 |
**返回值：**
| 类型 | 说明 |
| ----------------- | --------------------------------------------------- |
| Promise\ | 以Promise的形式返回当前界面的所有控件是否已经空闲。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let idled = await driver.waitForIdle(4000,5000)
}
```
### fling9+
fling(from: Point, to: Point, stepLen: number, speed: number): Promise\
模拟手指滑动后脱离屏幕的快速滑动操作。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ---------------- | ---- | ------------------------------------------------------------ |
| from | [Point](#point9) | 是 | 手指接触屏幕的起始点坐标。 |
| to | [Point](#point9) | 是 | 手指离开屏幕时的坐标点。 |
| stepLen | number | 是 | 间隔距离，单位：像素点。 |
| speed | number | 是 | 滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
await driver.fling({X: 500, Y: 480},{X: 450, Y: 480},5,600)
}
```
### injectMultiPointerAction9+
injectMultiPointerAction(pointers: PointerMatrix, speed?: number): Promise\
向设备注入多指操作。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------------- | ---- | ------------------------------------------------------------ |
| pointers | [PointerMatrix](#pointermatrix9) | 是 | 起始点的坐标。 |
| speed | number | 否 | 滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。 |
**返回值：**
| 类型 | 说明 |
| ----------------- | ----------------------------------------- |
| Promise\ | 以Promise的形式返回植入操作是否成功完成。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let pointers = PointerMatrix.create(2,3)
pointers.setPoint(0,0,{X:230,Y:480})
pointers.setPoint(0,1,{X:250,Y:380})
pointers.setPoint(0,2,{X:270,Y:280})
pointers.setPoint(1,0,{X:230,Y:680})
pointers.setPoint(1,1,{X:240,Y:580})
pointers.setPoint(1,2,{X:250,Y:480})
await driver.injectMultiPointerAction(pointers)
}
```
## PointerMatrix9+
表示存储多指操作中每根手指每一步动作的坐标点及其行为的二维数组。
### create9+
static create(fingers: number, steps: number): PointerMatrix
静态方法，构造一个PointerMatrix对象，并返回该对象。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------ | ---- | ------------------------------------------ |
| fingers | number | 是 | 多指操作中注入的手指数，取值范围：[1,10]。 |
| steps | number | 是 | 每根手指操作的步骤数，取值范围：[1,1000]。 |
**返回值：**
| 类型 | 说明 |
| -------------------------------- | ----------------------------- |
| [PointerMatrix](#pointermatrix9) | 返回构造的PointerMatrix对象。 |
**示例：**
```js
async function demo() {
let pointerMatrix = PointerMatrix.create(2,3)
}
```
### setPoint9+
setPoint(finger: number, step: number, point: Point): void
设置PointerMatrix对象中指定手指和步骤对应动作的坐标点。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------------- | ---- | ---------------- |
| finger | number | 是 | 手指的序号。 |
| step | number | 是 | 步骤的序号。 |
| point | [Point](#point9) | 是 | 该行为的坐标点。 |
**示例：**
```js
async function demo() {
let pointers = PointerMatrix.create(2,3)
pointers.setPoint(0,0,{X:230,Y:480})
pointers.setPoint(0,1,{X:250,Y:380})
pointers.setPoint(0,2,{X:270,Y:280})
pointers.setPoint(1,0,{X:230,Y:680})
pointers.setPoint(1,1,{X:240,Y:580})
pointers.setPoint(1,2,{X:250,Y:480})
}
```
## UiWindow9+
UiTest中，UiWindow类代表了UI界面上的一个窗口，提供窗口属性获取，窗口拖动、调整窗口大小等API。
该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。
### getBundleName9+
getBundleName(): Promise\
获取窗口的包名信息。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ---------------- | --------------------------------- |
| Promise\ | 以Promise形式返回窗口的包名信息。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
let name = await window.getBundleName()
}
```
### getBounds9+
getBounds(): Promise\
获取窗口的边框信息。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ------------------------ | --------------------------------- |
| Promise\<[Rect](#rect9)> | 以Promise形式返回窗口的边框信息。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
let rect = await window.getBounds()
}
```
### getTitle9+
getTitle(): Promise\
获取窗口的标题信息。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ---------------- | --------------------------------- |
| Promise\ | 以Promise形式返回窗口的标题信息。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
let rect = await window.getTitle()
}
```
### getWindowMode9+
getWindowMode(): Promise\
获取窗口的窗口模式信息。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ------------------------------------ | ------------------------------------- |
| Promise\<[WindowMode](#windowmode9)> | 以Promise形式返回窗口的窗口模式信息。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
let mode = await window.getWindowMode()
}
```
### isFocused9+
isFocused(): Promise\
判断窗口是否获焦。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 以Promise形式返回窗口对象是否获焦，true：获焦，false：未获焦。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
let focused = await window.isFocused()
}
```
### isActived9+
isActived(): Promise\
判断窗口是否为用户交互窗口。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 以Promise形式返回窗口对象是否为用户交互窗口，true：交互窗口，false：非交互窗口。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
let focused = await window.isActived()
}
```
### focus9+
focus(): Promise\
让窗口获焦。
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.focus()
}
```
### moveTo9+
moveTo(x: number, y: number): Promise\
将窗口移动到目标点。适用于支持移动的窗口。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | 是 | 以number的形式传入目标点的横坐标信息。 |
| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
| 17000005 | This operation is not supported. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.moveTo(100, 100)
}
```
### resize9+
resize(wide: number, height: number, direction: ResizeDirection): Promise\
根据传入的宽、高和调整方向来调整窗口的大小。适用于支持大小调整的窗口。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------------------------------------ | ---- | ------------------------------------------------------------ |
| wide | number | 是 | 以number的形式传入调整后窗口的宽度。 |
| height | number | 是 | 以number的形式传入调整后窗口的高度。 |
| direction | [ResizeDirection](#resizedirection9) | 是 | 以[ResizeDirection](#resizedirection9)的形式传入窗口调整的方向。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
| 17000005 | This operation is not supported. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.resize(100, 100, ResizeDirection.LEFT)
}
```
### split9+
split(): Promise\
将窗口模式切换成分屏模式。适用于支持切屏操作的窗口。
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 类型 | 说明 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
| 17000005 | This operation is not supported. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.split()
}
```
### maximize9+
maximize(): Promise\
将窗口最大化。适用于支持窗口最大化操作的窗口。
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
| 17000005 | This operation is not supported. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.maximize()
}
```
### minimize9+
minimize(): Promise\
将窗口最小化。适用于支持窗口最小化操作的窗口。
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
| 17000005 | This operation is not supported. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.minimize()
}
```
### resume9+
resume(): Promise\
将窗口恢复到之前的窗口模式。
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
| 17000005 | This operation is not supported. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.resume()
}
```
### close9+
close(): Promise\
将窗口关闭。
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
| 17000005 | This operation is not supported. |
**示例：**
```js
async function demo() {
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.close()
}
```
## MatchPattern
控件属性支持的匹配模式。
**系统能力**：SystemCapability.Test.UiTest
| 名称 | 值 | 说明 |
| ----------- | ---- | -------------- |
| EQUALS | 0 | 等于给定值。 |
| CONTAINS | 1 | 包含给定值。 |
| STARTS_WITH | 2 | 从给定值开始。 |
| ENDS_WITH | 3 | 以给定值结束。 |
## ResizeDirection9+
窗口调整大小的方向。
**系统能力**：SystemCapability.Test.UiTest
| 名称 | 说明 |
| ---------- | -------- |
| LEFT | 左方。 |
| RIGHT | 右方。 |
| UP | 上方。 |
| DOWN | 下方。 |
| LEFT_UP | 左上方。 |
| LEFT_DOWN | 左下方。 |
| RIGHT_UP | 右上方。 |
| RIGHT_DOWN | 右下方。 |
## Point9+
坐标点信息。
**系统能力**：SystemCapability.Test.UiTest
| 名称 | 参数类型 | 可读 | 可写 | 描述 |
| ---- | -------- | ---- | ---- | ---------------- |
| X | number | 是 | 否 | 坐标点的横坐标。 |
| Y | number | 是 | 否 | 坐标点的纵坐标。 |
## Rect9+
控件的边框信息。
**系统能力**：SystemCapability.Test.UiTest
| 名称 | 参数类型 | 可读 | 可写 | 描述 |
| ------- | -------- | ---- | ---- | ------------------------- |
| leftX | number | 是 | 否 | 控件边框的左上角的X坐标。 |
| topY | number | 是 | 否 | 控件边框的左上角的Y坐标。 |
| rightX | number | 是 | 否 | 控件边框的右下角的X坐标。 |
| bottomY | number | 是 | 否 | 控件边框的右下角的Y坐标。 |
## WindowMode9+
**系统能力**：SystemCapability.Test.UiTest
窗口的窗口模式。
| 名称 | 说明 |
| ---------- | ---------- |
| FULLSCREEN | 全屏模式。 |
| PRIMARY | 主窗口。 |
| SECONDARY | 第二窗口。 |
| FLOATING | 浮动窗口。 |
## DisplayRotation9+
**系统能力**：SystemCapability.Test.UiTest
设备显示器的显示方向。
| 名称 | 说明 |
| ------------ | ---------------------------------------- |
| ROTATION_0 | 设备显示器不旋转，初始形态垂直显示。 |
| ROTATION_90 | 设备显示器顺时针旋转90°，水平显示。 |
| ROTATION_180 | 设备显示器顺时针旋转180°，逆向垂直显示。 |
| ROTATION_270 | 设备显示器顺时针旋转270°，逆向水平显示。 |
## WindowFilter9+
窗口的标志属性信息。
**系统能力**：SystemCapability.Test.UiTest
| 名称 | 参数类型 | 必填 | 可读 | 可写 | 描述 |
| ---------- | -------- | ---- | ---- | ---- | -------------------------- |
| bundleName | string | 否 | 是 | 否 | 窗口对应的包名。 |
| title | string | 否 | 是 | 否 | 窗口的标题。 |
| focused | boolean | 否 | 是 | 否 | 窗口是否获焦。 |
| actived | boolean | 否 | 是 | 否 | 窗口是否正与用户进行交互。 |
## By(deprecated)
UiTest框架通过By类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。
By提供的API能力具有以下几个特点:
1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。
2、控件属性支持多种匹配模式。
3、支持控件绝对定位，相对定位，可通过[By.isBefore](#isbefore)和[By.isAfter](#isafter)等API限定邻近控件特征进行辅助定位。
By类提供的所有API均为同步接口，建议使用者通过静态构造器BY来链式创建By对象。
从API version9开始不再维护，建议使用[On9+](#on9)。
```js
BY.text('123').type('button')
```
### text(deprecated)
text(txt: string, pattern?: MatchPattern): By
指定目标控件文本属性，支持多种匹配模式，返回By对象自身。
从API version9开始不再维护，建议使用[text9+](#text9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ----------------------------- | ---- | --------------------------------------------------- |
| txt | string | 是 | 指定控件文本，用于匹配目标控件文本。 |
| pattern | [MatchPattern](#matchpattern) | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------- |
| [By](#by) | 返回指定目标控件文本属性的By对象。 |
**示例：**
```js
let by = BY.text('123') //使用静态构造器BY创建by对象，指定目标控件的text属性。
```
### key(deprecated)
key(key: string): By
指定目标控件key值属性，返回By对象自身。
从API version9开始不再维护，建议使用[id9+](#id9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ----------------- |
| key | string | 是 | 指定控件的Key值。 |
**返回值：**
| 类型 | 说明 |
| --------- | ----------------------------------- |
| [By](#by) | 返回指定目标控件key值属性的By对象。 |
**示例：**
```js
let by = BY.key('123') //使用静态构造器BY创建by对象，指定目标控件的key值属性。
```
### id(deprecated)
id(id: number): By
指定目标控件id属性，返回By对象自身。
从API version9开始不再维护，被废弃。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------------- |
| id | number | 是 | 指定控件的id值。 |
**返回值：**
| 类型 | 说明 |
| --------- | -------------------------------- |
| [By](#by) | 返回指定目标控件id属性的By对象。 |
**示例：**
```js
let by = BY.id(123) //使用静态构造器BY创建by对象，指定目标控件的id属性。
```
### type(deprecated)
type(tp: string): By
指定目标控件的控件类型属性，返回By对象自身。
从API version9开始不再维护，建议使用[type9+](#type9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------------- |
| tp | string | 是 | 指定控件类型。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------- |
| [By](#by) | 返回指定目标控件的控件类型属性的By对象。 |
**示例：**
```js
let by = BY.type('button') //使用静态构造器BY创建by对象，指定目标控件的控件类型属性。
```
### clickable(deprecated)
clickable(b?: boolean): By
指定目标控件的可点击状态属性，返回By对象自身。
从API version9开始不再维护，建议使用[clickable9+](#clickable9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | 否 | 指定控件可点击状态，true：可点击，false：不可点击。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ------------------------------------------ |
| [By](#by) | 返回指定目标控件的可点击状态属性的By对象。 |
**示例：**
```js
let by = BY.clickable(true) //使用静态构造器BY创建by对象，指定目标控件的可点击状态属性。
```
### scrollable(deprecated)
scrollable(b?: boolean): By
指定目标控件的可滑动状态属性，返回By对象自身。
从API version9开始不再维护，建议使用[scrollable9+](#scrollable9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ----------------------------------------------------------- |
| b | boolean | 否 | 控件可滑动状态，true：可滑动，false：不可滑动。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ------------------------------------------ |
| [By](#by) | 返回指定目标控件的可滑动状态属性的By对象。 |
**示例：**
```js
let by = BY.scrollable(true) //使用静态构造器BY创建by对象，指定目标控件的可滑动状态属性。
```
### enabled(deprecated)
enabled(b?: boolean): By
指定目标控件的使能状态属性，返回By对象自身。
从API version9开始不再维护，建议使用[enabled9+](#enabled9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | --------------------------------------------------------- |
| b | boolean | 否 | 指定控件使能状态，true：使能，false：未使能。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------- |
| [By](#by) | 返回指定目标控件的使能状态属性的By对象。 |
**示例：**
```js
let by = BY.enabled(true) //使用静态构造器BY创建by对象，指定目标控件的使能状态属性。
```
### focused(deprecated)
focused(b?: boolean): By
指定目标控件的获焦状态属性，返回By对象自身。
从API version9开始不再维护，建议使用[focused9+](#focused9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ----------------------------------------------------- |
| b | boolean | 否 | 控件获焦状态，true：获焦，false：未获焦。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------- |
| [By](#by) | 返回指定目标控件的获焦状态属性的By对象。 |
**示例：**
```js
let by = BY.focused(true) //使用静态构造器BY创建by对象，指定目标控件的获焦状态属性。
```
### selected(deprecated)
selected(b?: boolean): By
指定目标控件的被选中状态属性，返回By对象自身。
从API version9开始不再维护，建议使用[selected9+](#selected9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | 否 | 指定控件被选中状态，true：被选中，false：未被选中。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ------------------------------------------ |
| [By](#by) | 返回指定目标控件的被选中状态属性的By对象。 |
**示例：**
```js
let by = BY.selected(true) //使用静态构造器BY创建by对象，指定目标控件的被选中状态属性。
```
### isBefore(deprecated)
isBefore(by: By): By
指定目标控件位于给出的特征属性控件之前，返回By对象自身。
从API version9开始不再维护，建议使用[isBefore9+](#isbefore9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | ---------------- |
| by | [By](#by) | 是 | 特征控件的属性。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------------------- |
| [By](#by) | 返回指定目标控件位于给出的特征属性控件之前的By对象。 |
**示例：**
```js
let by = BY.isBefore(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之前。
```
### isAfter(deprecated)
isAfter(by: By): By
指定目标控件位于给出的特征属性控件之后，返回By对象自身。
从API version9开始不再维护，建议使用[isAfter9+](#isafter9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | ---------------- |
| by | [By](#by) | 是 | 特征控件的属性。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------------------- |
| [By](#by) | 返回指定目标控件位于给出的特征属性控件之后的By对象。 |
**示例：**
```js
let by = BY.isAfter(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之后。
```
## UiComponent(deprecated)
UiTest中，UiComponent类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。
该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。
从API version9开始不再维护，建议使用[Component9+](#component9)。
### click(deprecated)
click(): Promise\
控件对象进行点击操作。
从API version9开始不再维护，建议使用[click9+](#click9)。
**系统能力**：SystemCapability.Test.UiTest
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
await button.click()
}
```
### doubleClick(deprecated)
doubleClick(): Promise\
控件对象进行双击操作。
从API version9开始不再维护，建议使用[doubleClick9+](#doubleclick9)。
**系统能力**：SystemCapability.Test.UiTest
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
await button.doubleClick()
}
```
### longClick(deprecated)
longClick(): Promise\
控件对象进行长按操作。
从API version9开始不再维护，建议使用[longClick9+](#longclick9)。
**系统能力**：SystemCapability.Test.UiTest
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
await button.longClick()
}
```
### getId(deprecated)
getId(): Promise\
获取控件对象的id值。
从API version9开始不再维护，建议使用[getId9+](#getid9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ---------------- | ------------------------------- |
| Promise\ | 以Promise形式返回的控件的id值。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let num = await button.getId()
}
```
### getKey(deprecated)
getKey(): Promise\
获取控件对象的key值。
从API version9开始不再维护，被废弃。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ---------------- | ------------------------------ |
| Promise\ | 以Promise形式返回控件的key值。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let str_key = await button.getKey()
}
```
### getText(deprecated)
getText(): Promise\
获取控件对象的文本信息。
从API version9开始不再维护，建议使用[getText9+](#gettext9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ---------------- | --------------------------------- |
| Promise\ | 以Promise形式返回控件的文本信息。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let text = await button.getText()
}
```
### getType(deprecated)
getType(): Promise\
获取控件对象的控件类型。
从API version9开始不再维护，建议使用[getType9+](#gettype9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ---------------- | ----------------------------- |
| Promise\ | 以Promise形式返回控件的类型。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let type = await button.getType()
}
```
### isClickable(deprecated)
isClickable(): Promise\
获取控件对象可点击状态。
从API version9开始不再维护，建议使用[isClickable9+](#isclickable9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 以Promise形式返回控件对象可点击状态，true：可点击，false：不可点击。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
if(await button.isClickable()) {
console.info('This button can be Clicked')
}
else{
console.info('This button can not be Clicked')
}
}
```
### isScrollable(deprecated)
isScrollable(): Promise\
获取控件对象可滑动状态。
从API version9开始不再维护，建议使用[isScrollable9+](#isscrollable9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 以Promise形式返回控件对象可滑动状态，true：可滑动，false：不可滑动。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let scrollBar = await driver.findComponent(BY.scrollable(true))
if(await scrollBar.isScrollable()) {
console.info('This scrollBar can be operated')
}
else{
console.info('This scrollBar can not be operated')
}
}
```
### isEnabled(deprecated)
isEnabled(): Promise\
获取控件使能状态。
从API version9开始不再维护，建议使用[isEnabled9+](#isenabled9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ---------------------------------------------------------- |
| Promise\ | 以Promise形式返回控件使能状态，true：使能，false：未使能。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
if(await button.isEnabled()) {
console.info('This button can be operated')
}
else{
console.info('This button can not be operated')
}
}
```
### isFocused(deprecated)
isFocused(): Promise\
判断控件对象是否获焦。
从API version9开始不再维护，建议使用[isFocused9+](#isfocused9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\ | 以Promise形式返回控件对象是否获焦，true：获焦，false：未获焦。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
if(await button.isFocused()) {
console.info('This button is focused')
}
else{
console.info('This button is not focused')
}
}
```
### isSelected(deprecated)
isSelected(): Promise\
获取控件对象被选中状态。
从API version9开始不再维护，建议使用[isSelected9+](#isselected9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ----------------------------------------------------- |
| Promise\ | 控件对象被选中的状态，true：被选中，false：未被选中。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
if(await button.isSelected()) {
console.info('This button is selected')
}
else{
console.info('This button is not selected')
}
}
```
### inputText(deprecated)
inputText(text: string): Promise\
向控件中输入文本(适用于文本框控件)。
从API version9开始不再维护，建议使用[inputText9+](#inputtext9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------------- |
| text | string | 是 | 输入的文本信息。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let text = await driver.findComponent(BY.text('hello world'))
await text.inputText('123')
}
```
### scrollSearch(deprecated)
scrollSearch(by: By): Promise\
在控件上滑动查找目标控件(适用于List等支持滑动的控件)。
从API version9开始不再维护，建议使用[scrollSearch9+](#scrollsearch9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | -------------------- |
| by | [By](#by) | 是 | 目标控件的属性要求。 |
**返回值：**
| 类型 | 说明 |
| ------------------------------------- | ------------------------------------- |
| Promise\<[UiComponent](#uicomponent)> | 以Promise形式返回找到的目标控件对象。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let scrollBar = await driver.findComponent(BY.type('Scroll'))
let button = await scrollBar.scrollSearch(BY.text('next page'))
}
```
## UiDriver(deprecated)
UiDriver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等API。
该类提供的方法除UiDriver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await调用。
从API version9开始不再维护，建议使用[Driver9+](#driver9)。
### create(deprecated)
static create(): UiDriver
静态方法，构造一个UiDriver对象，并返回该对象。
从API version9开始不再维护，建议使用[create9+](#create9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| -------- | ------------------------ |
| UiDriver | 返回构造的UiDriver对象。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
}
```
### delayMs(deprecated)
delayMs(duration: number): Promise\
UiDriver对象在给定的时间内延时。
从API version9开始不再维护，建议使用[delayMs9+](#delayms9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ------------ |
| duration | number | 是 | 给定的时间。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.delayMs(1000)
}
```
### findComponent(deprecated)
findComponent(by: By): Promise\
在UiDriver对象中，根据给出的目标控件属性要求查找目标控件。
从API version9开始不再维护，建议使用[findComponent9+](#findcomponent9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | -------------------- |
| by | [By](#by) | 是 | 目标控件的属性要求。 |
**返回值：**
| 类型 | 说明 |
| ------------------------------------- | --------------------------------- |
| Promise\<[UiComponent](#uicomponent)> | 以Promise形式返回找到的控件对象。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.text('next page'))
}
```
### findComponents(deprecated)
findComponents(by: By): Promise\>
在UiDriver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。
从API version9开始不再维护，建议使用[findComponents9+](#findcomponents9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | -------------------- |
| by | [By](#by) | 是 | 目标控件的属性要求。 |
**返回值：**
| 类型 | 说明 |
| --------------------------------------------- | --------------------------------------- |
| Promise\> | 以Promise形式返回找到的控件对象的列表。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let buttonList = await driver.findComponents(BY.text('next page'))
}
```
### assertComponentExist(deprecated)
assertComponentExist(by: By): Promise\
断言API，用于断言当前界面存在满足给出的目标控件属性的控件; 如果控件不存在，该API将抛出JS异常，使当前测试用例失败。
从API version9开始不再维护，建议使用[assertComponentExist9+](#assertcomponentexist9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | -------------------- |
| by | [By](#by) | 是 | 目标控件的属性要求。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.assertComponentExist(BY.text('next page'))
}
```
### pressBack(deprecated)
pressBack(): Promise\
UiDriver对象进行点击BACK键的操作。
从API version9开始不再维护，建议使用[pressBack9+](#pressback9)。
**系统能力**：SystemCapability.Test.UiTest
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.pressBack()
}
```
### triggerKey(deprecated)
triggerKey(keyCode: number): Promise\
UiDriver对象采取如下操作：通过key值找到对应键并点击。
从API version9开始不再维护，建议使用[triggerKey9+](#triggerkey9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------ | ---- | ------------- |
| keyCode | number | 是 | 指定的key值。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.triggerKey(123)
}
```
### click(deprecated)
click(x: number, y: number): Promise\
UiDriver对象采取如下操作：在目标坐标点单击。
从API version9开始不再维护，建议使用[click9+](#click9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | 是 | 以number的形式传入目标点的横坐标信息。 |
| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.click(100,100)
}
```
### doubleClick(deprecated)
doubleClick(x: number, y: number): Promise\
UiDriver对象采取如下操作：在目标坐标点双击。
从API version9开始不再维护，建议使用[doubleClick9+](#doubleclick9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | 是 | 以number的形式传入目标点的横坐标信息。 |
| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.doubleClick(100,100)
}
```
### longClick(deprecated)
longClick(x: number, y: number): Promise\
UiDriver对象采取如下操作：在目标坐标点长按下鼠标左键。
从API version9开始不再维护，建议使用[longClick9+](#longclick9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | 是 | 以number的形式传入目标点的横坐标信息。 |
| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.longClick(100,100)
}
```
### swipe(deprecated)
swipe(startx: number, starty: number, endx: number, endy: number): Promise\
UiDriver对象采取如下操作：从给出的起始坐标点滑向给出的目的坐标点。
从API version9开始不再维护，建议使用[swipe9+](#swipe9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------------------------------------- |
| startx | number | 是 | 以number的形式传入起始点的横坐标信息。 |
| starty | number | 是 | 以number的形式传入起始点的纵坐标信息。 |
| endx | number | 是 | 以number的形式传入目的点的横坐标信息。 |
| endy | number | 是 | 以number的形式传入目的点的纵坐标信息。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.swipe(100,100,200,200)
}
```
### screenCap(deprecated)
screenCap(savePath: string): Promise\
UiDriver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。
从API version9开始不再维护，建议使用[screenCap9+](#screencap9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | -------------- |
| savePath | string | 是 | 文件保存路径。 |
**返回值：**
| 类型 | 说明 |
| ----------------- | -------------------------------------- |
| Promise\ | 截图操作是否成功完成。成功完成为true。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.screenCap('/local/tmp/')
}
```