diff --git a/en/application-dev/reference/apis/js-apis-inner-application-accessibilityExtensionContext.md b/en/application-dev/reference/apis/js-apis-inner-application-accessibilityExtensionContext.md index 92450992f6d642dc1583f3147827a94622bcc96a..445443209e3ca4a670cfced56f285530144505c4 100644 --- a/en/application-dev/reference/apis/js-apis-inner-application-accessibilityExtensionContext.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-accessibilityExtensionContext.md @@ -1,6 +1,6 @@ # AccessibilityExtensionContext (Accessibility Extension Context) -The **AccessibilityExtensionContext** module, inherited from **ExtensionContext**, provides context for **Accessibility Extension** abilities. +The **AccessibilityExtensionContext** module, inherited from **ExtensionContext**, provides context for **AccessibilityExtensionAbility**. You can use the APIs of this module to configure the concerned information, obtain root information, and inject gestures. @@ -131,7 +131,7 @@ Sets the concerned target bundle. This API uses an asynchronous callback to retu let targetNames = ['com.ohos.xyz']; try { axContext.setTargetBundleName(targetNames, (err, data) => { - if (err) { + if (err && err.code) { console.error('failed to set target bundle names, because ${JSON.stringify(err)}'); return; } @@ -214,7 +214,7 @@ For details about the error codes, see [Accessibility Error Codes](../errorcodes let focusElement; try { axContext.getFocusElement((err, data) => { - if (err) { + if (err && err.code) { console.error('failed to get focus element, because ${JSON.stringify(err)}'); return; } @@ -248,7 +248,7 @@ let focusElement; let isAccessibilityFocus = true; try { axContext.getFocusElement(isAccessibilityFocus, (err, data) => { - if (err) { + if (err && err.code) { console.error('failed to get focus element, because ${JSON.stringify(err)}'); return; } @@ -331,7 +331,7 @@ For details about the error codes, see [Accessibility Error Codes](../errorcodes let rootElement; try { axContext.getWindowRootElement((err, data) => { - if (err) { + if (err && err.code) { console.error('failed to get root element of the window, because ${JSON.stringify(err)}'); return; } @@ -373,7 +373,7 @@ let rootElement; let windowId = 10; try { axContext.getWindowRootElement(windowId, (err, data) => { - if (err) { + if (err && err.code) { console.error('failed to get root element of the window, because ${JSON.stringify(err)}'); return; } @@ -457,7 +457,7 @@ For details about the error codes, see [Accessibility Error Codes](../errorcodes let windows; try { axContext.getWindows((err, data) => { - if (err) { + if (err && err.code) { console.error('failed to get windows, because ${JSON.stringify(err)}'); return; } @@ -499,7 +499,7 @@ let windows; let displayId = 10; try { axContext.getWindows(displayId, (err, data) => { - if (err) { + if (err && err.code) { console.error('failed to get windows, because ${JSON.stringify(err)}'); return; } @@ -594,7 +594,7 @@ try { gesturePath.points.push(gesturePoint); } axContext.injectGesture(gesturePath, (err, data) => { - if (err) { + if (err && err.code) { console.error('failed to inject gesture, because ${JSON.stringify(err)}'); return; } @@ -818,7 +818,7 @@ Performs an action based on the specified action name. This API uses a promise t | Name | Type | Mandatory | Description | | ----------- | ---------------------------------------- | ---- | -------------- | -| actionName | string | Yes | Action name. | +| actionName | string | Yes | Action name. For details, see [Action](./js-apis-accessibility.md#action). | parameters | object | No | Parameter required for performing the target action. | **Return value** @@ -861,7 +861,7 @@ Performs an action based on the specified action name. This API uses an asynchro | Name | Type | Mandatory | Description | | ----------- | ---------------------------------------- | ---- | -------------- | -| actionName | string | Yes | Attribute name. | +| actionName | string | Yes | Action name. For details, see [Action](./js-apis-accessibility.md#action). | callback | AsyncCallback<void> | Yes | Callback used to return the result.| **Error codes** @@ -900,7 +900,7 @@ Performs an action based on the specified action name. This API uses an asynchro | Name | Type | Mandatory | Description | | ----------- | ---------------------------------------- | ---- | -------------- | -| actionName | string | Yes | Action name. | +| actionName | string | Yes | Action name. For details, see [Action](./js-apis-accessibility.md#action).| | parameters | object | Yes | Parameter required for performing the target action. | | callback | AsyncCallback<void> | Yes | Callback used to return the result.| diff --git a/en/application-dev/reference/apis/js-apis-uitest.md b/en/application-dev/reference/apis/js-apis-uitest.md index d738e7b69170bc84f17286594cfd98b3ff908249..d1f1ba4db59b314b345b3f0efc9ec58d6a5fb913 100644 --- a/en/application-dev/reference/apis/js-apis-uitest.md +++ b/en/application-dev/reference/apis/js-apis-uitest.md @@ -1,4 +1,4 @@ -# @ohos.uitest (UiTest) +# @ohos.UiTest The **UiTest** module provides APIs that you can use to simulate UI actions during testing, such as clicks, double-clicks, long-clicks, and swipes. @@ -20,7 +20,7 @@ This module provides the following functions: ## Modules to Import ```js -import {UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix} from '@ohos.uitest'; +import {UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix, UiDirection, MouseButton} from '@ohos.UiTest'; ``` ## MatchPattern @@ -61,8 +61,8 @@ Provides the coordinates of a point. | Name| Type | Readable| Writable| Description | | ---- | ------ | ---- | ---- | ---------------- | -| X | number | Yes | No | X-coordinate of a point.| -| Y | number | Yes | No | Y-coordinate of a point.| +| x | number | Yes | No | X-coordinate of a point.| +| y | number | Yes | No | Y-coordinate of a point.| ## Rect9+ @@ -79,10 +79,10 @@ Provides bounds information of a component. ## WindowMode9+ -**System capability**: SystemCapability.Test.UiTest - Enumerates the window modes. +**System capability**: SystemCapability.Test.UiTest + | Name | Value | Description | | ---------- | ---- | ---------- | | FULLSCREEN | 0 | Full-screen mode.| @@ -92,10 +92,10 @@ Enumerates the window modes. ## DisplayRotation9+ -**System capability**: SystemCapability.Test.UiTest - Describes the display rotation of the device. +**System capability**: SystemCapability.Test.UiTest + | Name | Value | Description | | ------------ | ---- | ---------------------------------------- | | ROTATION_0 | 0 | The device display is not rotated and is in its original vertical orientation. | @@ -116,6 +116,31 @@ Provides the flag attributes of this window. | focused | boolean | Yes | No | Whether the window is in focused state. | | actived | boolean | Yes | No | Whether the window is interacting with the user.| +## UiDirection10+ + +Describes the direction of a UI operation such as fling. + +**System capability**: SystemCapability.Test.UiTest + +| Name | Value | Description | +| ----- | ---- | ------ | +| LEFT | 0 | Leftward.| +| RIGHT | 1 | Rightward.| +| UP | 2 | Upward.| +| DOWN | 3 | Downward.| + +## MouseButton10+ + +Describes the injected simulated mouse button. + +**System capability**: SystemCapability.Test.UiTest + +| Name | Value | Description | +| ------------------- | ---- | ------------ | +| MOUSE_BUTTON_LEFT | 0 | Left button on the mouse. | +| MOUSE_BUTTON_RIGHT | 1 | Right button on the mouse. | +| MOUSE_BUTTON_MIDDLE | 2 | Middle button on the mouse.| + ## On9+ Since API version 9, the UiTest framework provides a wide range of UI component feature description APIs in the **On** class to filter and match components. @@ -420,7 +445,7 @@ let on = ON.checkable(true); // Use the static constructor ON to create an On ob isBefore(on: On): On -Specifies the attributes of the component before which the target component is located. +Specifies that the target component is located before the given attribute component. **System capability**: SystemCapability.Test.UiTest @@ -428,7 +453,7 @@ Specifies the attributes of the component before which the target component is l | Name| Type | Mandatory| Description | | ------ | ---------- | ---- | -------------------- | -| on | [On](#on9) | Yes | Attributes of the component before which the target component is located.| +| on | [On](#on9) | Yes | Information about the attribute component.| **Return value** @@ -439,14 +464,14 @@ Specifies the attributes of the component before which the target component is l **Example** ```js -let on = ON.isBefore(ON.text('123')); // Use the static constructor ON to create an On object and specify the attributes of the component before which the target component is located. +let on = ON.isBefore(ON.text('123')); // Create an On object using the static constructor ON, specifying that the target component is located before the given attribute component. ``` ### isAfter9+ isAfter(on: On): On -Specifies the attributes of the component after which the target component is located. +Specifies that the target component is located after the given attribute component. **System capability**: SystemCapability.Test.UiTest @@ -454,7 +479,7 @@ Specifies the attributes of the component after which the target component is lo | Name| Type | Mandatory| Description | | ------ | ---------- | ---- | -------------------- | -| on | [On](#on9) | Yes | Attributes of the component after which the target component is located.| +| on | [On](#on9) | Yes | Information about the attribute component.| **Return value** @@ -465,7 +490,59 @@ Specifies the attributes of the component after which the target component is lo **Example** ```js -let on = ON.isAfter(ON.text('123')); // Use the static constructor ON to create an On object and specify the attributes of the component after which the target component is located. +let on = ON.isAfter(ON.text('123')); // Create an On object using the static constructor ON, specifying that the target component is located after the given attribute component. +``` + +### within10+ + +within(on: On): On + +Specifies that the target component is located within the given attribute component. + +**System capability**: SystemCapability.Test.UiTest + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ---------- | ---- | -------------------- | +| on | [On](#on9) | Yes | Information about the attribute component.| + +**Return value** + +| Type | Description | +| ---------- | -------------------------------------------------- | +| [On](#on9) | **On** object.| + +**Example** + +```js +let on = ON.within(ON.type('List')); // Create an On object using the static constructor ON, specifying that the target component is located within the given attribute component. +``` + +### inWindow10+ + +inWindow(bundleName: string): On; + +Specifies that the target component is within the given application window. + +**System capability**: SystemCapability.Test.UiTest + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------ | ---- | ---------------- | +| bundleName | string | Yes | Bundle name of the application window.| + +**Return value** + +| Type | Description | +| ---------- | ---------------------------------------------- | +| [On](#on9) | **On** object.| + +**Example** + +```js +let on = ON.inWindow(ON.inWindow('com.uitestScene.acts')); // Create an On object using the static constructor ON, specifying that the target component is within the given application window. ``` ## Component9+ @@ -1816,7 +1893,7 @@ For details about the error codes, see [UiTest Error Codes](../errorcodes/errorc ```js async function demo() { let driver = Driver.create(); - await driver.screenCap('/local/tmp/1.png'); + await driver.screenCap('/data/storage/el2/base/cache/1.png'); } ``` @@ -2078,7 +2155,7 @@ Simulates a fling operation on the screen. | from | [Point](#point9) | Yes | Coordinates of the point where the finger touches the screen. | | to | [Point](#point9) | Yes | Coordinates of the point where the finger leaves the screen. | | stepLen | number | Yes | Fling step length, in pixels. | -| speed | number | Yes | Scroll speed, in pixel/s. The value ranges from 200 to 15000. If the set value is not in the range, the default value 600 is used.| +| speed | number | Yes | Fling speed, in pixel/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value 600 is used.| **Error codes** @@ -2093,7 +2170,7 @@ For details about the error codes, see [UiTest Error Codes](../errorcodes/errorc ```js async function demo() { let driver = Driver.create(); - await driver.fling({X: 500, Y: 480},{X: 450, Y: 480},5,600); + await driver.fling({x: 500, y: 480},{x: 450, y: 480},5,600); } ``` @@ -2132,16 +2209,186 @@ For details about the error codes, see [UiTest Error Codes](../errorcodes/errorc async function demo() { let driver = Driver.create(); 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}); + 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); } ``` +### fling10+ + +fling(direction: UiDirection, speed: number): Promise; + +Simulates a fling operation on the screen, in the specified direction and speed. + +**System capability**: SystemCapability.Test.UiTest + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | ----------------------------- | ---- | ------------------------------------------------------------ | +| direction | [UiDirection](#uidirection10) | Yes | Direction of the fling operation. | +| speed | number | Yes | Fling speed, in pixel/s. The value ranges from 200 to 40000. If the set value is not in the range, the default value 600 is used.| + +**Error codes** + +For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). + +| ID| Error Message | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | + +**Example** + +```js +async function demo() { + let driver = Driver.create(); + await driver.fling(UiDirection.DOWN, 10000); +} +``` + +### screenCapture10+ + +screenCapture(savePath: string, rect?: Rect): Promise; + +Captures the specified area of the current screen and saves the captured screenshot as a PNG image to the specified path. + +**System capability**: SystemCapability.Test.UiTest + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------- | ---- | ---------------------- | +| savePath | string | Yes | File save path. | +| rect | [Rect](#rect9) | No | Area of the screen to capture. The default value is the entire screen.| + +**Return value** + +| Type | Description | +| ----------------- | -------------------------------------- | +| Promise\ | Promise used to return the operation result. The value **true** means that the operation is successful.| + +**Error codes** + +For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). + +| ID| Error Message | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | + +**Example** + +```js +async function demo() { + let driver = Driver.create(); + await driver.screenCapture('/data/storage/el2/base/cache/1.png', {left: 0, top: 0, right: 100, bottom: 100}); +} +``` + +### mouseClick10+ + +mouseClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise; + +Injects a mouse click at the specified coordinates, with the optional key or key combination. For example, if the value of **key1** is **2072**, the **Ctrl** button is pressed with the mouse click. + +**System capability**: SystemCapability.Test.UiTest + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ----------------------------- | ---- | ------------------- | +| p | [Point](#point9) | Yes | Coordinates of the mouse click. | +| btnId | [MouseButton](#mousebutton10) | Yes | Mouse button pressesd. | +| key1 | number | Yes | The first key value.| +| key2 | number | No | The second key value.| + +**Error codes** + +For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). + +| ID| Error Message | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | + +**Example** + +```js +async function demo() { + let driver = Driver.create(); + await driver.mouseClick({x:248, y:194}, MouseButton.MOUSE_BUTTON_LEFT, 2072); +} +``` + +### mouseScroll10+ + +mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number): Promise; + +Injects a mouse scroll action at the specified coordinates, with the optional key or key combination. For example, if the value of **key1** is **2072**, the **Ctrl** button is pressed with mouse scrolling. + +**System capability**: SystemCapability.Test.UiTest + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ---------------- | ---- | --------------------------------------------------- | +| p | [Point](#point9) | Yes | Coordinates of the mouse click. | +| down | boolean | Yes | Whether the scroll wheel slides downward. | +| d | number | Yes | Number of grids by which the scroll wheel slides. Sliding by one grid means a 120-pixel offset of the target point.| +| key1 | number | Yes | The first key value. | +| key2 | number | No | The second key value. | + +**Error codes** + +For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). + +| ID| Error Message | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | + +**Example** + +```js +async function demo() { + let driver = Driver.create(); + await driver.mouseScroll({x:360, y:640}, true, 30, 2072) +} +``` + +### mouseMoveTo10+ + +mouseMoveTo(p: Point): Promise; + +Moves the cursor to the target point. + +**System capability**: SystemCapability.Test.UiTest + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ---------------- | ---- | -------------- | +| p | [Point](#point9) | Yes | Coordinates of the target point.| + +**Error codes** + +For details about the error codes, see [UiTest Error Codes](../errorcodes/errorcode-uitest.md). + +| ID| Error Message | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | + +**Example** + +```js +async function demo() { + let driver = Driver.create(); + await driver.mouseMoveTo({x:100, y:100}) +} +``` + ## PointerMatrix9+ Implements a **PointerMatrix** object that stores coordinates and behaviors of each action of each finger in a multi-touch operation. @@ -2196,12 +2443,12 @@ Sets the coordinates for the action corresponding to the specified finger and st ```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}); + 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}); } ``` @@ -2919,7 +3166,7 @@ let by = BY.selected(true); // Use the static constructor BY to create a By obje isBefore(by: By): By -Specifies the attributes of the component before which the target component is located. +Specifies that the target component is located before the given attribute component. This API is deprecated since API version 9. You are advised to use [isBefore9+](#isbefore9). @@ -2929,7 +3176,7 @@ This API is deprecated since API version 9. You are advised to use [isBefore(deprecated) isAfter(by: By): By -Specifies the attributes of the component after which the target component is located. +Specifies the target component is located after the given attribute component. This API is deprecated since API version 9. You are advised to use [isAfter9+](#isafter9). @@ -2957,7 +3204,7 @@ This API is deprecated since API version 9. You are advised to use [isAfter | Name| Type | Mandatory| Description | | ------ | ------------------- | ---- | ---------------- | -| by | [By](#bydeprecated) | Yes | Attributes of the component before which the target component is located.| +| by | [By](#bydeprecated) | Yes | Information about the attribute component.| **Return value** @@ -2968,7 +3215,7 @@ This API is deprecated since API version 9. You are advised to use [isAfter **Example** ```js -let by = BY.isAfter(BY.text('123')); // Use the static constructor BY to create a By object and specify the attributes of the component after which the target component is located. +let by = BY.isAfter(BY.text('123')); // Use the static constructor BY to create a By object, specifying that the target component is located after the given attribute component. ``` ## UiComponent(deprecated) @@ -3673,6 +3920,6 @@ This API is deprecated since API version 9. You are advised to use [screenCap