diff --git a/en/application-dev/reference/apis/js-apis-contact.md b/en/application-dev/reference/apis/js-apis-contact.md index 022394ac0493a3f2b66eed1c0b5af9b02bdab334..67b846c17b94a6acee894da72ae28cedefd2532c 100644 --- a/en/application-dev/reference/apis/js-apis-contact.md +++ b/en/application-dev/reference/apis/js-apis-contact.md @@ -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.| diff --git a/en/application-dev/reference/apis/js-apis-hidebug.md b/en/application-dev/reference/apis/js-apis-hidebug.md index 5620062988d8b16d374f7cfc010e2b77b378cb3a..469fcae6f1c0f82f0894422b3e2a4416fabc7a60 100644 --- a/en/application-dev/reference/apis/js-apis-hidebug.md +++ b/en/application-dev/reference/apis/js-apis-hidebug.md @@ -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.getPrivateDirty9+ @@ -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. | diff --git a/en/application-dev/reference/apis/js-apis-net-connection.md b/en/application-dev/reference/apis/js-apis-net-connection.md index ec63d11121dcd5138d11d7a2e1898833deaaf9c7..1d272e9f03c4956e141456324b1eb1f05293cea8 100644 --- a/en/application-dev/reference/apis/js-apis-net-connection.md +++ b/en/application-dev/reference/apis/js-apis-net-connection.md @@ -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<Array<[NetHandle](#nethandle)>> | 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<Array<[NetHandle](#nethandle)>> | 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<void> | 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<void> | 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 | | ----------------------------------- | ------------------------------- | diff --git a/zh-cn/application-dev/Readme-CN.md b/zh-cn/application-dev/Readme-CN.md index 70a832e1fcb12e85d4fc742b171fd9bb33a1db23..4743c1e020b9e08362342363ba79178e9c07139e 100644 --- a/zh-cn/application-dev/Readme-CN.md +++ b/zh-cn/application-dev/Readme-CN.md @@ -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) diff --git a/zh-cn/application-dev/application-test/arkxtest-guidelines.md b/zh-cn/application-dev/application-test/arkxtest-guidelines.md new file mode 100644 index 0000000000000000000000000000000000000000..410547a5d0ef493f9cee83b670b7a391023fb6e2 --- /dev/null +++ b/zh-cn/application-dev/application-test/arkxtest-guidelines.md @@ -0,0 +1,171 @@ +# 自动化测试框架使用指南 + + +## 概述 + +为支撑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) diff --git a/zh-cn/application-dev/application-test/figures/Execute.PNG b/zh-cn/application-dev/application-test/figures/Execute.PNG new file mode 100644 index 0000000000000000000000000000000000000000..49155c9b3406ea477e08273818e52fe026a62737 Binary files /dev/null and b/zh-cn/application-dev/application-test/figures/Execute.PNG differ diff --git a/zh-cn/application-dev/application-test/figures/TestFlow.PNG b/zh-cn/application-dev/application-test/figures/TestFlow.PNG new file mode 100644 index 0000000000000000000000000000000000000000..c1cd0d4e87070a5af4b7c8d72432a55585754551 Binary files /dev/null and b/zh-cn/application-dev/application-test/figures/TestFlow.PNG differ diff --git a/zh-cn/application-dev/application-test/figures/TestResult.PNG b/zh-cn/application-dev/application-test/figures/TestResult.PNG new file mode 100644 index 0000000000000000000000000000000000000000..300266842efab6da7a4f7469ab8c9e890f238b89 Binary files /dev/null and b/zh-cn/application-dev/application-test/figures/TestResult.PNG differ diff --git a/zh-cn/application-dev/application-test/figures/Uitest.PNG b/zh-cn/application-dev/application-test/figures/Uitest.PNG new file mode 100644 index 0000000000000000000000000000000000000000..2e84b95e4b0e61d78351e46a4ac2706e7847c6e2 Binary files /dev/null and b/zh-cn/application-dev/application-test/figures/Uitest.PNG differ diff --git a/zh-cn/application-dev/application-test/figures/UnitTest.PNG b/zh-cn/application-dev/application-test/figures/UnitTest.PNG new file mode 100644 index 0000000000000000000000000000000000000000..a7af248d62e34bda8e02be095bcdb73c15e97a3f Binary files /dev/null and b/zh-cn/application-dev/application-test/figures/UnitTest.PNG differ diff --git a/zh-cn/application-dev/media/audio-playback.md b/zh-cn/application-dev/media/audio-playback.md index 5a63c2fc33fab83623b8de9a1b1c8497d5790742..3ca354a1305c8e1282367633aba33c3c098bbac7 100644 --- a/zh-cn/application-dev/media/audio-playback.md +++ b/zh-cn/application-dev/media/audio-playback.md @@ -1,28 +1,34 @@ # 音频播放开发指导 -## 场景介绍 +## 简介 -音频播放的主要工作是将音频数据转码为可听见的音频模拟信号并通过输出设备进行播放，同时对播放任务进行管理。 +音频播放的主要工作是将音频数据转码为可听见的音频模拟信号，并通过输出设备进行播放，同时对播放任务进行管理，包括开始播放、暂停播放、停止播放、释放资源、设置音量、跳转播放位置、获取轨道信息等功能控制。 -**图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_属性) diff --git a/zh-cn/application-dev/media/audio-recorder.md b/zh-cn/application-dev/media/audio-recorder.md index 21fe9c01ad216b331e5c2e708397bfdce4672a4d..94215fe834e26b66115046fbe543137371ed5912 100644 --- a/zh-cn/application-dev/media/audio-recorder.md +++ b/zh-cn/application-dev/media/audio-recorder.md @@ -1,26 +1,36 @@ # 音频录制开发指导 -## 场景介绍 +## 简介 -音频录制的主要工作是捕获音频信号，完成音频编码并保存到文件中，帮助开发者轻松实现音频录制功能。它允许调用者指定音频录制的采样率、声道数、编码格式、封装格式、文件路径等参数。 +音频录制的主要工作是捕获音频信号，完成音频编码并保存到文件中，帮助开发者轻松实现音频录制功能。该模块允许调用者指定音频录制的采样率、声道数、编码格式、封装格式、输出文件的路径等参数。 -**图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' diff --git a/zh-cn/application-dev/media/video-playback.md b/zh-cn/application-dev/media/video-playback.md index 040b9b479adce001468631ae6920321be06dc894..b9f30aab7ed944d3a702adc002d6e18627b31414 100644 --- a/zh-cn/application-dev/media/video-playback.md +++ b/zh-cn/application-dev/media/video-playback.md @@ -1,17 +1,23 @@ # 视频播放开发指导 -## 场景介绍 +## 简介 -视频播放的主要工作是将视频数据转码并输出到设备进行播放，同时管理播放任务。本文将对视频播放全流程、视频切换、视频循环播放等场景开发进行介绍说明。 +视频播放的主要工作是将视频数据转码并输出到设备进行播放，同时管理播放任务，包括开始播放、暂停播放、停止播放、资源释放、音量设置、跳转播放位置、设置倍数、获取轨道信息等功能控制。本文将对视频播放全流程、视频切换、视频循环播放等场景开发进行介绍说明。 -**图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_属性) diff --git a/zh-cn/application-dev/media/video-recorder.md b/zh-cn/application-dev/media/video-recorder.md index 3be9de0cbb47ea787f1861fba9f32aa423fd935a..07b83bdf86217f38bfb47d8fa0850ed8349d4e96 100644 --- a/zh-cn/application-dev/media/video-recorder.md +++ b/zh-cn/application-dev/media/video-recorder.md @@ -1,24 +1,34 @@ # 视频录制开发指导 -## 场景介绍 +## 简介 -视频录制的主要工作是捕获音视频信号，完成音视频编码并保存到文件中，帮助开发者轻松实现音视频录制功能。它允许调用者指定录制的编码格式、封装格式、文件路径等参数。 +视频录制的主要工作是捕获音视频信号，完成音视频编码并保存到文件中，帮助开发者轻松实现音视频录制功能，包括开始录制、暂停录制、恢复录制、停止录制、释放资源等功能控制。它允许调用者指定录制的编码格式、封装格式、文件路径等参数。 -**图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' diff --git a/zh-cn/application-dev/notification/Readme-CN.md b/zh-cn/application-dev/notification/Readme-CN.md index a85b267052b65b947b5cfd34d25ca940add25804..02b3a06e412f3617b2db876b92bf673e46d4914f 100644 --- a/zh-cn/application-dev/notification/Readme-CN.md +++ b/zh-cn/application-dev/notification/Readme-CN.md @@ -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 diff --git a/zh-cn/application-dev/quick-start/Readme-CN.md b/zh-cn/application-dev/quick-start/Readme-CN.md index 58a1eb04c23c9ef05efbc29c9ad77e0156525581..0789c9dcef1e697ea822f28a1939588495204758 100755 --- a/zh-cn/application-dev/quick-start/Readme-CN.md +++ b/zh-cn/application-dev/quick-start/Readme-CN.md @@ -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) - 开发基础知识 diff --git a/zh-cn/application-dev/quick-start/start-overview.md b/zh-cn/application-dev/quick-start/start-overview.md index 0834b0f2e2ea1b612027a5db9ebd43a854ead7c3..8b3da7d45a8f15236dcd3ed13f3fecceff8589f4 100644 --- a/zh-cn/application-dev/quick-start/start-overview.md +++ b/zh-cn/application-dev/quick-start/start-overview.md @@ -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)中的任一章节进行下一步体验和学习。 diff --git a/zh-cn/application-dev/quick-start/start-with-ets-fa.md b/zh-cn/application-dev/quick-start/start-with-ets-fa.md index 67029223fecfe851231b29a186dd886cc48d0364..7dc4539e81e291b8b5f79774f4b69752588ad7bc 100644 --- a/zh-cn/application-dev/quick-start/start-with-ets-fa.md +++ b/zh-cn/application-dev/quick-start/start-with-ets-fa.md @@ -1,4 +1,4 @@ -# 使用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)吧。 diff --git a/zh-cn/application-dev/quick-start/start-with-ets-stage.md b/zh-cn/application-dev/quick-start/start-with-ets-stage.md index 33a404e1cc73a1cf5ee03e725cfc3ce8d4f8da81..8ff628f5a300a4257f6414431ef32d9e037e62f2 100644 --- a/zh-cn/application-dev/quick-start/start-with-ets-stage.md +++ b/zh-cn/application-dev/quick-start/start-with-ets-stage.md @@ -1,4 +1,4 @@ -# 使用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)吧。 diff --git a/zh-cn/application-dev/reference/apis/js-apis-camera.md b/zh-cn/application-dev/reference/apis/js-apis-camera.md index 5bad8bf8c1cb69f43ae5cb9a469f70fb3572a261..1f7ab803f4c4d48b2cefcfa7874461b553f02cd5 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-camera.md +++ b/zh-cn/application-dev/reference/apis/js-apis-camera.md @@ -20,9 +20,9 @@ getCameraManager(context: Context, callback: AsyncCallback): voi **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------------- | ---- | ---------------------------------- | -| context | Context | 是 | 应用上下文。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------- | ---- | ---------------------------- | +| context | Context | 是 | 应用上下文。 | | callback | AsyncCallback<[CameraManager](#cameramanager)\> | 是 | 回调函数，用于获取相机管理器实例。 | **示例：** @@ -30,7 +30,7 @@ getCameraManager(context: Context, callback: AsyncCallback): voi ```js camera.getCameraManager(context, (err, cameraManager) => { if (err) { - console.error('Failed to get the CameraManager instance ${err.message}'); + console.error(`Failed to get the CameraManager instance ${err.message}`); return; } console.log('Callback returned with the CameraManager instance'); @@ -53,8 +53,8 @@ getCameraManager(context: Context): Promise **返回值：** -| 类型 | 说明 | -| ----------------------------------------- | ----------------------------------------- | +| 类型 | 说明 | +| ----------------------------------------- | ----------------------------------- | | Promise<[CameraManager](#cameramanager)\> | 使用Promise的方式获取一个相机管理器实例。 | **示例：** @@ -73,952 +73,969 @@ camera.getCameraManager(context).then((cameraManager) => { | 名称 | 值 | 说明 | | ------------------------- | ---- | ------------ | -| CAMERA_STATUS_APPEAR | 0 | 相机存在。 | -| CAMERA_STATUS_DISAPPEAR | 1 | 相机不存在。 | -| CAMERA_STATUS_AVAILABLE | 2 | 相机就绪。 | -| CAMERA_STATUS_UNAVAILABLE | 3 | 相机未就绪。 | +| CAMERA_STATUS_APPEAR | 0 | 新的相机出现。 | +| CAMERA_STATUS_DISAPPEAR | 1 | 相机被移除。 | +| CAMERA_STATUS_AVAILABLE | 2 | 相机可用。 | +| CAMERA_STATUS_UNAVAILABLE | 3 | 相机不可用。 | +## Profile -## CameraPosition - -枚举，相机方向。 - -**系统能力：** SystemCapability.Multimedia.Camera.Core - -| 名称 | 值 | 说明 | -| --------------------------- | ---- | ---------------- | -| CAMERA_POSITION_UNSPECIFIED | 0 | 未指定方向相机。 | -| CAMERA_POSITION_BACK | 1 | 后置相机。 | -| CAMERA_POSITION_FRONT | 2 | 前置相机。 | - -## CameraType - -枚举，相机类型。 +相机配置信息项。 **系统能力：** SystemCapability.Multimedia.Camera.Core -| 名称 | 值 | 说明 | -| ----------------------- | ---- | ---------------- | -| CAMERA_TYPE_UNSPECIFIED | 0 | 未指定相机类型。 | -| CAMERA_TYPE_WIDE_ANGLE | 1 | 广角相机。 | -| CAMERA_TYPE_ULTRA_WIDE | 2 | 超级广角相机。 | -| CAMERA_TYPE_TELEPHOTO | 3 | 长焦相机。 | -| CAMERA_TYPE_TRUE_DEPTH | 4 | 深度相机。 | - +| 名称 | 类型 | 只读 | 说明 | +| -------- | ----------------------------- |---- | ------------- | +| format | [CameraFormat](#cameraformat) | 是 | 输出格式。 | +| size | [Size](#size) | 是 | 分辨率。 | -## ConnectionType +## VideoProfile -枚举，相机连接类型。 +视频配置信息项。 **系统能力：** SystemCapability.Multimedia.Camera.Core -| 名称 | 值 | 说明 | -| ---------------------------- | ---- | ------------- | -| CAMERA_CONNECTION_BUILT_IN | 0 | 内置相机。 | -| CAMERA_CONNECTION_USB_PLUGIN | 1 | 外置USB相机。 | -| CAMERA_CONNECTION_REMOTE | 2 | 分布式相机。 | +| 名称 | 类型 | 只读 | 说明 | +| ------------------------- | ----------------------------------------- | --- |----------- | +| format | [CameraFormat](#cameraformat) | 是 | 输出格式。 | +| size | [Size](#size) | 是 | 分辨率。 | +| frameRate | Array | 是 | 帧率。 | -## Size +## CameraOutputCapability -用于表示相机预览、照片、视频支持的尺寸大小。 +相机输出能力项。 **系统能力：** SystemCapability.Multimedia.Camera.Core -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------ | ------ | ---- | ---- | ------------ | -| height | string | 是 | 是 | 图像的高度。 | -| width | number | 是 | 是 | 图像的宽度。 | +| 名称 | 类型 | 只读 | 说明 | +| ----------------------------- | -------------------------------------------------- | --- |------------------- | +| previewProfiles | Array<[Profile](#profile)\> | 是 | 支持的预览配置信息。 | +| photoProfiles | Array<[Profile](#profile)\> | 是 | 支持的拍照配置信息。 | +| videoProfiles | Array<[VideoProfile](#videoprofile)\> | 是 | 支持的录像配置信息。 | +| supportedMetadataObjectTypes | Array<[MetadataObjectType](#metadataobjecttype)\> | 是 | 支持的metadata流类型信息。| ## CameraManager 相机管理器类，使用前需要通过getCameraManager获取相机管理实例。 -### getCameras +### getSupportedCameras -getCameras(callback: AsyncCallback\>): void +getSupportedCameras(callback: AsyncCallback\>): void -异步获取设备支持的相机列表，通过注册回调函数获取结果。 +获取支持指定的相机设备对象，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------- | ---- | ------------------------------------ | -| callback | AsyncCallback\> | 是 | 使用callback方式获取支持的相机列表。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------- | ---- | ------------------------------- | +| callback | AsyncCallback\> | 是 | 使用callback方式获取支持的相机列表。 | **示例：** ```js -cameraManager.getCameras((err, cameras) => { +cameraManager.getSupportedCameras((err, cameras) => { if (err) { - console.error('Failed to get the cameras. ${err.message}'); + console.error(`Failed to get the cameras. ${err.message}`); return; } - console.log('Callback returned with an array of supported cameras: ' + cameras.length); + console.log(`Callback returned with an array of supported cameras: ${cameras.length}`); }) ``` -### getCameras +### getSupportedCameras -getCameras(): Promise\> +getSupportedCameras(): Promise\> -异步获取设备支持的相机列表，通过Promise获取结果。 +获取支持指定的相机设备对象，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **返回值：** -| 类型 | 说明 | -| ----------------------------------- | ----------------------------- | -| Promise\> | 使用promise获取支持相机列表。 | +| 类型 | 说明 | +| ----------------------------------------------- | ------------------------- | +| Promise\> | 使用promise获取支持相机列表。 | **示例：** ```js -cameraManager.getCameras().then((cameraArray) => { - console.log('Promise returned with an array of supported cameras: ' + cameraArray.length); +cameraManager.getSupportedCameras().then((cameraArray) => { + console.log(`Promise returned with an array of supported cameras: ${cameraArray.length}`); }) ``` -### createCameraInput - -createCameraInput(cameraId: string, callback: AsyncCallback): void +### getSupportedOutputCapability -使用相机ID异步创建CameraInput实例，通过注册回调函数获取结果。 +getSupportedOutputCapability(callback: AsyncCallback): void -**需要权限：** ohos.permission.CAMERA +查询相机设备在模式下支持的输出能力，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------- | ---- | ----------------------------------- | -| cameraId | string | 是 | 指定相机ID。 | -| callback | AsyncCallback<[CameraInput](#camerainput)\> | 是 | 回调函数，用于获取CameraInput实例。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------------------- | -- | -------------------------- | +| callback | AsyncCallback<[CameraOutputCapability](#cameraoutputcapability)\> | 是 | 使用callback方式获取相机输出能力。 | **示例：** ```js -cameraManager.createCameraInput(cameraId, (err, cameraInput) => { +cameraManager.getSupportedOutputCapability((err, cameras) => { if (err) { - console.error('Failed to create the CameraInput instance. ${err.message}'); + console.error(`Failed to get the cameras. ${err.message}`); return; } - console.log('Callback returned with the CameraInput instance.'); + console.log('Callback returned with an array of supported outputCapability'); }) ``` -### createCameraInput - -createCameraInput(cameraId: string): Promise +### getSupportedOutputCapability -使用相机ID异步创建CameraInput实例，通过Promise获取结果。 +getSupportedOutputCapability(): Promise -**需要权限：** ohos.permission.CAMERA +查询相机设备在模式下支持的输出能力，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | ------------ | -| cameraId | string | 是 | 指定相机ID。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | --------------------------------- | ---- | ---------- | +| camera | [CameraDevice](#cameradevice) | 是 | CameraDevice对象。| **返回值：** -| 类型 | 说明 | -| ------------------------------------- | ---------------------------------------- | -| Promise<[CameraInput](#camerainput)\> | 使用Promise的方式获取CameraInput的实例。 | +| 类型 | 说明 | +| -------------------------------------------------------------- | ----------------------------- | +| Promise<[CameraOutputCapability](#cameraoutputcapability)\> | 使用Promise的方式获取结果，返回相机输出能力。 | + **示例：** ```js -cameraManager.createCameraInput(cameraId).then((cameraInput) => { - console.log('Promise returned with the CameraInput instance'); +cameraManager.getSupportedOutputCapability().then((cameraoutputcapability) => { + console.log('Promise returned with an array of supported outputCapability'); }) ``` -### createCameraInput - -createCameraInput(position: CameraPosition, type: CameraType, callback: AsyncCallback): void +### getSupportedMetadataObjectType -使用相机位置和相机类型异步创建CameraInput实例，通过注册回调函数获取结果。 +getSupportedMetadataObjectType(callback: AsyncCallback\>): void -**需要权限：** ohos.permission.CAMERA +查询相机设备支持的元能力信息，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------- | ---- | ----------------------------------- | -| position | [CameraPosition](#cameraposition) | 是 | 相机位置。 | -| type | [CameraType](#cameratype) | 是 | 相机类型。 | -| callback | AsyncCallback<[CameraInput](#camerainput)\> | 是 | 回调函数，用于获取CameraInput实例。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------------------------------- | -- | -------------------------- | +| callback | AsyncCallback\> | 是 | 使用callback方式获取相机支持的元能力力信息。 | **示例：** ```js -cameraManager.createCameraInput(camera.CameraPosition.CAMERA_POSITION_BACK, camera.CameraType.CAMERA_TYPE_UNSPECIFIED, (err, cameraInput) => { +cameraManager.getSupportedMetadataObjectType((err, metadataobject) => { if (err) { - console.error('Failed to create the CameraInput instance. ${err.message}'); + console.error(`Failed to get the supported metadataObjectType. ${err.message}`); return; } - console.log('Callback returned with the CameraInput instance'); + console.log('Callback returned with an array of supported metadataObjectType.' ); }) ``` -### createCameraInput - -createCameraInput(position: CameraPosition, type: CameraType): Promise +### getSupportedMetadataObjectType -使用相机位置和相机类型异步创建CameraInput实例，通过Promise获取结果。 +getSupportedMetadataObjectType(): Promise -**需要权限：** ohos.permission.CAMERA +查询相机设备支持的元能力信息，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core -**参数：** - -| 名称 | 类型 | 必填 | 说明 | -| -------- | --------------------------------- | ---- | ---------- | -| position | [CameraPosition](#cameraposition) | 是 | 相机位置。 | -| type | [CameraType](#cameratype) | 是 | 相机类型。 | - **返回值：** -| 类型 | 说明 | -| ------------------------------------- | ---------------------------------------- | -| Promise<[CameraInput](#camerainput)\> | 使用Promise的方式获取CameraInput的实例。 | +| 类型 | 说明 | +| -------------------------------------------------------------- | ----------------------------- | +| Promise\> | 使用Promise的方式获取结果，返回相机支持的元能力信息。 | + **示例：** ```js -cameraManager.createCameraInput(camera.CameraPosition.CAMERA_POSITION_BACK, camera.CameraType.CAMERA_TYPE_UNSPECIFIED).then((cameraInput) => { - console.log('Promise returned with the CameraInput instance.'); +cameraManager.getSupportedMetadataObjectType().then((metadataobject) => { + console.log('Promise returned with an array of supported metadataObjectType.' ); }) ``` -### on('cameraStatus') +### createCameraInput -on(type: 'cameraStatus', callback: AsyncCallback): void +createCameraInput(camera: CameraDevice, callback: AsyncCallback): void + +使用CameraDevice对象异步创建CameraInput实例，通过注册回调函数获取结果。 + +此接口为系统接口。 -监听相机的状态变化，通过注册回调函数获取相机的状态变化。 +**需要权限：** ohos.permission.CAMERA **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| :------- | :---------------------------------------------------- | :--- | :--------------------------------------------------- | -| type | string | 是 | 监听事件，固定为'cameraStatus'，即相机状态变化事件。 | -| callback | AsyncCallback<[CameraStatusInfo](#camerastatusinfo)\> | 是 | 回调函数，用于获取相机状态变化信息。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------- | ---- | --------------------------------- | +| camera | [CameraDevice](#cameradevice) | 是 | CameraDevice对象。 | +| callback | AsyncCallback<[CameraInput](#camerainput)\> | 是 | 回调函数，用于获取CameraInput实例。 | **示例：** ```js -cameraManager.on('cameraStatus', (err, cameraStatusInfo) => { +cameraManager.createCameraInput(camera, (err, cameraInput) => { if (err) { - console.error('Failed to get cameraStatus callback. ${err.message}'); + console.error(`Failed to create the CameraInput instance. ${err.message}`); return; } - console.log('camera : ' + cameraStatusInfo.camera.cameraId); - console.log('status: ' + cameraStatusInfo.status); + console.log('Callback returned with the CameraInput instance.'); }) ``` -## Camera - -调用[camera.getCameraManager](#cameragetcameramanager)后，将返回Camera实例，包括相机ID、位置、类型、连接类型等相机相关的元数据。 - -**系统能力：** SystemCapability.Multimedia.Camera.Core。 - -| 名称 | 类型 | 只读 | 说明 | -| -------------- | --------------------------------- | ---- | -------------- | -| cameraId | string | 是 | 相机ID。 | -| cameraPosition | [CameraPosition](#cameraposition) | 是 | 相机位置。 | -| cameraType | [CameraType](#cameratype) | 是 | 相机类型。 | -| connectionType | [ConnectionType](#connectiontype) | 是 | 相机连接类型。 | - -**示例：** - -```js -async function getCameraInfo("cameraId") { - var cameraManager = await camera.getCameraManager(context); - var cameras = await cameraManager.getCameras(); - var cameraObj = cameras[0]; - var cameraId = cameraObj.cameraId; - var cameraPosition = cameraObj.cameraPosition; - var cameraType = cameraObj.cameraType; - var connectionType = cameraObj.connectionType; -} -``` - -## CameraStatusInfo - -相机管理器回调返回的接口实例，表示相机状态信息。 - -**系统能力：** SystemCapability.Multimedia.Camera.Core。 - -| 名称 | 类型 | 说明 | -| ------ | ----------------------------- | ---------- | -| camera | [Camera](#camera) | 相机信息。 | -| status | [CameraStatus](#camerastatus) | 相机状态。 | - - -## CameraInput +### createCameraInput -相机输入类。在使用该类的方法前，需要先构建一个CameraInput实例。 +createCameraInput(camera: CameraDevice): Promise -### getCameraId +使用CameraDevice对象异步创建CameraInput实例，通过Promise获取结果。 -getCameraId(callback: AsyncCallback\): void +此接口为系统接口。 -异步获取该CameraInput实例的相机ID，通过注册回调函数获取结果。 +**需要权限：** ohos.permission.CAMERA **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | ---------------------- | ---- | -------------------------- | -| callback | AsyncCallback | 是 | 回调函数，用于获取相机ID。 | - -**示例：** - -```js -cameraInput.getCameraId((err, cameraId) => { - if (err) { - console.error('Failed to get the camera ID. ${err.message}'); - return; - } - console.log('Callback returned with the camera ID: ' + cameraId); -}) -``` - -### getCameraId - -getCameraId(): Promise - -异步获取该CameraInput实例的相机ID，通过Promise获取结果。 - -**系统能力：** SystemCapability.Multimedia.Camera.Core +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------- | ---- | ---------- | +| camera | [CameraDevice](#cameradevice) | 是 | CameraDevice对象。 | **返回值：** -| 类型 | 说明 | -| ---------------- | ----------------------------- | -| Promise | 使用Promise的方式获取相机ID。 | +| 类型 | 说明 | +| ------------------------------------- | ------------------------------------ | +| Promise<[CameraInput](#camerainput)\> | 使用Promise的方式获取CameraInput的实例。 | **示例：** ```js -cameraInput.getCameraId().then((cameraId) => { - console.log('Promise returned with the camera ID:' + cameraId); +cameraManager.createCameraInput(camera).then((cameraInput) => { + console.log('Promise returned with the CameraInput instance'); }) ``` +### createCameraInput -### hasFlash +createCameraInput(position: CameraPosition, type: CameraType, callback: AsyncCallback): void -hasFlash(callback: AsyncCallback): void +根据相机位置和类型创建CameraInput实例，通过注册回调函数获取结果。 -判断设备是否支持闪光灯，通过注册回调函数获取结果。 +此接口为系统接口。 + +**需要权限：** ohos.permission.CAMERA **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | ----------------------- | ---- | -------------------------------------- | -| callback | AsyncCallback | 是 | 回调函数，返回true表示设备支持闪光灯。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------- | ---- | --------------------------------- | +| position | [CameraPosition](#cameraposition) | 是 | 相机位置。 | +| type | [CameraType](#cameratype) | 是 | 相机类型。 | +| callback | AsyncCallback<[CameraInput](#camerainput)\> | 是 | 回调函数，用于获取CameraInput实例。 | **示例：** ```js -cameraInput.hasFlash((err, status) => { +cameraManager.createCameraInput(camera.CameraPosition.CAMERA_POSITION_BACK, camera.CameraType.CAMERA_TYPE_UNSPECIFIED, (err, cameraInput) => { if (err) { - console.error('Failed to check whether the device has flash light. ${err.message}'); + console.error(`Failed to create the CameraInput instance. ${err.message}`); return; } - console.log('Callback returned with flash light support status: ' + status); + console.log('Callback returned with the CameraInput instance'); }) ``` -### hasFlash +### createCameraInput -hasFlash(): Promise +createCameraInput(position: CameraPosition, type:CameraType ): Promise + +根据相机位置和类型创建CameraInput实例，通过Promise获取结果。 + +此接口为系统接口。 -判断设备是否支持闪光灯，通过Promise获取结果。 +**需要权限：** ohos.permission.CAMERA **系统能力：** SystemCapability.Multimedia.Camera.Core +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | --------------------------------- | ---- | ------------ | +| position | [CameraPosition](#cameraposition) | 是 | 相机位置。 | +| type | [CameraType](#cameratype) | 是 | 相机类型。 | + **返回值：** -| 类型 | 说明 | -| ----------------- | ------------------------------------------------------- | -| Promise | 使用Promise的方式获取结果，返回true表示设备支持闪光灯。 | +| 类型 | 说明 | +| ------------------------------------- | ------------------------------------ | +| Promise<[CameraInput](#camerainput)\> | 使用Promise的方式获取CameraInput的实例。 | **示例：** ```js -cameraInput.hasFlash().then((status) => { - console.log('Promise returned with the flash light support status:' + status); +cameraManager.createCameraInput(camera.CameraPosition.CAMERA_POSITION_BACK, camera.CameraType.CAMERA_TYPE_UNSPECIFIED).then((cameraInput) => { + console.log('Promise returned with the CameraInput instance'); }) ``` -### isFlashModeSupported +### createPreviewOutput -isFlashModeSupported(flashMode: FlashMode, callback: AsyncCallback): void +createPreviewOutput(profile: Profile, surfaceId: string, callback: AsyncCallback): void -判断设备是否支持指定闪光灯模式，通过注册回调函数获取结果。 +创建预览输出对象，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| --------- | ----------------------- | ---- | ---------------------------------------- | -| flashMode | [FlashMode](#flashmode) | 是 | 指定闪光灯模式。 | -| callback | AsyncCallback | 是 | 回调函数，返回true表示支持该闪光灯模式。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------- | ---- | ------------------------------- | +| profile | [Profile](#profile) | 是 | 支持的预览配置信息。 | +| surfaceId| string | 是 | 从[XComponent](../arkui-ts/ts-basic-components-xcomponent.md)或者[ImageReceiver](js-apis-image.md#imagereceiver9)组件获取的SurfaceID。| +| callback | AsyncCallback<[PreviewOutput](#previewoutput)\> | 是 | 回调函数，用于获取PreviewOutput实例。| **示例：** ```js -cameraInput.isFlashModeSupported(camera.FlashMode.FLASH_MODE_AUTO, (err, status) => { +cameraManager.createPreviewOutput(profile, surfaceId, (err, previewoutput) => { if (err) { - console.error('Failed to check whether the flash mode is supported. ${err.message}'); + console.error(`Failed to gcreate previewOutput. ${err.message}`); return; } - console.log('Callback returned with the flash mode support status: ' + status); + console.log('Callback returned with previewOutput created.'); }) ``` -### isFlashModeSupported +### createPreviewOutput -isFlashModeSupported(flashMode: FlashMode): Promise +createPreviewOutput(profile: Profile, surfaceId: string): Promise -判断设备是否支持指定闪光灯模式，通过Promise获取结果。 +创建预览输出对象，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| --------- | ----------------------- | ---- | ---------------- | -| flashMode | [FlashMode](#flashmode) | 是 | 指定闪光灯模式。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------| ---- | ----------------- | +| profile | [Profile](#profile) | 是 | 支持的预览配置信息。 | +| surfaceId| string | 是 | 从[XComponent](../arkui-ts/ts-basic-components-xcomponent.md)或者[ImageReceiver](js-apis-image.md#imagereceiver9)组件获取的SurfaceID。 | **返回值：** -| 类型 | 说明 | -| ----------------- | ------------------------------------------------------------ | -| Promise | 使用Promise的方式获取结果，返回true表示设备支持该闪光灯模式。 | +| 类型 | 说明 | +| ---------------------------------------- | ---------------------------------------- | +| Promise<[PreviewOutput](#previewoutput)\> | 使用Promise的方式获取PreviewOutput的实例。 | **示例：** ```js -cameraInput.isFlashModeSupported(camera.FlashMode.FLASH_MODE_AUTO).then((status) => { - console.log('Promise returned with flash mode support status.' + status); +cameraManager.createPreviewOutput(profile, surfaceId).then((previewoutput) => { + console.log('Promise returned with previewOutput created.'); }) ``` -### setFlashMode - -setFlashMode(flashMode: FlashMode, callback: AsyncCallback): void - -设置闪光灯模式，通过注册回调函数获取结果。 +### createDeferredPreviewOutput -进行设置之前，需要先检查： +createDeferredPreviewOutput(profile: Profile, surfaceId: string, callback: AsyncCallback): void -1. 设备是否支持闪光灯，可使用方法[hasFlash](#hasflash)。 -2. 设备是否支持指定的闪光灯模式，可使用方法[isFlashModeSupported](#isflashmodesupported)。 +尚未获取surfaceID时创建预览输出对象，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| --------- | ----------------------- | ---- | ------------------------ | -| flashMode | [FlashMode](#flashmode) | 是 | 指定闪光灯模式。 | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------- | ---- | --------------------------------- | +| profile | [Profile](#profile) | 是 | 支持的预览配置信息。 | +| surfaceId| string | 是 | 从[XComponent](../arkui-ts/ts-basic-components-xcomponent.md)或者[ImageReceiver](js-apis-image.md#imagereceiver9)组件获取的SurfaceID。 | +| callback | AsyncCallback<[PreviewOutput](#previewoutput)\> | 是 | 回调函数，用于获取PreviewOutput实例。 | **示例：** ```js -cameraInput.setFlashMode(camera.FlashMode.FLASH_MODE_AUTO, (err) => { +cameraManager.createDeferredPreviewOutput(profile, surfaceId, (err, previewoutput) => { if (err) { - console.error('Failed to set the flash mode ${err.message}'); + console.error(`Failed to create deferredPreviewOutput. ${err.message}`); return; } - console.log('Callback returned with the successful execution of setFlashMode.'); + console.log('Callback returned with deferredPreviewOutput created.'); }) ``` -### setFlashMode - -setFlashMode(flashMode: FlashMode): Promise - -设置闪光灯模式，通过Promise获取结果。 +### createDeferredPreviewOutput -进行设置之前，需要先检查： +createDeferredPreviewOutput(profile: Profile, surfaceId: string): Promise -1. 设备是否支持闪光灯，可使用方法[hasFlash](#hasflash)。 -2. 设备是否支持指定的闪光灯模式，可使用方法[isFlashModeSupported](#isflashmodesupported)。 +尚未获取surfaceID时创建预览输出对象，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| --------- | ----------------------- | ---- | ---------------- | -| flashMode | [FlashMode](#flashmode) | 是 | 指定闪光灯模式。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------| ---- | ---------- | +| profile | [Profile](#profile) | 是 | 支持的预览配置信息。 | +| surfaceId| string | 是 | 从[XComponent](../arkui-ts/ts-basic-components-xcomponent.md)或者[ImageReceiver](js-apis-image.md#imagereceiver9)组件获取的SurfaceID。 | **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | -| Promise | 使用Promise的方式获取结果。 | +| 类型 | 说明 | +| ----------------------------------------- | --------------------------------------- | +| Promise<[PreviewOutput](#previewoutput)\> | 使用Promise的方式获取PreviewOutput的实例。 | **示例：** ```js -cameraInput.setFlashMode(camera.FlashMode.FLASH_MODE_AUTO).then(() => { - console.log('Promise returned with the successful execution of setFlashMode.'); +cameraManager.createDeferredPreviewOutput(profile, surfaceId).then((previewoutput) => { + console.log('Promise returned with DefeerredPreviewOutput created.'); }) ``` -### getFlashMode +### createPhotoOutput -getFlashMode(callback: AsyncCallback): void +createPhotoOutput(profile: Profile, surfaceId: string, callback: AsyncCallback): void -获取当前设备的闪光灯模式，通过注册回调函数获取结果。 +创建拍照输出对象，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | --------------------------------------- | ---- | ---------------------------------------- | -| callback | AsyncCallback<[FlashMode](#flashmode)\> | 是 | 回调函数，用于获取当前设备的闪光灯模式。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------- | ---- | ----------------------------------- | +| profile | [Profile](#profile) | 是 | 支持的拍照配置信息。 | +| surfaceId| string | 是 | 从[ImageReceiver](js-apis-image.md#imagereceiver9)获取的SurfaceID。| +| callback | AsyncCallback<[PhotoOutput](#photooutput)\> | 是 | 回调函数，用于获取PhotoOutput实例。 | **示例：** ```js -cameraInput.getFlashMode((err, flashMode) => { +cameraManager.createPhotoOutput(profile, surfaceId, (err, photooutput) => { if (err) { - console.error('Failed to get the flash mode ${err.message}'); + console.error(`Failed to create photoOutput. ${err.message}`); return; } - console.log('Callback returned with current flash mode: ' + flashMode); + console.log('Callback returned with photoOutput created.'); }) ``` -### getFlashMode +### createPhotoOutput -getFlashMode(): Promise +createPhotoOutput(profile: Profile, surfaceId: string): Promise -获取当前设备的闪光灯模式，通过Promise获取结果。 +创建拍照输出对象，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------| ---- | ----------- | +| profile | [Profile](#profile) | 是 | 支持的拍照配置信息。 | +| surfaceId| string | 是 | 从[ImageReceiver](js-apis-image.md#imagereceiver9)获取的SurfaceID。| + **返回值：** -| 类型 | 说明 | -| --------------------------------- | --------------------------------------- | -| Promise<[FlashMode](#flashmode)\> | 使用Promise的方式获取当前的闪光灯模式。 | +| 类型 | 说明 | +| ------------------------------------- | -------------------------------------- | +| Promise<[PhotoOutput](#photooutput)\> | 使用Promise的方式获取PhotoOutput的实例。 | **示例：** ```js -cameraInput.getFlashMode().then((flashMode) => { - console.log('Promise returned with current flash mode : ' + flashMode); +cameraManager.createPhotoOutput(profile, surfaceId).then((photooutput) => { + console.log('Promise returned with photoOutput created.'); }) ``` -### isFocusModeSupported +### createVideoOutput -isFocusModeSupported(afMode: FocusMode, callback: AsyncCallback): void +createVideoOutput(profile: VideoProfile, surfaceId: string, callback: AsyncCallback): void -判断设备是否支持指定的焦距模式，通过注册回调函数获取结果。 +创建录像输出对象，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | ----------------------- | ---- | -------------------------------------- | -| afMode | [FocusMode](#focusmode) | 是 | 指定的焦距模式。 | -| callback | AsyncCallback | 是 | 回调函数，返回true表示支持该焦距模式。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------- | ---- | ------------------------------ | +| profile | [VideoProfile](#videoprofile) | 是 | 支持的录像配置信息。 | +| surfaceId| string | 是 | 从[VideoRecorder](js-apis-media.md#videorecorder9)获取的SurfaceID。| +| callback | AsyncCallback<[VideoOutput](#videooutput)\> | 是 | 回调函数，用于获取VideoOutput实例。 | **示例：** ```js -cameraInput.isFocusModeSupported(camera.FocusMode.FOCUS_MODE_AUTO, (err, status) => { +cameraManager.createVideoOutput(profile, surfaceId, (err, videooutput) => { if (err) { - console.error('Failed to check whether the focus mode is supported. ${err.message}'); + console.error(`Failed to create videoOutput. ${err.message}`); return; } - console.log('Callback returned with the focus mode support status: ' + status); + console.log('Callback returned with an array of supported outputCapability' ); }) ``` -### isFocusModeSupported +### createVideoOutput -isFocusModeSupported(afMode: FocusMode): Promise +createVideoOutput(profile: VideoProfile, surfaceId: string): Promise -判断设备是否支持指定的焦距模式，通过Promise获取结果。 +创建录像输出对象，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| ------ | ----------------------- | ---- | ---------------- | -| afMode | [FocusMode](#focusmode) | 是 | 指定的焦距模式。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------| ---- | ---------- | +| profile | [VideoProfile](#videoprofile) | 是 | 支持的录像配置信息。 | +| surfaceId| string | 是 | 从[VideoRecorder](js-apis-media.md#videorecorder9)获取的SurfaceID。| **返回值：** -| 类型 | 说明 | -| ----------------- | ----------------------------------------------------------- | -| Promise | 使用Promise的方式获取结果，返回true表示设备支持该焦距模式。 | +| 类型 | 说明 | +| ------------------------------------- | -------------------------------------- | +| Promise<[VideoOutput](#videooutput)\> | 使用Promise的方式获取videoOutput的实例。 | **示例：** ```js -cameraInput.isFocusModeSupported(camera.FocusMode.FOCUS_MODE_AUTO).then((status) => { - console.log('Promise returned with focus mode support status.' + status); +cameraManager.createVideoOutput(profile, surfaceId).then((videooutput) => { + console.log('Promise returned with videoOutput created.'); }) ``` -### setFocusMode - -setFocusMode(afMode: FocusMode, callback: AsyncCallback): void +### createMetadataOutput -设置焦距模式，通过注册回调函数获取结果。 +createMetadataOutput(callback: AsyncCallback): void -进行设置之前，需要先检查设备是否支持指定的焦距模式，可使用方法[isFocusModeSupported](#isfocusmodesupported)。 +创建metadata流输出对象，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | ----------------------- | ---- | ------------------------ | -| afMode | [FocusMode](#focusmode) | 是 | 指定的焦距模式。 | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| -------------------- | -------------------------------------------------- | --- | ---------------------------- | +| callback | AsyncCallback<[MetadataOutput](#metadataoutput)\> | 是 | 回调函数，用于获取MetadataOutput实例。 | **示例：** ```js -cameraInput.setFocusMode(camera.FocusMode.FOCUS_MODE_AUTO, (err) => { +cameraManager.createMetadataOutput((err, metadataoutput) => { if (err) { - console.error('Failed to set the focus mode ${err.message}'); + console.error(`Failed to create metadataOutput. ${err.message}`); return; } - console.log('Callback returned with the successful execution of setFocusMode.'); + console.log('Callback returned with metadataOutput created.'); }) ``` -### setFocusMode - -setFocusMode(afMode: FocusMode): Promise +### createMetadataOutput -设置焦距模式，通过Promise获取结果。 +createMetadataOutput(): Promise -进行设置之前，需要先检查设备是否支持指定的焦距模式，可使用方法[isFocusModeSupported](#isfocusmodesupported)。 +创建metadata流输出对象，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core -**参数：** - -| 名称 | 类型 | 必填 | 说明 | -| ------ | ----------------------- | ---- | ---------------- | -| afMode | [FocusMode](#focusmode) | 是 | 指定的焦距模式。 | - **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | -| Promise | 使用Promise的方式获取结果。 | +| 类型 | 说明 | +| ------------------------------------------ | ----------------------------------------- | +| Promise<[MetadataOutput](#metadataoutput)\> | 使用Promise的方式获取MetadataOutput的实例。 | **示例：** ```js -cameraInput.setFocusMode(camera.FocusMode.FOCUS_MODE_AUTO).then(() => { - console.log('Promise returned with the successful execution of setFocusMode.'); +cameraManager.createMetadataOutput().then((metadataoutput) => { + console.log('Promise returned with metadataOutput created.'); }) ``` -### getFocusMode +### createCaptureSession -getFocusMode(callback: AsyncCallback): void +createCaptureSession(callback: AsyncCallback): void -获取当前设备的焦距模式，通过注册回调函数获取结果。 +创建CaptureSession实例，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | --------------------------------------- | ---- | -------------------------------------- | -| callback | AsyncCallback<[FocusMode](#focusmode)\> | 是 | 回调函数，用于获取当前设备的焦距模式。 | +| 名称 | 类型 | 必填 | 说明 | +| -------------------- | ----------------------------------------- | ----------- | ---------------------------- | +| callback | AsyncCallback<[CaptureSession](#capturesession)\> | 是 | 回调函数，用于获取拍照会话实例。 | **示例：** ```js -cameraInput.getFocusMode((err, afMode) => { +cameraManager.createCaptureSession((err, capturesession) => { if (err) { - console.error('Failed to get the focus mode ${err.message}'); + console.error(`Failed to create captureSession. ${err.message}`); return; } - console.log('Callback returned with current focus mode: ' + afMode); + console.log('Callback returned with captureSession created.'); }) ``` -### getFocusMode +### createCaptureSession -getFocusMode(): Promise +createCaptureSession(): Promise -获取当前设备的焦距模式，通过Promise获取结果。 +创建CaptureSession实例，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **返回值：** -| 类型 | 说明 | -| ------------------- | ------------------------------------- | -| Promise | 使用Promise的方式获取当前的焦距模式。 | +| 类型 | 说明 | +| ------------------------------------------- | ---------------------------------------- | +| Promise<[CaptureSession](#capturesession)\> | 使用Promise的方式获取CaptureSession的实例。 | **示例：** ```js -cameraInput.getFocusMode().then((afMode) => { - console.log('Promise returned with current focus mode : ' + afMode); +cameraManager.createCaptureSession().then((capturesession) => { + console.log('Promise returned with captureSession created.'); }) ``` -### getZoomRatioRange +### on('cameraStatus') -getZoomRatioRange\(callback: AsyncCallback\>\): void +on(type: 'cameraStatus', callback: AsyncCallback): void -获取可变焦距比范围，通过注册回调函数获取结果。 +镜头状态回调，通过注册回调函数获取相机的状态变化。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | ------------------------------ | ---- | ------------------------ | -| callback | AsyncCallback\> | 是 | 回调函数，用于获取可变焦距比范围，返回的数组包括其最小值和最大值。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------- | ---- | --------- | +| type | string | 是 | 监听事件，固定为'cameraStatus'，即镜头状态变化事件。 | +| callback | AsyncCallback<[CameraStatusInfo](#camerastatusinfo)\> | 是 | 回调函数，用于获取镜头状态变化信息。 | **示例：** ```js -cameraInput.getZoomRatioRange((err, zoomRatioRange) => { +cameraManager.on('cameraStatus', (err, cameraStatusInfo) => { if (err) { - console.error('Failed to get the zoom ratio range. ${err.message}'); + console.error(`Failed to get cameraStatus callback. ${err.message}`); return; } - console.log('Callback returned with zoom ratio range: ' + zoomRatioRange.length); + console.log(`camera : ${cameraStatusInfo.camera.cameraId}`); + console.log(`status: ${cameraStatusInfo.status}`); }) ``` -### getZoomRatioRange - -getZoomRatioRange\(\): Promise\> - -获取可变焦距比范围，通过Promise获取结果。 - -**系统能力：** SystemCapability.Multimedia.Camera.Core - -**返回值：** - -| 类型 | 说明 | -| ------------------------ | ------------------------------------------- | -| Promise\> | 使用Promise的方式获取当前的可变焦距比范围，返回的数组包括其最小值和最大值。 | - -**示例：** +### on('cameraMute') -```js -cameraInput.getZoomRatioRange().then((zoomRatioRange) => { - console.log('Promise returned with zoom ratio range: ' + zoomRatioRange.length); -}) -``` +on(type: 'cameraMute', callback: AsyncCallback): void -### setZoomRatio +监听相机禁用的状态变化，通过注册回调函数获取相机的状态变化。 -setZoomRatio(zoomRatio: number, callback: AsyncCallback): void +此接口为系统接口。 -设置可变焦距比，通过注册回调函数获取结果。 +**需要权限：** ohos.permission.CAMERA **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| --------- | -------------------- | ---- | ------------------------ | -| zoomRatio | number | 是 | 可变焦距比。 | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ------------------------------- | +| type | string | 是 | 监听事件，固定为'cameraMute'，即相机状禁用态变化事件。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取相机是否禁用。 | **示例：** ```js -cameraInput.setZoomRatio(1, (err) => { +cameraManager.on('cameraMute', (err, status) => { if (err) { - console.error('Failed to set the zoom ratio value ${err.message}'); + console.error(`Failed to get cameraMute callback. ${err.message}`); return; } - console.log('Callback returned with the successful execution of setZoomRatio.'); + console.log(`status: ${status}`); }) ``` -### setZoomRatio +## CameraStatusInfo -setZoomRatio(zoomRatio: number): Promise +相机管理器回调返回的接口实例，表示相机状态信息。 -设置可变焦距比，通过Promise获取结果。 +**系统能力：** SystemCapability.Multimedia.Camera.Core。 -**系统能力：** SystemCapability.Multimedia.Camera.Core +| 名称 | 类型 | 说明 | +| ------ | ----------------------------- | ---------- | +| camera | [CameraDevice](#cameradevice) | 相机信息。 | +| status | [CameraStatus](#camerastatus) | 相机状态。 | -**参数：** +## CameraPosition -| 名称 | 类型 | 必填 | 说明 | -| --------- | ------ | ---- | ------------ | -| zoomRatio | number | 是 | 可变焦距比。 | +枚举，相机位置。 -**返回值：** +**系统能力：** SystemCapability.Multimedia.Camera.Core -| 类型 | 说明 | -| -------------- | --------------------------- | -| Promise | 使用Promise的方式获取结果。 | +| 名称 | 值 | 说明 | +| --------------------------- | ---- | -------------- | +| CAMERA_POSITION_UNSPECIFIED | 0 | 相机位置未指定。 | +| CAMERA_POSITION_BACK | 1 | 后置相机。 | +| CAMERA_POSITION_FRONT | 2 | 前置相机。 | + +## CameraType + +枚举，相机类型。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 值 | 说明 | +| ----------------------- | ---- | -------------- | +| CAMERA_TYPE_UNSPECIFIED | 0 | 相机类型未指定。 | +| CAMERA_TYPE_WIDE_ANGLE | 1 | 广角相机。 | +| CAMERA_TYPE_ULTRA_WIDE | 2 | 超广角相机。 | +| CAMERA_TYPE_TELEPHOTO | 3 | 长焦相机。 | +| CAMERA_TYPE_TRUE_DEPTH | 4 | 带景深信息的相机。 | + +## ConnectionType + +枚举，相机连接类型。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 值 | 说明 | +| ---------------------------- | ---- | ------------- | +| CAMERA_CONNECTION_BUILT_IN | 0 | 内置相机。 | +| CAMERA_CONNECTION_USB_PLUGIN | 1 | USB连接的相机。 | +| CAMERA_CONNECTION_REMOTE | 2 | 远程连接的相机。 | + +## CameraDevice + +相机设备信息。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core。 + +| 名称 | 类型 | 只读 | 说明 | +| -------------- | --------------------------------- | ---- | ---------- | +| cameraId | string | 是 | CameraDevice对象| +| cameraPosition | [CameraPosition](#cameraposition) | 是 | 相机位置。 | +| cameraType | [CameraType](#cameratype) | 是 | 相机类型。 | +| connectionType | [ConnectionType](#connectiontype) | 是 | 相机连接类型。 | **示例：** ```js -cameraInput.setZoomRatio(1).then(() => { - console.log('Promise returned with the successful execution of setZoomRatio.'); -}) +async function getCameraInfo("cameraId") { + let cameraManager = await camera.getCameraManager(context); + let cameras = await cameraManager.getSupportedCameras(); + let cameraObj = cameras[0]; + let cameraId = cameraObj.cameraId; + let cameraPosition = cameraObj.cameraPosition; + let cameraType = cameraObj.cameraType; + let connectionType = cameraObj.connectionType; +} ``` -### getZoomRatio +## Size -getZoomRatio(callback: AsyncCallback): void +枚举，输出能力查询。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------ | ------ | ---- | ---- | ------------ | +| height | number | 是 | 是 | 图像尺寸高(像素)。 | +| width | number | 是 | 是 | 图像尺寸宽(像素)。 | -获取当前的可变焦距比，通过注册回调函数获取结果。 +## Point + +枚举，点坐标用于对焦、曝光配置。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------ | +| x | number | 是 | 点的x坐标。 | +| y | number | 是 | 点的y坐标。 | + +## CameraFormat + +枚举，输出格式。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 默认值 | 说明 | +| ----------------------- | --------- | ------------ | +| CAMERA_FORMAT_YUV_420_SP| 1003 | YUV 420 SP格式的图片。 | +| CAMERA_FORMAT_JPEG | 2000 | JPEG格式的图片。 | + +## CameraInput + +会话中[CaptureSession](#capturesession)使用的相机信息。 + +### open + +open\(callback: AsyncCallback\): void + +打开相机，通过注册回调函数获取状态。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | ---------------------- | ---- | ------------------------ | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ------------------- | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -cameraInput.getZoomRatio((err, zoomRatio) => { +cameraInput.open((err) => { if (err) { - console.error('Failed to get the zoom ratio ${err.message}'); + console.error(`Failed to open the camera. ${err.message}`); return; } - console.log('Callback returned with current zoom ratio: ' + zoomRatio); + console.log('Callback returned with camera opened.'); }) ``` -### getZoomRatio +### open -getZoomRatio(): Promise +open(): Promise -获取当前的可变焦距比，通过Promise获取结果。 +打开相机，通过Promise获取相机的状态。 **系统能力：** SystemCapability.Multimedia.Camera.Core **返回值：** -| 类型 | 说明 | -| ---------------- | --------------------------- | -| Promise | 使用Promise的方式获取结果。 | +| 类型 | 说明 | +| -------------- | ----------------------- | +| Promise | 使用Promise的方式获取结果。 | **示例：** ```js -cameraInput.getZoomRatio().then((zoomRatio) => { - console.log('Promise returned with current zoom ratio : ' + zoomRatio); +cameraInput.open().then(() => { + console.log('Promise returned with camera opened.'); }) ``` -### release +### close -release\(callback: AsyncCallback\): void +close\(callback: AsyncCallback\): void -释放相机实例，通过注册回调函数获取结果。 +关闭相机，通过注册回调函数获取状态。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ------------------------ | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | -------------------- | | callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -cameraInput.release((err) => { +cameraInput.close((err) => { if (err) { - console.error('Failed to release the CameraInput instance ${err.message}'); + console.error(`Failed to close the cameras. ${err.message}`); return; } - console.log('Callback invoked to indicate that the CameraInput instance is released successfully.'); -}); + console.log('Callback returned with camera closed.'); +}) ``` -### release +### close -release(): Promise +close(): Promise -释放相机实例，通过Promise获取结果。 +关闭相机，通过Promise获取状态。 **系统能力：** SystemCapability.Multimedia.Camera.Core **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | +| 类型 | 说明 | +| -------------- | ----------------------- | | Promise | 使用Promise的方式获取结果。 | **示例：** ```js -cameraInput.release().then(() => { - console.log('Promise returned to indicate that the CameraInput instance is released successfully.'); +cameraInput.close().then(() => { + console.log('Promise returned with camera closed.'); }) ``` -### on('focusStateChange') +### release -on(type: 'focusStateChange', callback: AsyncCallback): void +release\(callback: AsyncCallback\): void -监听焦距的状态变化，通过注册回调函数获取结果。 +释放资源，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| :------- | :---------------------------------------- | :--- | :------------------------------------------------------- | -| type | string | 是 | 监听事件，固定为'focusStateChange'，即焦距状态变化事件。 | -| callback | AsyncCallback<[FocusState](#focusstate)\> | 是 | 回调函数，用于获取焦距状态。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ------------------- | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -cameraInput.on('focusStateChange', (focusState) => { - console.log('Focus state : ' + focusState); +cameraInput.release((err) => { + if (err) { + console.error(`Failed to release the CameraInput instance ${err.message}`); + return; + } + console.log('Callback invoked to indicate that the CameraInput instance is released successfully.'); +}); +``` + +### release + +release(): Promise + +释放资源，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------- | +| Promise | 使用Promise的方式获取结果。 | + +**示例：** + +```js +cameraInput.release().then(() => { + console.log('Promise returned to indicate that the CameraInput instance is released successfully.'); }) ``` @@ -1032,37 +1049,42 @@ on(type: 'error', callback: ErrorCallback): void **参数：** -| 名称 | 类型 | 必填 | 说明 | -| :------- | :------------------------------- | :--- | :----------------------------------------------- | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------------------- | ---- | ------------------------------------------- | | type | string | 是 | 监听事件，固定为'error'，即CameraInput错误事件。 | -| callback | ErrorCallback<[CameraInputError](#camerainputerror)\> | 是 | 回调函数，用于获取结果。 | +| callback | ErrorCallback<[CameraInputError](#camerainputerror)\> | 是 | 回调函数，用于获取结果。 | **示例：** ```js cameraInput.on('error', (cameraInputError) => { - console.log('Camera input error code: ' + cameraInputError.code); + console.log(`Camera input error code: ${cameraInputError.code}`); }) ``` -## CameraInputErrorCode +## CameraInputErrorCode -枚举，CameraInput的错误码。 +枚举，[CameraInput](#camerainput)错误类型。 **系统能力：** SystemCapability.Multimedia.Camera.Core -| 名称 | 值 | 说明 | -| ------------- | ---- | ---------- | -| ERROR_UNKNOWN | -1 | 未知错误。 | +| 名称 | 值 | 说明 | +| ------------------------- | ---- | ---------- | +| ERROR_UNKNOWN | -1 | 未知错误。 | +| ERROR_NO_PERMISSION | 0 | 没有权限。 | +| ERROR_DEVICE_PREEMPTED | 1 | 相机被抢占。 | +| ERROR_DEVICE_DISCONNECTED | 2 | 相机断开连接。 | +| ERROR_DEVICE_IN_USE | 3 | 相机正在使用。 | +| ERROR_DRIVER_ERROR | 4 | 驱动错误。 | -## CameraInputError +## CameraInputError -CameraInput错误对象。 +[CameraInput](#camerainput)错误码。 **系统能力：** SystemCapability.Multimedia.Camera.Core -| 名称 | 类型 | 说明 | -| ---- | ------------------------------------------- | -------------------------- | +| 名称 | 类型 | 说明 | +| ---- | --------------------------------------------- | --------------------- | | code | [CameraInputErrorCode](#camerainputerrorcode) | CameraInput中的错误码。 | @@ -1072,96 +1094,78 @@ CameraInput错误对象。 **系统能力：** SystemCapability.Multimedia.Camera.Core。 -| 名称 | 值 | 说明 | -| ---------------------- | ---- | ------------ | +| 名称 | 值 | 说明 | +| ---------------------- | ---- | ---------- | | FLASH_MODE_CLOSE | 0 | 闪光灯关闭。 | -| FLASH_MODE_OPEN | 1 | 闪光灯开启。 | +| FLASH_MODE_OPEN | 1 | 闪光灯打开。 | | FLASH_MODE_AUTO | 2 | 自动闪光灯。 | | FLASH_MODE_ALWAYS_OPEN | 3 | 闪光灯常亮。 | -## FocusMode +## ExposureMode -枚举，焦距模式。 +枚举，曝光模式。 **系统能力：** SystemCapability.Multimedia.Camera.Core。 -| 名称 | 值 | 说明 | -| -------------------------- | ---- | ------------------ | -| FOCUS_MODE_MANUAL | 0 | 手动变焦模式。 | -| FOCUS_MODE_CONTINUOUS_AUTO | 1 | 连续自动变焦模式。 | -| FOCUS_MODE_AUTO | 2 | 自动变焦模式。 | -| FOCUS_MODE_LOCKED | 3 | 定焦模式。 | +| 名称 | 值 | 说明 | +| ----------------------------- | ---- | ----------- | +| EXPOSURE_MODE_LOCKED | 0 | 锁定曝光模式。 | +| EXPOSURE_MODE_AUTO | 1 | 自动曝光模式。 | +| EXPOSURE_MODE_CONTINUOUS_AUTO | 2 | 连续自动曝光。 | -## FocusState +## FocusMode -枚举，焦距状态。 +枚举，焦距模式。 **系统能力：** SystemCapability.Multimedia.Camera.Core。 -| 名称 | 值 | 说明 | -| --------------------- | ---- | ------------ | -| FOCUS_STATE_SCAN | 0 | 扫描状态。 | -| FOCUS_STATE_FOCUSED | 1 | 相机已对焦。 | -| FOCUS_STATE_UNFOCUSED | 2 | 相机未对焦。 | - -## camera.createCaptureSession - -createCaptureSession\(context: Context, callback: AsyncCallback\): void - -获取CaptureSession实例，通过注册回调函数获取结果。 - -**系统能力：** SystemCapability.Multimedia.Camera.Core - -**参数：** - -| 名称 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------- | ---- | -------------------------------------- | -| context | Context | 是 | 应用上下文。 | -| callback | AsyncCallback<[CaptureSession](#capturesession)\> | 是 | 回调函数，用于获取CaptureSession实例。 | +| 名称 | 值 | 说明 | +| -------------------------- | ---- | ------------ | +| FOCUS_MODE_MANUAL | 0 | 手动对焦。 | +| FOCUS_MODE_CONTINUOUS_AUTO | 1 | 连续自动对焦。 | +| FOCUS_MODE_AUTO | 2 | 自动变焦。 | +| FOCUS_MODE_LOCKED | 3 | 对焦锁定。 | -**示例：** +## FocusState -```js -camera.createCaptureSession((context), (err, captureSession) => { - if (err) { - console.error('Failed to create the CaptureSession instance. ${err.message}'); - return; - } - console.log('Callback returned with the CaptureSession instance.' + captureSession); -}); -``` +枚举，焦距状态。 -## camera.createCaptureSession +**系统能力：** SystemCapability.Multimedia.Camera.Core。 -createCaptureSession(context: Context\): Promise; +| 名称 | 值 | 说明 | +| --------------------- | ---- | --------- | +| FOCUS_STATE_SCAN | 0 | 触发对焦。 | +| FOCUS_STATE_FOCUSED | 1 | 对焦成功。 | +| FOCUS_STATE_UNFOCUSED | 2 | 未完成对焦。 | -获取CaptureSession实例，通过Promise获取结果。 +## ExposureState -**系统能力：** SystemCapability.Multimedia.Camera.Core +枚举，曝光状态。 -**参数：** +**系统能力：** SystemCapability.Multimedia.Camera.Core。 -| 名称 | 类型 | 必填 | 说明 | -| ------- | ------- | ---- | ------------ | -| context | Context | 是 | 应用上下文。 | +| 名称 | 值 | 说明 | +| ------------------------- | ---- | -------- | +| EXPOSURE_STATE_SCAN | 0 | 曝光中。 | +| EXPOSURE_STATE_CONVERGED | 1 | 曝光收敛。 | -**返回值：** +## VideoStabilizationMode -| 类型 | 说明 | -| ------------------------------------------- | ----------------------------------------- | -| Promise<[CaptureSession](#capturesession)\> | 使用Promise的方式获取CaptureSession实例。 | +枚举，视频防抖模式。 -**示例：** +**系统能力：** SystemCapability.Multimedia.Camera.Core。 -```js -camera.createCaptureSession(context).then((captureSession) => { - console.log('Promise returned with the CaptureSession instance'); -}) -``` +| 名称 | 值 | 说明 | +| --------- | ---- | ------------ | +| OFF | 0 | 关闭视频防抖功能。 | +| LOW | 1 | 使用基础防抖算法。 | +| MIDDLE | 2 | 使用防抖效果一般的防抖算法，防抖效果优于LOW类型。 | +| HIGH | 3 | 使用防抖效果最好的防抖算法，防抖效果优于MIDDLE类型。 | +| AUTO | 4 | 自动进行选择。 | ## CaptureSession -拍照会话类。 +拍照会话类，保存一次相机运行所需要的所有资源[CameraInput](#camerainput)、[CameraOutput](#cameraoutput)，并向相机设备申请完成相机功能(录像，拍照)。 ### beginConfig @@ -1173,8 +1177,8 @@ beginConfig\(callback: AsyncCallback\): void **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ------------------------ | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ------------------- | | callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** @@ -1182,7 +1186,7 @@ beginConfig\(callback: AsyncCallback\): void ```js captureSession.beginConfig((err) => { if (err) { - console.error('Failed to start the configuration. ${err.message}'); + console.error(`Failed to start the configuration. ${err.message}`); return; } console.log('Callback invoked to indicate the begin config success.'); @@ -1199,8 +1203,8 @@ beginConfig\(\): Promise **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | +| 类型 | 说明 | +| -------------- | ------------------------ | | Promise | 使用Promise的方式获取结果。 | @@ -1216,14 +1220,14 @@ captureSession.beginConfig().then(() => { commitConfig\(callback: AsyncCallback\): void -提交会话配置，通过注册回调函数获取结果。 +提交配置信息，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ------------------------ | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | -------------------- | | callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** @@ -1231,7 +1235,7 @@ commitConfig\(callback: AsyncCallback\): void ```js captureSession.commitConfig((err) => { if (err) { - console.error('Failed to commit the configuration. ${err.message}'); + console.error(`Failed to commit the configuration. ${err.message}`); return; } console.log('Callback invoked to indicate the commit config success.'); @@ -1242,14 +1246,14 @@ captureSession.commitConfig((err) => { commitConfig\(\): Promise -提交会话配置，通过Promise获取结果。 +提交配置信息，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | +| 类型 | 说明 | +| -------------- | ------------------------ | | Promise | 使用Promise的方式获取结果。 | **示例：** @@ -1260,546 +1264,529 @@ captureSession.commitConfig().then(() => { }) ``` -### addInput +### canAddInput -addInput\(cameraInput: CameraInput, callback: AsyncCallback\): void +canAddInput(cameraInput: CameraInput, callback: AsyncCallback): void -在当前会话中，添加一个CameraInput实例，通过注册回调函数获取结果。 +判断是否可以添加[CameraInput](#camerainput)到会话中，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| ----------- | --------------------------- | ---- | --------------------------- | +| 名称 | 类型 | 必填 | 说明 | +| ----------- | --------------------------- | ---- | ------------------------ | | cameraInput | [CameraInput](#camerainput) | 是 | 需要添加的CameraInput实例。 | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -captureSession.addInput(cameraInput, (err) => { +captureSession.canAddInput(cameraInput, (err, status) => { if (err) { - console.error('Failed to add the CameraInput instance. ${err.message}'); + console.error(`Can not add cameraInput. ${err.message}`); return; } - console.log('Callback invoked to indicate that the CameraInput instance is added.'); -}); + console.log('Callback returned with cameraInput can added.'); +}) ``` -### addInput +### canAddInput -addInput\(cameraInput: CameraInput\): Promise +canAddInput(cameraInput: CameraInput): Promise -在当前会话中，添加一个CameraInput实例，通过Promise获取结果。 +判断是否可以添加[CameraInput](#camerainput)到会话中，通过注Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| ----------- | --------------------------- | ---- | --------------------------- | +| 名称 | 类型 | 必填 | 说明 | +| ----------- | --------------------------- | ---- | ------------------------ | | cameraInput | [CameraInput](#camerainput) | 是 | 需要添加的CameraInput实例。 | **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | -| Promise | 使用Promise的方式获取结果。 | +| 类型 | 说明 | +| -------------- | -------------------------- | +| Promise | 使用Promise的方式获取结果。 | **示例：** ```js -captureSession.addInput(cameraInput).then(() => { - console.log('Promise used to indicate that the CameraInput instance is added.'); +captureSession.canAddInput(cameraInput).then(() => { + console.log('Promise returned with cameraInput can added.'); }) ``` -### addOutput +### addInput -addOutput\(previewOutput: PreviewOutput, callback: AsyncCallback\): void +addInput\(cameraInput: CameraInput, callback: AsyncCallback\): void -在当前会话中，添加一个PreviewOutput实例，通过注册回调函数获取结果。 +把[CameraInput](#camerainput)加入到会话，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| ------------- | ------------------------------- | ---- | ----------------------------- | -| previewOutput | [PreviewOutput](#previewoutput) | 是 | 需要添加的PreviewOutput实例。 | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| ----------- | --------------------------- | ---- | ------------------------ | +| cameraInput | [CameraInput](#camerainput) | 是 | 需要添加的CameraInput实例。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -captureSession.addOutput(previewOutput, (err) => { +captureSession.addInput(cameraInput, (err) => { if (err) { - console.error('Failed to add the PreviewOutput instance ${err.message}'); + console.error(`Failed to add the CameraInput instance. ${err.message}`); return; } - console.log('Callback invoked to indicate that the PreviewOutput instance is added.'); + console.log('Callback invoked to indicate that the CameraInput instance is added.'); }); ``` -### addOutput +### addInput -addOutput\(previewOutput: PreviewOutput\): Promise +addInput\(cameraInput: CameraInput\): Promise -在当前会话中，添加一个PreviewOutput实例，通过Promise获取结果。 +把[CameraInput](#camerainput)加入到会话，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| ------------- | ------------------------------- | ---- | ----------------------------- | -| previewOutput | [PreviewOutput](#previewoutput) | 是 | 需要添加的PreviewOutput实例。 | +| 名称 | 类型 | 必填 | 说明 | +| ----------- | --------------------------- | ---- | ------------------------ | +| cameraInput | [CameraInput](#camerainput) | 是 | 需要添加的CameraInput实例。 | **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | +| 类型 | 说明 | +| -------------- | ------------------------ | | Promise | 使用Promise的方式获取结果。 | **示例：** ```js -captureSession.addOutput(previewOutput).then(() => { - console.log('Promise used to indicate that the PreviewOutput instance is added.'); +captureSession.addInput(cameraInput).then(() => { + console.log('Promise used to indicate that the CameraInput instance is added.'); }) ``` -### addOutput +### removeInput -addOutput\(photoOutput: PhotoOutput, callback: AsyncCallback\): void +removeInput\(cameraInput: CameraInput, callback: AsyncCallback\): void -在当前会话中，添加一个PhotoOutput实例，通过注册回调函数获取结果。 +移除[CameraInput](#camerainput)，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| ----------- | --------------------------- | ---- | --------------------------- | -| photoOutput | [PhotoOutput](#photooutput) | 是 | 需要添加的PhotoOutput实例。 | +| 名称 | 类型 | 必填 | 说明 | +| ----------- | --------------------------- | ---- | ------------------------ | +| cameraInput | [CameraInput](#camerainput) | 是 | 需要移除的CameraInput实例。 | | callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -captureSession.addOutput(photoOutput, (err) => { +captureSession.removeInput(cameraInput, (err) => { if (err) { - console.error('Failed to add the PhotoOutput instance ${err.message}'); + console.error(`Failed to remove the CameraInput instance. ${err.message}`); return; } - console.log('Callback invoked to indicate that the PhotoOutput instance is added.'); + console.log('Callback invoked to indicate that the cameraInput instance is removed.'); }); ``` -### addOutput +### removeInput -addOutput\(photoOutput: PhotoOutput\): Promise +removeInput\(cameraInput: CameraInput\): Promise -在当前会话中，添加一个PhotoOutput实例，通过Promise获取结果。 +移除[CameraInput](#camerainput)，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| ----------- | --------------------------- | ---- | --------------------------- | -| photoOutput | [PhotoOutput](#photooutput) | 是 | 需要添加的PhotoOutput实例。 | +| 名称 | 类型 | 必填 | 说明 | +| ----------- | --------------------------- | ---- | ------------------------ | +| cameraInput | [CameraInput](#camerainput) | 是 | 需要移除的CameraInput实例。 | **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | -| Promise\ | 使用Promise的方式获取结果。 | +| 类型 | 说明 | +| -------------- | ------------------------- | +| Promise\ | 使用Promise的方式获取结果。 | **示例：** ```js -captureSession.addOutput(photoOutput).then(() => { - console.log('Promise used to indicate that the PhotoOutput instance is added.'); +captureSession.removeInput(cameraInput).then(() => { + console.log('Promise returned to indicate that the cameraInput instance is removed.'); }) ``` -### addOutput +### canAddOutput -addOutput\(videoOutput: VideoOutput, callback: AsyncCallback\): void +canAddOutput(cameraOutput: CameraOutput, callback: AsyncCallback\): void -在当前会话中，添加一个VideoOutput实例，通过注册回调函数获取结果。 +查询是否可以添加[CameraOutput](#cameraoutput)到会话中，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| ----------- | --------------------------- | ---- | --------------------------- | -| videoOutput | [VideoOutput](#videooutput) | 是 | 需要添加的VideoOutput实例。 | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| ------------- | ------------------------------- | ---- | ------------------------- | +| cameraOutput | [CameraOutput](#cameraoutput) | 是 | 需要添加的CameraOutput实例。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -captureSession.addOutput(videoOutput, (err) => { +captureSession.canAddOutput(cameraOutput, (err, status) => { if (err) { - console.error('Failed to add the VideoOutput instance ${err.message}'); + console.error(`Can not add cameraOutput. ${err.message}`); return; } - console.log('Callback invoked to indicate that the VideoOutput instance is added.'); -}); + console.log('Callback returned with cameraOutput can added.'); +}) ``` -### addOutput +### canAddOutput -addOutput\(videoOutput: VideoOutput\): Promise +canAddOutput(cameraOutput: CameraOutput): Promise -在当前会话中，添加一个VideoOutput实例，通过Promise获取结果。 +查询是否可以添加[CameraOutput](#cameraoutput)到会话中，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| ----------- | --------------------------- | ---- | --------------------------- | -| videoOutput | [VideoOutput](#videooutput) | 是 | 需要添加的VideoOutput实例。 | +| 名称 | 类型 | 必填 | 说明 | +| ------------- | ------------------------------- | ---- | ------------------------- | +| cameraOutput | [CameraOutput](#cameraoutput) | 是 | 需要添加的CameraOutput实例。 | + **返回值：** -| 类型 | 说明 | +| 类型 | 说明 | | -------------- | --------------------------- | -| Promise\ | 使用Promise的方式获取结果。 | +| Promise | 使用Promise的方式获取结果。 | + **示例：** ```js -captureSession.addOutput(videoOutput).then(() => { - console.log('Promise used to indicate that the VideoOutput instance is added.'); +captureSession.canAddOutput(cameraOutput).then(() => { + console.log('Promise returned with cameraOutput can added.'); }) ``` -### removeInput +### addOutput -removeInput\(cameraInput: CameraInput, callback: AsyncCallback\): void +addOutput\(cameraOutput: CameraOutput, callback: AsyncCallback\): void -在当前会话中，移除一个CameraInput实例，通过注册回调函数获取结果。 +把[CameraOutput](#cameraoutput)加入到会话，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| ----------- | --------------------------- | ---- | --------------------------- | -| cameraInput | [CameraInput](#camerainput) | 是 | 需要移除的CameraInput实例。 | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| ------------- | ------------------------------- | ---- | ------------------------ | +| cameraOutput | [CameraOutput](#cameraoutput) | 是 | 需要添加的CameraOutput实例。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -captureSession.removeInput(cameraInput, (err) => { +captureSession.addOutput(cameraOutput, (err) => { if (err) { - console.error('Failed to remove the CameraInput instance. ${err.message}'); + console.error(`Failed to add output. ${err.message}`); return; } - console.log('Callback invoked to indicate that the cameraInput instance is removed.'); -}); + console.log('Callback returned with output added.'); +}) ``` -### removeInput +### addOutput -removeInput\(cameraInput: CameraInput\): Promise +addOutput\(cameraOutput: CameraOutput\): Promise -在当前会话中，移除一个CameraInput实例，通过Promise获取结果。 +把[CameraOutput](#cameraoutput)加入到会话，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| ----------- | --------------------------- | ---- | --------------------------- | -| cameraInput | [CameraInput](#camerainput) | 是 | 需要移除的CameraInput实例。 | +| 名称 | 类型 | 必填 | 说明 | +| ------------- | ------------------------------- | ---- | ------------------------- | +| cameraOutput | [CameraOutput](#cameraoutput) | 是 | 需要添加的CameraOutput实例。 | **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | -| Promise\ | 使用Promise的方式获取结果。 | +| 类型 | 说明 | +| -------------- | ----------------------- | +| Promise | 使用Promise的方式获取结果。 | **示例：** ```js -captureSession.removeInput(cameraInput).then(() => { - console.log('Promise returned to indicate that the cameraInput instance is removed.'); +captureSession.addOutput(cameraOutput).then(() => { + console.log('Promise returned with cameraOutput added.'); }) ``` ### removeOutput -removeOutput\(previewOutput: PreviewOutput, callback: AsyncCallback\): void +removeOutput\(cameraOutput: CameraOutput, callback: AsyncCallback\): void -在当前会话中，移除一个PreviewOutput实例，通过注册回调函数获取结果。 +从会话中移除[CameraOutput](#cameraoutput)，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| ------------- | ------------------------------- | ---- | ----------------------------- | -| previewOutput | [PreviewOutput](#previewoutput) | 是 | 需要移除的PreviewOutput实例。 | +| 名称 | 类型 | 必填 | 说明 | +| ------------- | ------------------------------- | ---- | ------------------------ | +| cameraOutput | [CameraOutput](#cameraoutput) | 是 | 需要移除的CameraOutput实例。 | | callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -captureSession.removeOutput(previewOutput, (err) => { +captureSession.removeOutput(cameraOutput, (err) => { if (err) { - console.error('Failed to remove the PreviewOutput instance. ${err.message}'); + console.error(`Failed to remove the CameraOutput instance. ${err.message}`); return; } - console.log('Callback invoked to indicate that the PreviewOutput instance is removed.'); + console.log('Callback invoked to indicate that the CameraOutput instance is removed.'); }); ``` ### removeOutput -removeOutput(previewOutput: PreviewOutput): Promise +removeOutput(cameraOutput: CameraOutput): Promise -在当前会话中，移除一个PreviewOutput实例，通过Promise获取结果。 +从会话中移除[CameraOutput](#cameraoutput)，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| ------------- | ------------------------------- | ---- | ----------------------------- | -| previewOutput | [PreviewOutput](#previewoutput) | 是 | 需要移除的PreviewOutput实例。 | +| 名称 | 类型 | 必填 | 说明 | +| ------------- | ------------------------------- | ---- | ------------------------- | +| cameraOutput | [CameraOutput](#cameraoutput) | 是 | 需要移除的CameraOutput实例。 | **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | +| 类型 | 说明 | +| -------------- | ------------------------ | | Promise | 使用Promise的方式获取结果。 | **示例：** ```js -captureSession.removeOutput(previewOutput).then(() => { - console.log('Promise returned to indicate that the PreviewOutput instance is removed.'); +captureSession.removeOutput(cameraOutput).then(() => { + console.log('Promise returned to indicate that the CameraOutput instance is removed.'); }) ``` -### removeOutput +### start -removeOutput(photoOutput: PhotoOutput, callback: AsyncCallback): void +start\(callback: AsyncCallback\): void -在当前会话中，移除一个PhotoOutput实例，通过注册回调函数获取结果。 +开始会话工作，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| ----------- | --------------------------- | ---- | --------------------------- | -| photoOutput | [PhotoOutput](#photooutput) | 是 | 需要移除的PhotoOutput实例。 | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | -------------------- | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -captureSession.removeOutput(photoOutput, (err) => { +captureSession.start((err) => { if (err) { - console.error('Failed to remove the PhotoOutput instance. ${err.message}'); + console.error(`Failed to start the session ${err.message}`); return; } - console.log('Callback invoked to indicate that the PhotoOutput instance is removed.'); + console.log('Callback invoked to indicate the session start success.'); }); ``` -### removeOutput +### start -removeOutput(photoOutput: PhotoOutput): Promise +start\(\): Promise -在当前会话中，移除一个PhotoOutput实例，通过Promise获取结果。 +开始会话工作，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core -**参数：** - -| 名称 | 类型 | 必填 | 说明 | -| ----------- | --------------------------- | ---- | --------------------------- | -| photoOutput | [PhotoOutput](#photooutput) | 是 | 需要移除的PhotoOutput实例。 | - - **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | +| 类型 | 说明 | +| -------------- | ------------------------ | | Promise | 使用Promise的方式获取结果。 | - **示例：** ```js -captureSession.removeOutput(photoOutput).then(() => { - console.log('Promise returned to indicate that the PhotoOutput instance is removed.'); +captureSession.start().then(() => { + console.log('Promise returned to indicate the session start success.'); }) ``` -### removeOutput +### stop -removeOutput(videoOutput: VideoOutput, callback: AsyncCallback): void +stop\(callback: AsyncCallback\): void -在当前会话中，移除一个VideoOutput实例，通过注册回调函数获取结果。 +停止会话工作，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| ----------- | --------------------------- | ---- | --------------------------- | -| videoOutput | [VideoOutput](#videooutput) | 是 | 需要移除的VideoOutput实例。 | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ------------------- | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -captureSession.removeOutput(videoOutput, (err) => { +captureSession.stop((err) => { if (err) { - console.error('Failed to remove the VideoOutput instance. ${err.message}'); + console.error(`Failed to stop the session ${err.message}`); return; } - console.log('Callback invoked to indicate that the VideoOutput instance is removed.'); + console.log('Callback invoked to indicate the session stop success.'); }); ``` -### removeOutput +### stop -removeOutput(videoOutput: VideoOutput): Promise +stop(): Promise -在当前会话中，移除一个VideoOutput实例，通过Promise获取结果。 +停止会话工作，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core -**参数：** - -| 名称 | 类型 | 必填 | 说明 | -| ----------- | --------------------------- | ---- | --------------------------- | -| videoOutput | [VideoOutput](#videooutput) | 是 | 需要移除的VideoOutput实例。 | - - **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | +| 类型 | 说明 | +| -------------- | ----------------------- | | Promise | 使用Promise的方式获取结果。 | - **示例：** ```js -captureSession.removeOutput(videoOutput).then(() => { - console.log('Promise returned to indicate that the VideoOutput instance is removed.'); +captureSession.stop().then(() => { + console.log('Promise returned to indicate the session stop success.'); }) ``` -### start +### lockForControl -start\(callback: AsyncCallback\): void +lockForControl(callback: AsyncCallback): void -启动拍照会话，通过注册回调函数获取结果。 +请求以独占方式控制设备的硬件属性[CameraInput](#camerainput)，需要调用[unlockForControl](#unlockforcontrol)，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ------------------------ | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ------------------- | | callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -captureSession.start((err) => { +captureSession.lockForControl((err) => { if (err) { - console.error('Failed to start the session ${err.message}'); + console.error(`Failed to lock. ${err.message}`); return; } - console.log('Callback invoked to indicate the session start success.'); -}); + console.log('Locked.'); +}) ``` -### start +### lockForControl -start\(\): Promise +lockForControl(): Promise -启动拍照会话，通过Promise获取结果。 +请求以独占方式控制设备的硬件属性[CameraInput](#camerainput)，需要调用[unlockForControl](#unlockforcontrol)，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | +| 类型 | 说明 | +| -------------- | ------------------------ | | Promise | 使用Promise的方式获取结果。 | **示例：** ```js -captureSession.start().then(() => { - console.log('Promise returned to indicate the session start success.'); +captureSession.lockForControl().then(() => { + console.log('Locked.'); }) ``` -### stop +### unlockForControl -stop\(callback: AsyncCallback\): void +unlockForControl(callback: AsyncCallback): void -停止拍照会话，通过注册回调函数获取结果。 +控制生效，并放弃对设备配置的排他控制，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** - -| 名称 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ------------------------ | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | -------------------- | | callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -captureSession.stop((err) => { +captureSession.unlockForControl((err) => { if (err) { - console.error('Failed to stop the session ${err.message}'); + console.error(`Failed to unlock. ${err.message}`); return; } - console.log('Callback invoked to indicate the session stop success.'); -}); + console.log('Unlocked.'); +}) ``` -### stop +### unlockForControl -stop(): Promise +unlockForControl(): Promise -停止拍照会话，通过Promise获取结果。 +控制生效，并放弃对设备配置的排他控制，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | +| 类型 | 说明 | +| -------------- | ------------------------ | | Promise | 使用Promise的方式获取结果。 | **示例：** ```js -captureSession.stop().then(() => { - console.log('Promise returned to indicate the session stop success.'); +captureSession.unlockForControl().then(() => { + console.log('Unlocked.'); }) ``` @@ -1807,14 +1794,14 @@ captureSession.stop().then(() => { release\(callback: AsyncCallback\): void -释放CaptureSession实例，通过注册回调函数获取结果。 +释放会话资源，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ------------------------ | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | -------------------- | | callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** @@ -1822,7 +1809,7 @@ release\(callback: AsyncCallback\): void ```js captureSession.release((err) => { if (err) { - console.error('Failed to release the CaptureSession instance ${err.message}'); + console.error(`Failed to release the CaptureSession instance ${err.message}`); return; } console.log('Callback invoked to indicate that the CaptureSession instance is released successfully.'); @@ -1833,14 +1820,14 @@ captureSession.release((err) => { release(): Promise -释放CaptureSession实例，通过Promise获取结果。 +释放会话资源，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | +| 类型 | 说明 | +| -------------- | ------------------------ | | Promise | 使用Promise的方式获取结果。 | **示例：** @@ -1851,904 +1838,2652 @@ captureSession.release().then(() => { }) ``` -### on('error') +### hasFlash -on(type: 'error', callback: ErrorCallback): void +hasFlash(callback: AsyncCallback): void -监听拍照会话的错误事件，通过注册回调函数获取结果。 +检测是否有闪光灯，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| :------- | :---------------------------------------------------------- | :--- | :-------------------------------------------- | -| type | string | 是 | 监听事件，固定为'error'，即拍照会话错误事件。 | -| callback | ErrorCallback<[CaptureSessionError](#capturesessionerror)\> | 是 | 回调函数，用于获取错误信息。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | -------------------------------- | +| callback | AsyncCallback | 是 | 回调函数，返回true表示设备支持闪光灯。 | **示例：** ```js -captureSession.on('error', (captureSessionError) => { - console.log('Capture session error code: ' + captureSessionError.code); +cameraInput.hasFlash((err, status) => { + if (err) { + console.error(`Failed to check whether the device has flash light. ${err.message}`); + return; + } + console.log(`Callback returned with flash light support status: ${status}`); }) ``` -## CaptureSessionErrorCode +### hasFlash + +hasFlash(): Promise -枚举，拍照会话的错误码。 +检测是否有闪光灯，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core -| 名称 | 值 | 说明 | -| ------------- | ---- | ---------- | -| ERROR_UNKNOWN | -1 | 未知错误。 | - -## CaptureSessionError +**返回值：** -拍照会话错误对象。 +| 类型 | 说明 | +| ----------------- | ----------------------------------------------- | +| Promise | 使用Promise的方式获取结果，返回true表示设备支持闪光灯。 | -**系统能力：** SystemCapability.Multimedia.Camera.Core +**示例：** -| 名称 | 类型 | 说明 | -| ---- | ------------------------------------------- | -------------------------- | -| code | [CaptureSessionError](#capturesessionerror) | CaptureSession中的错误码。 | +```js +cameraInput.hasFlash().then((status) => { + console.log(`Promise returned with the flash light support status: ${status}`); +}) +``` -## camera.createPreviewOutput +### isFlashModeSupported -createPreviewOutput(surfaceId: string, callback: AsyncCallback): void +isFlashModeSupported(flashMode: FlashMode, callback: AsyncCallback): void -获取PreviewOutput实例，通过注册回调函数获取结果。 +检测闪光灯模式是否支持，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| --------- | ----------------------------------------------- | ---- | ------------------------------------- | -| surfaceId | string | 是 | 从XComponent组件获取的Surface ID。 | -| callback | AsyncCallback<[PreviewOutput](#previewoutput)\> | 是 | 回调函数，用于获取PreviewOutput实例。 | +| 名称 | 类型 | 必填 | 说明 | +| --------- | ----------------------- | ---- | --------------------------------- | +| flashMode | [FlashMode](#flashmode) | 是 | 指定闪光灯模式。 | +| callback | AsyncCallback | 是 | 回调函数，返回true表示支持该闪光灯模式。 | **示例：** ```js -camera.createPreviewOutput(("surfaceId"), (err, previewOutput) => { +cameraInput.isFlashModeSupported(camera.FlashMode.FLASH_MODE_AUTO, (err, status) => { if (err) { - console.error('Failed to create the PreviewOutput instance. ${err.message}'); + console.error(`Failed to check whether the flash mode is supported. ${err.message}`); return; } - console.log('Callback returned with previewOutput instance'); -}); + console.log(`Callback returned with the flash mode support status: ${status}`); +}) ``` -## camera.createPreviewOutput +### isFlashModeSupported -createPreviewOutput(surfaceId: string): Promise\ +isFlashModeSupported(flashMode: FlashMode): Promise -获取PreviewOutput实例，通过Promise获取结果。 +检测闪光灯模式是否支持，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| --------- | ------ | ---- | ---------------------------------- | -| surfaceId | string | 是 | 从XComponent组件获取的Surface ID。 | +| 名称 | 类型 | 必填 | 说明 | +| --------- | ----------------------- | ---- | ------------- | +| flashMode | [FlashMode](#flashmode) | 是 | 指定闪光灯模式。 | **返回值：** -| 类型 | 说明 | -| ----------------------------------------- | --------------------------- | -| Promise<[PreviewOutput](#previewoutput)\> | 使用Promise的方式获取结果。 | +| 类型 | 说明 | +| ----------------- | ---------------------------------------------------- | +| Promise | 使用Promise的方式获取结果，返回true表示设备支持该闪光灯模式。 | **示例：** ```js -camera.createPreviewOutput("surfaceId").then((previewOutput) => { - console.log('Promise returned with the PreviewOutput instance'); +cameraInput.isFlashModeSupported(camera.FlashMode.FLASH_MODE_AUTO).then((status) => { + console.log(`Promise returned with flash mode support status.${status}`); }) ``` -## PreviewOutput +### setFlashMode -预览输出类。 +setFlashMode(flashMode: FlashMode, callback: AsyncCallback): void -### release +设置闪光灯模式，通过注册回调函数获取结果。 -release(callback: AsyncCallback): void +进行设置之前，需要先检查： -释放PreviewOutput实例，通过注册回调函数获取结果。 +1. 设备是否支持闪光灯，可使用方法[hasFlash](#hasflash)。 +2. 设备是否支持指定的闪光灯模式，可使用方法[isFlashModeSupported](#isflashmodesupported)。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ------------------------ | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| --------- | ----------------------- | ---- | --------------------- | +| flashMode | [FlashMode](#flashmode) | 是 | 指定闪光灯模式。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -previewOutput.release((err) => { +cameraInput.setFlashMode(camera.FlashMode.FLASH_MODE_AUTO, (err) => { if (err) { - console.error('Failed to release the PreviewOutput instance ${err.message}'); + console.error(`Failed to set the flash mode ${err.message}`); return; } - console.log('Callback invoked to indicate that the PreviewOutput instance is released successfully.'); -}); + console.log('Callback returned with the successful execution of setFlashMode.'); +}) ``` -### release +### setFlashMode -release(): Promise +setFlashMode(flashMode: FlashMode): Promise + +设置闪光灯模式，通过Promise获取结果。 -释放PreviewOutput实例，通过Promise获取结果。 +进行设置之前，需要先检查： + +1. 设备是否支持闪光灯，可使用方法[hasFlash](#hasflash)。 +2. 设备是否支持指定的闪光灯模式，可使用方法[isFlashModeSupported](#isflashmodesupported)。 **系统能力：** SystemCapability.Multimedia.Camera.Core +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| --------- | ----------------------- | ---- | ------------- | +| flashMode | [FlashMode](#flashmode) | 是 | 指定闪光灯模式。 | + **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | +| 类型 | 说明 | +| -------------- | ------------------------ | | Promise | 使用Promise的方式获取结果。 | - **示例：** ```js -previewOutput.release().then(() => { - console.log('Promise returned to indicate that the PreviewOutput instance is released successfully.'); +cameraInput.setFlashMode(camera.FlashMode.FLASH_MODE_AUTO).then(() => { + console.log('Promise returned with the successful execution of setFlashMode.'); }) ``` -### on('frameStart') +### getFlashMode -on(type: 'frameStart', callback: AsyncCallback): void +getFlashMode(callback: AsyncCallback): void -监听预览帧启动，通过注册回调函数获取结果。 +获取当前设备的闪光灯模式，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| :------- | :------------------- | :--- | :------------------------------------------- | -| type | string | 是 | 监听事件，固定为'frameStart'，即帧启动事件。 | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | --------------------------------- | +| callback | AsyncCallback<[FlashMode](#flashmode)\> | 是 | 回调函数，用于获取当前设备的闪光灯模式。 | **示例：** ```js -previewOutput.on('frameStart', () => { - console.log('Preview frame started'); +cameraInput.getFlashMode((err, flashMode) => { + if (err) { + console.error(`Failed to get the flash mode ${err.message}`); + return; + } + console.log(`Callback returned with current flash mode: ${flashMode}`); }) ``` -### on('frameEnd') +### getFlashMode -on(type: 'frameEnd', callback: AsyncCallback): void +getFlashMode(): Promise -监听预览帧结束，通过注册回调函数获取结果。 +获取当前设备的闪光灯模式，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core -**参数：** +**返回值：** -| 名称 | 类型 | 必填 | 说明 | -| :------- | :------------------- | :--- | :----------------------------------------- | -| type | string | 是 | 监听事件，固定为'frameEnd'，即帧结束事件。 | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 类型 | 说明 | +| --------------------------------- | --------------------------------- | +| Promise<[FlashMode](#flashmode)\> | 使用Promise的方式获取当前的闪光灯模式。 | **示例：** ```js -previewOutput.on('frameEnd', () => { - console.log('Preview frame ended'); +cameraInput.getFlashMode().then((flashMode) => { + console.log(`Promise returned with current flash mode : ${flashMode}`); }) ``` -### on('error') +### isExposureModeSupported -on(type: 'error', callback: ErrorCallback): void +isExposureModeSupported(aeMode: ExposureMode, callback: AsyncCallback): void; -监听预览输出的错误事件，通过注册回调函数获取结果。 +检测曝光模式是否支持，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| :------- | :----------------------------------------------------------- | :--- | :-------------------------------------------- | -| type | string | 是 | 监听事件，固定为'error'，即预览输出错误事件。 | -| callback | ErrorCallback<[PreviewOutputErrorCode](#previewoutputerrorcode)\> | 是 | 回调函数，用于获取错误信息。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------------------| ---- | ----------------------------- | +| aeMode | [ExposureMode](#exposuremode) | 是 | 曝光模式。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取是否支持曝光模式。 | **示例：** ```js -previewOutput.on('error', (previewOutputError) => { - console.log('Preview output error code: ' + previewOutputError.code); +cameraInput.isExposureModeSupported(camera.ExposureMode.EXPOSURE_MODE_LOCKEN,(err) => { + if (err) { + console.log(`Failed to check exposure mode supported ${err.message}`); + return ; + } + console.log('Callback returned with the successful execution of isExposureModeSupported'); }) ``` -## PreviewOutputErrorCode +### isExposureModeSupported + +isExposureModeSupported(aeMode: ExposureMode): Promise -枚举，预览输出的错误码。 +检测曝光模式是否支持，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core -| 名称 | 值 | 说明 | -| ------------- | ---- | ---------- | -| ERROR_UNKNOWN | -1 | 未知错误。 | +**参数：** -## PreviewOutputError +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------------------| ---- | ----------------------------- | +| aeMode | [ExposureMode](#exposuremode) | 是 | 曝光模式。 | -预览输出错误对象。 +**返回值：** -**系统能力：** SystemCapability.Multimedia.Camera.Core +| 名称 | 说明 | +| ----------------- |--------------------------------- | +| Promise | 使用Promise的方式获取支持的曝光模式。 | -| 名称 | 类型 | 说明 | -| ---- | ------------------------------------------------- | ---------------------- | -| code | [PreviewOutputErrorCode](#previewoutputerrorcode) | PreviewOutput中的错误码。 | +**示例：** + +```js +cameraInput.isExposureModeSupported(camera.ExposureMode.EXPOSURE_MODE_LOCKED).then((isSupported) => { + console.log(`Promise returned with exposure mode supported : ${isSupported}`); +}) +``` -## camera.createPhotoOutput +### getExposureMode -createPhotoOutput(surfaceId: string, callback: AsyncCallback): void +getExposureMode(callback: AsyncCallback): void -获取PhotoOutput实例，通过注册回调函数获取结果。 +获取当前曝光模式，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| --------- | ------------------------------------------- | ---- | ----------------------------------- | -| surfaceId | string | 是 | 从[ImageReceiver](js-apis-image.md#imagereceiver9)获取的Surface ID。 | -| callback | AsyncCallback<[PhotoOutput](#photooutput)\> | 是 | 回调函数，用于获取PhotoOutput实例。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------------------| ---- | ---------------------------------------- | +| callback | AsyncCallback<[ExposureMode](#exposuremode)\> | 是 | 回调函数，用于获取当前曝光模式。 | **示例：** ```js -camera.createPhotoOutput(("surfaceId"), (err, photoOutput) => { +cameraInput.getExposureMode((err, exposureMode) => { if (err) { - console.error('Failed to create the PhotoOutput instance. ${err.message}'); - return; + console.log(`Failed to get the exposure mode ${err.message}`); + return ; } - console.log('Callback returned with the PhotoOutput instance.'); -}); + console.log(`Callback returned with current exposure mode: ${exposureMode}`); +}) ``` -## camera.createPhotoOutput +### getExposureMode -createPhotoOutput(surfaceId: string): Promise +getExposureMode(): Promise -获取PhotoOutput实例，通过Promise获取结果。 +获取当前曝光模式，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core -**参数：** - -| 名称 | 类型 | 必填 | 说明 | -| --------- | ------ | ---- | --------------------------------- | -| surfaceId | string | 是 | 从[ImageReceiver](js-apis-image.md#imagereceiver9)获取的Surface ID。 | - **返回值：** -| 类型 | 说明 | -| ------------------------------------- | -------------------------------------- | -| Promise<[PhotoOutput](#photooutput)\> | 使用Promise的方式获取PhotoOutput实例。 | +| 名称 | 说明 | +| --------------------------------------- |------------------------------- | +| Promise<[ExposureMode](#exposuremode)\> | 使用Promise的方式获取当前曝光模式。 | **示例：** ```js -camera.createPhotoOutput("surfaceId").then((photoOutput) => { - console.log('Promise returned with PhotoOutput instance'); +cameraInput.getExposureMode().then((exposureMode) => { + console.log(`Promise returned with current exposure mode : ${exposureMode}`); }) ``` -## ImageRotation - -枚举，图片旋转角度。 - -**系统能力：** SystemCapability.Multimedia.Camera.Core - -| 名称 | 值 | 说明 | -| ------------ | ---- | --------------- | -| ROTATION_0 | 0 | 图片旋转0度。 | -| ROTATION_90 | 90 | 图片旋转90度。 | -| ROTATION_180 | 180 | 图片旋转180度。 | -| ROTATION_270 | 270 | 图片旋转270度。 | - -## QualityLevel - -枚举，图片质量。 - -**系统能力：** SystemCapability.Multimedia.Camera.Core - -| 名称 | 值 | 说明 | -| -------------------- | ---- | -------------- | -| QUALITY_LEVEL_HIGH | 0 | 图片质量高。 | -| QUALITY_LEVEL_MEDIUM | 1 | 图片质量中等。 | -| QUALITY_LEVEL_LOW | 2 | 图片质量差。 | +### setExposureMode -## PhotoCaptureSetting +setExposureMode(aeMode: ExposureMode, callback: AsyncCallback): void -拍摄照片的设置。 +设置曝光模式，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core -| 名称 | 类型 | 必填 | 说明 | -| -------- | ------------------------------- | ---- | -------------- | -| quality | [QualityLevel](#qualitylevel) | 否 | 图片质量。 | -| rotation | [ImageRotation](#imagerotation) | 否 | 图片旋转角度。 | +**参数：** +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------------------| ---- | ----------------------- | +| aeMode | [ExposureMode](#exposuremode) | 是 | 曝光模式。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取设置结果。 | -## PhotoOutput +**示例：** -照片输出类。 +```js +cameraInput.setExposureMode(camera.ExposureMode.EXPOSURE_MODE_LOCKEN,(err) => { + if (err) { + console.log(`Failed to set the exposure mode ${err.message}`); + return ; + } + console.log('Callback returned with the successful execution of setExposureMode'); +}) +``` -### capture +### setExposureMode -capture(callback: AsyncCallback): void +setExposureMode(aeMode: ExposureMode): Promise -拍照，通过注册回调函数获取结果。 +设置曝光模式，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core -**参数：** +**返回值：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ------------------------ | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 说明 | +| ----------------- |---------------------------- | +| Promise | 使用Promise的方式获取设置结果。 | **示例：** ```js -photoOutput.capture((err) => { - if (err) { - console.error('Failed to capture the photo ${err.message}'); - return; - } - console.log('Callback invoked to indicate the photo capture request success.'); -}); +cameraInput.setExposureMode(camera.ExposureMode.EXPOSURE_MODE_LOCKED).then(() => { + console.log('Promise returned with the successful execution of setExposureMode.'); +}) ``` -### capture +### getMeteringPoint -capture(setting: PhotoCaptureSetting, callback: AsyncCallback): void +getMeteringPoint(callback: AsyncCallback): void -根据拍照设置拍照，通过注册回调函数获取结果。 +查询曝光区域中心点，通过注册回调函数获取结果。（该接口目前为预留) **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------- | ---- | ------------------------ | -| setting | [PhotoCaptureSetting](#photocapturesetting) | 是 | 拍照设置。 | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------------------| ---- | ------------------------ | +| callback | AsyncCallback<[Point](#point)\>| 是 | 回调函数，用于获取当前曝光点。 | **示例：** ```js -let settings:PhotoCaptureSetting = { - quality = 1, - rotation = 0 -} -photoOutput.capture(settings, (err) => { +cameraInput.getMeteringPoint((err, exposurePoint) => { if (err) { - console.error('Failed to capture the photo ${err.message}'); - return; + console.log(`Failed to get the current exposure point ${err.message}`); + return ; } - console.log('Callback invoked to indicate the photo capture request success.'); -}); + console.log(`Callback returned with current exposure point: ${exposurePoint}`); +}) ``` -### capture +### getMeteringPoint -capture(setting?: PhotoCaptureSetting): Promise +getMeteringPoint(): Promise -根据拍照设置拍照，通过Promise获取结果。 +查询曝光区域中心点，通过Promise获取结果。（该接口目前为预留) **系统能力：** SystemCapability.Multimedia.Camera.Core -**参数：** - -| 名称 | 类型 | 必填 | 说明 | -| ------- | ------------------------------------------- | ---- | ---------- | -| setting | [PhotoCaptureSetting](#photocapturesetting) | 否 | 拍照设置。 | - **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | -| Promise | 使用Promise的方式获取结果。 | - +| 名称 | 说明 | +| ------------------------- |----------------------------- | +| Promise<[Point](#point)\> | 使用Promise的方式获取当前曝光点。 | **示例：** ```js -photoOutput.capture().then(() => { - console.log('Promise returned to indicate that photo capture request success.'); +cameraInput.getMeteringPoint().then((exposurePoint) => { + console.log(`Promise returned with current exposure point : ${exposurePoint}`); }) ``` -### release +### setMeteringPoint -release(callback: AsyncCallback): void +setMeteringPoint(point: Point, callback: AsyncCallback): void -释放PhotoOutput实例，通过注册回调函数获取结果。 +设置曝光区域中心点，通过注册回调函数获取结果。（该接口目前为预留) **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ------------------------ | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| ------------- | -------------------------------| ---- | ------------------- | +| exposurePoint | [Point](#point) | 是 | 曝光点。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -photoOutput.release((err) => { +const Point1 = {x: 1, y: 1}; + +cameraInput.setMeteringPoint(Point1,(err) => { if (err) { - console.error('Failed to release the PhotoOutput instance ${err.message}'); - return; + console.log(`Failed to set the exposure point ${err.message}`); + return ; } - console.log('Callback invoked to indicate that the PhotoOutput instance is released successfully.'); -}); + console.log('Callback returned with the successful execution of setMeteringPoint'); +}) ``` -### release +### setMeteringPoint -release(): Promise +setMeteringPoint(point: Point): Promise -释放PhotoOutput实例，通过Promise获取结果。 +设置曝光区域中心点，通过Promise获取结果。（该接口目前为预留) + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| ------------- | -------------------------------| ---- | ------------------- | +| exposurePoint | [Point](#point) | 是 | 曝光点。 | + +**返回值：** + +| 名称 | 说明 | +| ----------------- |------------------------ | +| Promise | 使用Promise的方式返回结果。 | + +**示例：** + +```js +const Point2 = {x: 2, y: 2}; + +cameraInput.setMeteringPoint(Point2).then(() => { + console.log('Promise returned with the successful execution of setMeteringPoint'); +}) +``` + +### getExposureBiasRange + +getExposureBiasRange(callback: AsyncCallback\>): void + +查询曝光补偿范围，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------------------| ---- | ----------------------------- | +| callback | AsyncCallback\> | 是 | 回调函数，用于获取补偿范围的数组。 | + +**示例：** + +```js +cameraInput.getExposureBiasRange((err, biasRangeArray) => { + if (err) { + console.log(`Failed to get the array of compenstation range ${err.message}`); + return ; + } + console.log('Callback returned with the array of compenstation range: ' + JSON.stringify(biasRangeArray)); +}) +``` + +### getExposureBiasRange + +getExposureBiasRange(): Promise\> + +查询曝光补偿范围，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 名称 | 说明 | +| ----------------- |-------------------------------------- | +| Promise\> | 使用Promise的方式获取曝光补偿范围。 | + +**示例：** + +```js +cameraInput.isExposureModeSupported(camera.ExposureMode.EXPOSURE_MODE_LOCKED).then((isSupported) => { + console.log(`Promise returned with exposure mode supported : ${isSupported}`); +}) +``` + +### setExposureBias + +setExposureBias(exposureBias: number, callback: AsyncCallback): void + +设置曝光补偿，通过注册回调函数获取结果。 + +进行设置之前，建议先通过方法[getExposureBiasRange](#getexposurebiasrange)查询支持的范围。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------------------| ---- | ------------------- | +| exposureBias | number | 是 | 曝光补偿。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +cameraInput.setExposureBias(-4,(err) => { + if (err) { + console.log(`Failed to set the exposure bias ${err.message}`); + return ; + } + console.log('Callback returned with the successful execution of setExposureBias'); +}) +``` + +### setExposureBias + +setExposureBias(exposureBias: number): Promise + +设置曝光补偿，通过Promise获取结果。 + +进行设置之前，建议先通过方法[getExposureBiasRange](#getexposurebiasrange)查询支持的范围。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------------- | --------- | ---- | --------- | +| exposureBias | number | 是 | 曝光补偿。 | + +**返回值：** + +| 名称 | 说明 | +| ----------------- |------------------------- | +| Promise | 使用Promise的方式获取结果。 | + +**示例：** + +```js +cameraInput.setExposureBias(-4).then(() => { + console.log('Promise returned with the successful execution of setExposureBias.'); +}) +``` + +### getExposureValue + +getExposureValue(callback: AsyncCallback): void + +查询当前曝光值，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------| ---- | --------------------- | +| callback | AsyncCallback | 是 | 回调函数，用于获取曝光值。 | + +**示例：** + +```js +cameraInput.getExposureValue((err, exposureValue) => { + if (err) { + console.log(`Failed to get the exposure value ${err.message}`); + return ; + } + console.log(`Callback returned with the exposure value: ${exposureValue}`); +}) +``` + +### getExposureValue + +getExposureValue(): Promise + +查询当前曝光值，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 名称 | 说明 | +| ----------------- |-------------------------- | +| Promise | 使用Promise的方式获取曝光值。 | + +**示例：** + +```js +cameraInput.getExposureValue().then((exposureValue) => { + console.log(`Promise returned with exposure value: ${exposureValude}`); +}) +``` + +### isFocusModeSupported + +isFocusModeSupported(afMode: FocusMode, callback: AsyncCallback): void + +检测对焦模式是否支持，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | -------------------------------- | +| afMode | [FocusMode](#focusmode) | 是 | 指定的焦距模式。 | +| callback | AsyncCallback | 是 | 回调函数，返回true表示支持该焦距模式。 | + +**示例：** + +```js +cameraInput.isFocusModeSupported(camera.FocusMode.FOCUS_MODE_AUTO, (err, status) => { + if (err) { + console.error(`Failed to check whether the focus mode is supported. ${err.message}`); + return; + } + console.log(`Callback returned with the focus mode support status: ${status}`); +}) +``` + +### isFocusModeSupported + +isFocusModeSupported(afMode: FocusMode): Promise + +检测对焦模式是否支持，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| ------ | ----------------------- | ---- | ------------- | +| afMode | [FocusMode](#focusmode) | 是 | 指定的焦距模式。 | + +**返回值：** + +| 类型 | 说明 | +| ----------------- | --------------------------------------------------- | +| Promise | 使用Promise的方式获取结果，返回true表示设备支持该焦距模式。 | + +**示例：** + +```js +cameraInput.isFocusModeSupported(camera.FocusMode.FOCUS_MODE_AUTO).then((status) => { + console.log(`Promise returned with focus mode support status ${status}.`); +}) +``` + +### setFocusMode + +setFocusMode(afMode: FocusMode, callback: AsyncCallback): void + +设置对焦模式，通过注册回调函数获取结果。 + +进行设置之前，需要先检查设备是否支持指定的焦距模式，可使用方法[isFocusModeSupported](#isfocusmodesupported)。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------- | +| afMode | [FocusMode](#focusmode) | 是 | 指定的焦距模式。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +cameraInput.setFocusMode(camera.FocusMode.FOCUS_MODE_AUTO, (err) => { + if (err) { + console.error(`Failed to set the focus mode ${err.message}`); + return; + } + console.log('Callback returned with the successful execution of setFocusMode.'); +}) +``` + +### setFocusMode + +setFocusMode(afMode: FocusMode): Promise + +设置对焦模式，通过Promise获取结果。 + +进行设置之前，需要先检查设备是否支持指定的焦距模式，可使用方法[isFocusModeSupported](#isfocusmodesupported)。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| ------ | ----------------------- | ---- | ------------- | +| afMode | [FocusMode](#focusmode) | 是 | 指定的焦距模式。 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ------------------------ | +| Promise | 使用Promise的方式获取结果。 | + +**示例：** + +```js +cameraInput.setFocusMode(camera.FocusMode.FOCUS_MODE_AUTO).then(() => { + console.log('Promise returned with the successful execution of setFocusMode.'); +}) +``` + +### getFocusMode + +getFocusMode(callback: AsyncCallback): void + +获取当前的对焦模式，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ------------------------------- | +| callback | AsyncCallback<[FocusMode](#focusmode)\> | 是 | 回调函数，用于获取当前设备的焦距模式。 | + +**示例：** + +```js +cameraInput.getFocusMode((err, afMode) => { + if (err) { + console.error(`Failed to get the focus mode ${err.message}`); + return; + } + console.log(`Callback returned with current focus mode: ${afMode}`); +}) +``` + +### getFocusMode + +getFocusMode(): Promise + +获取当前的对焦模式，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| ------------------- | -------------------------------- | +| Promise | 使用Promise的方式获取当前的焦距模式。 | + +**示例：** + +```js +cameraInput.getFocusMode().then((afMode) => { + console.log(`Promise returned with current focus mode : ${afMode}`); +}) +``` + +### setFocusPoint + +setFocusPoint(point: Point, callback: AsyncCallback): void + +设置焦点，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------- | +| point | [Point](#point) | 是 | 焦点。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +const Point1 = {x: 1, y: 1}; + +cameraInput.setFocusPoint(Point1, (err) => { + if (err) { + console.error(`Failed to set the focus point ${err.message}`); + return; + } + console.log('Callback returned with the successful execution of setFocusPoint.'); +}) +``` + +### setFocusPoint + +setFocusPoint(point: Point): Promise + +设置焦点，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------- | +| point | [Point](#point) | 是 | 焦点。 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------- | +| Promise | 使用Promise的方式获取结果。 | + +**示例：** + +```js +const Point2 = {x: 2, y: 2}; + +cameraInput.setFocusPoint(Point2).then(() => { + console.log('Promise returned with the successful execution of setFocusPoint.'); +}) +``` + +### getFocusPoint + +getFocusPoint(callback: AsyncCallback): void + +查询焦点，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------- | ---- | ----------------------- | +| callback | AsyncCallback<[Point](#point)\> | 是 | 回调函数，用于获取当前焦点。 | + +**示例：** + +```js +cameraInput.getFocusPoint((err, point) => { + if (err) { + console.error(`Failed to get the current focus point ${err.message}`); + return; + } + console.log('Callback returned with the current focus point: ' + JSON.stringify(point)); +}) +``` + +### getFocusPoint + +getFocusPoint(): Promise + +查询焦点，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| --------------- | --------------------------- | +| Promise | 使用Promise的方式获取当前焦点。 | + +**示例：** + +```js +cameraInput.getFocusPoint().then((point) => { + console.log('Promise returned with the current focus point: ' + JSON.stringify(point)); +}) +``` + +### getFocalLength + +getFocalLength(callback: AsyncCallback): void + +查询焦距值，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ----------------------- | +| callback | AsyncCallback | 是 | 回调函数，用于获取当前焦距。 | + +**示例：** + +```js +cameraInput.getFocalLength((err, focalLength) => { + if (err) { + console.error(`Failed to get the current focal length ${err.message}`); + return; + } + console.log(`Callback returned with the current focal length: ${focalLength}`); +}) +``` + +### getFocalLength + +getFocalLength(): Promise + +查询焦距值，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| ---------------- | ----------------------- | +| Promise | 使用Promise的方式获取焦距。 | + +**示例：** + +```js +cameraInput.getFocalLength().then((focalLength) => { + console.log(`Promise returned with the current focal length: ${focalLength}`); +}) +``` + +### getZoomRatioRange + +getZoomRatioRange\(callback: AsyncCallback\>\): void + +获取支持的变焦范围，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------ | ---- | ------------------- | +| callback | AsyncCallback\> | 是 | 回调函数，用于获取可变焦距比范围，返回的数组包括其最小值和最大值。 | + +**示例：** + +```js +cameraInput.getZoomRatioRange((err, zoomRatioRange) => { + if (err) { + console.error(`Failed to get the zoom ratio range. ${err.message}`); + return; + } + console.log(`Callback returned with zoom ratio range: ${zoomRatioRange.length}`); +}) +``` + +### getZoomRatioRange + +getZoomRatioRange\(\): Promise\> + +获取支持的变焦范围，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| ------------------------ | --------------------------- | +| Promise\> | 使用Promise的方式获取当前的可变焦距比范围，返回的数组包括其最小值和最大值。 | + +**示例：** + +```js +cameraInput.getZoomRatioRange().then((zoomRatioRange) => { + console.log(`Promise returned with zoom ratio range: ${zoomRatioRange.length}`); +}) +``` + +### setZoomRatio + +setZoomRatio(zoomRatio: number, callback: AsyncCallback): void + +设置变焦比，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| --------- | -------------------- | ---- | ------------------- | +| zoomRatio | number | 是 | 可变焦距比。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +cameraInput.setZoomRatio(1, (err) => { + if (err) { + console.error(`Failed to set the zoom ratio value ${err.message}`); + return; + } + console.log('Callback returned with the successful execution of setZoomRatio.'); +}) +``` + +### setZoomRatio + +setZoomRatio(zoomRatio: number): Promise + +设置变焦比，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| --------- | ------ | ---- | --------- | +| zoomRatio | number | 是 | 可变焦距比。 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------- | +| Promise | 使用Promise的方式获取结果。 | + +**示例：** + +```js +cameraInput.setZoomRatio(1).then(() => { + console.log('Promise returned with the successful execution of setZoomRatio.'); +}) +``` + +### getZoomRatio + +getZoomRatio(callback: AsyncCallback): void + +获取当前的变焦比，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | ------------------- | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +cameraInput.getZoomRatio((err, zoomRatio) => { + if (err) { + console.error(`Failed to get the zoom ratio ${err.message}`); + return; + } + console.log(`Callback returned with current zoom ratio: ${zoomRatio}`); +}) +``` + +### getZoomRatio + +getZoomRatio(): Promise + +获取当前的变焦比，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| ---------------- | ----------------------- | +| Promise | 使用Promise的方式获取结果。 | + +**示例：** + +```js +cameraInput.getZoomRatio().then((zoomRatio) => { + console.log(`Promise returned with current zoom ratio : ${zoomRatio}`); +}) +``` + +### isVideoStabilizationModeSupported + +isVideoStabilizationModeSupported(vsMode: VideoStabilizationMode, callback: AsyncCallback): void + +查询是否支持指定的视频防抖模式，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------- | ---- | ------------------------------ | +| vsMode | [VideoStabilizationMode](#videostabilizationmode) | 是 | 视频防抖模式。 | +| callback | AsyncCallback | 是 | 回调函数，返回视频防抖模式是否支持。 | + +**示例：** + +```js +captureSession.isVideoStabilizationModeSupported(camera.VideoStabilizationMode.OFF, (err, isSupported) => { + if (err) { + console.error(`Failed to check whether video stabilization mode supported. ${err.message}`); + return; + } + console.log(`Callback returned with the successful execution of isVideoStabilizationModeSupported: ${status}`); +}) +``` + +### isVideoStabilizationModeSupported + +isVideoStabilizationModeSupported(vsMode: VideoStabilizationMode): Promise + +查询是否支持指定的视频防抖模式，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| ----------------- | --------------------------------------------- | +| Promise | 使用Promise的方式获取结果，返回视频防抖模式是否支持。 | + +**示例：** + +```js +captureSession.isVideoStabilizationModeSupported(camera.VideoStabilizationMode.OFF).then((isSupported) => { + console.log(`Promise returned with video stabilization mode supported: ${isSupported}`); +}) +``` + +### getActiveVideoStabilizationMode + +getActiveVideoStabilizationMode(callback: AsyncCallback): void + +查询当前正在使用的视频防抖模式，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | ------------------------------ | +| callback | AsyncCallback | 是 | 回调函数，返回视频防抖是否正在使用。 | + +**示例：** + +```js +captureSession.getActiveVideoStabilizationMode((err, vsMode) => { + if (err) { + console.error(`Failed to get active video stabilization mode ${err.message}`); + return; + } + console.log('Callback returned with the successful execution of getActiveVideoStabilizationMode.'); +}) +``` + +### getActiveVideoStabilizationMode + +getActiveVideoStabilizationMode(): Promise + +查询当前正在使用的视频防抖模式，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| -------------------------------- | ------------------------------------------------- | +| Promise | 使用Promise的方式获取结果，返回视频防抖当前是否正在使用。 | + +**示例：** + +```js +captureSession.getActiveVideoStabilizationMode().then((vsMode) => { + console.log(`Promise returned with the current video stabilization mode: ${vsMode}`); +}) +``` + +### setVideoStabilizationMode + +setVideoStabilizationMode(mode: VideoStabilizationMode, callback: AsyncCallback): void + +设置视频防抖模式，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------- | ---- | --------------------- | +| mode | [VideoStabilizationMode](#videostabilizationmode) | 是 | 需要设置的视频防抖模式。 | +| callback | AsyncCallback | 是 | 回调函数。 | + +**示例：** + +```js +captureSession.setVideoStabilizationMode(camera.VideoStabilizationMode.OFF, (err) => { + if (err) { + console.error(`Failed to set the video stabilization mode ${err.message}`); + return; + } + console.log('Callback returned with the successful execution of setVideoStabilizationMode.'); +}) +``` + +### setVideoStabilizationMode + +setVideoStabilizationMode(mode: VideoStabilizationMode): Promise + +设置视频防抖，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------- | ---- | --------------------- | +| mode | [VideoStabilizationMode](#videostabilizationmode) | 是 | 需要设置的视频防抖模式。 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ------------------------------------------------- | +| Promise | 使用Promise的方式获取结果，返回设置的视频防抖模式的结果。 | + +**示例：** + +```js +captureSession.setVideoStabilizationMode(camera.VideoStabilizationMode.OFF).then(() => { + console.log('Promise returned with the successful execution of setVideoStabilizationMode.'); +}) +``` + +### on('focusStateChange') + +on(type: 'focusStateChange', callback: AsyncCallback): void + +监听焦距的状态变化，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | ------------------------ | +| type | string | 是 | 监听事件，固定为'focusStateChange'，即焦距状态变化事件。 | +| callback | AsyncCallback<[FocusState](#focusstate)\> | 是 | 回调函数，用于获取焦距状态。 | + +**示例：** + +```js +cameraInput.on('focusStateChange', (focusState) => { + console.log(`Focus state : ${focusState}`); +}) +``` + +### on('exposureStateChange') + +on(type: 'exposureStateChange', callback: AsyncCallback): void + +监听曝光的状态变化，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | ---------------------------------------------- | +| type | string | 是 | 监听事件，固定为'exposureStateChange'，即曝光状态变化事件。| +| callback | AsyncCallback<[ExposureState](#exposurestate)\> | 是 | 回调函数，用于获取曝光状态。 | + +**示例：** + +```js +cameraInput.on('exposureStateChange', (exposureState) => { + console.log(`Exposuer state : ${exposureState}`); +}) +``` + +### on('error') + +on(type: 'error', callback: ErrorCallback): void + +监听拍照会话的错误事件，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------------- | ---- | ------------------------------ | +| type | string | 是 | 监听事件，固定为'error'，即拍照会话错误事件。 | +| callback | ErrorCallback<[CaptureSessionError](#capturesessionerror)\> | 是 | 回调函数，用于获取错误信息。 | + +**示例：** + +```js +captureSession.on('error', (captureSessionError) => { + console.log(`Capture session error code: ${captureSessionError.code}`); +}) +``` + +## CaptureSessionErrorCode + +枚举，会话错误类型。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 值 | 说明 | +| ----------------------------- | ---- | -------- | +| ERROR_UNKNOWN | -1 | 未知错误。 | +| ERROR_INSUFFICIENT_RESOURCES | 0 | 资源不足。 | +| ERROR_TIMEOUT | 1 | 超时。 | + +## CaptureSessionError + +会话错误码。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 类型 | 说明 | +| ---- | ------------------------------------------- | -------------------------- | +| code | [CaptureSessionError](#capturesessionerror) | CaptureSession中的错误码。 | + +## CameraOutput + +会话中[CaptureSession](#capturesession)使用的输出信息，output的基类。 + +### release + +release(callback: AsyncCallback): void + +释放输出资源，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ------------------- | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +previewOutput.release((err) => { + if (err) { + console.error(`Failed to release the PreviewOutput instance ${err.message}`); + return; + } + console.log('Callback invoked to indicate that the PreviewOutput instance is released successfully.'); +}); +``` + +### release + +release(): Promise + +释放输出资源，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------- | +| Promise | 使用Promise的方式获取结果。 | + +**示例：** + +```js +previewOutput.release().then(() => { + console.log('Promise returned to indicate that the PreviewOutput instance is released successfully.'); +}) +``` + +## PreviewOutput + +预览输出类。继承[CameraOutput](#cameraoutput) + +### addDeferredSurface + +addDeferredSurface(surfaceId: string, callback: AsyncCallback): void + +在previewOutput生成之后添加surface，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | -------------------------------------------------------------------- | +| surfaceId| string | 是 | 从[XComponent](../arkui-ts/ts-basic-components-xcomponent.md)组件获取的SurfaceID。| +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +previewOutput.addDeferredSurface('surfaceId', (err) => { + if (err) { + console.error(`Failed to add deferredSurface. ${err.message}`); + return; + } + console.log('Callback returned with deferredSurface added.'); +}) +``` + +### addDeferredSurface + +addDeferredSurface(surfaceId: string): Promise + +在previewOutput生成之后添加surface，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -----------| ---- | ------------------------------------------------------------------------------ | +| surfaceId| string | 是 | 从[XComponent](../arkui-ts/ts-basic-components-xcomponent.md)组件获取的SurfaceID。| + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------- | +| Promise | 使用Promise的方式获取结果。 | + +**示例：** + +```js +previewOutput.addDeferredSurface('surfaceId').then(() => { + console.log('Promise returned with deferredSurface added.'); +}) +``` + +### start + +start(callback: AsyncCallback): void + +开始输出预览流，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | -------------------- | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +previewOutput.start((err) => { + if (err) { + console.error(`Failed to start the previewOutput. ${err.message}`); + return; + } + console.log('Callback returned with previewOutput started.'); +}) +``` + +### start + +start(): Promise + +开始输出预览流，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------- | +| Promise | 使用Promise的方式获取结果。 | + +**示例：** + +```js +previewOutput.start().then(() => { + console.log('Promise returned with previewOutput started.'); +}) +``` + +### stop + +stop(callback: AsyncCallback): void + +停止输出预览流，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | -------------------- | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +previewOutput.stop((err) => { + if (err) { + console.error(`Failed to stop the previewOutput. ${err.message}`); + return; + } + console.log('Callback returned with previewOutput stopped.'); +}) +``` + +### stop + +stop(): Promise + +停止输出预览流，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| -------------- | ------------------------ | +| Promise | 使用Promise的方式获取结果。 | + +**示例：** + +```js +previewOutput.stop().then(() => { + console.log('Callback returned with previewOutput stopped.'); +}) +``` + +### on('frameStart') + +on(type: 'frameStart', callback: AsyncCallback): void + +监听预览帧启动，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | --------------------------------------- | +| type | string | 是 | 监听事件，固定为'frameStart'，即帧启动事件。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +previewOutput.on('frameStart', () => { + console.log('Preview frame started'); +}) +``` + +### on('frameEnd') + +on(type: 'frameEnd', callback: AsyncCallback): void + +监听预览帧结束，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ------------------------------------- | +| type | string | 是 | 监听事件，固定为'frameEnd'，即帧结束事件。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +previewOutput.on('frameEnd', () => { + console.log('Preview frame ended'); +}) +``` + +### on('error') + +on(type: 'error', callback: ErrorCallback): void + +监听预览输出的错误事件，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------------------- | ---- | ------------------------ | +| type | string | 是 | 监听事件，固定为'error'，即预览输出错误事件。| +| callback | ErrorCallback<[PreviewOutputErrorCode](#previewoutputerrorcode)\> | 是 | 回调函数，用于获取错误信息。 | + +**示例：** + +```js +previewOutput.on('error', (previewOutputError) => { + console.log(`Preview output error code: ${previewOutputError.code}`); +}) +``` + +## PreviewOutputErrorCode + +枚举，预览输出错误类型。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 值 | 说明 | +| ------------- | ---- | -------- | +| ERROR_UNKNOWN | -1 | 未知错误。 | + +## PreviewOutputError + +预览输出错误码。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 类型 | 说明 | +| ---- | ------------------------------------------------- | ---------------------- | +| code | [PreviewOutputErrorCode](#previewoutputerrorcode) | PreviewOutput中的错误码。 | + +## ImageRotation + +枚举，图片旋转角度。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 值 | 说明 | +| ------------ | ---- | ------------- | +| ROTATION_0 | 0 | 图片旋转0度。 | +| ROTATION_90 | 90 | 图片旋转90度。 | +| ROTATION_180 | 180 | 图片旋转180度。 | +| ROTATION_270 | 270 | 图片旋转270度。 | + +## Location + +图片地理位置信息。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 类型 | 必填 |说明 | +| ------------ | ------ | --- |------------ | +| latitude | number | 是 |纬度(度)。 | +| longitude | number | 是 |经度(度)。 | +| altitude | number | 是 |海拔(米)。 | + +## QualityLevel + +枚举，图片质量。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 值 | 说明 | +| -------------------- | ---- | ------------ | +| QUALITY_LEVEL_HIGH | 0 | 图片质量高。 | +| QUALITY_LEVEL_MEDIUM | 1 | 图片质量中等。 | +| QUALITY_LEVEL_LOW | 2 | 图片质量差。 | + + +## PhotoCaptureSetting + +拍摄照片的设置。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 类型 | 必填 | 默认值 | 说明 | +| -------- | ------------------------------- | ---- | ----------------- | -----------------| +| quality | [QualityLevel](#qualitylevel) | 否 | QUALITY_LEVEL_HIGH| 图片质量。 | +| rotation | [ImageRotation](#imagerotation) | 否 | ROTATION_0 | 图片旋转角度。 | +| location | [Location](#location) | 否 | (0,0,0) | 图片地理位置信息。 | + +## PhotoOutput + +拍照会话中使用的输出信息。 + +### getDefaultCaptureSetting + +getDefaultCaptureSetting(callback: AsyncCallback): void + +获取默认拍照参数，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------------- | ---- | -------------------- | +| callback | AsyncCallback<[PhotoCaptureSetting](#photocapturesetting)\> | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +photoOutput.getDefaultCaptureSetting((err, photocapturesetting) => { + if (err) { + console.error(`Failed to get the defaultCaptureSetting. ${err.message}`); + return; + } + console.log('Callback returned with an array of defaultCaptureSetting.'); +}) +``` + +### getDefaultCaptureSetting + +getDefaultCaptureSetting(): Promise + +获取默认拍照参数，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| ----------------------------------------------------- | ----------------------- | +| Promise<[PhotoCaptureSetting](#photocapturesetting)\> | 使用Promise的方式获取结果。 | + +**示例：** + +```js +photoOutput.getDefaultCaptureSetting().then((photocapturesetting) => { + console.log('Callback returned with an array of defaultCaptureSetting.'); +}) +``` + +### capture + +capture(callback: AsyncCallback): void + +以默认设置触发一次拍照，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ------------------- | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +photoOutput.capture((err) => { + if (err) { + console.error(`Failed to capture the photo ${err.message}`); + return; + } + console.log('Callback invoked to indicate the photo capture request success.'); +}); +``` + +### capture + +capture(setting: PhotoCaptureSetting, callback: AsyncCallback): void + +以指定参数触发一次拍照，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------- | ---- | -------------------- | +| setting | [PhotoCaptureSetting](#photocapturesetting) | 是 | 拍照设置。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +let settings:PhotoCaptureSetting = { + quality = 1, + rotation = 0 +} +photoOutput.capture(settings, (err) => { + if (err) { + console.error(`Failed to capture the photo ${err.message}`); + return; + } + console.log('Callback invoked to indicate the photo capture request success.'); +}); +``` + +### capture + +capture(setting?: PhotoCaptureSetting): Promise + +以指定参数触发一次拍照，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| ------- | ------------------------------------------- | ---- | -------- | +| setting | [PhotoCaptureSetting](#photocapturesetting) | 否 | 拍照设置。 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ------------------------ | +| Promise | 使用Promise的方式获取结果。 | + + +**示例：** + +```js +photoOutput.capture().then(() => { + console.log('Promise returned to indicate that photo capture request success.'); +}) +``` + +### isMirrorSupported + +isMirrorSupported(callback: AsyncCallback): void + +查询是否支持镜像拍照，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------- | ---- | -------------------------- | +| callback | AsyncCallback | 是 | 回调函数,返回是否支持镜像拍照。 | + +**示例：** + +```js +captureSession.isMirrorSupported((err, isSupported) => { + if (err) { + console.error(`Failed to check mirror is supported ${err.message}`); + return; + } + console.log('Callback returned with the successful execution of isMirrorSupported.'); +}) +``` + +### isMirrorSupported + +isMirrorSupported(): Promise + +查询是否支持镜像拍照，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ------------------------------------------- | +| Promise | 使用Promise的方式获取结果，返回是否支持自拍结果。 | + +**示例：** + +```js +captureSession.isMirrorSupported().then((isSupported) => { + console.log(`Promise returned with mirror supported: ${isSupported}`); +}) +``` + +### on('captureStart') + +on(type: 'captureStart', callback: AsyncCallback): void + +监听拍照开始，通过注册回调函数获取Capture ID。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | ------------------------------------------ | +| type | string | 是 | 监听事件，固定为'captureStart'，即拍照启动事件。 | +| callback | AsyncCallback | 是 | 使用callback的方式获取Capture ID。 | + +**示例：** + +```js +photoOutput.on('captureStart', (err, captureId) => { + console.log(`photo capture stated, captureId : ${captureId}`); +}) +``` + +### on('frameShutter') + +on(type: 'frameShutter', callback: AsyncCallback): void + +监听拍照帧输出捕获，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------- | --- | ------------------------------------ | +| type | string | 是 | 监听事件，固定为'frameShutter'，即帧刷新事件。 | +| callback | AsyncCallback<[FrameShutterInfo](#frameshutterinfo)\> | 是 | 回调函数，用于获取相关信息。 | + +**示例：** + +```js +photoOutput.on('frameShutter', (err, frameShutterInfo) => { + console.log(`photo capture end, captureId : ${frameShutterInfo.captureId}`); + console.log(`Timestamp for frame : ${frameShutterInfo.timestamp}`); +}) +``` + +### on('captureEnd') + +on(type: 'captureEnd', callback: AsyncCallback): void + +监听拍照结束，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------- | ---- | ---------------------------------------- | +| type | string | 是 | 监听事件，固定为'captureEnd'，即拍照停止事件。 | +| callback | AsyncCallback<[CaptureEndInfo](#captureendinfo)\> | 是 | 回调函数，用于获取相关信息。 | + +**示例：** + +```js +photoOutput.on('captureEnd', (err, captureEndInfo) => { + console.log(`photo capture end, captureId : ${captureEndInfo.captureId}`); + console.log(`frameCount : ${captureEndInfo.frameCount}`); +}) +``` + +### on('error') + +on(type: 'error', callback: ErrorCallback): void + +监听拍照输出发生错误，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------- | ---- | ----------------------------------- | +| type | string | 是 | 监听事件，固定为'error'，即拍照错误事件。 | +| callback | ErrorCallback<[PhotoOutputError](#photooutputerror)\> | 是 | 回调函数，用于获取错误信息。 | + +**示例：** + +```js +photoOutput.on('error', (err, photoOutputError) => { + console.log(`Photo output error code: ${photoOutputError.code}`); +}) +``` + +## FrameShutterInfo + +拍照帧输出信息。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 类型 | 必填 | 说明 | +| --------- | ------ | ---- | ---------- | +| captureId | number | 是 | 拍照的ID。 | +| timestamp | number | 是 | 快门时间戳。 | + +## CaptureEndInfo + +拍照停止信息。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 类型 | 必填 | 说明 | +| ---------- | ------ | ---- | ---------| +| captureId | number | 是 | 拍照的ID。 | +| frameCount | number | 是 | 帧数。 | + +## PhotoOutputErrorCode + +枚举，拍照输出错误类型。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 值 | 说明 | +| ----------------------------- | ---- | --------------- | +| ERROR_UNKNOWN | -1 | 未知错误。 | +| ERROR_DRIVER_ERROR | 0 | 驱动或者硬件错误。 | +| ERROR_INSUFFICIENT_RESOURCES | 1 | 资源不足。 | +| ERROR_TIMEOUT | 2 | 超时。 | + +## PhotoOutputError + +拍照输出错误码。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +| 名称 | 类型 | 说明 | +| ---- | ------------------------------------- | ----------------------- | +| code | [PhotoOutputError](#photooutputerror) | PhotoOutput中的错误码。 | + +## VideoOutput + +录像会话中使用的输出信息。 + +### start + +start(callback: AsyncCallback): void + +启动录制，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | -------------------- | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +videoOutput.start((err) => { + if (err) { + console.error(`Failed to start the video output ${err.message}`); + return; + } + console.log('Callback invoked to indicate the video output start success.'); +}); +``` + +### start + +start(): Promise + +启动录制，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | +| 类型 | 说明 | +| -------------- | ----------------------- | | Promise | 使用Promise的方式获取结果。 | **示例：** ```js -photoOutput.release().then(() => { - console.log('Promise returned to indicate that the PhotoOutput instance is released successfully.'); +videoOutput.start().then(() => { + console.log('Promise returned to indicate that start method execution success.'); }) ``` -### on('captureStart') +### stop -on(type: 'captureStart', callback: AsyncCallback): void +stop(callback: AsyncCallback): void -监听拍照启动，通过注册回调函数获取Capture ID。 +结束录制，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| :------- | :--------------------- | :--- | :----------------------------------------------- | -| type | string | 是 | 监听事件，固定为'captureStart'，即拍照启动事件。 | -| callback | AsyncCallback | 是 | 使用callback的方式获取Capture ID。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ------------------------ | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -photoOutput.on('captureStart', (err, captureId) => { - console.log('photo capture stated, captureId : ' + captureId); +videoOutput.stop((err) => { + if (err) { + console.error(`Failed to stop the video output ${err.message}`); + return; + } + console.log('Callback invoked to indicate the video output stop success.'); +}); +``` + +### stop + +stop(): Promise + +结束录制，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------- | +| Promise | 使用Promise的方式获取结果。 | + +**示例：** + +```js +videoOutput.stop().then(() => { + console.log('Promise returned to indicate that stop method execution success.'); +}) +``` + +### getFrameRateRange + +getFrameRateRange(callback: AsyncCallback\>): void + +获取帧率范围，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ------------------------ | +| callback | AsyncCallback\> | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +videoOutput.getFrameRateRange((err) => { + if (err) { + console.error(`Failed to get the frameRateRange ${err.message}`); + return; + } + console.log('getFrameRateRange success.'); +}); +``` + +### getFrameRateRange + +getFrameRateRange(): Promise\> + +获取帧率范围，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------- | +| Promise\> | 使用Promise的方式获取结果。 | + +**示例：** + +```js +videoOutput.getFrameRateRange().then(() => { + console.log('getFrameRateRange success.'); }) +``` + +### setFrameRateRange + +setFrameRateRange(minFrameRate: number, maxFrameRate: number, callback: AsyncCallback\>): void + +获取帧率范围，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| ------------ | ----------------------------- | ---- | ------------------- | +| minFrameRate | number | 是 | 最小帧率。 | +| maxFrameRate | number | 是 | 最大帧率。 | +| callback | AsyncCallback\> | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +videoOutput.setFrameRateRange(minFrameRate， maxFrameRate，(err) => { + if (err) { + console.error(`Failed to set the frameRateRange ${err.message}`); + return; + } + console.log('setFrameRateRange success.'); +}); ``` -### on('frameShutter') +### setFrameRateRange -on(type: 'frameShutter', callback: AsyncCallback): void +setFrameRateRange(minFrameRate: number, maxFrameRate: number): Promise\> -监听快门，通过注册回调函数获取结果。 +获取帧率范围，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| :------- | :---------------------------------------------------- | :--- | :--------------------------------------------- | -| type | string | 是 | 监听事件，固定为'frameShutter'，即帧刷新事件。 | -| callback | AsyncCallback<[FrameShutterInfo](#frameshutterinfo)\> | 是 | 回调函数，用于获取相关信息。 | +| 名称 | 类型 | 必填 | 说明 | +| ------------ | ----------------------------- | ---- | ------------------- | +| minFrameRate | number | 是 | 最小帧率。 | +| maxFrameRate | number | 是 | 最大帧率。 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------------------- | +| Promise\> | 使用Promise的方式获取结果。 | **示例：** ```js -photoOutput.on('frameShutter', (err, frameShutterInfo) => { - console.log('photo capture end, captureId : ' + frameShutterInfo.captureId); - console.log('Timestamp for frame : ' + frameShutterInfo.timestamp); +videoOutput.setFrameRateRange(minFrameRate， maxFrameRate).then(() => { + console.log('setFrameRateRange success.'); +}) +``` + +### on('frameStart') + +on(type: 'frameStart', callback: AsyncCallback): void + +监听录像开始，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**参数：** + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ----------------------------------------- | +| type | string | 是 | 监听事件，固定为'frameStart'，即视频帧开启事件。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | + +**示例：** + +```js +videoOutput.on('frameStart', () => { + console.log('Video frame started'); }) ``` -### on('captureEnd') +### on('frameEnd') -on(type: 'captureEnd', callback: AsyncCallback): void +on(type: 'frameEnd', callback: AsyncCallback): void -监听拍照停止，通过注册回调函数获取结果。 +监听录像结束，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| :------- | :------------------------------------------------ | :--- | :--------------------------------------------- | -| type | string | 是 | 监听事件，固定为'captureEnd'，即拍照停止事件。 | -| callback | AsyncCallback<[CaptureEndInfo](#captureendinfo)\> | 是 | 回调函数，用于获取相关信息。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ------------------------------------------ | +| type | string | 是 | 监听事件，固定为'frameEnd'，即视频帧结束事件 。 | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -photoOutput.on('captureEnd', (err, captureEndInfo) => { - console.log('photo capture end, captureId : ' + captureEndInfo.captureId); - console.log('frameCount : ' + captureEndInfo.frameCount); +videoOutput.on('frameEnd', () => { + console.log('Video frame ended'); }) ``` ### on('error') -on(type: 'error', callback: ErrorCallback): void +on(type: 'error', callback: ErrorCallback): void -监听拍照的错误事件，通过注册回调函数获取结果。 +监听录像输出发生错误，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| :------- | :---------------------------------------------------- | :--- | :---------------------------------------- | -| type | string | 是 | 监听事件，固定为'error'，即拍照错误事件。 | -| callback | ErrorCallback<[PhotoOutputError](#photooutputerror)\> | 是 | 回调函数，用于获取错误信息。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------ | ---- | -------------------------------------- | +| type | string | 是 | 监听事件，固定为'error'，即视频输出错误事件。 | +| callback | Callback<[VideoOutputError](#videooutputerror)\> | 是 | 回调函数，用于获取错误信息。 | **示例：** ```js -photoOutput.on('error', (err, photoOutputError) => { - console.log('Photo output error code: ' + photoOutputError.code); +videoOutput.on('error', (VideoOutputError) => { + console.log(`Video output error code: ${VideoOutputError.code}`); }) ``` -## FrameShutterInfo +## VideoOutputErrorCode -快门事件信息。 +枚举，录像输出错误类型。 **系统能力：** SystemCapability.Multimedia.Camera.Core -| 名称 | 类型 | 必填 | 说明 | -| --------- | ------ | ---- | ----------------------------- | -| captureId | number | 是 | CaptureId，本次拍摄动作的ID。 | -| timestamp | number | 是 | 时间戳。 | +| 名称 | 值 | 说明 | +| --------------------- | ---- | ------------ | +| ERROR_UNKNOWN | -1 | 未知错误。 | +| ERROR_DRIVER_ERROR | 0 | 驱动或者硬件错误。| -## CaptureEndInfo +## VideoOutputError -拍照停止信息。 +录像输出错误码。 **系统能力：** SystemCapability.Multimedia.Camera.Core -| 名称 | 类型 | 必填 | 说明 | -| ---------- | ------ | ---- | ----------------------------- | -| captureId | number | 是 | CaptureId，本次拍摄动作的ID。 | -| frameCount | number | 是 | 帧计数。 | +| 名称 | 类型 | 说明 | +| ---- | ------------------------------------- | ----------------------- | +| code | [PhotoOutputError](#photooutputerror) | VideoOutput中的错误码。 | -## PhotoOutputErrorCode +## MetadataObjectType -枚举，拍照输出的错误码。 +枚举，metadata流。 **系统能力：** SystemCapability.Multimedia.Camera.Core -| 名称 | 值 | 说明 | -| ------------- | ---- | ---------- | -| ERROR_UNKNOWN | -1 | 未知错误。 | +| 名称 | 值 | 说明 | +| ------------------------- | ---- | ----------------- | +| FACE_DETECTION | 0 | metadata对象类型。 | -## PhotoOutputError +## Rect -拍照输出错误对象。 +矩形定义。 **系统能力：** SystemCapability.Multimedia.Camera.Core -| 名称 | 类型 | 说明 | -| ---- | ------------------------------------- | ----------------------- | -| code | [PhotoOutputError](#photooutputerror) | PhotoOutput中的错误码。 | +| 名称 | 类型 | 说明 | +| -------- | ------ | -------------------- | +| topLeftX | number | 矩形区域左上角x坐标。 | +| topLeftY | number | 矩形区域左上角y坐标。 | +| width | number | 矩形宽。 | +| height | number | 矩形高。 | -## camera.createVideoOutput +## MetadataObject -createVideoOutput(surfaceId: string, callback: AsyncCallback): void +相机元能力信息，[CameraInput](#camerainput)相机信息中的数据来源。 -获取VideoOutput实例，通过注册回调函数获取结果。 +### getType + +getType(callback: AsyncCallback): void + +查询metadata对象类型，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| --------- | ------------------------------------------- | ---- | ----------------------------------- | -| surfaceId | string | 是 | 从VideoRecorder获取的Surface ID。 | -| callback | AsyncCallback<[VideoOutput](#videooutput)\> | 是 | 回调函数，用于获取VideoOutput实例。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------------------------- | --- | -------------------- | +| callback | AsyncCallback<[MetadataObjectType](#metadataobjecttype)\> | 是 | 回调函数，用于获取结果。 | **示例：** ```js -camera.createVideoOutput(("surfaceId"), (err, videoOutput) => { +metadataObject.getType((err, metadataObjectType) => { if (err) { - console.error('Failed to create the VideoOutput instance. ${err.message}'); + console.error(`Failed to get type. ${err.message}`); return; } - console.log('Callback returned with the VideoOutput instance'); -}); + console.log('Callback returned with an array of metadataObjectType.'); +}) ``` -## camera.createVideoOutput +### getType -createVideoOutput(surfaceId: string): Promise +getType(): Promise -获取VideoOutput实例，通过Promise获取结果。 +查询metadata对象类型，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core -**参数：** - -| 名称 | 类型 | 必填 | 说明 | -| --------- | ------ | ---- | --------------------------------- | -| surfaceId | string | 是 | 从VideoRecorder获取的Surface ID。 | - **返回值：** -| 类型 | 说明 | -| ------------------------------------- | -------------------------------------- | -| Promise<[VideoOutput](#videooutput)\> | 使用Promise的方式获取VideoOutput实例。 | +| 类型 | 说明 | +| --------------------------------------------------- | --------------------------- | +| Promise<[MetadataObjectType](#metadataobjecttype)\> | 使用Promise的方式获取结果。 | **示例：** ```js -camera.createVideoOutput("surfaceId" -).then((videoOutput) => { - console.log('Promise returned with the VideoOutput instance'); +metadataObject.getType().then((metadataObjectType) => { + console.log('Callback returned with an array of metadataObjectType.'); }) ``` -## VideoOutput - -视频输出类。 - -### start +### getTimestamp -start(callback: AsyncCallback): void +getTimestamp(callback: AsyncCallback): void -开始拍摄视频，通过注册回调函数获取结果。 +查询metadata时间戳，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ------------------------ | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------------- | ---- | ------------------------ | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -videoOutput.start((err) => { +metadataObject.getTimestamp((err) => { if (err) { - console.error('Failed to start the video output ${err.message}'); + console.error(`Failed to get timestamp. ${err.message}`); return; } - console.log('Callback invoked to indicate the video output start success.'); -}); + console.log('Callback returned with timestamp getted.'); +}) ``` -### start +### getTimestamp -start(): Promise +getTimestamp(): Promise -开始拍摄视频，通过Promise获取结果。 +查询metadata时间戳，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | -| Promise | 使用Promise的方式获取结果。 | - +| 类型 | 说明 | +| ---------------- | --------------------------- | +| Promise | 使用Promise的方式获取结果。 | **示例：** ```js -videoOutput.start().then(() => { - console.log('Promise returned to indicate that start method execution success.'); +metadataObject.getTimestamp().then(() => { + console.log('Callback returned with timestamp getted.'); }) ``` -### stop +### getBoundingBox -stop(callback: AsyncCallback): void +getBoundingBox(callback: AsyncCallback): void -停止拍摄视频，通过注册回调函数获取结果。 +查询metadata的边界框，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ------------------------ | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------------- | ---- | ------------------------ | +| callback | AsyncCallback<[Rect](#rect)\> | 是 | 回调函数，用于获取结果。 | **示例：** ```js -videoOutput.stop((err) => { +metadataObject.getBoundingBox((err, rect) => { if (err) { - console.error('Failed to stop the video output ${err.message}'); + console.error(`Failed to get boundingBox. ${err.message}`); return; } - console.log('Callback invoked to indicate the video output stop success.'); -}); + console.log('Callback returned with boundingBox getted.'); +}) ``` -### stop +### getBoundingBox -stop(): Promise +getBoundingBox(): Promise -停止拍摄视频，通过Promise获取结果。 +查询metadata的边界框，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | -| Promise | 使用Promise的方式获取结果。 | +| 类型 | 说明 | +| ---------------------- | --------------------------- | +| Promise<[Rect](#rect)\> | 使用Promise的方式获取结果。 | **示例：** ```js -videoOutput.start().then(() => { - console.log('Promise returned to indicate that stop method execution success.'); +metadataObject.getBoundingBox().then((rect) => { + console.log('Callback returned with boundingBox getted.'); }) ``` -### release +## MetadataFaceObject -release(callback: AsyncCallback): void +metadata的人脸对象。继承[MetadataObject](#metadataobject) + +## MetadataOutput + +metadata流。继承[CameraOutput](#cameraoutput) + +### start + +start(callback: AsyncCallback): void -释放VideoOutput实例，通过注册回调函数获取结果。 +开始输出metadata，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ------------------------ | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------------- | ---- | ------------------- | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -videoOutput.release((err) => { +metadataOutput.start((err) => { if (err) { - console.error('Failed to release the VideoOutput instance ${err.message}'); + console.error(`Failed to start metadataOutput. ${err.message}`); return; } - console.log('Callback invoked to indicate that the VideoOutput instance is released successfully.'); -}); + console.log('Callback returned with metadataOutput started.'); +}) ``` -### release +### start -release(): Promise +start(): Promise -释放VideoOutput实例，通过Promise获取结果。 +开始输出metadata，通过Promise获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------- | -| Promise | 使用Promise的方式获取结果。 | - +| 类型 | 说明 | +| ---------------------- | ------------------------ | +| Promise | 使用Promise的方式获取结果。 | **示例：** ```js -videoOutput.release().then(() => { - console.log('Promise returned to indicate that the VideoOutput instance is released successfully.'); +metadataOutput.start().then(() => { + console.log('Callback returned with metadataOutput started.'); }) ``` -### on('frameStart') +### stop -on(type: 'frameStart', callback: AsyncCallback): void +stop(callback: AsyncCallback): void -监听视频帧开启，通过注册回调函数获取结果。 +停止输出metadata，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| :------- | :------------------- | :--- | :----------------------------------------------- | -| type | string | 是 | 监听事件，固定为'frameStart'，即视频帧开启事件。 | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------------------------- | ---- | ------------------- | +| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | **示例：** ```js -videoOutput.on('frameStart', () => { - console.log('Video frame started'); +metadataOutput.stop((err) => { + if (err) { + console.error(`Failed to stop the metadataOutput. ${err.message}`); + return; + } + console.log('Callback returned with metadataOutput stopped.'); }) ``` -### on('frameEnd') +### stop -on(type: 'frameEnd', callback: AsyncCallback): void +stop(): Promise + +停止输出metadata，通过Promise获取结果。 + +**系统能力：** SystemCapability.Multimedia.Camera.Core + +**返回值：** + +| 类型 | 说明 | +| ---------------------- | --------------------------- | +| Promise | 使用Promise的方式获取结果。 | + +**示例：** + +```js +metadataOutput.stop().then(() => { + console.log('Callback returned with metadataOutput stopped.'); +}) +``` + +### on('metadataObjectsAvailable') -监听视频帧结束，通过注册回调函数获取结果。 +on(type: 'metadataObjectsAvailable', callback: AsyncCallback\>): void + +监听检测到的metadata对象，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| :------- | :------------------- | :--- | :--------------------------------------------- | -| type | string | 是 | 监听事件，固定为'frameEnd'，即视频帧结束事件。 | -| callback | AsyncCallback | 是 | 回调函数，用于获取结果。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------ | ---- | ------------------------------------ | +| type | string | 是 | 监听事件，固定为'metadataObjectsAvailable'，即metadata对象。 | +| callback | Callback\> | 是 | 回调函数，用于获取错误信息。 | **示例：** ```js -videoOutput.on('frameEnd', () => { - console.log('Video frame ended'); +metadataOutput.on('metadataObjectsAvailable', (metadataObject) => { + console.log(`metadata output error code: ${metadataObject.code}`); }) ``` ### on('error') -on(type: 'error', callback: ErrorCallback): void +on(tuype: 'error', callback: ErrorCallback): void -监听视频输出的错误事件，通过注册回调函数获取结果。 +监听metadata流的错误，通过注册回调函数获取结果。 **系统能力：** SystemCapability.Multimedia.Camera.Core **参数：** -| 名称 | 类型 | 必填 | 说明 | -| :------- | :----------------------------------------------- | :--- | :-------------------------------------------- | -| type | string | 是 | 监听事件，固定为'error'，即视频输出错误事件。 | -| callback | Callback<[VideoOutputError](#videooutputerror)\> | 是 | 回调函数，用于获取错误信息。 | +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------ | ---- | --------------------------------------- | +| type | string | 是 | 监听事件，固定为'error'，即metadata流的错误。 | +| callback | Callback<[MetadataOutputError](#metadataoutputerror)\> | 是 | 回调函数，用于获取错误信息。 | **示例：** ```js -videoOutput.on('error', (VideoOutputError) => { - console.log('Video output error code: ' + VideoOutputError.code); +metadataOutput.on('error', (metadataOutputError) => { + console.log(`Metadata output error code: ${metadataOutputError.code}`); }) ``` -## VideoOutputErrorCode +## MetadataOutputErrorCode -枚举，视频输出的错误码。 +枚举，metadata输出错误类型。 **系统能力：** SystemCapability.Multimedia.Camera.Core -| 名称 | 值 | 说明 | -| ------------- | ---- | ---------- | -| ERROR_UNKNOWN | -1 | 未知错误。 | +| 名称 | 值 | 说明 | +| ------------------------------- | ---- | -------- | +| ERROR_UNKNOWN | -1 | 未知错误。 | +| ERROR_INSUFFICIENT_RESOURCES | 0 | 资源不足。 | -## VideoOutputError +## MetadataOutputError -视频输出错误对象。 +metadata输出错误码。 **系统能力：** SystemCapability.Multimedia.Camera.Core | 名称 | 类型 | 说明 | | ---- | ------------------------------------- | ----------------------- | -| code | [PhotoOutputError](#photooutputerror) | VideoOutput中的错误码。 | \ No newline at end of file +| code | [MetadataOutputErrorCode](#metadataoutputerrorcode) | MetadataOutput中的错误码。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-media.md b/zh-cn/application-dev/reference/apis/js-apis-media.md index dab4a75c0a4ee4f5079cfd0fcce5497b76be0abc..32319b0f5e36631db7f00257255834b220947330 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-media.md +++ b/zh-cn/application-dev/reference/apis/js-apis-media.md @@ -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>): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------------ | ---- | -------------------------- | -| callback | AsyncCallback> | 是 | 获取音频轨道信息回调方法。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | +| callback | AsyncCallback> | 是 | 音频轨道信息MediaDescription数组回调方法。 | **示例：** @@ -462,9 +462,9 @@ getTrackDescription(): Promise> **返回值：** -| 类型 | 说明 | -| ------------------------------------------------------ | ------------------------------- | -| Promise> | 获取音频轨道信息Promise返回值。 | +| 类型 | 说明 | +| ------------------------------------------------------ | ----------------------------------------------- | +| Promise> | 音频轨道信息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\): void -开始订阅音频播放时间更新事件。 +开始订阅音频播放时间更新事件。处于播放状态时，每隔1s上报一次该事件。 **系统能力：** SystemCapability.Multimedia.Media.AudioPlayer @@ -1013,10 +1013,10 @@ seek(timeMs: number, callback: AsyncCallback\): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | ---- | ------------------------------------ | -| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms）。 | -| callback | function | 是 | 跳转到指定播放位置的回调方法。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------------------------------------------ | +| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 | +| callback | function | 是 | 跳转到指定播放位置的回调方法。 | **示例：** @@ -1041,11 +1041,11 @@ seek(timeMs: number, mode:SeekMode, callback: AsyncCallback\): 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\ **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---------------------- | ---- | ------------------------------------ | -| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms）。 | -| mode | [SeekMode](#seekmode8) | 否 | 跳转模式。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------------------- | ---- | ------------------------------------------------------------ | +| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 | +| mode | [SeekMode](#seekmode8) | 否 | 跳转模式。 | **返回值：** -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise\ | 跳转到指定播放位置的Promise返回值。 | +| 类型 | 说明 | +| -------------- | ------------------------------------------- | +| Promise\ | 跳转到指定播放位置的Promise返回值，单位ms。 | **示例：** @@ -1219,9 +1219,9 @@ getTrackDescription(callback: AsyncCallback>): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------------ | ---- | -------------------------- | -| callback | AsyncCallback> | 是 | 获取视频轨道信息回调方法。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | +| callback | AsyncCallback> | 是 | 视频轨道信息MediaDescription数组回调方法。 | **示例：** @@ -1255,9 +1255,9 @@ getTrackDescription(): Promise> **返回值：** -| 类型 | 说明 | -| ------------------------------------------------------ | ------------------------------- | -| Promise> | 获取视频轨道信息Promise返回值。 | +| 类型 | 说明 | +| ------------------------------------------------------ | ----------------------------------------------- | +| Promise> | 视频轨道信息MediaDescription数组Promise返回值。 | **示例：** @@ -1331,9 +1331,9 @@ setSpeed(speed:number): Promise\ **返回值：** -| 类型 | 说明 | -| ---------------- | ------------------------- | -| Promise\ | 通过Promise获取设置结果。 | +| 类型 | 说明 | +| ---------------- | ------------------------------------------------------------ | +| Promise\ | 播放速度Promise返回值，具体见[PlaybackSpeed](#playbackspeed8)。 | **示例：** @@ -1388,13 +1388,13 @@ selectBitrate(bitrate:number): Promise\ | 参数名 | 类型 | 必填 | 说明 | | ------- | ------ | ---- | -------------------------------------------- | -| bitrate | number | 是 | 指定码率播放，用于hls多码率场景，单位为bps。 | +| bitrate | number | 是 | 指定播放码率，用于hls多码率场景，单位为bps。 | **返回值：** -| 类型 | 说明 | -| ---------------- | ------------------------- | -| Promise\ | 通过Promise获取设置结果。 | +| 类型 | 说明 | +| ---------------- | --------------------------- | +| Promise\ | 指定播放码率Promise返回值。 | **示例：** @@ -1434,7 +1434,7 @@ videoPlayer.on('playbackCompleted', () => { on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void -开始监听视频缓存更新事件。 +开始监听视频缓存更新事件。仅网络播放支持该订阅事件。 **系统能力：** SystemCapability.Multimedia.Media.VideoPlayer diff --git a/zh-cn/application-dev/reference/apis/js-apis-system-device.md b/zh-cn/application-dev/reference/apis/js-apis-system-device.md index dec8bf99b4096f9680bdc3027d47dc035d7c4e1c..041de24dcec98a54249d43b79335721e7f97d315 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-system-device.md +++ b/zh-cn/application-dev/reference/apis/js-apis-system-device.md @@ -1,19 +1,18 @@ # 设备信息 +本模块提供当前设备的信息。 + > ![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 **参数：** diff --git a/zh-cn/application-dev/reference/apis/js-apis-uitest.md b/zh-cn/application-dev/reference/apis/js-apis-uitest.md index 0e824de04cfa4dd1de206838d519ace19d934ce2..1e6f73189bdcdcd1486b869cd1788513e5a9cddc 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-uitest.md +++ b/zh-cn/application-dev/reference/apis/js-apis-uitest.md @@ -4,10 +4,13 @@ UiTest提供模拟UI操作的能力，供开发者在测试场景使用，主要 该模块提供以下功能： -- [By](#by)：提供控件特征描述能力，用于控件筛选匹配查找。 -- [UiComponent](#uicomponent)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。 -- [UiDriver](#uidriver)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能能力。 -- [UiWINDOW9+](#uiwindow9)：入口类，提供窗口属性获取，窗口拖动、调整窗口大小等能能力。 +- [On9+](#on9)：提供控件特征描述能力，用于控件筛选匹配查找。 +- [Component9+](#component9)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。 +- [Driver9+](#driver9)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能能力。 +- [UiWindow9+](#uiwindow9)：入口类，提供窗口属性获取，窗口拖动、调整窗口大小等能能力。 +- [By](#by)：提供控件特征描述能力，用于控件筛选匹配查找。从API version9开始不再维护，建议使用[[On9+](#on9)](#driver9)。 +- [UiComponent](#uicomponent)：代表UI界面上的指定控件，提供控件属性获取，控件点击，滑动查找，文本注入等能力。从API version9开始不再维护，建议使用[Component9+](#component9)。 +- [UiDriver](#uidriver)：入口类，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等能能力。从API version9开始不再维护，建议使用[Driver9+](#driver9)。 >**说明：** > @@ -16,79 +19,52 @@ UiTest提供模拟UI操作的能力，供开发者在测试场景使用，主要 ## 导入模块 -``` -import {UiDriver, BY, MatchPattern, ResizeDirection, WindowMode, DisplayRotation, PointerMatrix} from '@ohos.uitest' -``` - -## By - -UiTest框架通过By类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。
-By提供的API能力具有以下几个特点:
1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。
2、控件属性支持多种匹配模式。
3、支持控件绝对定位，相对定位，可通过[By.isBefore](#isbefore)和[By.isAfter](#isafter)等API限定邻近控件特征进行辅助定位。
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对象。 | +## On9+ -**示例：** +UiTest框架在API9中，通过On类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。
+On提供的API能力具有以下几个特点:
1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。
2、控件属性支持多种匹配模式。
3、支持控件绝对定位，相对定位，可通过[ON.isBefore](#isbefore)和[ON.isAfter](#isafter)等API限定邻近控件特征进行辅助定位。
On类提供的所有API均为同步接口，建议使用者通过静态构造器ON来链式创建On对象。 ```js -let by = BY.text('123') //使用静态构造器BY创建by对象，指定目标控件的text属性。 +ON.text('123').type('button') ``` +### text9+ -### 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 +### id9+ -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 +### type9+ -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 +### clickable9+ -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对象，指定目标控件的可点击状态属性。 ``` ### longClickable9+ -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 +### scrollable9+ -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 +### enabled9+ -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 +### focused9+ -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 +### selected9+ -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对象，指定目标控件的被选中状态属性。 ``` ### checked9+ -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对象，指定目标控件的被勾选状态属性 ``` ### checkable9+ -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 +### isBefore9+ -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 +### isAfter9+ -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 +## Component9+ -UiTest中，UiComponent类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。 +UiTest框架在API9中，Component类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。 该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。 -### Point9+ - -坐标点信息。 - -**系统能力**：SystemCapability.Test.UiTest - -| 名称 | 参数类型 | 可读 | 可写 | 描述 | -| ---- | -------- | ---- | ---- | ---------------- | -| X | number | 是 | 否 | 坐标点的横坐标。 | -| Y | number | 是 | 否 | 坐标点的纵坐标。 | +### click9+ -### Rect9+ +click(): Promise\ -控件的边框信息。 +控件对象进行点击操作。 **系统能力**：SystemCapability.Test.UiTest -| 名称 | 参数类型 | 可读 | 可写 | 描述 | -| ------- | -------- | ---- | ---- | ------------------------- | -| leftX | number | 是 | 否 | 控件边框的左上角的X坐标。 | -| topY | number | 是 | 否 | 控件边框的左上角的Y坐标。 | -| rightX | number | 是 | 否 | 控件边框的右下角的X坐标。 | -| bottomY | number | 是 | 否 | 控件边框的右下角的Y坐标。 | - -### UiComponent.click - -click(): Promise\ +**错误码：** -控件对象进行点击操作。 +以下错误码的详细介绍请参见[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 +### doubleClick9+ doubleClick(): Promise\ @@ -454,17 +415,26 @@ doubleClick(): Promise\ **系统能力**：SystemCapability.Test.UiTest +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = 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 +### longClick9+ longClick(): Promise\ @@ -472,19 +442,28 @@ longClick(): Promise\ **系统能力**：SystemCapability.Test.UiTest +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = 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 +### getId9+ -getId(): Promise\ +getId(): Promise\ 获取控件对象的id值。 @@ -494,43 +473,28 @@ getId(): Promise\ | 类型 | 说明 | | ---------------- | ------------------------------- | -| Promise\ | 以Promise形式返回的控件的id值。 | - -**示例：** - -```js -async function demo() { - let driver = UiDriver.create() - let button = await driver.findComponent(BY.type('button')) - let num = await button.getId() -} -``` - -### getKey - -getKey(): Promise\ - -获取控件对象的key值。 +| Promise\ | 以Promise形式返回的控件的id值。 | -**系统能力**：SystemCapability.Test.UiTest +**错误码：** -**返回值：** +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 -| 类型 | 说明 | -| ---------------- | ------------------------------ | -| Promise\ | 以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 +### getText9+ getText(): Promise\ @@ -544,17 +508,26 @@ getText(): Promise\ | ---------------- | --------------------------------- | | Promise\ | 以Promise形式返回控件的文本信息。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = 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 +### getType9+ getType(): Promise\ @@ -568,12 +541,21 @@ getType(): Promise\ | ---------------- | ----------------------------- | | Promise\ | 以Promise形式返回控件的类型。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = 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\ | ------------------------ | ------------------------------------- | | 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\ | -------------------------- | --------------------------------------- | | 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 +### isClickable9+ isClickable(): Promise\ @@ -636,16 +636,25 @@ isClickable(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | ------------------------------------- | +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回控件对象可点击状态，true：可点击，false：不可点击。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = 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\ **返回值：** -| 类型 | 说明 | -| -------------- | ------------------------------------------- | +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回控件对象能否长按点击状态，true：可长按点击，false：不可长按点击。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = 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\ **返回值：** -| 类型 | 说明 | -| -------------- | ------------------------------------- | +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回控件对象被勾选状态，true：被勾选，false：未被勾选。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = 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\ **返回值：** -| 类型 | 说明 | -| -------------- | ------------------------------------------- | +| 错误码ID | 错误码信息 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回控件对象能否被勾选的属性，true：可被勾选，false：不可被勾选。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 类型 | 说明 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = 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 +### isScrollable9+ isScrollable(): Promise\ @@ -752,16 +788,25 @@ isScrollable(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | ------------------------------------- | +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回控件对象可滑动状态，true：可滑动，false：不可滑动。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = 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 +### isEnabled9+ isEnabled(): Promise\ @@ -782,16 +827,25 @@ isEnabled(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | ------------------------------- | +| 类型 | 说明 | +| ----------------- | ---------------------------------------------------------- | | Promise\ | 以Promise形式返回控件使能状态，true：使能，false：未使能。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = 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 +### isFocused9+ isFocused(): Promise\ @@ -812,16 +866,25 @@ isFocused(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | ----------------------------------- | +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回控件对象是否获焦，true：获焦，false：未获焦。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = 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 +### isSelected9+ isSelected(): Promise\ @@ -841,16 +904,25 @@ isSelected(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | -------------------- | +| 类型 | 说明 | +| ----------------- | ----------------------------------------------------- | | Promise\ | 控件对象被选中的状态，true：被选中，false：未被选中。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = 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 +### inputText9+ inputText(text: string): Promise\ @@ -874,12 +946,21 @@ inputText(text: string): Promise\ | ------ | ------ | ---- | ---------------- | | 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\ **系统能力**：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 +### scrollSearch9+ -scrollSearch(by: By): Promise\ +scrollSearch(on: ON): Promise\ 在控件上滑动查找目标控件(适用于List等支持滑动的控件)。 @@ -912,23 +1000,32 @@ scrollSearch(by: By): Promise\ **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | --------- | ---- | -------------------- | -| 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\ | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------------------------------------------------------------ | -| 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\ | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------------------------------------------------------------ | -| 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() } ``` ### dragTo9+ -dragTo(target: UiComponent): Promise\ +dragTo(target: Component): Promise\ 将控件拖拽至目标控件处。 @@ -990,17 +1105,26 @@ dragTo(target: UiComponent): Promise\ **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | --------------------------- | ---- | ---------- | -| 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\ | ------ | ------ | ---- | ---------------- | | 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\ | ------ | ------ | ---- | ---------------- | | 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 +## Driver9+ -UiDriver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等API。 -该类提供的方法除UiDriver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await调用。 +UiTest框架在API9中，Driver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等API。 +该类提供的方法除Driver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await调用。 -### create +### create9+ -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 +### delayMs9+ delayMs(duration: number): Promise\ -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 +### findComponent9+ -findComponent(by: By): Promise\ +findComponent(on: On): Promise\ -在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 +### findComponents9+ -findComponents(by: By): Promise\> +findComponents(on: On): Promise\> -在UiDriver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。 +在Driver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。 **系统能力**：SystemCapability.Test.UiTest **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | --------- | ---- | -------------------- | -| by | [By](#by) | 是 | 目标控件的属性要求。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------- | ---- | -------------------- | +| on | [On](#on9) | 是 | 目标控件的属性要求。 | **返回值：** -| 类型 | 说明 | -| --------------------------------------------- | --------------------------------------- | -| Promise\> | 以Promise形式返回找到的控件对象的列表。 | +| 类型 | 说明 | +| ------------------------------------------ | --------------------------------------- | +| Promise\> | 以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\ | -------------------------------- | ------------------------------------- | | 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}) } ``` ### waitForComponent9+ -waitForComponent(by: By, time: number): Promise\ +waitForComponent(on: On, time: number): Promise\ -在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 +### assertComponentExist9+ -assertComponentExist(by: By): Promise\ +assertComponentExist(on: On): Promise\ -断言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 +### pressBack9+ pressBack(): Promise\ -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 +### triggerKey9+ triggerKey(keyCode: number): Promise\ -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\ -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 +### click9+ click(x: number, y: number): Promise\ -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 +### doubleClick9+ doubleClick(x: number, y: number): Promise\ -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 +### longClick9+ longClick(x: number, y: number): Promise\ -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\ -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\ -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 +### screenCap9+ screenCap(savePath: string): Promise\ -UiDriver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。 +Driver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。 **系统能力**：SystemCapability.Test.UiTest @@ -1451,15 +1714,23 @@ UiDriver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的 **返回值：** -| 类型 | 说明 | -| -------------- | -------------------------------------- | +| 类型 | 说明 | +| ----------------- | -------------------------------------- | | Promise\ | 截图操作是否成功完成。成功完成为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\ | -------- | ------------------------------------ | ---- | ---------------- | | 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\ | ---------------------------------------------- | --------------------------------------- | | 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\ **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ---- | ---- | -------------------- | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------- | ---- | ------------------------------------------------------- | | 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\ | -------------------------- | --------------------------------------- | | 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\ | -------------------------- | ------------------------------------------- | | 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\ **系统能力**：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\ **系统能力**：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\ **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------------------------------- | +| 类型 | 说明 | +| ----------------- | --------------------------------------------------- | | Promise\ | 以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\ | 参数名 | 类型 | 必填 | 说明 | | ------- | ---------------- | ---- | ------------------------------------------------------------ | | 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\ | 以Promise的形式返回植入操作是否成功完成。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | + **示例：** ```js @@ -1705,23 +2056,73 @@ async function demo() { } ``` -## UiWindow9+ +## PointerMatrix9+ -UiTest中，UiWindow类代表了UI界面上的一个窗口，提供窗口属性获取，窗口拖动、调整窗口大小等API。 -该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。 +表示存储多指操作中每根手指每一步动作的坐标点及其行为的二维数组。 + +### create9+ -### WindowFilter9+ +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) +} +``` + +### setPoint9+ + +setPoint(finger: number, step: number, point: Point): void + +设置PointerMatrix对象中指定手指和步骤对应动作的坐标点。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------------- | ---- | ---------------- | +| finger | number | 是 | 手指的序号。 | +| step | number | 是 | 步骤的序号。 | +| point | [Point](#point9) | 是 | 该行为的坐标点。 | + +**示例：** + +```js +async function demo() { + let pointers = PointerMatrix.create(2,3) + pointers.setPoint(0,0,{X:230,Y:480}) + pointers.setPoint(0,1,{X:250,Y:380}) + pointers.setPoint(0,2,{X:270,Y:280}) + pointers.setPoint(1,0,{X:230,Y:680}) + pointers.setPoint(1,1,{X:240,Y:580}) + pointers.setPoint(1,2,{X:250,Y:480}) +} +``` + +## UiWindow9+ + +UiTest中，UiWindow类代表了UI界面上的一个窗口，提供窗口属性获取，窗口拖动、调整窗口大小等API。 +该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。 ### getBundleName9+ @@ -1737,11 +2138,20 @@ getBundleName(): Promise\ | ---------------- | --------------------------------- | | Promise\ | 以Promise形式返回窗口的包名信息。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) let name = await window.getBundleName() } @@ -1761,11 +2171,20 @@ getBounds(): Promise\ | ------------------------ | --------------------------------- | | 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\ | ---------------- | --------------------------------- | | Promise\ | 以Promise形式返回窗口的标题信息。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) let rect = await window.getTitle() } @@ -1805,15 +2233,24 @@ getWindowMode(): Promise\ **返回值：** -| 类型 | 说明 | -| ------------------------------------------------ | ------------------------------------- | +| 类型 | 说明 | +| ------------------------------------ | ------------------------------------- | | 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\ **返回值：** -| 类型 | 说明 | -| -------------- | ----------------------------------- | +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回窗口对象是否获焦，true：获焦，false：未获焦。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) let focused = await window.isFocused() } @@ -1853,15 +2299,24 @@ isActived(): Promise\ **返回值：** -| 类型 | 说明 | -| -------------- | --------------------------------------------- | +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回窗口对象是否为用户交互窗口，true：交互窗口，false：非交互窗口。 | +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | + **示例：** ```js async function demo() { - let driver = 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() { ### focus9+ -focus(): Promise\ +focus(): Promise\ 让窗口获焦。 **系统能力**：SystemCapability.Test.UiTest -**返回值：** +**错误码：** -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise\ | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 | +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | **示例：** ```js async function demo() { - let driver = UiDriver.create() + let driver = Driver.create() let window = await driver.findWindow({actived: true}) await window.focus() } @@ -1893,7 +2351,7 @@ async function demo() { ### moveTo9+ -moveTo(x: number, y: number): Promise\ +moveTo(x: number, y: number): Promise\ 将窗口移动到目标点。适用于支持移动的窗口。 @@ -1906,17 +2364,21 @@ moveTo(x: number, y: number): Promise\ | x | number | 是 | 以number的形式传入目标点的横坐标信息。 | | y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | -**返回值：** +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise\ | 以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() { ### resize9+ -resize(wide: number, height: number, direction: ResizeDirection): Promise\ +resize(wide: number, height: number, direction: ResizeDirection): Promise\ 根据传入的宽、高和调整方向来调整窗口的大小。适用于支持大小调整的窗口。 @@ -1932,23 +2394,27 @@ resize(wide: number, height: number, direction: ResizeDirection): Promise\ | 以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() { ### split9+ -split(): Promise\ +split(): Promise\ 将窗口模式切换成分屏模式。适用于支持切屏操作的窗口。 **系统能力**：SystemCapability.Test.UiTest -**返回值：** +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise\ | 以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() { ### maximize9+ -maximize(): Promise\ +maximize(): Promise\ 将窗口最大化。适用于支持窗口最大化操作的窗口。 **系统能力**：SystemCapability.Test.UiTest -**返回值：** +**错误码：** -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise\ | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 | +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | +| 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() { ### minimize9+ -minimize(): Promise\ +minimize(): Promise\ 将窗口最小化。适用于支持窗口最小化操作的窗口。 **系统能力**：SystemCapability.Test.UiTest -**返回值：** +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise\ | 以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() { ### resume9+ -resume(): Promise\ +resume(): Promise\ 将窗口恢复到之前的窗口模式。 **系统能力**：SystemCapability.Test.UiTest -**返回值：** +**错误码：** -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise\ | 以Promise形式返回操作是否成功完成，true：操作已完成，false：操作未完成。 | +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 + +| 错误码ID | 错误码信息 | +| -------- | ---------------------------------------- | +| 17000002 | API does not allow calling concurrently. | +| 17000004 | Component lost/UiWindow lost. | +| 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() { ### close9+ -close(): Promise\ +close(): Promise\ 将窗口关闭。 **系统能力**：SystemCapability.Test.UiTest -**返回值：** +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](../errorcodes/errorcode-uitest.md)。 -| 类型 | 说明 | -| -------------- | ----------------------------------- | -| Promise\ | 以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() } ``` -## PointerMatrix9+ - -表示存储多指操作中每根手指每一步动作的坐标点及其行为的二维数组。 - -### create9+ - -static create(fingers: number, steps: number): PointerMatrix - -静态方法，构造一个PointerMatrix对象，并返回该对象。 - -**系统能力**：SystemCapability.Test.UiTest - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------------------------------ | -| fingers | number | 是 | 多指操作中注入的手指数，取值范围：[1,10]。 | -| steps | number | 是 | 每根手指操作的步骤数，取值范围：[1,1000]。 | - -**返回值：** - -| 类型 | 说明 | -| -------------------------------- | ----------------------------- | -| [PointerMatrix](#pointermatrix9) | 返回构造的PointerMatrix对象。 | - -**示例：** - -```js -async function demo() { - let pointerMatrix = PointerMatrix.create(2,3) -} -``` - -### setPoint9+ - -setPoint(finger: number, step: number, point: Point): void - -设置PointerMatrix对象中指定手指和步骤对应动作的坐标点。 - -**系统能力**：SystemCapability.Test.UiTest - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---------------- | ---- | ---------------- | -| finger | number | 是 | 手指的序号。 | -| step | number | 是 | 步骤的序号。 | -| point | [Point](#point9) | 是 | 该行为的坐标点。 | - -**示例：** - -```js -async function demo() { - let pointers = PointerMatrix.create(2,3) - pointers.setPoint(0,0,{X:230,Y:480}) - pointers.setPoint(0,1,{X:250,Y:380}) - pointers.setPoint(0,2,{X:270,Y:280}) - pointers.setPoint(1,0,{X:230,Y:680}) - pointers.setPoint(1,1,{X:240,Y:580}) - pointers.setPoint(1,2,{X:250,Y:480}) -} -``` - -### - ## MatchPattern 控件属性支持的匹配模式。 @@ -2169,6 +2590,30 @@ async function demo() { | RIGHT_UP | 右上方。 | | RIGHT_DOWN | 右下方。 | +## Point9+ + +坐标点信息。 + +**系统能力**：SystemCapability.Test.UiTest + +| 名称 | 参数类型 | 可读 | 可写 | 描述 | +| ---- | -------- | ---- | ---- | ---------------- | +| X | number | 是 | 否 | 坐标点的横坐标。 | +| Y | number | 是 | 否 | 坐标点的纵坐标。 | + +## Rect9+ + +控件的边框信息。 + +**系统能力**：SystemCapability.Test.UiTest + +| 名称 | 参数类型 | 可读 | 可写 | 描述 | +| ------- | -------- | ---- | ---- | ------------------------- | +| leftX | number | 是 | 否 | 控件边框的左上角的X坐标。 | +| topY | number | 是 | 否 | 控件边框的左上角的Y坐标。 | +| rightX | number | 是 | 否 | 控件边框的右下角的X坐标。 | +| bottomY | number | 是 | 否 | 控件边框的右下角的Y坐标。 | + ## WindowMode9+ **系统能力**：SystemCapability.Test.UiTest @@ -2194,3 +2639,1052 @@ async function demo() { | ROTATION_90 | 设备显示器顺时针旋转90°，水平显示。 | | ROTATION_180 | 设备显示器顺时针旋转180°，逆向垂直显示。 | | ROTATION_270 | 设备显示器顺时针旋转270°，逆向水平显示。 | + +## WindowFilter9+ + +窗口的标志属性信息。 + +**系统能力**：SystemCapability.Test.UiTest + +| 名称 | 参数类型 | 必填 | 可读 | 可写 | 描述 | +| ---------- | -------- | ---- | ---- | ---- | -------------------------- | +| bundleName | string | 否 | 是 | 否 | 窗口对应的包名。 | +| title | string | 否 | 是 | 否 | 窗口的标题。 | +| focused | boolean | 否 | 是 | 否 | 窗口是否获焦。 | +| actived | boolean | 否 | 是 | 否 | 窗口是否正与用户进行交互。 | + +## By(deprecated) + +UiTest框架通过By类提供了丰富的控件特征描述API，用于进行控件筛选来匹配/查找出目标控件。
+By提供的API能力具有以下几个特点:
1、支持单属性匹配和多属性组合匹配，例如同时指定目标控件text和id。
2、控件属性支持多种匹配模式。
3、支持控件绝对定位，相对定位，可通过[By.isBefore](#isbefore)和[By.isAfter](#isafter)等API限定邻近控件特征进行辅助定位。
By类提供的所有API均为同步接口，建议使用者通过静态构造器BY来链式创建By对象。 + +从API version9开始不再维护，建议使用[On9+](#on9)。 + +```js +BY.text('123').type('button') +``` + +### text(deprecated) + +text(txt: string, pattern?: MatchPattern): By + +指定目标控件文本属性，支持多种匹配模式，返回By对象自身。 + +从API version9开始不再维护，建议使用[text9+](#text9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------------------------- | ---- | --------------------------------------------------- | +| txt | string | 是 | 指定控件文本，用于匹配目标控件文本。 | +| pattern | [MatchPattern](#matchpattern) | 否 | 指定的文本匹配模式，默认为[EQUALS](#matchpattern)。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ---------------------------------- | +| [By](#by) | 返回指定目标控件文本属性的By对象。 | + +**示例：** + +```js +let by = BY.text('123') //使用静态构造器BY创建by对象，指定目标控件的text属性。 +``` + + +### key(deprecated) + +key(key: string): By + +指定目标控件key值属性，返回By对象自身。 + +从API version9开始不再维护，建议使用[id9+](#id9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ----------------- | +| key | string | 是 | 指定控件的Key值。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ----------------------------------- | +| [By](#by) | 返回指定目标控件key值属性的By对象。 | + +**示例：** + +```js +let by = BY.key('123') //使用静态构造器BY创建by对象，指定目标控件的key值属性。 +``` + + +### id(deprecated) + +id(id: number): By + +指定目标控件id属性，返回By对象自身。 + +从API version9开始不再维护，被废弃。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------- | +| id | number | 是 | 指定控件的id值。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | -------------------------------- | +| [By](#by) | 返回指定目标控件id属性的By对象。 | + +**示例：** + +```js +let by = BY.id(123) //使用静态构造器BY创建by对象，指定目标控件的id属性。 +``` + + +### type(deprecated) + +type(tp: string): By + +指定目标控件的控件类型属性，返回By对象自身。 + +从API version9开始不再维护，建议使用[type9+](#type9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------- | +| tp | string | 是 | 指定控件类型。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ---------------------------------------- | +| [By](#by) | 返回指定目标控件的控件类型属性的By对象。 | + +**示例：** + +```js +let by = BY.type('button') //使用静态构造器BY创建by对象，指定目标控件的控件类型属性。 +``` + + +### clickable(deprecated) + +clickable(b?: boolean): By + +指定目标控件的可点击状态属性，返回By对象自身。 + +从API version9开始不再维护，建议使用[clickable9+](#clickable9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | ------------------------------------------------------------ | +| b | boolean | 否 | 指定控件可点击状态，true：可点击，false：不可点击。默认为true。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ------------------------------------------ | +| [By](#by) | 返回指定目标控件的可点击状态属性的By对象。 | + +**示例：** + +```js +let by = BY.clickable(true) //使用静态构造器BY创建by对象，指定目标控件的可点击状态属性。 +``` + + +### scrollable(deprecated) + +scrollable(b?: boolean): By + +指定目标控件的可滑动状态属性，返回By对象自身。 + +从API version9开始不再维护，建议使用[scrollable9+](#scrollable9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | ----------------------------------------------------------- | +| b | boolean | 否 | 控件可滑动状态，true：可滑动，false：不可滑动。默认为true。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ------------------------------------------ | +| [By](#by) | 返回指定目标控件的可滑动状态属性的By对象。 | + +**示例：** + +```js +let by = BY.scrollable(true) //使用静态构造器BY创建by对象，指定目标控件的可滑动状态属性。 +``` + +### enabled(deprecated) + +enabled(b?: boolean): By + +指定目标控件的使能状态属性，返回By对象自身。 + +从API version9开始不再维护，建议使用[enabled9+](#enabled9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | --------------------------------------------------------- | +| b | boolean | 否 | 指定控件使能状态，true：使能，false：未使能。默认为true。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ---------------------------------------- | +| [By](#by) | 返回指定目标控件的使能状态属性的By对象。 | + +**示例：** + +```js +let by = BY.enabled(true) //使用静态构造器BY创建by对象，指定目标控件的使能状态属性。 +``` + +### focused(deprecated) + +focused(b?: boolean): By + +指定目标控件的获焦状态属性，返回By对象自身。 + +从API version9开始不再维护，建议使用[focused9+](#focused9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | ----------------------------------------------------- | +| b | boolean | 否 | 控件获焦状态，true：获焦，false：未获焦。默认为true。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ---------------------------------------- | +| [By](#by) | 返回指定目标控件的获焦状态属性的By对象。 | + +**示例：** + +```js +let by = BY.focused(true) //使用静态构造器BY创建by对象，指定目标控件的获焦状态属性。 +``` + +### selected(deprecated) + +selected(b?: boolean): By + +指定目标控件的被选中状态属性，返回By对象自身。 + +从API version9开始不再维护，建议使用[selected9+](#selected9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------- | ---- | ------------------------------------------------------------ | +| b | boolean | 否 | 指定控件被选中状态，true：被选中，false：未被选中。默认为true。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ------------------------------------------ | +| [By](#by) | 返回指定目标控件的被选中状态属性的By对象。 | + +**示例：** + +```js +let by = BY.selected(true) //使用静态构造器BY创建by对象，指定目标控件的被选中状态属性。 +``` + +### isBefore(deprecated) + +isBefore(by: By): By + +指定目标控件位于给出的特征属性控件之前，返回By对象自身。 + +从API version9开始不再维护，建议使用[isBefore9+](#isbefore9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | ---------------- | +| by | [By](#by) | 是 | 特征控件的属性。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ---------------------------------------------------- | +| [By](#by) | 返回指定目标控件位于给出的特征属性控件之前的By对象。 | + +**示例：** + +```js +let by = BY.isBefore(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之前。 +``` + +### isAfter(deprecated) + +isAfter(by: By): By + +指定目标控件位于给出的特征属性控件之后，返回By对象自身。 + +从API version9开始不再维护，建议使用[isAfter9+](#isafter9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | ---------------- | +| by | [By](#by) | 是 | 特征控件的属性。 | + +**返回值：** + +| 类型 | 说明 | +| --------- | ---------------------------------------------------- | +| [By](#by) | 返回指定目标控件位于给出的特征属性控件之后的By对象。 | + +**示例：** + +```js +let by = BY.isAfter(BY.text('123')) //使用静态构造器BY创建by对象，指定目标控件位于给出的特征属性控件之后。 +``` + +## UiComponent(deprecated) + +UiTest中，UiComponent类代表了UI界面上的一个控件，提供控件属性获取，控件点击，滑动查找，文本注入等API。 +该类提供的所有方法都使用Promise方式作为异步方法，需使用await调用。 + +从API version9开始不再维护，建议使用[Component9+](#component9)。 + +### click(deprecated) + +click(): Promise\ + +控件对象进行点击操作。 + +从API version9开始不再维护，建议使用[click9+](#click9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + await button.click() +} +``` + +### doubleClick(deprecated) + +doubleClick(): Promise\ + +控件对象进行双击操作。 + +从API version9开始不再维护，建议使用[doubleClick9+](#doubleclick9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + await button.doubleClick() +} +``` + +### longClick(deprecated) + +longClick(): Promise\ + +控件对象进行长按操作。 + +从API version9开始不再维护，建议使用[longClick9+](#longclick9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + await button.longClick() +} +``` + +### getId(deprecated) + +getId(): Promise\ + +获取控件对象的id值。 + +从API version9开始不再维护，建议使用[getId9+](#getid9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ---------------- | ------------------------------- | +| Promise\ | 以Promise形式返回的控件的id值。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + let num = await button.getId() +} +``` + +### getKey(deprecated) + +getKey(): Promise\ + +获取控件对象的key值。 + +从API version9开始不再维护，被废弃。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ---------------- | ------------------------------ | +| Promise\ | 以Promise形式返回控件的key值。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + let str_key = await button.getKey() +} +``` + +### getText(deprecated) + +getText(): Promise\ + +获取控件对象的文本信息。 + +从API version9开始不再维护，建议使用[getText9+](#gettext9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ---------------- | --------------------------------- | +| Promise\ | 以Promise形式返回控件的文本信息。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + let text = await button.getText() +} +``` + +### getType(deprecated) + +getType(): Promise\ + +获取控件对象的控件类型。 + +从API version9开始不再维护，建议使用[getType9+](#gettype9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ---------------- | ----------------------------- | +| Promise\ | 以Promise形式返回控件的类型。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + let type = await button.getType() +} +``` + +### isClickable(deprecated) + +isClickable(): Promise\ + +获取控件对象可点击状态。 + +从API version9开始不再维护，建议使用[isClickable9+](#isclickable9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | +| Promise\ | 以Promise形式返回控件对象可点击状态，true：可点击，false：不可点击。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + if(await button.isClickable()) { + console.info('This button can be Clicked') + } + else{ + console.info('This button can not be Clicked') + } +} +``` + +### isScrollable(deprecated) + +isScrollable(): Promise\ + +获取控件对象可滑动状态。 + +从API version9开始不再维护，建议使用[isScrollable9+](#isscrollable9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | +| Promise\ | 以Promise形式返回控件对象可滑动状态，true：可滑动，false：不可滑动。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let scrollBar = await driver.findComponent(BY.scrollable(true)) + if(await scrollBar.isScrollable()) { + console.info('This scrollBar can be operated') + } + else{ + console.info('This scrollBar can not be operated') + } +} +``` + + +### isEnabled(deprecated) + +isEnabled(): Promise\ + +获取控件使能状态。 + +从API version9开始不再维护，建议使用[isEnabled9+](#isenabled9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ---------------------------------------------------------- | +| Promise\ | 以Promise形式返回控件使能状态，true：使能，false：未使能。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + if(await button.isEnabled()) { + console.info('This button can be operated') + } + else{ + console.info('This button can not be operated') + } +} + +``` + +### isFocused(deprecated) + +isFocused(): Promise\ + +判断控件对象是否获焦。 + +从API version9开始不再维护，建议使用[isFocused9+](#isfocused9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ------------------------------------------------------------ | +| Promise\ | 以Promise形式返回控件对象是否获焦，true：获焦，false：未获焦。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + if(await button.isFocused()) { + console.info('This button is focused') + } + else{ + console.info('This button is not focused') + } +} +``` + +### isSelected(deprecated) + +isSelected(): Promise\ + +获取控件对象被选中状态。 + +从API version9开始不再维护，建议使用[isSelected9+](#isselected9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ----------------------------------------------------- | +| Promise\ | 控件对象被选中的状态，true：被选中，false：未被选中。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.type('button')) + if(await button.isSelected()) { + console.info('This button is selected') + } + else{ + console.info('This button is not selected') + } +} +``` + +### inputText(deprecated) + +inputText(text: string): Promise\ + +向控件中输入文本(适用于文本框控件)。 + +从API version9开始不再维护，建议使用[inputText9+](#inputtext9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------- | +| text | string | 是 | 输入的文本信息。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let text = await driver.findComponent(BY.text('hello world')) + await text.inputText('123') +} +``` + +### scrollSearch(deprecated) + +scrollSearch(by: By): Promise\ + +在控件上滑动查找目标控件(适用于List等支持滑动的控件)。 + +从API version9开始不再维护，建议使用[scrollSearch9+](#scrollsearch9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | -------------------- | +| by | [By](#by) | 是 | 目标控件的属性要求。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------- | ------------------------------------- | +| Promise\<[UiComponent](#uicomponent)> | 以Promise形式返回找到的目标控件对象。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let scrollBar = await driver.findComponent(BY.type('Scroll')) + let button = await scrollBar.scrollSearch(BY.text('next page')) +} +``` + +## UiDriver(deprecated) + +UiDriver类为uitest测试框架的总入口，提供控件匹配/查找，按键注入，坐标点击/滑动，截图等API。 +该类提供的方法除UiDriver.create()以外的所有方法都使用Promise方式作为异步方法，需使用await调用。 + +从API version9开始不再维护，建议使用[Driver9+](#driver9)。 + +### create(deprecated) + +static create(): UiDriver + +静态方法，构造一个UiDriver对象，并返回该对象。 + +从API version9开始不再维护，建议使用[create9+](#create9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**返回值：** + +| 类型 | 说明 | +| -------- | ------------------------ | +| UiDriver | 返回构造的UiDriver对象。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() +} +``` + +### delayMs(deprecated) + +delayMs(duration: number): Promise\ + +UiDriver对象在给定的时间内延时。 + +从API version9开始不再维护，建议使用[delayMs9+](#delayms9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------ | +| duration | number | 是 | 给定的时间。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.delayMs(1000) +} +``` + +### findComponent(deprecated) + +findComponent(by: By): Promise\ + +在UiDriver对象中，根据给出的目标控件属性要求查找目标控件。 + +从API version9开始不再维护，建议使用[findComponent9+](#findcomponent9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | -------------------- | +| by | [By](#by) | 是 | 目标控件的属性要求。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------- | --------------------------------- | +| Promise\<[UiComponent](#uicomponent)> | 以Promise形式返回找到的控件对象。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let button = await driver.findComponent(BY.text('next page')) +} +``` + +### findComponents(deprecated) + +findComponents(by: By): Promise\> + +在UiDriver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。 + +从API version9开始不再维护，建议使用[findComponents9+](#findcomponents9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | -------------------- | +| by | [By](#by) | 是 | 目标控件的属性要求。 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------------------- | --------------------------------------- | +| Promise\> | 以Promise形式返回找到的控件对象的列表。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + let buttonList = await driver.findComponents(BY.text('next page')) +} +``` + +### assertComponentExist(deprecated) + +assertComponentExist(by: By): Promise\ + +断言API，用于断言当前界面存在满足给出的目标控件属性的控件; 如果控件不存在，该API将抛出JS异常，使当前测试用例失败。 + +从API version9开始不再维护，建议使用[assertComponentExist9+](#assertcomponentexist9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | -------------------- | +| by | [By](#by) | 是 | 目标控件的属性要求。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.assertComponentExist(BY.text('next page')) +} +``` + +### pressBack(deprecated) + +pressBack(): Promise\ + +UiDriver对象进行点击BACK键的操作。 + +从API version9开始不再维护，建议使用[pressBack9+](#pressback9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.pressBack() +} +``` + +### triggerKey(deprecated) + +triggerKey(keyCode: number): Promise\ + +UiDriver对象采取如下操作：通过key值找到对应键并点击。 + +从API version9开始不再维护，建议使用[triggerKey9+](#triggerkey9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------- | +| keyCode | number | 是 | 指定的key值。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.triggerKey(123) +} +``` + + +### click(deprecated) + +click(x: number, y: number): Promise\ + +UiDriver对象采取如下操作：在目标坐标点单击。 + +从API version9开始不再维护，建议使用[click9+](#click9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------------- | +| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | +| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.click(100,100) +} +``` + +### doubleClick(deprecated) + +doubleClick(x: number, y: number): Promise\ + +UiDriver对象采取如下操作：在目标坐标点双击。 + +从API version9开始不再维护，建议使用[doubleClick9+](#doubleclick9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------------- | +| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | +| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.doubleClick(100,100) +} +``` + +### longClick(deprecated) + +longClick(x: number, y: number): Promise\ + +UiDriver对象采取如下操作：在目标坐标点长按下鼠标左键。 + +从API version9开始不再维护，建议使用[longClick9+](#longclick9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------------- | +| x | number | 是 | 以number的形式传入目标点的横坐标信息。 | +| y | number | 是 | 以number的形式传入目标点的纵坐标信息。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.longClick(100,100) +} +``` + +### swipe(deprecated) + +swipe(startx: number, starty: number, endx: number, endy: number): Promise\ + +UiDriver对象采取如下操作：从给出的起始坐标点滑向给出的目的坐标点。 + +从API version9开始不再维护，建议使用[swipe9+](#swipe9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------------- | +| startx | number | 是 | 以number的形式传入起始点的横坐标信息。 | +| starty | number | 是 | 以number的形式传入起始点的纵坐标信息。 | +| endx | number | 是 | 以number的形式传入目的点的横坐标信息。 | +| endy | number | 是 | 以number的形式传入目的点的纵坐标信息。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.swipe(100,100,200,200) +} +``` + +### screenCap(deprecated) + +screenCap(savePath: string): Promise\ + +UiDriver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的图片至给出的保存路径中。 + +从API version9开始不再维护，建议使用[screenCap9+](#screencap9)。 + +**系统能力**：SystemCapability.Test.UiTest + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | -------------- | +| savePath | string | 是 | 文件保存路径。 | + +**返回值：** + +| 类型 | 说明 | +| ----------------- | -------------------------------------- | +| Promise\ | 截图操作是否成功完成。成功完成为true。 | + +**示例：** + +```js +async function demo() { + let driver = UiDriver.create() + await driver.screenCap('/local/tmp/') +} +``` diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-huks.md b/zh-cn/application-dev/reference/errorcodes/errorcode-huks.md new file mode 100644 index 0000000000000000000000000000000000000000..0baec0448e812c078b0f89b2f7d983960460ffdd --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errorcode-huks.md @@ -0,0 +1,223 @@ +# 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. + +**可能原因** + +其他系统服务未启动。 + +**处理步骤** + +开发者等待一段时间后尝试再次触发调用。 diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-uitest.md b/zh-cn/application-dev/reference/errorcodes/errorcode-uitest.md new file mode 100644 index 0000000000000000000000000000000000000000..dda3aabebadab92b9937e8f86039344e87329343 --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errorcode-uitest.md @@ -0,0 +1,87 @@ +# 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对象不支持该操作。 + +**可能原因** + +当前界面控件/窗口属性不支持该操作。 + +**处理步骤** + +检查当前界面控件/窗口属性是否该操作。 diff --git a/zh-cn/application-dev/reference/errorcodes/errorcodes-zlib.md b/zh-cn/application-dev/reference/errorcodes/errorcodes-zlib.md index a2518a702c545f9d81821cef3680cb51b534c030..559f2ba4a7e76e966212fc53bb96e88270e1c09a 100755 --- a/zh-cn/application-dev/reference/errorcodes/errorcodes-zlib.md +++ b/zh-cn/application-dev/reference/errorcodes/errorcodes-zlib.md @@ -1,24 +1,5 @@ # zlib子系统错误码 -## 401 参数检查错误 - -**错误信息** - -The parameter invalid. - -**错误描述** - -当调用zlib的compress及decompress接口时，若传入参数的类型或者范围不匹配，会报此错误码。 - -**可能原因** - -1. 入参类型错误不匹配，如传入的文件路径类型不是strinf。 -2. 入参范围不匹配，如传入的options中包含的枚举不存在。 - -**处理步骤** - -检查入参类型和范围是否匹配。 - ## 900001 传入的源文件错误 **错误信息** diff --git a/zh-cn/application-dev/task-management/Readme-CN.md b/zh-cn/application-dev/task-management/Readme-CN.md index 216d2ed2bdf4c7188a26b1449cc0d209861ec8db..994e21697c55f18fd58df906939975cca4f694d8 100644 --- a/zh-cn/application-dev/task-management/Readme-CN.md +++ b/zh-cn/application-dev/task-management/Readme-CN.md @@ -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 diff --git a/zh-cn/application-dev/notification/background-agent-scheduled-reminder-guide.md b/zh-cn/application-dev/task-management/background-agent-scheduled-reminder-guide.md similarity index 100% rename from zh-cn/application-dev/notification/background-agent-scheduled-reminder-guide.md rename to zh-cn/application-dev/task-management/background-agent-scheduled-reminder-guide.md diff --git a/zh-cn/application-dev/notification/background-agent-scheduled-reminder-overview.md b/zh-cn/application-dev/task-management/background-agent-scheduled-reminder-overview.md similarity index 100% rename from zh-cn/application-dev/notification/background-agent-scheduled-reminder-overview.md rename to zh-cn/application-dev/task-management/background-agent-scheduled-reminder-overview.md diff --git a/zh-cn/application-dev/ui/arkui-overview.md b/zh-cn/application-dev/ui/arkui-overview.md index 3d809b82f2c6fbc107a710376dc63b3fd2800b60..fa6a13c44764b405d9233895a71216803086f671 100644 --- a/zh-cn/application-dev/ui/arkui-overview.md +++ b/zh-cn/application-dev/ui/arkui-overview.md @@ -1,42 +1,60 @@ # 方舟开发框架概述 -## 框架介绍 - -方舟开发框架（简称：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
业务入口：使用固定文件名app.ets（Page类型Ability）/service.ts（Service类型Ability）/data.ts（Data类型Ability）
业务逻辑语言：js/ts | + | | 声明式开发范式 | UI开发语言：ArkTS
业务入口：使用固定文件名app.ets（Page类型Ability）/service.ts（Service类型Ability）/data.ts（Data类型Ability）
业务逻辑语言：js/ts | + | 服务卡片 | 类web开发范式 | UI开发语言：卡片显示使用hml+css+json(action)
业务入口：form.ts
卡片业务逻辑语言：js/ts | + | | 声明式开发范式 | 当前不支持 | + + **Stage模型：** + + | 类型 | UI开发范式 | 说明 | + | -------- | --------------------------- | --------------------------- | + | 应用 | 类web开发范式 | 当前不支持 | + | | 声明式开发范式 | UI开发语言：ArkTS
业务入口：应用模型基于ohos.application.Ability/ExtensionAbility等派生
业务逻辑语言：ts | + | 服务卡片 | 类web开发范式 | UI开发语言：卡片显示使用hml+css+json(action)
业务入口：从FormExtensionAbility派生
业务逻辑语言：ts | + | | 声明式开发范式 | 当前不支持 | -![zh-cn_image_0000001183709904](figures/zh-cn_image_0000001183709904.png) -从上图可以看出，类Web开发范式与声明式开发范式的UI后端引擎和语言运行时是共用的，其中，UI后端引擎实现了方舟开发框架的六种基本能力。声明式开发范式无需JS Framework进行页面DOM管理，渲染更新链路更为精简，占用内存更少，因此更推荐开发者选用声明式开发范式来搭建应用UI界面。 \ No newline at end of file diff --git a/zh-cn/device-dev/device-test/developer_test.md b/zh-cn/device-dev/device-test/developer_test.md new file mode 100644 index 0000000000000000000000000000000000000000..05f860d7e9dc7420a75d0f9daa8fb378979fe9ee --- /dev/null +++ b/zh-cn/device-dev/device-test/developer_test.md @@ -0,0 +1,851 @@ +# 开发自测试执行框架使用指南 + + +## 概述 + +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 + +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 + +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文件，文件内容格式如下: + +``` + + + + + + + +``` + +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配置 +``` + + + + false + + false + + true + + + + + + + + + + + + + + + + + cmd + 115200 + 8 + 1 + 1 + + + + + + + + + + + + + + + + + + +``` +>**说明：** 在执行测试用例之前，若使用HDC连接设备，用例仅需配置设备IP和端口号即可，其余信息均默认不修改。 + +### 执行命令说明 + +1. 启动测试框架 + ``` + start.bat + ``` +2. 选择产品形态 + + 进入测试框架，系统会自动提示您选择产品形态，请根据实际的开发板进行选择。 + + 如需手动添加，请在config/framework_config.xml的\标签内增加产品项。 + +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 + ``` + + + false + + + + D:\Test\testcase\tests + + ``` + >**说明：** ``标签表示是否需要编译用例；``标签表示测试用例查找路径。 + +#### 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 +``` diff --git a/zh-cn/device-dev/kernel/Readme-CN.md b/zh-cn/device-dev/kernel/Readme-CN.md index 10f14510e83b69dbad815992ca986139bb87df16..d243354b9c95f462dcddd8fcb6ef7acd396b62d9 100755 --- a/zh-cn/device-dev/kernel/Readme-CN.md +++ b/zh-cn/device-dev/kernel/Readme-CN.md @@ -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) diff --git a/zh-cn/device-dev/kernel/figures/zh-cn_image_0000002324.png b/zh-cn/device-dev/kernel/figures/zh-cn_image_0000002324.png new file mode 100644 index 0000000000000000000000000000000000000000..bb35a8ccde16464e275917644fb5066b2706bbdb Binary files /dev/null and b/zh-cn/device-dev/kernel/figures/zh-cn_image_0000002324.png differ diff --git a/zh-cn/device-dev/kernel/figures/zh-cn_image_000000232425.png b/zh-cn/device-dev/kernel/figures/zh-cn_image_000000232425.png new file mode 100644 index 0000000000000000000000000000000000000000..8239b823f6d02fe6b9459b319c9f1260bbbfb789 Binary files /dev/null and b/zh-cn/device-dev/kernel/figures/zh-cn_image_000000232425.png differ diff --git a/zh-cn/device-dev/kernel/figures/zh-cn_image_000000232426.png b/zh-cn/device-dev/kernel/figures/zh-cn_image_000000232426.png new file mode 100644 index 0000000000000000000000000000000000000000..fd8550c59b39a3c98a225060e93b2316e7c45b96 Binary files /dev/null and b/zh-cn/device-dev/kernel/figures/zh-cn_image_000000232426.png differ diff --git a/zh-cn/device-dev/kernel/figures/zh-cn_image_000000232428.png b/zh-cn/device-dev/kernel/figures/zh-cn_image_000000232428.png new file mode 100644 index 0000000000000000000000000000000000000000..7c2ecfd6e8c1f0d84b9e9cb97efa29af98859d0b Binary files /dev/null and b/zh-cn/device-dev/kernel/figures/zh-cn_image_000000232428.png differ diff --git a/zh-cn/device-dev/kernel/kernel-small-plimits.md b/zh-cn/device-dev/kernel/kernel-small-plimits.md new file mode 100644 index 0000000000000000000000000000000000000000..7472c723e125f842df01088fddf2ff3a4b7f94d9 --- /dev/null +++ b/zh-cn/device-dev/kernel/kernel-small-plimits.md @@ -0,0 +1,331 @@ +# 容器配额（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文件目录见下表： + + |
权限
| 大小 | 用户 | 用户组 | 文件名 | 文件描述 | + | --------- | ---- | ---- | ------ | ---------------------- | --------- | + |-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 +#include +#include +#include +#include +#include +#include + +#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 +``` diff --git a/zh-cn/device-dev/reference/hdi-apis/_alloc_info.md b/zh-cn/device-dev/reference/hdi-apis/_alloc_info.md index ccbcd8849e6a1dd3f440561b03a50953475f2248..b75e855aa644a53d4a51f52124346e34c4368d9c 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_alloc_info.md +++ b/zh-cn/device-dev/reference/hdi-apis/_alloc_info.md @@ -3,7 +3,7 @@ ## **概述** -定义关于要分配的内存的信息。 +定义待分配的内存的信息。 **相关模块:** diff --git a/zh-cn/device-dev/reference/hdi-apis/_audio_adapter.md b/zh-cn/device-dev/reference/hdi-apis/_audio_adapter.md index be115d34419463c495a8b9e4e4b3f78f44ccbcaf..21b6213df6b8046579946e9992314dadd360fa22 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_audio_adapter.md +++ b/zh-cn/device-dev/reference/hdi-apis/_audio_adapter.md @@ -5,7 +5,7 @@ AudioAdapter音频适配器接口。 -提供音频适配器（声卡）对外支持的驱动能力，包括初始化端口、创建render、创建capture、获取端口能力集等。 +提供音频适配器（声卡）对外支持的驱动能力，包括初始化端口、创建Render、创建Capture、获取端口能力集等。 **Since:** @@ -34,15 +34,15 @@ AudioAdapter音频适配器接口。 | 名称 | 描述 | | -------- | -------- | | ([InitAllPorts](#initallports))(struct AudioAdapter \*adapter) | 初始化一个音频适配器所有的端口驱动 | -| ([CreateRender](#createrender) )(struct AudioAdapter \*adapter, const struct AudioDeviceDescriptor \*desc, const struct AudioSampleAttributes \*attrs, struct AudioRender \*\*render) | 创建一个音频播放（render）接口的对象 | -| ([DestroyRender](#destroyrender) )(struct AudioAdapter \*adapter, struct AudioRender \*render) | 销毁一个音频播放（render）接口的对象 | -| ([CreateCapture](#createcapture))(struct AudioAdapter \*adapter, const struct AudioDeviceDescriptor \*desc, const struct AudioSampleAttributes \*attrs, struct AudioCapture \*\*capture) | 创建一个音频录音（capture）接口的对象 | -| ([DestroyCapture](#destroycapture))(struct AudioAdapter \*adapter, struct AudioCapture \*capture) | 销毁一个音频录音（capture）接口的对象 | +| ([CreateRender](#createrender) )(struct AudioAdapter \*adapter, const struct AudioDeviceDescriptor \*desc, const struct AudioSampleAttributes \*attrs, struct AudioRender \*\*render) | 创建一个音频播放（Render）接口的对象 | +| ([DestroyRender](#destroyrender) )(struct AudioAdapter \*adapter, struct AudioRender \*render) | 销毁一个音频播放（Render）接口的对象 | +| ([CreateCapture](#createcapture))(struct AudioAdapter \*adapter, const struct AudioDeviceDescriptor \*desc, const struct AudioSampleAttributes \*attrs, struct AudioCapture \*\*capture) | 创建一个音频录音（Capture）接口的对象 | +| ([DestroyCapture](#destroycapture))(struct AudioAdapter \*adapter, struct AudioCapture \*capture) | 销毁一个音频录音（Capture）接口的对象 | | ([GetPortCapability](#getportcapability) )(struct AudioAdapter \*adapter, struct AudioPort \*port, struct AudioPortCapability \*capability) | 获取一个音频适配器的端口驱动的能力集 | | ([SetPassthroughMode](#setpassthroughmode) )(struct AudioAdapter \*adapter, struct AudioPort \*port, enum AudioPortPassthroughMode mode) | 设置音频端口驱动的数据透传模式 | | ([GetPassthroughMode](#getpassthroughmode))(struct AudioAdapter \*adapter, struct AudioPort \*port, enum AudioPortPassthroughMode \*mode) | 获取音频端口驱动的数据透传模式 | | ([UpdateAudioRoute](#updateaudioroute))(struct AudioAdapter \*adapter, const struct AudioRoute \*route, int32_t \*routeHandle) | 更新一个或多个发送端和接受端之间的路由 | -| ([ReleaseAudioRoute](#releaseaudioroute))(struct AudioAdapter \*adapter, int32_t routeHandle) | 释放一个音频路由. | +| ([ReleaseAudioRoute](#releaseaudioroute))(struct AudioAdapter \*adapter, int32_t 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，失败返回负值。 diff --git a/zh-cn/device-dev/reference/hdi-apis/_audio_attribute.md b/zh-cn/device-dev/reference/hdi-apis/_audio_attribute.md index 91b7118108cc00bdce8ecfc2931789e5bbb40ba3..32fb2917b206ae9297f47d920e61a9c1cac27323 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_audio_attribute.md +++ b/zh-cn/device-dev/reference/hdi-apis/_audio_attribute.md @@ -5,7 +5,7 @@ AudioAttribute音频属性接口。 -提供音频播放（render）或录音（capture）需要的公共属性驱动能力，包括获取帧（frame）信息、设置采样属性等。 +提供音频播放（Render）或录音（Capture）需要的公共属性驱动能力，包括获取帧（frame）信息、设置采样属性等。 **Since:** @@ -34,8 +34,8 @@ AudioAttribute音频属性接口。 | ([GetCurrentChannelId](#getcurrentchannelid))(AudioHandle handle, uint32_t \*channelId) | 获取音频的数据通道ID | | ([SetExtraParams](#setextraparams))(AudioHandle handle, const char \*keyValueList) | 设置音频拓展参数 | | ([GetExtraParams](#getextraparams))(AudioHandle handle, char \*keyValueList) | 获取音频拓展参数 | -| ([ReqMmapBuffer](#reqmmapbuffer))(AudioHandle handle, int32_t reqSize, struct AudioMmapBufferDescripter \*desc) | 请求mmap缓冲区 | -| ([GetMmapPosition](#getmmapposition))(AudioHandle handle, uint64_t \*frames, struct AudioTimeStamp \*time) | 获取当前mmap的读/写位置 | +| ([ReqMmapBuffer](#reqmmapbuffer))(AudioHandle handle, int32_t reqSize, struct AudioMmapBufferDescripter \*desc) | 请求Mmap缓冲区 | +| ([GetMmapPosition](#getmmapposition))(AudioHandle handle, uint64_t \*frames, struct AudioTimeStamp \*time) | 获取当前Mmap的读/写位置 | | ([AddAudioEffect](#addaudioeffect))(AudioHandle handle, uint64_t effectid) | 添加音频效果算法实例 | | ([RemoveAudioEffect](#removeaudioeffect))(AudioHandle handle, uint64_t effectid) | 移除音频效果算法实例 | | ([GetFrameBufferSize](#getframebuffersize))(AudioHandle handle, uint64_t \*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，失败返回负值。 **参见:** diff --git a/zh-cn/device-dev/reference/hdi-apis/_audio_capture.md b/zh-cn/device-dev/reference/hdi-apis/_audio_capture.md index 9f316b158812e5d3de68fbd18ccbbf6cfd659a57..c3cecd48016cf8819856ae7cf1eccf85fe778c86 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_audio_capture.md +++ b/zh-cn/device-dev/reference/hdi-apis/_audio_capture.md @@ -21,7 +21,7 @@ AudioCapture录音接口。 | attr | 音频属性能力接口，详情参考[AudioAttribute](_audio_attribute.md)。 | | scene | 音频场景能力接口，详情参考[AudioScene](_audio_scene.md)。 | | volume | 音频音量能力接口，详情参考[AudioVolume](_audio_volume.md)。 | -| ([CaptureFrame](#captureframe))(struct AudioCapture \*capture, void \*frame, uint64_t requestBytes, uint64_t \*replyBytes) | 从音频驱动中录制（capture）一帧输入数据（录音，音频上行数据）。 | +| ([CaptureFrame](#captureframe))(struct AudioCapture \*capture, void \*frame, uint64_t requestBytes, uint64_t \*replyBytes) | 从音频驱动中录制（Capture）一帧输入数据（录音，音频上行数据）。 | | ([GetCapturePosition](#getcaptureposition))(struct AudioCapture \*capture, uint64_t \*frames, struct AudioTimeStamp \*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，失败返回负值。 **参见:** diff --git a/zh-cn/device-dev/reference/hdi-apis/_audio_control.md b/zh-cn/device-dev/reference/hdi-apis/_audio_control.md index 0a7c29043458659885ef3be77f83309b93364b76..368c9f34b2028cbd0a4b99d7abf6bb0ebe502fdc 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_audio_control.md +++ b/zh-cn/device-dev/reference/hdi-apis/_audio_control.md @@ -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 handle) | 启动一个音频播放（render）或录音（capture）处理 | -| ([Stop](#stop))(AudioHandle handle) | 停止一个音频播放（render）或录音（capture）处理 | -| ([Pause](#pause))(AudioHandle handle) | 暂停一个音频播放（render）或录音（capture）处理 | -| ([Resume](#resume))(AudioHandle handle) | 恢复一个音频播放（render）或录音（capture）处理 | -| ([Flush](#flush))(AudioHandle handle) | 刷新音频缓冲区buffer中的数据 | -| ([TurnStandbyMode](#turnstandbymode))(AudioHandle handle) | 设置或去设置设备的待机模式 | -| ([AudioDevDump](#audiodevdump))(AudioHandle handle, int32_t range, int32_t fd) | Dump音频设备信息 | +| ([Start](#start))(AudioHandle handle) | 启动一个音频播放（Render）或录音（Capture）处理。 | +| ([Stop](#stop))(AudioHandle handle) | 停止一个音频播放（Render）或录音（Capture）处理。 | +| ([Pause](#pause))(AudioHandle handle) | 暂停一个音频播放（Render）或录音（Capture）处理。 | +| ([Resume](#resume))(AudioHandle handle) | 恢复一个音频播放（Render）或录音（Capture）处理。 | +| ([Flush](#flush))(AudioHandle handle) | 刷新音频缓冲区buffer中的数据。 | +| ([TurnStandbyMode](#turnstandbymode))(AudioHandle handle) | 设置或去设置设备的待机模式。 | +| ([AudioDevDump](#audiodevdump))(AudioHandle handle, int32_t range, int32_t 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) **描述：** -设置或去设置设备的待机模式 +设置或去设置设备的待机模式。 **参数:** diff --git a/zh-cn/device-dev/reference/hdi-apis/_audio_manager.md b/zh-cn/device-dev/reference/hdi-apis/_audio_manager.md index d0ad0ecea2c79788ef86f7b9bcd5d130aeb3485a..c809c03c0b8835dcea26e5d18c48cf05d59f3211 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_audio_manager.md +++ b/zh-cn/device-dev/reference/hdi-apis/_audio_manager.md @@ -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 | 输入参数，待卸载的音频适配器接口的对象。 | **参见:** diff --git a/zh-cn/device-dev/reference/hdi-apis/_audio_mmap_buffer_descripter.md b/zh-cn/device-dev/reference/hdi-apis/_audio_mmap_buffer_descripter.md index ae1a56a61e43026fdf892b4c956a884c4d6cce2b..93470c6b005a438663e7efd1b8e6ec204701af20 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_audio_mmap_buffer_descripter.md +++ b/zh-cn/device-dev/reference/hdi-apis/_audio_mmap_buffer_descripter.md @@ -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缓冲区是否可以在进程间共享 | diff --git a/zh-cn/device-dev/reference/hdi-apis/_audio_render.md b/zh-cn/device-dev/reference/hdi-apis/_audio_render.md index c4a172ab2af2c546cb3a33363d254dcebd9b5de6..c7aed448a1393871e2325b41f47be8edeae7bfee 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_audio_render.md +++ b/zh-cn/device-dev/reference/hdi-apis/_audio_render.md @@ -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 AudioRender \*render, uint32_t \*ms) | 获取音频硬件驱动估计的延迟时间。 | -| ([RenderFrame](#renderframe))(struct AudioRender \*render, const void \*frame, uint64_t requestBytes, uint64_t \*replyBytes) | 往音频驱动中播放（render）一帧输出数据（放音，音频下行数据）。 | +| ([RenderFrame](#renderframe))(struct AudioRender \*render, const void \*frame, uint64_t requestBytes, uint64_t \*replyBytes) | 往音频驱动中播放（Render）一帧输出数据（放音，音频下行数据）。 | | ([GetRenderPosition](#getrenderposition))(struct AudioRender \*render, uint64_t \*frames, struct AudioTimeStamp \*time) | 获取音频输出帧数的上一次计数。 | | ([SetRenderSpeed](#setrenderspeed))(struct AudioRender \*render, float speed) | 设置一个音频的播放速度。 | | ([GetRenderSpeed](#getrenderspeed))(struct AudioRender \*render, float \*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，失败返回负值。 **参见:** diff --git a/zh-cn/device-dev/reference/hdi-apis/_audio_scene.md b/zh-cn/device-dev/reference/hdi-apis/_audio_scene.md index 27bf2daee3c3eaf3da86ab30c5d6a24dca4feeb2..f2bf7f3c7639d81dbe4f3ef17c511659dbcf02d3 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_audio_scene.md +++ b/zh-cn/device-dev/reference/hdi-apis/_audio_scene.md @@ -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，失败返回负值。 **参见:** diff --git a/zh-cn/device-dev/reference/hdi-apis/_audio_volume.md b/zh-cn/device-dev/reference/hdi-apis/_audio_volume.md index a4872b457d81268fcf4bcf13e7c6f056f965cbbb..677f5f1999aee3d67a1d6ed0df577ca08eafde16 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_audio_volume.md +++ b/zh-cn/device-dev/reference/hdi-apis/_audio_volume.md @@ -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 待设置的增益 | +| 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，失败返回负值。 diff --git a/zh-cn/device-dev/reference/hdi-apis/_ext_data_handle.md b/zh-cn/device-dev/reference/hdi-apis/_ext_data_handle.md index 51239a52338c14e4d3a360136e58c80b73a64df7..eb120bcd201dd27759e96c7dd73872c7f004b28e 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_ext_data_handle.md +++ b/zh-cn/device-dev/reference/hdi-apis/_ext_data_handle.md @@ -17,6 +17,6 @@ | 名称 | 描述 | | -------- | -------- | -| [fd](_display.md#fd) | 句柄 fd, -1代表不支持。 | +| [fd](_display.md#fd) | 句柄fd，-1代表不支持。 | | [reserveInts](_display.md#reserveints) | reserve数组的个数。 | | [reserve](_display.md#reserve) [0] | reserve数组。 | diff --git a/zh-cn/device-dev/reference/hdi-apis/_i_wlan_interface_8idl.md b/zh-cn/device-dev/reference/hdi-apis/_i_wlan_interface_8idl.md index c29124f5e5f131c61798081b8f95a1d97360ffce..adaa08cb01c1d4e01d58f984623fd0d762a7a56e 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_i_wlan_interface_8idl.md +++ b/zh-cn/device-dev/reference/hdi-apis/_i_wlan_interface_8idl.md @@ -3,9 +3,7 @@ ## **概述** -建立/关闭WLAN热点，扫描/关联/去关联WLAN热点，设置国家码，管理网络设备等操作的接口。 - -上层服务调用相关的接口实现：建立/关闭WLAN热点，扫描/关联/去关联WLAN热点，设置国家码，管理网络设备等功能。 +WLAN模块操作接口，上层服务调用相关的接口可实现：建立/关闭WLAN热点，扫描/关联/去关联WLAN热点，设置国家码，管理网络设备等功能。 **Since:** diff --git a/zh-cn/device-dev/reference/hdi-apis/_wlan_types_8idl.md b/zh-cn/device-dev/reference/hdi-apis/_wlan_types_8idl.md index a0919917f8cad341d90e5637c1ed462b457832f9..03cc663f0672292fae1a77a5f912f80050ee946f 100644 --- a/zh-cn/device-dev/reference/hdi-apis/_wlan_types_8idl.md +++ b/zh-cn/device-dev/reference/hdi-apis/_wlan_types_8idl.md @@ -3,8 +3,6 @@ ## **概述** -WLAN模块相关的数据类型。 - WLAN模块中使用的数据类型，包括feature对象信息、STA信息、扫描信息、网络设备信息等。 **Since:** diff --git a/zh-cn/device-dev/reference/hdi-apis/codec__component__type_h.md b/zh-cn/device-dev/reference/hdi-apis/codec__component__type_h.md index 027912d120d337445daa2a14dcece28259b3ebda..b6ddc54e8b1acbe57d7207ef04e78df87a3a85c6 100644 --- a/zh-cn/device-dev/reference/hdi-apis/codec__component__type_h.md +++ b/zh-cn/device-dev/reference/hdi-apis/codec__component__type_h.md @@ -3,7 +3,6 @@ ## **概述** -Codec模块接口定义中使用的自定义数据类型。 Codec模块接口定义中使用的自定义数据类型，包括编解码类型、音视频参数、buffer定义等。 diff --git a/zh-cn/device-dev/reference/hdi-apis/display__type_8h.md b/zh-cn/device-dev/reference/hdi-apis/display__type_8h.md index bfb64ef5202af14af0ea969ce208b19a2d6e0348..bbf2dabaf247dda3f019bb5b8341ee96019e5f2a 100644 --- a/zh-cn/device-dev/reference/hdi-apis/display__type_8h.md +++ b/zh-cn/device-dev/reference/hdi-apis/display__type_8h.md @@ -52,7 +52,7 @@ | 名称 | 描述 | | -------- | -------- | -| [PROPERTY_NAME_LEN](_display.md#propertynamelen)   50 | 属性名字长度。 | +| [PROPERTY_NAME_LEN](_display.md#property_name_len)  50 | 属性名字长度。 | ### 枚举 diff --git a/zh-cn/device-dev/reference/hdi-apis/input__type_8h.md b/zh-cn/device-dev/reference/hdi-apis/input__type_8h.md index 22fd725d29f3777faa610810224f9626ce38fae7..44430e50ce053966b1da33e26c65a5ed9147260e 100644 --- a/zh-cn/device-dev/reference/hdi-apis/input__type_8h.md +++ b/zh-cn/device-dev/reference/hdi-apis/input__type_8h.md @@ -44,17 +44,17 @@ Input设备相关的类型定义。 | 名称 | 描述 | | -------- | -------- | -| [MAX_INPUT_DEV_NUM](input.md#maxinputdevnum)   32 | Input设备数量的最大值。 | -| [CHIP_INFO_LEN](input.md#chipinfolen)   10 | 芯片信息长度。 | -| [CHIP_NAME_LEN](input.md#chipnamelen)   10 | 芯片名称长度。 | -| [VENDOR_NAME_LEN](input.md#vendornamelen)   10 | 厂商名称长度。 | -| [DEV_NAME_LEN](input.md#devnamelen)   64 | Input设备名称长度。 | -| [SELF_TEST_RESULT_LEN](input.md#selftestresultlen)   20 | 自测结果长度。 | -| [DEV_MANAGER_SERVICE_NAME](input.md#devmanagerservicename)   "hdf_input_host" | Input设备节点服务名称。 | -| [DIV_ROUND_UP](input.md#divroundup)(nr, d)   (((nr) + (d) - 1) / (d)) | 向上取整计算公式。 | -| [BYTE_HAS_BITS](input.md#bytehasbits)   8 | 一个字节所包含的比特数。 | -| [BITS_TO_UINT64](input.md#bitstouint64)(count)   [DIV_ROUND_UP](input.md#divroundup)(count, [BYTE_HAS_BITS](input.md#bytehasbits) \* sizeof(uint64_t)) | 比特与64位无符号整数的转换公式。 | -| [HDF_FF_CNT](input.md#hdfffcnt)   (0x7f + 1) | Input设备发送力反馈命令的数量最大值。 | +| [MAX_INPUT_DEV_NUM](input.md#max_input_dev_num)   32 | Input设备数量的最大值。 | +| [CHIP_INFO_LEN](input.md#chip_info_len)   10 | 芯片信息长度。 | +| [CHIP_NAME_LEN](input.md#chip_name_len)   10 | 芯片名称长度。 | +| [VENDOR_NAME_LEN](input.md#vendor_name_len)   10 | 厂商名称长度。 | +| [DEV_NAME_LEN](input.md#dev_name_len)   64 | Input设备名称长度。 | +| [SELF_TEST_RESULT_LEN](input.md#self_test_result_len)   20 | 自测结果长度。 | +| [DEV_MANAGER_SERVICE_NAME](input.md#dev_manager_service_name)   "hdf_input_host" | Input设备节点服务名称。 | +| [DIV_ROUND_UP](input.md#div_round_up)(nr, d)   (((nr) + (d) - 1) / (d)) | 向上取整计算公式。 | +| [BYTE_HAS_BITS](input.md#byte_has_bits)   8 | 一个字节所包含的比特数。 | +| [BITS_TO_UINT64](input.md#bits_to_uint64)(count)   [DIV_ROUND_UP](input.md#div_round_up)(count, [BYTE_HAS_BITS](input.md#byte_has_bits) \* sizeof(uint64_t)) | 比特与64位无符号整数的转换公式。 | +| [HDF_FF_CNT](input.md#hdf_ff_cnt)   (0x7f + 1) | Input设备发送力反馈命令的数量最大值。 | ### 枚举 diff --git a/zh-cn/device-dev/reference/hdi-apis/sensor.md b/zh-cn/device-dev/reference/hdi-apis/sensor.md index 819b16becb94b74508e91dfdd5f560235b1ffe21..5c37da3a27dd00fe925aba5de15f35a8a52d1a88 100644 --- a/zh-cn/device-dev/reference/hdi-apis/sensor.md +++ b/zh-cn/device-dev/reference/hdi-apis/sensor.md @@ -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模块对外通用的接口声明文件，提供获取传感器设备信息、订阅/取消订阅传感器数据、 使能/去使能传感器、设置传感器模式、设置传感器精度，量程等可选配置接口定义。 | +| [ISensorInterface.idl](_i_sensor_interface_8idl.md) | Sensor模块对外通用的接口声明文件，提供获取传感器设备信息、订阅/取消订阅传感器数据、使能/去使能传感器、设置传感器模式、设置传感器精度，量程等可选配置接口定义。 | | [SensorTypes.idl](_sensor_types_8idl.md) | 定义传感器模块所使用的传感器类型，传感器信息，传感器数据结构等数据类型。 | diff --git a/zh-cn/device-dev/subsystems/figures/HiTraceMeter.png b/zh-cn/device-dev/subsystems/figures/HiTraceMeter.png new file mode 100644 index 0000000000000000000000000000000000000000..15e6c6bc750993801d814bfba775a8f4a0141590 Binary files /dev/null and b/zh-cn/device-dev/subsystems/figures/HiTraceMeter.png differ diff --git a/zh-cn/device-dev/subsystems/subsys-build-module.md b/zh-cn/device-dev/subsystems/subsys-build-module.md index 060c3e8cd1de8b643d28172f663400a785f2512e..07c0b3022f064ca92c99795b200684f510ac7514 100644 --- a/zh-cn/device-dev/subsystems/subsys-build-module.md +++ b/zh-cn/device-dev/subsystems/subsys-build-module.md @@ -25,7 +25,7 @@ ohos_resources #其他常用模板 #配置文件 -ohos_prebuild_etc +ohos_prebuilt_etc #sa配置 ohos_sa_profile diff --git a/zh-cn/device-dev/subsystems/subsys-dfx-hitracemeter.md b/zh-cn/device-dev/subsystems/subsys-dfx-hitracemeter.md index 11ec506b37867823f6c4e73dae4b7444dba48fe5..43eb7d21472cf8206f517711046af4786a327516 100644 --- a/zh-cn/device-dev/subsystems/subsys-dfx-hitracemeter.md +++ b/zh-cn/device-dev/subsystems/subsys-dfx-hitracemeter.md @@ -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。
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。
value: Trace携带的信息，表明当前的某种状态，例如内存大小，队列长短等。
taskId：异步Trace中用来表示关联的ID。 | +| void FinishAsyncTrace(uint64_t label, const std::string& value, int32_t taskId); | 关闭异步trace | label: Trace category。
value: Trace携带的信息，表明当前的某种状态，例如内存大小，队列长短等。
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。
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; + } ```