From 2e6eccffe3ee0bcda5d6f91ad19d36e51d74d3ec Mon Sep 17 00:00:00 2001 From: zhouke Date: Thu, 26 May 2022 10:20:36 +0800 Subject: [PATCH] =?UTF-8?q?=203.1release=E5=88=86=E6=94=AFjs-apis-uitest.m?= =?UTF-8?q?d=E8=A7=84=E8=8C=83=E4=BF=AE=E6=94=B9=EF=BC=8C=E5=A2=9E?= =?UTF-8?q?=E5=8A=A0=E6=96=B0=E6=8E=A5=E5=8F=A3=E6=8F=8F=E8=BF=B0.=20Signe?= =?UTF-8?q?d-off-by:=20.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: zhouke --- .../reference/apis/js-apis-uitest.md | 577 ++++++++---------- 1 file changed, 257 insertions(+), 320 deletions(-) diff --git a/zh-cn/application-dev/reference/apis/js-apis-uitest.md b/zh-cn/application-dev/reference/apis/js-apis-uitest.md index db3eb654d2..e80af5529d 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-uitest.md +++ b/zh-cn/application-dev/reference/apis/js-apis-uitest.md @@ -13,42 +13,27 @@ import {UiDriver,BY,MatchPattern} from '@ohos.uitest' ## By -UiTest框架通过By类提供了丰富的控件特征描述API，用以进行控件筛选来匹配/查找出目标控件。 -By提供的API能力具有以下几个特点: - 1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id - 2、控件属性支持多种匹配模式 - 3、支持控件绝对定位，相对定位，可通过isBefore和isAfter等API限定邻近控件特征进行辅助定位 -By类提供的所有API均为同步接口，建议使用者通过静态构造器BY来链式创建By对象，例如：BY.text('123').type('button') +UiTest框架通过By类提供了丰富的控件特征描述API，用以进行控件筛选来匹配/查找出目标控件。
+By提供的API能力具有以下几个特点:
1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。
2、控件属性支持多种匹配模式。
3、支持控件绝对定位，相对定位，可通过[By.isBefore](#byisbefore)和[By.isAfter](#byisafter)等API限定邻近控件特征进行辅助定位。
By类提供的所有API均为同步接口，建议使用者通过静态构造器BY来链式创建By对象。 -### enum MatchPattern - -控件属性支持的匹配模式 - -**系统能力**：以下各项对应的系统能力均为SystemCapability.Test.UiTest - -| 名称 | 值 | 说明 | -| ----------- | ---- | ------------ | -| EQUALS | 0 | 等于给定值 | -| CONTAINS | 1 | 包含给定值 | -| STARTS_WITH | 2 | 以给定值开始 | -| ENDS_WITH | 3 | 以给定值结束 | +```js +BY.text('123').type('button') +``` ### By.text -text(txt:string,pattern?:MatchPattern):By +text(txt: string, pattern?: MatchPattern): By 指定目标控件文本属性，支持多种匹配模式，返回By对象自身。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------------ | ---- | ---------------------------------- | -| txt | string | 是 | 指定控件文本，用于匹配目标控件文本 | -| pattern | MatchPattern | 否 | 指定的文本匹配模式，默认为EQUALS | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------ | ---- | ------------------------------------------------- | +| txt | string | 是 | 指定控件文本，用于匹配目标控件文本。 | +| pattern | MatchPattern | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern) | **返回值：** @@ -58,293 +43,273 @@ text(txt:string,pattern?:MatchPattern):By **示例：** -``` -let by = BY.text('123') //使用静态构造器BY创建by对象，指定目标控件的text属性 +```js +let by = BY.text('123') //使用静态构造器BY创建by对象，指定目标控件的text属性。 ``` ### By.key -key(key:string):By; +key(key: string): By 指定目标控件key值属性，返回By对象自身。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | --------------- | -| key | string | 是 | 指定控件的Key值 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ----------------- | +| key | string | 是 | 指定控件的Key值。 | **返回值：** -| 类型 | 说明 | -| ---- | -------------- | -| By | 返回By对象自身 | +| 类型 | 说明 | +| ---- | ---------------- | +| By | 返回By对象自身。 | **示例：** -``` -let by = BY.key('123') //使用静态构造器BY创建by对象，指定目标控件的key值属性 +```js +let by = BY.key('123') //使用静态构造器BY创建by对象，指定目标控件的key值属性。 ``` ### By.id -id(id:number):By; +id(id: number): By 指定目标控件id属性，返回By对象自身。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | ------------ | -| id | number | 是 | 指定控件id值 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------- | +| id | number | 是 | 指定控件的id值。 | **返回值：** -| 类型 | 说明 | -| ---- | -------------- | -| By | 返回By对象自身 | +| 类型 | 说明 | +| ---- | ---------------- | +| By | 返回By对象自身。 | **示例：** -``` -let by = BY.id(123) //使用静态构造器BY创建by对象，指定目标控件的id属性 +```js +let by = BY.id(123) //使用静态构造器BY创建by对象，指定目标控件的id属性。 ``` ### By.type -type(tp:string):By; +type(tp: string): By 指定目标控件的控件类型属性，返回By对象自身。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | ------------ | -| tp | string | 是 | 指定控件类型 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------- | +| tp | string | 是 | 指定控件类型。 | **返回值：** -| 类型 | 说明 | -| ---- | -------------- | -| By | 返回By对象自身 | +| 类型 | 说明 | +| ---- | ---------------- | +| By | 返回By对象自身。 | **示例：** -``` -let by = BY.type('button') //使用静态构造器BY创建by对象，指定目标控件的控件类型属性 +```js +let by = BY.type('button') //使用静态构造器BY创建by对象，指定目标控件的控件类型属性。 ``` ### By.clickable -clickable(b?:bool):By; +clickable(b?: bool): By 指定目标控件的可点击状态属性，返回By对象自身。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | ------------------------------ | -| b | bool | 否 | 指定控件可点击状态，默认为true | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---- | ---- | -------------------------------- | +| b | bool | 否 | 指定控件可点击状态，默认为true。 | **返回值：** -| 类型 | 说明 | -| ---- | -------------- | -| By | 返回By对象自身 | +| 类型 | 说明 | +| ---- | ---------------- | +| By | 返回By对象自身。 | **示例：** -``` -let by = BY.clickable(true) //使用静态构造器BY创建by对象，指定目标控件的可点击状态属性 +```js +let by = BY.clickable(true) //使用静态构造器BY创建by对象，指定目标控件的可点击状态属性。 ``` ### By.scrollable -scrollable(b?:bool):By; +scrollable(b?: bool): By 指定目标控件的可滑动状态属性，返回By对象自身。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | -------------------------- | -| b | bool | 否 | 控件可滑动状态，默认为true | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---- | ---- | ---------------------------- | +| b | bool | 否 | 控件可滑动状态，默认为true。 | **返回值：** -| 类型 | 说明 | -| ---- | -------------- | -| By | 返回By对象自身 | +| 类型 | 说明 | +| ---- | ---------------- | +| By | 返回By对象自身。 | **示例：** -``` -let by = BY.scrollable(true) //使用静态构造器BY创建by对象，指定目标控件的可滑动状态属性 +```js +let by = BY.scrollable(true) //使用静态构造器BY创建by对象，指定目标控件的可滑动状态属性。 ``` ### By.enabled -enabled(b?:bool):By; +enabled(b?: bool): By 指定目标控件的使能状态属性，返回By对象自身。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | ---------------------------- | -| b | bool | 否 | 指定控件使能状态，默认为true | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---- | ---- | ------------------------------ | +| b | bool | 否 | 指定控件使能状态，默认为true。 | **返回值：** -| 类型 | 说明 | -| ---- | -------------- | -| By | 返回By对象自身 | +| 类型 | 说明 | +| ---- | ---------------- | +| By | 返回By对象自身。 | **示例：** -``` -let by = BY.enabled(true) //使用静态构造器BY创建by对象，指定目标控件的使能状态属性 +```js +let by = BY.enabled(true) //使用静态构造器BY创建by对象，指定目标控件的使能状态属性。 ``` ### By.focused -focused(b?:bool):By; +focused(b?: bool): By 指定目标控件的获焦状态属性，返回By对象自身。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | ------------------------ | -| b | bool | 否 | 控件获焦状态，默认为true | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---- | ---- | -------------------------- | +| b | bool | 否 | 控件获焦状态，默认为true。 | **返回值：** -| 类型 | 说明 | -| ---- | -------------- | -| By | 返回By对象自身 | +| 类型 | 说明 | +| ---- | ---------------- | +| By | 返回By对象自身。 | **示例：** -``` -let by = BY.focused(true) //使用静态构造器BY创建by对象，指定目标控件的获焦状态属性 +```js +let by = BY.focused(true) //使用静态构造器BY创建by对象，指定目标控件的获焦状态属性。 ``` ### By.selected -selected(b?:bool):By; +selected(b?: bool): By 指定目标控件的被选中状态属性，返回By对象自身。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | ------------------------------ | -| b | bool | 否 | 指定控件被选中状态，默认为true | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---- | ---- | -------------------------------- | +| b | bool | 否 | 指定控件被选中状态，默认为true。 | **返回值：** -| 类型 | 说明 | -| ---- | -------------- | -| By | 返回By对象自身 | +| 类型 | 说明 | +| ---- | ---------------- | +| By | 返回By对象自身。 | **示例：** -``` -let by = BY.selected(true) //使用静态构造器BY创建by对象，指定目标控件的被选中状态属性 +```js +let by = BY.selected(true) //使用静态构造器BY创建by对象，指定目标控件的被选中状态属性。 ``` ### By.isBefore -isBefore(by:By):By; +isBefore(by: By): By 指定目标控件位于给出的特征属性控件之前，返回By对象自身。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | -------------- | -| by | By | 是 | 特征控件的属性 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---- | ---- | ---------------- | +| by | By | 是 | 特征控件的属性。 | **返回值：** -| 类型 | 说明 | -| ---- | -------------- | -| By | 返回By对象自身 | +| 类型 | 说明 | +| ---- | ---------------- | +| By | 返回By对象自身。 | **示例：** -``` -let by = BY.isBefore(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之前 +```js +let by = BY.isBefore(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之前。 ``` ### By.isAfter -isAfter(by:By):By; +isAfter(by: By): By 指定目标控件位于给出的特征属性控件之后，返回By对象自身。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | -------------- | -| by | By | 是 | 特征控件的属性 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---- | ---- | ---------------- | +| by | By | 是 | 特征控件的属性。 | **返回值：** -| 类型 | 说明 | -| ---- | -------------- | -| By | 返回By对象自身 | +| 类型 | 说明 | +| ---- | ---------------- | +| By | 返回By对象自身。 | **示例：** -``` -let by = BY.isAfter(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之后 +```js +let by = BY.isAfter(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之后。 ``` ## UiComponent @@ -354,17 +319,15 @@ UiTest中，UiComponent类代表了UI界面上的一个控件，提供控件属 ### UiComponent.click -click():Promise; +click(): Promise\ 控件对象进行点击操作。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **示例：** -``` +```js async function demo() { let driver = UiDriver.create() let button = await driver.findComponent(BY.type('button')) @@ -374,37 +337,33 @@ async function demo() { ### UiComponent.doubleClick -doubleClick():Promise; +doubleClick(): Promise\ 控件对象进行双击操作。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **示例：** -``` +```js async function demo() { let driver = UiDriver.create() let button = await driver.findComponent(BY.type('button')) - await buttont.doubleClick() + await button.doubleClick() } ``` ### UiComponent.longClick -longClick():Promise; +longClick(): Promise\ 控件对象进行长按操作。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **示例：** -``` +```js async function demo() { let driver = UiDriver.create() let button = await driver.findComponent(BY.type('button')) @@ -414,23 +373,21 @@ async function demo() { ### UiComponent.getId -getId():Promise; +getId(): Promise\ 获取控件对象的id值。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **返回值：** -| 类型 | 说明 | -| ---------------- | ------------------------- | -| Promise; | 以Promise形式返回控件id值 | +| 类型 | 说明 | +| ---------------- | ------------------------------- | +| Promise\ | 以Promise形式返回的控件的id值。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() let button = await driver.findComponent(BY.type('button')) @@ -440,23 +397,21 @@ async function demo() { ### UiComponent.getKey -getKey():Promise; +getKey(): Promise\ 获取控件对象的key值。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **返回值：** -| 类型 | 说明 | -| ---------------- | -------------------------- | -| Promise; | 以Promise形式返回控件key值 | +| 类型 | 说明 | +| ---------------- | ------------------------------ | +| Promise\ | 以Promise形式返回控件的key值。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() let button = await driver.findComponent(BY.type('button')) @@ -466,23 +421,21 @@ async function demo() { ### UiComponent.getText -getText():Promise; +getText(): Promise\ 获取控件对象的文本信息。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **返回值：** -| 类型 | 说明 | -| ---------------- | ------------------------------- | -| Promise; | 以Promise形式返回控件的文本信息 | +| 类型 | 说明 | +| ---------------- | --------------------------------- | +| Promise\ | 以Promise形式返回控件的文本信息。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() let button = await driver.findComponent(BY.type('button')) @@ -492,23 +445,21 @@ async function demo() { ### UiComponent.getType -getType():Promise; +getType(): Promise\ 获取控件对象的控件类型。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **返回值：** -| 类型 | 说明 | -| ---------------- | ------------------------------- | -| Promise; | 以Promise形式返回控件对象的类型 | +| 类型 | 说明 | +| ---------------- | ----------------------------- | +| Promise\ | 以Promise形式返回控件的类型。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() let button = await driver.findComponent(BY.type('button')) @@ -518,23 +469,21 @@ async function demo() { ### UiComponent.isClickable -isClickable():Promise; +isClickable(): Promise\ 获取控件对象可点击状态。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **返回值：** -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise; | 以Promise形式返回控件对象可点击状态 | +| 类型 | 说明 | +| -------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回控件对象可点击状态。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() let button = await driver.findComponent(BY.type('button')) @@ -549,23 +498,21 @@ async function demo() { ### UiComponent.isScrollable -isScrollable():Promise; +isScrollable(): Promise\ 获取控件对象可滑动状态。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **返回值：** -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise; | 以Promise形式返回控件对象可滑动状态 | +| 类型 | 说明 | +| -------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回控件对象可滑动状态。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() let scrollBar = await driver.findComponent(BY.scrollable(true)) @@ -581,23 +528,21 @@ async function demo() { ### UiComponent.isEnabled -isEnabled():Promise; +isEnabled(): Promise\ 获取控件使能状态。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **返回值：** -| 类型 | 说明 | -| -------------- | ----------------------------- | -| Promise; | 以Promise形式返回控件使能状态 | +| 类型 | 说明 | +| -------------- | ------------------------------- | +| Promise\ | 以Promise形式返回控件使能状态。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() let button = await driver.findComponent(BY.type('button')) @@ -613,23 +558,21 @@ async function demo() { ### UiComponent.isFocused -isFocused():Promise; +isFocused(): Promise\ 判断控件对象是否获焦。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------------- | -| Promise; | 以Promise形式返回控件对象是否获焦 | +| 类型 | 说明 | +| -------------- | ----------------------------------- | +| Promise\ | 以Promise形式返回控件对象是否获焦。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() let button = await driver.findComponent(BY.type('button')) @@ -644,23 +587,21 @@ async function demo() { ### UiComponent.isSelected -isSelected():Promise; +isSelected(): Promise\ 获取控件对象被选中状态。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **返回值：** -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise; | 以Promise形式返回控件对象被选中状态 | +| 类型 | 说明 | +| -------------- | -------------------- | +| Promise\ | 控件对象被选中的状态 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() let button = await driver.findComponent(BY.type('button')) @@ -675,37 +616,33 @@ async function demo() { ### UiComponent.inputText -inputText(text: string):Promise; +inputText(text: string): Promise\ 向控件中输入文本(适用于文本框控件)。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | ------------------------- | -| text | string | 是 | 用于向控件输入的文本信息, | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------- | +| text | string | 是 | 输入的文本信息。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) - await button.inputText('next page') + let text = await driver.findComponent(BY.text('hello world')) + await text.inputText('123') } ``` ### UiComponent.scrollSearch -scrollSearch(by:By):Promise; - -在控件上滑动查找目标控件(适用于List等控件)。 +scrollSearch(by:By): Promise\ -**需要权限**：NA +在控件上滑动查找目标控件(适用于List等支持滑动的控件)。 **系统能力**：SystemCapability.Test.UiTest @@ -713,20 +650,20 @@ scrollSearch(by:By):Promise; | 参数名 | 类型 | 必填 | 说明 | | ------ | ---- | ---- | -------------------- | -| by | By | 是 | 目标控件的体属性要求 | +| by | By | 是 | 目标控件的属性要求。 | **返回值：** -| 类型 | 说明 | -| --------------------- | ----------------------------------- | -| Promise; | 以Promise形式返回找到的目标控件对象 | +| 类型 | 说明 | +| --------------------- | ------------------------------------- | +| Promise\ | 以Promise形式返回找到的目标控件对象。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() - let scrollBar = await driver.findComponent(BY.scrollable(true)) + let scrollBar = await driver.findComponent(BY.type('Scroll')) let button = await scrollBar.scrollSearch(BY.text('next page')) } ``` @@ -738,23 +675,21 @@ UiDriver类为uitest测试框架的总入口，提供控件匹配/查找，按 ### UiDriver.create -static create():UiDriver; +static create(): UiDriver 静态方法，构造一个UiDriver对象，并返回该对象。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **返回值：** -| 类型 | 说明 | -| ------- | ---------------------- | -| UiDrive | 返回构造的UiDriver对象 | +| 类型 | 说明 | +| ------- | ------------------------ | +| UiDrive | 返回构造的UiDriver对象。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() } @@ -762,23 +697,21 @@ async function demo() { ### UiDriver.delayMs -delayMs(duration:number):Promise; +delayMs(duration: number): Promise\ UiDriver对象在给定的时间内延时。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ---------- | -| duration | number | 是 | 给定的时间 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------ | +| duration | number | 是 | 给定的时间。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() await driver.delayMs(1000) @@ -787,29 +720,27 @@ async function demo() { ### UiDriver.findComponent -findComponent(by:By):Promise; +findComponent(by: By): Promise\ 在UiDriver对象中，根据给出的目标控件属性要求查找目标控件。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | ------------------ | -| by | By | 是 | 目标控件的属性要求 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---- | ---- | -------------------- | +| by | By | 是 | 目标控件的属性要求。 | **返回值：** -| 类型 | 说明 | -| --------------------- | ------------------------------- | -| Promise; | 以Promise形式返回找到的控件对象 | +| 类型 | 说明 | +| --------------------- | --------------------------------- | +| Promise\ | 以Promise形式返回找到的控件对象。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() let button = await driver.findComponent(BY.text('next page')) @@ -818,29 +749,27 @@ async function demo() { ### UiDriver.findComponents -findComponents(by:By):Promise>; +findComponents(by: By): Promise\> 在UiDriver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | ------------------ | -| by | By | 是 | 目标控件的属性要求 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---- | ---- | -------------------- | +| by | By | 是 | 目标控件的属性要求。 | **返回值：** -| 类型 | 说明 | -| ---------------------------- | ------------------------------------- | -| Promise>; | 以Promise形式返回找到的控件对象的列表 | +| 类型 | 说明 | +| ----------------------------- | --------------------------------------- | +| Promise\> | 以Promise形式返回找到的控件对象的列表。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() let buttonList = await driver.findComponents(BY.text('next page')) @@ -849,23 +778,21 @@ async function demo() { ### UiDriver.assertComponentExist -assertComponentExist(by:By):Promise; +assertComponentExist(by: By): Promise\ 断言API，用于断言当前界面存在满足给出的目标控件属性的控件; 如果控件不存在，该API将抛出JS异常，使当前测试用例失败。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | ------------------ | -| by | By | 是 | 目标控件的属性要求 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---- | ---- | -------------------- | +| by | By | 是 | 目标控件的属性要求。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() await driver.assertComponentExist(BY.text('next page')) @@ -874,17 +801,15 @@ async function demo() { ### UiDriver.pressBack -pressBack():Promise; +pressBack(): Promise\ UiDriver对象进行点击BACK键的操作。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **示例：** -``` +```js async function demo() { let driver = UiDriver.create() await driver.pressBack() @@ -893,23 +818,21 @@ async function demo() { ### UiDriver.triggerKey -triggerKey(keyCode:number):Promise; +triggerKey(keyCode: number): Promise\ UiDriver对象采取如下操作：通过key值找到对应键并点击。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | --------- | -| keyCode | number | 是 | 指定key值 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------- | +| keyCode | number | 是 | 指定的key值。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() await driver.triggerKey(123) @@ -918,23 +841,22 @@ async function demo() { ### UiDriver.click -click(x:number,y:number):Promise; +click(x: number, y: number): Promise\ UiDriver对象采取如下操作：在目标坐标点单击。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------------- | ---- | ------------------------------------------- | -| x,y | number,number | 是 | 以(number,number)的形式传入特定点的坐标信息 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------------- | +| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | +| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() await driver.click(100,100) @@ -943,23 +865,22 @@ async function demo() { ### UiDriver.doubleClick -doubleClick(x:number,y:number):Promise; +doubleClick(x: number, y: number): Promise\ UiDriver对象采取如下操作：在目标坐标点双击。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------------- | ---- | ------------------------------------------- | -| x,y | number,number | 是 | 以(number,number)的形式传入特定点的坐标信息 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------------- | +| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | +| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() await driver.doubleClick(100,100) @@ -968,23 +889,22 @@ async function demo() { ### UiDriver.longClick -longClick(x:number,y:number):Promise; +longClick(x: number, y: number): Promise\ UiDriver对象采取如下操作：在目标坐标点长按下鼠标左键。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------------- | ---- | ------------------------------------------- | -| x,y | number,number | 是 | 以(number,number)的形式传入特定点的坐标信息 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------------- | +| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | +| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() await driver.longClick(100,100) @@ -993,24 +913,25 @@ async function demo() { ### UiDriver.swipe -swipe(startx:number,starty:number,endx:number,endy:number):Promise; +swipe(startx: number, starty: number, endx: number, endy: number, speed: number): Promise\ UiDriver对象采取如下操作：从给出的起始坐标点滑向给出的目的坐标点。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------------- | ------------- | ---- | ------------------------------------------- | -| startx,starty | number,number | 是 | 以(number,number)的形式传入起始点的坐标信息 | -| endx,endy | number,number | 是 | 以(number,number)的形式传入目的点的坐标信息 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| startx | number | 是 | 以number的形式传入起始点的横坐标信息。 | +| starty | number | 是 | 以number的形式传入起始点的纵坐标信息。 | +| endx | number | 是 | 以number的形式传入目的点的横坐标信息。 | +| endy | number | 是 | 以number的形式传入目的点的纵坐标信息。 | +| speed | number | 否 | 拖拽的速度。范围200-3000，超出范围设为默认值600。单位：像素点/秒。单位：像素点/秒。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() await driver.swipe(100,100,200,200) @@ -1019,26 +940,42 @@ async function demo() { ### UiDriver.screenCap -screenCap(savePath:string):Promise; +screenCap(savePath: string): Promise\ UiDriver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。 -**需要权限**：NA - **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ------------ | -| savePath | string | 是 | 文件保存路径 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | -------------- | +| savePath | string | 是 | 文件保存路径。 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | -------------------------------------- | +| Promise\ | 截图操作是否成功完成。成功完成为true。 | **示例：** -``` +```js async function demo() { let driver = UiDriver.create() await driver.screenCap('/local/tmp/') } ``` +## MatchPattern + +控件属性支持的匹配模式。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Test.UiTest + +| 名称 | 值 | 说明 | +| ----------- | ---- | -------------- | +| EQUALS | 0 | 等于给定值。 | +| CONTAINS | 1 | 包含给定值。 | +| STARTS_WITH | 2 | 从给定值开始。 | +| ENDS_WITH | 3 | 以给定值结束。 | -- GitLab