Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
提交 d5332ef7 编写于 作者: Z zengyawen
浏览文件
操作

Merge branch 'master' of https://gitee.com/zengyawen/docs

上级 576332ee 6479ea84
隐藏空白更改
内联 并排
Showing with 7123 addition and 2138 deletion
en/application-dev/reference/apis/js-apis-contact.md
浏览文件 @ d5332ef7
......@@ -22,6 +22,7 @@ Adds a contact. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ------------------------------ |
| contact | [Contact](#contact) | Yes | Contact information. |
......@@ -54,11 +55,13 @@ Adds a contact. This API uses a promise to return the result.
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------- | ---- | ------------ |
| contact | [Contact](#contact) | Yes | Contact information.|
**Return Value**
| Type | Description |
| --------------------- | ------------------------------------------- |
| Promise<number> | Promise used to return the contact ID.|
......@@ -89,6 +92,7 @@ Deletes a contact based on the specified contact key. This API uses an asynchron
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ------------------------------------ |
| key | string | Yes | Contact key. Each contact corresponds to one key.|
......@@ -118,11 +122,13 @@ Deletes a contact based on the specified contact key. This API uses a promise to
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------------------------- |
| key | string | Yes | Contact key. Each contact corresponds to one key.|
**Return Value**
| Type | Description |
| ------------------- | --------------------------------------------- |
| Promise<void> | Promise used to return the result.|
......@@ -150,6 +156,7 @@ Updates a contact based on the specified contact information. This API uses an a
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ------------------------------------ |
| contact | [Contact](#contact) | Yes | Contact information. |
......@@ -182,6 +189,7 @@ Updates a contact based on the specified contact information and attributes. Thi
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------- | ---- | ------------------------------------ |
| contact | [Contact](#contact) | Yes | Contact information. |
......@@ -217,12 +225,14 @@ Updates a contact based on the specified contact information and attributes. Thi
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | --------------------------------------- | ---- | ------------------ |
| contact | [Contact](#contact) | Yes | Contact information. |
| attrs | [ContactAttributes](#contactattributes) | No | List of contact attributes.|
**Return Value**
| Type | Description |
| ------------------- | ------------------------------------------------- |
| Promise<void> | Promise used to return the result.|
......@@ -255,6 +265,7 @@ Checks whether the ID of this contact is in the local address book. This API use
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------- | ---- | ------------------------------------------------------------ |
| id | number | Yes | Contact ID. Each contact corresponds to one ID. |
......@@ -284,11 +295,13 @@ Checks whether the ID of this contact is in the local address book. This API use
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------------------------------------------ |
| id | number | Yes | Contact ID. Each contact corresponds to one ID.|
**Return Value**
| Type | Description |
| ---------------------- | ------------------------------------------------------------ |
| Promise<boolean> | Promise used to return the result. The value **true** indicates that the contact ID is in the local address book, and the value **false** indicates the opposite.|
......@@ -316,6 +329,7 @@ Checks whether a contact is included in my card. This API uses an asynchronous c
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------- | ---- | ------------------------------------------------------------ |
| id | number | Yes | Contact ID. |
......@@ -345,11 +359,13 @@ Checks whether a contact is included in my card. This API uses a promise to retu
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------- |
| id | number | Yes | Contact ID.|
**Return Value**
| Type | Description |
| ---------------------- | ------------------------------------------------------------ |
| Promise<boolean> | Promise used to return the result. The value **true** indicates that the contact is included in my card, and the value **false** indicates the opposite.|
......@@ -377,6 +393,7 @@ Queries my card. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------------------- | ---- | ------------------------------ |
| callback | AsyncCallback<[Contact](#contact)> | Yes | Callback used to return the result.|
......@@ -405,6 +422,7 @@ Queries my card based on the specified contact attributes. This API uses an asyn
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------------------- | ---- | ------------------------------ |
| attrs | [ContactAttributes](#contactattributes) | Yes | List of contact attributes. |
......@@ -436,11 +454,13 @@ Queries my card based on the specified contact attributes. This API uses a promi
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | --------------------------------------- | ---- | ------------------ |
| attrs | [ContactAttributes](#contactattributes) | No | List of contact attributes.|
**Return Value**
| Type | Description |
| ---------------------------------- | ------------------------------------------- |
| Promise<[Contact](#contact)> | Promise used to return the result.|
......@@ -470,6 +490,7 @@ Selects a contact. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | ------------------------------------ |
| callback | AsyncCallback<Array<[Contact](#contact)>> | Yes | Callback used to return the result.|
......@@ -498,6 +519,7 @@ Selects a contact. This API uses a promise to return the result.
**System capability**: SystemCapability.Applications.ContactsData
**Return Value**
| Type | Description |
| ----------------------------------------------- | ------------------------------------------------- |
| Promise<Array<[Contact](#contact)>> | Promise used to return the result.|
......@@ -525,6 +547,7 @@ Queries a contact based on the specified key. This API uses an asynchronous call
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------------------- | ---- | -------------------------------------- |
| key | string | Yes | Contact key. Each contact corresponds to one key.|
......@@ -554,6 +577,7 @@ Queries contacts based on the specified key and application. This API uses an as
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------------------- | ---- | -------------------------------------- |
| key | string | Yes | Contact key. Each contact corresponds to one key.|
......@@ -588,6 +612,7 @@ Queries contacts based on the specified key and attributes. This API uses an asy
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------------------- | ---- | -------------------------------------- |
| key | string | Yes | Contact key. Each contact corresponds to one key.|
......@@ -620,6 +645,7 @@ Queries contacts based on the specified key, application, and attributes. This A
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------------------- | ---- | -------------------------------------- |
| key | string | Yes | Contact key. Each contact corresponds to one key.|
......@@ -658,6 +684,7 @@ Queries contacts based on the specified key, application, and attributes. This A
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | --------------------------------------- | ---- | -------------------------------------- |
| key | string | Yes | Contact key. Each contact corresponds to one key.|
......@@ -665,6 +692,7 @@ Queries contacts based on the specified key, application, and attributes. This A
| attrs | [ContactAttributes](#contactattributes) | No | List of contact attributes. |
**Return Value**
| Type | Description |
| ---------------------------------- | ----------------------------------------------- |
| Promise<[Contact](#contact)> | Promise used to return the result.|
......@@ -699,6 +727,7 @@ Queries all contacts. This API uses an asynchronous callback to return the resul
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| callback | AsyncCallback<Array<[Contact](#contact)>> | Yes | Callback used to return the result.|
......@@ -727,6 +756,7 @@ Queries all contacts based on the specified application. This API uses an asynch
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| holder | [Holder](#holder) | Yes | Application that creates the contacts. |
......@@ -760,6 +790,7 @@ Queries all contacts based on the specified attributes. This API uses an asynchr
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| attrs | [ContactAttributes](#contactattributes) | Yes | List of contact attributes. |
......@@ -791,6 +822,7 @@ Queries all contacts based on the specified application and attributes. This API
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| holder | [Holder](#holder) | Yes | Application that creates the contacts. |
......@@ -827,12 +859,14 @@ Queries all contacts based on the specified application and attributes. This API
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | --------------------------------------- | ---- | ---------------------- |
| holder | [Holder](#holder) | No | Application that creates the contacts.|
| attrs | [ContactAttributes](#contactattributes) | No | List of contact attributes. |
**Return Value**
| Type | Description |
| ----------------------------------------------- | --------------------------------------------------- |
| Promise<Array<[Contact](#contact)>> | Promise used to return the result.|
......@@ -866,6 +900,7 @@ Queries contacts based on the specified phone number. This API uses an asynchron
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| phoneNumber | string | Yes | Phone number of the contacts. |
......@@ -895,6 +930,7 @@ Queries contacts based on the specified phone number and application. This API u
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| phoneNumber | string | Yes | Phone number of the contacts. |
......@@ -929,6 +965,7 @@ Queries contacts based on the specified phone number and attributes. This API us
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| phoneNumber | string | Yes | Phone number of the contacts. |
......@@ -961,6 +998,7 @@ Queries contacts based on the specified phone number, application, and attribute
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| phoneNumber | string | Yes | Phone number of the contacts. |
......@@ -998,6 +1036,7 @@ Queries contacts based on the specified phone number, application, and attribute
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | --------------------------------------- | ---- | ---------------------- |
| phoneNumber | string | Yes | Phone number of the contacts. |
......@@ -1005,6 +1044,7 @@ Queries contacts based on the specified phone number, application, and attribute
| attrs | [ContactAttributes](#contactattributes) | No | List of contact attributes. |
**Return Value**
| Type | Description |
| ----------------------------------------------- | --------------------------------------------------- |
| Promise<Array<[Contact](#contact)>> | Promise used to return the result.|
......@@ -1038,6 +1078,7 @@ Queries contacts based on the specified email address. This API uses an asynchro
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| email | string | Yes | Email address of the contact. |
......@@ -1067,6 +1108,7 @@ Queries contacts based on the specified email address and application. This API
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| email | string | Yes | Email address of the contact. |
......@@ -1101,6 +1143,7 @@ Queries contacts based on the specified email address and attributes. This API u
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | ------------------------------------ |
| email | string | Yes | Email address of the contact. |
......@@ -1133,6 +1176,7 @@ Queries contacts based on the specified email address, application, and attribut
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | ------------------------------------ |
| email | string | Yes | Email address of the contact. |
......@@ -1170,6 +1214,7 @@ Queries contacts based on the specified email address, application, and attribut
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | --------------------------------------- | ---- | ---------------------- |
| email | string | Yes | Email address of the contact. |
......@@ -1177,6 +1222,7 @@ Queries contacts based on the specified email address, application, and attribut
| attrs | [ContactAttributes](#contactattributes) | No | List of contact attributes. |
**Return Value**
| Type | Description |
| ----------------------------------------------- | --------------------------------------------------- |
| Promise<Array<[Contact](#contact)>> | Promise used to return the result.|
......@@ -1210,6 +1256,7 @@ Queries all groups of this contact. This API uses an asynchronous callback to re
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------- | ---- | ------------------------------------ |
| callback | AsyncCallback<Array<[Group](#group)>> | Yes | Callback used to return the result.|
......@@ -1238,6 +1285,7 @@ Queries all groups of this contact based on the specified application. This API
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------- | ---- | ------------------------------------ |
| holder | Holder | Yes | Application that creates the contacts. |
......@@ -1271,11 +1319,13 @@ Queries all groups of this contact based on the specified application. This API
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ----------------- | ---- | ---------------------- |
| holder | [Holder](#holder) | No | Application that creates the contacts.|
**Return Value**
| Type | Description |
| ------------------------------------------- | ------------------------------------------------- |
| Promise<Array<[Group](#group)>> | Promise used to return the result.|
......@@ -1307,6 +1357,7 @@ Queries all applications that have created contacts. This API uses an asynchrono
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------------- | ---- | ---------------------------------------------------- |
| callback | AsyncCallback<Array<[Holder](#holder)>> | Yes | Callback used to return the result.|
......@@ -1335,6 +1386,7 @@ Queries all applications that have created contacts. This API uses a promise to
**System capability**: SystemCapability.Applications.ContactsData
**Return Value**
| Type | Description |
| --------------------------------------------- | ------------------------------------------------------------ |
| Promise<Array<[Holder](#holder)>> | Promise used to return the result.|
......@@ -1362,6 +1414,7 @@ Queries the key of a contact based on the specified contact ID. This API uses an
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | --------------------------------------- |
| id | number | Yes | Contact ID. |
......@@ -1391,6 +1444,7 @@ Queries the key of a contact based on the specified contact ID and application.
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | --------------------------------------- |
| id | number | Yes | Contact ID. |
......@@ -1425,12 +1479,14 @@ Queries the key of a contact based on the specified contact ID and application.
**System capability**: SystemCapability.Applications.ContactsData
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ----------------- | ---- | ---------------------- |
| id | number | Yes | Contact ID. |
| holder | [Holder](#holder) | No | Application that creates the contacts.|
**Return Value**
| Type | Description |
| --------------------- | ---------------------------------------------------- |
| Promise<string> | Promise used to return the result.|
......
en/application-dev/reference/apis/js-apis-hidebug.md
浏览文件 @ d5332ef7
......@@ -30,9 +30,10 @@ This API is defined but not implemented in OpenHarmony 3.1 Release.
**Example**
```js
let nativeHeapSize = hidebug.getNativeHeapSize();
```
```js
let nativeHeapSize = hidebug.getNativeHeapSize();
```
## hidebug.getNativeHeapAllocatedSize
......@@ -45,17 +46,18 @@ This API is defined but not implemented in OpenHarmony 3.1 Release.
**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug
**Return value**
| Type | Description |
| ------ | --------------------------------- |
| bigint | Size of the allocated native heap memory, in kB.|
**Example**
```js
let nativeHeapAllocatedSize = hidebug.getNativeHeapAllocatedSize();
```
```js
let nativeHeapAllocatedSize = hidebug.getNativeHeapAllocatedSize();
```
## hidebug.getNativeHeapFreeSize
......@@ -68,17 +70,18 @@ This API is defined but not implemented in OpenHarmony 3.1 Release.
**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug
**Return value**
| Type | Description |
| ------ | ------------------------------- |
| bigint | Size of the free native heap memory, in kB.|
**Example**
```js
let nativeHeapFreeSize = hidebug.getNativeHeapFreeSize();
```
```js
let nativeHeapFreeSize = hidebug.getNativeHeapFreeSize();
```
## hidebug.getPss
......@@ -89,17 +92,18 @@ Obtains the PSS of this process.
**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug
**Return value**
| Type | Description |
| ------ | ------------------------- |
| bigint | PSS of the process, in kB.|
**Example**
```js
let pss = hidebug.getPss();
```
```js
let pss = hidebug.getPss();
```
## hidebug.getSharedDirty
......@@ -110,17 +114,18 @@ Obtains the size of the shared dirty memory of this process.
**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug
**Return value**
| Type | Description |
| ------ | -------------------------- |
| bigint | Size of the shared dirty memory of the process, in kB.|
**Example**
```js
let sharedDirty = hidebug.getSharedDirty();
```
```js
let sharedDirty = hidebug.getSharedDirty();
```
## hidebug.getPrivateDirty<sup>9+<sup>
......@@ -130,8 +135,8 @@ Obtains the size of the private dirty memory of this process.
**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug
**Return value**
| Type | Description |
| ------ | -------------------------- |
| bigint | Size of the private dirty memory of the process, in kB.|
......@@ -152,17 +157,18 @@ For example, if the CPU usage is **50%**, **0.5** is returned.
**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug
**Return value**
| Type | Description |
| ------ | -------------------------- |
| number | CPU usage of the process.|
**Example**
```js
let cpuUsage = hidebug.getCpuUsage();
```
```js
let cpuUsage = hidebug.getCpuUsage();
```
## hidebug.startProfiling
......@@ -189,7 +195,6 @@ hidebug.stopProfiling();
```
## hidebug.stopProfiling
stopProfiling() : void
......@@ -245,6 +250,7 @@ This is a system API and cannot be called by third-party applications.
| serviceid | number | Yes | ID of the system service. |
**Return value**
| Type | Description |
| ------ | -------------------------- |
| string | Absolute path of the file that contains the service information to dump. |
......
en/application-dev/reference/apis/js-apis-net-connection.md
浏览文件 @ d5332ef7
......@@ -47,7 +47,7 @@ Obtains the default active data network. This API uses a promise to return the r
**System capability**: SystemCapability.Communication.NetManager.Core
**Return Value**
**Return value**
| Type | Description |
| --------------------------------- | ------------------------------------- |
......@@ -92,7 +92,7 @@ Checks whether the default data network is activated. This API uses a promise to
**System capability**: SystemCapability.Communication.NetManager.Core
**Return Value**
**Return value**
| Type | Description |
| ----------------- | ----------------------------------------------- |
......@@ -117,6 +117,7 @@ Obtains the list of all active data networks. This API uses an asynchronous call
**System capability**: SystemCapability.Communication.NetManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;Array&lt;[NetHandle](#nethandle)&gt;&gt; | Yes| Callback used to return the result.|
......@@ -141,7 +142,8 @@ Obtains the list of all active data networks. This API uses a promise to return
**System capability**: SystemCapability.Communication.NetManager.Core
**Return Value**
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;Array&lt;[NetHandle](#nethandle)&gt;&gt; | Promise used to return the result.|
......@@ -198,7 +200,7 @@ Obtains connection properties of the network corresponding to **netHandle**. Thi
| --------- | ----------------------- | ---- | ---------------- |
| netHandle | [NetHandle](#nethandle) | Yes | Handle of the data network.|
**Return Value**
**Return value**
| Type | Description |
| ------------------------------------------------------- | --------------------------------- |
......@@ -258,7 +260,7 @@ Obtains capability information of the network corresponding to **netHandle**. Th
| --------- | ----------------------- | ---- | ---------------- |
| netHandle | [NetHandle](#nethandle) | Yes | Handle of the data network.|
**Return Value**
**Return value**
| Type | Description |
| --------------------------------------------- | --------------------------------- |
......@@ -285,6 +287,7 @@ Reports connection of the data network. This API uses an asynchronous callback t
**System capability**: SystemCapability.Communication.NetManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| netHandle | [NetHandle](#nethandle) | Yes| Handle of the data network. For details, see [NetHandle](#nethandle).|
......@@ -312,11 +315,13 @@ Reports connection of the data network. This API uses a promise to return the re
**System capability**: SystemCapability.Communication.NetManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| netHandle | [NetHandle](#nethandle) | Yes| Handle of the data network. For details, see [NetHandle](#nethandle).|
**Return Value**
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|
......@@ -343,6 +348,7 @@ Reports disconnection of the data network. This API uses an asynchronous callbac
**System capability**: SystemCapability.Communication.NetManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| netHandle | [NetHandle](#nethandle) | Yes| Handle of the data network. For details, see [NetHandle](#nethandle).|
......@@ -370,11 +376,13 @@ Reports disconnection of the data network. This API uses a promise to return the
**System capability**: SystemCapability.Communication.NetManager.Core
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| netHandle | [NetHandle](#nethandle) | Yes| Handle of the data network. For details, see [NetHandle](#nethandle).|
**Return Value**
**Return value**
| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|
......@@ -432,7 +440,7 @@ Resolves the host name by using the default network to obtain all IP addresses.
| ------ | ------ | ---- | ------------------ |
| host | string | Yes | Host name to be resolved.|
**Return Value**
**Return value**
| Type | Description |
| ------------------------------------------- | ----------------------------- |
......@@ -561,7 +569,7 @@ Obtains the handle of the network specified by **netSpecifier**.
| netSpecifier | [NetSpecifier](#netspecifier) | No | Network specifier. If this parameter is not set, the default network is used. |
| timeout | number | No | Timeout interval for obtaining the network specified by **netSpecifier**. This parameter is valid only when **netSpecifier** is set.|
**Return Value**
**Return value**
| Type | Description |
| ------------------------------- | -------------------- |
......@@ -829,7 +837,7 @@ Resolves the host name by using the corresponding network to obtain all IP addre
| ------ | ------ | ---- | ------------------ |
| host | string | Yes | Host name to be resolved.|
**Return Value**
**Return value**
| Type | Description |
| ------------------------------------------- | ----------------------------- |
......@@ -891,7 +899,7 @@ Resolves the host name by using the corresponding network to obtain the first IP
| ------ | ------ | ---- | ------------------ |
| host | string | Yes | Host name to be resolved.|
**Return Value**
**Return value**
| Type | Description |
| ----------------------------------- | ------------------------------- |
......
zh-cn/application-dev/Readme-CN.md
浏览文件 @ d5332ef7
......@@ -8,8 +8,8 @@
- 快速开始
- 快速入门
- [开发准备](quick-start/start-overview.md)
- [使用eTS语言开发（Stage模型）](quick-start/start-with-ets-stage.md)
- [使用eTS语言开发（FA模型）](quick-start/start-with-ets-fa.md)
- [使用ArkTS语言开发（Stage模型）](quick-start/start-with-ets-stage.md)
- [使用ArkTS语言开发（FA模型）](quick-start/start-with-ets-fa.md)
- [使用JS语言开发（FA模型）](quick-start/start-with-js-fa.md)
- 开发基础知识
- [应用包结构说明(FA模型)](quick-start/package-structure.md)
......
zh-cn/application-dev/application-test/arkxtest-guidelines.md 0 → 100644
浏览文件 @ d5332ef7
# 自动化测试框架使用指南
## 概述
为支撑OpenHarmony操作系统的自动化测试活动开展，我们提供了支持JS/TS语言的单元及UI测试框架，支持开发者针对应用接口或系统接口进行单元测试，并且可基于UI操作进行UI自动化脚本的编写。
本指南重点介绍自动化测试框架的主要功能，同时介绍编写单元/UI自动化测试脚本的方法以及执行过程。
### 简介
OpenHarmony自动化测试框架arkxtest，作为OpenHarmony工具集的重要组成部分，提供了OpenHarmony自动化脚本编写和运行的基础能力。编写方面提供了一系列支持测试脚本编写的API，包括了基础流程API、断言API以及UI操作相关的API，运行方面提供了识别测试脚本、调度执行测试脚本以及汇总测试脚本执行结果的能力。
### 实现原理
框架重要分为两大部分：单元测试框架和UI测试框架。
- 单元测试框架
单元测试框架是测试框架的基础底座，提供了最基本的用例识别、调度、执行及结果汇总的能力。主要功能如下图所示：
![](figures/UnitTest.PNG)
单元测试脚本的基础运行流程如下图所示，依赖aa test命令作为执行入口，该命令可具体参考[对应指南。](../ability/ability-delegator.md)
![](figures/TestFlow.PNG)
- UI测试框架
UI测试框架主要对外提供了[UiTest API](../reference/apis/js-apis-uitest.md)供开发人员在对应测试场景调用，而其脚本的运行基础还是上面提到的单元测试框架。
UI测试框架的主要功能如下图所示：
![](figures/Uitest.PNG)
### 约束与限制
- UI测试框架的能力在OpenHarmony 3.1 release版本之后方可使用，历史版本不支持使用。
- 单元测试框架的部分能力与其版本有关，具体能力与版本匹配信息可见代码仓中的[文档介绍](https://gitee.com/openharmony/testfwk_arkxtest/blob/master/README_zh.md)。
## 环境准备
### 环境要求
OpenHarmony自动化脚本的编写主要基于DevEco Studio，并建议使用3.0之后的版本进行脚本编写。
脚本执行需要PC连接OpenHarmony设备，如RK3568开发板等。
### 搭建环境
DevEco Studio可参考其官网介绍进行[下载](https://developer.harmonyos.com/cn/develop/deveco-studio#download)，并进行相关的配置动作。
## 新建测试脚本
1. 在DevEco Studio中新建应用开发工程，其中ohos目录即为测试脚本所在的目录。
2. 在工程目录下打开待测试模块下的ets文件，将光标置于代码中任意位置，单击**右键 > Show Context Actions** **> Create Ohos Test**或快捷键**Alt+enter** **> Create Ohos Test**创建测试类，更多指导请参考DevEco Studio中[指导](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-openharmony-test-framework-0000001267284568)。
## 编写单元测试脚本
```TS
import { describe, beforeAll, beforeEach, afterEach, afterAll, it, expect } from '@ohos/hypium'
import abilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'
const delegator = abilityDelegatorRegistry.getAbilityDelegator()
export default function abilityTest() {
describe('ActsAbilityTest', function () {
it('testUiExample',0, async function (done) {
console.info("uitest: TestUiExample begin");
//start tested ability
await delegator.executeShellCommand('aa start -b com.ohos.uitest -a MainAbility').then(result =>{
console.info('Uitest, start ability finished:' + result)
}).catch(err => {
console.info('Uitest, start ability failed: ' + err)
})
await sleep(1000);
//check top display ability
await delegator.getCurrentTopAbility().then((Ability)=>{
console.info("get top ability");
expect(Ability.context.abilityInfo.name).assertEqual('MainAbility');
})
done();
})
function sleep(time) {
return new Promise((resolve) => setTimeout(resolve, time));
}
})
}
```
单元测试脚本需要包含如下基本元素：
1、依赖导包，以便使用依赖的测试接口。
2、测试代码编写，主要编写测试代码的相关逻辑，如接口调用等。
3、断言接口调用，设置测试代码中的检查点，如无检查点，则不可认为一个完整的测试脚本。
## 编写UI测试脚本
UI测试脚本是在单元测试框架的基础上编写，主要就是增加了UI测试框架提供的接口调用，实现对应的测试逻辑。
下面的示例代码是在上面的测试脚本基础上增量编写，首先需要增加依赖导包，如下示例代码所示：
```js
import {UiDriver,BY,UiComponent,MatchPattern} from '@ohos.uitest'
```
然后是具体测试代码编写，场景较为简单，就是在启动的应用页面上进行点击操作，然后增加检查点检查用例。
```js
export default function abilityTest() {
describe('ActsAbilityTest', function () {
it('testUiExample',0, async function (done) {
console.info("uitest: TestUiExample begin");
//start tested ability
await delegator.executeShellCommand('aa start -b com.ohos.uitest -a MainAbility').then(result =>{
console.info('Uitest, start ability finished:' + result)
}).catch(err => {
console.info('Uitest, start ability failed: ' + err)
})
await sleep(1000);
//check top display ability
await delegator.getCurrentTopAbility().then((Ability)=>{
console.info("get top ability");
expect(Ability.context.abilityInfo.name).assertEqual('MainAbility');
})
//ui test code
//init uidriver
var driver = await UiDriver.create();
await driver.delayMs(1000);
//find button by text 'Next'
var button = await driver.findComponent(BY.text('Next'));
//click button
await button.click();
await driver.delayMs(1000);
//check text
await driver.assertComponentExist(BY.text('after click'));
await driver.pressBack();
done();
})
function sleep(time) {
return new Promise((resolve) => setTimeout(resolve, time));
}
})
}
```
## 执行测试脚本
执行测试脚本可以直接在DevEco Studio中通过点击按钮执行，当前支持以下执行方式：
1、测试包级别执行即执行测试包内的全部用例。
2、测试套级别执行即执行describe方法中定义的全部测试用例。
3、测试方法级别执行即执行指定it方法也就是单条测试用例。
![](figures/Execute.PNG)
## 查看测试结果
测试执行完毕后可直接在DevEco Studio中查看测试结果，如下图示例所示：
![](figures/TestResult.PNG)
zh-cn/application-dev/media/audio-playback.md
浏览文件 @ d5332ef7
# 音频播放开发指导
## 场景介绍
## 简介
音频播放的主要工作是将音频数据转码为可听见的音频模拟信号并通过输出设备进行播放，同时对播放任务进行管理。
音频播放的主要工作是将音频数据转码为可听见的音频模拟信号，并通过输出设备进行播放，同时对播放任务进行管理，包括开始播放、暂停播放、停止播放、释放资源、设置音量、跳转播放位置、获取轨道信息等功能控制。
**图1** 音频播放状态机
## 运作机制
该模块提供了音频播放状态变化示意图和音频播放外部模块交互图。
**图1** 音频播放状态变化示意图
![zh-ch_image_audio_state_machine](figures/zh-ch_image_audio_state_machine.png)
**说明**：当前为Idle状态，设置src不会改变状态；且src设置成功后，不能再次设置其它src，需调用reset()接口后，才能重新设置src。
**注意**：当前为Idle状态，设置src不会改变状态；且src设置成功后，不能再次设置其它src，需调用reset()接口后，才能重新设置src。
**图2** 音频播放零层图
**图2** 音频播放外部模块交互图
![zh-ch_image_audio_player](figures/zh-ch_image_audio_player.png)
## 开发步骤
**说明**：三方应用通过调用JS接口层提供的js接口实现相应功能时，框架层会通过Native Framework的媒体服务，调用音频部件，将软件解码后的音频数据输出至硬件接口层的音频HDI，实现音频播放功能。
## 开发指导
详细API含义可参考：[媒体服务API文档AudioPlayer](../reference/apis/js-apis-media.md#audioplayer)
### 全流程场景
包含流程：创建实例，设置uri，播放音频，跳转播放位置，设置音量，暂停播放，获取轨道信息，停止播放，重置，释放资源等流程。
音频播放的全流程场景包含：创建实例，设置uri，播放音频，跳转播放位置，设置音量，暂停播放，获取轨道信息，停止播放，重置，释放资源等流程。
AudioPlayer支持的src媒体源输入类型可参考：[src属性说明](../reference/apis/js-apis-media.md#audioplayer_属性)
......
zh-cn/application-dev/media/audio-recorder.md
浏览文件 @ d5332ef7
# 音频录制开发指导
## 场景介绍
## 简介
音频录制的主要工作是捕获音频信号，完成音频编码并保存到文件中，帮助开发者轻松实现音频录制功能。它允许调用者指定音频录制的采样率、声道数、编码格式、封装格式、文件路径等参数。
音频录制的主要工作是捕获音频信号，完成音频编码并保存到文件中，帮助开发者轻松实现音频录制功能。该模块允许调用者指定音频录制的采样率、声道数、编码格式、封装格式、输出文件的路径等参数。
**图1** 音频录制状态机
## 运作机制
该模块提供了音频录制状态变化示意图和音频录制外部模块交互图。
**图1** 音频录制状态变化变化示意图
![zh-ch_image_audio_recorder_state_machine](figures/zh-ch_image_audio_recorder_state_machine.png)
**图2** 音频录制零层图
**图2** 音频录制外部模块交互图
![zh-ch_image_audio_recorder_zero](figures/zh-ch_image_audio_recorder_zero.png)
## 开发步骤
**说明**：三方录音应用或录音机通过调用JS接口层提供的js接口实现相应功能时，框架层会通过Native Framework的媒体服务，调用音频部件获取通过音频HDI捕获的音频数据，再通过软件编码输出编码封装后的音频数据保存至文件中，实现音频录制功能。
## 约束与限制
开发者在进行录制功能开发前，需要先对所开发的应用配置麦克风权限（ohos.permission.MICROPHONE），权限配置相关内容可参考：[访问控制权限申请指导](../security/accesstoken-guidelines.md)
## 开发指导
详细API含义可参考：[媒体服务API文档AudioRecorder](../reference/apis/js-apis-media.md#audiorecorder)
### 全流程场景
包含流程：创建实例，设置录制参数，录制音频，暂停录制，恢复录制，停止录制，释放资源等流程。
音频录制的全流程场景包含：创建实例，设置录制参数，开始录制，暂停录制，恢复录制，停止录制，释放资源等流程。
```js
import media from '@ohos.multimedia.media'
......
zh-cn/application-dev/media/video-playback.md
浏览文件 @ d5332ef7
# 视频播放开发指导
## 场景介绍
## 简介
视频播放的主要工作是将视频数据转码并输出到设备进行播放，同时管理播放任务。本文将对视频播放全流程、视频切换、视频循环播放等场景开发进行介绍说明。
视频播放的主要工作是将视频数据转码并输出到设备进行播放，同时管理播放任务，包括开始播放、暂停播放、停止播放、资源释放、音量设置、跳转播放位置、设置倍数、获取轨道信息等功能控制。本文将对视频播放全流程、视频切换、视频循环播放等场景开发进行介绍说明。
**图1** 视频播放状态机
## 运作机制
该模块提供了视频播放状态变化示意图和视频播放外部模块交互图。
**图1** 视频播放状态变化示意图
![zh-ch_image_video_state_machine](figures/zh-ch_image_video_state_machine.png)
**图2** 视频播放零层图
**图2** 视频播放外部模块交互图
![zh-ch_image_video_player](figures/zh-ch_image_video_player.png)
**说明**：三方应用通过调用JS接口层提供的js接口实现相应功能时，框架层会通过Native Framework的媒体服务，调用音频部件将软件解码后的音频数据，输出至音频HDI，和图形子系统将硬件接口层的解码HDI部件的解码后的图像数据，输出至显示HDI，实现视频播放功能。
*注意：视频播放需要显示、音频、编解码等硬件能力。*
1. 三方应用从Xcomponent组件获取surfaceID。
......@@ -31,13 +37,13 @@
| ts | 视频格式：H264/MPEG2/MPEG4 音频格式：AAC/MP3 | 主流分辨率，如1080P/720P/480P/270P |
| webm | 视频格式：VP8 音频格式：VORBIS | 主流分辨率，如1080P/720P/480P/270P |
## 开发步骤
## 开发指导
详细API含义可参考：[媒体服务API文档VideoPlayer](../reference/apis/js-apis-media.md#videoplayer8)
### 全流程场景
包含流程：创建实例，设置url，设置SurfaceId，准备播放视频，播放视频，暂停播放，获取轨道信息，跳转播放位置，设置音量，设置倍速，结束播放，重置，释放资源等流程。
视频播放的全流程场景包含：创建实例，设置url，设置SurfaceId，准备播放视频，播放视频，暂停播放，获取轨道信息，跳转播放位置，设置音量，设置倍速，结束播放，重置，释放资源等流程。
VideoPlayer支持的url媒体源输入类型可参考：[url属性说明](../reference/apis/js-apis-media.md#videoplayer_属性)
......
zh-cn/application-dev/media/video-recorder.md
浏览文件 @ d5332ef7
# 视频录制开发指导
## 场景介绍
## 简介
视频录制的主要工作是捕获音视频信号，完成音视频编码并保存到文件中，帮助开发者轻松实现音视频录制功能。它允许调用者指定录制的编码格式、封装格式、文件路径等参数。
视频录制的主要工作是捕获音视频信号，完成音视频编码并保存到文件中，帮助开发者轻松实现音视频录制功能，包括开始录制、暂停录制、恢复录制、停止录制、释放资源等功能控制。它允许调用者指定录制的编码格式、封装格式、文件路径等参数。
**图1** 视频录制状态机
## 运作机制
该模块提供了视频录制状态变化示意图和视频录制外部模块交互图。
**图1** 视频录制状态变化示意图
![zh-ch_image_video_recorder_state_machine](figures/zh-ch_image_video_recorder_state_machine.png)
**图2** 视频录制零层图
**图2** 视频录制外部模块交互图
![zh-ch_image_video_recorder_zero](figures/zh-ch_image_video_recorder_zero.png)
## 开发步骤
**说明**：三方相机应用或系统相机通过调用JS接口层提供的js接口实现相应功能时，框架层会通过Native Framework的媒体服务，调用音频部件通过音频HDI捕获的音频数据，再通过软件编码输出编码封装后的音频数据保存至文件中，和图形子系统通过视频HDI捕获的图像数据，再通过视频编码HDI编码，将编码后的图像数据保存至文件中，实现视频录制功能。
## 约束与限制
开发者在进行录制功能开发前，需要先对所开发的应用配置麦克风权限（ohos.permission.MICROPHONE）和相机权限（ohos.permission.CAMERA），权限配置相关内容可参考：[访问控制权限申请指导](../security/accesstoken-guidelines.md)
## 开发指导
详细API含义可参考：[媒体服务API文档VideoRecorder](../reference/apis/js-apis-media.md#videorecorder9)
### 全流程场景
包含流程：创建实例、设置录制参数、录制视频、暂停录制、恢复录制、停止录制、释放资源等流程。
视频录制全流程场景包含：创建实例、设置录制参数、开始录制、暂停录制、恢复录制、停止录制、释放资源等流程。
```js
import media from '@ohos.multimedia.media'
......
zh-cn/application-dev/notification/Readme-CN.md
浏览文件 @ d5332ef7
......@@ -3,7 +3,4 @@
- [公共事件与通知概述](notification-brief.md)
- [公共事件开发指导](common-event.md)
- [通知开发指导](notification-guidelines.md)
- 后台代理提醒
- [后台代理提醒开发概述](background-agent-scheduled-reminder-overview.md)
- [后台代理提醒开发指导](background-agent-scheduled-reminder-guide.md)
- [调试助手使用指导](assistant-guidelines.md)
\ No newline at end of file
zh-cn/application-dev/quick-start/Readme-CN.md
浏览文件 @ d5332ef7
......@@ -2,8 +2,8 @@
- 快速入门
- [开发准备](start-overview.md)
- [使用eTS语言开发（Stage模型）](start-with-ets-stage.md)
- [使用eTS语言开发（FA模型）](start-with-ets-fa.md)
- [使用ArkTS语言开发（Stage模型）](start-with-ets-stage.md)
- [使用ArkTS语言开发（FA模型）](start-with-ets-fa.md)
- [使用JS语言开发（FA模型）](start-with-js-fa.md)
- 开发基础知识
......
zh-cn/application-dev/quick-start/start-overview.md
浏览文件 @ d5332ef7
......@@ -16,11 +16,11 @@
OpenHarmony提供了一套UI开发框架，即方舟开发框架（ArkUI框架）。方舟开发框架可为开发者提供应用UI开发所必需的能力，比如多种组件、布局计算、动画能力、UI交互、绘制等。
方舟开发框架针对不同目的和技术背景的开发者提供了两种开发范式，分别是基于eTS的声明式开发范式（简称“声明式开发范式”）和兼容JS的类Web开发范式（简称“类Web开发范式”）。以下是两种开发范式的简单对比。
方舟开发框架针对不同目的和技术背景的开发者提供了两种开发范式，分别是基于ArkTS的声明式开发范式（简称“声明式开发范式”）和兼容JS的类Web开发范式（简称“类Web开发范式”）。以下是两种开发范式的简单对比。
| **开发范式名称** | **语言生态** | **UI更新方式** | **适用场景** | **适用人群** |
| -------- | -------- | -------- | -------- | -------- |
| 声明式开发范式 | eTS语言 | 数据驱动更新 | 复杂度较大、团队合作度较高的程序 | 移动系统应用开发人员、系统应用开发人员 |
| 声明式开发范式 | ArkTS语言 | 数据驱动更新 | 复杂度较大、团队合作度较高的程序 | 移动系统应用开发人员、系统应用开发人员 |
| 类Web开发范式 | JS语言 | 数据驱动更新 | 界面较为简单的程序应用和卡片 | Web前端开发人员 |
更多UI框架的开发内容及指导，详见[UI开发](../ui/arkui-overview.md)。
......@@ -36,7 +36,7 @@ Ability框架模型结构具有两种形态：
- **Stage模型**：从API 9开始，Ability框架引入并支持使用Stage模型进行开发。更多Stage模型的内容详见[Stage模型综述](../ability/stage-brief.md)。
FA模型和Stage模型的工程目录结构存在差异，Stage模型只支持使用eTS语言进行开发。
FA模型和Stage模型的工程目录结构存在差异，Stage模型只支持使用ArkTS语言进行开发。
关于FA模型和Stage模型的整体架构和设计思想等更多区别，详见[Ability框架概述](../ability/ability-brief.md)。
......@@ -49,4 +49,4 @@ FA模型和Stage模型的工程目录结构存在差异，Stage模型只支持
2. 请参考[配置OpenHarmony SDK](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-setting-up-environment-0000001263160443)，完成**DevEco Studio**的安装和开发环境配置。
完成上述操作及基本概念的理解后，可参照[使用eTS语言进行开发（Stage模型）](start-with-ets-stage.md)、[使用eTS语言开发（FA模型）](start-with-ets-fa.md)、[使用JS语言开发（FA模型）](../quick-start/start-with-js-fa.md)中的任一章节进行下一步体验和学习。
完成上述操作及基本概念的理解后，可参照[使用ArkTS语言进行开发（Stage模型）](start-with-ets-stage.md)、[使用ArkTS语言开发（FA模型）](start-with-ets-fa.md)、[使用JS语言开发（FA模型）](../quick-start/start-with-js-fa.md)中的任一章节进行下一步体验和学习。
zh-cn/application-dev/quick-start/start-with-ets-fa.md
浏览文件 @ d5332ef7
# 使用eTS语言开发（FA模型）
# 使用ArkTS语言开发（FA模型）
> **说明：**
......@@ -18,7 +18,7 @@
![02](figures/02.png)
> **说明：**
> DevEco Studio V3.0 Beta3及更高版本支持使用eTS[低代码开发](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-low-code-development-0000001218440652)方式。
> DevEco Studio V3.0 Beta3及更高版本支持使用ArkTS[低代码开发](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-low-code-development-0000001218440652)方式。
>
> 低代码开发方式具有丰富的UI界面编辑功能，通过可视化界面开发方式快速构建布局，可有效降低开发者的上手成本并提升开发者构建UI界面的效率。
>
......@@ -288,4 +288,4 @@
![zh-cn_image_0000001363934577](figures/zh-cn_image_0000001363934577.png)
恭喜您已经使用eTS语言开发（FA模型）完成了第一个OpenHarmony应用，快来[探索更多的OpenHarmony功能](../application-dev-guide.md)吧。
恭喜您已经使用ArkTS语言开发（FA模型）完成了第一个OpenHarmony应用，快来[探索更多的OpenHarmony功能](../application-dev-guide.md)吧。
zh-cn/application-dev/quick-start/start-with-ets-stage.md
浏览文件 @ d5332ef7
# 使用eTS语言开发（Stage模型）
# 使用ArkTS语言开发（Stage模型）
> **说明：**
......@@ -19,7 +19,7 @@
> **说明：**
>
> 支持使用eTS[低代码开发](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-low-code-development-0000001218440652)方式。
> 支持使用ArkTS[低代码开发](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-low-code-development-0000001218440652)方式。
>
> 低代码开发方式具有丰富的UI界面编辑功能，通过可视化界面开发方式快速构建布局，可有效降低开发者的上手成本并提升开发者构建UI界面的效率。
>
......@@ -287,4 +287,4 @@
![zh-cn_image_0000001311334972](figures/zh-cn_image_0000001311334972.png)
恭喜您已经使用eTS语言开发（Stage模型）完成了第一个OpenHarmony应用，快来[探索更多的OpenHarmony功能](../application-dev-guide.md)吧。
恭喜您已经使用ArkTS语言开发（Stage模型）完成了第一个OpenHarmony应用，快来[探索更多的OpenHarmony功能](../application-dev-guide.md)吧。
zh-cn/application-dev/reference/apis/js-apis-camera.md
浏览文件 @ d5332ef7
因为 它太大了无法显示 source diff 。你可以改为 查看blob。
zh-cn/application-dev/reference/apis/js-apis-media.md
浏览文件 @ d5332ef7
......@@ -52,7 +52,7 @@ createVideoPlayer(callback: AsyncCallback\<[VideoPlayer](#videoplayer8)>): void
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------- | ---- | ------------------------------ |
| callback | AsyncCallback<[VideoPlayer](#videoplayer8)> | 是 | 回调函数。异步返回VideoPlayer实例，可用于管理和播放视频媒体。 |
| callback | AsyncCallback<[VideoPlayer](#videoplayer8)> | 是 | 回调函数。异步返回VideoPlayer实例，失败时返回null。可用于管理和播放视频媒体。 |
**示例：**
......@@ -79,9 +79,9 @@ createVideoPlayer(): Promise<[VideoPlayer](#videoplayer8)>
**返回值：**
| 类型 | 说明 |
| ------------------------------------- | ----------------------------------- |
| Promise<[VideoPlayer](#videoplayer8)> | Promise对象。异步返回VideoPlayer实例，可用于管理和播放视频媒体。 |
| 类型 | 说明 |
| ------------------------------------- | ------------------------------------------------------------ |
| Promise<[VideoPlayer](#videoplayer8)> | Promise对象。异步返回VideoPlayer实例，失败时返回null。可用于管理和播放视频媒体。 |
**示例：**
......@@ -111,9 +111,9 @@ createAudioRecorder(): AudioRecorder
**返回值:**
| 类型 | 说明 |
| ------------------------------- | ----------------------------------------- |
| [AudioRecorder](#audiorecorder) | 返回AudioRecorder类实例，失败时返回null。 |
| 类型 | 说明 |
| ------------------------------- | ------------------------------------------------------------ |
| [AudioRecorder](#audiorecorder) | 返回AudioRecorder类实例，失败时返回null。可用于录制音频媒体。 |
**示例：**
......@@ -134,7 +134,7 @@ createVideoRecorder(callback: AsyncCallback\<[VideoRecorder](#videorecorder9)>):
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------------- | ---- | ------------------------------ |
| callback | AsyncCallback<[VideoRecorder](#videorecorder9)> | 是 | 回调函数。异步返回VideoRecorder实例，可用于录制视频媒体。 |
| callback | AsyncCallback<[VideoRecorder](#videorecorder9)> | 是 | 回调函数。异步返回VideoRecorder实例，失败时返回null。可用于录制视频媒体。 |
**示例：**
......@@ -162,9 +162,9 @@ createVideoRecorder(): Promise<[VideoRecorder](#videorecorder9)>
**返回值：**
| 类型 | 说明 |
| ----------------------------------------- | ----------------------------------- |
| Promise<[VideoRecorder](#videorecorder9)> | Promise对象。异步返回VideoRecorder实例，可用于录制视频媒体。 |
| 类型 | 说明 |
| ----------------------------------------- | ------------------------------------------------------------ |
| Promise<[VideoRecorder](#videorecorder9)> | Promise对象。异步返回VideoRecorder实例，失败时返回null。可用于录制视频媒体。 |
**示例：**
......@@ -361,9 +361,9 @@ seek(timeMs: number): void
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------------------------ |
| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms）。 |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ----------------------------------------------------------- |
| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围[0, duration]。 |
**示例：**
......@@ -426,9 +426,9 @@ getTrackDescription(callback: AsyncCallback<Array\<MediaDescription>>): void
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | -------------------------- |
| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是 | 获取音频轨道信息回调方法。 |
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ |
| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是 | 音频轨道信息MediaDescription数组回调方法。 |
**示例：**
......@@ -462,9 +462,9 @@ getTrackDescription(): Promise<Array\<MediaDescription>>
**返回值：**
| 类型 | 说明 |
| ------------------------------------------------------ | ------------------------------- |
| Promise<Array<[MediaDescription](#mediadescription8)>> | 获取音频轨道信息Promise返回值。 |
| 类型 | 说明 |
| ------------------------------------------------------ | ----------------------------------------------- |
| Promise<Array<[MediaDescription](#mediadescription8)>> | 音频轨道信息MediaDescription数组Promise返回值。 |
**示例：**
......@@ -496,7 +496,7 @@ for (let i = 0; i < arrayDescription.length; i++) {
on(type: 'bufferingUpdate', callback: (infoType: [BufferingInfoType](#bufferinginfotype8), value: number) => void): void
开始订阅音频缓存更新事件。
开始订阅音频缓存更新事件。仅网络播放支持该订阅事件。
**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer
......@@ -593,7 +593,7 @@ audioPlayer.src = fdPath; //设置src属性，并触发'dataLoad'事件回调
on(type: 'timeUpdate', callback: Callback\<number>): void
开始订阅音频播放时间更新事件。
开始订阅音频播放时间更新事件。处于播放状态时，每隔1s上报一次该事件。
**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer
......@@ -1013,10 +1013,10 @@ seek(timeMs: number, callback: AsyncCallback\<number>): void
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ------------------------------------ |
| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms）。 |
| callback | function | 是 | 跳转到指定播放位置的回调方法。 |
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 |
| callback | function | 是 | 跳转到指定播放位置的回调方法。 |
**示例：**
......@@ -1041,11 +1041,11 @@ seek(timeMs: number, mode:SeekMode, callback: AsyncCallback\<number>): void
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---------------------- | ---- | ------------------------------------ |
| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms）。 |
| mode | [SeekMode](#seekmode8) | 是 | 跳转模式。 |
| callback | function | 是 | 跳转到指定播放位置的回调方法。 |
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---------------------- | ---- | ------------------------------------------------------------ |
| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 |
| mode | [SeekMode](#seekmode8) | 是 | 跳转模式。 |
| callback | function | 是 | 跳转到指定播放位置的回调方法。 |
**示例：**
......@@ -1071,16 +1071,16 @@ seek(timeMs: number, mode?:SeekMode): Promise\<number>
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------------------- | ---- | ------------------------------------ |
| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms）。 |
| mode | [SeekMode](#seekmode8) | 否 | 跳转模式。 |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------------------- | ---- | ------------------------------------------------------------ |
| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 |
| mode | [SeekMode](#seekmode8) | 否 | 跳转模式。 |
**返回值：**
| 类型 | 说明 |
| -------------- | ----------------------------------- |
| Promise\<void> | 跳转到指定播放位置的Promise返回值。 |
| 类型 | 说明 |
| -------------- | ------------------------------------------- |
| Promise\<void> | 跳转到指定播放位置的Promise返回值，单位ms。 |
**示例：**
......@@ -1219,9 +1219,9 @@ getTrackDescription(callback: AsyncCallback<Array\<MediaDescription>>): void
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | -------------------------- |
| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是 | 获取视频轨道信息回调方法。 |
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ |
| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是 | 视频轨道信息MediaDescription数组回调方法。 |
**示例：**
......@@ -1255,9 +1255,9 @@ getTrackDescription(): Promise<Array\<MediaDescription>>
**返回值：**
| 类型 | 说明 |
| ------------------------------------------------------ | ------------------------------- |
| Promise<Array<[MediaDescription](#mediadescription8)>> | 获取视频轨道信息Promise返回值。 |
| 类型 | 说明 |
| ------------------------------------------------------ | ----------------------------------------------- |
| Promise<Array<[MediaDescription](#mediadescription8)>> | 视频轨道信息MediaDescription数组Promise返回值。 |
**示例：**
......@@ -1331,9 +1331,9 @@ setSpeed(speed:number): Promise\<number>
**返回值：**
| 类型 | 说明 |
| ---------------- | ------------------------- |
| Promise\<number> | 通过Promise获取设置结果。 |
| 类型 | 说明 |
| ---------------- | ------------------------------------------------------------ |
| Promise\<number> | 播放速度Promise返回值，具体见[PlaybackSpeed](#playbackspeed8)。 |
**示例：**
......@@ -1388,13 +1388,13 @@ selectBitrate(bitrate:number): Promise\<number>
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------ | ---- | -------------------------------------------- |
| bitrate | number | 是 | 指定码率播放，用于hls多码率场景，单位为bps。 |
| bitrate | number | 是 | 指定播放码率，用于hls多码率场景，单位为bps。 |
**返回值：**
| 类型 | 说明 |
| ---------------- | ------------------------- |
| Promise\<number> | 通过Promise获取设置结果。 |
| 类型 | 说明 |
| ---------------- | --------------------------- |
| Promise\<number> | 指定播放码率Promise返回值。 |
**示例：**
......@@ -1434,7 +1434,7 @@ videoPlayer.on('playbackCompleted', () => {
on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void
开始监听视频缓存更新事件。
开始监听视频缓存更新事件。仅网络播放支持该订阅事件。
**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer
......
zh-cn/application-dev/reference/apis/js-apis-system-device.md
浏览文件 @ d5332ef7
# 设备信息
本模块提供当前设备的信息。
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> - 从API Version 6开始，该接口不再维护，推荐使用新接口[`@ohos.deviceInfo`](js-apis-device-info.md)进行设备信息查询。
>
> - 本模块首批接口从API version 3开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
## 导入模块
```
import device from '@system.device';
```
## device.getInfo
getInfo(Object): void
......@@ -23,7 +22,7 @@ getInfo(Object): void
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> 在首页的onShow生命周期之前不建议调用device.getInfo接口。
**系统能力：** SystemCapability.Startup.SysInfo
**系统能力：** SystemCapability.Startup.SystemInfo
**参数：**
......
zh-cn/application-dev/reference/apis/js-apis-uitest.md
浏览文件 @ d5332ef7
......@@ -4,10 +4,13 @@ UiTest提供模拟UI操作的能力，供开发者在测试场景使用，主要
该模块提供以下功能：
- [By](#by)：提供控件特征描述能力，用于控件筛选匹配查找。
- [UiComponent](#uicomponent)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。
- [UiDriver](#uidriver)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能能力。
- [UiWINDOW<sup>9+</sup>](#uiwindow9)：入口类，提供窗口属性获取，窗口拖动、调整窗口大小等能能力。
- [On<sup>9+</sup>](#on9)：提供控件特征描述能力，用于控件筛选匹配查找。
- [Component<sup>9+</sup>](#component9)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。
- [Driver<sup>9+</sup>](#driver9)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能能力。
- [UiWindow<sup>9+</sup>](#uiwindow9)：入口类，提供窗口属性获取，窗口拖动、调整窗口大小等能能力。
- [By](#by)：提供控件特征描述能力，用于控件筛选匹配查找。从API version9开始不再维护，建议使用[[On<sup>9+</sup>](#on9)](#driver9)。
- [UiComponent](#uicomponent)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。从API version9开始不再维护，建议使用[Component<sup>9+</sup>](#component9)。
- [UiDriver](#uidriver)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能能力。从API version9开始不再维护，建议使用[Driver<sup>9+</sup>](#driver9)。
>**说明：**
>
......@@ -16,79 +19,52 @@ UiTest提供模拟UI操作的能力，供开发者在测试场景使用，主要
## 导入模块
```
import {UiDriver, BY, MatchPattern, ResizeDirection, WindowMode, DisplayRotation, PointerMatrix} from '@ohos.uitest'
```
## By
UiTest框架通过By类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。<br>
By提供的API能力具有以下几个特点:<br>1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。<br>2、控件属性支持多种匹配模式。<br>3、支持控件绝对定位，相对定位，可通过[By.isBefore](#isbefore)和[By.isAfter](#isafter)等API限定邻近控件特征进行辅助定位。<br>By类提供的所有API均为同步接口，建议使用者通过静态构造器BY来链式创建By对象。
```js
BY.text('123').type('button')
import {UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix} from '@ohos.uitest'
```
### text
text(txt: string, pattern?: MatchPattern): By
指定目标控件文本属性，支持多种匹配模式，返回By对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------------ | ---- | --------------------------------------------------- |
| txt | string | 是 | 指定控件文本，用于匹配目标控件文本。 |
| pattern | MatchPattern | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------- |
| [By](#by) | 返回指定目标控件文本属性的By对象。 |
## On<sup>9+</sup>
**示例：**
UiTest框架在API9中，通过On类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。<br>
On提供的API能力具有以下几个特点:<br>1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。<br>2、控件属性支持多种匹配模式。<br>3、支持控件绝对定位，相对定位，可通过[ON.isBefore](#isbefore)和[ON.isAfter](#isafter)等API限定邻近控件特征进行辅助定位。<br>On类提供的所有API均为同步接口，建议使用者通过静态构造器ON来链式创建On对象。
```js
let by = BY.text('123') //使用静态构造器BY创建by对象，指定目标控件的text属性。
ON.text('123').type('button')
```
### text<sup>9+</sup>
### key
key(key: string): By
text(txt: string, pattern?: MatchPattern): On
指定目标控件key值属性，返回By对象自身。
指定目标控件文本属性，支持多种匹配模式，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ----------------- |
| key | string | 是 | 指定控件的Key值。 |
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ----------------------------- | ---- | --------------------------------------------------- |
| txt | string | 是 | 指定控件文本，用于匹配目标控件文本。 |
| pattern | [MatchPattern](#matchpattern) | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 |
**返回值：**
| 类型 | 说明 |
| --------- | ----------------------------------- |
| [By](#by) | 返回指定目标控件key值属性的By对象。 |
| 类型 | 说明 |
| ---------- | ---------------------------------- |
| [On](#on9) | 返回指定目标控件文本属性的On对象。 |
**示例：**
```js
let by = BY.key('123') //使用静态构造器BY创建by对象，指定目标控件的key值属性。
let on = ON.text('123') //使用静态构造器ON创建On对象，指定目标控件的text属性。
```
### id
### id<sup>9+</sup>
id(id: number): By
id(id: string): On
指定目标控件id属性，返回By对象自身。
指定目标控件id属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
......@@ -96,26 +72,26 @@ id(id: number): By
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------------- |
| id | number | 是 | 指定控件的id值。 |
| id | string | 是 | 指定控件的id值。 |
**返回值：**
| 类型 | 说明 |
| --------- | -------------------------------- |
| [By](#by) | 返回指定目标控件id属性的By对象。 |
| 类型 | 说明 |
| ---------- | -------------------------------- |
| [On](#on9) | 返回指定目标控件id属性的On对象。 |
**示例：**
```js
let by = BY.id(123) //使用静态构造器BY创建by对象，指定目标控件的id属性。
let on = ON.id(123) //使用静态构造器ON创建On对象，指定目标控件的id属性。
```
### type
### type<sup>9+</sup>
type(tp: string): By
type(tp: string): On
指定目标控件的控件类型属性，返回By对象自身。
指定目标控件的控件类型属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
......@@ -127,326 +103,311 @@ type(tp: string): By
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------- |
| [By](#by) | 返回指定目标控件的控件类型属性的By对象。 |
| 类型 | 说明 |
| ---------- | ---------------------------------------- |
| [On](#on9) | 返回指定目标控件的控件类型属性的On对象。 |
**示例：**
```js
let by = BY.type('button') //使用静态构造器BY创建by对象，指定目标控件的控件类型属性。
let on = ON.type('button') //使用静态构造器ON创建On对象，指定目标控件的控件类型属性。
```
### clickable
### clickable<sup>9+</sup>
clickable(b?: boolean): By
clickable(b?: boolean): On
指定目标控件的可点击状态属性，返回By对象自身。
指定目标控件的可点击状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---- | ---- | -------------------------------- |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | 否 | 指定控件可点击状态，true：可点击，false：不可点击。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ------------------------------------------ |
| [By](#by) | 返回指定目标控件的可点击状态属性的By对象。 |
| 类型 | 说明 |
| ---------- | ------------------------------------------ |
| [On](#on9) | 返回指定目标控件的可点击状态属性的On对象。 |
**示例：**
```js
let by = BY.clickable(true) //使用静态构造器BY创建by对象，指定目标控件的可点击状态属性。
let on = ON.clickable(true) //使用静态构造器ON创建On对象，指定目标控件的可点击状态属性。
```
### longClickable<sup>9+</sup>
longClickable(b?: boolean): By
longClickable(b?: boolean): On
指定目标控件的可长按点击状态属性，返回By对象自身。
指定目标控件的可长按点击状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---- | ---- | ------------------------------------ |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | 否 | 指定控件可长按点击状态，true：可长按点击，false：不可长按点击。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------------- |
| [By](#by) | 返回指定目标控件的可长按点击状态属性的By对象。 |
| 类型 | 说明 |
| ---------- | ---------------------------------------------- |
| [On](#on9) | 返回指定目标控件的可长按点击状态属性的On对象。 |
**示例：**
```js
let by = BY.longClickable(true) //使用静态构造器BY创建by对象，指定目标控件的可长按点击状态属性。
let on = ON.longClickable(true) //使用静态构造器ON创建On对象，指定目标控件的可长按点击状态属性。
```
### scrollable
### scrollable<sup>9+</sup>
scrollable(b?: boolean): By
scrollable(b?: boolean): On
指定目标控件的可滑动状态属性，返回By对象自身。
指定目标控件的可滑动状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---- | ---- | ---------------------------- |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ----------------------------------------------------------- |
| b | boolean | 否 | 控件可滑动状态，true：可滑动，false：不可滑动。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ------------------------------------------ |
| [By](#by) | 返回指定目标控件的可滑动状态属性的By对象。 |
| 类型 | 说明 |
| ---------- | ------------------------------------------ |
| [On](#on9) | 返回指定目标控件的可滑动状态属性的On对象。 |
**示例：**
```js
let by = BY.scrollable(true) //使用静态构造器BY创建by对象，指定目标控件的可滑动状态属性。
let on = ON.scrollable(true) //使用静态构造器ON创建On对象，指定目标控件的可滑动状态属性。
```
### enabled
### enabled<sup>9+</sup>
enabled(b?: boolean): By
enabled(b?: boolean): On
指定目标控件的使能状态属性，返回By对象自身。
指定目标控件的使能状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---- | ---- | ------------------------------ |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | --------------------------------------------------------- |
| b | boolean | 否 | 指定控件使能状态，true：使能，false：未使能。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------- |
| [By](#by) | 返回指定目标控件的使能状态属性的By对象。 |
| 类型 | 说明 |
| ---------- | ---------------------------------------- |
| [On](#on9) | 返回指定目标控件的使能状态属性的On对象。 |
**示例：**
```js
let by = BY.enabled(true) //使用静态构造器BY创建by对象，指定目标控件的使能状态属性。
let on = ON.enabled(true) //使用静态构造器ON创建On对象，指定目标控件的使能状态属性。
```
### focused
### focused<sup>9+</sup>
focused(b?: boolean): By
focused(b?: boolean): On
指定目标控件的获焦状态属性，返回By对象自身。
指定目标控件的获焦状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---- | ---- | -------------------------- |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ----------------------------------------------------- |
| b | boolean | 否 | 控件获焦状态，true：获焦，false：未获焦。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------- |
| [By](#by) | 返回指定目标控件的获焦状态属性的By对象。 |
| 类型 | 说明 |
| ---------- | ---------------------------------------- |
| [On](#on9) | 返回指定目标控件的获焦状态属性的On对象。 |
**示例：**
```js
let by = BY.focused(true) //使用静态构造器BY创建by对象，指定目标控件的获焦状态属性。
let on = ON.focused(true) //使用静态构造器ON创建On对象，指定目标控件的获焦状态属性。
```
### selected
### selected<sup>9+</sup>
selected(b?: boolean): By
selected(b?: boolean): On
指定目标控件的被选中状态属性，返回By对象自身。
指定目标控件的被选中状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---- | ---- | -------------------------------- |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | 否 | 指定控件被选中状态，true：被选中，false：未被选中。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ------------------------------------------ |
| [By](#by) | 返回指定目标控件的被选中状态属性的By对象。 |
| 类型 | 说明 |
| ---------- | ------------------------------------------ |
| [On](#on9) | 返回指定目标控件的被选中状态属性的On对象。 |
**示例：**
```js
let by = BY.selected(true) //使用静态构造器BY创建by对象，指定目标控件的被选中状态属性。
let on = ON.selected(true) //使用静态构造器ON创建On对象，指定目标控件的被选中状态属性。
```
### checked<sup>9+</sup>
checked(b?: boolean): By
checked(b?: boolean): On
指定目标控件的被勾选状态属性，返回By对象自身。
指定目标控件的被勾选状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---- | ---- | --------------------------------- |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | 否 | 指定控件被勾选状态，true：被勾选，false：未被勾选。默认为false。 |
**返回值：**
| 类型 | 说明 |
| --------- | ------------------------------------------ |
| [By](#by) | 返回指定目标控件的被勾选状态属性的By对象。 |
| 类型 | 说明 |
| ---------- | ------------------------------------------ |
| [On](#on9) | 返回指定目标控件的被勾选状态属性的On对象。 |
**示例：**
```js
let by = BY.checked(true) //使用静态构造器BY创建by对象，指定目标控件的被勾选状态属性
let on = ON.checked(true) //使用静态构造器ON创建On对象，指定目标控件的被勾选状态属性
```
### checkable<sup>9+</sup>
checkable(b?: boolean): By
checkable(b?: boolean): On
指定目标控件能否被勾选状态属性，返回By对象自身。
指定目标控件能否被勾选状态属性，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---- | ---- | ------------------------------------- |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | 否 | 指定控件能否被勾选状态，true：能被勾选，false：不能被勾选。默认为false。 |
**返回值：**
| 类型 | 说明 |
| --------- | -------------------------------------------- |
| [By](#by) | 返回指定目标控件能否被勾选状态属性的By对象。 |
| 类型 | 说明 |
| ---------- | -------------------------------------------- |
| [On](#on9) | 返回指定目标控件能否被勾选状态属性的On对象。 |
**示例：**
```js
let by = BY.checkable(true) //使用静态构造器BY创建by对象，指定目标控件的能否被勾选状态属性。
let on = ON.checkable(true) //使用静态构造器ON创建On对象，指定目标控件的能否被勾选状态属性。
```
### isBefore
### isBefore<sup>9+</sup>
isBefore(by: By): By
isBefore(on: On): On
指定目标控件位于给出的特征属性控件之前，返回By对象自身。
指定目标控件位于给出的特征属性控件之前，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | ---------------- |
| by | [By](#by) | 是 | 特征控件的属性。 |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | 是 | 特征控件的属性要求。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------------------- |
| [By](#by) | 返回指定目标控件位于给出的特征属性控件之前的By对象。 |
| 类型 | 说明 |
| ---------- | ---------------------------------------------------- |
| [On](#on9) | 返回指定目标控件位于给出的特征属性控件之前的On对象。 |
**示例：**
```js
let by = BY.isBefore(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之前。
let on = ON.isBefore(ON.text('123')) //使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之前。
```
### isAfter
### isAfter<sup>9+</sup>
isAfter(by: By): By
isAfter(on: On): On
指定目标控件位于给出的特征属性控件之后，返回By对象自身。
指定目标控件位于给出的特征属性控件之后，返回On对象自身。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | ---------------- |
| by | [By](#by) | 是 | 特征控件的属性。 |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | 是 | 特征控件的属性要求。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------------------- |
| [By](#by) | 返回指定目标控件位于给出的特征属性控件之后的By对象。 |
| 类型 | 说明 |
| ---------- | ---------------------------------------------------- |
| [On](#on9) | 返回指定目标控件位于给出的特征属性控件之后的On对象。 |
**示例：**
```js
let by = BY.isAfter(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之后。
let on = ON.isAfter(ON.text('123')) //使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之后。
```
## UiComponent
## Component<sup>9+</sup>
UiTest中，UiComponent类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。
UiTest框架在API9中，Component类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。
该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。
### Point<sup>9+</sup>
坐标点信息。
**系统能力**：SystemCapability.Test.UiTest
| 名称 | 参数类型 | 可读 | 可写 | 描述 |
| ---- | -------- | ---- | ---- | ---------------- |
| X | number | 是 | 否 | 坐标点的横坐标。 |
| Y | number | 是 | 否 | 坐标点的纵坐标。 |
### click<sup>9+</sup>
### Rect<sup>9+</sup>
click(): Promise\<void>
控件的边框信息。
控件对象进行点击操作。
**系统能力**：SystemCapability.Test.UiTest
| 名称 | 参数类型 | 可读 | 可写 | 描述 |
| ------- | -------- | ---- | ---- | ------------------------- |
| leftX | number | 是 | 否 | 控件边框的左上角的X坐标。 |
| topY | number | 是 | 否 | 控件边框的左上角的Y坐标。 |
| rightX | number | 是 | 否 | 控件边框的右下角的X坐标。 |
| bottomY | number | 是 | 否 | 控件边框的右下角的Y坐标。 |
### UiComponent.click
click(): Promise\<void>
**错误码：**
控件对象进行点击操作。
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
**系统能力**：SystemCapability.Test.UiTest
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
await button.click()
}
```
### doubleClick
### doubleClick<sup>9+</sup>
doubleClick(): Promise\<void>
......@@ -454,17 +415,26 @@ doubleClick(): Promise\<void>
**系统能力**：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 = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
await button.doubleClick()
}
```
### longClick
### longClick<sup>9+</sup>
longClick(): Promise\<void>
......@@ -472,19 +442,28 @@ longClick(): Promise\<void>
**系统能力**：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 = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
await button.longClick()
}
```
### getId
### getId<sup>9+</sup>
getId(): Promise\<number>
getId(): Promise\<string>
获取控件对象的id值。
......@@ -494,43 +473,28 @@ getId(): Promise\<number>
| 类型 | 说明 |
| ---------------- | ------------------------------- |
| Promise\<number> | 以Promise形式返回的控件的id值。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let num = await button.getId()
}
```
### getKey
getKey(): Promise\<string>
获取控件对象的key值。
| Promise\<string> | 以Promise形式返回的控件的id值。 |
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
**返回值：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 类型 | 说明 |
| ---------------- | ------------------------------ |
| Promise\<string> | 以Promise形式返回控件的key值。 |
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let str_key = await button.getKey()
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
let num = await button.getId()
}
```
### getText
### getText<sup>9+</sup>
getText(): Promise\<string>
......@@ -544,17 +508,26 @@ getText(): Promise\<string>
| ---------------- | --------------------------------- |
| Promise\<string> | 以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 = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
let text = await button.getText()
}
```
### getType
### getType<sup>9+</sup>
getType(): Promise\<string>
......@@ -568,12 +541,21 @@ getType(): Promise\<string>
| ---------------- | ----------------------------- |
| Promise\<string> | 以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 = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
let type = await button.getType()
}
```
......@@ -592,12 +574,21 @@ getBounds(): Promise\<Rect>
| ------------------------ | ------------------------------------- |
| 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 = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
let rect = await button.getBounds()
}
```
......@@ -616,17 +607,26 @@ getBoundsCenter(): Promise\<Point>
| -------------------------- | --------------------------------------- |
| 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 = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
let point = await button.getBoundsCenter()
}
```
### isClickable
### isClickable<sup>9+</sup>
isClickable(): Promise\<boolean>
......@@ -636,16 +636,25 @@ isClickable(): Promise\<boolean>
**返回值：**
| 类型 | 说明 |
| -------------- | ------------------------------------- |
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\<boolean> | 以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 = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
if(await button.isClickable()) {
console.info('This button can be Clicked')
}
......@@ -665,16 +674,25 @@ isLongClickable(): Promise\<boolean>
**返回值：**
| 类型 | 说明 |
| -------------- | ------------------------------------------- |
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\<boolean> | 以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 = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
if(await button.isLongClickable()) {
console.info('This button can longClick')
}
......@@ -694,16 +712,25 @@ isChecked(): Promise\<boolean>
**返回值：**
| 类型 | 说明 |
| -------------- | ------------------------------------- |
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\<boolean> | 以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 = UiDriver.create()
let checkBox = await driver.findComponent(BY.type('Checkbox'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('Checkbox'))
if(await checkBox.isChecked) {
console.info('This checkBox is checked')
}
......@@ -723,16 +750,25 @@ isCheckable(): Promise\<boolean>
**返回值：**
| 类型 | 说明 |
| -------------- | ------------------------------------------- |
| 错误码ID | 错误码信息 |
| ----------------- | ------------------------------------------------------------ |
| Promise\<boolean> | 以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 = UiDriver.create()
let checkBox = await driver.findComponent(BY.type('Checkbox'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('Checkbox'))
if(await checkBox.isCheckable) {
console.info('This checkBox is checkable')
}
......@@ -742,7 +778,7 @@ async function demo() {
}
```
### isScrollable
### isScrollable<sup>9+</sup>
isScrollable(): Promise\<boolean>
......@@ -752,16 +788,25 @@ isScrollable(): Promise\<boolean>
**返回值：**
| 类型 | 说明 |
| -------------- | ------------------------------------- |
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\<boolean> | 以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 = UiDriver.create()
let scrollBar = await driver.findComponent(BY.scrollable(true))
let driver = Driver.create()
let button = await driver.findComponent(ON.scrollable(true))
if(await scrollBar.isScrollable()) {
console.info('This scrollBar can be operated')
}
......@@ -772,7 +817,7 @@ async function demo() {
```
### isEnabled
### isEnabled<sup>9+</sup>
isEnabled(): Promise\<boolean>
......@@ -782,16 +827,25 @@ isEnabled(): Promise\<boolean>
**返回值：**
| 类型 | 说明 |
| -------------- | ------------------------------- |
| 类型 | 说明 |
| ----------------- | ---------------------------------------------------------- |
| Promise\<boolean> | 以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 = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
if(await button.isEnabled()) {
console.info('This button can be operated')
}
......@@ -802,7 +856,7 @@ async function demo() {
```
### isFocused
### isFocused<sup>9+</sup>
isFocused(): Promise\<boolean>
......@@ -812,16 +866,25 @@ isFocused(): Promise\<boolean>
**返回值：**
| 类型 | 说明 |
| -------------- | ----------------------------------- |
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\<boolean> | 以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 = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
if(await button.isFocused()) {
console.info('This button is focused')
}
......@@ -831,7 +894,7 @@ async function demo() {
}
```
### isSelected
### isSelected<sup>9+</sup>
isSelected(): Promise\<boolean>
......@@ -841,16 +904,25 @@ isSelected(): Promise\<boolean>
**返回值：**
| 类型 | 说明 |
| -------------- | -------------------- |
| 类型 | 说明 |
| ----------------- | ----------------------------------------------------- |
| Promise\<boolean> | 控件对象被选中的状态，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 = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('button'))
if(await button.isSelected()) {
console.info('This button is selected')
}
......@@ -860,7 +932,7 @@ async function demo() {
}
```
### inputText
### inputText<sup>9+</sup>
inputText(text: string): Promise\<void>
......@@ -874,12 +946,21 @@ inputText(text: string): Promise\<void>
| ------ | ------ | ---- | ---------------- |
| 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 = UiDriver.create()
let text = await driver.findComponent(BY.text('hello world'))
let driver = Driver.create()
let button = await driver.findComponent(ON.text('hello world'))
await text.inputText('123')
}
```
......@@ -892,19 +973,26 @@ clearText(): Promise\<void>
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let text = await driver.findComponent(BY.text('hello world'))
let driver = Driver.create()
let button = await driver.findComponent(ON.text('hello world'))
await text.clearText()
}
```
### scrollSearch
### scrollSearch<sup>9+</sup>
scrollSearch(by: By): Promise\<UiComponent>
scrollSearch(on: ON): Promise\<Component>
在控件上滑动查找目标控件(适用于List等支持滑动的控件)。
......@@ -912,23 +1000,32 @@ scrollSearch(by: By): Promise\<UiComponent>
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | -------------------- |
| by | [By](#by) | 是 | 目标控件的属性要求。 |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | 是 | 目标控件的属性要求。 |
**返回值：**
| 类型 | 说明 |
| ------------------------------------- | ------------------------------------- |
| Promise\<[UiComponent](#uicomponent)> | 以Promise形式返回找到的目标控件对象。 |
| 类型 | 说明 |
| ---------------------------------- | ------------------------------------- |
| 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 = UiDriver.create()
let scrollBar = await driver.findComponent(BY.type('Scroll'))
let button = await scrollBar.scrollSearch(BY.text('next page'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('Scroll'))
let button = await scrollBar.scrollSearch(ON.text('next page'))
}
```
......@@ -944,14 +1041,23 @@ scrollToTop(speed?: number): Promise\<void>
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| speed | number | 否 | 滑动速率，范围：200-3000，不在范围内设为默认值为600，单位：像素点/秒。 |
| 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 = UiDriver.create()
let scrollBar = await driver.findComponent(BY.type('Scroll'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('Scroll'))
await scrollBar.scrollToTop()
}
```
......@@ -968,21 +1074,30 @@ scrollToBottom(speed?: number): Promise\<void>
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| speed | number | 否 | 滑动速率，范围：200-3000，不在范围内设为默认值为600，单位：像素点/秒。 |
| 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 = UiDriver.create()
let scrollBar = await driver.findComponent(BY.type('Scroll'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('Scroll'))
await scrollBar.scrollToBottom()
}
```
### dragTo<sup>9+</sup>
dragTo(target: UiComponent): Promise\<void>
dragTo(target: Component): Promise\<void>
将控件拖拽至目标控件处。
......@@ -990,17 +1105,26 @@ dragTo(target: UiComponent): Promise\<void>
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------------------------- | ---- | ---------- |
| target | [UiComponent](#uicomponent) | 是 | 目标控件。 |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------------------------ | ---- | ---------- |
| 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 = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let text = await driver.findComponent(BY.text('hello world'))
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)
}
```
......@@ -1019,12 +1143,21 @@ pinchOut(scale: number): Promise\<void>
| ------ | ------ | ---- | ---------------- |
| 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 = UiDriver.create()
let image = await driver.findComponent(BY.type('image'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('image'))
await image.pinchOut(1.5)
}
```
......@@ -1043,121 +1176,162 @@ pinchIn(scale: number): Promise\<void>
| ------ | ------ | ---- | ---------------- |
| 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 = UiDriver.create()
let image = await driver.findComponent(BY.type('image'))
let driver = Driver.create()
let button = await driver.findComponent(ON.type('image'))
await image.pinchIn(0.5)
}
```
## UiDriver
## Driver<sup>9+</sup>
UiDriver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等API。
该类提供的方法除UiDriver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await调用。
UiTest框架在API9中，Driver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等API。
该类提供的方法除Driver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await调用。
### create
### create<sup>9+</sup>
static create(): UiDriver
static create(): Driver
静态方法，构造一个UiDriver对象，并返回该对象。
静态方法，构造一个Driver对象，并返回该对象。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| -------- | ------------------------ |
| UiDriver | 返回构造的UiDriver对象。 |
| 错误码ID | 错误码信息 |
| -------- | ---------------------- |
| Driver | 返回构造的Driver对象。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 类型 | 说明 |
| -------- | ------------------ |
| 17000001 | Initialize failed. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
}
```
### delayMs
### delayMs<sup>9+</sup>
delayMs(duration: number): Promise\<void>
UiDriver对象在给定的时间内延时。
Driver对象在给定的时间内延时。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ------------ |
| duration | number | 是 | 给定的时间。 |
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ---------------------- |
| duration | number | 是 | 给定的时间，单位：ms。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
await driver.delayMs(1000)
}
```
### findComponent
### findComponent<sup>9+</sup>
findComponent(by: By): Promise\<UiComponent>
findComponent(on: On): Promise\<Component>
在UiDriver对象中，根据给出的目标控件属性要求查找目标控件。
在Driver对象中，根据给出的目标控件属性要求查找目标控件。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | -------------------- |
| by | [By](#by) | 是 | 目标控件的属性要求。 |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | 是 | 目标控件的属性要求。 |
**返回值：**
| 类型 | 说明 |
| ------------------------------------- | --------------------------------- |
| Promise\<[UiComponent](#uicomponent)> | 以Promise形式返回找到的控件对象。 |
| 类型 | 说明 |
| ---------------------------------- | --------------------------------- |
| Promise\<[Component](#component9)> | 以Promise形式返回找到的控件对象。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.text('next page'))
let driver = Driver.create()
let button = await driver.findComponent(ON.text('next page'))
}
```
### findComponents
### findComponents<sup>9+</sup>
findComponents(by: By): Promise\<Array\<UiComponent>>
findComponents(on: On): Promise\<Array\<Component>>
在UiDriver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。
在Driver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | -------------------- |
| by | [By](#by) | 是 | 目标控件的属性要求。 |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------- | ---- | -------------------- |
| on | [On](#on9) | 是 | 目标控件的属性要求。 |
**返回值：**
| 类型 | 说明 |
| --------------------------------------------- | --------------------------------------- |
| Promise\<Array\<[UiComponent](#uicomponent)>> | 以Promise形式返回找到的控件对象的列表。 |
| 类型 | 说明 |
| ------------------------------------------ | --------------------------------------- |
| Promise\<Array\<[Component](#component9)>> | 以Promise形式返回找到的控件对象的列表。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let buttonList = await driver.findComponents(BY.text('next page'))
let driver = Driver.create()
let buttonList = await driver.findComponents(ON.text('next page'))
}
```
......@@ -1181,90 +1355,123 @@ findWindow(filter: WindowFilter): Promise\<UiWindow>
| -------------------------------- | ------------------------------------- |
| Promise\<[UiWindow](#uiwindow9)> | 以Promise形式返回找到的目标窗口对象。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
}
```
### waitForComponent<sup>9+</sup>
waitForComponent(by: By, time: number): Promise\<UiComponent>
waitForComponent(on: On, time: number): Promise\<Component>
在UiDriver对象中，在用户给定的时间内，持续查找满足控件属性要求的目标控件。
在Driver对象中，在用户给定的时间内，持续查找满足控件属性要求的目标控件。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | -------------------------------- |
| by | [By](#by) | 是 | 目标控件的属性要求。 |
| time | number | 是 | 查找目标控件的持续时间。单位ms。 |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------- | ---- | -------------------------------- |
| On | [On](#on9) | 是 | 目标控件的属性要求。 |
| time | number | 是 | 查找目标控件的持续时间。单位ms。 |
**返回值：**
| 类型 | 说明 |
| ------------------------------------- | --------------------------------- |
| Promise\<[UiComponent](#uicomponent)> | 以Promise形式返回找到的控件对象。 |
| 类型 | 说明 |
| --------------------------------- | --------------------------------- |
| Promise\<[Component](#component)> | 以Promise形式返回找到的控件对象。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.waitForComponent(BY.text('next page'),500)
let driver = Driver.create()
let button = await driver.waitForComponent(ON.text('next page'),500)
}
```
### assertComponentExist
### assertComponentExist<sup>9+</sup>
assertComponentExist(by: By): Promise\<void>
assertComponentExist(on: On): Promise\<void>
断言API，用于断言当前界面存在满足给出的目标控件属性的控件; 如果控件不存在，该API将抛出JS异常，使当前测试用例失败。
断言API，用于断言当前界面存在满足给出的目标控件属性的控件。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | -------------------- |
| by | [By](#by) | 是 | 目标控件的属性要求。 |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------- | ---- | -------------------- |
| 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 = UiDriver.create()
await driver.assertComponentExist(BY.text('next page'))
let driver = Driver.create()
await driver.assertComponentExist(ON.text('next page'))
}
```
### pressBack
### pressBack<sup>9+</sup>
pressBack(): Promise\<void>
UiDriver对象进行点击BACK键的操作。
Driver对象进行点击BACK键的操作。
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
await driver.pressBack()
}
```
### triggerKey
### triggerKey<sup>9+</sup>
triggerKey(keyCode: number): Promise\<void>
UiDriver对象采取如下操作：通过key值找到对应键并点击。
Driver对象采取如下操作：通过key值找到对应键并点击。
**系统能力**：SystemCapability.Test.UiTest
......@@ -1274,11 +1481,19 @@ UiDriver对象采取如下操作：通过key值找到对应键并点击。
| ------- | ------ | ---- | ------------- |
| keyCode | number | 是 | 指定的key值。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
await driver.triggerKey(123)
}
```
......@@ -1287,33 +1502,41 @@ async function demo() {
triggerCombineKeys(key0: number, key1: number, key2?: number): Promise\<void>
UiDriver对象通过给定的key值，找到对应组合键并点击。例如，Key值为(2072, 2019)时，UiDriver对象找到组合键并点击ctrl+c。
Driver对象通过给定的key值，找到对应组合键并点击。例如，Key值为(2072, 2019)时，Driver对象找到组合键并点击ctrl+c。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------ | ---- | ------------------- |
| key0 | number | 是 | 指定的第一个key值。 |
| key1 | number | 是 | 指定的第二个key值。 |
| key2 | number | 否 | 指定的第三个key值。 |
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------- |
| 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 = UiDriver.create()
let driver = Driver.create()
await driver.triggerCombineKeys(2072, 2047, 2035)
}
```
### click
### click<sup>9+</sup>
click(x: number, y: number): Promise\<void>
UiDriver对象采取如下操作：在目标坐标点单击。
Driver对象采取如下操作：在目标坐标点单击。
**系统能力**：SystemCapability.Test.UiTest
......@@ -1324,20 +1547,28 @@ UiDriver对象采取如下操作：在目标坐标点单击。
| 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 = UiDriver.create()
let driver = Driver.create()
await driver.click(100,100)
}
```
### doubleClick
### doubleClick<sup>9+</sup>
doubleClick(x: number, y: number): Promise\<void>
UiDriver对象采取如下操作：在目标坐标点双击。
Driver对象采取如下操作：在目标坐标点双击。
**系统能力**：SystemCapability.Test.UiTest
......@@ -1348,20 +1579,28 @@ UiDriver对象采取如下操作：在目标坐标点双击。
| 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 = UiDriver.create()
let driver = Driver.create()
await driver.doubleClick(100,100)
}
```
### longClick
### longClick<sup>9+</sup>
longClick(x: number, y: number): Promise\<void>
UiDriver对象采取如下操作：在目标坐标点长按下鼠标左键。
Driver对象采取如下操作：在目标坐标点长按下。
**系统能力**：SystemCapability.Test.UiTest
......@@ -1372,11 +1611,19 @@ UiDriver对象采取如下操作：在目标坐标点长按下鼠标左键。
| 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 = UiDriver.create()
let driver = Driver.create()
await driver.longClick(100,100)
}
```
......@@ -1385,7 +1632,7 @@ async function demo() {
swipe(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\<void>
UiDriver对象采取如下操作：从给出的起始坐标点滑向给出的目的坐标点。
Driver对象采取如下操作：从给出的起始坐标点滑向给出的目的坐标点。
**系统能力**：SystemCapability.Test.UiTest
......@@ -1397,13 +1644,21 @@ UiDriver对象采取如下操作：从给出的起始坐标点滑向给出的目
| starty | number | 是 | 以number的形式传入起始点的纵坐标信息。 |
| endx | number | 是 | 以number的形式传入目的点的横坐标信息。 |
| endy | number | 是 | 以number的形式传入目的点的纵坐标信息。 |
| speed | number | 否 | 滑动速率，范围：200-3000，不在范围内设为默认值为600，单位：像素点/秒。 |
| speed | number | 否 | 滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
await driver.swipe(100,100,200,200,600)
}
```
......@@ -1412,7 +1667,7 @@ async function demo() {
drag(startx: number, starty: number, endx: number, endy: number, speed?: number): Promise\<void>
UiDriver对象采取如下操作：从给出的起始坐标点拖拽至给出的目的坐标点。
Driver对象采取如下操作：从给出的起始坐标点拖拽至给出的目的坐标点。
**系统能力**：SystemCapability.Test.UiTest
......@@ -1424,22 +1679,30 @@ UiDriver对象采取如下操作：从给出的起始坐标点拖拽至给出的
| starty | number | 是 | 以number的形式传入起始点的纵坐标信息。 |
| endx | number | 是 | 以number的形式传入目的点的横坐标信息。 |
| endy | number | 是 | 以number的形式传入目的点的纵坐标信息。 |
| speed | number | 否 | 滑动速率，范围：200-3000，不在范围内设为默认值为600，单位：像素点/秒。 |
| speed | number | 否 | 滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
await driver.drag(100,100,200,200,600)
}
```
### screenCap
### screenCap<sup>9+</sup>
screenCap(savePath: string): Promise\<boolean>
UiDriver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。
Driver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。
**系统能力**：SystemCapability.Test.UiTest
......@@ -1451,15 +1714,23 @@ UiDriver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的
**返回值：**
| 类型 | 说明 |
| -------------- | -------------------------------------- |
| 类型 | 说明 |
| ----------------- | -------------------------------------- |
| Promise\<boolean> | 截图操作是否成功完成。成功完成为true。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
await driver.screenCap('/local/tmp/')
}
```
......@@ -1478,11 +1749,19 @@ setDisplayRotation(rotation: DisplayRotation): Promise\<void>
| -------- | ------------------------------------ | ---- | ---------------- |
| rotation | [DisplayRotation](#displayrotation9) | 是 | 设备的显示方向。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
await driver.setDisplayRotation(DisplayRotation.ROTATION_180)
}
```
......@@ -1501,11 +1780,19 @@ getDisplayRotation(): Promise\<DisplayRotation>
| ---------------------------------------------- | --------------------------------------- |
| Promise\<[DisplayRotation](#displayrotation9)> | 以Promise的形式返回当前设备的显示方向。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
let rotation = await driver.getDisplayRotation()
}
```
......@@ -1520,15 +1807,23 @@ setDisplayRotationEnabled(enabled: boolean): Promise\<void>
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ---- | ---- | -------------------- |
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------- | ---- | ------------------------------------------------------- |
| enabled | boolean | 是 | 能否旋转屏幕的标识，true：可以旋转，false：不可以旋转。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
await driver.setDisplayRotationEnabled(false)
}
```
......@@ -1547,11 +1842,19 @@ getDisplaySize(): Promise\<Point>
| -------------------------- | --------------------------------------- |
| Promise\<[Point](#point9)> | 以Promise的形式返回当前设备的屏幕大小。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
let size = await driver.getDisplaySize()
}
```
......@@ -1570,11 +1873,19 @@ getDisplayDensity(): Promise\<Point>
| -------------------------- | ------------------------------------------- |
| Promise\<[Point](#point9)> | 以Promise的形式返回当前设备的屏幕的分辨率。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
let density = await driver.getDisplayDensity()
}
```
......@@ -1587,11 +1898,19 @@ wakeUpDisplay(): Promise\<void>
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
await driver.wakeUpDisplay()
}
```
......@@ -1604,11 +1923,19 @@ pressHome(): Promise\<void>
**系统能力**：SystemCapability.Test.UiTest
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
await driver.pressHome()
}
```
......@@ -1630,15 +1957,23 @@ waitForIdle(idleTime: number, timeout: number): Promise\<boolean>
**返回值：**
| 类型 | 说明 |
| -------------- | --------------------------------------------------- |
| 类型 | 说明 |
| ----------------- | --------------------------------------------------- |
| Promise\<boolean> | 以Promise的形式返回当前界面的所有控件是否已经空闲。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
let idled = await driver.waitForIdle(4000,5000)
}
```
......@@ -1656,15 +1991,23 @@ fling(from: Point, to: Point, stepLen: number, speed: number): Promise\<void>
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ---------------- | ---- | ------------------------------------------------------------ |
| from | [Point](#point9) | 是 | 手指接触屏幕的起始点坐标。 |
| to | [Point](#point9) | 是 | 手指离开屏幕时的坐标点。 |
| to | [Point](#point9) | 是 | 手指离开屏幕时的坐标点。 |
| stepLen | number | 是 | 间隔距离，单位：像素点。 |
| speed | number | 是 | 滑动速率，范围：200-3000，不在范围内设为默认值为600，单位：像素点/秒。 |
| speed | number | 是 | 滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
await driver.fling({X: 500, Y: 480},{X: 450, Y: 480},5,600)
}
```
......@@ -1682,14 +2025,22 @@ injectMultiPointerAction(pointers: PointerMatrix, speed?: number): Promise\<bool
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------------- | ---- | ------------------------------------------------------------ |
| pointers | [PointerMatrix](#pointermatrix9) | 是 | 起始点的坐标。 |
| speed | number | 否 | 滑动速率，范围：200-3000，不在范围内设为默认值为600，单位：像素点/秒。 |
| speed | number | 否 | 滑动速率，范围：200-15000，不在范围内设为默认值为600，单位：像素点/秒。 |
**返回值：**
| 类型 | 说明 |
| -------------- | ----------------------------------------- |
| 类型 | 说明 |
| ----------------- | ----------------------------------------- |
| Promise\<boolean> | 以Promise的形式返回植入操作是否成功完成。 |
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 错误码ID | 错误码信息 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
**示例：**
```js
......@@ -1705,23 +2056,73 @@ async function demo() {
}
```
## UiWindow<sup>9+</sup>
## PointerMatrix<sup>9+</sup>
UiTest中，UiWindow类代表了UI界面上的一个窗口，提供窗口属性获取，窗口拖动、调整窗口大小等API。
该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。
表示存储多指操作中每根手指每一步动作的坐标点及其行为的二维数组。
### create<sup>9+</sup>
### WindowFilter<sup>9+</sup>
static create(fingers: number, steps: number): PointerMatrix
窗口的标志属性信息。
静态方法，构造一个PointerMatrix对象，并返回该对象。
**系统能力**：SystemCapability.Test.UiTest
| 名称 | 参数类型 | 必填 | 可读 | 可写 | 描述 |
| ---------- | -------- | ---- | ---- | ---- | -------------------------- |
| bundleName | string | 否 | 是 | 否 | 窗口对应的包名。 |
| title | string | 否 | 是 | 否 | 窗口的标题。 |
| focused | boolean | 否 | 是 | 否 | 窗口是否获焦。 |
| actived | boolean | 否 | 是 | 否 | 窗口是否正与用户进行交互。 |
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------ | ---- | ------------------------------------------ |
| fingers | number | 是 | 多指操作中注入的手指数，取值范围：[1,10]。 |
| steps | number | 是 | 每根手指操作的步骤数，取值范围：[1,1000]。 |
**返回值：**
| 类型 | 说明 |
| -------------------------------- | ----------------------------- |
| [PointerMatrix](#pointermatrix9) | 返回构造的PointerMatrix对象。 |
**示例：**
```js
async function demo() {
let pointerMatrix = PointerMatrix.create(2,3)
}
```
### setPoint<sup>9+</sup>
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})
}
```
## UiWindow<sup>9+</sup>
UiTest中，UiWindow类代表了UI界面上的一个窗口，提供窗口属性获取，窗口拖动、调整窗口大小等API。
该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。
### getBundleName<sup>9+</sup>
......@@ -1737,11 +2138,20 @@ getBundleName(): Promise\<string>
| ---------------- | --------------------------------- |
| Promise\<string> | 以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 = UiDriver.create()
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
let name = await window.getBundleName()
}
......@@ -1761,11 +2171,20 @@ getBounds(): Promise\<Rect>
| ------------------------ | --------------------------------- |
| 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 = UiDriver.create()
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
let rect = await window.getBounds()
}
......@@ -1785,11 +2204,20 @@ getTitle(): Promise\<string>
| ---------------- | --------------------------------- |
| Promise\<string> | 以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 = UiDriver.create()
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
let rect = await window.getTitle()
}
......@@ -1805,15 +2233,24 @@ getWindowMode(): Promise\<WindowMode>
**返回值：**
| 类型 | 说明 |
| ------------------------------------------------ | ------------------------------------- |
| 类型 | 说明 |
| ------------------------------------ | ------------------------------------- |
| 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 = UiDriver.create()
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
let mode = await window.getWindowMode()
}
......@@ -1829,15 +2266,24 @@ isFocused(): Promise\<boolean>
**返回值：**
| 类型 | 说明 |
| -------------- | ----------------------------------- |
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\<boolean> | 以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 = UiDriver.create()
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
let focused = await window.isFocused()
}
......@@ -1853,15 +2299,24 @@ isActived(): Promise\<boolean>
**返回值：**
| 类型 | 说明 |
| -------------- | --------------------------------------------- |
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\<boolean> | 以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 = UiDriver.create()
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
let focused = await window.isActived()
}
......@@ -1869,23 +2324,26 @@ async function demo() {
### focus<sup>9+</sup>
focus(): Promise\<boolean>
focus(): Promise\<void>
让窗口获焦。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
**错误码：**
| 类型 | 说明 |
| -------------- | ----------------------------------- |
| Promise\<boolean> | 以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 = UiDriver.create()
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.focus()
}
......@@ -1893,7 +2351,7 @@ async function demo() {
### moveTo<sup>9+</sup>
moveTo(x: number, y: number): Promise\<boolean>
moveTo(x: number, y: number): Promise\<void>
将窗口移动到目标点。适用于支持移动的窗口。
......@@ -1906,17 +2364,21 @@ moveTo(x: number, y: number): Promise\<boolean>
| x | number | 是 | 以number的形式传入目标点的横坐标信息。 |
| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 |
**返回值：**
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 类型 | 说明 |
| -------------- | ----------------------------------- |
| Promise\<boolean> | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 |
| 错误码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 = UiDriver.create()
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.moveTo(100, 100)
}
......@@ -1924,7 +2386,7 @@ async function demo() {
### resize<sup>9+</sup>
resize(wide: number, height: number, direction: ResizeDirection): Promise\<boolean>
resize(wide: number, height: number, direction: ResizeDirection): Promise\<void>
根据传入的宽、高和调整方向来调整窗口的大小。适用于支持大小调整的窗口。
......@@ -1932,23 +2394,27 @@ resize(wide: number, height: number, direction: ResizeDirection): Promise\<boole
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ |
| wide | number | 是 | 以number的形式传入调整后窗口的宽度。 |
| height | number | 是 | 以number的形式传入调整后窗口的高度。 |
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------------------------------------ | ---- | ------------------------------------------------------------ |
| wide | number | 是 | 以number的形式传入调整后窗口的宽度。 |
| height | number | 是 | 以number的形式传入调整后窗口的高度。 |
| direction | [ResizeDirection](#resizedirection9) | 是 | 以[ResizeDirection](#resizedirection9)的形式传入窗口调整的方向。 |
**返回值：**
**错误码：**
| 类型 | 说明 |
| -------------- | ----------------------------------- |
| Promise\<boolean> | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 |
以下错误码的详细介绍请参见[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 = UiDriver.create()
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.resize(100, 100, ResizeDirection.LEFT)
}
......@@ -1956,23 +2422,27 @@ async function demo() {
### split<sup>9+</sup>
split(): Promise\<boolean>
split(): Promise\<void>
将窗口模式切换成分屏模式。适用于支持切屏操作的窗口。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 类型 | 说明 |
| -------------- | ----------------------------------- |
| Promise\<boolean> | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 |
| 类型 | 说明 |
| -------- | ---------------------------------------- |
| 17000002 | API does not allow calling concurrently. |
| 17000004 | Component lost/UiWindow lost. |
| 17000005 | This operation is not supported. |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.split()
}
......@@ -1980,23 +2450,27 @@ async function demo() {
### maximize<sup>9+</sup>
maximize(): Promise\<boolean>
maximize(): Promise\<void>
将窗口最大化。适用于支持窗口最大化操作的窗口。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
**错误码：**
| 类型 | 说明 |
| -------------- | ----------------------------------- |
| Promise\<boolean> | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 |
以下错误码的详细介绍请参见[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 = UiDriver.create()
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.maximize()
}
......@@ -2004,23 +2478,27 @@ async function demo() {
### minimize<sup>9+</sup>
minimize(): Promise\<boolean>
minimize(): Promise\<void>
将窗口最小化。适用于支持窗口最小化操作的窗口。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 类型 | 说明 |
| -------------- | ----------------------------------- |
| Promise\<boolean> | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 |
| 错误码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 = UiDriver.create()
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.minimize()
}
......@@ -2028,23 +2506,27 @@ async function demo() {
### resume<sup>9+</sup>
resume(): Promise\<boolean>
resume(): Promise\<void>
将窗口恢复到之前的窗口模式。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
**错误码：**
| 类型 | 说明 |
| -------------- | ----------------------------------- |
| Promise\<boolean> | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 |
以下错误码的详细介绍请参见[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 = UiDriver.create()
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.resume()
}
......@@ -2052,93 +2534,32 @@ async function demo() {
### close<sup>9+</sup>
close(): Promise\<boolean>
close(): Promise\<void>
将窗口关闭。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
**错误码：**
以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。
| 类型 | 说明 |
| -------------- | ----------------------------------- |
| Promise\<boolean> | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 |
| 错误码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 = UiDriver.create()
let driver = Driver.create()
let window = await driver.findWindow({actived: true})
await window.close()
}
```
## PointerMatrix<sup>9+</sup>
表示存储多指操作中每根手指每一步动作的坐标点及其行为的二维数组。
### create<sup>9+</sup>
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)
}
```
### setPoint<sup>9+</sup>
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})
}
```
###
## MatchPattern
控件属性支持的匹配模式。
......@@ -2169,6 +2590,30 @@ async function demo() {
| RIGHT_UP | 右上方。 |
| RIGHT_DOWN | 右下方。 |
## Point<sup>9+</sup>
坐标点信息。
**系统能力**：SystemCapability.Test.UiTest
| 名称 | 参数类型 | 可读 | 可写 | 描述 |
| ---- | -------- | ---- | ---- | ---------------- |
| X | number | 是 | 否 | 坐标点的横坐标。 |
| Y | number | 是 | 否 | 坐标点的纵坐标。 |
## Rect<sup>9+</sup>
控件的边框信息。
**系统能力**：SystemCapability.Test.UiTest
| 名称 | 参数类型 | 可读 | 可写 | 描述 |
| ------- | -------- | ---- | ---- | ------------------------- |
| leftX | number | 是 | 否 | 控件边框的左上角的X坐标。 |
| topY | number | 是 | 否 | 控件边框的左上角的Y坐标。 |
| rightX | number | 是 | 否 | 控件边框的右下角的X坐标。 |
| bottomY | number | 是 | 否 | 控件边框的右下角的Y坐标。 |
## WindowMode<sup>9+</sup>
**系统能力**：SystemCapability.Test.UiTest
......@@ -2194,3 +2639,1052 @@ async function demo() {
| ROTATION_90 | 设备显示器顺时针旋转90°，水平显示。 |
| ROTATION_180 | 设备显示器顺时针旋转180°，逆向垂直显示。 |
| ROTATION_270 | 设备显示器顺时针旋转270°，逆向水平显示。 |
## WindowFilter<sup>9+</sup>
窗口的标志属性信息。
**系统能力**：SystemCapability.Test.UiTest
| 名称 | 参数类型 | 必填 | 可读 | 可写 | 描述 |
| ---------- | -------- | ---- | ---- | ---- | -------------------------- |
| bundleName | string | 否 | 是 | 否 | 窗口对应的包名。 |
| title | string | 否 | 是 | 否 | 窗口的标题。 |
| focused | boolean | 否 | 是 | 否 | 窗口是否获焦。 |
| actived | boolean | 否 | 是 | 否 | 窗口是否正与用户进行交互。 |
## By<sup>(deprecated)</sup>
UiTest框架通过By类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。<br>
By提供的API能力具有以下几个特点:<br>1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。<br>2、控件属性支持多种匹配模式。<br>3、支持控件绝对定位，相对定位，可通过[By.isBefore](#isbefore)和[By.isAfter](#isafter)等API限定邻近控件特征进行辅助定位。<br>By类提供的所有API均为同步接口，建议使用者通过静态构造器BY来链式创建By对象。
从API version9开始不再维护，建议使用[On<sup>9+</sup>](#on9)。
```js
BY.text('123').type('button')
```
### text<sup>(deprecated)</sup>
text(txt: string, pattern?: MatchPattern): By
指定目标控件文本属性，支持多种匹配模式，返回By对象自身。
从API version9开始不再维护，建议使用[text<sup>9+</sup>](#text9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ----------------------------- | ---- | --------------------------------------------------- |
| txt | string | 是 | 指定控件文本，用于匹配目标控件文本。 |
| pattern | [MatchPattern](#matchpattern) | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------- |
| [By](#by) | 返回指定目标控件文本属性的By对象。 |
**示例：**
```js
let by = BY.text('123') //使用静态构造器BY创建by对象，指定目标控件的text属性。
```
### key<sup>(deprecated)</sup>
key(key: string): By
指定目标控件key值属性，返回By对象自身。
从API version9开始不再维护，建议使用[id<sup>9+</sup>](#id9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ----------------- |
| key | string | 是 | 指定控件的Key值。 |
**返回值：**
| 类型 | 说明 |
| --------- | ----------------------------------- |
| [By](#by) | 返回指定目标控件key值属性的By对象。 |
**示例：**
```js
let by = BY.key('123') //使用静态构造器BY创建by对象，指定目标控件的key值属性。
```
### id<sup>(deprecated)</sup>
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<sup>(deprecated)</sup>
type(tp: string): By
指定目标控件的控件类型属性，返回By对象自身。
从API version9开始不再维护，建议使用[type<sup>9+</sup>](#type9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------------- |
| tp | string | 是 | 指定控件类型。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------- |
| [By](#by) | 返回指定目标控件的控件类型属性的By对象。 |
**示例：**
```js
let by = BY.type('button') //使用静态构造器BY创建by对象，指定目标控件的控件类型属性。
```
### clickable<sup>(deprecated)</sup>
clickable(b?: boolean): By
指定目标控件的可点击状态属性，返回By对象自身。
从API version9开始不再维护，建议使用[clickable<sup>9+</sup>](#clickable9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | 否 | 指定控件可点击状态，true：可点击，false：不可点击。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ------------------------------------------ |
| [By](#by) | 返回指定目标控件的可点击状态属性的By对象。 |
**示例：**
```js
let by = BY.clickable(true) //使用静态构造器BY创建by对象，指定目标控件的可点击状态属性。
```
### scrollable<sup>(deprecated)</sup>
scrollable(b?: boolean): By
指定目标控件的可滑动状态属性，返回By对象自身。
从API version9开始不再维护，建议使用[scrollable<sup>9+</sup>](#scrollable9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ----------------------------------------------------------- |
| b | boolean | 否 | 控件可滑动状态，true：可滑动，false：不可滑动。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ------------------------------------------ |
| [By](#by) | 返回指定目标控件的可滑动状态属性的By对象。 |
**示例：**
```js
let by = BY.scrollable(true) //使用静态构造器BY创建by对象，指定目标控件的可滑动状态属性。
```
### enabled<sup>(deprecated)</sup>
enabled(b?: boolean): By
指定目标控件的使能状态属性，返回By对象自身。
从API version9开始不再维护，建议使用[enabled<sup>9+</sup>](#enabled9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | --------------------------------------------------------- |
| b | boolean | 否 | 指定控件使能状态，true：使能，false：未使能。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------- |
| [By](#by) | 返回指定目标控件的使能状态属性的By对象。 |
**示例：**
```js
let by = BY.enabled(true) //使用静态构造器BY创建by对象，指定目标控件的使能状态属性。
```
### focused<sup>(deprecated)</sup>
focused(b?: boolean): By
指定目标控件的获焦状态属性，返回By对象自身。
从API version9开始不再维护，建议使用[focused<sup>9+</sup>](#focused9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ----------------------------------------------------- |
| b | boolean | 否 | 控件获焦状态，true：获焦，false：未获焦。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------- |
| [By](#by) | 返回指定目标控件的获焦状态属性的By对象。 |
**示例：**
```js
let by = BY.focused(true) //使用静态构造器BY创建by对象，指定目标控件的获焦状态属性。
```
### selected<sup>(deprecated)</sup>
selected(b?: boolean): By
指定目标控件的被选中状态属性，返回By对象自身。
从API version9开始不再维护，建议使用[selected<sup>9+</sup>](#selected9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| b | boolean | 否 | 指定控件被选中状态，true：被选中，false：未被选中。默认为true。 |
**返回值：**
| 类型 | 说明 |
| --------- | ------------------------------------------ |
| [By](#by) | 返回指定目标控件的被选中状态属性的By对象。 |
**示例：**
```js
let by = BY.selected(true) //使用静态构造器BY创建by对象，指定目标控件的被选中状态属性。
```
### isBefore<sup>(deprecated)</sup>
isBefore(by: By): By
指定目标控件位于给出的特征属性控件之前，返回By对象自身。
从API version9开始不再维护，建议使用[isBefore<sup>9+</sup>](#isbefore9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | ---------------- |
| by | [By](#by) | 是 | 特征控件的属性。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------------------- |
| [By](#by) | 返回指定目标控件位于给出的特征属性控件之前的By对象。 |
**示例：**
```js
let by = BY.isBefore(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之前。
```
### isAfter<sup>(deprecated)</sup>
isAfter(by: By): By
指定目标控件位于给出的特征属性控件之后，返回By对象自身。
从API version9开始不再维护，建议使用[isAfter<sup>9+</sup>](#isafter9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | ---------------- |
| by | [By](#by) | 是 | 特征控件的属性。 |
**返回值：**
| 类型 | 说明 |
| --------- | ---------------------------------------------------- |
| [By](#by) | 返回指定目标控件位于给出的特征属性控件之后的By对象。 |
**示例：**
```js
let by = BY.isAfter(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之后。
```
## UiComponent<sup>(deprecated)</sup>
UiTest中，UiComponent类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。
该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。
从API version9开始不再维护，建议使用[Component<sup>9+</sup>](#component9)。
### click<sup>(deprecated)</sup>
click(): Promise\<void>
控件对象进行点击操作。
从API version9开始不再维护，建议使用[click<sup>9+</sup>](#click9)。
**系统能力**：SystemCapability.Test.UiTest
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
await button.click()
}
```
### doubleClick<sup>(deprecated)</sup>
doubleClick(): Promise\<void>
控件对象进行双击操作。
从API version9开始不再维护，建议使用[doubleClick<sup>9+</sup>](#doubleclick9)。
**系统能力**：SystemCapability.Test.UiTest
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
await button.doubleClick()
}
```
### longClick<sup>(deprecated)</sup>
longClick(): Promise\<void>
控件对象进行长按操作。
从API version9开始不再维护，建议使用[longClick<sup>9+</sup>](#longclick9)。
**系统能力**：SystemCapability.Test.UiTest
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
await button.longClick()
}
```
### getId<sup>(deprecated)</sup>
getId(): Promise\<number>
获取控件对象的id值。
从API version9开始不再维护，建议使用[getId<sup>9+</sup>](#getid9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ---------------- | ------------------------------- |
| Promise\<number> | 以Promise形式返回的控件的id值。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let num = await button.getId()
}
```
### getKey<sup>(deprecated)</sup>
getKey(): Promise\<string>
获取控件对象的key值。
从API version9开始不再维护，被废弃。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ---------------- | ------------------------------ |
| Promise\<string> | 以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<sup>(deprecated)</sup>
getText(): Promise\<string>
获取控件对象的文本信息。
从API version9开始不再维护，建议使用[getText<sup>9+</sup>](#gettext9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ---------------- | --------------------------------- |
| Promise\<string> | 以Promise形式返回控件的文本信息。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let text = await button.getText()
}
```
### getType<sup>(deprecated)</sup>
getType(): Promise\<string>
获取控件对象的控件类型。
从API version9开始不再维护，建议使用[getType<sup>9+</sup>](#gettype9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ---------------- | ----------------------------- |
| Promise\<string> | 以Promise形式返回控件的类型。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let button = await driver.findComponent(BY.type('button'))
let type = await button.getType()
}
```
### isClickable<sup>(deprecated)</sup>
isClickable(): Promise\<boolean>
获取控件对象可点击状态。
从API version9开始不再维护，建议使用[isClickable<sup>9+</sup>](#isclickable9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\<boolean> | 以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<sup>(deprecated)</sup>
isScrollable(): Promise\<boolean>
获取控件对象可滑动状态。
从API version9开始不再维护，建议使用[isScrollable<sup>9+</sup>](#isscrollable9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\<boolean> | 以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<sup>(deprecated)</sup>
isEnabled(): Promise\<boolean>
获取控件使能状态。
从API version9开始不再维护，建议使用[isEnabled<sup>9+</sup>](#isenabled9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ---------------------------------------------------------- |
| Promise\<boolean> | 以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<sup>(deprecated)</sup>
isFocused(): Promise\<boolean>
判断控件对象是否获焦。
从API version9开始不再维护，建议使用[isFocused<sup>9+</sup>](#isfocused9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise\<boolean> | 以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<sup>(deprecated)</sup>
isSelected(): Promise\<boolean>
获取控件对象被选中状态。
从API version9开始不再维护，建议使用[isSelected<sup>9+</sup>](#isselected9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| ----------------- | ----------------------------------------------------- |
| Promise\<boolean> | 控件对象被选中的状态，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<sup>(deprecated)</sup>
inputText(text: string): Promise\<void>
向控件中输入文本(适用于文本框控件)。
从API version9开始不再维护，建议使用[inputText<sup>9+</sup>](#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<sup>(deprecated)</sup>
scrollSearch(by: By): Promise\<UiComponent>
在控件上滑动查找目标控件(适用于List等支持滑动的控件)。
从API version9开始不再维护，建议使用[scrollSearch<sup>9+</sup>](#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<sup>(deprecated)</sup>
UiDriver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等API。
该类提供的方法除UiDriver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await调用。
从API version9开始不再维护，建议使用[Driver<sup>9+</sup>](#driver9)。
### create<sup>(deprecated)</sup>
static create(): UiDriver
静态方法，构造一个UiDriver对象，并返回该对象。
从API version9开始不再维护，建议使用[create<sup>9+</sup>](#create9)。
**系统能力**：SystemCapability.Test.UiTest
**返回值：**
| 类型 | 说明 |
| -------- | ------------------------ |
| UiDriver | 返回构造的UiDriver对象。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
}
```
### delayMs<sup>(deprecated)</sup>
delayMs(duration: number): Promise\<void>
UiDriver对象在给定的时间内延时。
从API version9开始不再维护，建议使用[delayMs<sup>9+</sup>](#delayms9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ------------ |
| duration | number | 是 | 给定的时间。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.delayMs(1000)
}
```
### findComponent<sup>(deprecated)</sup>
findComponent(by: By): Promise\<UiComponent>
在UiDriver对象中，根据给出的目标控件属性要求查找目标控件。
从API version9开始不再维护，建议使用[findComponent<sup>9+</sup>](#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<sup>(deprecated)</sup>
findComponents(by: By): Promise\<Array\<UiComponent>>
在UiDriver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。
从API version9开始不再维护，建议使用[findComponents<sup>9+</sup>](#findcomponents9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | -------------------- |
| by | [By](#by) | 是 | 目标控件的属性要求。 |
**返回值：**
| 类型 | 说明 |
| --------------------------------------------- | --------------------------------------- |
| Promise\<Array\<[UiComponent](#uicomponent)>> | 以Promise形式返回找到的控件对象的列表。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
let buttonList = await driver.findComponents(BY.text('next page'))
}
```
### assertComponentExist<sup>(deprecated)</sup>
assertComponentExist(by: By): Promise\<void>
断言API，用于断言当前界面存在满足给出的目标控件属性的控件; 如果控件不存在，该API将抛出JS异常，使当前测试用例失败。
从API version9开始不再维护，建议使用[assertComponentExist<sup>9+</sup>](#assertcomponentexist9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | --------- | ---- | -------------------- |
| by | [By](#by) | 是 | 目标控件的属性要求。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.assertComponentExist(BY.text('next page'))
}
```
### pressBack<sup>(deprecated)</sup>
pressBack(): Promise\<void>
UiDriver对象进行点击BACK键的操作。
从API version9开始不再维护，建议使用[pressBack<sup>9+</sup>](#pressback9)。
**系统能力**：SystemCapability.Test.UiTest
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.pressBack()
}
```
### triggerKey<sup>(deprecated)</sup>
triggerKey(keyCode: number): Promise\<void>
UiDriver对象采取如下操作：通过key值找到对应键并点击。
从API version9开始不再维护，建议使用[triggerKey<sup>9+</sup>](#triggerkey9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------ | ---- | ------------- |
| keyCode | number | 是 | 指定的key值。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.triggerKey(123)
}
```
### click<sup>(deprecated)</sup>
click(x: number, y: number): Promise\<void>
UiDriver对象采取如下操作：在目标坐标点单击。
从API version9开始不再维护，建议使用[click<sup>9+</sup>](#click9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | 是 | 以number的形式传入目标点的横坐标信息。 |
| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.click(100,100)
}
```
### doubleClick<sup>(deprecated)</sup>
doubleClick(x: number, y: number): Promise\<void>
UiDriver对象采取如下操作：在目标坐标点双击。
从API version9开始不再维护，建议使用[doubleClick<sup>9+</sup>](#doubleclick9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | 是 | 以number的形式传入目标点的横坐标信息。 |
| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.doubleClick(100,100)
}
```
### longClick<sup>(deprecated)</sup>
longClick(x: number, y: number): Promise\<void>
UiDriver对象采取如下操作：在目标坐标点长按下鼠标左键。
从API version9开始不再维护，建议使用[longClick<sup>9+</sup>](#longclick9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | -------------------------------------- |
| x | number | 是 | 以number的形式传入目标点的横坐标信息。 |
| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.longClick(100,100)
}
```
### swipe<sup>(deprecated)</sup>
swipe(startx: number, starty: number, endx: number, endy: number): Promise\<void>
UiDriver对象采取如下操作：从给出的起始坐标点滑向给出的目的坐标点。
从API version9开始不再维护，建议使用[swipe<sup>9+</sup>](#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<sup>(deprecated)</sup>
screenCap(savePath: string): Promise\<boolean>
UiDriver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。
从API version9开始不再维护，建议使用[screenCap<sup>9+</sup>](#screencap9)。
**系统能力**：SystemCapability.Test.UiTest
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | -------------- |
| savePath | string | 是 | 文件保存路径。 |
**返回值：**
| 类型 | 说明 |
| ----------------- | -------------------------------------- |
| Promise\<boolean> | 截图操作是否成功完成。成功完成为true。 |
**示例：**
```js
async function demo() {
let driver = UiDriver.create()
await driver.screenCap('/local/tmp/')
}
```
zh-cn/application-dev/reference/errorcodes/errorcode-huks.md 0 → 100644
浏览文件 @ d5332ef7
# huks错误码
## 12000001 该子功能不支持（特性）
**错误信息**
``${messageInfo}`` mode is not support in current device.
**可能原因**
支持API，但是不支持API内部某些子特性（功能），如算法参数。
**处理步骤**
调整API参数，使用可替代可支持的参数。
## 12000002 缺少密钥算法参数
**错误信息**
Check get ``${messageInfo}`` failed. User should add ``${messageInfo}`` in param set.
**可能原因**
使用密钥时缺少相关参数。
**处理步骤**
1. 查看errorMessage确认缺少的密钥参数。
2. 添加对应的正确的密钥参数。
## 12000003 无效的密钥算法参数
**错误信息**
``${messageInfo}`` argument is invalid. User should make sure using the correct value.
**可能原因**
使用密钥时无效相关参数。
**处理步骤**
1. 查看errorMessage确认无效的的密钥参数名。
2. 修改对应的密钥参数。
## 12000004 文件错误
**错误信息**
Read file failed. or Write file failed.
**可能原因**
文件操作错误。
**处理步骤**
1. 查看是否磁盘空间已经写满、文件系统是否有其他异常。
2. 清理磁盘。
## 12000005 进程通信错误
**错误信息**
IPC communication timeout. or Receive message from IPC failed.
**可能原因**
进程通信错误。
**处理步骤**
查看错误信息，排查是否进程IPC通信问题。
## 12000006 算法库操作失败
**错误信息**
Error occured in crypto engine.
**可能原因**
该错误码表示算法库操作失败，可能原因如下。
1. 算法库加解密错误，可能是密文数据不对。
2. 密钥参数不正确。
**处理步骤**
1. 排查密文数据是否正确。
2. 排查加解密参数是否正确。
## 12000007 密钥访问失败 - 密钥已失效
**错误信息**
This credential is already invalidated permanently.
**可能原因**
该错误码表示密钥访问失败 - 密钥已失效，可能原因如下。
1. 该密钥设置了清除密码失效的用户认证访问控制属性，清除过设备密钥导致密钥失效。
2. 该密钥设置了新录入生物特征失效的用户认证访问控制属性，由于录入过新的指纹或人脸导致该密钥失败。
**处理步骤**
1. 确认日志是哪种方式导致的认证不通过。
2. 如果使用了正确参数，但是失效控制导致认证不通过，则该密钥已经无法使用。
## 12000008 密钥访问失败 - 密钥认证失败
**错误信息**
Verify authtoken failed.
**可能原因**
该密钥设置了用户认证访问控制属性，由于challenge参数不正确导致无法通过认证。
**处理步骤**
1. 检查userIAM认证的challenge参数组装是否正确。
2. 如果是challenge参数不正确导致，则修改正确的组装方式，使用huks生成challenge组装，并传入userIAM重新认证。
## 12000009 密钥访问失败 - 密钥访问超时
**错误信息**
This authtoken is already timeout.
**可能原因**
该密钥设置了用户认证访问控制属性，由于使用时间窗timeout导致无法通过认证。
**处理步骤**
如果是timeout导致不正确，则重新触发密钥init并重新认证，使得认证时间和密钥init时间小于设置的timeout时间。
## 12000010 密钥操作会话数已达上限
**错误信息**
The number of session has reached limit.
**可能原因**
同时使用huks进行密钥会话操作的调用方（同应用或者跨应用）过多，已经达到上限（15个）。
**处理步骤**
1. 检查同应用内部是否同时存在多个密钥会话操作（init)，存在则修改避免同时调用。
2. 如不存在上述情形，则可能是其它应用同时调用多个会话，通过等待其它应用释放会话后再使用。
## 12000011 目标对象不存在
**错误信息**
Queried entity does not exist.
**可能原因**
该别名对应的密钥不存在。
**处理步骤**
1. 检查密钥别名是否拼写错误。
2. 检查改密钥别名对应的密钥是否生成成功。
## 12000012 外部错误
**错误信息**
External error ``${messageInfo}``.
**可能原因**
外部的硬件出错，文件错误等。
**处理步骤**
拿错误码与日志在社区反馈。
## 12000013 密钥设置生物访问控制时，待绑定的凭据不存在
**错误信息**
Queried credential does not exist.
**可能原因**
密钥绑定PIN、指纹、人脸时，未录入相关凭据。
**处理步骤**
录入相关凭据，或更改绑定凭据类型。
## 12000014 内存不足
**错误信息**
Memory is insufficient.
**可能原因**
系统内存不足。
**处理步骤**
开发者释放部分内存或重启。
## 12000015 调用其他系统服务失败
**错误信息**
Call ``${messageInfo}`` service to do ``${messageInfo}`` failed.
**可能原因**
其他系统服务未启动。
**处理步骤**
开发者等待一段时间后尝试再次触发调用。
zh-cn/application-dev/reference/errorcodes/errorcode-uitest.md 0 → 100644
浏览文件 @ d5332ef7
# uitest错误码
## 17000001 初始化失败
**错误信息**
Initialize failed.
**错误描述**
框架初始化失败。
**可能原因**
无法连接到无障碍服务。
**处理步骤**
执行param set persist.ace.testmode.enabled 1，并重启设备。
## 17000002 当前无法调用
**错误信息**
API does not allow calling concurrently.
**错误描述**
当前无法调用API。
**可能原因**
API没有使用await进行异步调用，造成堵塞。
**处理步骤**
检查测试用例，确保异步接口使用await调用。
## 17000003 断言失败
**错误信息**
Component existence assertion failed.
**错误描述**
用户断言失败。
**可能原因**
用户断言存在的控件实际不存在。
**处理步骤**
检查用户断言存在的控件实际是否存在。
## 17000004 目标控件/窗口丢失
**错误信息**
Component lost/UiWindow lost.
**错误描述**
目标控件/窗口丢失，无法进行操作。
**可能原因**
获取到目标控件/窗口后，页面发生变化导致目标丢失。
**处理步骤**
检查获取到目标控件/窗口后，页面是否发生变化导致目标丢失。
## 17000005 操作不支持
**错误信息**
This operation is not supported.
**错误描述**
UI对象不支持该操作。
**可能原因**
当前界面控件/窗口属性不支持该操作。
**处理步骤**
检查当前界面控件/窗口属性是否该操作。
zh-cn/application-dev/reference/errorcodes/errorcodes-zlib.md
浏览文件 @ d5332ef7
# zlib子系统错误码
## 401 参数检查错误
**错误信息**
The parameter invalid.
**错误描述**
当调用zlib的compress及decompress接口时，若传入参数的类型或者范围不匹配，会报此错误码。
**可能原因**
1. 入参类型错误不匹配，如传入的文件路径类型不是strinf。
2. 入参范围不匹配，如传入的options中包含的枚举不存在。
**处理步骤**
检查入参类型和范围是否匹配。
## 900001 传入的源文件错误
**错误信息**
......
zh-cn/application-dev/task-management/Readme-CN.md
浏览文件 @ d5332ef7
......@@ -6,4 +6,8 @@
- 延迟任务调度
- [延迟任务调度概述](work-scheduler-overview.md)
- [延迟任务调度开发指导](work-scheduler-dev-guide.md)
\ No newline at end of file
- [延迟任务调度开发指导](work-scheduler-dev-guide.md)
- 后台代理提醒
- [后台代理提醒开发概述](background-agent-scheduled-reminder-overview.md)
- [后台代理提醒开发指导](background-agent-scheduled-reminder-guide.md)
\ No newline at end of file
zh-cn/application-dev/ui/arkui-overview.md
浏览文件 @ d5332ef7
# 方舟开发框架概述
## 框架介绍
方舟开发框架（简称：ArkUI），是一套UI开发框架，提供开发者进行应用UI开发时所必需的能力。
方舟开发框架（简称：ArkUI），是一套构建OpenHarmony应用界面的UI开发框架，它提供了极简的UI语法与包括UI组件、动画机制、事件交互等在内的UI开发基础设施，以满足应用开发者的可视化界面开发需求。
## 基本概念
- 组件：组件是界面搭建与显示的最小单位。开发者通过多种组件的组合，构建出满足自身应用诉求的完整界面。
- 页面：page页面是方舟开发框架最小的调度分割单位。开发者可以将应用设计为多个功能页面，每个页面进行单独的文件管理，并通过路由API实现页面的调度管理，以实现应用内功能的解耦。
- **组件：** 组件是界面搭建与显示的最小单位。开发者通过多种组件的组合，构建出满足自身应用诉求的完整界面。
- **页面：** page页面是方舟开发框架最小的调度分割单位。开发者可以将应用设计为多个功能页面，每个页面进行单独的文件管理，并通过[页面路由](../reference/apis/js-apis-router.md)API完成页面间的调度管理，以实现应用内功能的解耦。
## 主要特征
- UI组件：方舟开发框架不仅提供了多种基础组件， 例如文本、图片、按钮等 ，也提供了支持视频播放能力的媒体组件。并且针对不同类型设备进行了组件设计，提供了组件在不同平台上的样式适配能力，此种组件称为“多态组件”。
- **UI组件：** 方舟开发框架内置了丰富的多态组件，包括文本、图片、按钮等基础组件，可包含一个或多个子组件的容器组件，满足开发者自定义绘图需求的绘制组件，以及提供视频播放能力的媒体组件等。其中“多态”是指组件针对不同类型设备进行了设计，提供了在不同平台上的样式适配能力。
- 布局：UI界面设计离不开布局的参与。方舟开发框架提供了多种布局方式，不仅保留了经典的弹性布局能力，也提供了列表、宫格、栅格布局和适应多分辨率场景开发的原子布局能力。
- **布局：** UI界面设计离不开布局的参与。方舟开发框架提供了多种布局方式，除了基础的线性布局、弹性布局外，也提供了相对复杂的列表、宫格、栅格布局，以及自适应多分辨率场景开发的原子布局能力。
- 动画：方舟开发框架对于UI界面的美化，除了组件内置动画效果外，也提供了属性动画、转场动画和自定义动画能力。
- **动画：** 动画是UI界面的重要元素之一，优秀的动画设计能够极大地提升用户体验，方舟开发框架提供了丰富的动画能力，除了组件内置动画效果外，还包括属性动画、自定义转场动画以及动画API等。
- 绘制：方舟开发框架提供了多种绘制能力，以满足开发者绘制自定义形状的需求，支持图形绘制、颜色填充、文本绘制、图片绘制等。
- **绘制：** 方舟开发框架提供了多种绘制能力，以满足开发者的自定义绘图需求，支持绘制形状、颜色填充、绘制文本、变形与裁剪、嵌入图片等。
- 交互事件：方舟开发框架提供了多种交互能力，满足应用在不同平台通过不同输入设备均可正常进行UI交互响应，默认适配了触摸手势、遥控器、鼠标等输入操作，同时也提供事件通知能力。
- **交互事件：** 方舟开发框架提供了多种交互能力，以满足应用在不同平台通过不同输入设备进行UI交互响应的需求，默认适配了触摸手势、遥控器按键输入、键鼠输入，同时提供了相应的事件回调以便开发者添加交互逻辑。
- 平台API通道：方舟开发框架提供了API扩展机制，平台能力通过此种机制进行封装，提供风格统一的JS接口。
- **平台API通道：** 方舟开发框架提供了API扩展机制，可通过该机制对平台能力进行封装，提供风格统一的JS接口。
- 两种开发范式：方舟开发框架针对不同目的和技术背景的开发者提供了两种开发范式，分别是基于eTS的声明式开发范式（简称“声明式开发范式”）和兼容JS的类Web开发范式（简称“类Web开发范式”）。
- **两种开发范式：** 方舟开发框架针对不同的应用场景以及不同技术背景的开发者提供了两种开发范式，分别是[基于ArkTS的声明式开发范式](./ui-ts-overview.md)（简称“声明式开发范式”）和[兼容JS的类Web开发范式](./ui-js-overview.md)（简称“类Web开发范式”）。
| 开发范式名称 | 简介 | 适用场景 | 适用人群 |
| -------- | ---------------------------------------- | ---------------- | ------------------- |
| 声明式开发范式 | 采用TS语言并进行声明式UI语法扩展，从组件、动效和状态管理三个维度提供了UI绘制能力。UI开发更接近自然语义的编程方式，让开发者直观地描述UI界面，不必关心框架如何实现UI绘制和渲染，实现极简高效开发。同时，选用有类型标注的TS语言，引入编译期的类型校验。 | 复杂度较大、团队合作度较高的程序 | 移动系统应用开发人员、系统应用开发人员 |
| 类Web开发范式 | 采用经典的HML、CSS、JavaScript三段式开发方式。使用HML标签文件进行布局搭建，使用CSS文件进行样式描述，使用JavaScript文件进行逻辑处理。UI组件与数据之间通过单向数据绑定的方式建立关联，当数据发生变化时，UI界面自动触发更新。此种开发方式，更接近Web前端开发者的使用习惯，快速将已有的Web应用改造成方舟开发框架应用。 | 界面较为简单的中小型应用和卡片 | Web前端开发人员 |
| 声明式开发范式 | 采用基于TypeScript进行声明式UI语法扩展而来的[ArkTS语言](../quick-start/ets-get-started.md)，从组件、动画和状态管理三个维度提供了UI绘制能力。声明式开发范式更接近自然语义的编程方式，让开发者直观地描述UI界面，不必关心框架如何实现UI绘制和渲染，实现极简高效开发。 | 复杂度较大、团队合作度较高的应用 | 移动系统应用开发人员、系统应用开发人员 |
| 类Web开发范式 | 采用经典的HML、CSS、JavaScript三段式开发方式，使用HML标签文件进行布局搭建，使用CSS文件进行样式描述，使用JavaScript文件进行逻辑处理。UI组件与数据之间通过单向数据绑定的方式建立关联，当数据发生变化时，UI界面自动触发刷新。该开发方式更接近Web前端开发者的使用习惯，便于快速将已有的Web应用改造成方舟开发框架应用。 | 界面较简单的中小型应用和卡片 | Web前端开发人员 |
## 框架结构
![zh-cn_image_0000001183709904](figures/zh-cn_image_0000001183709904.png)
### 框架结构
从上图可以看出，类Web开发范式与声明式开发范式的UI后端引擎和语言运行时是共用的，其中，UI后端引擎实现了方舟开发框架的六种基本能力。声明式开发范式无需JS Framework进行页面DOM管理，渲染更新链路更为精简，占用内存更少，因此更推荐开发者选用声明式开发范式来搭建应用UI界面。
## UI与Ability框架的关系
Ability也是OpenHarmony应用的重要组成部分，[Ability框架](../ability/ability-brief.md)包括FA模型与Stage模型两种模型。下表给出了Ability框架的两种模型分别与方舟开发框架的两种开发范式的关系。
**FA模型：**
| 类型 | UI开发范式 | 说明 |
| -------- | --------------------------- | --------------------------- |
| 应用 | 类web开发范式 | UI开发语言：使用hml/css/js <br>业务入口：使用固定文件名app.ets（Page类型Ability）/service.ts（Service类型Ability）/data.ts（Data类型Ability）<br>业务逻辑语言：js/ts |
| | 声明式开发范式 | UI开发语言：ArkTS <br>业务入口：使用固定文件名app.ets（Page类型Ability）/service.ts（Service类型Ability）/data.ts（Data类型Ability） <br>业务逻辑语言：js/ts |
| 服务卡片 | 类web开发范式 | UI开发语言：卡片显示使用hml+css+json(action) <br>业务入口：form.ts <br>卡片业务逻辑语言：js/ts |
| | 声明式开发范式 | 当前不支持 |
**Stage模型：**
| 类型 | UI开发范式 | 说明 |
| -------- | --------------------------- | --------------------------- |
| 应用 | 类web开发范式 | 当前不支持 |
| | 声明式开发范式 | UI开发语言：ArkTS <br>业务入口：应用模型基于ohos.application.Ability/ExtensionAbility等派生 <br>业务逻辑语言：ts |
| 服务卡片 | 类web开发范式 | UI开发语言：卡片显示使用hml+css+json(action) <br>业务入口：从FormExtensionAbility派生 <br>业务逻辑语言：ts |
| | 声明式开发范式 | 当前不支持 |
![zh-cn_image_0000001183709904](figures/zh-cn_image_0000001183709904.png)
从上图可以看出，类Web开发范式与声明式开发范式的UI后端引擎和语言运行时是共用的，其中，UI后端引擎实现了方舟开发框架的六种基本能力。声明式开发范式无需JS Framework进行页面DOM管理，渲染更新链路更为精简，占用内存更少，因此更推荐开发者选用声明式开发范式来搭建应用UI界面。
\ No newline at end of file
zh-cn/device-dev/device-test/developer_test.md 0 → 100644
浏览文件 @ d5332ef7
# 开发自测试执行框架使用指南
## 概述
OpenHarmony为开发者提供了一套全面的开发自测试框架developer_test，作为OpenHarmony测试工具集的一部分，提供给开发者自测试使用。开发者可根据测试需求开发相关测试用例，开发阶段提前发现缺陷，大幅提高代码质量。
本文从基础环境构建，用例开发，编译以及执行等方面介绍OpenHarmony开发自测试执行框架如何运行和使用。
### 简介
OpenHarmony系统开发人员在新增或修改代码之后，希望可以快速的验证修改代码的功能的正确性，而系统中已经存在了大量的已有功能的自动化测试用例，比如TDD用例或XTS用例等。开发者自测试执行框架目的就是为了提升开发者的自测试执行效率，方便开发人员可以快速便捷的执行指定的自动化测试用例，将测试活动左移到开发阶段。
### 约束与限制
- 框架使用时必须提前连接OpenHarmony设备方可执行测试用例。
## 环境准备
开发自测试框架依赖于python运行环境,python版本为3.8.X,在使用测试框架之前可参阅以下方式进行配置。
- [环境配置](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/subsystems/subsys-testguide-test.md#%E7%8E%AF%E5%A2%83%E9%85%8D%E7%BD%AE)
- [源码获取](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/get-code/sourcecode-acquire.md)
## 编写测试用例
本测试框架支持多种类型测试，针对不同测试类型提供了不同的用例编写模板以供参考。_
**TDD测试（C++）**
用例源文件命名规范
测试用例源文件名称和测试套内容保持一致，文件命名采用全小写+下划线方式命名，以test结尾，具体格式为：[功能]_[子功能]_test，子功能支持向下细分。
示例：
```
calculator_sub_test.cpp
```
用例示例
```
/*
* Copyright (c) 2021 XXXX Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#include "calculator.h"
#include <gtest/gtest.h>
using namespace testing::ext;
class CalculatorSubTest : public testing::Test {
public:
static void SetUpTestCase(void);
static void TearDownTestCase(void);
void SetUp();
void TearDown();
};
void CalculatorSubTest::SetUpTestCase(void)
{
// input testsuit setup step，setup invoked before all testcases
}
void CalculatorSubTest::TearDownTestCase(void)
{
// input testsuit teardown step，teardown invoked after all testcases
}
void CalculatorSubTest::SetUp(void)
{
// input testcase setup step，setup invoked before each testcases
}
void CalculatorSubTest::TearDown(void)
{
// input testcase teardown step，teardown invoked after each testcases
}
/**
* @tc.name: integer_sub_001
* @tc.desc: Verify the sub function.
* @tc.type: FUNC
* @tc.require: issueNumber
*/
HWTEST_F(CalculatorSubTest, integer_sub_001, TestSize.Level1)
{
// step 1:调用函数获取结果
int actual = Sub(4，0)；
// Step 2:使用断言比较预期与实际结果
EXPECT_EQ(4, actual);
}
```
详细内容介绍：
1.添加测试用例文件头注释信息
```
/*
* Copyright (c) 2021 XXXX Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
```
2.引用测试框架头文件和命名空间
```
#include <gtest/gtest.h>
using namespace testing::ext;
```
3.添加被测试类的头文件
```
#include "calculator.h"
```
4.定义测试套（测试类）
```
class CalculatorSubTest : public testing::Test {
public:
static void SetUpTestCase(void);
static void TearDownTestCase(void);
void SetUp();
void TearDown();
};
void CalculatorSubTest::SetUpTestCase(void)
{
// input testsuit setup step，setup invoked before all testcases
}
void CalculatorSubTest::TearDownTestCase(void)
{
// input testsuit teardown step，teardown invoked after all testcases
}
void CalculatorSubTest::SetUp(void)
{
// input testcase setup step，setup invoked before each testcases
}
void CalculatorSubTest::TearDown(void)
{
// input testcase teardown step，teardown invoked after each testcases
}
```
> **注意：** 在定义测试套时，测试套名称应与编译目标保持一致，采用大驼峰风格。
5.测试用例实现，包含用例注释和逻辑实现
```
/**
* @tc.name: integer_sub_001
* @tc.desc: Verify the sub function.
* @tc.type: FUNC
* @tc.require: issueNumber
*/
HWTEST_F(CalculatorSubTest, integer_sub_001, TestSize.Level1)
{
//step 1:调用函数获取结果
int actual = Sub(4，0)；
//Step 2:使用断言比较预期与实际结果
EXPECT_EQ(4, actual);
}
```
> **注意：** @tc.require: 格式必须以AR/SR或issue开头： 如：issueI56WJ7
在编写用例时，我们提供了三种用例模板供您选择。
| 类型 | 描述 |
| --------------- | ------------------------------------------------ |
| HWTEST(A,B,C) | 用例执行不依赖Setup&Teardown时，可选取 |
| HWTEST_F(A,B,C) | 用例执行(不含参数)依赖于Setup&Teardown时，可选取 |
| HWTEST_P(A,B,C) | 用例执行(含参数)依赖于Set&Teardown时，可选取 |
其中，参数A，B，C的含义如下：
- 参数A为测试套名。
- 参数B为测试用例名，其命名必须遵循[功能点]_[编号]的格式，编号为3位数字，从001开始。
- 参数C为测试用例等级，具体分为门禁level0 以及非门禁level1-level4共五个等级，其中非门禁level1-level4等级的具体选取规则为：测试用例功能越重要，level等级越低。
**注意：**
- 测试用例的预期结果必须有对应的断言。
- 测试用例必须填写用例等级。
- 测试体建议按照模板分步实现。
- 用例描述信息按照标准格式@tc.xxx value书写，注释信息必须包含用例名称，用例描述，用例类型，需求编号四项。其中用例测试类型@tc.type参数的选取，可参考下表。
| 测试类型名称 | 类型编码 |
| ------------ | -------- |
| 功能测试 | FUNC |
| 性能测试 | PERF |
| 可靠性测试 | RELI |
| 安全测试 | SECU |
| 模糊测试 | FUZZ |
**TDD测试（JS）**
- 用例源文件命名规范
测试用例原文件名称采用大驼峰风格，以TEST结尾，具体格式为：[功能][子功能]TEST，子功能支持向下细分。
示例：
```
AppInfoTest.js
```
- 用例示例
```
/*
* Copyright (C) 2021 XXXX Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import app from '@system.app'
import {describe, beforeAll, beforeEach, afterEach, afterAll, it, expect} from 'deccjsunit/index'
describe("AppInfoTest", function () {
beforeAll(function() {
// input testsuit setup step，setup invoked before all testcases
console.info('beforeAll caled')
})
afterAll(function() {
// input testsuit teardown step，teardown invoked after all testcases
console.info('afterAll caled')
})
beforeEach(function() {
// input testcase setup step，setup invoked before each testcases
console.info('beforeEach caled')
})
afterEach(function() {
// input testcase teardown step，teardown invoked after each testcases
console.info('afterEach caled')
})
/*
* @tc.name:appInfoTest001
* @tc.desc:verify app info is not null
* @tc.type: FUNC
* @tc.require: issueNumber
*/
it("appInfoTest001", 0, function () {
//step 1:调用函数获取结果
var info = app.getInfo()
//Step 2:使用断言比较预期与实际结果
expect(info != null).assertEqual(true)
})
})
```
详细内容介绍：
1. 添加测试用例文件头注释信息
```
/*
* Copyright (C) 2021 XXXX Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
```
2. 导入被测api和jsunit测试库
```
import app from '@system.app'
import {describe, beforeAll, beforeEach, afterEach, afterAll, it, expect} from 'deccjsunit/index'
```
3. 定义测试套（测试类）
```
describe("AppInfoTest", function () {
beforeAll(function() {
// input testsuit setup step，setup invoked before all testcases
console.info('beforeAll caled')
})
afterAll(function() {
// input testsuit teardown step，teardown invoked after all testcases
console.info('afterAll caled')
})
beforeEach(function() {
// input testcase setup step，setup invoked before each testcases
console.info('beforeEach caled')
})
afterEach(function() {
// input testcase teardown step，teardown invoked after each testcases
console.info('afterEach caled')
})
```
4. 测试用例实现
```
/*
* @tc.name:appInfoTest001
* @tc.desc:verify app info is not null
* @tc.type: FUNC
* @tc.require: issueNumber
*/
it("appInfoTest001", 0, function () {
//step 1:调用函数获取结果
var info = app.getInfo()
//Step 2:使用断言比较预期与实际结果
expect(info != null).assertEqual(true)
})
```
> **注意：** @tc.require: 格式必须以AR/SR或issue开头： 如：issueI56WJ7
**Fuzz测试**
[Fuzz用例编写规范](https://gitee.com/openharmony/test_developertest/blob/master/libs/fuzzlib/README_zh.md)
**Benchmark测试**
[Benchmark用例编写规范](https://gitee.com/openharmony/test_developertest/blob/master/libs/benchmark/README_zh.md)_
## 编译测试用例
根据测试用例目录规划，当执行某一用例时，测试框架会根据编译文件逐层查找，最终找到所需用例进行编译。下面通过不同示例来讲解gn文件如何编写。
**TDD测试**
针对不同语言，下面提供不同的编译模板以供参考。
- **C++用例编译配置示例**
```
# Copyright (c) 2021 XXXX Device Co., Ltd.
import("//build/test.gni")
module_output_path = "developertest/calculator"
config("module_private_config") {
visibility = [ ":*" ]
include_dirs = [ "../../../include" ]
}
ohos_unittest("CalculatorSubTest") {
module_out_path = module_output_path
sources = [
"../../../include/calculator.h",
"../../../src/calculator.cpp",
]
sources += [ "calculator_sub_test.cpp" ]
configs = [ ":module_private_config" ]
deps = [ "//third_party/googletest:gtest_main" ]
}
group("unittest") {
testonly = true
deps = [":CalculatorSubTest"]
}
```
详细内容如下：
1. 添加文件头注释信息
```
# Copyright (c) 2021 XXXX Device Co., Ltd.
```
2. 导入编译模板文件
```
import("//build/test.gni")
```
3. 指定文件输出路径
```
module_output_path = "developertest/calculator"
```
> **说明：** 此处输出路径为部件/模块名。
4. 配置依赖包含目录
```
config("module_private_config") {
visibility = [ ":*" ]
include_dirs = [ "../../../include" ]
}
```
> **说明：** 一般在此处对相关配置进行设置，在测试用例编译脚本中可直接引用。
5. 指定测试用例编译目标输出的文件名称
```
ohos_unittest("CalculatorSubTest") {
}
```
6. 编写具体的测试用例编译脚本（添加需要参与编译的源文件、配置和依赖）
```
ohos_unittest("CalculatorSubTest") {
module_out_path = module_output_path
sources = [
"../../../include/calculator.h",
"../../../src/calculator.cpp",
"../../../test/calculator_sub_test.cpp"
]
sources += [ "calculator_sub_test.cpp" ]
configs = [ ":module_private_config" ]
deps = [ "//third_party/googletest:gtest_main" ]
}
```
> **说明：根据测试类型的不同，在具体编写过程中可选择不同的测试类型：**
> - ohos_unittest：单元测试
> - ohos_moduletest：模块测试
> - ohos_systemtest：系统测试
> - ohos_performancetest：性能测试
> - ohos_securitytest：安全测试
> - ohos_reliabilitytest：可靠性测试
> - ohos_distributedtest：分布式测试
7. 对目标测试用例文件进行条件分组
```
group("unittest") {
testonly = true
deps = [":CalculatorSubTest"]
}
```
> **说明：** 进行条件分组的目的在于执行用例时可以选择性的执行某一种特定类型的用例。
- **JavaScript用例编译配置示例**
```
# Copyright (C) 2021 XXXX Device Co., Ltd.
import("//build/test.gni")
module_output_path = "developertest/app_info"
ohos_js_unittest("GetAppInfoJsTest") {
module_out_path = module_output_path
hap_profile = "./config.json"
certificate_profile = "//test/developertest/signature/openharmony_sx.p7b"
}
group("unittest") {
testonly = true
deps = [ ":GetAppInfoJsTest" ]
}
```
详细内容如下：
1.添加文件头注释信息
```
# Copyright (C) 2021 XXXX Device Co., Ltd.
```
2.导入编译模板文件
```
import("//build/test.gni")
```
3.指定文件输出路径
```
module_output_path = "developertest/app_info"
```
> **说明：** 此处输出路径为部件/模块名。
4.指定测试用例编译目标输出的文件名称
```
ohos_js_unittest("GetAppInfoJsTest") {
}
```
> **说明：**
> - 使用模板ohos_js_unittest定义js测试套，注意与C++用例区分。
> - js测试套编译输出文件为hap类型，hap名为此处定义的测试套名，测试套名称必须以JsTest结尾。
5.指定hap包配置文件config.json和签名文件，两个配置为必选项
```
ohos_js_unittest("GetAppInfoJsTest") {
module_out_path = module_output_path
hap_profile = "./config.json"
certificate_profile = "//test/developertest/signature/openharmony_sx.p7b"
}
```
config.json为hap编译所需配置文件，需要开发者根据被测sdk版本配置“target”项，其余项可默认，具体如下所示：
```
{
"app": {
"bundleName": "com.example.myapplication",
"vendor": "example",
"version": {
"code": 1,
"name": "1.0"
},
"apiVersion": {
"compatible": 4,
"target": 5 // 根据被测sdk版本进行修改，此例为sdk5
}
},
"deviceConfig": {},
"module": {
"package": "com.example.myapplication",
"name": ".MyApplication",
"deviceType": [
"phone"
],
"distro": {
"deliveryWithInstall": true,
"moduleName": "entry",
"moduleType": "entry"
},
"abilities": [
{
"skills": [
{
"entities": [
"entity.system.home"
],
"actions": [
"action.system.home"
]
}
],
"name": "com.example.myapplication.MainAbility",
"icon": "$media:icon",
"description": "$string:mainability_description",
"label": "MyApplication",
"type": "page",
"launchType": "standard"
}
],
"js": [
{
"pages": [
"pages/index/index"
],
"name": "default",
"window": {
"designWidth": 720,
"autoDesignWidth": false
}
}
]
}
}
```
6.对目标测试用例文件进行条件分组
```
group("unittest") {
testonly = true
deps = [ ":GetAppInfoJsTest" ]
}
```
> **说明：** 进行条件分组的目的在于执行用例时可以选择性的执行某一种特定类型的用例。
**Fuzz测试**
[Fuzz编译文件编写规范](https://gitee.com/openharmony/test_developertest/blob/master/libs/fuzzlib/README_zh.md)
**Benchmark测试**
[Benchmark编译文件编写规范](https://gitee.com/openharmony/test_developertest/blob/master/libs/benchmark/README_zh.md)
**编译入口配置文件ohos.build**
当完成用例编译配置文件编写后，需要进一步编写部件编译配置文件，以关联到具体的测试用例。
```
"partA": {
"module_list": [
],
"inner_list": [
],
"system_kits": [
],
"test_list": [ //配置模块calculator下的test
"//system/subsystem/partA/calculator/test:unittest",
"//system/subsystem/partA/calculator/test:fuzztest",
"//system/subsystem/partA/calculator/test:benchmarktest"
}
```
> **说明：** test_list中配置的是对应模块的测试用例。
## 测试资源配置
试依赖资源主要包括测试用例在执行过程中需要的图片文件，视频文件、第三方库等对外的文件资源。
依赖资源文件配置步骤如下：
1.在部件的test目录下创建resource目录，在resource目录下创建对应的模块，在模块目录中存放该模块所需要的资源文件
2.在resource目录下对应的模块目录中创建一个ohos_test.xml文件，文件内容格式如下:
```
<?xml version="1.0" encoding="UTF-8"?>
<configuration ver="2.0">
<target name="CalculatorSubTest">
<preparer>
<option name="push" value="test.jpg -> /data/test/resource" src="res"/>
<option name="push" value="libc++.z.so -> /data/test/resource" src="out"/>
</preparer>
</target>
</configuration>
```
3.在测试用例的编译配置文件中定义resource_config_file进行指引，用来指定对应的资源文件ohos_test.xml
```
ohos_unittest("CalculatorSubTest") {
resource_config_file = "//system/subsystem/partA/test/resource/calculator/ohos_test.xml"
}
```
>**说明：**
>- target_name: 测试套的名称，定义在测试目录的BUILD.gn中。preparer: 表示该测试套执行前执行的动作。
>- src="res": 表示测试资源位于test目录下的resource目录下，src="out"：表示位于out/release/$(部件)目录下。
## 执行测试用例
### 配置文件
在执行测试用例之前，针对用例使用设备的不同，需要对相应配置进行修改，修改完成即可执行测试用例。
#### user_config.xml配置
```
<user_config>
<build>
<!-- 是否编译demo用例, 默认为false，如果需要编译demo可修改为true -->
<example>false</example>
<!-- 是否编译版本, 默认为false -->
<version>false</version>
<!-- 是否编译测试用例, 默认为true，若已完成编译，再执行用例之前可修改为false，防止重新编译 -->
<testcase>true</testcase>
<!-- 在编译测试用例的情况下，选择编译target_cpu是64位的还是32位的，默认为空（32bit）可以选择: arm64 -->
<parameter>
<target_cpu></target_cpu>
</parameter>
</build>
<environment>
<!-- 配置远程映射机器的IP及端口，以支持HDC连接的设备 -->
<device type="usb-hdc">
<ip></ip>
<port></port>
<sn></sn>
</device>
<!-- 配置设备的串口信息，以支持串口连接的设备 -->
<device type="com" label="ipcamera">
<serial>
<com></com>
<type>cmd</type>
<baud_rate>115200</baud_rate>
<data_bits>8</data_bits>
<stop_bits>1</stop_bits>
<timeout>1</timeout>
</serial>
</device>
</environment>
<!-- 配置测试用例路径，若测试用例未编译，即<testcase>标签属性为true时，此处默认不填写；若编译已完成，需在此处指定测试用例的实际路径 -->
<test_cases>
<dir></dir>
</test_cases>
<!-- 配置覆盖率编译路径 -->
<coverage>
<outpath></outpath>
</coverage>
<!-- NFS挂载信息配置，被测设备仅支持串口连接时配置，指定NFS的映射路径，host_dir为PC侧的NFS目录，board_dir为板侧创建的目录 -->
<NFS>
<host_dir></host_dir>
<mnt_cmd></mnt_cmd>
<board_dir></board_dir>
</NFS>
</user_config>
```
>**说明：** 在执行测试用例之前，若使用HDC连接设备，用例仅需配置设备IP和端口号即可，其余信息均默认不修改。
### 执行命令说明
1. 启动测试框架
```
start.bat
```
2. 选择产品形态
进入测试框架，系统会自动提示您选择产品形态，请根据实际的开发板进行选择。
如需手动添加，请在config/framework_config.xml的\<productform\>标签内增加产品项。
3. 执行测试用例
当选择完产品形态，可参考如下指令执行测试用例。
```
run -t UT -ts CalculatorSubTest -tc interger_sub_00l
```
执行命令参数说明：
```
-t [TESTTYPE]: 指定测试用例类型，有UT，MST，ST，PERF，FUZZ，BENCHMARK等。（必选参数）
-tp [TESTPART]: 指定部件，可独立使用。
-tm [TESTMODULE]: 指定模块，不可独立使用，需结合-tp指定上级部件使用。
-ts [TESTSUITE]: 指定测试套，可独立使用。
-tc [TESTCASE]: 指定测试用例，不可独立使用，需结合-ts指定上级测试套使用。
-h : 帮助命令。
#### Windows环境执行
由于Windows环境下无法实现用例编译，因此执行用例前需要在Linux环境下进行用例编译，用例编译命令：
```
./build.sh --product-name {product_name} --build-target make_test
```
>说明:
>- product-name：指定编译产品名称。
>- build-target：指定所需编译用例，make_test表示指定全部用例，实际开发中可指定特定用例。
编译完成后，测试用例将自动保存在out/ohos-arm-release/packages/phone/tests目录下。
##### 搭建执行环境
1. 在Windows环境创建测试框架目录Test，并在此目录下创建testcase目录
2. 从Linux环境拷贝测试框架developertest和xdevice到创建的Test目录下，拷贝编译好的测试用例到testcase目录下
>**说明：** 将测试框架及测试用例从Linux环境移植到Windows环境，以便后续执行。
3. 修改user_config.xml
```
<build>
<!-- 由于测试用例已编译完成，此标签属性需改为false -->
<testcase>false</testcase>
</build>
<test_cases>
<!-- 由于已将测试用例拷贝到Windows环境下，测试用例输出路径发生改变，需要修改为拷贝后所存放的路径 -->
<dir>D:\Test\testcase\tests</dir>
</test_cases>
```
>**说明：** `<testcase>`标签表示是否需要编译用例；`<dir>`标签表示测试用例查找路径。
#### Linux环境执行
如是直接连接Linux机器，则可直接使用上面的执行命令执行命令
##### 远程端口映射
为支持Linux远程服务器以及Linux虚拟机两种环境下执行测试用例，需要对端口进行远程映射，以实现与设备的数据通路连接。具体操作如下：
1. HDC Server指令：
```
hdc_std kill
hdc_std -m -s 0.0.0.0:8710
```
>**说明：** IP和端口号为默认值。
2. HDC Client指令：
```
hdc_std -s xx.xx.xx.xx:8710 list targets
```
>**说明：** 此处IP填写设备侧IP地址。
## 查看测试结果
### 测试报告日志
当执行完测试指令，控制台会自动生成测试结果，若需要详细测试报告您可在相应的数据文档中进行查找。
### 测试结果
测试结果输出根路径如下：
```
test/developertest/reports/xxxx_xx_xx_xx_xx_xx
```
>**说明：** 测试报告文件目录将自动生成。
该目录中包含以下几类结果：
| 类型 | 描述 |
| ------------------------------------ | ------------------ |
| result/ | 测试用例格式化结果 |
| log/plan_log_xxxx_xx_xx_xx_xx_xx.log | 测试用例日志 |
| summary_report.html | 测试报告汇总 |
| details_report.html | 测试报告详情 |
### 测试框架日志
```
reports/platform_log_xxxx_xx_xx_xx_xx_xx.log
```
### 最新测试报告
```
reports/latest
```
zh-cn/device-dev/kernel/Readme-CN.md
浏览文件 @ d5332ef7
......@@ -65,6 +65,7 @@
- [虚拟文件系统](kernel-small-bundles-fs-virtual.md)
- [支持的文件系统](kernel-small-bundles-fs-support.md)
- [适配新的文件系统](kernel-small-bundles-fs-new.md)
- [Plimitsfs文件系统](kernel-small-plimits.md)
- 调测与工具
- Shell
- [Shell介绍](kernel-small-debug-shell-overview.md)
......
zh-cn/device-dev/kernel/kernel-small-plimits.md 0 → 100644
浏览文件 @ d5332ef7
# 容器配额（plimits）
## 简介
面对进程越来越多，应用环境越来越复杂的状况，需要对容器做限制，若不做限制，会发生资源浪费、争夺等。容器配额plimits（Process Limits）是内核提供的一种可以限制单个进程或者多个进程所使用资源的机制，可以对cpu，内存等资源实现精细化控制。plimits的接口通过plimitsfs的伪文件系统提供。通过操作文件对进程及进程资源进行分组管理，通过配置plimits组内限制器Plimiter限制进程组的memory、sched等资源的使用。
## 基本概念
- plimits：内核的一个特性，用于限制、记录和隔离一组进程的资源使用。
- plimitsfs：plimits文件系统，向用户提供操作接口，实现plimits的创建，删除。向用户展示plimits的层级等。
- plimiter：资源限制器的总称，一个子系统代表一类资源限制器，包含memory限制器、pids限制器、sched限制器。
- sched限制器：限制plimits组内的所有进程，在时间周期内占用的cpu时间。
- memory限制器：限制plimits组内所有进程的内存使用总和。
- pids限制器：限制plimits组内能挂载的最大进程数。
## 运行机制
plimitsfs文件系统，在系统初始化阶段，初始化plimits目录挂载至proc目录下：
```
├─proc
│ ├─plimits
│ │ ├─plimits.plimiter_add
│ │ ├─plimits.plimiter_delete
│ │ ├─plimits.procs
│ │ ├─plimits.limiters
│ │ ├─pids.max
│ │ ├─sched.period
│ │ ├─sched.quota
│ │ ├─sched.stat
│ │ ├─memory.failcnt
│ │ ├─memory.limit
│ │ ├─memory.peak
│ │ ├─memory.usage
│ │ ├─memory.oom_ctrl
│ │ └─memory.stat
```
1. plimits分组：
**图1** plimits创建/删除
![zh-cn_image_0000002324](figures/zh-cn_image_0000002324.png)
2. sched限制器：
**图2** sched限制器配置
![zh-cn_image_000000252628](figures/zh-cn_image_000000232425.png)
3. memory限制器：
**图3** memory限制器配置
![zh-cn_image_000000232426](figures/zh-cn_image_000000232426.png)
4. pids限制器：
**图4** Pids限制器配置
![zh-cn_image_000000232428](figures/zh-cn_image_000000232428.png)
## 开发指导
### 接口说明
LiteOS-A的plimits根目录在/proc/plimits下，其下的所有文件只有只读权限，不允许写操作。限制器文件设定值默认为最大值，通过读文件，可查看组内进程资源状态。
通过mkdir创建plimitsA目录完成对进程资源分组，进而操作资源的分配限制。创建的plimitsA目录继承其父plimits目录。
1. plimitsA文件目录见下表：
| <div style="width:70px">权限</div> | 大小 | 用户 | 用户组 | 文件名 | 文件描述 |
| --------- | ---- | ---- | ------ | ---------------------- | --------- |
|-r--r--r-- | 0 | u:0 | g:0 | sched.stat | 每个线程上周期内使用的时间片信息，方便测试验证使用 |
|-rw-r--r-- | 0 | u:0 | g:0 | sched.quota | 组内所有进程在周期内使用时间片总和，单位：ns |
|-rw-r--r-- | 0 | u:0 | g:0 | sched.period | 时间片统计周期，单位：ns |
|-r--r--r-- | 0 | u:0 | g:0 | memory.stat | 统计内存使用的信息，单位：字节 |
|-r--r--r-- | 0 | u:0 | g:0 | memory.usage | 已使用内存份额，单位：字节 |
|-r--r--r-- | 0 | u:0 | g:0 | memory.peak | 内存历史使用峰值，单位：字节 |
|-rw-r--r-- | 0 | u:0 | g:0 | memory.limit | 内存使用限额，单位：字节 |
|-r--r--r-- | 0 | u:0 | g:0 | memory.failcnt | 记录超过限额内存分配失败的次数，单位：次 |
|-rw-r--r-- | 0 | u:0 | g:0 | pids.max | 组内允许挂载进程的最大数，单位：个 |
|-rw-r--r-- | 0 | u:0 | g:0 | plimits.procs | 组内挂载的所有进程 |
|-rw-r--r-- | 0 | u:0 | g:0 | plimits.limiter_delete | 根据写入的限制器名称，删除限制器 |
|-rw-r--r-- | 0 | u:0 | g:0 | plimits.limiter_add | 根据写入的限制器名称，添加限制器 |
|-r--r--r-- | 0 | u:0 | g:0 | plimits.limiters | 查看组内限制器 |
在/proc/plimits/下创建的plimitsA目录下文件均可读部分可写，通过write对plimitsA子目录中写入内容，完成对进程资源分配与限制。
- 对文件sched.quota写入时间，单位ns，可限制组内所有进程使用cpu的时间
- 对文件sched.period写入时间，单位ns，可设置组内统计的时间周期
- 对文件memory.limit写入内存，单位字节，可限制组内允许使用的内存制
- 对文件pids.max写入十进制数字，可限制组内允许挂载的进程个数
- 对文件plimits.procs写入Pid，可将进程挂到不同的plimits组
- 通过read读不同的文件，可查看组内资源配置使用状况
2. 删除plimitsA组：
首先对/proc/plimits/plimitsA/plimits.limiter_delete文件依次写入字段“sched”、“memory”、“pids”删除限制器，才能使用rmdir删除plimitsA。
| 权限 | 大小 | 用户 | 用户组 | 文件名 |
| --------- | ------- | ------ | ------ | ----------------------- |
|-rw-r--r-- | 0 | u:0 | g:0 | plimits.procs |
|-rw-r--r-- | 0 | u:0 | g:0 | plimits.limiter_delete |
|-rw-r--r-- | 0 | u:0 | g:0 | plimits.limiter_add |
|-r--r--r-- | 0 | u:0 | g:0 | plimits.limiters |
### 开发流程
plimits文件系统的主要开发流程包括创建新的plimitsA，将pid号写入/plimitsA/plimits.procs，对进程资源分组；按照字节大小写文件/plimitsA/memory.limit文件，限制plimitsA组内能使用的最大内存；对文件/plimitsA/pids.max写入十进制数字限制plimitsA组内所能挂载的进程数等；通过配置plimitsA组内限制器文件，对相应的资源进行分配和限制。亦可删除plimitsA，不限制资源的使用。
### 编程实例
编程示例主要是创建分组plimitsA，通过读写子目录内容，完成进程与进程资源的分组，对Plimits组内进程资源限制。
```
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>
#include <string.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#define LOS_OK 0
#define LOS_NOK -1
int main ()
{
int ret;
ssize_t len;
int fd = -1;
//get main pid
int mainpid = getpid();
char plimitsA[128] = "/proc/plimits/plimitsA";
char plimitsAPids[128] = "/proc/plimits/plimitsA/pids.max";
char plimitsAMemoryLimit[128] = "/proc/plimits/plimitsA/memory.limit";
char plimitsAMemoryUsage[128] = "/proc/plimits/plimitsA/memory.usage";
char plimitsAProcs[128] = "/proc/plimits/plimitsA/plimits.procs";
char plimitsAAdd[128] = "/proc/plimits/plimitsA/plimits.limiter_add";
char plimitsADelete[128] = "/proc/plimits/plimitsA/plimits.limiter_delete";
char plimitsMem[128] = "/proc/plimits/memory.usage";
char plimitsPid[128] = "/proc/plimits/plimits.procs";
char *mem = NULL;
char writeBuf[128];
char readBuf[128];
/* 查看根plimits组内进程 */
memset(readBuf, 0, sizeof(readBuf));
fd = open(plimitsPid, O_RDONLY);
len = read(fd, readBuf, sizeof(readBuf));
if (len != strlen(readBuf)) {
printf("read file failed.\n");
return LOS_NOK;
}
close(fd);
printf("/proc/plimits组内进程：%s\n", readBuf);
/* 查看根plimits组内内存使用 */
memset(readBuf, 0, sizeof(readBuf));
fd = open(plimitsMem, O_RDONLY);
len = read(fd, readBuf, sizeof(readBuf));
if (len != strlen(readBuf)) {
printf("read file failed.\n");
return LOS_NOK;
}
close(fd);
printf("/proc/plimits组内已使用内存：%s\n", readBuf);
/* 创建plimitsA “/proc/plimits/plimitsA” */
ret = mkdir(plimitsA, 0777);
if (ret != LOS_OK) {
printf("mkdir failed.\n");
return LOS_NOK;
}
/* 设置plimitsA组允许挂载进程个数 */
memset(writeBuf, 0, sizeof(writeBuf));
sprintf(writeBuf, "%d", 3);
fd = open(plimitsAPids, O_WRONLY);
len = write(fd, writeBuf, strlen(writeBuf));
if (len != strlen(writeBuf)) {
printf("write file failed.\n");
return LOS_NOK;
}
close(fd);
/* 挂载进程至plimitsA组 */
memset(writeBuf, 0, sizeof(writeBuf));
sprintf(writeBuf, "%d", mainpid);
fd = open(plimitsAProcs, O_WRONLY);
len = write(fd, writeBuf, strlen(writeBuf));
if (len != strlen(writeBuf)) {
printf("write file failed.\n");
return LOS_NOK;
}
close(fd);
/* 设置plimitsA组内分配内存限额 */
memset(writeBuf, 0, sizeof(writeBuf));
//limit memory
sprintf(writeBuf, "%d", (1024*1024*3));
fd = open(plimitsAMemoryLimit, O_WRONLY);
len = write(fd, writeBuf, strlen(writeBuf));
if (len != strlen(writeBuf)) {
printf("write file failed.\n");
return LOS_NOK;
}
close(fd);
/* 查看plimitsA组内允许使用的最大内存 */
memset(readBuf, 0, sizeof(readBuf));
fd = open(plimitsAMemoryLimit, O_RDONLY);
len = read(fd, readBuf, sizeof(readBuf));
if (len != strlen(readBuf)) {
printf("read file failed.\n");
return LOS_NOK;
}
close(fd);
printf("/proc/plimits/plimitsA组允许使用的最大内存：%s\n", readBuf);
/* 查看plimitsA组内挂载的进程 */
memset(readBuf, 0, sizeof(readBuf));
fd = open(plimitsAProcs, O_RDONLY);
len = read(fd, readBuf, sizeof(readBuf));
if (len != strlen(readBuf)) {
printf("read file failed.\n");
return LOS_NOK;
}
close(fd);
printf("/proc/plimits/plimitsA组内挂载的进程：%s\n", readBuf);
/* 查看plimitsA组内存的使用情况 */
mem = (char*)malloc(1024*1024);
memset(mem, 0, 1024);
memset(readBuf, 0, sizeof(readBuf));
fd = open(plimitsAMemoryUsage, O_RDONLY);
len = read(fd, readBuf, sizeof(readBuf));
if (len != strlen(readBuf)) {
printf("read file failed.\n");
return LOS_NOK;
}
close(fd);
printf("/proc/plimits/plimitsA组已使用内存：%s\n", readBuf);
/* 删除plimitsA组内memory限制器 */
memset(writeBuf, 0, sizeof(writeBuf));
sprintf(writeBuf, "%s", "memory");
fd = open(plimitsADelete, O_WRONLY);
len = write(fd, writeBuf, strlen(writeBuf));
if (len != strlen(writeBuf)) {
printf("write file failed.\n");
return LOS_NOK;
}
close(fd);
/* 增加plimitsA组内memory限制器 */
memset(writeBuf, 0, sizeof(writeBuf));
sprintf(writeBuf, "%s", "memory");
fd = open(plimitsAAdd, O_WRONLY);
len = write(fd, writeBuf, strlen(writeBuf));
if (len != strlen(writeBuf)) {
printf("write file failed.\n");
return LOS_NOK;
}
close(fd);
/* 删除plimitsA组,首先删除memory、pids、sched限制器 */
memset(writeBuf, 0, sizeof(writeBuf));
sprintf(writeBuf, "%s", "memory");
fd = open(plimitsADelete, O_WRONLY);
len = write(fd, writeBuf, strlen(writeBuf));
if (len != strlen(writeBuf)) {
printf("write file failed.\n");
return LOS_NOK;
}
memset(writeBuf, 0, sizeof(writeBuf));
sprintf(writeBuf, "%s", "pids");
fd = open(plimitsADelete, O_WRONLY);
len = write(fd, writeBuf, strlen(writeBuf));
memset(writeBuf, 0, sizeof(writeBuf));
sprintf(writeBuf, "%s", "sched");
fd = open(plimitsADelete, O_WRONLY);
len = write(fd, writeBuf, strlen(writeBuf));
close(fd);
ret = rmdir(plimitsA);
if (ret != LOS_OK) {
printf("rmdir failed.\n");
return LOS_NOK;
}
return 0;
}
```
### 结果验证
编译运行得到的结果为：
```
/proc/plimits组内进程：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/proc/plimits组内已使用内存：28016640
/proc/plimits/plimitsA组允许使用的最大内存：3145728
/proc/plimits/plimitsA组内挂载的进程：
15
/proc/plimits/plimitsA组已使用内存：4096
```
zh-cn/device-dev/reference/hdi-apis/_alloc_info.md
浏览文件 @ d5332ef7
......@@ -3,7 +3,7 @@
## **概述**
定义关于要分配的内存的信息。
定义待分配的内存的信息。
**相关模块:**
......
zh-cn/device-dev/reference/hdi-apis/_audio_adapter.md
浏览文件 @ d5332ef7
......@@ -5,7 +5,7 @@
AudioAdapter音频适配器接口。
提供音频适配器（声卡）对外支持的驱动能力，包括初始化端口、创建render、创建capture、获取端口能力集等。
提供音频适配器（声卡）对外支持的驱动能力，包括初始化端口、创建Render、创建Capture、获取端口能力集等。
**Since:**
......@@ -34,15 +34,15 @@ AudioAdapter音频适配器接口。
| 名称 | 描述 |
| -------- | -------- |
| ([InitAllPorts](#initallports))(struct&nbsp;AudioAdapter&nbsp;\*adapter) | 初始化一个音频适配器所有的端口驱动 |
| ([CreateRender](#createrender)&nbsp;)(struct&nbsp;AudioAdapter&nbsp;\*adapter,&nbsp;const&nbsp;struct&nbsp;AudioDeviceDescriptor&nbsp;\*desc,&nbsp;const&nbsp;struct&nbsp;AudioSampleAttributes&nbsp;\*attrs,&nbsp;struct&nbsp;AudioRender&nbsp;\*\*render) | 创建一个音频播放（render）接口的对象 |
| ([DestroyRender](#destroyrender)&nbsp;)(struct&nbsp;AudioAdapter&nbsp;\*adapter,&nbsp;struct&nbsp;AudioRender&nbsp;\*render) | 销毁一个音频播放（render）接口的对象 |
| ([CreateCapture](#createcapture))(struct&nbsp;AudioAdapter&nbsp;\*adapter,&nbsp;const&nbsp;struct&nbsp;AudioDeviceDescriptor&nbsp;\*desc,&nbsp;const&nbsp;struct&nbsp;AudioSampleAttributes&nbsp;\*attrs,&nbsp;struct&nbsp;AudioCapture&nbsp;\*\*capture) | 创建一个音频录音（capture）接口的对象 |
| ([DestroyCapture](#destroycapture))(struct&nbsp;AudioAdapter&nbsp;\*adapter,&nbsp;struct&nbsp;AudioCapture&nbsp;\*capture) | 销毁一个音频录音（capture）接口的对象 |
| ([CreateRender](#createrender)&nbsp;)(struct&nbsp;AudioAdapter&nbsp;\*adapter,&nbsp;const&nbsp;struct&nbsp;AudioDeviceDescriptor&nbsp;\*desc,&nbsp;const&nbsp;struct&nbsp;AudioSampleAttributes&nbsp;\*attrs,&nbsp;struct&nbsp;AudioRender&nbsp;\*\*render) | 创建一个音频播放（Render）接口的对象 |
| ([DestroyRender](#destroyrender)&nbsp;)(struct&nbsp;AudioAdapter&nbsp;\*adapter,&nbsp;struct&nbsp;AudioRender&nbsp;\*render) | 销毁一个音频播放（Render）接口的对象 |
| ([CreateCapture](#createcapture))(struct&nbsp;AudioAdapter&nbsp;\*adapter,&nbsp;const&nbsp;struct&nbsp;AudioDeviceDescriptor&nbsp;\*desc,&nbsp;const&nbsp;struct&nbsp;AudioSampleAttributes&nbsp;\*attrs,&nbsp;struct&nbsp;AudioCapture&nbsp;\*\*capture) | 创建一个音频录音（Capture）接口的对象 |
| ([DestroyCapture](#destroycapture))(struct&nbsp;AudioAdapter&nbsp;\*adapter,&nbsp;struct&nbsp;AudioCapture&nbsp;\*capture) | 销毁一个音频录音（Capture）接口的对象 |
| ([GetPortCapability](#getportcapability)&nbsp;)(struct&nbsp;AudioAdapter&nbsp;\*adapter,&nbsp;struct&nbsp;AudioPort&nbsp;\*port,&nbsp;struct&nbsp;AudioPortCapability&nbsp;\*capability) | 获取一个音频适配器的端口驱动的能力集 |
| ([SetPassthroughMode](#setpassthroughmode)&nbsp;)(struct&nbsp;AudioAdapter&nbsp;\*adapter,&nbsp;struct&nbsp;AudioPort&nbsp;\*port,&nbsp;enum&nbsp;AudioPortPassthroughMode&nbsp;mode) | 设置音频端口驱动的数据透传模式 |
| ([GetPassthroughMode](#getpassthroughmode))(struct&nbsp;AudioAdapter&nbsp;\*adapter,&nbsp;struct&nbsp;AudioPort&nbsp;\*port,&nbsp;enum&nbsp;AudioPortPassthroughMode&nbsp;\*mode) | 获取音频端口驱动的数据透传模式 |
| ([UpdateAudioRoute](#updateaudioroute))(struct&nbsp;AudioAdapter&nbsp;\*adapter,&nbsp;const&nbsp;struct&nbsp;AudioRoute&nbsp;\*route,&nbsp;int32_t&nbsp;\*routeHandle) | 更新一个或多个发送端和接受端之间的路由 |
| ([ReleaseAudioRoute](#releaseaudioroute))(struct&nbsp;AudioAdapter&nbsp;\*adapter,&nbsp;int32_t&nbsp;routeHandle) | 释放一个音频路由. |
| ([ReleaseAudioRoute](#releaseaudioroute))(struct&nbsp;AudioAdapter&nbsp;\*adapter,&nbsp;int32_t&nbsp;routeHandle) | 释放一个音频路由 |
## **类成员变量说明**
......@@ -57,7 +57,7 @@ int32_t(* AudioAdapter::CreateCapture) (struct AudioAdapter *adapter, const stru
**描述：**
创建一个音频录音（capture）接口的对象
创建一个音频录音（Capture）接口的对象。
**参数:**
......@@ -70,7 +70,7 @@ int32_t(* AudioAdapter::CreateCapture) (struct AudioAdapter *adapter, const stru
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -88,7 +88,7 @@ int32_t(* AudioAdapter::CreateRender) (struct AudioAdapter *adapter, const struc
**描述：**
创建一个音频播放（render）接口的对象
创建一个音频播放（Render）接口的对象。
**参数:**
......@@ -101,7 +101,7 @@ int32_t(* AudioAdapter::CreateRender) (struct AudioAdapter *adapter, const struc
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -119,7 +119,7 @@ int32_t(* AudioAdapter::DestroyCapture) (struct AudioAdapter *adapter, struct Au
**描述：**
销毁一个音频录音（capture）接口的对象
销毁一个音频录音（Capture）接口的对象。
**参数:**
......@@ -130,11 +130,11 @@ int32_t(* AudioAdapter::DestroyCapture) (struct AudioAdapter *adapter, struct Au
**注意:**
在音频录音过程中，不能销毁该接口对象
在音频录音过程中，不能销毁该接口对象。
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -150,7 +150,7 @@ int32_t(* AudioAdapter::DestroyRender) (struct AudioAdapter *adapter, struct Aud
**描述：**
销毁一个音频播放（render）接口的对象
销毁一个音频播放（Render）接口的对象。
**参数:**
......@@ -165,7 +165,7 @@ int32_t(* AudioAdapter::DestroyRender) (struct AudioAdapter *adapter, struct Aud
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -181,7 +181,7 @@ int(* AudioAdapter::GetPassthroughMode) (struct AudioAdapter *adapter, struct Au
**描述：**
获取音频端口驱动的数据透传模式
获取音频端口驱动的数据透传模式。
**参数:**
......@@ -193,7 +193,7 @@ int(* AudioAdapter::GetPassthroughMode) (struct AudioAdapter *adapter, struct Au
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -209,7 +209,7 @@ int(* AudioAdapter::GetPortCapability) (struct AudioAdapter *adapter, struct Aud
**描述：**
获取一个音频适配器的端口驱动的能力集
获取一个音频适配器的端口驱动的能力集。
**参数:**
......@@ -221,7 +221,7 @@ int(* AudioAdapter::GetPortCapability) (struct AudioAdapter *adapter, struct Aud
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### InitAllPorts
......@@ -249,7 +249,7 @@ int(* AudioAdapter::InitAllPorts) (struct AudioAdapter *adapter)
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### ReleaseAudioRoute
......@@ -261,18 +261,18 @@ int32_t(* AudioAdapter::ReleaseAudioRoute) (struct AudioAdapter *adapter, int32_
**描述：**
释放一个音频路由.
释放一个音频路由。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| adapter | 待操作的音频适配器对象 |
| routeHandle | 待释放的路由句柄. |
| routeHandle | 待释放的路由句柄 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### SetPassthroughMode
......@@ -284,7 +284,7 @@ int(* AudioAdapter::SetPassthroughMode) (struct AudioAdapter *adapter, struct Au
**描述：**
设置音频端口驱动的数据透传模式
设置音频端口驱动的数据透传模式。
**参数:**
......@@ -296,7 +296,7 @@ int(* AudioAdapter::SetPassthroughMode) (struct AudioAdapter *adapter, struct Au
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -312,7 +312,7 @@ int32_t(* AudioAdapter::UpdateAudioRoute) (struct AudioAdapter *adapter, const s
**描述：**
更新一个或多个发送端和接受端之间的路由
更新一个或多个发送端和接受端之间的路由。
**参数:**
......@@ -324,4 +324,4 @@ int32_t(* AudioAdapter::UpdateAudioRoute) (struct AudioAdapter *adapter, const s
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
zh-cn/device-dev/reference/hdi-apis/_audio_attribute.md
浏览文件 @ d5332ef7
......@@ -5,7 +5,7 @@
AudioAttribute音频属性接口。
提供音频播放（render）或录音（capture）需要的公共属性驱动能力，包括获取帧（frame）信息、设置采样属性等。
提供音频播放（Render）或录音（Capture）需要的公共属性驱动能力，包括获取帧（frame）信息、设置采样属性等。
**Since:**
......@@ -34,8 +34,8 @@ AudioAttribute音频属性接口。
| ([GetCurrentChannelId](#getcurrentchannelid))(AudioHandle&nbsp;handle,&nbsp;uint32_t&nbsp;\*channelId) | 获取音频的数据通道ID |
| ([SetExtraParams](#setextraparams))(AudioHandle&nbsp;handle,&nbsp;const&nbsp;char&nbsp;\*keyValueList) | 设置音频拓展参数 |
| ([GetExtraParams](#getextraparams))(AudioHandle&nbsp;handle,&nbsp;char&nbsp;\*keyValueList) | 获取音频拓展参数 |
| ([ReqMmapBuffer](#reqmmapbuffer))(AudioHandle&nbsp;handle,&nbsp;int32_t&nbsp;reqSize,&nbsp;struct&nbsp;AudioMmapBufferDescripter&nbsp;\*desc) | 请求mmap缓冲区 |
| ([GetMmapPosition](#getmmapposition))(AudioHandle&nbsp;handle,&nbsp;uint64_t&nbsp;\*frames,&nbsp;struct&nbsp;AudioTimeStamp&nbsp;\*time) | 获取当前mmap的读/写位置 |
| ([ReqMmapBuffer](#reqmmapbuffer))(AudioHandle&nbsp;handle,&nbsp;int32_t&nbsp;reqSize,&nbsp;struct&nbsp;AudioMmapBufferDescripter&nbsp;\*desc) | 请求Mmap缓冲区 |
| ([GetMmapPosition](#getmmapposition))(AudioHandle&nbsp;handle,&nbsp;uint64_t&nbsp;\*frames,&nbsp;struct&nbsp;AudioTimeStamp&nbsp;\*time) | 获取当前Mmap的读/写位置 |
| ([AddAudioEffect](#addaudioeffect))(AudioHandle&nbsp;handle,&nbsp;uint64_t&nbsp;effectid) | 添加音频效果算法实例 |
| ([RemoveAudioEffect](#removeaudioeffect))(AudioHandle&nbsp;handle,&nbsp;uint64_t&nbsp;effectid) | 移除音频效果算法实例 |
| ([GetFrameBufferSize](#getframebuffersize))(AudioHandle&nbsp;handle,&nbsp;uint64_t&nbsp;\*bufferSize) | 获取播放或录音的缓冲区大小 |
......@@ -53,7 +53,7 @@ int32_t (*AudioAttribute::AddAudioEffect)(AudioHandle handle, uint64_t effectid)
**描述：**
添加音频效果算法实例
添加音频效果算法实例。
**参数:**
......@@ -64,7 +64,7 @@ int32_t (*AudioAttribute::AddAudioEffect)(AudioHandle handle, uint64_t effectid)
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### GetCurrentChannelId
......@@ -76,18 +76,18 @@ int32_t(* AudioAttribute::GetCurrentChannelId) (AudioHandle handle, uint32_t *ch
**描述：**
获取音频的数据通道ID
获取音频的数据通道ID。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| channelId | 获取的通道ID保存到channelId中 |
| handle | 输入参数，待操作的音频句柄。 |
| channelId | 输出参数，获取的通道ID保存到channelId中。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### GetExtraParams
......@@ -99,18 +99,18 @@ int32_t(* AudioAttribute::GetExtraParams) (AudioHandle handle, char *keyValueLis
**描述：**
获取音频拓展参数
获取音频拓展参数。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| keyValueList | 拓展参数键值对字符串列表，格式为key=value，多个键值对通过分号分割 |
| handle | 输入参数，待操作的音频句柄。 |
| keyValueList | 输出参数，拓展参数键值对字符串列表，格式为key=value，多个键值对通过分号分割。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### GetFrameBufferSize
......@@ -122,7 +122,7 @@ int32_t (*AudioAttribute::GetFrameBufferSize)(AudioHandle handle, uint64_t *buff
**描述：**
获取播放或录音的缓冲区大小
获取播放或录音的缓冲区大小。
**参数:**
......@@ -145,18 +145,18 @@ int32_t(* AudioAttribute::GetFrameCount) (AudioHandle handle, uint64_t *count)
**描述：**
获取音频buffer中的音频帧数
获取音频buffer中的音频帧数。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| count | 一个音频buffer中包含的音频帧数，获取后保存到count中 |
| handle | 输入参数，待操作的音频句柄。 |
| count | 输出参数，一个音频buffer中包含的音频帧数，获取后保存到count中。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### GetFrameSize
......@@ -168,20 +168,18 @@ int32_t(* AudioAttribute::GetFrameSize) (AudioHandle handle, uint64_t *size)
**描述：**
获取音频帧（frame）的大小
获取一帧音频数据的长度（字节数）
获取音频帧（frame）的大小，即一帧音频数据的长度（字节数）。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| size | 获取的音频帧大小（字节数）保存到size中 |
| handle | 输入参数，待操作的音频句柄。 |
| size | 输出参数，获取的音频帧大小（字节数）保存到size中。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### GetMmapPosition
......@@ -193,19 +191,19 @@ int32_t(* AudioAttribute::GetMmapPosition) (AudioHandle handle, uint64_t *frames
**描述：**
获取当前mmap的读/写位置
获取当前Mmap的读/写位置。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| frames | 获取的音频帧计数保存到frames中 |
| time | 获取的关联时间戳保存到time中 |
| handle | 输入参数，待操作的音频句柄。 |
| frames | 输出参数，获取的音频帧计数保存到frames中。 |
| time | 输出参数，获取的关联时间戳保存到time中。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### GetSampleAttributes
......@@ -217,14 +215,14 @@ int32_t(* AudioAttribute::GetSampleAttributes) (AudioHandle handle, struct Audio
**描述：**
获取音频采样的属性参数
获取音频采样的属性参数。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| attrs | 获取的音频采样属性（例如采样频率、采样精度、通道）保存到attrs中 |
| handle | 输入参数，待操作的音频句柄。 |
| attrs | 输出参数，获取的音频采样属性（例如采样频率、采样精度、通道）保存到attrs中。 |
**返回:**
......@@ -244,7 +242,7 @@ int32_t (*AudioAttribute::RemoveAudioEffect)(AudioHandle handle, uint64_t effect
**描述：**
移除音频效果算法实例
移除音频效果算法实例。
**参数:**
......@@ -267,19 +265,19 @@ int32_t(* AudioAttribute::ReqMmapBuffer) (AudioHandle handle, int32_t reqSize, s
**描述：**
请求mmap缓冲区
请求Mmap缓冲区。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| reqSize | 请求缓冲区的大小 |
| desc | 缓冲区描述符 |
| handle | 输入参数，待操作的音频句柄。 |
| reqSize | 输入参数，请求缓冲区的大小。 |
| desc | 输出参数，缓冲区描述符。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### SetExtraParams
......@@ -291,18 +289,18 @@ int32_t(* AudioAttribute::SetExtraParams) (AudioHandle handle, const char *keyVa
**描述：**
设置音频拓展参数
设置音频拓展参数。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| keyValueList | 拓展参数键值对字符串列表，格式为key=value，多个键值对通过分号分割 |
| handle | 输入参数，待操作的音频句柄。 |
| keyValueList | 输入参数，拓展参数键值对字符串列表，格式为key=value，多个键值对通过分号分割。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### SetSampleAttributes
......@@ -314,18 +312,18 @@ int32_t(* AudioAttribute::SetSampleAttributes) (AudioHandle handle, const struct
**描述：**
设置音频采样的属性参数
设置音频采样的属性参数。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| attrs | 待设置的音频采样属性，例如采样频率、采样精度、通道 |
| handle | 输入参数，待操作的音频句柄。 |
| attrs | 输入参数，待设置的音频采样属性，例如采样频率、采样精度、通道。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......
zh-cn/device-dev/reference/hdi-apis/_audio_capture.md
浏览文件 @ d5332ef7
......@@ -21,7 +21,7 @@ AudioCapture录音接口。
| attr | 音频属性能力接口，详情参考[AudioAttribute](_audio_attribute.md)。 |
| scene | 音频场景能力接口，详情参考[AudioScene](_audio_scene.md)。 |
| volume | 音频音量能力接口，详情参考[AudioVolume](_audio_volume.md)。 |
| ([CaptureFrame](#captureframe))(struct&nbsp;AudioCapture&nbsp;\*capture,&nbsp;void&nbsp;\*frame,&nbsp;uint64_t&nbsp;requestBytes,&nbsp;uint64_t&nbsp;\*replyBytes) | 从音频驱动中录制（capture）一帧输入数据（录音，音频上行数据）。 |
| ([CaptureFrame](#captureframe))(struct&nbsp;AudioCapture&nbsp;\*capture,&nbsp;void&nbsp;\*frame,&nbsp;uint64_t&nbsp;requestBytes,&nbsp;uint64_t&nbsp;\*replyBytes) | 从音频驱动中录制（Capture）一帧输入数据（录音，音频上行数据）。 |
| ([GetCapturePosition](#getcaptureposition))(struct&nbsp;AudioCapture&nbsp;\*capture,&nbsp;uint64_t&nbsp;\*frames,&nbsp;struct&nbsp;AudioTimeStamp&nbsp;\*time) | 获取音频输入帧数的上一次计数。 |
......@@ -37,20 +37,20 @@ int32_t(* AudioCapture::CaptureFrame) (struct AudioCapture *capture, void *frame
**描述：**
从音频驱动中录制（capture）一帧输入数据（录音，音频上行数据）
从音频驱动中录制（Capture）一帧输入数据（录音，音频上行数据）。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| capture | 待操作的音频录音接口对象 |
| frame | 待存放输入数据的音频frame |
| requestBytes | 待存放输入数据的音频frame大小（字节数） |
| replyBytes | 实际读取到的音频数据长度（字节数），获取后保存到replyBytes中 |
| capture | 输入参数，待操作的音频录音接口对象。 |
| frame | 输入参数，待存放输入数据的音频frame。 |
| requestBytes | 输入参数，待存放输入数据的音频frame大小（字节数）。 |
| replyBytes | 输出参数，实际读取到的音频数据长度（字节数），获取后保存到replyBytes中。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### GetCapturePosition
......@@ -62,19 +62,19 @@ int32_t(* AudioCapture::GetCapturePosition) (struct AudioCapture *capture, uint6
**描述：**
获取音频输入帧数的上一次计数
获取音频输入帧数的上一次计数。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| capture | 待操作的音频录音接口对象 |
| frames | 获取的音频帧计数保存到frames中 |
| time | 获取的关联时间戳保存到time中 |
| capture | 输入参数，待操作的音频录音接口对象。|
| frames | 输出参数，获取的音频帧计数保存到frames中。 |
| time | 输出参数，获取的关联时间戳保存到time中。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......
zh-cn/device-dev/reference/hdi-apis/_audio_control.md
浏览文件 @ d5332ef7
......@@ -3,9 +3,9 @@
## **概述**
AudioControl音频控制接口
AudioControl音频控制接口。
提供音频播放（render）或录音（capture）需要的公共控制驱动能力，包括Start、Stop、Pause、Resume、Flush等。
提供音频播放（Render）或录音（Capture）需要的公共控制驱动能力，包括Start、Stop、Pause、Resume、Flush等。
**Since:**
......@@ -27,13 +27,13 @@ AudioControl音频控制接口
| 名称 | 描述 |
| -------- | -------- |
| ([Start](#start))(AudioHandle&nbsp;handle) | 启动一个音频播放（render）或录音（capture）处理 |
| ([Stop](#stop))(AudioHandle&nbsp;handle) | 停止一个音频播放（render）或录音（capture）处理 |
| ([Pause](#pause))(AudioHandle&nbsp;handle) | 暂停一个音频播放（render）或录音（capture）处理 |
| ([Resume](#resume))(AudioHandle&nbsp;handle) | 恢复一个音频播放（render）或录音（capture）处理 |
| ([Flush](#flush))(AudioHandle&nbsp;handle) | 刷新音频缓冲区buffer中的数据 |
| ([TurnStandbyMode](#turnstandbymode))(AudioHandle&nbsp;handle) | 设置或去设置设备的待机模式 |
| ([AudioDevDump](#audiodevdump))(AudioHandle&nbsp;handle,&nbsp;int32_t&nbsp;range,&nbsp;int32_t&nbsp;fd) | Dump音频设备信息 |
| ([Start](#start))(AudioHandle&nbsp;handle) | 启动一个音频播放（Render）或录音（Capture）处理。 |
| ([Stop](#stop))(AudioHandle&nbsp;handle) | 停止一个音频播放（Render）或录音（Capture）处理。 |
| ([Pause](#pause))(AudioHandle&nbsp;handle) | 暂停一个音频播放（Render）或录音（Capture）处理。 |
| ([Resume](#resume))(AudioHandle&nbsp;handle) | 恢复一个音频播放（Render）或录音（Capture）处理。 |
| ([Flush](#flush))(AudioHandle&nbsp;handle) | 刷新音频缓冲区buffer中的数据。 |
| ([TurnStandbyMode](#turnstandbymode))(AudioHandle&nbsp;handle) | 设置或去设置设备的待机模式。 |
| ([AudioDevDump](#audiodevdump))(AudioHandle&nbsp;handle,&nbsp;int32_t&nbsp;range,&nbsp;int32_t&nbsp;fd) | Dump音频设备信息。 |
## **类成员变量说明**
......@@ -48,7 +48,7 @@ int32_t(* AudioControl::AudioDevDump) (AudioHandle handle, int32_t range, int32_
**描述：**
Dump音频设备信息
Dump音频设备信息。
**参数:**
......@@ -60,7 +60,7 @@ Dump音频设备信息
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### Flush
......@@ -72,7 +72,7 @@ int32_t(* AudioControl::Flush) (AudioHandle handle)
**描述：**
刷新音频缓冲区buffer中的数据
刷新音频缓冲区buffer中的数据。
**参数:**
......@@ -82,7 +82,7 @@ int32_t(* AudioControl::Flush) (AudioHandle handle)
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### Pause
......@@ -94,7 +94,7 @@ int32_t(* AudioControl::Pause) (AudioHandle handle)
**描述：**
暂停一个音频播放（render）或录音（capture）处理
暂停一个音频播放（Render）或录音（Capture）处理。
**参数:**
......@@ -104,7 +104,7 @@ int32_t(* AudioControl::Pause) (AudioHandle handle)
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -120,7 +120,7 @@ int32_t(* AudioControl::Resume) (AudioHandle handle)
**描述：**
恢复一个音频播放（render）或录音（capture）处理
恢复一个音频播放（Render）或录音（Capture）处理。
**参数:**
......@@ -130,7 +130,7 @@ int32_t(* AudioControl::Resume) (AudioHandle handle)
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -146,7 +146,7 @@ int32_t(* AudioControl::Start) (AudioHandle handle)
**描述：**
启动一个音频播放（render）或录音（capture）处理
启动一个音频播放（Render）或录音（Capture）处理。
**参数:**
......@@ -156,7 +156,7 @@ int32_t(* AudioControl::Start) (AudioHandle handle)
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -172,7 +172,7 @@ int32_t(* AudioControl::Stop) (AudioHandle handle)
**描述：**
停止一个音频播放（render）或录音（capture）处理
停止一个音频播放（Render）或录音（Capture）处理。
**参数:**
......@@ -182,7 +182,7 @@ int32_t(* AudioControl::Stop) (AudioHandle handle)
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -198,7 +198,7 @@ int32_t(* AudioControl::TurnStandbyMode) (AudioHandle handle)
**描述：**
设置或去设置设备的待机模式
设置或去设置设备的待机模式。
**参数:**
......
zh-cn/device-dev/reference/hdi-apis/_audio_manager.md
浏览文件 @ d5332ef7
......@@ -49,19 +49,19 @@ int(* AudioManager::GetAllAdapters) (struct AudioAdapterManager *manager, struct
**描述：**
获取音频驱动中支持的所有适配器的列表
获取音频驱动中支持的所有适配器的列表。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| manager | 待操作的音频管理接口对象 |
| descs | 获取到的音频适配器列表保存到descs中 |
| size | 获取到的音频适配器列表的长度保存到size中 |
| manager | 输入参数，待操作的音频管理接口对象。 |
| descs | 输出参数，获取到的音频适配器列表保存到descs中。 |
| size | 输出参数，获取到的音频适配器列表的长度保存到size中。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -77,21 +77,21 @@ int(* AudioManager::LoadAdapter) (struct AudioAdapterManager *manager, const str
**描述：**
加载一个音频适配器（声卡）的驱动
加载一个音频适配器（声卡）的驱动。
加载一个具体的音频驱动，例如usb驱动，在具体实现中可能加载的是一个动态链接库（\*.so）
加载一个具体的音频驱动，例如USB驱动，在具体实现中可能加载的是一个动态链接库（\*.so）。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| manager | 待操作的音频管理接口对象 |
| desc | 待加载的音频适配器描述符 |
| adapter | 获取的音频适配器接口的对象实例保存到adapter中 |
| manager | 输入参数，待操作的音频管理接口对象。 |
| desc | 输入参数，待加载的音频适配器描述符。 |
| adapter | 输出参数，获取的音频适配器接口的对象实例保存到adapter中。|
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -109,17 +109,17 @@ bool(* AudioManager::ReleaseAudioManagerObject) (struct AudioManager *object)
**描述：**
释放音频管理接口对象
释放音频管理接口对象。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| 待操作的音频管理接口对象 | |
| object | 输入参数，待操作的音频管理接口对象。 |
**返回:**
成功返回true，失败返回false
成功返回true，失败返回false。
### UnloadAdapter
......@@ -131,14 +131,14 @@ void(* AudioManager::UnloadAdapter) (struct AudioAdapterManager *manager, struct
**描述：**
卸载音频适配器（声卡）的驱动
卸载音频适配器（声卡）的驱动。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| manager | 待操作的音频管理接口对象 |
| adapter | 待卸载的音频适配器接口的对象 |
| manager | 输入参数，待操作的音频管理接口对象。 |
| adapter | 输入参数，待卸载的音频适配器接口的对象。 |
**参见:**
......
zh-cn/device-dev/reference/hdi-apis/_audio_mmap_buffer_descripter.md
浏览文件 @ d5332ef7
......@@ -17,8 +17,8 @@ Mmap缓冲区描述符。
| 名称 | 描述 |
| -------- | -------- |
| [memoryAddress](_audio.md#memoryaddress) | 指向mmap缓冲区的指针 |
| [memoryFd](_audio.md#memoryfd) | mmap缓冲区的文件描述符 |
| [memoryAddress](_audio.md#memoryaddress) | 指向Mmap缓冲区的指针 |
| [memoryFd](_audio.md#memoryfd) | Mmap缓冲区的文件描述符 |
| [totalBufferFrames](_audio.md#totalbufferframes) | 缓冲区总大小，单位：帧 |
| [transferFrameSize](_audio.md#transferframesize) | 传输大小，单位：帧 |
| [isShareable](_audio.md#isshareable) | mmap缓冲区是否可以在进程间共享 |
| [isShareable](_audio.md#isshareable) | Mmap缓冲区是否可以在进程间共享 |
zh-cn/device-dev/reference/hdi-apis/_audio_render.md
浏览文件 @ d5332ef7
......@@ -5,7 +5,7 @@
AudioRender音频播放接口。
提供音频播放支持的驱动能力，包括音频控制、音频属性、音频场景、音频音量、获取硬件延迟时间、播放音频帧数据（render frame）等。
提供音频播放支持的驱动能力，包括音频控制、音频属性、音频场景、音频音量、获取硬件延迟时间、播放音频帧数据（Render frame）等。
**Since：**
......@@ -42,7 +42,7 @@ AudioRender音频播放接口。
| scene | 音频场景能力接口，详情参考[AudioScene](_audio_scene.md)。 |
| volume | 音频音量能力接口，详情参考[AudioVolume](_audio_volume.md)。 |
| ([GetLatency](#getlatency))(struct&nbsp;AudioRender&nbsp;\*render,&nbsp;uint32_t&nbsp;\*ms) | 获取音频硬件驱动估计的延迟时间。 |
| ([RenderFrame](#renderframe))(struct&nbsp;AudioRender&nbsp;\*render,&nbsp;const&nbsp;void&nbsp;\*frame,&nbsp;uint64_t&nbsp;requestBytes,&nbsp;uint64_t&nbsp;\*replyBytes) | 往音频驱动中播放（render）一帧输出数据（放音，音频下行数据）。 |
| ([RenderFrame](#renderframe))(struct&nbsp;AudioRender&nbsp;\*render,&nbsp;const&nbsp;void&nbsp;\*frame,&nbsp;uint64_t&nbsp;requestBytes,&nbsp;uint64_t&nbsp;\*replyBytes) | 往音频驱动中播放（Render）一帧输出数据（放音，音频下行数据）。 |
| ([GetRenderPosition](#getrenderposition))(struct&nbsp;AudioRender&nbsp;\*render,&nbsp;uint64_t&nbsp;\*frames,&nbsp;struct&nbsp;AudioTimeStamp&nbsp;\*time) | 获取音频输出帧数的上一次计数。 |
| ([SetRenderSpeed](#setrenderspeed))(struct&nbsp;AudioRender&nbsp;\*render,&nbsp;float&nbsp;speed) | 设置一个音频的播放速度。 |
| ([GetRenderSpeed](#getrenderspeed))(struct&nbsp;AudioRender&nbsp;\*render,&nbsp;float&nbsp;\*speed) | 获取一个音频当前的播放速度。 |
......@@ -64,18 +64,18 @@ int32_t(* AudioRender::DrainBuffer) (struct AudioRender *render, enum AudioDrain
**描述：**
排空缓冲区中的数据
排空缓冲区中的数据。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| render | 待操作的音频播放接口对象 |
| type | DrainBuffer的操作类型，详情请参考[AudioDrainNotifyType](_audio.md#audiodrainnotifytype)。 |
| render | 输入参数，待操作的音频播放接口对象。 |
| type | 输入参数，DrainBuffer的操作类型，详情请参考[AudioDrainNotifyType](_audio.md#audiodrainnotifytype)。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -91,18 +91,18 @@ int32_t(* AudioRender::GetChannelMode) (struct AudioRender *render, enum AudioCh
**描述：**
获取音频播放当前的通道模式
获取音频播放当前的通道模式。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| render | 待操作的音频播放接口对象 |
| mode | 获取的通道模式保存到mode中 |
| render | 输入参数，待操作的音频播放接口对象。|
| mode | 输出参数，获取的通道模式保存到mode中。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -118,18 +118,18 @@ int32_t(* AudioRender::GetLatency) (struct AudioRender *render, uint32_t *ms)
**描述：**
获取音频硬件驱动估计的延迟时间
获取音频硬件驱动估计的延迟时间。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| render | 待操作的音频播放接口对象 |
| ms | 获取的延迟时间（单位：毫秒）保存到ms中 |
| render | 输入参数，待操作的音频播放接口对象。 |
| ms | 输出参数，获取的延迟时间（单位：毫秒）保存到ms中。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### GetRenderPosition
......@@ -141,19 +141,19 @@ int32_t(* AudioRender::GetRenderPosition) (struct AudioRender *render, uint64_t
**描述：**
获取音频输出帧数的上一次计数
获取音频输出帧数的上一次计数。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| render | 待操作的音频播放接口对象 |
| frames | 获取的音频帧计数保存到frames中 |
| time | 获取的关联时间戳保存到time中 |
| render | 输入参数，待操作的音频播放接口对象。 |
| frames | 输出参数，获取的音频帧计数保存到frames中。 |
| time | 输出参数，获取的关联时间戳保存到time中。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -169,18 +169,18 @@ int32_t(* AudioRender::GetRenderSpeed) (struct AudioRender *render, float *speed
**描述：**
获取一个音频当前的播放速度
获取一个音频当前的播放速度。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| render | 待操作的音频播放接口对象 |
| speed | 获取的播放速度保存到speed中 |
| render | 输入参数，待操作的音频播放接口对象。 |
| speed | 输出参数，获取的播放速度保存到speed中。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -196,19 +196,19 @@ int32_t(* AudioRender::RegCallback) (struct AudioRender *render, RenderCallback
**描述：**
注册音频回调函数，用于放音过程中缓冲区数据写、DrainBuffer完成通知
注册音频回调函数，用于放音过程中缓冲区数据写、DrainBuffer完成通知。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| render | 待操作的音频播放接口对象 |
| callback | 注册的回调函数 |
| cookie | 回调函数的入参 |
| render | 输入参数，待操作的音频播放接口对象。 |
| callback | 输入参数，注册的回调函数。 |
| cookie | 输入参数，回调函数的入参。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -224,20 +224,20 @@ int32_t(* AudioRender::RenderFrame) (struct AudioRender *render, const void *fra
**描述：**
往音频驱动中播放（render）一帧输出数据（放音，音频下行数据）
向音频驱动中播放（Render）一帧输出数据（放音，音频下行数据）。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| render | 待操作的音频播放接口对象 |
| frame | 待写入的输出数据的音频frame |
| requestBytes | 待写入的输出数据的音频frame大小（字节数） |
| replyBytes | 实际写入的音频数据长度（字节数），获取后保存到replyBytes中 |
| render | 输入参数，待操作的音频播放接口对象。 |
| frame | 输入参数，待写入的输出数据的音频frame。 |
| requestBytes | 输入参数，待写入的输出数据的音频frame大小（字节数）。 |
| replyBytes | 输出参数，实际写入的音频数据长度（字节数），获取后保存到replyBytes中。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
### SetChannelMode
......@@ -249,18 +249,18 @@ int32_t(* AudioRender::SetChannelMode) (struct AudioRender *render, enum AudioCh
**描述：**
设置音频播放的通道模式
设置音频播放的通道模式。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| render | 待操作的音频播放接口对象 |
| speed | 待设置的通道模式 |
| render | 输入参数，待操作的音频播放接口对象。 |
| speed | 输入参数，待设置的通道模式。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -276,18 +276,18 @@ int32_t(* AudioRender::SetRenderSpeed) (struct AudioRender *render, float speed)
**描述：**
设置一个音频的播放速度
设置一个音频的播放速度。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| render | 待操作的音频播放接口对象 |
| speed | 待设置的播放速度 |
| render | 输入参数，待操作的音频播放接口对象。 |
| speed | 输入参数，待设置的播放速度。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......
zh-cn/device-dev/reference/hdi-apis/_audio_scene.md
浏览文件 @ d5332ef7
......@@ -43,19 +43,19 @@ int32_t(* AudioScene::CheckSceneCapability) (AudioHandle handle, const struct Au
**描述：**
是否支持某个音频场景的配置
是否支持某个音频场景的配置。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| scene | 待获取的音频场景描述符 |
| supported | 是否支持的状态保存到supported中，true表示支持，false表示不支持 |
| handle | 输入参数，待操作的音频句柄。 |
| scene | 输入参数，待获取的音频场景描述符。 |
| supported | 输出参数，是否支持的状态保存到supported中，true表示支持，false表示不支持。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -71,26 +71,26 @@ int32_t(* AudioScene::SelectScene) (AudioHandle handle, const struct AudioSceneD
**描述：**
选择音频场景
选择音频场景。
- 1. 选择一个非常具体的音频场景（应用场景和输出设备的组合），例如同样是使用手机中的喇叭作为输出设备
- 选择一个非常具体的音频场景（应用场景和输出设备的组合），例如同样是使用手机中的喇叭作为输出设备：
- 在媒体播放场景scene为media_speaker
- 在语音通话免提场景scene为voice_speaker
- 2. 只是选择一个音频场景，例如使用场景为媒体播放（media）、电影播放（movie）、游戏播放（game）
- 只是选择一个音频场景，例如使用场景为媒体播放（media）、电影播放（movie）、游戏播放（game）。
- 3. 只是选择一个音频输出设备，例如输出设备为听筒（receiver）、喇叭（speaker）、有线耳机（headset）
- 只是选择一个音频输出设备，例如输出设备为听筒（receiver）、喇叭（speaker）、有线耳机（headset）。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| scene | 待设置的音频场景描述符 |
| handle | 输入参数，待操作的音频句柄。 |
| scene | 输入参数，待设置的音频场景描述符。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......
zh-cn/device-dev/reference/hdi-apis/_audio_volume.md
浏览文件 @ d5332ef7
......@@ -5,7 +5,7 @@
AudioVolume音频音量接口。
提供音频播放（render）或录音（capture）需要的公共音量驱动能力，包括静音操作、设置音量、设置增益等。
提供音频播放（Render）或录音（Capture）需要的公共音量驱动能力，包括静音操作、设置音量、设置增益等。
**Since：**
......@@ -48,18 +48,18 @@ int32_t(* AudioVolume::GetGain) (AudioHandle handle, float *gain)
**描述：**
获取音频流的增益
获取音频流的增益。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| gain | 保存当前获取到的增益到gain中 |
| handle | 输入参数，待操作的音频句柄。 |
| gain | 输出参数，保存当前获取到的增益到gain中。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -77,7 +77,7 @@ int32_t(* AudioVolume::GetGainThreshold) (AudioHandle handle, float *min, float
**描述：**
获取音频流增益的阈值
获取音频流增益的阈值。
在具体的功能实现中，可以根据芯片平台的实际情况来进行处理：
......@@ -89,13 +89,13 @@ int32_t(* AudioVolume::GetGainThreshold) (AudioHandle handle, float *min, float
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| min | 获取的音频增益的阈值下限保存到min中 |
| max | 获取的音频增益的阈值上限保存到max中 |
| handle | 输入参数，待操作的音频句柄。 |
| min | 输出参数，获取的音频增益的阈值下限保存到min中。 |
| max | 输出参数，获取的音频增益的阈值上限保存到max中。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -113,18 +113,18 @@ int32_t(* AudioVolume::GetMute) (AudioHandle handle, bool *mute)
**描述：**
获取音频的静音状态
获取音频的静音状态。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| mute | 获取的静音状态保存到mute中，true表示静音操作、false表示取消静音操作 |
| handle | 输入参数，待操作的音频句柄。 |
| mute | 输出参数，获取的静音状态保存到mute中，true表示静音操作，false表示取消静音操作。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -140,18 +140,18 @@ int32_t(* AudioVolume::GetVolume) (AudioHandle handle, float *volume)
**描述：**
获取一个音频流的音量
获取一个音频流的音量。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| volume | 获取的音量保存到volume中，范围0.0~1.0 |
| handle | 输入参数，待操作的音频句柄。 |
| volume | 输出参数，获取的音量保存到volume中，范围0.0~1.0。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -167,18 +167,18 @@ int32_t(* AudioVolume::SetGain) (AudioHandle handle, float gain)
**描述：**
设置音频流的增益
设置音频流的增益。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| gain | gain&nbsp;待设置的增益 |
| handle | 输入参数，待操作的音频句柄。 |
| gain | 输入参数，待设置的增益。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -196,18 +196,18 @@ int32_t(* AudioVolume::SetMute) (AudioHandle handle, bool mute)
**描述：**
设置音频的静音状态
设置音频的静音状态。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| mute | 待设置的静音状态，true表示静音操作、false表示取消静音操作 |
| handle | 输入参数，待操作的音频句柄。 |
| mute | 输入参数，待设置的静音状态，true表示静音操作，false表示取消静音操作。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
**参见:**
......@@ -225,15 +225,15 @@ int32_t(* AudioVolume::SetVolume) (AudioHandle handle, float volume)
设置一个音频流的音量。
音量的取值范围是0.0~1.0，如果音频服务中的音量等级为15级（0 ~ 15）， 则音量的映射关系为0.0表示静音，1.0表示最大音量等级（15）。
音量的取值范围是0.0~1.0，如果音频服务中的音量等级为15级（0 ~ 15），则音量的映射关系为0.0表示静音，1.0表示最大音量等级（15）。
**参数:**
| 名称 | 描述 |
| -------- | -------- |
| handle | 待操作的音频句柄 |
| volume | 待设置的音量，范围0.0~1.0 |
| handle | 输入参数，待操作的音频句柄。 |
| volume | 输入参数，待设置的音量，范围0.0~1.0。 |
**返回:**
成功返回值0，失败返回负值
成功返回值0，失败返回负值。
zh-cn/device-dev/reference/hdi-apis/_ext_data_handle.md
浏览文件 @ d5332ef7
......@@ -17,6 +17,6 @@
| 名称 | 描述 |
| -------- | -------- |
| [fd](_display.md#fd) | 句柄&nbsp;fd,&nbsp;-1代表不支持。 |
| [fd](_display.md#fd) | 句柄fd，-1代表不支持。 |
| [reserveInts](_display.md#reserveints) | reserve数组的个数。 |
| [reserve](_display.md#reserve)&nbsp;[0] | reserve数组。 |
zh-cn/device-dev/reference/hdi-apis/_i_wlan_interface_8idl.md
浏览文件 @ d5332ef7
......@@ -3,9 +3,7 @@
## **概述**
建立/关闭WLAN热点，扫描/关联/去关联WLAN热点，设置国家码，管理网络设备等操作的接口。
上层服务调用相关的接口实现：建立/关闭WLAN热点，扫描/关联/去关联WLAN热点，设置国家码，管理网络设备等功能。
WLAN模块操作接口，上层服务调用相关的接口可实现：建立/关闭WLAN热点，扫描/关联/去关联WLAN热点，设置国家码，管理网络设备等功能。
**Since:**
......
zh-cn/device-dev/reference/hdi-apis/_wlan_types_8idl.md
浏览文件 @ d5332ef7
......@@ -3,8 +3,6 @@
## **概述**
WLAN模块相关的数据类型。
WLAN模块中使用的数据类型，包括feature对象信息、STA信息、扫描信息、网络设备信息等。
**Since:**
......
zh-cn/device-dev/reference/hdi-apis/codec__component__type_h.md
浏览文件 @ d5332ef7
......@@ -3,7 +3,6 @@
## **概述**
Codec模块接口定义中使用的自定义数据类型。
Codec模块接口定义中使用的自定义数据类型，包括编解码类型、音视频参数、buffer定义等。
......
zh-cn/device-dev/reference/hdi-apis/display__type_8h.md
浏览文件 @ d5332ef7
......@@ -52,7 +52,7 @@
| 名称 | 描述 |
| -------- | -------- |
| [PROPERTY_NAME_LEN](_display.md#propertynamelen)&nbsp;&nbsp;&nbsp;50 | 属性名字长度。 |
| [PROPERTY_NAME_LEN](_display.md#property_name_len)&nbsp;&nbsp;50 | 属性名字长度。 |
### 枚举
......
zh-cn/device-dev/reference/hdi-apis/input__type_8h.md
浏览文件 @ d5332ef7
......@@ -44,17 +44,17 @@ Input设备相关的类型定义。
| 名称 | 描述 |
| -------- | -------- |
| [MAX_INPUT_DEV_NUM](input.md#maxinputdevnum)&nbsp;&nbsp;&nbsp;32 | Input设备数量的最大值。 |
| [CHIP_INFO_LEN](input.md#chipinfolen)&nbsp;&nbsp;&nbsp;10 | 芯片信息长度。 |
| [CHIP_NAME_LEN](input.md#chipnamelen)&nbsp;&nbsp;&nbsp;10 | 芯片名称长度。 |
| [VENDOR_NAME_LEN](input.md#vendornamelen)&nbsp;&nbsp;&nbsp;10 | 厂商名称长度。 |
| [DEV_NAME_LEN](input.md#devnamelen)&nbsp;&nbsp;&nbsp;64 | Input设备名称长度。 |
| [SELF_TEST_RESULT_LEN](input.md#selftestresultlen)&nbsp;&nbsp;&nbsp;20 | 自测结果长度。 |
| [DEV_MANAGER_SERVICE_NAME](input.md#devmanagerservicename)&nbsp;&nbsp;&nbsp;"hdf_input_host" | Input设备节点服务名称。 |
| [DIV_ROUND_UP](input.md#divroundup)(nr,&nbsp;d)&nbsp;&nbsp;&nbsp;(((nr)&nbsp;+&nbsp;(d)&nbsp;-&nbsp;1)&nbsp;/&nbsp;(d)) | 向上取整计算公式。 |
| [BYTE_HAS_BITS](input.md#bytehasbits)&nbsp;&nbsp;&nbsp;8 | 一个字节所包含的比特数。 |
| [BITS_TO_UINT64](input.md#bitstouint64)(count)&nbsp;&nbsp;&nbsp;[DIV_ROUND_UP](input.md#divroundup)(count,&nbsp;[BYTE_HAS_BITS](input.md#bytehasbits)&nbsp;\*&nbsp;sizeof(uint64_t)) | 比特与64位无符号整数的转换公式。 |
| [HDF_FF_CNT](input.md#hdfffcnt)&nbsp;&nbsp;&nbsp;(0x7f&nbsp;+&nbsp;1) | Input设备发送力反馈命令的数量最大值。 |
| [MAX_INPUT_DEV_NUM](input.md#max_input_dev_num)&nbsp;&nbsp;&nbsp;32 | Input设备数量的最大值。 |
| [CHIP_INFO_LEN](input.md#chip_info_len)&nbsp;&nbsp;&nbsp;10 | 芯片信息长度。 |
| [CHIP_NAME_LEN](input.md#chip_name_len)&nbsp;&nbsp;&nbsp;10 | 芯片名称长度。 |
| [VENDOR_NAME_LEN](input.md#vendor_name_len)&nbsp;&nbsp;&nbsp;10 | 厂商名称长度。 |
| [DEV_NAME_LEN](input.md#dev_name_len)&nbsp;&nbsp;&nbsp;64 | Input设备名称长度。 |
| [SELF_TEST_RESULT_LEN](input.md#self_test_result_len)&nbsp;&nbsp;&nbsp;20 | 自测结果长度。 |
| [DEV_MANAGER_SERVICE_NAME](input.md#dev_manager_service_name)&nbsp;&nbsp;&nbsp;"hdf_input_host" | Input设备节点服务名称。 |
| [DIV_ROUND_UP](input.md#div_round_up)(nr,&nbsp;d)&nbsp;&nbsp;&nbsp;(((nr)&nbsp;+&nbsp;(d)&nbsp;-&nbsp;1)&nbsp;/&nbsp;(d)) | 向上取整计算公式。 |
| [BYTE_HAS_BITS](input.md#byte_has_bits)&nbsp;&nbsp;&nbsp;8 | 一个字节所包含的比特数。 |
| [BITS_TO_UINT64](input.md#bits_to_uint64)(count)&nbsp;&nbsp;&nbsp;[DIV_ROUND_UP](input.md#div_round_up)(count,&nbsp;[BYTE_HAS_BITS](input.md#byte_has_bits)&nbsp;\*&nbsp;sizeof(uint64_t)) | 比特与64位无符号整数的转换公式。 |
| [HDF_FF_CNT](input.md#hdf_ff_cnt)&nbsp;&nbsp;&nbsp;(0x7f&nbsp;+&nbsp;1) | Input设备发送力反馈命令的数量最大值。 |
### 枚举
......
zh-cn/device-dev/reference/hdi-apis/sensor.md
浏览文件 @ d5332ef7
......@@ -3,9 +3,9 @@
## **概述**
提供休眠/唤醒操作、订阅休眠/唤醒状态、运行锁管理的接口。
传感器设备驱动对传感器服务提供通用的接口能力。
电源模块为电源服务提供的休眠/唤醒操作、订阅休眠/唤醒状态和运行锁管理的接口。 服务获取此模块的对象或代理后，可以调用相关的接口对设备进行休眠/唤醒、订阅休眠/唤醒状态和管理运行锁。
模块提供传感器服务对传感器驱动访问统一接口，服务获取驱动对象或者代理后，通过其提供的各类方法，以传感器ID区分访问不同类型传感器设备，实现获取传感器设备信息、订阅/取消订阅传感器数据、 使能/去使能传感器、设置传感器模式、设置传感器精度、量程等可选配置等。
**Since**:
......@@ -24,7 +24,7 @@
| 名称 | 描述 |
| -------- | -------- |
| [ISensorCallback.idl](_i_sensor_callback_8idl.md) | Sensor模块为Sensor服务提供数据上报的回调函数。 |
| [ISensorInterface.idl](_i_sensor_interface_8idl.md) | Sensor模块对外通用的接口声明文件，提供获取传感器设备信息、订阅/取消订阅传感器数据、&nbsp;使能/去使能传感器、设置传感器模式、设置传感器精度，量程等可选配置接口定义。 |
| [ISensorInterface.idl](_i_sensor_interface_8idl.md) | Sensor模块对外通用的接口声明文件，提供获取传感器设备信息、订阅/取消订阅传感器数据、使能/去使能传感器、设置传感器模式、设置传感器精度，量程等可选配置接口定义。 |
| [SensorTypes.idl](_sensor_types_8idl.md) | 定义传感器模块所使用的传感器类型，传感器信息，传感器数据结构等数据类型。 |
......
zh-cn/device-dev/subsystems/subsys-build-module.md
浏览文件 @ d5332ef7
......@@ -25,7 +25,7 @@ ohos_resources
#其他常用模板
#配置文件
ohos_prebuild_etc
ohos_prebuilt_etc
#sa配置
ohos_sa_profile
......
zh-cn/device-dev/subsystems/subsys-dfx-hitracemeter.md
浏览文件 @ d5332ef7
......@@ -76,7 +76,7 @@ HiTraceMeter主要提供抓取用户态和内核态Trace数据的命令行工具
![输入图片说明](../../figures/Hitrace.png)
![输入图片说明](figures/HiTraceMeter.png)
......@@ -108,8 +108,8 @@ C++接口仅系统开发者使用，JS（目前暂未开放js接口）应用开
| Sync trace | 功能描述 |参数说明 |
| :----------------------------------------------------------- | ------------- |------------- |
| void StartTrace(uint64_t label, const std::string& value, float limit = -1); | 启动同步trace |label: Trace category。 |
| void FinishTrace(uint64_t label); | 关闭同步trace |value: Trace携带的信息，表明当前的某种状态，例如内存大小，队列长短等。 |
| void StartTrace(uint64_t label, const std::string& value, float limit = -1); | 启动同步trace |label: Trace category。<br />value: Trace携带的信息，表明当前的某种状态，例如内存大小，队列长短等。 |
| void FinishTrace(uint64_t label); | 关闭同步trace |label: Trace category。 |
同步接口StartTrace和FinishTrace必须配对使用，FinishTrace和前面最近的StartTrace进行匹配。StartTrace和FinishTrace函数对可以嵌套模式使用，跟踪数据解析时使用栈式数据结构进行匹配。接口中的limit参数用于限流，使用默认值即可。
......@@ -118,9 +118,8 @@ C++接口仅系统开发者使用，JS（目前暂未开放js接口）应用开
| Async trace | 功能描述 |参数说明 |
| ------------------------------------------------------------ | ------------- |------------- |
| void StartAsyncTrace(uint64_t label, const std::string& value, int32_t taskId, float limit = -1); | 开启异步trace | label: Trace category。 |
| void FinishAsyncTrace(uint64_t label, const std::string& value, int32_t taskId); | 关闭异步trace | value: Trace携带的信息，表明当前的某种状态，例如内存大小，队列长短等。|
| | | taskId：异步Trace中用来表示关联的ID。 |
| void StartAsyncTrace(uint64_t label, const std::string& value, int32_t taskId, float limit = -1); | 开启异步trace | label: Trace category。<br />value: Trace携带的信息，表明当前的某种状态，例如内存大小，队列长短等。<br />taskId：异步Trace中用来表示关联的ID。 |
| void FinishAsyncTrace(uint64_t label, const std::string& value, int32_t taskId); | 关闭异步trace | label: Trace category。<br />value: Trace携带的信息，表明当前的某种状态，例如内存大小，队列长短等。<br />taskId：异步Trace中用来表示关联的ID。 |
......@@ -130,8 +129,7 @@ C++接口仅系统开发者使用，JS（目前暂未开放js接口）应用开
| Counter Trace | 功能描述 |参数说明 |
| ------------------------------------------------------------ | --------- |--------- |
| void CountTrace(uint64_t label, const std::string& name, int64_t); | 计数trace |label: Trace category。。 |
| | |name: Trace的名称，IDE中会以此字段展示这段Trace。 |
| void CountTrace(uint64_t label, const std::string& name, int64_t); | 计数trace |label: Trace category。<br />name: Trace的名称，IDE中会以此字段展示这段Trace。 |
## 开发步骤
......@@ -142,7 +140,7 @@ C++接口仅系统开发者使用，JS（目前暂未开放js接口）应用开
```
2. 头文件依赖添加。
```
```cpp
#include "hitrace_meter.h"//接口函数定义头文件
```
......@@ -150,39 +148,39 @@ C++接口仅系统开发者使用，JS（目前暂未开放js接口）应用开
```cpp
#include "hitrace_meter.h" // 包含hitrace_meter.h
using namespace std;
#include "hitrace_meter.h" // 包含hitrace_meter.h
using namespace std;
int main()
{
uint64_t label = BYTRACE_TAG_OHOS;
sleep(1);
CountTrace(label, "count number", 2000); // 整数跟踪
StartTrace(label, "func1Trace", -1); // func1Start的跟踪起始点
sleep(1);
StartTrace(label, "func2Trace", -1); // func2Start的跟踪起始点
sleep(2);
FinishTrace(label); // func2Trace的结束点
sleep(1);
FinishTrace(label); // func1Trace的结束点
sleep(1);
CountTrace(label, "count number", 3000); // 整数跟踪
StartAsyncTrace(label, "asyncTrace1", 1234); // 异步asyncTrace1的开始点
sleep(1);
StartAsyncTrace(label, "asyncTrace2", 3456); // 异步asyncTrace2的开始点
StartAsyncTrace(label, "asyncTrace3", 5678); // 异步asyncTrace3的开始点
sleep(1);
FinishAsyncTrace(label, "asyncTrace3", 5678); // 异步asyncTrace3的结束点
sleep(1);
FinishAsyncTrace(label, "asyncTrace1", 1234); // 异步asyncTrace1的结束点
sleep(1);
FinishAsyncTrace(label, "asyncTrace2", 3456); // 异步asyncTrace2的结束点
return 0;
}
int main()
{
uint64_t label = BYTRACE_TAG_OHOS;
sleep(1);
CountTrace(label, "count number", 2000); // 整数跟踪
StartTrace(label, "func1Trace", -1); // func1Start的跟踪起始点
sleep(1);
StartTrace(label, "func2Trace", -1); // func2Start的跟踪起始点
sleep(2);
FinishTrace(label); // func2Trace的结束点
sleep(1);
FinishTrace(label); // func1Trace的结束点
sleep(1);
CountTrace(label, "count number", 3000); // 整数跟踪
StartAsyncTrace(label, "asyncTrace1", 1234); // 异步asyncTrace1的开始点
sleep(1);
StartAsyncTrace(label, "asyncTrace2", 3456); // 异步asyncTrace2的开始点
StartAsyncTrace(label, "asyncTrace3", 5678); // 异步asyncTrace3的开始点
sleep(1);
FinishAsyncTrace(label, "asyncTrace3", 5678); // 异步asyncTrace3的结束点
sleep(1);
FinishAsyncTrace(label, "asyncTrace1", 1234); // 异步asyncTrace1的结束点
sleep(1);
FinishAsyncTrace(label, "asyncTrace2", 3456); // 异步asyncTrace2的结束点
return 0;
}
```
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或