[InputMethodExtensionAbility](../reference/apis/js-apis-inputmethod-extension-ability.md), inherited from [ExtensionAbility](extensionability-overview.md), is used for developing input method applications.
@@ -13,7 +13,7 @@ In this document you will learn about the key functions of arkXtest and how to u
arkXtest is part of the OpenHarmony toolkit and provides basic capabilities of writing and running OpenHarmony automated test scripts. In terms of test script writing, arkXtest offers a wide range of APIs, including basic process APIs, assertion APIs, and APIs related to UI operations. In terms of test script running, arkXtest offers such features as identifying, scheduling, and executing test scripts, as well as summarizing test script execution results.
### Principles
### Implementation
arkXtest is divided into two parts: unit test framework and UI test framework.
...
...
@@ -27,28 +27,28 @@ arkXtest is divided into two parts: unit test framework and UI test framework.
- UI Testing Framework
- UI Test Framework
The UI test framework provides [UiTest APIs](../reference/apis/js-apis-uitest.md) for you to call in different test scenarios. The test scripts are executed on top of the unit test framework mentioned above.
The UI test framework provides [UiTest APIs](../reference/apis/js-apis-uitest.md) for you to call in different test scenarios. The UI test scripts are executed on top of the aformentioned unit test framework.
The figure below shows the main functions of the UI test framework.
### Limitations and Constraints
### Constraints
- The features of the UI test framework are available only in OpenHarmony 3.1 and later versions.
- The feature availability of the unit test framework varies by version. For details about the mappings between the features and versions, see [arkXtest](https://gitee.com/openharmony/testfwk_arkxtest/blob/master/README_en.md).
## Environment preparations
## Preparing the Environment
### Environment Requirements
Software for writing test scripts: DevEco Studio 3.0 or later
Software: DevEco Studio 3.0 or later
Hardware for running test scripts: PC connected to a OpenHarmony device, such as the RK3568 development board
Hardware: PC connected to an OpenHarmony device, such as the RK3568 development board
### Setting Up the Environment
...
...
@@ -57,7 +57,7 @@ Hardware for running test scripts: PC connected to a OpenHarmony device, such as
## Creating a Test Script
1. Open DevEco Studio and create a project, where the **ohos** directory is where the test script is located.
1. Open DevEco Studio and create a project, in which the **ohos** directory is where the test script is located.
2. Open the .ets file of the module to be tested in the project directory. Move the cursor to any position in the code, and then right-click and choose **Show Context Actions** > **Create Ohos Test** or press **Alt+Enter** and choose **Create Ohos Test** to create a test class.
## Writing a Unit Test Script
...
...
@@ -95,7 +95,7 @@ export default function abilityTest() {
The unit test script must contain the following basic elements:
1. Import of the dependency package so that the dependent test APIs can be used.
1. Import of the dependencies so that the dependent test APIs can be used.
2. Test code, mainly about the related logic, such as API invoking.
...
...
@@ -105,7 +105,7 @@ The unit test script must contain the following basic elements:
You write a UI test script based on the unit test framework, adding the invoking of APIs provided by the UI test framework to implement the corresponding test logic.
In this example, the UI test script is written based on the preceding unit test script. First, add the dependency package, as shown below:
In this example, the UI test script is written based on the preceding unit test script. First, import the dependency, as shown below:
@@ -180,11 +180,11 @@ The logs added to the test case are displayed after the test case execution, rat
**Possible Causes**
More than one asynchronous interface is called in the test case.<br>In principle, logs in the test case are printed before the test case execution is complete.
More than one asynchronous API is called in the test case.<br>In principle, logs in the test case are printed before the test case execution is complete.
**Solution**
**Solution**
If more than one asynchronous interface is called, you are advised to encapsulate the interface invoking into the promise mode
If more than one asynchronous API is called, you are advised to encapsulate the API invoking into the promise mode.
#### Error "fail to start ability" is reported during test case execution
...
...
@@ -227,7 +227,7 @@ The UI test case fails to be executed. The HiLog file contains the error message
**Possible Causes**
The ArkUI feature is disabled. As a result, the control tree information on the test page is not generated.
The ArkUI feature is disabled. As a result, the component tree information is not generated on the test page.
**Solution**
...
...
@@ -237,33 +237,33 @@ Run the following command, restart the device, and execute the test case again:
hdc shell param set persist.ace.testmode.enabled 1
```
#### The failure log contains "uitest-api dose not allow calling concurrently"
#### The failure log contains "uitest-api does not allow calling concurrently"
**Problem**
The UI test case fails to be executed. The HiLog file contains the error message "uitest-api dose not allow calling concurrently".
The UI test case fails to be executed. The HiLog file contains the error message "uitest-api does not allow calling concurrently".
**Possible Causes**
1. In the test case, the **await** operator is not added to the asynchronous interface provided by the UI test framework.
1. In the test case, the **await** operator is not added to the asynchronous API provided by the UI test framework.
2. The UI test case is executed in multiple processes. As a result, multiple UI test processes are started. The framework does not support multi-process invoking.
**Solution**
1. Check the case implementation and add the **await** operator to the asynchronous interface invoking.
1. Check the case implementation and add the **await** operator to the asynchronous API.
2. Do not execute UI test cases in multiple processes.
#### The failure log contains "dose not exist on current UI! Check if the UI has changed after you got the widget object"
#### The failure log contains "does not exist on current UI! Check if the UI has changed after you got the widget object"
**Problem**
The UI test case fails to be executed. The HiLog file contains the error message "dose not exist on current UI! Check if the UI has changed after you got the widget object".
The UI test case fails to be executed. The HiLog file contains the error message "does not exist on current UI! Check if the UI has changed after you got the widget object."
**Possible Causes**
After the target component is found in the code of the test case, the device UI changes. As a result, the found component is lost and the emulation operation cannot be performed.
After the target component is found in the code of the test case, the device UI changes, resulting in loss of the found component and inability to perform emulation.
To develop an application based on the [stage model](application-configuration-file-overview-stage.md), it will be helpful if you have a basic understanding of the structure of the application package created after the application is built and packaged, as well as the related basic concepts.
- In development, an application contains one or more modules. You can [create modules](https://developer.harmonyos.com/en/docs/documentation/doc-guides-V3/ohos-adding-deleting-module-0000001218760594-V3) in the application project in [DevEco Studio](https://developer.harmonyos.com/en/develop/deveco-studio/). As a basic functional unit of an OpenHarmony application/service, a module contains source code, resource files, third-party libraries, and application/service configuration files, and can be built and run independently. Modules can be classified as Ability or Library. A module of the Ability type is built into a Harmony Ability Package (HAP) file, and a module of the Library type is built into a [Harmony Archive (HAR)](har-package.md) file or a [Harmony Shared Package (HSP)](shared-guide.md).
- In development, an application contains one or more modules. You can [create modules](https://developer.harmonyos.com/en/docs/documentation/doc-guides-V3/add_new_module-0000001053223741-V3) in the application project in [DevEco Studio](https://developer.harmonyos.com/en/develop/deveco-studio/). As a basic functional unit of an OpenHarmony application/service, a module contains source code, resource files, third-party libraries, and application/service configuration files, and can be built and run independently. Modules can be classified as Ability or Library. A module of the Ability type is built into a Harmony Ability Package (HAP) file, and a module of the Library type is built into a [Harmony Archive (HAR)](har-package.md) file or a [Harmony Shared Package (HSP)](shared-guide.md).
A module can contain one or more [UIAbility](../application-models/uiability-overview.md) components, as shown in the figure below.
**Figure 1** Relationship between modules and UIAbility components
The $$ operator provides a TS variable by-reference to a built-in component so that the variable value and the internal state of that component are kept in sync.
What the internal state is depends on the component. For example, for the [bindPopup](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/arkui-ts/ts-universal-attributes-popup.md) attribute method, it is the **show** parameter.
What the internal state is depends on the component. For example, for the [bindPopup](../reference/arkui-ts/ts-universal-attributes-popup.md) attribute method, it is the **show** parameter.
## Rules of Use
- $$ supports variables of simple types and variables decorated by **\@State**, **\@Link**, or **\@Prop**.
- Currently, $$ supports only the **show** parameter of the [bindPopup](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/arkui-ts/ts-universal-attributes-popup.md) attribute method, the **checked** attribute of the [\<Radio>](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/arkui-ts/ts-basic-components-radio.md) component, and the **refreshing** parameter of the [\<Refresh>](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/arkui-ts/ts-container-refresh.md) component.
- Currently, $$ supports only the **show** parameter of the [bindPopup](../reference/arkui-ts/ts-universal-attributes-popup.md) attribute method, the **checked** attribute of the [\<Radio>](../reference/arkui-ts/ts-basic-components-radio.md) component, and the **refreshing** parameter of the [\<Refresh>](../reference/arkui-ts/ts-container-refresh.md) component.
- When the variable bound to $$ changes, the UI is re-rendered synchronously.
## Example
This example uses the **show** parameter of the [bindPopup](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/arkui-ts/ts-universal-attributes-popup.md) attribute method.
This example uses the **show** parameter of the [bindPopup](../reference/arkui-ts/ts-universal-attributes-popup.md) attribute method.
Implements a **PasteData** object. Paste data contains one or more data records ([PasteDataRecord](#pastedatarecord7)) and property description objects ([PasteDataProperty](#pastedataproperty7)).
Before calling any **PasteData** API, you must obtain a **PasteData** object.
Before calling any API in **PasteData**, you must use **[createData()](#pasteboardcreatedata9)** or **[getData()](#getdata9)** to create a **PasteData** object.
@@ -63,7 +63,6 @@ Provides the device information.
| screenDensity<sup>4+</sup> | number | Screen density.|
| screenShape<sup>4+</sup> | string | Screen shape. The options are as follows:<br>- **rect**: rectangular screen<br>- **circle**: round screen|
| apiVersion<sup>4+</sup> | number | API version.|
| releaseType<sup>4+</sup> | string | Release type. The value includes both the release type and the API version, for example, Beta1.<br>Available release types are as follows:<br>- **Canary**: Releases of this type are compatible with each other under the same API version, but not with those of the **beta** and **release** type.<br>- **Beta**: Releases of this type are compatible with each other under the same API version, but not with those of the **release** type.<br>- **Release**: Releases of this type are compatible with the latest five API versions. |
| uri | string | Yes | URI of the target page, in either of the following formats:<br>1. Absolute path, which is provided by the **pages** list in the **config.json** file. Example:<br>- pages/index/index<br> - pages/detail/detail<br>2. Specific path. If the URI is a slash (/), the home page is displayed.|
| params | object | No | Data that needs to be passed to the target page during redirection. The target page can use **router.getParams()** to obtain the passed parameters, for example, **this.keyValue** (**keyValue** is the value of a key in **params**). In the web-like paradigm, these parameters can be directly used on the target page. If the field specified by **key** already exists on the target page, the passed value of the key will be displayed.|
| uri<sup>7+</sup> | string | Yes | URI of the target page, in either of the following formats:<br>1. Absolute path, which is provided by the **pages** list in the **config.json** file. Example:<br>- pages/index/index<br> - pages/detail/detail<br>2. Specific path. If the URI is a slash (/), the home page is displayed.|
| params<sup>7+</sup> | object | No | Data that needs to be passed to the target page during redirection. The target page can use **router.getParams()** to obtain the passed parameters, for example, **this.keyValue** (**keyValue** is the value of a key in **params**). In the web-like paradigm, these parameters can be directly used on the target page. If the field specified by **key** already exists on the target page, the passed value of the key will be displayed.|
## BackRouterOptions
...
...
@@ -355,8 +355,8 @@ Defines the parameters for routing back.
| uri | string | No | URI of the page to return to. If the specified page does not exist in the page stack, the application does not respond. If this parameter is not set, the application returns to the previous page.<br>**System capability**: SystemCapability.ArkUI.ArkUI.Full|
| params | object | No | Data that needs to be passed to the target page during redirection.<br>**System capability**: SystemCapability.ArkUI.ArkUI.Lite|
| uri<sup>7+</sup> | string | No | URI of the page to return to. If the specified page does not exist in the page stack, the application does not respond. If this parameter is not set, the application returns to the previous page.<br>**System capability**: SystemCapability.ArkUI.ArkUI.Full|
| params<sup>7+</sup> | object | No | Data that needs to be passed to the target page during redirection.<br>**System capability**: SystemCapability.ArkUI.ArkUI.Lite|
@@ -18,9 +18,9 @@ Sets a timer for the system to call a function after the timer goes off.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| handler | Function \| string | Yes| Function to be called after the timer goes off.|
| handler | Function \| string | Yes| Function to be called after the timer goes off. If the type is string, error information is printed and no other processing is performed.|
| delay | number | No| Number of milliseconds delayed before the execution. If this parameter is left empty, the default value **0** is used, which means that the execution starts immediately or as soon as possible.|
| ...arguments | Array<any> | No| Additional parameters to pass to the handler after the timer goes off.|
| ...arguments | any[] | No| Additional parameters to pass to the handler after the timer goes off.|
**Return value**
...
...
@@ -31,19 +31,15 @@ Sets a timer for the system to call a function after the timer goes off.
**Example**
```js
exportdefault{
setTimeOut(){
vartimeoutID=setTimeout(function(){
console.log('delay 1s');
},1000);
}
}
setTimeout(function(){
console.log('delay 1s');
},1000);
```
## clearTimeout
clearTimeout(timeoutID: number): void
clearTimeout(timeoutID?: number): void
Cancels the timer created via **setTimeout()**.
...
...
@@ -53,19 +49,15 @@ Cancels the timer created via **setTimeout()**.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| timeoutID | number | Yes| ID of the timer to cancel, which is returned by **setTimeout()**|
| timeoutID | number | No| ID of the timer to cancel, which is returned by **setTimeout()** If this parameter is omitted, no timer is canceled.|
**Example**
```js
exportdefault{
clearTimeOut(){
vartimeoutID=setTimeout(function(){
console.log('do after 1s delay.');
},1000);
clearTimeout(timeoutID);
}
}
```js
lettimeoutID=setTimeout(function(){
console.log('do after 1s delay.');
},1000);
clearTimeout(timeoutID);
```
...
...
@@ -81,32 +73,28 @@ Sets a repeating timer for the system to repeatedly call a function at a fixed i
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| handler | Function \| string | Yes| Function to be called repeatedly.|
| handler | Function \| string | Yes| Function to be called repeatedly. If the type is string, error information is printed and no other processing is performed.|
| delay | number | Yes| Number of milliseconds delayed before the execution.|
| ...arguments | Array<any> | No| Additional parameters to pass to the handler after the timer goes off.|
| ...arguments | any[] | No| Additional parameters to pass to the handler after the timer goes off.|
**Return value**
| Type| Description|
| -------- | -------- |
| number | ID of the repeating timer.|
| number | Timer ID.|
**Example**
```js
exportdefault{
setInterval(){
varintervalID=setInterval(function(){
console.log('do very 1s.');
},1000);
}
}
setInterval(function(){
console.log('do every 1s.');
},1000);
```
## clearInterval
clearInterval(intervalID: number): void
clearInterval(intervalID?: number): void
Cancels the repeating timer set via **setInterval()**.
...
...
@@ -116,17 +104,13 @@ Cancels the repeating timer set via **setInterval()**.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| intervalID | number | Yes| ID of the repeating timer to cancel, which is returned by **setInterval()**.|
| intervalID | number | No| ID of the repeating timer to cancel, which is returned by **setInterval()**. If this parameter is omitted, no timer is canceled.|
ArkUI is a UI development framework for building OpenHarmony applications. It provides effortlessly natural UI syntax and UI development infrastructure including UI components, animation mechanisms, and event interaction, to meet the visualized GUI development requirements of application developers.
## Basic Concepts
ArkUI provides a comprehensive infrastructure for UI development of OpenHarmony applications, including simple UI syntax, a diverse array of UI features (components, layouts, animations, and interaction events), and a powerful previewer.
-**Component**: the smallest unit for UI building and display. You build a UI that meets your needs through flexible combinations of components.
-**Page**: the smallest unit for ArkUI application scheduling. You can design multiple pages for your application, manage their files on a per-page basis, and schedule page redirection through [page routing](../reference/apis/js-apis-router.md) APIs, so as to implement decoupling of application functions.
## Basic Concepts
## Key Features
-**UI**: user interface. You can design multiple pages for your application, manage their files on a per-page basis, and schedule page redirection through [routing](arkts-routing.md) APIs, so as to implement decoupling of application functions.
-**UI components**: ArkUI comes with a diverse array of built-in polymorphic components, including basic components (such as text, image, and button), container components with one or more child components, drawing components allowing for customization, and media components that provide video playback capabilities. By being polymorphic, a component provides variant forms to adapt to different types of devices and platforms.
-**Component**: the smallest unit for UI building and display, for example, a list, grid, button, radio button, progress indicator, and text. You build a UI that meets your needs through flexible combinations of components.
-**Flexible layouts**: Creating a responsive UI in ArkUI is easy, with the carefully-designed layout approaches: Besides the basic linear and flexible layouts, you also have access to the advanced list, grid, and column grid layouts as well as the atomic layouts that auto-adapt to screen resolutions.
-**Animation**: Apart from animations embedded in components, ArkUI offers additional animation features: attribute animation, transition animation, and custom animation.
## Two Development Paradigms
-**Drawing**: ArkUI offers advanced drawing capabilities that allow you to draw custom shapes with a range of editors, from images to fill colors and texts.
ArkUI comes with two development paradigms: [ArkTS-based declarative development paradigm](arkts-ui-development-overview.md)(declarative development paradigm for short) and [JS-compatible web-like development paradigm](../ui/ui-js-overview.md)(web-like development paradigm for short). You can choose whichever development paradigm that aligns with your practice.
-**Interaction**: ArkUI allows users to interact with your application UI properly, regardless of the system platform and input device. By default, the UI accepts input from touch gestures, remote controls, keyboards, and mouse devices, with support for event callbacks where you can define interaction logic of your own.
-**Declarative development paradigm**: uses [ArkTS](../quick-start/arkts-get-started.md) – a superset of TypeScript with declarative UI syntax, providing UI drawing capabilities from three dimensions: component, animation, and state management.
-**Platform API channel**: ArkUI provides an API extension mechanism through which platform capabilities are encapsulated to produce JavaScript (JS) APIs in a unified style.
-**Web-like development paradigm**: uses the classical three-stage programming model, in which OpenHarmony Markup Language (HML) is used for building layouts, CSS for defining styles, and JS for adding processing logic. This development paradigm has a low learning curve for frontend web developers, allowing them to quickly transform existing web applications into ArkUI applications.
-**Two development paradigms**: ArkUI comes with two development paradigms: [ArkTS-based declarative development paradigm](./ui-ts-overview.md)(declarative development paradigm for short) and [JS-compatible web-like development paradigm](./ui-js-overview.md)(web-like development paradigm for short). You can choose whichever development paradigm that aligns with your practice.
The declarative development paradigm is a better choice for building new application UIs for the following reasons:
| Development Paradigm | Description | Applicable To | Target Audience |
| Declarative development paradigm | Uses [ArkTS](../quick-start/arkts-get-started.md) – a superset of TypeScript with declarative UI syntax, providing UI drawing capabilities from three dimensions: component, animation, and status management. The programming mode used is closer to natural semantics. You can intuitively describe the UI without caring about how the framework implements UI drawing and rendering, leading to simplified and efficient development.| Applications involving technological sophistication and teamwork| Mobile application and system application developers|
| Web-like development paradigm| Uses the classical three-stage programming model, in which OpenHarmony Markup Language (HML) is used for building layouts, CSS for defining styles, and JS for adding processing logic. UI components are associated with data through one-way data-binding. This means that when data changes, the UI automatically refreshes with the new data. This development paradigm has a low learning curve for frontend web developers, allowing them to quickly transform existing web applications into ArkUI applications.| Small- and medium-sized applications and service widgets with simple UIs | Frontend web developers |
-**Higher development efficiency**: In the declarative development paradigm, the programming mode used is closer to natural semantics. You can intuitively describe the UI without caring about how the framework implements UI drawing and rendering, leading to simplified and efficient development.
## Framework Structure
-**Higher application performance**: As shown below, the two development paradigms share the UI backend engine and language runtime. However, the declarative development paradigm does not require the JS framework for managing the page DOM. As such, it has more streamlined rendering and update links and less memory usage.
-**Future proof**: The declarative development paradigm will continue to develop as the preferred development paradigm in OpenHarmony, providing increasingly more diverse and powerful capabilities.
As shown above, the two development paradigms share the UI backend engine and language runtime. The UI backend engine implements the six basic capabilities of ArkUI. The declarative development paradigm does not require the JS Framework for managing the page DOM. As such, it has more streamlined rendering and update links and less memory usage. This makes the declarative development paradigm a better choice for building application UIs.
**Figure 1** ArkUI framework
## Relationship Between UI and Ability Framework
OpenHarmony provides two application models: FA model and stage model. The table below describes the relationship between these two models and the two development paradigms of ArkUI.
**FA Model**
## Development Paradigm Support by Application Type
| Application | Web-like development paradigm| UI development: HML, CSS, and JS<br>Service entries: files with fixed file names, which are **app.ets** (Page ability), **service.ts** (Service ability), and **data.ts** (Data ability)<br>Service logic: JS and TS|
| | Declarative development paradigm | UI development: ArkTS<br>Service entries: files with fixed file names, which are **app.ets** (Page ability), **service.ts** (Service ability), and **data.ts** (Data ability)<br>Service logic: JS and TS|
| Service widget| Web-like development paradigm| UI development: HML, CSS, and JSON (action)<br>Service entry: **form.ts**<br>Service logic: JS and TS|
| | Declarative development paradigm | Not supported currently |
The support for development paradigms varies according to the OpenHarmony [application model](../application-models/application-model-composition.md) and page form. For details, see the following table.
| Application | Web-like development paradigm| Not supported currently |
| | Declarative development paradigm | UI development: ArkTS<br>Service entries: derived from **ohos.application.Ability**/**ExtensionAbility**<br>Service logic: TS|
| Service widget| Web-like development paradigm| UI development: HML, CSS, and JSON (action)<br>Service entries: derived from **FormExtensionAbility**<br>Service logic: TS|
| | Declarative development paradigm | Not supported currently |
| Application Model | Page Form | Supported Development Paradigm |
