diff --git a/CODEOWNERS b/CODEOWNERS index 3598264d0126154e0a84838f393fb3864f493dd7..24411de3dbc2ce0663ee65f2cfd514c27f94bb81 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -554,3 +554,4 @@ zh-cn/application-dev/reference/errorcodes/errorcode-webview.md @HelloCrease zh-cn/application-dev/reference/errorcodes/errorcode-window.md @ge-yafang zh-cn/application-dev/reference/errorcodes/errorcode-workScheduler.md @ningningW zh-cn/application-dev/reference/errorcodes/errorcode-zlib.md @RayShih +zh-cn/application-dev/reference/apis/js-apis-calendarManager.md @ge-yafang @jt_123456 @edollar \ No newline at end of file diff --git a/en/application-dev/connectivity/socket-connection.md b/en/application-dev/connectivity/socket-connection.md index 109b63fdb5fdcae98e23882b32018d4a03435f55..9dda8b4e4c0ac6931ea75ad706fef76c9fb3c0a3 100644 --- a/en/application-dev/connectivity/socket-connection.md +++ b/en/application-dev/connectivity/socket-connection.md @@ -2,7 +2,7 @@ ## Introduction -The Socket Connection module allows an application to transmit data over a Socket connection through the TCP, UDP, or TLS protocol. +The Socket Connection module allows an application to transmit data over a socket connection through the TCP, UDP, or TLS protocol. ## Basic Concepts @@ -13,10 +13,11 @@ The Socket Connection module allows an application to transmit data over a Socke ## When to Use -Applications transmit data over TCP, UDP, or TLS Socket connections. The main application scenarios are as follows: +Applications transmit data over TCP, UDP, or TLS socket connections. The main application scenarios are as follows: -- Implementing data transmission over TCP/UDP Socket connections -- Implementing encrypted data transmission over TLS Socket connections +- Implementing data transmission over TCP socket or UDP socket connections +- Implementing data transmission over TCP socket server connections +- Implementing encrypted data transmission over TLS socket connections ## Available APIs @@ -28,72 +29,75 @@ Socket connection functions are mainly implemented by the **socket** module. The | -------- | -------- | | constructUDPSocketInstance() | Creates a **UDPSocket** object.| | constructTCPSocketInstance() | Creates a **TCPSocket** object.| +| constructTCPSocketServerInstance() | Creates a **TCPSocketServer** object.| +| listen() | Listens for and accepts TCP socket connections established over the socket. (This API is applicable only to TCP.)| | bind() | Binds the IP address and port number.| | send() | Sends data.| -| close() | Closes a Socket connection.| -| getState() | Obtains the Socket connection status.| +| close() | Closes a socket connection.| +| getState() | Obtains the socket connection status.| | connect() | Connects to the specified IP address and port. This function is supported only for TCP.| -| getRemoteAddress() | Obtains the peer address of the Socket connection. This function is supported only for TCP. The **connect** API must have been called before you use this API.| -| on(type: 'message') | Subscribes to **message** events of the Socket connection.| -| off(type: 'message') | Unsubscribes from **message** events of the Socket connection.| -| on(type: 'close') | Subscribes to **close** events of the Socket connection.| -| off(type: 'close') | Unsubscribes from **close** events of the Socket connection.| -| on(type: 'error') | Subscribes to **error** events of the Socket connection.| -| off(type: 'error') | Unsubscribes from **error** events of the Socket connection.| -| on(type: 'listening') | Subscribes to **listening** events of the UDP Socket connection. | -| off(type: 'listening') | Unsubscribes from **listening** events of the UDP Socket connection. | -| on(type: 'connect') | Subscribes to **connect** events of the TCP Socket connection. | -| off(type: 'connect') | Unsubscribes from **connect** events of the TCP Socket connection.| - -TLS Socket connection functions are mainly provided by the **tls_socket** module. The following table describes the related APIs. +| getRemoteAddress() | Obtains the peer address of the socket connection. This function is supported only for TCP. The **connect** API must have been called before you use this API.| +| setExtraOptions() | Sets other properties of the socket connection.| +| on(type: 'message') | Subscribes to **message** events of the socket connection.| +| off(type: 'message') | Unsubscribes from **message** events of the socket connection.| +| on(type: 'close') | Subscribes to **close** events of the socket connection.| +| off(type: 'close') | Unsubscribes from **close** events of the socket connection.| +| on(type: 'error') | Subscribes to **error** events of the socket connection.| +| off(type: 'error') | Unsubscribes from **error** events of the socket connection.| +| on(type: 'listening') | Subscribes to **listening** events of the UDP socket connection. | +| off(type: 'listening') | Unsubscribes from **listening** events of the UDP socket connection. | +| on(type: 'connect') | Subscribes to **connect** events of the TCP socket connection. | +| off(type: 'connect') | Unsubscribes from **connect** events of the TCP socket connection.| + +TLS socket connection functions are mainly provided by the **tls_socket** module. The following table describes the related APIs. | API| Description| | -------- | -------- | | constructTLSSocketInstance() | Creates a **TLSSocket** object.| | bind() | Binds the IP address and port number.| -| close(type: 'error') | Closes a Socket connection.| +| close(type: 'error') | Closes a socket connection.| | connect() | Sets up a connection to the specified IP address and port number.| | getCertificate() | Obtains an object representing the local certificate.| | getCipherSuite() | Obtains a list containing information about the negotiated cipher suite.| | getProtocol() | Obtains a string containing the SSL/TLS protocol version negotiated for the current connection.| -| getRemoteAddress() | Obtains the peer address of the TLS Socket connection.| +| getRemoteAddress() | Obtains the peer address of the TLS socket connection.| | getRemoteCertificate() | Obtains an object representing a peer certificate.| | getSignatureAlgorithms() | Obtains a list containing signature algorithms shared between the server and client, in descending order of priority.| -| getState() | Obtains the TLS Socket connection status.| -| off(type: 'close') | Unsubscribes from **close** events of the TLS Socket connection.| -| off(type: 'error') | Unsubscribes from **error** events of the TLS Socket connection.| -| off(type: 'message') | Unsubscribes from **message** events of the TLS Socket connection.| -| on(type: 'close') | Subscribes to **close** events of the TLS Socket connection.| -| on(type: 'error') | Subscribes to **error** events of the TLS Socket connection.| -| on(type: 'message') | Subscribes to **message** events of the TLS Socket connection.| +| getState() | Obtains the TLS socket connection status.| +| off(type: 'close') | Unsubscribes from **close** events of the TLS socket connection.| +| off(type: 'error') | Unsubscribes from **error** events of the TLS socket connection.| +| off(type: 'message') | Unsubscribes from **message** events of the TLS socket connection.| +| on(type: 'close') | Subscribes to **close** events of the TLS socket connection.| +| on(type: 'error') | Subscribes to **error** events of the TLS socket connection.| +| on(type: 'message') | Subscribes to **message** events of the TLS socket connection.| | send() | Sends data.| -| setExtraOptions() | Sets other properties of the TLS Socket connection.| +| setExtraOptions() | Sets other properties of the TLS socket connection.| -## Transmitting Data over TCP/UDP Socket Connections +## Transmitting Data over TCP Socket or UDP Socket Connections -The implementation is similar for UDP Socket and TCP Socket connections. The following uses data transmission over a TCP Socket connection as an example. +The implementation is similar for UDP socket and TCP socket connections. The following uses data transmission over a TCP socket connection as an example. 1. Import the required **socket** module. -2. Create a **TCPSocket** object. +2. Create a TCP socket connection. A **TCPSocket** object is returned. -3. (Optional) Subscribe to TCP Socket connection events. +3. (Optional) Subscribe to TCP socket connection events. 4. Bind the IP address and port number. The port number can be specified or randomly allocated by the system. 5. Set up a connection to the specified IP address and port number. -6. Send data. +6. Send data over the connection. -7. Enable the TCP Socket connection to be automatically closed after use. +7. Enable the TCP socket connection to be automatically closed after use. ```js import socket from '@ohos.net.socket' -// Create a TCPSocket object. +// Create a TCP socket connection. A TCPSocket object is returned. let tcp = socket.constructTCPSocketInstance(); -// Subscribe to TCP Socket connection events. +// Subscribe to events of the TCPSocket object. tcp.on('message', value => { console.log("on message") let buffer = value.message @@ -139,7 +143,7 @@ tcp.bind(bindAddress, err => { } console.log('connect success'); - // Send data. + // Send data over the connection. tcp.send({ data: 'Hello, server!' }, err => { @@ -152,7 +156,7 @@ tcp.bind(bindAddress, err => { }); }); -// Enable the TCP Socket connection to be automatically closed after use. Then, disable listening for TCP Socket connection events. +// Enable the socket connection to be automatically closed after use. Then, unsubscribe from events of the connection. setTimeout(() => { tcp.close((err) => { console.log('close socket.') @@ -163,11 +167,92 @@ setTimeout(() => { }, 30 * 1000); ``` +## Implementing Data Transmission over TCP Socket Server Connections + +### How to Develop + +The TCP socket server connection process is described as follows: + +1. Import the required **socket** module. +2. Create a TCP socket server connection. A **TCPSocketServer** object is returned. +3. Bind the local IP address and port, and listen for and accept TCP socket connections established over the socket. +4. Subscribe to **connect** events of the **TCPSocketServer** object to listen for client connection status changes. +5. Set up a connection between the client and the server. A **TCPSocketConnection** object is returned. +6. Subscribe to events of the **TCPSocketConnection** object, and send data to the client through the **TCPSocketConnection** object. +7. Close the connection between the client and the server. +8. Unsubscribe from events of the **TCPSocketConnection** and **TCPSocketServer** objects. + +```js +import socket from '@ohos.net.socket' + +// Create a TCP socket server connection. A TCPSocketServer object is returned. +let tcpServer = socket.constructTCPSocketServerInstance(); + +// Bind the local IP address and port number for listening. +tcpServer.listen({ address: "192.168.xx.xxx", port: xxxx, family: 1 }, err => { + if (err) { + console.log("listen fail"); + return; + } + console.log("listen success"); +}) + +// Subscribe to connect events of the TCPSocketServer object. +tcpServer.on('connect', function(client) { + // Subscribe to events of the TCPSocketConnection object. + client.on('close', () => { + console.log("on close success"); + }); + client.on('message', function(value) { + let buffer = value.message; + let dataView = new DataView(buffer); + let str = ""; + for (let i = 0; i < dataView.byteLength; ++i) { + str += String.fromCharCode(dataView.getUint8(i)); + } + console.log("received message--:" + str); + console.log("received address--:" + value.remoteInfo.address); + console.log("received family--:" + value.remoteInfo.family); + console.log("received port--:" + value.remoteInfo.port); + console.log("received size--:" + value.remoteInfo.size); + }); + + // Send data to the client. + client.send({data: 'Hello, client!'}, err => { + if (err) { + console.log('send fail'); + return; + } + console.log('send success'); + }); + + // Close the connection between the client and the server. + client.close(err => { + if (err) { + console.log('close fail'); + return; + } + console.log('close success'); + }); + + // Unsubscribe from events of the TCPSocketConnection object. + setTimeout(() => { + client.off('message'); + client.off('close'); + }, 10 * 1000); +}); + +// Unsubscribe from events of the TCPSocketServer object. +setTimeout(() => { + tcpServer.off('connect'); +}, 30 * 1000); +``` + ## Implementing Encrypted Data Transmission over TLS Socket Connections ### How to Develop -TLS Socket connection process on the client: +The TLSsocket connection process on the client is described as follows: 1. Import the required **socket** module. @@ -175,21 +260,21 @@ TLS Socket connection process on the client: 3. For two-way authentication, upload the client CA certificate and digital certificate. For one-way authentication, upload the client CA certificate. -4. Create a **TLSSocket** object. +4. Create a TLS socket connection. A **TLSsocket** object is returned. -5. (Optional) Subscribe to TLS Socket connection events. +5. (Optional) Subscribe to TLS socket connection events. -6. Send data. +6. Send data over the connection. -7. Enable the TLS Socket connection to be automatically closed after use. +7. Enable the TLS socket connection to be automatically closed after use. ```js import socket from '@ohos.net.socket' -// Create a TLS Socket connection (for two-way authentication). +// Create a TLS socket connection (for two-way authentication). A TLSSocket object is returned. let tlsTwoWay = socket.constructTLSSocketInstance(); -// Subscribe to TLS Socket connection events. +// Subscribe to TLS socket connection events. tlsTwoWay.on('message', value => { console.log("on message") let buffer = value.message @@ -246,7 +331,7 @@ tlsTwoWay.connect(options, (err, data) => { console.log(data); }); -// Enable the TCP Socket connection to be automatically closed after use. Then, disable listening for TCP Socket connection events. +// Enable the socket connection to be automatically closed after use. Then, unsubscribe from events of the connection. tlsTwoWay.close((err) => { if (err) { console.log("close callback error = " + err); @@ -258,10 +343,10 @@ tlsTwoWay.close((err) => { tlsTwoWay.off('close'); }); -// Create a TLS Socket connection (for one-way authentication). +// Create a TLS socket connection (for one-way authentication). A TLSsocket object is returned. let tlsOneWay = socket.constructTLSSocketInstance(); // One way authentication -// Subscribe to TLS Socket connection events. +// Subscribe to TLS socket connection events. tlsTwoWay.on('message', value => { console.log("on message") let buffer = value.message @@ -307,7 +392,7 @@ tlsOneWay.connect(oneWayOptions, (err, data) => { console.log(data); }); -// Enable the TCP Socket connection to be automatically closed after use. Then, disable listening for TCP Socket connection events. +// Enable the socket connection to be automatically closed after use. Then, unsubscribe from events of the connection. tlsTwoWay.close((err) => { if (err) { console.log("close callback error = " + err); @@ -319,11 +404,3 @@ tlsTwoWay.close((err) => { tlsTwoWay.off('close'); }); ``` - -## Samples - -The following samples are provided to help you better understand how to develop Socket connection features: - -- [`Socket`: Socket Connection (ArkTS) (API9)] (https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Connectivity/Socket) -- [UDP Socket (ArkTS) (API9)](https://gitee.com/openharmony/codelabs/tree/master/NetworkManagement/UdpDemoOH) -- [TCP Socket (ArkTS) (API9)](https://gitee.com/openharmony/codelabs/tree/master/NetworkManagement/TcpSocketDemo) diff --git a/en/application-dev/faqs/Readme-EN.md b/en/application-dev/faqs/Readme-EN.md index 760af4a45a98b31c5f8bfed8745c3f100c6e1f60..038869298ca254238293357a0c31b84c817cc9c4 100644 --- a/en/application-dev/faqs/Readme-EN.md +++ b/en/application-dev/faqs/Readme-EN.md @@ -2,7 +2,7 @@ - [Full SDK Compilation](full-sdk-compile-guide.md) - [Switching to Full SDK](full-sdk-switch-guide.md) -- [Using Native APIs (NDK) of the OpenHarmony SDK in a CMake Project](cmake-with-ndk.md) +- [Using NDK in a CMake Project](cmake-with-ndk.md) - [Application Model Development](faqs-ability.md) - ArkUI Development (ArkTS) - [ArkTS Syntax Usage](faqs-arkui-arkts.md) diff --git a/en/application-dev/faqs/cmake-with-ndk.md b/en/application-dev/faqs/cmake-with-ndk.md index 36f339529c78327f2698f90ce199e758ba06485f..60a68a9ecf05aa95680096d67a18dd37bdda74c1 100644 --- a/en/application-dev/faqs/cmake-with-ndk.md +++ b/en/application-dev/faqs/cmake-with-ndk.md @@ -1,4 +1,4 @@ -# Using Native APIs (NDK) of the OpenHarmony SDK in a CMake Project +# Using NDK in a CMake Project ## What Is Native API @@ -10,34 +10,34 @@ You download the Native API Development Kit (NDK) by downloading the OHOS SDK, w - (Recommended) Acquire source code from mirrors for an officially released version. For details, see [release notes](../../release-notes/OpenHarmony-v3.2-release.md). - Download the SDK from the SDK Manager in DevEco Studio. -- Download the SDK from the [daily build](http://ci.openharmony.cn/dailys/dailybuilds), by clicking the download link to the **ohos-sdk-full** component. +- Download the SDK from the [daily build](http://ci.openharmony.cn/workbench/cicd/dailybuild/dailylist), by clicking the download link to the **ohos-sdk-full** component. -![Download from Daily Build](figures/ci_download.png) +![](figures/ci_download.png) ## Decompressing the NDK Place the downloaded NDK in a folder you prefer and decompress it. Below shows the directory structure after decompression. -![SDK Directory Structure](figures/sdk-structure.png) +![](figures/sdk-structure.png) Configure the Linux environment as follows: (Skip them if the NDK is downloaded from DevEco Studio.) -1. Add the CMake tool that comes with the NDK to the environment variables. +Add the CMake tool that comes with the NDK to the environment variables. ``` # Open the .bashrc file. vim ~/.bashrc - # Append the custom CMake path to the file. Save the file and exit. + # Append the custom CMake path to the file. export PATH=~/ohos-sdk/ohos-sdk/linux/native/build-tools/cmake/bin:$PATH # Run the source ~/.bashrc command to make the environment variables take effect. source ~/.bashrc ``` -2. Check the default CMake path. +Check the default CMake path. ``` # Run the which cmake command. which cmake - # The result should be the same as the custom path previously appended to the file. + # The result should be the same as the custom path previously appended to the .bashrc file. ~/ohos-sdk/ohos-sdk/linux/native/build-tools/cmake/bin/cmake ``` diff --git a/en/application-dev/quick-start/module-configuration-file.md b/en/application-dev/quick-start/module-configuration-file.md index 5fe815d3e9df1e60501504dab5b38f3b860e9b93..b6e4a864d4dce6a991c6aa148fc7e45cf5bf002a 100644 --- a/en/application-dev/quick-start/module-configuration-file.md +++ b/en/application-dev/quick-start/module-configuration-file.md @@ -238,7 +238,7 @@ The **abilities** tag represents the UIAbility configuration of the module, whic | description | Description of the UIAbility component. The value is a string with a maximum of 255 bytes or a resource index to the description in multiple languages.| String| Yes (initial value: left empty)| | icon | Icon of the UIAbility component. The value is an icon resource index.| String| Yes (initial value: left empty)
If **UIAbility** is set to **MainElement**, this attribute is mandatory.| | label | Name of the UIAbility component displayed to users. The value is a string resource index.| String| Yes (initial value: left empty)
If **UIAbility** is set to **MainElement**, this attribute is mandatory.| -| permissions | Permissions required for another application to access the UIAbility component.
The value is an array of permission names predefined by the system, generally in the reverse domain name notation. It contains a maximum of 255 bytes.| String array| Yes (initial value: left empty)| +| permissions | Permissions required for another application to access the UIAbility component.
The value is generally in the reverse domain name notation and contains a maximum of 255 bytes. It is an array of predefined permission names.| String array| Yes (initial value: left empty)| | [metadata](#metadata)| Metadata information of the UIAbility component.| Object array| Yes (initial value: left empty)| | exported | Whether the UIAbility component can be called by other applications.
- **true**: The UIAbility component can be called by other applications.
- **false**: The UIAbility component cannot be called by other applications.| Boolean| Yes (initial value: **false**)| | continuable | Whether the UIAbility component can be [migrated](../application-models/hop-cross-device-migration.md).
- **true**: The UIAbility component can be migrated.
- **false**: The UIAbility component cannot be migrated.| Boolean| Yes (initial value: **false**)| @@ -377,7 +377,7 @@ The **extensionAbilities** tag represents the configuration of extensionAbilitie | icon | Icon of the ExtensionAbility component. The value is an icon resource index. If **ExtensionAbility** is set to **MainElement** of the current module, this attribute is mandatory and its value must be unique in the application.| String| Yes (initial value: left empty)| | label | Name of the ExtensionAbility component displayed to users. The value is a string resource index.
**NOTE**
If **ExtensionAbility** is set to **MainElement** of the current module, this attribute is mandatory and its value must be unique in the application.| String| No| | type | Type of the ExtensionAbility component. The options are as follows:
- **form**: ExtensionAbility of a widget.
- **workScheduler**: ExtensionAbility of a Work Scheduler task.
- **inputMethod**: ExtensionAbility of an input method.
- **service**: service component running in the background.
- **accessibility**: ExtensionAbility of an accessibility feature.
- **dataShare**: ExtensionAbility for data sharing.
- **fileShare**: ExtensionAbility for file sharing.
- **staticSubscriber**: ExtensionAbility for static broadcast.
- **wallpaper**: ExtensionAbility of the wallpaper.
- **backup**: ExtensionAbility for data backup.
- **window**: ExtensionAbility of a window. This type of ExtensionAbility creates a window during startup for which you can develop the GUI. The window is then combined with other application windows through **abilityComponent**.
- **thumbnail**: ExtensionAbility for obtaining file thumbnails. You can provide thumbnails for files of customized file types.
- **preview**: ExtensionAbility for preview. This type of ExtensionAbility can parse the file and display it in a window. You can combine the window with other application windows.
- **print**: ExtensionAbility for the print framework.
- **push**: ExtensionAbility to be pushed.
- **driver**: ExtensionAbility for the driver framework.
**NOTE**
The **service** and **dataShare** types apply only to system applications and do not take effect for third-party applications.| String| No| -| permissions | Permissions required for another application to access the ExtensionAbility component.
The value is generally in the reverse domain name notation and contains a maximum of 255 bytes. It is an array of permission names predefined by the system or customized. The name of a customized permission must be the same as the **name** value of a permission defined in the **defPermissions** attribute.| String array| Yes (initial value: left empty)| +| permissions | Permissions required for another application to access the ExtensionAbility component.
The value is generally in the reverse domain name notation and contains a maximum of 255 bytes. It is an array of [predefined permission names](../security/permission-list.md).| String array| Yes (initial value: left empty)| | uri | Data URI provided by the ExtensionAbility component. The value is a string with a maximum of 255 bytes, in the reverse domain name notation.
**NOTE**
This attribute is mandatory when the type of the ExtensionAbility component is set to **dataShare**.| String| Yes (initial value: left empty)| |skills | Feature set of [wants](../application-models/want-overview.md) that can be received by the ExtensionAbility component.
Configuration rule: In an entry package, you can configure multiple **skills** attributes with the entry capability. (A **skills** attribute with the entry capability is the one that has **ohos.want.action.home** and **entity.system.home** configured.) The **label** and **icon** in the first ExtensionAbility that has **skills** configured are used as the **label** and **icon** of the entire OpenHarmony service/application.
**NOTE**
The **skills** attribute with the entry capability can be configured for the feature package of an OpenHarmony application, but not for an OpenHarmony service.| Array| Yes (initial value: left empty)| | [metadata](#metadata)| Metadata of the ExtensionAbility component.| Object| Yes (initial value: left empty)| diff --git a/en/application-dev/quick-start/resource-categories-and-access.md b/en/application-dev/quick-start/resource-categories-and-access.md index f047ad787904690cb3efd7f8c9beaf580d348a7b..232d6c8a962762aff2bf8a457e5f168a33b13a29 100644 --- a/en/application-dev/quick-start/resource-categories-and-access.md +++ b/en/application-dev/quick-start/resource-categories-and-access.md @@ -265,7 +265,7 @@ Text($r('app.string.message_arrive', "five of the clock")) .fontColor($r('app.color.color_hello')) .fontSize($r('app.float.font_hello')) -// Reference plural resources. The first parameter of $r indicates the plural resource, the second parameter indicates the number of plural resources (for English, **one** indicates singular and is represented by **1**, and **other** indicates plural and is represented by an integer greater than or equal to 1; for Chinese, **other** indicates both singular and plural), and the third parameter is used to replace %d. +// Reference plural resources. The first parameter of $r indicates the plural resource, the second parameter indicates the number of plural resources (for English, one indicates singular and is represented by 1, and other indicates plural and is represented by an integer greater than or equal to 1; for Chinese, other indicates both singular and plural), and the third parameter is used to replace %d. // In this example, the resultant value is "5 apples". Text($r('app.plural.eat_apple', 5, 5)) .fontColor($r('app.color.color_world')) diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index cc95f18bea02638e473d14ac31d585b12a9ca45a..4fc3fb5005d7ac0208b083be1a084bd5c66b4865 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -441,6 +441,7 @@ - [@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)](js-apis-EnterpriseAdminExtensionAbility.md) - [@ohos.enterprise.networkManager (Network Management)](js-apis-enterprise-networkManager.md) - [@ohos.enterprise.restrictions (Restrictions)](js-apis-enterprise-restrictions.md) + - [@ohos.enterprise.usbManager (USB Management)](js-apis-enterprise-usbManager.md) - [@ohos.enterprise.wifiManager (Wi-Fi Management)](js-apis-enterprise-wifiManager.md) - Common Library diff --git a/en/application-dev/reference/apis/commonEventManager-definitions.md b/en/application-dev/reference/apis/commonEventManager-definitions.md index d43c0cc0aab7edef6c28384f1f0af0381634be74..134356837a602123aa51fbe489131eac0e12c87d 100644 --- a/en/application-dev/reference/apis/commonEventManager-definitions.md +++ b/en/application-dev/reference/apis/commonEventManager-definitions.md @@ -204,8 +204,8 @@ Indicates that user switching is in progress. - Value: **usual.event.USER_STARTING** - Required subscriber permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS -## COMMON_EVENT_USER_UNLOCKED -(Reserved, not supported yet) Indicates that the credential-encrypted storage has been unlocked for the current user after the device is restarted. +## [COMMON_EVENT_USER_UNLOCKED](./common_event/commonEvent-account.md) +Indicates that the credential-encrypted storage has been unlocked for the current user after the device is restarted. - Value: **usual.event.USER_UNLOCKED** - Required subscriber permissions: none diff --git a/en/application-dev/reference/apis/common_event/commonEvent-account.md b/en/application-dev/reference/apis/common_event/commonEvent-account.md index f850f33644513de697c1cd2f56d2f3439c6660c2..fe1328be2efb39090d7384f969ec8fd546b04b8c 100644 --- a/en/application-dev/reference/apis/common_event/commonEvent-account.md +++ b/en/application-dev/reference/apis/common_event/commonEvent-account.md @@ -44,33 +44,43 @@ APIs related to this event: **activateOsAccount**. This API is a system API. For ## COMMON_EVENT_USER_INFO_UPDATED9+ Indicates that the user information has been updated. -- Value: **usual.event.USER_INFO_UPDATED** +- Value: usual.event.USER_INFO_UPDATED - Required subscriber permissions: none When the distributed account information, system account profile picture, or system account name is changed, the event notification service is triggered to publish this event carrying the system account ID. APIs related to this event: **setOsAccountName**, **setOsAccountProfilePhoto**, and **setOsAccountDistributedInfon**. The first two are system APIs, and the last is a public API. For details, see [@ohos.account.osAccount (OS Account Management)](../js-apis-osAccount.md). +## COMMON_EVENT_USER_UNLOCKED +Indicates that the credential-encrypted storage has been unlocked for the current user after the device is restarted. + +- Value: usual.event.USER_UNLOCKED +- Required subscriber permissions: none + +When the device is unlocked with the lock screen password the first time after user switching, the event notification service is triggered to publish this event carrying the system account ID. + +APIs related to this event: **auth**. This API is a system API. For details, see [@ohos.account.osAccount (OS Account Management)](../js-apis-osAccount.md). + ## COMMON_EVENT_DISTRIBUTED_ACCOUNT_LOGIN (Reserved, not supported yet) Indicates a successful login to a distributed account. -- Value: usual.event.DISTRIBUTED_ACCOUNT_LOGIN +- Value: common.event.DISTRIBUTED_ACCOUNT_LOGIN - Required subscriber permissions: none ## COMMON_EVENT_DISTRIBUTED_ACCOUNT_LOGOUT (Reserved, not supported yet) Indicates a successful logout of a distributed account. -- Value: usual.event.DISTRIBUTED_ACCOUNT_LOGOUT +- Value: common.event.DISTRIBUTED_ACCOUNT_LOGOUT - Required subscriber permissions: none ## COMMON_EVENT_DISTRIBUTED_ACCOUNT_TOKEN_INVALID (Reserved, not supported yet) Indicates the token of a distributed account is invalid. -- Value: usual.event.DISTRIBUTED_ACCOUNT_TOKEN_INVALID +- Value: common.event.DISTRIBUTED_ACCOUNT_TOKEN_INVALID - Required subscriber permissions: none ## COMMON_EVENT_DISTRIBUTED_ACCOUNT_LOGOFF (Reserved, not supported yet) Indicates that a distributed account is deregistered. -- Value: usual.event.DISTRIBUTED_ACCOUNT_LOGOFF +- Value: common.event.DISTRIBUTED_ACCOUNT_LOGOFF - Required subscriber permissions: none diff --git a/en/application-dev/reference/apis/enterpriseDeviceManagement-overview.md b/en/application-dev/reference/apis/enterpriseDeviceManagement-overview.md index 215ec94ffacfccfab474f607b42c58cac8f7fa2b..099e3dc841128d79e6c62eaed2dba40b1cf6103a 100644 --- a/en/application-dev/reference/apis/enterpriseDeviceManagement-overview.md +++ b/en/application-dev/reference/apis/enterpriseDeviceManagement-overview.md @@ -12,12 +12,12 @@ OpenHarmony provides Enterprise Device Management APIs to support enterprise API - Only the stage model is supported. ### Environment Setup -- [Download DevEco Studio](https://developer.harmonyos.com/en/develop/deveco-studio#download) and set it up as instructed on the official website. -- [Download ohos-sdk-full](../../../release-notes/OpenHarmony-v3.2-beta2.md#acquiring-source-code-from-mirrors). +- DevEco Studio: Download DevEco Studio from its official website and perform related configuration. +- ohos-sdk-full: Obtain ohos-sdk-full. For details, see [Replacing Full SDK](../../faqs/full-sdk-switch-guide.md). ### How to Develop -1. Use DevEco Studio to create a project and [switch to full-sdk](../../faqs/full-sdk-switch-guide.md). +1. Use DevEco Studio to create a project and replace the full SDK. 2. In the [HarmonyAppProvision file](../../security/accesstoken-overview.md#application-apls), set the **app-feature** field to **hos_system_app**. @@ -27,11 +27,13 @@ OpenHarmony provides Enterprise Device Management APIs to support enterprise API ### API Reference -To implement network management and Wi-Fi management, see: - +> **NOTE** +> +> - For details about the APIs, see: - [@ohos.enterprise.accountManager (Account Management)](js-apis-enterprise-accountManager.md) - [@ohos.enterprise.adminManager (Enterprise Device Management)](js-apis-enterprise-adminManager.md) - [@ohos.enterprise.applicationManager (Application Management)](js-apis-enterprise-applicationManager.md) +- [@ohos.enterprise.browser (Browser Management)](js-apis-enterprise-browser.md) - [@ohos.enterprise.bundleManager (Bundle Management)](js-apis-enterprise-bundleManager.md) - [@ohos.enterprise.dateTimeManager (System Time Management)](js-apis-enterprise-dateTimeManager.md) - [@ohos.enterprise.deviceControl (Device Control Management)](js-apis-enterprise-deviceControl.md) @@ -40,4 +42,5 @@ To implement network management and Wi-Fi management, see: - [@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)](js-apis-EnterpriseAdminExtensionAbility.md) - [@ohos.enterprise.networkManager (Network Management)](js-apis-enterprise-networkManager.md) - [@ohos.enterprise.restrictions (Restrictions)](js-apis-enterprise-restrictions.md) +- [@ohos.enterprise.usbManager (USB Management)](js-apis-enterprise-usbManager.md) - [@ohos.enterprise.wifiManager (Wi-Fi Management)](js-apis-enterprise-wifiManager.md) diff --git a/en/application-dev/reference/apis/js-apis-accessibility-config.md b/en/application-dev/reference/apis/js-apis-accessibility-config.md index 9a7eb35e202d8fc5a8e73c76f9caee04e5f7776e..00ffea5edcad7dcf8dd8cb603dd3dfe1b66d093d 100644 --- a/en/application-dev/reference/apis/js-apis-accessibility-config.md +++ b/en/application-dev/reference/apis/js-apis-accessibility-config.md @@ -31,8 +31,8 @@ import config from '@ohos.accessibility.config'; | shortkeyTarget | [Config](#config)\| Yes| Yes| Target application for the accessibility extension shortcut key. The value format is 'bundleName/abilityName'.| | captions | [Config](#config)\| Yes| Yes| Whether to enable captions.| | captionsStyle | [Config](#config)\<[accessibility.CaptionsStyle](js-apis-accessibility.md#captionsstyle8)>| Yes| Yes| Captions style.| -| audioMono| [Config](#config)\| Yes| Yes| Whether to enable mono audio. The value **True** means to enable mono audio, and **False** means the opposite.| -| audioBalance| [Config](#config)\| Yes| Yes| Audio balance for the left and right audio channels. The value ranges from -1.0 to 1.0.| +| audioMono10+| [Config](#config)\| Yes| Yes| Whether to enable mono audio. The value **True** means to enable mono audio, and **False** means the opposite.| +| audioBalance10+| [Config](#config)\| Yes| Yes| Audio balance for the left and right audio channels. The value ranges from -1.0 to 1.0.| ## enableAbility diff --git a/en/application-dev/reference/apis/js-apis-bluetooth-ble.md b/en/application-dev/reference/apis/js-apis-bluetooth-ble.md index 4036451fc4941e9b047de860c4172bfa48076138..03c7b7eded3243a25730c8b14b79613315764b1a 100644 --- a/en/application-dev/reference/apis/js-apis-bluetooth-ble.md +++ b/en/application-dev/reference/apis/js-apis-bluetooth-ble.md @@ -1,6 +1,6 @@ # @ohos.bluetooth.ble (Bluetooth BLE Module) -The **ble** module provides APIs for accessing the Bluetooth personal area network. +The **ble** module provides APIs for operating and managing Bluetooth. > **NOTE** > diff --git a/en/application-dev/reference/apis/js-apis-bluetooth.md b/en/application-dev/reference/apis/js-apis-bluetooth.md index 7bd21aac353ac966f7d8f3b96c1b5ef8783dcfe8..8a5f05e2fb5db6b2bbcbeee3770fd4c1c46c7087 100644 --- a/en/application-dev/reference/apis/js-apis-bluetooth.md +++ b/en/application-dev/reference/apis/js-apis-bluetooth.md @@ -3,8 +3,9 @@ The **Bluetooth** module provides classic Bluetooth capabilities and Bluetooth Low Energy (BLE) scan and advertising. > **NOTE** -> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. -> The APIs provided by this module are no longer maintained since API version 9. You are advised to use [bluetoothManager](js-apis-bluetoothManager.md). +> +> - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> - The APIs provided by this module are no longer maintained since API version 9. You are advised to use profile APIs of [@ohos.bluetooth.ble](js-apis-bluetooth-ble.md). diff --git a/en/application-dev/reference/apis/js-apis-bluetoothManager.md b/en/application-dev/reference/apis/js-apis-bluetoothManager.md index b6b353fee524e2abef7c3f74bcb6d4993571a920..99506bf3206092ee1122381d5fb76f65d8618016 100644 --- a/en/application-dev/reference/apis/js-apis-bluetoothManager.md +++ b/en/application-dev/reference/apis/js-apis-bluetoothManager.md @@ -4,7 +4,9 @@ The **Bluetooth** module provides classic Bluetooth capabilities and Bluetooth L > **NOTE** > -> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> +> - This APIs provided by this module are no longer maintained since API version 10. You are advised to use profile APIs of [@ohos.bluetooth.ble](js-apis-bluetooth-ble.md). diff --git a/en/application-dev/reference/apis/js-apis-enterprise-accountManager.md b/en/application-dev/reference/apis/js-apis-enterprise-accountManager.md index 6fad182e98274663af3ded60c01fa955649ebfb4..dae9aefd44beb90aed973cb15b4e9461d135f36f 100644 --- a/en/application-dev/reference/apis/js-apis-enterprise-accountManager.md +++ b/en/application-dev/reference/apis/js-apis-enterprise-accountManager.md @@ -6,6 +6,8 @@ The **accountManager** module provides APIs for account management of enterprise > > - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. > +> - The APIs of this module can be used only in the stage model. +> > - The APIs provided by this module can be called only by a [device administrator application](enterpriseDeviceManagement-overview.md#basic-concepts) that is [enabled](js-apis-enterprise-adminManager.md#adminmanagerenableadmin). ## Modules to Import @@ -18,7 +20,7 @@ import accountManager from '@ohos.enterprise.accountManager'; disallowAddLocalAccount(admin: Want, disallow: boolean, callback: AsyncCallback<void>): void -Forbids a device administrator application to create local user accounts. This API uses an asynchronous callback to return the result. +Disallows a device administrator application to create local user accounts. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_ACCOUNT_POLICY @@ -30,8 +32,8 @@ Forbids a device administrator application to create local user accounts. This A | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | -| admin | [Want](js-apis-app-ability-want.md) | Yes | Enterprise device administrator application. | -| disallow | boolean | Yes | Whether to forbid the creation of local user accounts. The value **true** means that local user accounts cannot be created; the value **false** means the opposite. | +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | +| disallow | boolean | Yes | Whether to forbid the creation of local user accounts. The value **true** means to disallow the creation of local user accounts, and the value **false** means the opposite. | | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | **Error codes** @@ -64,7 +66,7 @@ accountManager.disallowAddLocalAccount(wantTemp, true, (err) => { disallowAddLocalAccount(admin: Want, disallow: boolean): Promise<void> -Forbids a device administrator application to create local user accounts. This API uses a promise to return the result. +Disallows a device administrator application to create local user accounts. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_ACCOUNT_POLICY @@ -76,14 +78,14 @@ Forbids a device administrator application to create local user accounts. This A | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | -| admin | [Want](js-apis-app-ability-want.md) | Yes | Enterprise device administrator application.| -| disallow | boolean | Yes | Whether to forbid the creation of local user accounts. The value **true** means that local user accounts cannot be created; the value **false** means the opposite. | +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| +| disallow | boolean | Yes | Whether to forbid the creation of local user accounts. The value **true** means to disallow the creation of local user accounts, and the value **false** means the opposite. | **Return value** | Type | Description | | --------------------- | ------------------------- | -| Promise<void> | Promise that returns no value. An error object will be thrown if the operation fails.| +| Promise<void> | Promise that returns no value. If the operation fails, an error object will be thrown.| **Error codes** diff --git a/en/application-dev/reference/apis/js-apis-enterprise-applicationManager.md b/en/application-dev/reference/apis/js-apis-enterprise-applicationManager.md index b2d127f28df7434b9bc3f2fad33f520109358178..00e17f92bd50d749a4940ae6f3b7efc48e1e0049 100644 --- a/en/application-dev/reference/apis/js-apis-enterprise-applicationManager.md +++ b/en/application-dev/reference/apis/js-apis-enterprise-applicationManager.md @@ -6,6 +6,8 @@ The **applicationManager** module provides application management capabilities, > > - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. > +> - The APIs of this module can be used only in the stage model. +> > - The APIs provided by this module can be called only by a [device administrator application](enterpriseDeviceManagement-overview.md#basic-concepts) that is [enabled](js-apis-enterprise-adminManager.md#adminmanagerenableadmin). ## Modules to Import @@ -18,7 +20,7 @@ import applicationManager from '@ohos.enterprise.applicationManager'; addDisallowedRunningBundles(admin: Want, appIds: Array\, callback: AsyncCallback<void>): void; -Adds a list of applications that are forbidden to run by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. +Adds the applications that are not allowed to run by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SET_APP_RUNNING_POLICY @@ -66,7 +68,7 @@ applicationManager.addDisallowedRunningBundles(wantTemp, appIds, (err) => { addDisallowedRunningBundles(admin: Want, appIds: Array\, userId: number, callback: AsyncCallback<void>): void; -Adds a list of applications that are forbidden to run by a given user through the specified device administrator application. This API uses an asynchronous callback to return the result. +Adds the applications that are not allowed to run by the specified user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SET_APP_RUNNING_POLICY @@ -80,7 +82,7 @@ Adds a list of applications that are forbidden to run by a given user through th | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | | appIds | Array<string> | Yes | IDs of the applications to add. | -| userId | number | Yes | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| userId | number | Yes | User ID, which must be greater than or equal to 0.| | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -114,7 +116,7 @@ applicationManager.addDisallowedRunningBundles(wantTemp, appIds, 100, (err) => { addDisallowedRunningBundles(admin: Want, appIds: Array\, userId?: number): Promise<void>; -Adds a list of applications that are forbiddedn to run by the specified user (if **userId** is passed in) or current user (if **userId** is not passed in) through the specified device administrator application. +Adds the applications that are not allowed to run by the current or specified user through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SET_APP_RUNNING_POLICY @@ -128,13 +130,13 @@ Adds a list of applications that are forbiddedn to run by the specified user (if | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | | appIds | Array<string> | Yes | IDs of the applications to add. | -| userId | number | No | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| userId | number | No | User ID, which must be greater than or equal to 0.
- If **userId** is passed in, the applications cannot be run by the specified user.
- If **userId** is not passed in, the applications cannot be run by the current user.| **Return value** | Type | Description | | --------------------- | ------------------------- | -| Promise<void> | Promise that returns no value. An error object is thrown when the applications fail to be added. | +| Promise<void> | Promise that returns no value. If the operation fails, an error object will be thrown. | **Error codes** @@ -165,7 +167,7 @@ applicationManager.addDisallowedRunningBundles(wantTemp, appIds, 100).then(() => removeDisallowedRunningBundles(admin: Want, appIds: Array\, callback: AsyncCallback<void>): void; -Removes a list of applications that are forbiddedn to run by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. +Removes the applications that are not allowed to run by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SET_APP_RUNNING_POLICY @@ -212,7 +214,7 @@ applicationManager.removeDisallowedRunningBundles(wantTemp, appIds, (err) => { removeDisallowedRunningBundles(admin: Want, appIds: Array\, userId: number, callback: AsyncCallback<void>): void; -Removes a list of applications that are forbiddedn to run by the specified user through the specified device administrator application. This API uses an asynchronous callback to return the result. +Removes the applications that are not allowed to run by the specified user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SET_APP_RUNNING_POLICY @@ -226,7 +228,7 @@ Removes a list of applications that are forbiddedn to run by the specified user | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | | appIds | Array<string> | Yes | IDs of the applications to remove. | -| userId | number | Yes | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| userId | number | Yes | User ID, which must be greater than or equal to 0.| | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -260,7 +262,7 @@ applicationManager.removeDisallowedRunningBundles(wantTemp, appIds, 100, (err) = removeDisallowedRunningBundles(admin: Want, appIds: Array\, userId?: number): Promise<void>; -Removes a list of applications that are forbiddedn to run by the specified user (if **userId** is passed in) or current user (if **userId** is not passed in) through the specified device administrator application. This API uses a promise to return the result. +Removes the applications that are not allowed to run by the current or specified user through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SET_APP_RUNNING_POLICY @@ -274,13 +276,13 @@ Removes a list of applications that are forbiddedn to run by the specified user | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | | appIds | Array<string> | Yes | IDs of the applications to remove. | -| userId | number | No | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| userId | number | No | User ID, which must be greater than or equal to 0.
- If **userId** is passed in, the applications cannot be run by the specified user.
- If **userId** is not passed in, the applications cannot be run by the current user.| **Return value** | Type | Description | | --------------------- | ------------------------- | -| Promise<void> | Promise that returns no value. An error object is thrown when the applications fail to be removed. | +| Promise<void> | Promise that returns no value. If the operation fails, an error object will be thrown. | **Error codes** @@ -311,7 +313,7 @@ applicationManager.removeDisallowedRunningBundles(wantTemp, appIds, 100).then(() getDisallowedRunningBundles(admin: Want, callback: AsyncCallback<Array<string>>): void; -Obtains the list of applications that are firbidded to run by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. +Obtains the applications that are not allowed to run by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SET_APP_RUNNING_POLICY @@ -356,7 +358,7 @@ applicationManager.getDisallowedRunningBundles(wantTemp, (err, result) => { getDisallowedRunningBundles(admin: Want, userId: number, callback: AsyncCallback<Array<string>>): void; -Obtains the list of applications that are firbidded to run by the specified user through the specified device administrator application. This API uses an asynchronous callback to return the result. +Obtains the applications that are not allowed to run by the specified user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SET_APP_RUNNING_POLICY @@ -369,7 +371,7 @@ Obtains the list of applications that are firbidded to run by the specified user | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| userId | number | Yes | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| userId | number | Yes | User ID, which must be greater than or equal to 0.| | callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | **Error codes** @@ -402,7 +404,7 @@ applicationManager.getDisallowedRunningBundles(wantTemp, 100, (err, result) => { getDisallowedRunningBundles(admin: Want, userId?: number): Promise<Array<string>>; -Obtains the list of applications that are firbidded to run by the specified user (if **userId** is passed in) or current user (if **userId** is not passed in) through the specified device administrator application. This API uses a promise to return the result. +Obtains the applications that are not allowed to run by the current or specified user through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_MANAGE_SET_APP_RUNNING_POLICY @@ -415,7 +417,7 @@ Obtains the list of applications that are firbidded to run by the specified user | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| -| userId | number | No | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| userId | number | No | User ID, which must be greater than or equal to 0.
- If **userId** is passed in, the applications cannot be run by the specified user.
- If **userId** is not passed in, the applications cannot be run by the current user.| **Return value** diff --git a/en/application-dev/reference/apis/js-apis-enterprise-bundleManager.md b/en/application-dev/reference/apis/js-apis-enterprise-bundleManager.md index 5eea933ded9cbe5cbd3c82aa477c1ff4ea32b923..949307fcf0c0ac3211aa279c99412fe0d53551c4 100644 --- a/en/application-dev/reference/apis/js-apis-enterprise-bundleManager.md +++ b/en/application-dev/reference/apis/js-apis-enterprise-bundleManager.md @@ -6,6 +6,7 @@ The **bundleManager** module provides APIs for bundle management, including addi > > - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. > +> - The APIs of this module can be used only in the stage model. > > - The APIs provided by this module can be called only by a [device administrator application](enterpriseDeviceManagement-overview.md#basic-concepts) that is [enabled](js-apis-enterprise-adminManager.md#adminmanagerenableadmin). @@ -19,7 +20,7 @@ import bundleManager from '@ohos.enterprise.bundleManager'; addAllowedInstallBundles(admin: Want, appIds: Array\, callback: AsyncCallback<void>): void; -Adds a list of bundles that are allowed to be installed by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. +Adds the applications that can be installed by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -32,7 +33,7 @@ Adds a list of bundles that are allowed to be installed by the current user thro | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array<string> | Yes | Bundles to be added. | +| appIds | Array<string> | Yes | IDs of the applications to add. | | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -66,7 +67,7 @@ bundleManager.addAllowedInstallBundles(wantTemp, appIds, (err) => { addAllowedInstallBundles(admin: Want, appIds: Array\, userId: number, callback: AsyncCallback<void>): void; -Adds a list of bundles that are allowed to be installed by the given user (specified by **userId**) through the specified device administrator application. This API uses an asynchronous callback to return the result. +Adds the applications that can be installed by the specified user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -79,8 +80,8 @@ Adds a list of bundles that are allowed to be installed by the given user (speci | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array<string> | Yes | Bundles to be added. | -| userId | number | Yes | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| appIds | Array<string> | Yes | IDs of the applications to add. | +| userId | number | Yes | User ID, which must be greater than or equal to 0.| | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -114,7 +115,7 @@ bundleManager.addAllowedInstallBundles(wantTemp, appIds, 100, (err) => { addAllowedInstallBundles(admin: Want, appIds: Array\, userId?: number): Promise<void>; -Adds a list of bundles that are allowed to be installed by the current user (if **userId** is not passed in) or the given user (if **userId** is passed in) through the specified device administrator application. This API uses a promise to return the result. +Adds the applications that can be installed by the current or specified user through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -127,14 +128,14 @@ Adds a list of bundles that are allowed to be installed by the current user (if | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array<string> | Yes | Bundles to be added. | -| userId | number | No | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| appIds | Array<string> | Yes | IDs of the applications to add. | +| userId | number | No |User ID, which must be greater than or equal to 0.
- If **userId** is passed in, the applications can be installed by the specified user.
- If **userId** is not passed in, the applications can be installed by the current user.| **Return value** | Type | Description | | --------------------- | ------------------------- | -| Promise<void> | Promise that returns no value. If the operation fails, an error object is thrown. | +| Promise<void> | Promise that returns no value. If the operation fails, an error object will be thrown. | **Error codes** @@ -165,7 +166,7 @@ bundleManager.addAllowedInstallBundles(wantTemp, appIds, 100).then(() => { removeAllowedInstallBundles(admin: Want, appIds: Array\, callback: AsyncCallback<void>): void; -Removes a list of bundles that are allowed to be installed by the current user through the specified device administrator application. The bundles removed from the list can no longer be installed. This API uses an asynchronous callback to return the result. +Removes the applications that can be installed by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -178,7 +179,7 @@ Removes a list of bundles that are allowed to be installed by the current user t | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array<string> | Yes | Bundles to be removed. | +| appIds | Array<string> | Yes | IDs of the applications to remove. | | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -212,7 +213,7 @@ bundleManager.removeAllowedInstallBundles(wantTemp, appIds, (err) => { removeAllowedInstallBundles(admin: Want, appIds: Array\, userId: number, callback: AsyncCallback<void>): void; -Removes a list of bundles that are allowed to be installed by the given user (specified by **userId**) through the specified device administrator application. The bundles removed from the list can no longer be installed. This API uses an asynchronous callback to return the result. +Removes the applications that can be installed by the specified user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -225,8 +226,8 @@ Removes a list of bundles that are allowed to be installed by the given user (sp | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array<string> | Yes | Bundles to be removed. | -| userId | number | Yes | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| appIds | Array<string> | Yes | IDs of the applications to remove. | +| userId | number | Yes | User ID, which must be greater than or equal to 0.| | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -260,7 +261,7 @@ bundleManager.removeAllowedInstallBundles(wantTemp, appIds, 100, (err) => { removeAllowedInstallBundles(admin: Want, appIds: Array\, userId?: number): Promise<void>; -Removes a list of bundles that are allowed to be installed by the current user (if **userId** is not passed in) or the given user (if **userId** is passed in) through the specified device administrator application. The bundles removed from the list can no longer be installed. This API uses a promise to return the result. +Removes the applications that can be installed by the current or specified user through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -273,14 +274,14 @@ Removes a list of bundles that are allowed to be installed by the current user ( | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array\<string> | Yes | Bundles to be removed. | -| userId | number | No | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| appIds | Array\<string> | Yes | IDs of the applications to remove. | +| userId | number | No | User ID, which must be greater than or equal to 0.
- If **userId** is passed in, the applications can be installed by the specified user.
- If **userId** is not passed in, the applications can be installed by the current user.| **Return value** | Type | Description | | --------------------- | ------------------------- | -| Promise<void> | Promise that returns no value. If the operation fails, an error object is thrown. | +| Promise<void> | Promise that returns no value. If the operation fails, an error object will be thrown. | **Error codes** @@ -311,7 +312,7 @@ bundleManager.removeAllowedInstallBundles(wantTemp, appIds, 100).then(() => { getAllowedInstallBundles(admin: Want, callback: AsyncCallback<Array<string>>): void; -Obtains the list of bundles that are allowed to be installed by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. +Obtains the applications that can be installed by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -356,7 +357,7 @@ bundleManager.getAllowedInstallBundles(wantTemp, (err, result) => { getAllowedInstallBundles(admin: Want, userId: number, callback: AsyncCallback<Array<string>>): void; -Obtains the list of bundles that are allowed to be installed by the given user (specified by **userId**) through the specified device administrator application. This API uses an asynchronous callback to return the result. +Obtains the applications that can be installed by the specified user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -369,7 +370,7 @@ Obtains the list of bundles that are allowed to be installed by the given user ( | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| userId | number | Yes | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| userId | number | Yes | User ID, which must be greater than or equal to 0.| | callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | **Error codes** @@ -402,7 +403,7 @@ bundleManager.getAllowedInstallBundles(wantTemp, 100, (err, result) => { getAllowedInstallBundles(admin: Want, userId?: number): Promise<Array<string>>; -Obtains the list of bundles that are allowed to be installed by the current user (if **userId** is not passed in) or the given user (if **userId** is passed in) through the specified device administrator application. This API uses a promise to return the result. +Obtains the applications that can be installed by the current or specified user through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -415,7 +416,7 @@ Obtains the list of bundles that are allowed to be installed by the current user | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| -| userId | number | No | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| userId | number | No | User ID, which must be greater than or equal to 0.
- If **userId** is passed in, the applications can be installed by the specified user.
- If **userId** is not passed in, the applications can be installed by the current user.| **Return value** @@ -451,7 +452,7 @@ bundleManager.getAllowedInstallBundles(wantTemp, 100).then((result) => { addDisallowedInstallBundles(admin: Want, appIds: Array\, callback: AsyncCallback<void>): void; -Adds a list of bundles that are not allowed to be installed by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. +Adds the applications that cannot be installed by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -464,7 +465,7 @@ Adds a list of bundles that are not allowed to be installed by the current user | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array<string> | Yes | Bundles to be added. | +| appIds | Array<string> | Yes | IDs of the applications to add. | | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -498,7 +499,7 @@ bundleManager.addDisallowedInstallBundles(wantTemp, appIds, (err) => { addDisallowedInstallBundles(admin: Want, appIds: Array\, userId: number, callback: AsyncCallback<void>): void; -Adds a list of bundles that are not allowed to be installed by the given user (specified by **userId**) through the specified device administrator application. This API uses an asynchronous callback to return the result. +Adds the applications that cannot be installed by the specified user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -511,8 +512,8 @@ Adds a list of bundles that are not allowed to be installed by the given user (s | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array<string> | Yes | Bundles to be added. | -| userId | number | Yes | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| appIds | Array<string> | Yes | IDs of the applications to add. | +| userId | number | Yes | User ID, which must be greater than or equal to 0.| | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -546,7 +547,7 @@ bundleManager.addDisallowedInstallBundles(wantTemp, appIds, 100, (err) => { addDisallowedInstallBundles(admin: Want, appIds: Array\, userId?: number): Promise<void>; -Adds a list of bundles that are not allowed to be installed by the current user (if **userId** is not passed in) or the given user (if **userId** is passed in) through the specified device administrator application. This API uses a promise to return the result. +Adds the applications that cannot be installed by the current or specified user through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -559,14 +560,14 @@ Adds a list of bundles that are not allowed to be installed by the current user | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array<string> | Yes | Bundles to be added. | -| userId | number | No | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| appIds | Array<string> | Yes | IDs of the applications to add. | +| userId | number | No | User ID, which must be greater than or equal to 0.
- If **userId** is passed in, the applications cannot be installed by the specified user.
- If **userId** is not passed in, the applications cannot be installed by the current user.| **Return value** | Type | Description | | --------------------- | ------------------------- | -| Promise<void> | Promise that returns no value. If the operation fails, an error object is thrown. | +| Promise<void> | Promise that returns no value. If the operation fails, an error object will be thrown. | **Error codes** @@ -597,7 +598,7 @@ bundleManager.addDisallowedInstallBundles(wantTemp, appIds, 100).then(() => { removeDisallowedInstallBundles(admin: Want, appIds: Array\, callback: AsyncCallback<void>): void; -Removes a list of bundles that are not allowed to be installed by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. +Removes the applications that cannot be installed by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -610,7 +611,7 @@ Removes a list of bundles that are not allowed to be installed by the current us | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array<string> | Yes | Bundles to be removed. | +| appIds | Array<string> | Yes | IDs of the applications to remove. | | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -642,9 +643,9 @@ bundleManager.removeDisallowedInstallBundles(wantTemp, appIds, (err) => { ## bundleManager.removeDisallowedInstallBundles -removeAllowedInstallBundles(admin: Want, appIds: Array\, userId: number, callback: AsyncCallback<void>): void; +removeDisallowedInstallBundles(admin: Want, appIds: Array\, userId: number, callback: AsyncCallback<void>): void; -Removes a list of bundles that are not allowed to be installed by the given user (specified by **userId**) through the specified device administrator application. This API uses an asynchronous callback to return the result. +Removes the applications that cannot be installed by the specified user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -657,8 +658,8 @@ Removes a list of bundles that are not allowed to be installed by the given user | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array<string> | Yes | Bundles to be added. | -| userId | number | Yes | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| appIds | Array<string> | Yes | IDs of the applications to remove. | +| userId | number | Yes | User ID, which must be greater than or equal to 0.| | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -692,7 +693,7 @@ bundleManager.removeDisallowedInstallBundles(wantTemp, appIds, 100, (err) => { removeDisallowedInstallBundles(admin: Want, appIds: Array\, userId?: number): Promise<void>; -Removes a list of bundles that are not allowed to be installed by the current user (if **userId** is not passed in) or the given user (if **userId** is passed in) through the specified device administrator application. This API uses a promise to return the result. +Removes the applications that cannot be installed by the current or specified user through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -705,14 +706,14 @@ Removes a list of bundles that are not allowed to be installed by the current us | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array\<string> | Yes | Bundles to be removed. | -| userId | number | No | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| appIds | Array\<string> | Yes | IDs of the applications to remove. | +| userId | number | No | User ID, which must be greater than or equal to 0.
- If **userId** is passed in, the applications cannot be installed by the specified user.
- If **userId** is not passed in, the applications cannot be installed by the current user.| **Return value** | Type | Description | | --------------------- | ------------------------- | -| Promise<void> | Promise that returns no value. If the operation fails, an error object is thrown. | +| Promise<void> | Promise that returns no value. If the operation fails, an error object will be thrown. | **Error codes** @@ -743,7 +744,7 @@ bundleManager.removeDisallowedInstallBundles(wantTemp, appIds, 100).then(() => { getDisallowedInstallBundles(admin: Want, callback: AsyncCallback<Array<string>>): void; -Obtains the list of bundles that are not allowed to be installed by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. +Obtains the applications that cannot be installed by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -788,7 +789,7 @@ bundleManager.getDisallowedInstallBundles(wantTemp, (err, result) => { getDisallowedInstallBundles(admin: Want, userId: number, callback: AsyncCallback<Array<string>>): void; -Obtains the list of bundles that are not allowed to be installed by the given user (specified by **userId**) through the specified device administrator application. This API uses an asynchronous callback to return the result. +Obtains the applications that cannot be installed by the specified user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -801,7 +802,7 @@ Obtains the list of bundles that are not allowed to be installed by the given us | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| userId | number | Yes | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| userId | number | Yes | User ID, which must be greater than or equal to 0.| | callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | **Error codes** @@ -834,7 +835,7 @@ bundleManager.getDisallowedInstallBundles(wantTemp, 100, (err, result) => { getDisallowedInstallBundles(admin: Want, userId?: number): Promise<Array<string>>; -Obtains the list of bundles that are not allowed to be installed by the current user (if **userId** is not passed in) or the given user (if **userId** is passed in) through the specified device administrator application. This API uses a promise to return the result. +Obtains the applications that cannot be installed by the current or specified user through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -847,7 +848,7 @@ Obtains the list of bundles that are not allowed to be installed by the current | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| -| userId | number | No | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| userId | number | No | User ID, which must be greater than or equal to 0.
- If **userId** is passed in, the applications cannot be installed by the specified user.
- If **userId** is not passed in, the applications cannot be installed by the current user.| **Return value** @@ -883,7 +884,7 @@ bundleManager.getDisallowedInstallBundles(wantTemp, 100).then((result) => { addDisallowedUninstallBundles(admin: Want, appIds: Array\, callback: AsyncCallback<void>): void -Adds a list of bundles that are not allowed to be uninstalled by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. +Adds the applications that cannot be uninstalled by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -896,7 +897,7 @@ Adds a list of bundles that are not allowed to be uninstalled by the current use | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array<string> | Yes | Bundles to be added. | +| appIds | Array<string> | Yes | IDs of the applications to add. | | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -930,7 +931,7 @@ bundleManager.addDisallowedUninstallBundles(wantTemp, appIds, (err) => { addDisallowedUninstallBundles(admin: Want, appIds: Array\, userId: number, callback: AsyncCallback<void>): void -Adds a list of bundles that are not allowed to be uninstalled by the given user (specified by **userId**) through the specified device administrator application. This API uses an asynchronous callback to return the result. +Adds the applications that cannot be uninstalled by the specified user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -943,8 +944,8 @@ Adds a list of bundles that are not allowed to be uninstalled by the given user | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array<string> | Yes | Bundles to be added. | -| userId | number | Yes | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| appIds | Array<string> | Yes | IDs of the applications to add. | +| userId | number | Yes | User ID, which must be greater than or equal to 0.| | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -978,7 +979,7 @@ bundleManager.addDisallowedUninstallBundles(wantTemp, appIds, 100, (err) => { addDisallowedUninstallBundles(admin: Want, appIds: Array\, userId?: number): Promise<void> -Adds a list of bundles that are not allowed to be uninstalled by the current user (if **userId** is not passed in) or the given user (if **userId** is passed in) through the specified device administrator application. This API uses a promise to return the result. +Adds the applications that cannot be uninstalled by the current or specified user through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -991,14 +992,14 @@ Adds a list of bundles that are not allowed to be uninstalled by the current use | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array<string> | Yes | Bundles to be added. | -| userId | number | No | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| appIds | Array<string> | Yes | IDs of the applications to add. | +| userId | number | No | User ID, which must be greater than or equal to 0.
- If **userId** is passed in, the applications cannot be uninstalled by the specified user.
- If **userId** is not passed in, the applications cannot be uninstalled by the current user.| **Return value** | Type | Description | | --------------------- | ------------------------- | -| Promise<void> | Promise that returns no value. If the operation fails, an error object is thrown. | +| Promise<void> | Promise that returns no value. If the operation fails, an error object will be thrown. | **Error codes** @@ -1029,7 +1030,7 @@ bundleManager.addDisallowedUninstallBundles(wantTemp, appIds, 100).then(() => { removeDisallowedUninstallBundles(admin: Want, appIds: Array\, callback: AsyncCallback<void>): void -Removes a list of bundles that are not allowed to be uninstalled by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. +Removes the applications that cannot be uninstalled by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -1042,7 +1043,7 @@ Removes a list of bundles that are not allowed to be uninstalled by the current | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array<string> | Yes | Bundles to be added. | +| appIds | Array<string> | Yes | IDs of the applications to remove. | | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -1076,7 +1077,7 @@ bundleManager.removeDisallowedUninstallBundles(wantTemp, appIds, (err) => { removeDisallowedUninstallBundles(admin: Want, appIds: Array\, userId: number, callback: AsyncCallback<void>): void -Removes a list of bundles that are not allowed to be uninstalled by the given user (specified by **userId**) through the specified device administrator application. This API uses an asynchronous callback to return the result. +Removes the applications that cannot be uninstalled by the specified user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -1089,8 +1090,8 @@ Removes a list of bundles that are not allowed to be uninstalled by the given us | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array<string> | Yes | Bundles to be removed. | -| userId | number | Yes | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| appIds | Array<string> | Yes | IDs of the applications to remove. | +| userId | number | Yes | User ID, which must be greater than or equal to 0.| | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -1124,7 +1125,7 @@ bundleManager.removeDisallowedUninstallBundles(wantTemp, appIds, 100, (err) => { removeDisallowedUninstallBundles(admin: Want, appIds: Array\, userId?: number): Promise<void> -Removes a list of bundles that are not allowed to be uninstalled by the current user (if **userId** is not passed in) or the given user (if **userId** is passed in) through the specified device administrator application. This API uses a promise to return the result. +Removes the applications that cannot be uninstalled by the current or specified user through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -1137,14 +1138,14 @@ Removes a list of bundles that are not allowed to be uninstalled by the current | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| appIds | Array\<string> | Yes | Bundles to be removed. | -| userId | number | No | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| appIds | Array\<string> | Yes | IDs of the applications to remove. | +| userId | number | No | User ID, which must be greater than or equal to 0.
- If **userId** is passed in, the applications cannot be uninstalled by the specified user.
- If **userId** is not passed in, the applications cannot be uninstalled by the current user.| **Return value** | Type | Description | | --------------------- | ------------------------- | -| Promise<void> | Promise that returns no value. If the operation fails, an error object is thrown. | +| Promise<void> | Promise that returns no value. If the operation fails, an error object will be thrown. | **Error codes** @@ -1175,7 +1176,7 @@ bundleManager.removeDisallowedUninstallBundles(wantTemp, appIds, 100).then(() => getDisallowedUninstallBundles(admin: Want, callback: AsyncCallback<Array<string>>): void -Obtains the list of bundles that are not allowed to be uninstalled by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. +Obtains the applications that cannot be uninstalled by the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -1220,7 +1221,7 @@ bundleManager.getDisallowedUninstallBundles(wantTemp, (err, result) => { getDisallowedUninstallBundles(admin: Want, userId: number, callback: AsyncCallback<Array<string>>): void -Obtains the list of bundles that are not allowed to be uninstalled by the given user (specified by **userId**) through the specified device administrator application. This API uses an asynchronous callback to return the result. +Obtains the applications that cannot be uninstalled by the specified user through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -1233,7 +1234,7 @@ Obtains the list of bundles that are not allowed to be uninstalled by the given | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| userId | number | Yes | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| userId | number | Yes | User ID, which must be greater than or equal to 0.| | callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | **Error codes** @@ -1266,7 +1267,7 @@ bundleManager.getDisallowedUninstallBundles(wantTemp, 100, (err, result) => { getDisallowedUninstallBundles(admin: Want, userId?: number): Promise<Array<string>> -Obtains the list of bundles that are not allowed to be uninstalled by the current user (if **userId** is not passed in) or the given user (if **userId** is passed in) through the specified device administrator application. This API uses a promise to return the result. +Obtains the applications that cannot be uninstalled by the current or specified user through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_BUNDLE_INSTALL_POLICY @@ -1279,7 +1280,7 @@ Obtains the list of bundles that are not allowed to be uninstalled by the curren | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| -| userId | number | No | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| userId | number | No | User ID, which must be greater than or equal to 0.
- If **userId** is passed in, the applications cannot be uninstalled by the specified user.
- If **userId** is not passed in, the applications cannot be uninstalled by the current user.| **Return value** @@ -1315,7 +1316,7 @@ bundleManager.getDisallowedUninstallBundles(wantTemp, 100).then((result) => { uninstall(admin: Want, bundleName: string, callback: AsyncCallback<void>): void -Uninstalls the given bundle of the current user without retaining the bundle data through the specified device administrator application. This API uses an asynchronous callback to return the result. +Uninstalls an application of the current user without retaining the bundle data through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_INSTALL_BUNDLE @@ -1328,7 +1329,7 @@ Uninstalls the given bundle of the current user without retaining the bundle dat | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| bundleName | string | Yes | Bundle name.| +| bundleName | string | Yes | Name of the bundle to uninstall.| | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | **Error codes** @@ -1360,7 +1361,7 @@ bundleManager.uninstall(wantTemp, 'bundleName', (err) => { uninstall(admin: Want, bundleName: string, userId: number, callback: AsyncCallback<void>): void -Uninstalls the given bundle of the user specified by **userId** without retaining the bundle data through the specified device administrator application. This API uses an asynchronous callback to return the result. +Uninstalls an application of the specified user without retaining the bundle data through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_INSTALL_BUNDLE @@ -1373,8 +1374,8 @@ Uninstalls the given bundle of the user specified by **userId** without retainin | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| bundleName | string | Yes | Bundle name.| -| userId | number | Yes | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| bundleName | string | Yes | Name of the bundle to uninstall.| +| userId | number | Yes | User ID, which must be greater than or equal to 0.| | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | **Error codes** @@ -1406,7 +1407,7 @@ bundleManager.uninstall(wantTemp, 'bundleName', 100, (err) => { uninstall(admin: Want, bundleName: string, isKeepData: boolean, callback: AsyncCallback<void>): void -Uninstalls the given bundle of the current user through the specified device administrator application. This API uses an asynchronous callback to return the result. If **isKeepData** is **false**, the bundle data is not retained. +Uninstalls an application of the current user through the specified device administrator application. The **isKeepData** parameter specifies whether to retain the bundle data. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_INSTALL_BUNDLE @@ -1419,7 +1420,7 @@ Uninstalls the given bundle of the current user through the specified device adm | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| bundleName | string | Yes | Bundle name.| +| bundleName | string | Yes | Name of the bundle to uninstall.| | isKeepData | boolean | Yes | Whether to retain the bundle data. The value **true** means to retain the bundle data; the value **false** means the opposite.| | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | @@ -1452,7 +1453,7 @@ bundleManager.uninstall(wantTemp, 'bundleName', true, (err) => { uninstall(admin: Want, bundleName: string, userId: number, isKeepData: boolean, callback: AsyncCallback<void>): void -Uninstalls the given bundle of the user specified by **userId** through the specified device administrator application. This API uses an asynchronous callback to return the result. If **isKeepData** is **false**, the bundle data is not retained. +Uninstalls an application of the specified user through the specified device administrator application. The **isKeepData** parameter specifies whether to retain the bundle data. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_INSTALL_BUNDLE @@ -1465,8 +1466,8 @@ Uninstalls the given bundle of the user specified by **userId** through the spec | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| bundleName | string | Yes | Bundle name.| -| userId | number | Yes | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| bundleName | string | Yes | Name of the bundle to uninstall.| +| userId | number | Yes | User ID, which must be greater than or equal to 0.| | isKeepData | boolean | Yes | Whether to retain the bundle data. The value **true** means to retain the bundle data; the value **false** means the opposite.| | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | @@ -1499,7 +1500,7 @@ bundleManager.uninstall(wantTemp, 'bundleName', 100, true, (err) => { uninstall(admin: Want, bundleName: string, userId?: number, isKeepData?: boolean): Promise<void> -Uninstalls the given bundle of the current user (if **userId** is not passed in) or the given user (if **userId** is passed in) through the specified device administrator application. This API uses a promise to return the result. If **isKeepData** is not passed in, the default value **false** is used, which means the bundle data will not be retained. +Uninstalls an application of the current or specified user through the specified device administrator application. The **isKeepData** parameter specifies whether to retain the bundle data. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_INSTALL_BUNDLE @@ -1512,8 +1513,8 @@ Uninstalls the given bundle of the current user (if **userId** is not passed in) | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| -| bundleName | string | Yes | Bundle name.| -| userId | number | No | User ID. The default value is the user ID of the caller. The user ID must be greater than or equal to **0**.| +| bundleName | string | Yes | Name of the bundle to uninstall.| +| userId | number | No | User ID, which must be greater than or equal to 0.
- If **userId** is passed in, the application of the specified user is uninstalled.
- If **userId** is not passed in, the application of the current user is uninstalled.| | isKeepData | boolean | No | Whether to retain the bundle data. The value **true** means to retain the bundle data; the value **false** means the opposite.| **Return value** diff --git a/en/application-dev/reference/apis/js-apis-enterprise-dateTimeManager.md b/en/application-dev/reference/apis/js-apis-enterprise-dateTimeManager.md index 68d3434970c426586a344a76d16bc3516a26f628..667455669f3e1049050f16c2bddadbb3089ec3df 100644 --- a/en/application-dev/reference/apis/js-apis-enterprise-dateTimeManager.md +++ b/en/application-dev/reference/apis/js-apis-enterprise-dateTimeManager.md @@ -6,6 +6,8 @@ The **dateTimeManager** module provides APIs for system time management. > > - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > +> - The APIs of this module can be used only in the stage model. +> > - The APIs provided by this module can be called only by a [device administrator application](enterpriseDeviceManagement-overview.md#basic-concepts) that is [enabled](js-apis-enterprise-adminManager.md#adminmanagerenableadmin). ## Modules to Import @@ -113,7 +115,7 @@ dateTimeManager.setDateTime(wantTemp, 1526003846000).then(() => { disallowModifyDateTime(admin: Want, disallow: boolean, callback: AsyncCallback\): void -Disallows modification of the system time through the specified device administrator application. This API uses an asynchronous callback to return the result. +Forbids the specified device administrator application to modify the system time. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_DATETIME @@ -126,7 +128,7 @@ Disallows modification of the system time through the specified device administr | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| -| disallow | boolean | Yes| Whether to disable modification of the system time. The value **true** means to disable modification of the system time, and **false** means the opposite.| +| disallow | boolean | Yes| Whether to disallow modification of the system time. The value **true** means to disallow modification of the system time, and **false** means the opposite.| | callback | AsyncCallback\ | Yes| Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -159,7 +161,7 @@ dateTimeManager.disallowModifyDateTime(wantTemp, true, (err) => { disallowModifyDateTime(admin: Want, disallow: boolean): Promise\ -Disallows modification of the system time through the specified device administrator application. This API uses a promise to return the result. +Forbids the specified device administrator application to modify the system time. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_DATETIME @@ -172,13 +174,13 @@ Disallows modification of the system time through the specified device administr | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| -| disallow | boolean | Yes| Whether to disable modification of the system time. The value **true** means to disable modification of the system time, and **false** means the opposite.| +| disallow | boolean | Yes| Whether to disallow modification of the system time. The value **true** means to disallow modification of the system time, and **false** means the opposite.| **Return value** | Type | Description | | ----- | ----------------------------------- | -| Promise\ | Promise that returns no value. An error object is thrown if the operation fails.| +| Promise\ | Promise that returns no value. If the operation fails, an error object will be thrown.| **Error codes** @@ -208,7 +210,7 @@ dateTimeManager.disallowModifyDateTime(wantTemp, true).then(() => { isModifyDateTimeDisallowed(admin: Want, callback: AsyncCallback\): void -Checks whether the modification of the system time is disallowed through the specified device administrator application. This API uses an asynchronous callback to return the result. +Checks whether the system time modification is disallowed through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_DATETIME @@ -221,7 +223,7 @@ Checks whether the modification of the system time is disallowed through the spe | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| -| callback | AsyncCallback\ | Yes| Callback invoked to return the result. The value **true** means that modification of the system time is disallowed, and **false** means the opposite.| +| callback | AsyncCallback\ | Yes| Callback invoked to return the result. The value **true** means the system time modification is disallowed, and **false** means the opposite.| **Error codes** @@ -253,7 +255,7 @@ dateTimeManager.isModifyDateTimeDisallowed(wantTemp, (err, result) => { isModifyDateTimeDisallowed(admin: Want): Promise\ -Checks whether the modification of the system time is disallowed through the specified device administrator application. This API uses a promise to return the result. +Checks whether the system time modification is disallowed through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_DATETIME @@ -271,7 +273,7 @@ Checks whether the modification of the system time is disallowed through the spe | Type | Description | | ----- | ----------------------------------- | -| Promise\ | Promise used to return the result. The value **true** means that modification of the system time is disallowed, and **false** means the opposite.| +| Promise\ | Promise used to return the result. The value **true** means the system time modification is disallowed, and **false** means the opposite.| **Error codes** diff --git a/en/application-dev/reference/apis/js-apis-enterprise-deviceControl.md b/en/application-dev/reference/apis/js-apis-enterprise-deviceControl.md index 86b7381381b5710e4b4acc046e545f37b10e1c96..9bae24e33a64d1539300474cdc9839ea1fe22cc9 100644 --- a/en/application-dev/reference/apis/js-apis-enterprise-deviceControl.md +++ b/en/application-dev/reference/apis/js-apis-enterprise-deviceControl.md @@ -1,11 +1,12 @@ # @ohos.enterprise.deviceControl (Device Control) -The **deviceControl** module provides APIs for device control, which can be called only by device administrator applications. +The **deviceControl** module provides APIs for device control. > **NOTE** -> +> > - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. > +> - The APIs of this module can be used only in the stage model. > > - The APIs provided by this module can be called only by a [device administrator application](enterpriseDeviceManagement-overview.md#basic-concepts) that is [enabled](js-apis-enterprise-adminManager.md#adminmanagerenableadmin). @@ -19,7 +20,7 @@ import deviceControl from '@ohos.enterprise.deviceControl' resetFactory(admin: Want, callback: AsyncCallback\): void -Restores factory settings through the specified device administrator application. This API uses an asynchronous callback to return the result. +Restores device factory settings through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_RESET_DEVICE @@ -31,7 +32,7 @@ Restores factory settings through the specified device administrator application | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | -| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application used to restore the factory settings.| +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| | callback | AsyncCallback\ | Yes| Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -64,7 +65,7 @@ deviceControl.resetFactory(wantTemp, (err) => { resetFactory(admin: Want): Promise\ -Restores factory settings. This API uses a promise to return the result. +Restores device factory settings through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_RESET_DEVICE @@ -76,7 +77,7 @@ Restores factory settings. This API uses a promise to return the result. | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | -| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application used to restore the factory settings.| +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| **Return value** diff --git a/en/application-dev/reference/apis/js-apis-enterprise-deviceInfo.md b/en/application-dev/reference/apis/js-apis-enterprise-deviceInfo.md index e859dd3af41f7cb97e7a204b80b2d0d98f4af9c3..c642ae6a5aaef9fc0d06356ce1f61850dc4ef74e 100644 --- a/en/application-dev/reference/apis/js-apis-enterprise-deviceInfo.md +++ b/en/application-dev/reference/apis/js-apis-enterprise-deviceInfo.md @@ -6,6 +6,8 @@ The **deviceInfo** module provides APIs for enterprise device information manage > > - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. > +> - The APIs of this module can be used only in the stage model. +> > - The APIs provided by this module can be called only by a [device administrator application](enterpriseDeviceManagement-overview.md#basic-concepts) that is [enabled](js-apis-enterprise-adminManager.md#adminmanagerenableadmin). ## Modules to Import @@ -111,7 +113,7 @@ deviceInfo.getDeviceSerial(wantTemp).then((result) => { getDisplayVersion(admin: Want, callback: AsyncCallback<string>): void; -Obtains the device version number through the specified device administrator application. This API uses an asynchronous callback to return the result. +Obtains the device version through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_DEVICE_INFO @@ -124,7 +126,7 @@ Obtains the device version number through the specified device administrator app | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| callback | AsyncCallback<string> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null** and **data** is the device version number obtained. If the operation fails, **err** is an error object. | +| callback | AsyncCallback<string> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null** and **data** is the device version obtained. If the operation fails, **err** is an error object. | **Error codes** @@ -156,7 +158,7 @@ deviceInfo.getDisplayVersion(wantTemp, (err, result) => { getDisplayVersion(admin: Want): Promise<string> -Obtains the device version number through the specified device administrator application. This API uses a promise to return the result. +Obtains the device version through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_DEVICE_INFO @@ -174,7 +176,7 @@ Obtains the device version number through the specified device administrator app | Type | Description | | --------------------- | ------------------------- | -| Promise<string> | Promise used to return the device version number.| +| Promise<string> | Promise used to return the device version obtained.| **Error codes** diff --git a/en/application-dev/reference/apis/js-apis-enterprise-deviceSettings.md b/en/application-dev/reference/apis/js-apis-enterprise-deviceSettings.md index 132c1d44b5e5c24150592c8bfabf73b61043df96..3c7a4030f2e76b4d972d77ea281738eb028986ef 100644 --- a/en/application-dev/reference/apis/js-apis-enterprise-deviceSettings.md +++ b/en/application-dev/reference/apis/js-apis-enterprise-deviceSettings.md @@ -6,7 +6,9 @@ The **deviceSettings** module provides APIs for setting enterprise devices, incl > > The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. > -> The APIs provided by this module apply only to the [device administrator applications](enterpriseDeviceManagement-overview.md#basic-concepts). Before calling the APIs, you must enable the device administrator application(js-apis-enterprise-adminManager.md#adminmanagerenableadmin). +> The APIs of this module can be used only in the stage model. +> +> The APIs provided by this module can be called only by a [device administrator application](enterpriseDeviceManagement-overview.md#basic-concepts) that is [enabled](js-apis-enterprise-adminManager.md#adminmanagerenableadmin). ## Modules to Import @@ -18,7 +20,7 @@ import deviceSettings from '@ohos.enterprise.deviceSettings'; getScreenOffTime(admin: Want, callback: AsyncCallback<number>): void -Obtains the screen-off time of a device through the specified device administrator application. This API uses an asynchronous callback to return the result. +Obtains the device screen-off time through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_SETTINGS @@ -63,7 +65,7 @@ deviceSettings.getScreenOffTime(wantTemp, (err, result) => { getScreenOffTime(admin: Want): Promise<number> -Obtains the screen-off time of a device through the specified device administrator application. This API uses a promise to return the result. +Obtains the device screen-off time through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_SETTINGS @@ -106,3 +108,232 @@ deviceSettings.getScreenOffTime(wantTemp).then((result) => { console.error(`Failed to get screen off time. Code: ${err.code}, message: ${err.message}`); }); ``` + +## deviceSettings.installUserCertificate + +installUserCertificate(admin: Want, certificate: CertBlob, callback: AsyncCallback<string>): void + +Installs a user certificate through the specified device administrator application. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE + +**System capability**: SystemCapability.Customization.EnterpriseDeviceManager + +**System API**: This is a system API. + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ------------------------------- | +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | +| certificate | [CertBlob](#certblob) | Yes | Information about the certificate to install. | +| callback | AsyncCallback<string> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | + +**Error codes** + +For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). + +| ID| Error Message | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | the application is not an administrator of the device. | +| 9200002 | the administrator application does not have permission to manage the device. | +| 9201001 | manage certificate failed | + +**Example** + +```js +let wantTemp = { + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', +}; +var certFileArray: Uint8Array; +// The variable context needs to be initialized in MainAbility's onCreate callback function +// test.cer needs to be placed in the rawfile directory +await globalThis.context.resourceManager.getRawFileContent("test.cer") + .then(value => { + certFileArray = value + }) + .catch(error => { + console.error(`Failed to get row file content. message: ${error.message}`); + return + }); +new Promise((resolve, reject) => { + deviceSettings.installUserCertificate(wantTemp, {inData: certFileArray, alias: "cert_alias_xts"}, (err, result) => { + if (err) { + console.error(`Failed to install user certificate. Code: ${err.code}, message: ${err.message}`); + } else{ + console.info(`Succeeded in installing user certificate, result : ${JSON.stringify(result)}`); + } + }); +}); +``` + +## deviceSettings.installUserCertificate + +installUserCertificate(admin: Want, certificate: CertBlob): Promise<string> + +Installs a user certificate through the specified device administrator application. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE + +**System capability**: SystemCapability.Customization.EnterpriseDeviceManager + +**System API**: This is a system API. + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----- | ----------------------------------- | ---- | ------- | +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| +| certificate | [CertBlob](#certblob) | Yes | Information about the certificate to install. | + +**Return value** + +| Type | Description | +| --------------------- | ------------------------- | +| Promise<string> | Promise used to return the URI of the installed certificate. This URI can be used to uninstall the certificate.| + +**Error codes** + +For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). + +| ID| Error Message | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | the application is not an administrator of the device. | +| 9200002 | the administrator application does not have permission to manage the device. | +| 9201001 | manage certificate failed | + +**Example** + +```js +let wantTemp = { + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', +}; +var certFileArray: Uint8Array +// The variable context needs to be initialized in MainAbility's onCreate callback function +// test.cer needs to be placed in the rawfile directory +await globalThis.context.resourceManager.getRawFileContent("test.cer") + .then(data => { + certFileArray = data + }).catch(error => { + console.log('getRawFileContent error' + error) + return + }) +deviceSettings.installUserCertificate(wantTemp, { inData: certFileArray, alias: "cert_alias_xts" }) + .then((result) => { + console.info(`Succeeded in installing user certificate, result : ${JSON.stringify(result)}`); + }).catch(err => { + console.error(`Failed to install user certificate. Code: ${err.code}, message: ${err.message}`); + }) +``` + +## CertBlob + +Represents the certificate information. + +**System capability**: SystemCapability.Customization.EnterpriseDeviceManager + +**System API**: This is a system API. + +| Name | Type | Mandatory| Description | +| ----------- | --------| ----- | ------------------------------- | +| inData | Uint8Array | Yes| Binary content of the certificate.| +| alias | string | Yes| Certificate alias.| + +## deviceSettings.uninstallUserCertificate + +uninstallUserCertificate(admin: Want, certUri: string, callback: AsyncCallback<void>): void + +Uninstalls a user certificate through the specified device administrator application. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE + +**System capability**: SystemCapability.Customization.EnterpriseDeviceManager + +**System API**: This is a system API. + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ------------------------------- | +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | +| certUri | string | Yes | Certificate URI, which is returned by **installUserCertificate()**. | +| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | + +**Error codes** + +For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). + +| ID| Error Message | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | the application is not an administrator of the device. | +| 9200002 | the administrator application does not have permission to manage the device. | +| 9201001 | manage certificate failed | + +**Example** + +```js +let wantTemp = { + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', +}; +let aliasStr = "certName" +deviceSettings.uninstallUserCertificate(wantTemp, aliasStr, (err) => { + if (err) { + console.error(`Failed to uninstall user certificate. Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in uninstalling user certificate`); +}); +``` + +## deviceSettings.uninstallUserCertificate + +uninstallUserCertificate(admin: Want, certUri: string): Promise<void> + +Uninstalls a user certificate through the specified device administrator application. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_CERTIFICATE + +**System capability**: SystemCapability.Customization.EnterpriseDeviceManager + +**System API**: This is a system API. + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----- | ----------------------------------- | ---- | ------- | +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| +| certUri | string | Yes | Certificate URI, which is returned by **installUserCertificate()**. | + +**Return value** + +| Type | Description | +| --------------------- | ------------------------- | +| Promise<void> | Promise that returns no value. An error object will be thrown if the operation fails.| + +**Error codes** + +For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). + +| ID| Error Message | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | the application is not an administrator of the device. | +| 9200002 | the administrator application does not have permission to manage the device. | +| 9201001 | manage certificate failed | + +**Example** + +```js +let wantTemp = { + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', +}; +let aliasStr = "certName" +deviceSettings.uninstallUserCertificate(wantTemp, aliasStr).then(() => { + console.info(`Succeeded in uninstalling user certificate`); +}).catch((err) => { + console.error(`Failed to uninstall user certificate. Code is ${err.code}, message is ${err.message}`); +}); +``` diff --git a/en/application-dev/reference/apis/js-apis-enterprise-networkManager.md b/en/application-dev/reference/apis/js-apis-enterprise-networkManager.md index 5b85d76cec32c66bab620e377f669a473e93ac75..8d4ed0a25c81f5fed9d9f17b33cfcf92546f7e1a 100644 --- a/en/application-dev/reference/apis/js-apis-enterprise-networkManager.md +++ b/en/application-dev/reference/apis/js-apis-enterprise-networkManager.md @@ -6,6 +6,8 @@ The **networkManager** module provides APIs for network management of enterprise > > The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. > +> The APIs of this module can be used only in the stage model. +> > The APIs provided by this module can be called only by a [device administrator application](enterpriseDeviceManagement-overview.md#basic-concepts) that is [enabled](js-apis-enterprise-adminManager.md#adminmanagerenableadmin). ## Modules to Import @@ -18,7 +20,7 @@ import networkManager from '@ohos.enterprise.networkManager'; getAllNetworkInterfaces(admin: Want, callback: AsyncCallback<Array<string>>): void -Obtains all active network interfaces through the specified device administrator application. This API uses an asynchronous callback to return the result. +Obtains all activated network ports through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_NETWORK_INFO @@ -31,7 +33,7 @@ Obtains all active network interfaces through the specified device administrator | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null** and **data** is an array of network interfaces obtained. If the operation fails, **err** is an error object. | +| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null** and **data** is an array of network ports obtained. If the operation fails, **err** is an error object. | **Error codes** @@ -63,7 +65,7 @@ networkManager.getAllNetworkInterfaces(wantTemp, (err, result) => { getAllNetworkInterfaces(admin: Want): Promise<Array<string>> -Obtains all active network interfaces through the specified device administrator application. This API uses a promise to return the result. +Obtains all activated network ports through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_NETWORK_INFO @@ -81,7 +83,7 @@ Obtains all active network interfaces through the specified device administrator | Type | Description | | --------------------- | ------------------------- | -| Promise<Array<string>> | Promise used to return an array of network interfaces obtained. | +| Promise<Array<string>> | Promise used to return an array of network ports obtained. | **Error codes** @@ -111,7 +113,7 @@ networkManager.getAllNetworkInterfaces(wantTemp).then((result) => { getIpAddress(admin: Want, networkInterface: string, callback: AsyncCallback<string>): void -Obtains the device IP address based on the given network interface through the specified device administrator application. This API uses an asynchronous callback to return the result. +Obtains the device IP address based on the network port through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_NETWORK_INFO @@ -124,7 +126,7 @@ Obtains the device IP address based on the given network interface through the s | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| networkInterface | string | Yes | Network interface. | +| networkInterface | string | Yes | Network port. | | callback | AsyncCallback<string> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null** and **data** is the IP address obtained. If the operation fails, **err** is an error object. | **Error codes** @@ -157,7 +159,7 @@ networkManager.getIpAddress(wantTemp, 'eth0', (err, result) => { getIpAddress(admin: Want, networkInterface: string): Promise<string> -Obtains the device IP address based on the given network interface through the specified device administrator application. This API uses a promise to return the result. +Obtains the device IP address based on the network port through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_NETWORK_INFO @@ -170,7 +172,7 @@ Obtains the device IP address based on the given network interface through the s | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| -| networkInterface | string | Yes | Network interface. | +| networkInterface | string | Yes | Network port. | **Return value** @@ -206,7 +208,7 @@ networkManager.getIpAddress(wantTemp, 'eth0').then((result) => { getMac(admin: Want, networkInterface: string, callback: AsyncCallback<string>): void -Obtains the device MAC address based on the given network interface through the specified device administrator application. This API uses an asynchronous callback to return the result. +Obtains the device MAC address based on the network port through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_NETWORK_INFO @@ -219,7 +221,7 @@ Obtains the device MAC address based on the given network interface through the | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| networkInterface | string | Yes | Network interface. | +| networkInterface | string | Yes | Network port. | | callback | AsyncCallback<string> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null** and **data** is the MAC address obtained. If the operation fails, **err** is an error object. | **Error codes** @@ -252,7 +254,7 @@ networkManager.getMac(wantTemp, 'eth0', (err, result) => { getMac(admin: Want, networkInterface: string): Promise\; -Obtain the device MAC address based on the given network interface through the specified device administrator application. This API uses a promise to return the result. +Obtains the device MAC address based on the network port through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_NETWORK_INFO @@ -265,7 +267,7 @@ Obtain the device MAC address based on the given network interface through the s | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| -| networkInterface | string | Yes | Network interface. | +| networkInterface | string | Yes | Network port. | **Return value** @@ -301,7 +303,7 @@ networkManager.getMac(wantTemp, 'eth0').then((result) => { isNetworkInterfaceDisabled(admin: Want, networkInterface: string, callback: AsyncCallback<boolean>): void -Checks whether a network interface is disabled through the specified device administrator application. This API uses an asynchronous callback to return the result. +Checks whether a network port is disabled through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_NETWORK_INFO @@ -314,8 +316,8 @@ Checks whether a network interface is disabled through the specified device admi | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| networkInterface | string | Yes | Network interface. | -| callback | AsyncCallback<boolean> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**, and **data** indicates whether the network interface is disabled. The value **true** means the network interface is disabled; and **false** means the opposite. If the operation fails, **err** is an error object. | +| networkInterface | string | Yes | Network port. | +| callback | AsyncCallback<boolean> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**, and **data** indicates whether the network port is disabled. The value **true** means the network port is disabled; and **false** means the opposite. If the operation fails, **err** is an error object. | **Error codes** @@ -347,7 +349,7 @@ networkManager.isNetworkInterfaceDisabled(wantTemp, 'eth0', (err, result) => { isNetworkInterfaceDisabled(admin: Want, networkInterface: string): Promise<boolean> -Checks whether a network interface is disabled through the specified device administrator application. This API uses a promise to return the result. +Checks whether a network port is disabled through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_NETWORK_INFO @@ -360,13 +362,13 @@ Checks whether a network interface is disabled through the specified device admi | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| -| networkInterface | string | Yes | Network interface. | +| networkInterface | string | Yes | Network port. | **Return value** | Type | Description | | --------------------- | ------------------------- | -| Promise<boolean> | Promise used to return the result. The value **true** means the network interface is disabled, and the value **false** means the opposite. | +| Promise<boolean> | Promise used to return the result. The value **true** means the network port is disabled, and the value **false** means the opposite. | **Error codes** @@ -396,7 +398,7 @@ networkManager.isNetworkInterfaceDisabled(wantTemp, 'eth0').then((result) => { setNetworkInterfaceDisabled(admin: Want, networkInterface: string, isDisabled: boolean, callback: AsyncCallback<void>): void -Sets a network interface through the specified device administrator application. This API uses an asynchronous callback to return the result. +Disables a network port through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_NETWORK @@ -409,8 +411,8 @@ Sets a network interface through the specified device administrator application. | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| networkInterface | string | Yes | Network interface. | -| isDisabled | boolean | Yes | Network interface status to set. The value **true** means to disable the network interface, and **false** means to enable the network interface. | +| networkInterface | string | Yes | Network port. | +| isDisabled | boolean | Yes | Network port status to set. The value **true** means to disable the network port, and **false** means to enable the network port. | | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | **Error codes** @@ -443,7 +445,7 @@ networkManager.setNetworkInterfaceDisabled(wantTemp, 'eth0', true, (err) => { setNetworkInterfaceDisabled(admin: Want, networkInterface: string, isDisabled: boolean): Promise<void> -Sets a network interface through the specified device administrator application. This API uses a promise to return the result. +Disables a network port through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_NETWORK @@ -456,14 +458,14 @@ Sets a network interface through the specified device administrator application. | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| -| networkInterface | string | Yes | Network interface. | -| isDisabled | boolean | Yes | Network interface status to set. The value **true** means to disable the network interface, and **false** means to enable the network interface. | +| networkInterface | string | Yes | Network port. | +| isDisabled | boolean | Yes | Network port status to set. The value **true** means to disable the network port, and **false** means to enable the network port. | **Return value** | Type | Description | | --------------------- | ------------------------- | -| Promise<void> | Promise that returns no value. An error object is thrown if the network interface fails to be disabled. | +| Promise<void> | Promise that returns no value. An error object is thrown if the network port fails to be disabled. | **Error codes** @@ -489,6 +491,209 @@ networkManager.setNetworkInterfaceDisabled(wantTemp, 'eth0', true).then(() => { }); ``` +## networkManager.setGlobalProxy + +setGlobalProxy(admin: Want, httpProxy: connection.HttpProxy, callback: AsyncCallback\): void + +Sets the global network proxy through the specified device administrator application. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_NETWORK + +**System capability**: SystemCapability.Customization.EnterpriseDeviceManager + +**System API**: This is a system API. + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ------------------------------- | +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | +| httpProxy | [connection.HttpProxy](js-apis-net-connection.md#httpproxy10) | Yes | Global HTTP proxy to set. | +| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | + +**Error codes** + +For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). + +| ID| Error Message | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | The application is not an administrator application of the device. | +| 9200002 | The administrator application does not have permission to manage the device.| + +**Example** + +```js +let wantTemp = { + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', +}; +let exclusionStr = "192.168,baidu.com" +let exclusionArray = exclusionStr.split(','); +let httpProxy = { + host: "192.168.xx.xxx", + port: 8080, + exclusionList: exclusionArray +}; + +networkManager.setGlobalProxy(wantTemp, httpProxy, (err) => { + if (err) { + console.error(`Failed to set network global proxy. Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in setting network global proxy`); +}); +``` + +## networkManager.setGlobalProxy + +setGlobalProxy(admin: Want, httpProxy: connection.HttpProxy): Promise\ + +Sets the global network proxy through the specified device administrator application. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_NETWORK + +**System capability**: SystemCapability.Customization.EnterpriseDeviceManager + +**System API**: This is a system API. + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----- | ----------------------------------- | ---- | ------- | +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| +| httpProxy | [connection.HttpProxy](js-apis-net-connection.md#httpproxy10) | Yes | Global HTTP proxy to set. | +| isDisabled | boolean | Yes | Network port status to set. The value **true** means to disable the network port, and **false** means to enable the network port. | + +**Return value** + +| Type | Description | +| --------------------- | ------------------------- | +| Promise<void> | Promise that returns no value. An error object will be thrown if the operation fails. | + +**Error codes** + +For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). + +| ID| Error Message | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | The application is not an administrator application of the device. | +| 9200002 | The administrator application does not have permission to manage the device.| + +**Example** + +```js +let wantTemp = { + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', +}; +let exclusionStr = "192.168,baidu.com" +let exclusionArray = exclusionStr.split(','); +let httpProxy = { + host: "192.168.xx.xxx", + port: 8080, + exclusionList: exclusionArray +}; + +networkManager.setGlobalProxy(wantTemp, httpProxy).then(() => { + console.info(`Succeeded in setting network global proxy`); +}).catch((err) => { + console.error(`Failed to set network global proxy. Code: ${err.code}, message: ${err.message}`); +}); +``` + +## networkManager.getGlobalProxy + +getGlobalProxy(admin: Want, callback: AsyncCallback\): void + +Obtains the global network proxy through the specified device administrator application. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_NETWORK + +**System capability**: SystemCapability.Customization.EnterpriseDeviceManager + +**System API**: This is a system API. + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ------------------------------- | +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | +| callback | AsyncCallback<[connection.HttpProxy](js-apis-net-connection.md#httpproxy10)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | + +**Error codes** + +For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). + +| ID| Error Message | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | The application is not an administrator application of the device. | +| 9200002 | The administrator application does not have permission to manage the device.| + +**Example** + +```js +let wantTemp = { + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', +}; + +networkManager.getGlobalProxy(wantTemp, (err, result) => { + if (err) { + console.error(`Failed to get network global proxy. Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in getting network global proxy, result : ${JSON.stringify(result)}`); +}); +``` + +## networkManager.getGlobalProxy + +getGlobalProxy(admin: Want): Promise\ + +Obtains the global network proxy through the specified device administrator application. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.ENTERPRISE_MANAGE_NETWORK + +**System capability**: SystemCapability.Customization.EnterpriseDeviceManager + +**System API**: This is a system API. + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----- | ----------------------------------- | ---- | ------- | +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| + +**Return value** + +| Type | Description | +| --------------------- | ------------------------- | +| Promise<[connection.HttpProxy](js-apis-net-connection.md#httpproxy10)> | Promise used to return the global HTTP proxy information obtained. | + +**Error codes** + +For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). + +| ID| Error Message | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | The application is not an administrator application of the device. | +| 9200002 | The administrator application does not have permission to manage the device.| + +**Example** + +```js +let wantTemp = { + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', +}; + +networkManager.getGlobalProxy(wantTemp).then(() => { + console.info(`Succeeded in getting network global proxy`); +}).catch((err) => { + console.error(`Failed to get network global proxy. Code: ${err.code}, message: ${err.message}`); +}); +``` + ## networkManager.addIptablesFilterRule addIptablesFilterRule(admin: Want, filterRule: AddFilterRule, callback: AsyncCallback\): void @@ -727,7 +932,7 @@ networkManager.removeIptablesFilterRule(wantTemp, filterRule).then(() => { listIptablesFilterRules(admin: Want, callback: AsyncCallback\): void -Obtain the network packet filtering rules through the specified device administrator application. This API uses an asynchronous callback to return the result. +Obtains network packet filtering rules through the specified device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_MANAGE_NETWORK @@ -772,7 +977,7 @@ networkManager.listIptablesFilterRules(wantTemp, (err, result) => { listIptablesFilterRules(admin: Want): Promise\ -Obtain the network packet filtering rules through the specified device administrator application. This API uses a promise to return the result. +Obtains network packet filtering rules through the specified device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_MANAGE_NETWORK diff --git a/en/application-dev/reference/apis/js-apis-enterprise-usbManager.md b/en/application-dev/reference/apis/js-apis-enterprise-usbManager.md new file mode 100644 index 0000000000000000000000000000000000000000..0b6768072723b7def564d67020fbf00e131eb8a4 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-enterprise-usbManager.md @@ -0,0 +1,127 @@ +# @ohos.enterprise.usbManager (USB Management) + +The **usbManager** module provides APIs for USB management. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> +> The APIs of this module can be used only in the stage model. +> +> The APIs provided by this module can be called only by a [device administrator application](enterpriseDeviceManagement-overview.md#basic-concepts) that is [enabled](js-apis-enterprise-adminManager.md#adminmanagerenableadmin). + +## Modules to Import + +```js +import usbManager from '@ohos.enterprise.usbManager' +``` + +## usbManager.setUsbPolicy + +setUsbPolicy(admin: Want, usbPolicy: UsbPolicy, callback: AsyncCallback\): void + +Sets the USB read/write policy through the specified device administrator application. This API uses an asynchronous callback to return the result. + +Required permissions: ohos.permission.ENTERPRISE_MANAGE_USB + +**System capability**: SystemCapability.Customization.EnterpriseDeviceManager + +**System API**: This is a system API. + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----- | ----------------------------------- | ---- | ------- | +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| +| usbPolicy | [UsbPolicy](#usbpolicy) | Yes| USB read/write policy to set.| +| callback | AsyncCallback\ | Yes| Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| + +**Error codes** + +For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). + +| ID| Error Message | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | the application is not an administrator of the device. | +| 9200002 | the administrator application does not have permission to manage the device. | + +**Example** + +```js +let wantTemp = { + bundleName: 'bundleName', + abilityName: 'abilityName', +}; +let policy = usbManager.UsbPolicy.READ_WRITE + +usbManager.setUsbPolicy(wantTemp, policy, (err) => { + if (err) { + console.error(`Failed to set usb policy. Code is ${err.code}, message is ${err.message}`); + return; + } + console.info('Succeeded in setting usb policy'); +}) +``` + +## usbManager.setUsbPolicy + +setUsbPolicy(admin: Want, usbPolicy: UsbPolicy): Promise\ + +Sets the USB read/write policy through the specified device administrator application. This API uses a promise to return the result. + +Required permissions: ohos.permission.ENTERPRISE_MANAGE_USB + +**System capability**: SystemCapability.Customization.EnterpriseDeviceManager + +**System API**: This is a system API. + +**Parameters** + +| Name | Type | Mandatory | Description | +| ----- | ----------------------------------- | ---- | ------- | +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| +| usbPolicy | [UsbPolicy](#usbpolicy) | Yes| USB read/write policy to set.| + +**Return value** + +| Type | Description | +| ----- | ----------------------------------- | +| Promise\ | Promise that returns no value. An error object will be thrown if the operation fails.| + +**Error codes** + +For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). + +| ID| Error Message | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | the application is not an administrator of the device. | +| 9200002 | the administrator application does not have permission to manage the device. | + +**Example** + +```js +let wantTemp = { + bundleName: 'bundleName', + abilityName: 'abilityName', +}; +let policy = usbManager.UsbPolicy.READ_WRITE + +usbManager.setUsbPolicy(wantTemp, policy).then(() => { + console.info('Succeeded in setting usb policy'); +}).catch((err) => { + console.error(`Failed to set usb policy. Code is ${err.code}, message is ${err.message}`); +}) +``` + +## UsbPolicy + +Enumerates the USB read/write policies. + +**System capability**: SystemCapability.Customization.EnterpriseDeviceManager + +**System API**: This is a system API. + +| Name| Value| Description| +| -------- | -------- | -------- | +| READ_WRITE | 0 | The USB is readable and writable.| +| READ_ONLY | 1 | The USB is read-only.| diff --git a/en/application-dev/reference/apis/js-apis-enterprise-wifiManager.md b/en/application-dev/reference/apis/js-apis-enterprise-wifiManager.md index 3d57b7d8be42df4e4b560b36885c7eccf885bbe7..3eb33e1c80e10cbffe5ff33ce2cd6f1d44de2097 100644 --- a/en/application-dev/reference/apis/js-apis-enterprise-wifiManager.md +++ b/en/application-dev/reference/apis/js-apis-enterprise-wifiManager.md @@ -4,9 +4,11 @@ The **wifiManager** module provides APIs for Wi-Fi management of enterprise devi > **NOTE** > -> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. > -> The APIs provided by this module can be called only by a [device administrator application](enterpriseDeviceManagement-overview.md#basic-concepts) that is [enabled](js-apis-enterprise-adminManager.md#adminmanagerenableadmin). +> - The APIs of this module can be used only in the stage model. +> +> - The APIs provided by this module can be called only by a [device administrator application](enterpriseDeviceManagement-overview.md#basic-concepts) that is [enabled](js-apis-enterprise-adminManager.md#adminmanagerenableadmin). ## Modules to Import @@ -37,7 +39,7 @@ Checks whether Wi-Fi is active through the specified device administrator applic For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). -| ID| Error Message | +| ID| Error Message | | ------- | ---------------------------------------------------------------------------- | | 9200001 | the application is not an administrator of the device. | | 9200002 | the administrator application does not have permission to manage the device. | @@ -87,7 +89,7 @@ Checks whether Wi-Fi is active through the specified device administrator applic For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). -| ID| Error Message | +| ID| Error Message | | ------- | ---------------------------------------------------------------------------- | | 9200001 | the application is not an administrator of the device. | | 9200002 | the administrator application does not have permission to manage the device. | @@ -111,7 +113,7 @@ wifiManager.isWifiActive(wantTemp).then((result) => { setWifiProfile(admin: Want, profile: WifiProfile, callback: AsyncCallback<void>): void -Sets Wi-Fi to connect to the specified network. This API uses an asynchronous callback to return the result. +Sets Wi-Fi profile through the specified device administrator application to enable the device to connect to the specified network. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_WIFI @@ -124,14 +126,14 @@ Sets Wi-Fi to connect to the specified network. This API uses an asynchronous ca | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| profile | [WifiProfile](#wifiprofile) | Yes | WLAN configuration. | +| profile | [WifiProfile](#wifiprofile) | Yes | Wi-Fi profile information. | | callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | **Error codes** For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). -| ID| Error Message | +| ID| Error Message | | ------- | ---------------------------------------------------------------------------- | | 9200001 | the application is not an administrator of the device. | | 9200002 | the administrator application does not have permission to manage the device. | @@ -162,7 +164,7 @@ wifiManager.setWifiProfile(wantTemp, profile, (err) => { setWifiProfile(admin: Want, profile: WifiProfile): Promise<void> -Sets Wi-Fi to connect to the specified network. This API uses a promise to return the result. +Sets Wi-Fi profile through the specified device administrator application to enable the device to connect to the specified network. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_WIFI @@ -175,7 +177,7 @@ Sets Wi-Fi to connect to the specified network. This API uses a promise to retur | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| -| profile | [WifiProfile](#wifiprofile) | Yes | WLAN configuration. | +| profile | [WifiProfile](#wifiprofile) | Yes | Wi-Fi profile information. | **Return value** @@ -187,7 +189,7 @@ Sets Wi-Fi to connect to the specified network. This API uses a promise to retur For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). -| ID| Error Message | +| ID| Error Message | | ------- | ---------------------------------------------------------------------------- | | 9200001 | the application is not an administrator of the device. | | 9200002 | the administrator application does not have permission to manage the device. | @@ -214,7 +216,7 @@ wifiManager.setWifiProfile(wantTemp, profile).then(() => { ## WifiProfile -Represents the WLAN configuration. +Represents the Wi-Fi profile information. **System capability**: SystemCapability.Customization.EnterpriseDeviceManager diff --git a/en/application-dev/reference/apis/js-apis-file-cloudsync.md b/en/application-dev/reference/apis/js-apis-file-cloudsync.md index e1a210c41c198c94539f427dbab3fdb5365b3ab5..a30d9f081b0d29b1179b09e13de434641270bcc0 100644 --- a/en/application-dev/reference/apis/js-apis-file-cloudsync.md +++ b/en/application-dev/reference/apis/js-apis-file-cloudsync.md @@ -116,8 +116,8 @@ For details about the error codes, see [File Management Error Codes](../errorcod ```js let gallerySync = new cloudSync.GallerySync(); - gallerySync.on('progress', (pg: SyncProgress) => { - console.info("syncState: " + pg.syncState); + gallerySync.on('progress', (pg: cloudSync.SyncProgress) => { + console.info("syncState: " + pg.state); }); ``` @@ -153,8 +153,8 @@ For details about the error codes, see [File Management Error Codes](../errorcod ```js let gallerySync = new cloudSync.GallerySync(); - gallerySync.on('progress', (pg: SyncProgress) => { - console.info("syncState: " + pg.syncState); + gallerySync.on('progress', (pg: cloudSync.SyncProgress) => { + console.info("syncState: " + pg.state); }); gallerySync.off('progress'); @@ -194,8 +194,8 @@ For details about the error codes, see [File Management Error Codes](../errorcod ```js let gallerySync = new cloudSync.GallerySync(); - gallerySync.on('progress', (pg: SyncProgress) => { - console.info("syncState: " + pg.syncState); + gallerySync.on('progress', (pg: cloudSync.SyncProgress) => { + console.info("syncState: " + pg.state); }); gallerySync.start().then(function() { @@ -411,7 +411,7 @@ For details about the error codes, see [File Management Error Codes](../errorcod ```js let download = new cloudSync.Download(); - download.on('progress', (pg: DownloadProgress) => { + download.on('progress', (pg: cloudSync.DownloadProgress) => { console.info("download state: " + pg.state); }); ``` @@ -448,7 +448,7 @@ For details about the error codes, see [File Management Error Codes](../errorcod ```js let download = new cloudSync.Download(); - download.on('progress', (pg: DownloadProgress) => { + download.on('progress', (pg: cloudSync.DownloadProgress) => { console.info("download state:" + pg.state); }); @@ -481,12 +481,13 @@ Starts to download a cloud file. This API uses a promise to return the result. ```js let download = new cloudSync.Download(); + let uri: string = "file:///media/Photo/1"; - download.on('progress', (pg: DownloadProgress) => { + download.on('progress', (pg: cloudSync.DownloadProgress) => { console.info("download state:" + pg.state); }); - download.start().then(function() { + download.start(uri).then(function() { console.info("start download successfully"); }).catch(function(err) { console.info("start download failed with error message: " + err.message + ", error code: " + err.code); @@ -538,8 +539,9 @@ For details about the error codes, see [File Management Error Codes](../errorcod ```js let download = new cloudSync.Download(); + let uri: string = "file:///media/Photo/1"; - download.start((err) => { + download.start(uri, (err) => { if (err) { console.info("start download failed with error message: " + err.message + ", error code: " + err.code); } else { @@ -588,8 +590,9 @@ For details about the error codes, see [File Management Error Codes](../errorcod ```js let download = new cloudSync.Download(); + let uri: string = "file:///media/Photo/1"; - download.stop().then(function() { + download.stop(uri).then(function() { console.info("stop download successfully"); }).catch(function(err) { console.info("stop download failed with error message: " + err.message + ", error code: " + err.code); @@ -631,8 +634,9 @@ For details about the error codes, see [File Management Error Codes](../errorcod ```js let download = new cloudSync.Download(); + let uri: string = "file:///media/Photo/1"; - download.stop((err) => { + download.stop(uri, (err) => { if (err) { console.info("stop download failed with error message: " + err.message + ", error code: " + err.code); } else { diff --git a/en/application-dev/reference/apis/js-apis-file-cloudsyncmanager.md b/en/application-dev/reference/apis/js-apis-file-cloudsyncmanager.md index aefe586ca9d7dbbb7e23c5c0478a88ca5b1834b9..f5699e324924708092eff07fc2d885c5fbef68b2 100644 --- a/en/application-dev/reference/apis/js-apis-file-cloudsyncmanager.md +++ b/en/application-dev/reference/apis/js-apis-file-cloudsyncmanager.md @@ -426,7 +426,7 @@ Clears the cloud data locally. This API uses an asynchronous callback to return | ---------- | ------ | ---- | ---- | | accountId | string | Yes | Account ID.| | appActions | object | Yes | Action to take. **bundleName** indicates the application bundle to clear, and [Action](#action) indicates the action to take.| -| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.| +| callback | AsyncCallback<void> | Yes | Callback invoked to clear the cloud data locally.| **Error codes** diff --git a/en/application-dev/reference/apis/js-apis-file-fs.md b/en/application-dev/reference/apis/js-apis-file-fs.md index f4818f8b2e4f1766f705cb699c2932c6e4a04907..5effa68ff47127104f00d7d9113104470f027b91 100644 --- a/en/application-dev/reference/apis/js-apis-file-fs.md +++ b/en/application-dev/reference/apis/js-apis-file-fs.md @@ -638,7 +638,7 @@ Opens a file. This API uses a promise to return the result. File uniform resourc | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------------------------------------------------ | | path | string | Yes | Application sandbox path or URI of the file. | -| mode | number | No | [Mode](#openmode) for opening the file. You must specify one of the following options. By default, the file is open in read-only mode.
- **OpenMode.READ_ONLY(0o0)**: Open the file in read-only mode.
- **OpenMode.WRITE_ONLY(0o1)**: Open the file in write-only mode.
- **OpenMode.READ_WRITE(0o2)**: Open the file in read/write mode.
You can also specify the following options, separated by a bitwise OR operator (|). By default, no additional options are given.
- **OpenMode.CREATE(0o100)**: If the file does not exist, create it.
- **OpenMode.TRUNC(0o1000)**: If the file exists and is open in write-only or read/write mode, truncate the file length to 0.
- **OpenMode.APPEND(0o2000)**: Open the file in append mode. New data will be added to the end of the file.
- **OpenMode.NONBLOCK(0o4000)**: If **path** points to a named pipe (also known as a FIFO), block special file, or character special file, perform non-blocking operations on the open file and in subsequent I/Os.
- **OpenMode.DIR(0o200000)**: If **path** does not point to a directory, throw an exception.
- **OpenMode.NOFOLLOW(0o400000)**: If **path** points to a symbolic link, throw an exception.
- **OpenMode.SYNC(0o4010000)**: Open the file in synchronous I/O mode.| +| mode | number | No | [Mode](#openmode) for opening the file. You must specify one of the following options. By default, the file is open in read-only mode.
- **OpenMode.READ_ONLY(0o0)**: Open the file in read-only mode.
- **OpenMode.WRITE_ONLY(0o1)**: Open the file in write-only mode.
- **OpenMode.READ_WRITE(0o2)**: Open the file in read/write mode.
You can also specify the following options, separated by a bitwise OR operator (|). By default, no additional options are given.
- **OpenMode.CREATE(0o100)**: If the file does not exist, create it.
- **OpenMode.TRUNC(0o1000)**: If the file exists and is open in write-only or read/write mode, truncate the file length to 0.
- **OpenMode.APPEND(0o2000)**: Open the file in append mode. New data will be added to the end of the file.
- **OpenMode.NONBLOCK(0o4000)**: If **path** points to a named pipe (also known as a FIFO), block special file, or character special file, perform non-blocking operations on the opened file and in subsequent I/Os.
- **OpenMode.DIR(0o200000)**: If **path** does not point to a directory, throw an exception.
- **OpenMode.NOFOLLOW(0o400000)**: If **path** points to a symbolic link, throw an exception.
- **OpenMode.SYNC(0o4010000)**: Open the file in synchronous I/O mode.| **Return value** @@ -742,7 +742,7 @@ Reads data from a file. This API uses a promise to return the result. | ------- | ----------- | ---- | ------------------------------------------------------------ | | fd | number | Yes | FD of the file. | | buffer | ArrayBuffer | Yes | Buffer used to store the file data read. | -| options | Object | No | The options are as follows:
- **offset** (number): position of the data to read in the file. This parameter is optional. By default, data is read from the current position.
- **length** (number): length of the data to read. This parameter is optional. The default value is the buffer length.| +| options | Object | No | The options are as follows:
- **offset** (number): start position to read the data. This parameter is optional. By default, data is read from the current position.
- **length** (number): length of the data to read. This parameter is optional. The default value is the buffer length.| **Return value** @@ -783,7 +783,7 @@ Reads data from a file. This API uses an asynchronous callback to return the res | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | fd | number | Yes | FD of the file. | | buffer | ArrayBuffer | Yes | Buffer used to store the file data read. | - | options | Object | No | The options are as follows:
- **offset** (number): position of the data to read in the file. This parameter is optional. By default, data is read from the current position.
- **length** (number): length of the data to read. This parameter is optional. The default value is the buffer length.| + | options | Object | No | The options are as follows:
- **offset** (number): start position to read the data. This parameter is optional. By default, data is read from the current position.
- **length** (number): length of the data to read. This parameter is optional. The default value is the buffer length.| | callback | AsyncCallback<number> | Yes | Callback invoked when the data is read asynchronously. | **Error codes** @@ -821,7 +821,7 @@ Synchronously reads data from a file. | ------- | ----------- | ---- | ---------------------------------------- | | fd | number | Yes | FD of the file. | | buffer | ArrayBuffer | Yes | Buffer used to store the file data read. | - | options | Object | No | The options are as follows:
- **offset** (number): position of the data to read in the file. This parameter is optional. By default, data is read from the current position.
- **length** (number): length of the data to read. This parameter is optional. The default value is the buffer length.| + | options | Object | No | The options are as follows:
- **offset** (number): start position to read the data. This parameter is optional. By default, data is read from the current position.
- **length** (number): length of the data to read. This parameter is optional. The default value is the buffer length.| **Return value** @@ -1042,7 +1042,7 @@ Writes data into a file. This API uses a promise to return the result. | ------- | ------------------------------- | ---- | ---------------------------------------- | | fd | number | Yes | FD of the file. | | buffer | ArrayBuffer\|string | Yes | Data to write. It can be a string or data from a buffer. | - | options | Object | No | The options are as follows:
- **offset** (number): start position to write the data in the file. This parameter is optional. By default, data is written from the current position.
- **length** (number): length of the data to write. This parameter is optional. The default value is the buffer length.
- **encoding** (string): format of the data to be encoded when the data is a string. The default value is **utf-8**, which is the only value supported currently.| + | options | Object | No | The options are as follows:
- **offset** (number): start position to write the data in the file. This parameter is optional. By default, data is written from the current position.
- **length** (number): length of the data to write. This parameter is optional. The default value is the buffer length.
- **encoding** (string): format of the data to be encoded when the data is a string. The default value is **'utf-8'**, which is the only value supported currently.| **Return value** @@ -1081,7 +1081,7 @@ Writes data into a file. This API uses an asynchronous callback to return the re | -------- | ------------------------------- | ---- | ---------------------------------------- | | fd | number | Yes | FD of the file. | | buffer | ArrayBuffer\|string | Yes | Data to write. It can be a string or data from a buffer. | - | options | Object | No | The options are as follows:
- **offset** (number): start position to write the data in the file. This parameter is optional. By default, data is written from the current position.
- **length** (number): length of the data to write. This parameter is optional. The default value is the buffer length.
- **encoding** (string): format of the data to be encoded when the data is a string. The default value is **utf-8**, which is the only value supported currently.| + | options | Object | No | The options are as follows:
- **offset** (number): start position to write the data in the file. This parameter is optional. By default, data is written from the current position.
- **length** (number): length of the data to write. This parameter is optional. The default value is the buffer length.
- **encoding** (string): format of the data to be encoded when the data is a string. The default value is **'utf-8'**, which is the only value supported currently.| | callback | AsyncCallback<number> | Yes | Callback invoked when the data is written asynchronously. | **Error codes** @@ -1117,7 +1117,7 @@ Synchronously writes data into a file. | ------- | ------------------------------- | ---- | ---------------------------------------- | | fd | number | Yes | FD of the file. | | buffer | ArrayBuffer\|string | Yes | Data to write. It can be a string or data from a buffer. | - | options | Object | No | The options are as follows:
- **offset** (number): start position to write the data in the file. This parameter is optional. By default, data is written from the current position.
- **length** (number): length of the data to write. This parameter is optional. The default value is the buffer length.
- **encoding** (string): format of the data to be encoded when the data is a string. The default value is **utf-8**, which is the only value supported currently.| + | options | Object | No | The options are as follows:
- **offset** (number): start position to write the data in the file. This parameter is optional. By default, data is written from the current position.
- **length** (number): length of the data to write. This parameter is optional. The default value is the buffer length.
- **encoding** (string): format of the data to be encoded when the data is a string. The default value is **'utf-8'**, which is the only value supported currently.| **Return value** @@ -1250,13 +1250,13 @@ Reads the text content of a file. This API uses a promise to return the result. | Name | Type | Mandatory| Description | | -------- | ------ | ---- | ------------------------------------------------------------ | | filePath | string | Yes | Application sandbox path of the file. | -| options | Object | No | The options are as follows:
- **offset** (number): position of the data to read in the file. This parameter is optional. By default, data is read from the current position.
- **length** (number): length of the data to read. This parameter is optional. The default value is the file length.
- **encoding** (string): format of the string to be encoded. The default value is **utf-8**, which is the only value supported.| +| options | Object | No | The options are as follows:
- **offset** (number): start position to read the data. This parameter is optional. By default, data is read from the current position.
- **length** (number): length of the data to read. This parameter is optional. The default value is the file length.
- **encoding** (string): format of the data (string) to be encoded. The default value is **'utf-8'**, which is the only value supported.| **Return value** | Type | Description | | --------------------- | ---------- | - | Promise<string> | Promise used to return the content read.| + | Promise<string> | Promise used to return the file content read.| **Error codes** @@ -1286,7 +1286,7 @@ Reads the text content of a file. This API uses an asynchronous callback to retu | Name | Type | Mandatory| Description | | -------- | --------------------------- | ---- | ------------------------------------------------------------ | | filePath | string | Yes | Application sandbox path of the file. | -| options | Object | No | The options are as follows:
- **offset** (number): position of the data to read in the file. This parameter is optional. By default, data is read from the current position.
- **length** (number): length of the data to read. This parameter is optional. The default value is the file length.
- **encoding** (string): format of the string to be encoded. The default value is **'utf-8'**, which is the only value supported.| +| options | Object | No | The options are as follows:
- **offset** (number): start position to read the data. This parameter is optional. By default, data is read from the current position.
- **length** (number): length of the data to read. This parameter is optional. The default value is the file length.
- **encoding**: format of the data to be encoded. The default value is **'utf-8'**, which is the only value supported.| | callback | AsyncCallback<string> | Yes | Callback invoked to return the content read. | **Error codes** @@ -1319,7 +1319,7 @@ Synchronously reads the text of a file. | Name | Type | Mandatory| Description | | -------- | ------ | ---- | ------------------------------------------------------------ | | filePath | string | Yes | Application sandbox path of the file. | -| options | Object | No | The options are as follows:
- **offset** (number): position of the data to read in the file. This parameter is optional. By default, data is read from the current position.
- **length** (number): length of the data to read. This parameter is optional. The default value is the file length.
- **encoding** (string): format of the string to be encoded. The default value is **utf-8**, which is the only value supported.| +| options | Object | No | The options are as follows:
- **offset** (number): start position to read the data. This parameter is optional. By default, data is read from the current position.
- **length** (number): length of the data to read. This parameter is optional. The default value is the file length.
- **encoding** (string): format of the data (string) to be encoded. The default value is **'utf-8'**, which is the only value supported.| **Return value** @@ -1859,7 +1859,7 @@ Lists all files in a folder. This API uses a promise to return the result.
Th | Type | Description | | --------------------- | ---------- | - | Promise<string[]> | Promise used to return the files names listed.| + | Promise<string[]> | Promise used to return the file names listed.| **Error codes** @@ -2285,6 +2285,111 @@ For details about the error codes, see [Basic File IO Error Codes](../errorcodes let res = fs.mkdtempSync(pathDir + "/XXXXXX"); ``` + +## fs.createRandomAccessFile10+ + +createRandomAccessFile(file: string|File, mode?: string): Promise<RandomAccessFile> + +Creates a **RandomAccessFile** instance based on the specified file path or file object. This API uses a promise to return the result. + +**System capability**: SystemCapability.FileManagement.File.FileIO + +**Parameters** +| Name | Type | Mandatory | Description | +| ------------ | ------ | ------ | ------------------------------------------------------------ | +| file | string\|[File](#file) | Yes | Application sandbox path of the file or an opened file object.| +| mode | number | No | [Option](#openmode) for creating the **RandomAccessFile** instance. This parameter is valid only when the application sandbox path of the file is passed in. One of the following options must be specified:
- **OpenMode.READ_ONLY(0o0)**: Create the file in read-only mode. This is the default value.
- **OpenMode.WRITE_ONLY(0o1)**: Create the file in write-only mode.
- **OpenMode.READ_WRITE(0o2)**: Create the file in read/write mode.
You can also specify the following options, separated by a bitwise OR operator (|). By default, no additional options are given.
- **OpenMode.CREATE(0o100)**: If the file does not exist, create it.
- **OpenMode.TRUNC(0o1000)**: If the **RandomAccessFile** object already exists and is created in write-only or read/write mode, truncate the file length to 0.
- **OpenMode.APPEND(0o2000)**: Create the file in append mode. New data will be added to the end of the **RandomAccessFile** object.
- **OpenMode.NONBLOCK(0o4000)**: If **path** points to a named pipe (also known as a FIFO), block special file, or character special file, perform non-blocking operations on the created file and in subsequent I/Os.
- **OpenMode.DIR(0o200000)**: If **path** does not point to a directory, throw an exception.
- **OpenMode.NOFOLLOW(0o400000)**: If **path** points to a symbolic link, throw an exception.
- **OpenMode.SYNC(0o4010000)**: Create a **RandomAccessFile** instance in synchronous I/O mode.| + +**Return value** + + | Type | Description | + | --------------------------------- | --------- | + | Promise<[RandomAccessFile](#randomaccessfile)> | Promise used to return the **RandomAccessFile** instance created.| + +**Error codes** + +For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). + +**Example** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); + fs.createRandomAccessFile(file).then((randomAccessFile) => { + console.info("randomAccessFile fd: " + randomAccessFile.fd); + }).catch((err) => { + console.info("create randomAccessFile failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +## fs.createRandomAccessFile10+ + +createRandomAccessFile(file: string|File, mode?: string, callback: AsyncCallback<RandomAccessFile>): void + +Creates a **RandomAccessFile** instance based on the specified file path or file object. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.FileManagement.File.FileIO + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------------ | ------ | ------ | ------------------------------------------------------------ | +| file | string\|[File](#file) | Yes | Application sandbox path of the file or an opened file object.| +| mode | number | No | [Option](#openmode) for creating the **RandomAccessFile** instance. This parameter is valid only when the application sandbox path of the file is passed in. One of the following options must be specified:
- **OpenMode.READ_ONLY(0o0)**: Create the file in read-only mode. This is the default value.
- **OpenMode.WRITE_ONLY(0o1)**: Create the file in write-only mode.
- **OpenMode.READ_WRITE(0o2)**: Create the file in read/write mode.
You can also specify the following options, separated by a bitwise OR operator (|). By default, no additional options are given.
- **OpenMode.CREATE(0o100)**: If the file does not exist, create it.
- **OpenMode.TRUNC(0o1000)**: If the **RandomAccessFile** object already exists and is created in write-only or read/write mode, truncate the file length to 0.
- **OpenMode.APPEND(0o2000)**: Create the file in append mode. New data will be added to the end of the **RandomAccessFile** object.
- **OpenMode.NONBLOCK(0o4000)**: If **path** points to a named pipe (also known as a FIFO), block special file, or character special file, perform non-blocking operations on the created file and in subsequent I/Os.
- **OpenMode.DIR(0o200000)**: If **path** does not point to a directory, throw an exception.
- **OpenMode.NOFOLLOW(0o400000)**: If **path** points to a symbolic link, throw an exception.
- **OpenMode.SYNC(0o4010000)**: Create a **RandomAccessFile** instance in synchronous I/O mode.| +| callback | AsyncCallback<[RandomAccessFile](#randomaccessfile)> | Yes | Callback invoked to return the **RandomAccessFile** instance created. | + +**Error codes** + +For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). + +**Example** + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); + fs.createRandomAccessFile(file, (err, randomAccessFile) => { + if (err) { + console.info("create randomAccessFile failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("randomAccessFilefile fd: " + randomAccessFile.fd); + } + }); + ``` + + +## fs.createRandomAccessFileSync10+ + +createRandomAccessFileSync(file: string|File, , mode?: string): RandomAccessFile + +Creates a **RandomAccessFile** instance based on the specified file path or file object. + +**System capability**: SystemCapability.FileManagement.File.FileIO + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------------ | ------ | ------ | ------------------------------------------------------------ | +| file | string\|[File](#file) | Yes | Application sandbox path of the file or an opened file object.| +| mode | number | No | [Option](#openmode) for creating the **RandomAccessFile** instance. This parameter is valid only when the application sandbox path of the file is passed in. One of the following options must be specified:
- **OpenMode.READ_ONLY(0o0)**: Create the file in read-only mode. This is the default value.
- **OpenMode.WRITE_ONLY(0o1)**: Create the file in write-only mode.
- **OpenMode.READ_WRITE(0o2)**: Create the file in read/write mode.
You can also specify the following options, separated by a bitwise OR operator (|). By default, no additional options are given.
- **OpenMode.CREATE(0o100)**: If the file does not exist, create it.
- **OpenMode.TRUNC(0o1000)**: If the **RandomAccessFile** object already exists and is created in write-only or read/write mode, truncate the file length to 0.
- **OpenMode.APPEND(0o2000)**: Create the file in append mode. New data will be added to the end of the **RandomAccessFile** object.
- **OpenMode.NONBLOCK(0o4000)**: If **path** points to a named pipe (also known as a FIFO), block special file, or character special file, perform non-blocking operations on the created file and in subsequent I/Os.
- **OpenMode.DIR(0o200000)**: If **path** does not point to a directory, throw an exception.
- **OpenMode.NOFOLLOW(0o400000)**: If **path** points to a symbolic link, throw an exception.
- **OpenMode.SYNC(0o4010000)**: Create a **RandomAccessFile** instance in synchronous I/O mode.| + +**Return value** + + | Type | Description | + | ------------------ | --------- | + | [RandomAccessFile](#randomaccessfile) | **RandomAccessFile** instance created.| + +**Error codes** + +For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). + +**Example** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath, fileIO.OpenMode.CREATE | fileIO.OpenMode.READ_WRITE); + let randomaccessfile = fileIO.createRandomAccessFileSync(file); + ``` + ## fs.createStream createStream(path: string, mode: string): Promise<Stream> @@ -2304,7 +2409,7 @@ Creates a stream based on the file path. This API uses a promise to return the r | Type | Description | | --------------------------------- | --------- | - | Promise<[Stream](#stream)> | Promise used to return the result.| + | Promise<[Stream](#stream)> | Promise used to return the stream opened.| **Error codes** @@ -2407,7 +2512,7 @@ Opens a stream based on the file descriptor. This API uses a promise to return t | Type | Description | | --------------------------------- | --------- | - | Promise<[Stream](#stream)> | Promise used to return the result.| + | Promise<[Stream](#stream)> | Promise used to return the stream opened.| **Error codes** @@ -2440,7 +2545,7 @@ Opens a stream based on the file descriptor. This API uses an asynchronous callb | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | fd | number | Yes | FD of the file. | | mode | string | Yes | - **r**: Open a file for reading. The file must exist.
- **r+**: Open a file for both reading and writing. The file must exist.
- **w**: Open a file for writing. If the file exists, clear its content. If the file does not exist, create a file.
- **w+**: Open a file for both reading and writing. If the file exists, clear its content. If the file does not exist, create a file.
- **a**: Open a file in append mode for writing at the end of the file. If the file does not exist, create a file. If the file exists, write data to the end of the file (the original content of the file is reserved).
- **a+**: Open a file in append mode for reading or updating at the end of the file. If the file does not exist, create a file. If the file exists, write data to the end of the file (the original content of the file is reserved).| - | callback | AsyncCallback<[Stream](#stream)> | Yes | Callback invoked when the stream is opened. | + | callback | AsyncCallback<[Stream](#stream)> | Yes | Callback invoked when the stream is created asynchronously. | **Error codes** @@ -2946,7 +3051,7 @@ Writes data into the stream. This API uses a promise to return the result. | Name | Type | Mandatory | Description | | ------- | ------------------------------- | ---- | ---------------------------------------- | | buffer | ArrayBuffer\|string | Yes | Data to write. It can be a string or data from a buffer. | - | options | Object | No | The options are as follows:
- **length** (number): length of the data to write. The default value is the buffer length.
- **offset** (number): start position to write the data in the file. This parameter is optional. By default, data is written from the current position.
- **encoding** (string): format of the data to be encoded when the data is a string. The default value is **utf-8**, which is the only value supported.| + | options | Object | No | The options are as follows:
- **length** (number): length of the data to write. The default value is the buffer length.
- **offset** (number): start position to write the data in the file. This parameter is optional. By default, data is written from the current position.
- **encoding** (string): format of the data to be encoded when the data is a string. The default value is **'utf-8'**, which is the only value supported.| **Return value** @@ -2983,7 +3088,7 @@ Writes data into the stream. This API uses an asynchronous callback to return th | Name | Type | Mandatory| Description | | -------- | ------------------------------- | ---- | ------------------------------------------------------------ | | buffer | ArrayBuffer\|string | Yes | Data to write. It can be a string or data from a buffer. | - | options | Object | No | The options are as follows:
- **length** (number): length of the data to write. This parameter is optional. The default value is the buffer length.
- **offset** (number): start position to write the data in the file. This parameter is optional. By default, data is written from the current position.
- **encoding** (string): format of the data to be encoded when the data is a string. The default value is **utf-8**, which is the only value supported.| + | options | Object | No | The options are as follows:
- **length** (number): length of the data to write. This parameter is optional. The default value is the buffer length.
- **offset** (number): start position to write the data in the file. This parameter is optional. By default, data is written from the current position.
- **encoding** (string): format of the data to be encoded when the data is a string. The default value is **'utf-8'**, which is the only value supported.| | callback | AsyncCallback<number> | Yes | Callback invoked when the data is written asynchronously. | **Error codes** @@ -3019,7 +3124,7 @@ Synchronously writes data into the stream. | Name | Type | Mandatory | Description | | ------- | ------------------------------- | ---- | ---------------------------------------- | | buffer | ArrayBuffer\|string | Yes | Data to write. It can be a string or data from a buffer. | - | options | Object | No | The options are as follows:
- **length** (number): length of the data to write. This parameter is optional. The default value is the buffer length.
- **offset** (number): start position to write the data in the file. This parameter is optional. By default, data is written from the current position.
- **encoding** (string): format of the data to be encoded when the data is a string. The default value is **utf-8**, which is the only value supported.| + | options | Object | No | The options are as follows:
- **length** (number): length of the data to write. This parameter is optional. The default value is the buffer length.
- **offset** (number): start position to write the data in the file. This parameter is optional. By default, data is written from the current position.
- **encoding** (string): format of the data to be encoded when the data is a string. The default value is **'utf-8'**, which is the only value supported.| **Return value** @@ -3052,7 +3157,7 @@ Reads data from the stream. This API uses a promise to return the result. | Name | Type | Mandatory | Description | | ------- | ----------- | ---- | ---------------------------------------- | | buffer | ArrayBuffer | Yes | Buffer used to store the file read. | - | options | Object | No | The options are as follows:
- **length** (number): length of the data to read. This parameter is optional. The default value is the buffer length.
- **offset** (number): position of the data to read in the file. By default, data is read from the current position.| + | options | Object | No | The options are as follows:
- **length** (number): length of the data to read. This parameter is optional. The default value is the buffer length.
- **offset** (number): start position to read the data. This parameter is optional. By default, data is read from the current position.| **Return value** @@ -3091,7 +3196,7 @@ Reads data from the stream. This API uses an asynchronous callback to return the | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ---------------------------------------- | | buffer | ArrayBuffer | Yes | Buffer used to store the file read. | - | options | Object | No | The options are as follows:
- **length** (number): length of the data to read. This parameter is optional. The default value is the buffer length.
- **offset** (number): position of the data to read in the file. This parameter is optional. By default, data is read from the current position.| + | options | Object | No | The options are as follows:
- **length** (number): length of the data to read. This parameter is optional. The default value is the buffer length.
- **offset** (number): start position to read the data. This parameter is optional. By default, data is read from the current position.| | callback | AsyncCallback<number> | Yes | Callback invoked when data is read asynchronously from the stream. | **Error codes** @@ -3127,7 +3232,7 @@ Synchronously reads data from the stream. | Name | Type | Mandatory | Description | | ------- | ----------- | ---- | ---------------------------------------- | | buffer | ArrayBuffer | Yes | Buffer used to store the file read. | - | options | Object | No | The options are as follows:
- **length** (number): length of the data to read. This parameter is optional. The default value is the buffer length.
- **offset** (number): position of the data to read in the file. By default, data is read from the current position.
| + | options | Object | No | The options are as follows:
- **length** (number): length of the data to read. This parameter is optional. The default value is the buffer length.
- **offset** (number): start position to read the data. This parameter is optional. By default, data is read from the current position.
| **Return value** @@ -3273,6 +3378,284 @@ For details about the error codes, see [Basic File IO Error Codes](../errorcodes console.log("unlock file successful"); ``` + +## RandomAccessFile + +Randomly reads and writes a stream. Before invoking any API of **RandomAccessFile**, you need to use **createRandomAccess()** to create a **RandomAccessFile** instance synchronously or asynchronously. + +**System capability**: SystemCapability.FileManagement.File.FileIO + +### Attributes + +| Name | Type | Readable | Writable | Description | +| ----------- | ------ | ---- | ----- | ---------------- | +| fd | number | Yes | No | FD of the file.| +| filePointer | number | Yes | Yes | Offset pointer to the **RandomAccessFile** instance.| + +### setFilePointer10+ + +setFilePointer(): void + +Sets the file offset pointer. + +**System capability**: SystemCapability.FileManagement.File.FileIO + +**Error codes** + +For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). + +**Example** + + ```js + let filePath = pathDir + "/test.txt"; + let randomAccessFile = fs.createRandomAccessFileSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + randomAccessFile.setFilePointer(1); + ``` + + +### close10+ + +close(): void + +Closes this **RandomAccessFile** instance synchronously. + +**System capability**: SystemCapability.FileManagement.File.FileIO + +**Error codes** + +For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). + +**Example** + + ```js + let filePath = pathDir + "/test.txt"; + let randomAccessFile = fs.createRandomAccessFileSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + randomAccessFile.closeSync(); + ``` + +### write10+ + +write(buffer: ArrayBuffer|string, options?: { offset?: number; length?: number; encoding?: string; }): Promise<number> + +Writes data into a file. This API uses a promise to return the result. + +**System capability**: SystemCapability.FileManagement.File.FileIO + +**Parameters** + + | Name | Type | Mandatory | Description | + | ------- | ------------------------------- | ---- | ---------------------------------------- | + | buffer | ArrayBuffer\|string | Yes | Data to write. It can be a string or data from a buffer. | + | options | Object | No | The options are as follows:
- **length** (number): length of the data to write. The default value is the buffer length.
- **offset** (number): start position to write the data (it is determined by **filePointer** plus **offset**). This parameter is optional. By default, data is written from the **filePointer**.
- **encoding** (string): format of the data to be encoded when the data is a string. The default value is **'utf-8'**, which is the only value supported.| + +**Return value** + + | Type | Description | + | --------------------- | -------- | + | Promise<number> | Promise used to return the length of the data written.| + +**Error codes** + +For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). + +**Example** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(fpath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); + let randomaccessfile = fs.createRandomAccessFileSync(file); + let bufferLength = 4096; + randomaccessfile.write(new ArrayBuffer(bufferLength), { offset: 1, length: 5 }).then((bytesWritten) => { + console.info("randomAccessFile bytesWritten: " + bytesWritten); + }).catch((err) => { + console.info("create randomAccessFile failed with error message: " + err.message + ", error code: " + err.code); + }); + + ``` + +### write10+ + +write(buffer: ArrayBuffer|string, options?: { offset?: number; length?: number; encoding?: string; }, callback: AsyncCallback<number>): void + +Writes data into a file. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.FileManagement.File.FileIO + +**Parameters** + + | Name | Type | Mandatory| Description | + | -------- | ------------------------------- | ---- | ------------------------------------------------------------ | + | buffer | ArrayBuffer\|string | Yes | Data to write. It can be a string or data from a buffer. | + | options | Object | No | The options are as follows:
- **length** (number): length of the data to write. This parameter is optional. The default value is the buffer length.
- **offset** (number): start position to write the data (it is determined by **filePointer** plus **offset**). This parameter is optional. By default, data is written from the **filePointer**.
- **encoding** (string): format of the data to be encoded when the data is a string. The default value is **'utf-8'**, which is the only value supported.| + | callback | AsyncCallback<number> | Yes | Callback invoked when the data is written asynchronously. | + +**Error codes** + +For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). + +**Example** + + ```js + let filePath = pathDir + "/test.txt"; + let randomAccessFile = fs.createRandomAccessFileSync(file); + let bufferLength = 4096; + randomAccessFile.write(new ArrayBuffer(bufferLength), { offset: 1 }, function(err, bytesWritten) { + if (err) { + console.info("write failed with error message: " + err.message + ", error code: " + err.code); + } else { + if (bytesWritten) { + console.info("write succeed and size is:" + bytesWritten); + } + } + }); + ``` + +### writeSync10+ + +writeSync(buffer: ArrayBuffer|string, options?: { offset?: number; length?: number; encoding?: string; }): number + +Synchronously writes data into a file. + +**System capability**: SystemCapability.FileManagement.File.FileIO + +**Parameters** + + | Name | Type | Mandatory | Description | + | ------- | ------------------------------- | ---- | ---------------------------------------- | + | buffer | ArrayBuffer\|string | Yes | Data to write. It can be a string or data from a buffer. | + | options | Object | No | The options are as follows:
- **length** (number): length of the data to write. This parameter is optional. The default value is the buffer length.
- **offset** (number): start position to write the data (it is determined by **filePointer** plus **offset**). This parameter is optional. By default, data is written from the **filePointer**.
- **encoding** (string): format of the data to be encoded when the data is a string. The default value is **'utf-8'**, which is the only value supported.| + +**Return value** + + | Type | Description | + | ------ | -------- | + | number | Length of the data written in the file.| + +**Error codes** + +For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). + +**Example** + + ```js + let filePath = pathDir + "/test.txt"; + let randomaccessfile= fs.createRandomAccessFileSync(filePath,"r+"); + let bytesWritten = randomaccessfile.writeSync("hello, world", {offset: 5, length: 5, encoding :'utf-8'}); + ``` + +### read10+ + +read(buffer: ArrayBuffer, options?: { offset?: number; length?: number; }): Promise<number> + +Reads data from a file. This API uses a promise to return the result. + +**System capability**: SystemCapability.FileManagement.File.FileIO + +**Parameters** + + | Name | Type | Mandatory | Description | + | ------- | ----------- | ---- | ---------------------------------------- | + | buffer | ArrayBuffer | Yes | Buffer used to store the file read. | + | options | Object | No | The options are as follows:
- **length** (number): length of the data to read. This parameter is optional. The default value is the buffer length.
- **offset** (number): start position to read the data (it is determined by **filePointer** plus **offset**). This parameter is optional. By default, data is read from the **filePointer**.| + +**Return value** + + | Type | Description | + | ---------------------------------- | ------ | + | Promise<number> | Promise used to return the data read.| + +**Error codes** + +For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). + +**Example** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); + let randomaccessfile = fs.createRandomAccessFileSync(file); + let bufferLength = 4096; + randomaccessfile.read(new ArrayBuffer(bufferLength), { offset: 1, length: 5 }).then((readLength) => { + console.info("randomAccessFile readLength: " + readLength); + }).catch((err) => { + console.info("create randomAccessFile failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + +### read10+ + +read(buffer: ArrayBuffer, options?: { position?: number; offset?: number; length?: number; }, callback: AsyncCallback<number>): void + +Reads data from a file. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.FileManagement.File.FileIO + +**Parameters** + + | Name | Type | Mandatory | Description | + | -------- | ---------------------------------------- | ---- | ---------------------------------------- | + | buffer | ArrayBuffer | Yes | Buffer used to store the file read. | + | options | Object | No | The options are as follows:
- **length** (number): length of the data to read. This parameter is optional. The default value is the buffer length.
- **offset** (number): start position to read the data (it is determined by **filePointer** plus **offset**). This parameter is optional. By default, data is read from the **filePointer**.| + | callback | AsyncCallback<number> | Yes | Callback invoked when data is read asynchronously from the stream. | + +**Error codes** + +For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). + +**Example** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); + let randomaccessfile = await fileIO.createRandomAccessFile(file); + let length = 20; + randomaccessfile.read(new ArrayBuffer(length), { offset: 1, length: 5 }, function (err, readLength) { + if (err) { + console.info("read failed with error message: " + err.message + ", error code: " + err.code); + } else { + if (readLength) { + console.info("read succeed and size is:" + readLength); + } + } + }); + ``` + +### readSync10+ + +readSync(buffer: ArrayBuffer, options?: { offset?: number; length?: number; }): number + +Synchronously reads data from a file. + +**System capability**: SystemCapability.FileManagement.File.FileIO + +**Parameters** + + | Name | Type | Mandatory | Description | + | ------- | ----------- | ---- | ---------------------------------------- | + | buffer | ArrayBuffer | Yes | Buffer used to store the file read. | + | options | Object | No | The options are as follows:
- **length** (number): length of the data to read. This parameter is optional. The default value is the buffer length.
- **offset** (number): start position to read the data (it is determined by **filePointer** plus **offset**). This parameter is optional. By default, data is read from the **filePointer**.
| + +**Return value** + + | Type | Description | + | ------ | -------- | + | number | Length of the data read.| + +**Error codes** + +For details about the error codes, see [Basic File IO Error Codes](../errorcodes/errorcode-filemanagement.md#basic-file-io-error-codes). + +**Example** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath, fileIO.OpenMode.CREATE | fileIO.OpenMode.READ_WRITE); + let randomaccessfile = fs.createRandomAccessFileSync(file); + let length = 4096; + let readLength = randomaccessfile.readSync(new ArrayBuffer(length)); + ``` + + ## Watcher10+ Provides APIs for observing the changes of files or folders. Before using the APIs of **Watcher** , call **createWatcher()** to create a **Watcher** object. @@ -3342,7 +3725,7 @@ Defines the constants of the **mode** parameter used in **open()**. It specifies | NOFOLLOW | number | 0o400000 | If **path** points to a symbolic link, throw an exception.| | SYNC | number | 0o4010000 | Open the file in synchronous I/O mode.| -## Filter +## Filter10+ **System capability**: SystemCapability.FileManagement.File.FileIO diff --git a/en/application-dev/reference/apis/js-apis-huks.md b/en/application-dev/reference/apis/js-apis-huks.md index 911af6e5872df7747d837dd656ae63a259a991ad..72a0d3d7fe91c29caf0c8f782eaf3804b64df42d 100644 --- a/en/application-dev/reference/apis/js-apis-huks.md +++ b/en/application-dev/reference/apis/js-apis-huks.md @@ -1771,7 +1771,7 @@ Aborts a key operation. This API uses an asynchronous callback to return the res | -------- | --------------------------- | ---- | ------------------------------------------- | | handle | number | Yes | Handle for the **abortSession** operation. | | options | [HuksOptions](#huksoptions) | Yes | Parameter set used for the **abortSession** operation. | -| callback | AsyncCallback\ | Yes | Callback that returns no value. | +| callback | AsyncCallback\ | Yes | Callback invoked to return the **abortSession** operation result.| **Error codes** @@ -2220,7 +2220,7 @@ Enumerates the key algorithms. | HUKS_ALG_HKDF | 51 | HKDF
**System capability**: SystemCapability.Security.Huks.Extension| | HUKS_ALG_PBKDF2 | 52 | PBKDF2
**System capability**: SystemCapability.Security.Huks.Extension| | HUKS_ALG_ECDH | 100 | ECDH
**System capability**: SystemCapability.Security.Huks.Extension| -| HUKS_ALG_X25519 | 101 | X25519
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ALG_X25519 | 101 | X25519
**System capability**: SystemCapability.Security.Huks.Extension| | HUKS_ALG_ED25519 | 102 | ED25519
**System capability**: SystemCapability.Security.Huks.Extension| | HUKS_ALG_DH | 103 | DH
**System capability**: SystemCapability.Security.Huks.Extension| | HUKS_ALG_SM29+ | 150 | SM2
**System capability**: SystemCapability.Security.Huks.Extension| @@ -2260,8 +2260,8 @@ Enumerates the key storage modes. | Name | Value | Description | | -------------------------------------------- | ---- | ------------------------------ | -| HUKS_STORAGE_TEMP(deprecated) | 0 | The key is managed locally.
**NOTE**: This tag is discarded since API version 10. No substitute is provided because this tag is not used in key management. In key derivation scenarios, use **HUKS_STORAGE_ONLY_USED_IN_HUKS** or **HUKS_STORAGE_KEY_EXPORT_ALLOWED**.
**System capability**: SystemCapability.Security.Huks.Core| -| HUKS_STORAGE_PERSISTENT(deprecated) | 1 | The key is managed by the HUKS service.
**NOTE**: This tag is discarded since API version 10. No substitute is provided because this tag is not used in key management. In key derivation scenarios, use **HUKS_STORAGE_ONLY_USED_IN_HUKS** or **HUKS_STORAGE_KEY_EXPORT_ALLOWED**.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_STORAGE_TEMP(deprecated) | 0 | The key is managed locally.
**NOTE**: This tag is deprecated since API version 10. No substitute is provided because this tag is not used in key management. In key derivation scenarios, use **HUKS_STORAGE_ONLY_USED_IN_HUKS** or **HUKS_STORAGE_KEY_EXPORT_ALLOWED**.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_STORAGE_PERSISTENT(deprecated) | 1 | The key is managed by the HUKS service.
**NOTE**: This tag is deprecated since API version 10. No substitute is provided because this tag is not used in key management. In key derivation scenarios, use **HUKS_STORAGE_ONLY_USED_IN_HUKS** or **HUKS_STORAGE_KEY_EXPORT_ALLOWED**.
**System capability**: SystemCapability.Security.Huks.Core| | HUKS_STORAGE_ONLY_USED_IN_HUKS10+ | 2 | The key derived from the master key is stored in the HUKS and managed by the HUKS.
**System capability**: SystemCapability.Security.Huks.Extension| | HUKS_STORAGE_KEY_EXPORT_ALLOWED10+ | 3 | The key derived from the master key is exported to the service, and not managed by the HUKS.
**System capability**: SystemCapability.Security.Huks.Extension| @@ -2427,7 +2427,7 @@ Enumerates the tags used to invoke parameters. | HUKS_TAG_ALL_USERS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 301 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| | HUKS_TAG_USER_ID | HuksTagType.HUKS_TAG_TYPE_UINT \| 302 | ID of the user to which the key belongs.
**System capability**: SystemCapability.Security.Huks.Extension| | HUKS_TAG_NO_AUTH_REQUIRED | HuksTagType.HUKS_TAG_TYPE_BOOL \| 303 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| -| HUKS_TAG_USER_AUTH_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 304 | User authentication type. For details, see [HuksUserAuthType](#huksuserauthtype9). This parameter must be set together with [HuksAuthAccessType](#huksauthaccesstype9). You can set a maximum of two user authentication types at a time. For example, if **HuksAuthAccessType** is **HKS_SECURE_ACCESS_INVALID_NEW_BIO_ENROLL**, you can set two of **HKS_USER_AUTH_TYPE_FACE**, **HKS_USER_AUTH_TYPE_FINGERPRINT**, and **HKS_USER_AUTH_TYPE_FACE\**.| HKS_USER_AUTH_TYPE_FINGERPRINT
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_USER_AUTH_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 304 | User authentication type. For details, see [HuksUserAuthType](#huksuserauthtype9). This parameter must be set together with [HuksAuthAccessType](#huksauthaccesstype9). You can set a maximum of two user authentication types at a time. For example, if **HuksAuthAccessType** is **HKS_SECURE_ACCESS_INVALID_NEW_BIO_ENROLL**, you can set two of **HKS_USER_AUTH_TYPE_FACE**, **HKS_USER_AUTH_TYPE_FINGERPRINT**, and **HKS_USER_AUTH_TYPE_FACE\**.| HKS_USER_AUTH_TYPE_FINGERPRINT
**System capability**: SystemCapability.Security.Huks.Extension| | HUKS_TAG_AUTH_TIMEOUT | HuksTagType.HUKS_TAG_TYPE_UINT \| 305 | Timeout period of an authentication token.
**System capability**: SystemCapability.Security.Huks.Extension| | HUKS_TAG_AUTH_TOKEN | HuksTagType.HUKS_TAG_TYPE_BYTES \| 306 | Used to pass in the authentication token.
**System capability**: SystemCapability.Security.Huks.Extension| | HUKS_TAG_KEY_AUTH_ACCESS_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 307 | Access control type. For details, see [HuksAuthAccessType](#huksauthaccesstype9). This parameter must be set together with [HuksUserAuthType](#huksuserauthtype9).
**System capability**: SystemCapability.Security.Huks.Extension| @@ -2483,7 +2483,9 @@ generateKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\ **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.generateKeyItem9+](#huksgeneratekeyitem9). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.generateKeyItem9+](#huksgeneratekeyitem9). **System capability**: SystemCapability.Security.Huks.Extension @@ -2493,7 +2495,7 @@ Generates a key. This API uses an asynchronous callback to return the result. | -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | | keyAlias | string | Yes | Alias of the key. | | options | [HuksOptions](#huksoptions) | Yes | Tags required for generating the key. | -| callback | AsyncCallback\<[HuksResult](#huksresultdeprecated)> | Yes | Callback invoked to return the result. If the operation is successful, **HUKS_SUCCESS** is returned; otherwise, an error code defined in **HuksResult** is returned.| +| callback | AsyncCallback\<[HuksResult](#huksresultdeprecated)> | Yes | Callback invoked to return the result. If the operation is successful, **HUKS_SUCCESS** is returned. If the operation fails, an error code defined in **HuksResult** is returned.| **Example** @@ -2535,7 +2537,9 @@ generateKey(keyAlias: string, options: HuksOptions) : Promise\ Generates a key. This API uses a promise to return the result. -> **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.generateKeyItem9+](#huksgeneratekeyitem9-1). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.generateKeyItem9+](#huksgeneratekeyitem9-1). **System capability**: SystemCapability.Security.Huks.Extension @@ -2550,7 +2554,7 @@ Generates a key. This API uses a promise to return the result. | Type | Description | | ----------------------------------- | -------------------------------------------------- | -| Promise\<[HuksResult](#huksresultdeprecated)> | Promise used to return the result. If the operation is successful, **HUKS_SUCCESS** is returned; otherwise, an error code is returned.| +| Promise\<[HuksResult](#huksresultdeprecated)> | Promise used to return the result. If the operation is successful, **HUKS_SUCCESS** is returned. If the operation fails, an error code is returned.| **Example** @@ -2588,7 +2592,9 @@ deleteKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\ **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.deleteKeyItem9+](#huksdeletekeyitem9). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.deleteKeyItem9+](#huksdeletekeyitem9). **System capability**: SystemCapability.Security.Huks.Extension @@ -2598,7 +2604,7 @@ Deletes a key. This API uses an asynchronous callback to return the result. | -------- | ----------------------------------------- | ---- | -------------------------------------------------- | | keyAlias | string | Yes | Key alias passed in when the key was generated. | | options | [HuksOptions](#huksoptions) | Yes | Empty object (leave this parameter empty). | -| callback | AsyncCallback\<[HuksResult](#huksresultdeprecated)> | Yes | Callback invoked to return the result. If the operation is successful, **HUKS_SUCCESS** is returned; otherwise, an error code is returned.| +| callback | AsyncCallback\<[HuksResult](#huksresultdeprecated)> | Yes | Callback invoked to return the result. If the operation is successful, **HUKS_SUCCESS** is returned. If the operation fails, an error code is returned.| **Example** @@ -2617,7 +2623,9 @@ deleteKey(keyAlias: string, options: HuksOptions) : Promise\ Deletes a key. This API uses a promise to return the result. -> **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.deleteKeyItem9+](#huksdeletekeyitem9-1). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.deleteKeyItem9+](#huksdeletekeyitem9-1). **System capability**: SystemCapability.Security.Huks.Extension @@ -2632,7 +2640,7 @@ Deletes a key. This API uses a promise to return the result. | Type | Description | | ----------------------------------- | -------------------------------------------------- | -| Promise\<[HuksResult](#huksresultdeprecated)> | Promise used to return the result. If the operation is successful, **HUKS_SUCCESS** is returned; otherwise, an error code is returned.| +| Promise\<[HuksResult](#huksresultdeprecated)> | Promise used to return the result. If the operation is successful, **HUKS_SUCCESS** is returned. If the operation fails, an error code is returned.| **Example** @@ -2651,7 +2659,9 @@ importKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\ **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.importKeyItem9+](#huksimportkeyitem9). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.importKeyItem9+](#huksimportkeyitem9). **System capability**: SystemCapability.Security.Huks.Extension @@ -2661,7 +2671,7 @@ Imports a key in plaintext. This API uses an asynchronous callback to return the | -------- | ------------------------ | ---- | ------------------------------------------------- | | keyAlias | string | Yes | Alias of the key.| | options | [HuksOptions](#huksoptions) | Yes | Tags required for the import and key to import.| -| callback | AsyncCallback\<[HuksResult](#huksresultdeprecated)> | Yes | Callback invoked to return the result. If the operation is successful, **HUKS_SUCCESS** is returned; otherwise, an error code is returned.| +| callback | AsyncCallback\<[HuksResult](#huksresultdeprecated)> | Yes | Callback invoked to return the result. If the operation is successful, **HUKS_SUCCESS** is returned. If the operation fails, an error code is returned.| **Example** @@ -2711,7 +2721,9 @@ importKey(keyAlias: string, options: HuksOptions) : Promise\ Imports a key in plaintext. This API uses a promise to return the result. -> **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.importKeyItem9+](#huksimportkeyitem9-1). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.importKeyItem9+](#huksimportkeyitem9-1). **System capability**: SystemCapability.Security.Huks.Extension @@ -2726,7 +2738,7 @@ Imports a key in plaintext. This API uses a promise to return the result. | Type | Description | | ----------------------------------- | -------------------------------------------------- | -| Promise\<[HuksResult](#huksresultdeprecated)> | Promise used to return the result. If the operation is successful, **HUKS_SUCCESS** is returned; otherwise, an error code is returned.| +| Promise\<[HuksResult](#huksresultdeprecated)> | Promise used to return the result. If the operation is successful, **HUKS_SUCCESS** is returned. If the operation fails, an error code is returned.| **Example** @@ -2778,7 +2790,9 @@ exportKey(keyAlias: string, options: HuksOptions, callback: AsyncCallback\ **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.exportKeyItem9+](#huksexportkeyitem9). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.exportKeyItem9+](#huksexportkeyitem9). **System capability**: SystemCapability.Security.Huks.Extension @@ -2807,7 +2821,9 @@ exportKey(keyAlias: string, options: HuksOptions) : Promise\ Exports a key. This API uses a promise to return the result. -> **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.exportKeyItem9+](#huksexportkeyitem9-1). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.exportKeyItem9+](#huksexportkeyitem9-1). **System capability**: SystemCapability.Security.Huks.Extension @@ -2841,7 +2857,9 @@ getKeyProperties(keyAlias: string, options: HuksOptions, callback: AsyncCallback Obtains key properties. This API uses an asynchronous callback to return the result. -> **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.getKeyItemProperties9+](#huksgetkeyitemproperties9). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.getKeyItemProperties9+](#huksgetkeyitemproperties9). **System capability**: SystemCapability.Security.Huks.Extension @@ -2870,7 +2888,9 @@ getKeyProperties(keyAlias: string, options: HuksOptions) : Promise\ Obtains key properties. This API uses a promise to return the result. -> **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.getKeyItemProperties9+](#huksgetkeyitemproperties9-1). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.getKeyItemProperties9+](#huksgetkeyitemproperties9-1). **System capability**: SystemCapability.Security.Huks.Extension @@ -2885,7 +2905,7 @@ Obtains key properties. This API uses a promise to return the result. | Type | Description | | ------------------ | ------------------------------------------------------------ | -| Promise\<[HuksResult](#huksoptions)> | Promise used to return the result. If the operation is successful, **errorCode** is **HUKS_SUCCESS** and **properties** contains the parameters required for generating the key. If the operation fails, an error code is returned. | +| Promise\<[HuksResult](#huksoptions)> | Promise used to return the result. If the operation is successful, **errorCode** is **HUKS_SUCCESS** and **properties** returns the parameters required for generating the key. If the operation fails, an error code is returned.| **Example** @@ -2904,7 +2924,9 @@ isKeyExist(keyAlias: string, options: HuksOptions, callback: AsyncCallback\ **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.isKeyItemExist9+](#huksiskeyitemexist9). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.isKeyItemExist9+](#huksiskeyitemexist9). **System capability**: SystemCapability.Security.Huks.Extension @@ -2933,7 +2955,9 @@ isKeyExist(keyAlias: string, options: HuksOptions) : Promise\ Checks whether a key exists. This API uses a promise to return the result. -> **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.isKeyItemExist9+](#huksiskeyitemexist9-1). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.isKeyItemExist9+](#huksiskeyitemexist9-1). **System capability**: SystemCapability.Security.Huks.Extension @@ -2967,7 +2991,9 @@ init(keyAlias: string, options: HuksOptions, callback: AsyncCallback\ **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.initSession9+](#huksinitsession9-1). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.initSession9+](#huksinitsession9-1). **System capability**: SystemCapability.Security.Huks.Extension @@ -2985,7 +3011,9 @@ init(keyAlias: string, options: HuksOptions) : Promise\ Initializes the data for a key operation. This API uses a promise to return the result. **huks.init**, **huks.update**, and **huks.finish** must be used together. -> **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.initSession9+](#huksinitsession9-1). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.initSession9+](#huksinitsession9-1). **System capability**: SystemCapability.Security.Huks.Extension @@ -3008,7 +3036,9 @@ update(handle: number, token?: Uint8Array, options: HuksOptions, callback: Async Updates the key operation by segment. This API uses an asynchronous callback to return the result. **huks.init**, **huks.update**, and **huks.finish** must be used together. -> **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.updateSession9+](#huksupdatesession9-1). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.updateSession9+](#huksupdatesession9-1). **System capability**: SystemCapability.Security.Huks.Extension @@ -3027,7 +3057,9 @@ update(handle: number, token?: Uint8Array, options: HuksOptions) : Promise\ **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.updateSession9+](#huksupdatesession9-2). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.updateSession9+](#huksupdatesession9-2). **System capability**: SystemCapability.Security.Huks.Extension @@ -3051,7 +3083,9 @@ finish(handle: number, options: HuksOptions, callback: AsyncCallback\ **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.finishSession9+](#huksfinishsession9). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.finishSession9+](#huksfinishsession9). **System capability**: SystemCapability.Security.Huks.Extension @@ -3069,7 +3103,9 @@ finish(handle: number, options: HuksOptions) : Promise\ Completes the key operation and releases resources. This API uses a promise to return the result. **huks.init**, **huks.update**, and **huks.finish** must be used together. -> **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.finishSession9+](#huksfinishsession9-1). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.finishSession9+](#huksfinishsession9-1). **System capability**: SystemCapability.Security.Huks.Extension @@ -3092,7 +3128,9 @@ abort(handle: number, options: HuksOptions, callback: AsyncCallback\ Aborts the use of the key. This API uses an asynchronous callback to return the result. -> **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.abortSession9+](#huksabortsession9). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.abortSession9+](#huksabortsession9). **System capability**: SystemCapability.Security.Huks.Extension @@ -3203,7 +3241,9 @@ abort(handle: number, options: HuksOptions) : Promise\; Aborts the use of the key. This API uses a promise to return the result. -> **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.abortSession9+](#huksabortsession9-1). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [huks.abortSession9+](#huksabortsession9-1). **System capability**: SystemCapability.Security.Huks.Extension @@ -3324,7 +3364,9 @@ function huksAbort() { Defines the HUKS handle structure. **System capability**: SystemCapability.Security.Huks.Extension -> **NOTE**
This API is deprecated since API version 9. You are advised to use [HuksSessionHandle9+](#hukssessionhandle9). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [HuksSessionHandle9+](#hukssessionhandle9). | Name | Type | Mandatory| Description | | ---------- | ---------------- | ---- | -------- | @@ -3338,7 +3380,10 @@ Defines the **HuksResult** structure. **System capability**: SystemCapability.Security.Huks.Extension -> **NOTE**
This API is deprecated since API version 9. You are advised to use [HuksReturnResult9+](#huksreturnresult9). +> **NOTE** +> +> - This API is deprecated since API version 9. You are advised to use [HuksReturnResult9+](#huksreturnresult9). +> - For details about the error codes, see [HUKS Error Codes](../errorcodes/errorcode-huks.md). | Name | Type | Mandatory| Description | | ---------- | ------------------------------- | ---- | ---------------- | @@ -3347,13 +3392,14 @@ Defines the **HuksResult** structure. | properties | Array\<[HuksParam](#huksparam)> | No | Property information. | | certChains | Array\ | No | Certificate chain information.| - ## HuksErrorCode(deprecated) Enumerates the error codes. **System capability**: SystemCapability.Security.Huks.Extension -> **NOTE**
This API is deprecated since API version 9. You are advised to use HuksExceptionErrCode9+](#huksexceptionerrcode9). +> **NOTE** +> +> This API is deprecated since API version 9. You are advised to use [HuksExceptionErrCode9+](#huksexceptionerrcode9). | Name | Value | Description| | -------------------------- | ----- | ---- | diff --git a/en/application-dev/reference/apis/js-apis-inputmethod-subtype.md b/en/application-dev/reference/apis/js-apis-inputmethod-subtype.md index 14a5ed2b9a6fee26af15baabfeb07470e9a0f658..f0a38ede3b18acb04b2286651afa9fe2d9ae8a25 100644 --- a/en/application-dev/reference/apis/js-apis-inputmethod-subtype.md +++ b/en/application-dev/reference/apis/js-apis-inputmethod-subtype.md @@ -18,15 +18,15 @@ import InputMethodSubtype from '@ohos.InputMethodSubtype'; **System capability**: SystemCapability.MiscServices.InputMethodFramework -| Name| Type| Readable| Writable| Mandatory| Description| -| -------- | -------- | -------- | -------- | -------- | -------- | -| label | string | Yes| No| No| Label of the input method subtype.| -| labelId10+ | string | Yes| No| No| Label ID of the input method subtype.| -| name | string | Yes| No| Yes| Bundle name of the input method.| -| id | string | Yes| No| Yes| ID of the input method subtype.| -| mode | string | Yes| No| No| Mode of the input method subtype, including **upper** (uppercase) and **lower** (lowercase).| -| locale | string | Yes| No| Yes| Locale of the input method subtype.| -| language | string | Yes| No| Yes| Language of the input method subtype.| -| icon | string | Yes| No| No| Icon of the input method subtype.| -| iconId | number | Yes| No| No| Icon ID of the input method subtype.| -| extra | object | Yes| Yes| No| Extra information of the input method subtype.
**NOTE**
This parameter is optional since API version 10.| +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| label | string | Yes| No| Optional. Label of the input method subtype.| +| labelId10+ | string | Yes| No| Optional. Label ID of the input method subtype.| +| name | string | Yes| No| Mandatory. Bundle name of the input method.| +| id | string | Yes| No| Mandatory. ID of the input method subtype.| +| mode | string | Yes| No| Optional. Mode of the input method subtype, including **upper** (uppercase) and **lower** (lowercase).| +| locale | string | Yes| No| Mandatory. Locale of the input method subtype.| +| language | string | Yes| No| Mandatory. Language of the input method subtype.| +| icon | string | Yes| No| Optional. Icon of the input method subtype. It can be obtained by using **iconId**. This parameter is reserved.| +| iconId | number | Yes| No| Optional. Icon ID of the input method subtype.| +| extra | object | Yes| Yes| Optional. Extra information of the input method subtype. This parameter is reserved and currently has no specific meaning.
**NOTE**
This parameter is optional since API version 10.| diff --git a/en/application-dev/reference/apis/js-apis-inputmethod.md b/en/application-dev/reference/apis/js-apis-inputmethod.md index 553c448b9a148406d548ae6bae0fcfe864d95eb9..b7f0b58fda7dc1f3c1b79d840d39756db8ceeb29 100644 --- a/en/application-dev/reference/apis/js-apis-inputmethod.md +++ b/en/application-dev/reference/apis/js-apis-inputmethod.md @@ -35,9 +35,9 @@ Describes the input method application attributes. | id9+ | string | Yes| No| Mandatory. Unique ID of the input method.| | label9+ | string | Yes| No| Optional. External name of the input method.| | labelId10+ | string | Yes| No| Optional. External ID of the input method.| -| icon9+ | string | Yes| No| Optional. Icon of the input method.| +| icon9+ | string | Yes| No| Optional. Icon of the input method. It can be obtained by using **iconId**. This parameter is reserved.| | iconId9+ | number | Yes| No| Optional. Icon ID of the input method.| -| extra9+ | object | Yes| Yes| Extra information about the input method.
- API version 10 and later: optional
- API version 9: mandatory| +| extra9+ | object | Yes| Yes| Extra information about the input method. This parameter is reserved and currently has no specific meaning.
- API version 10 and later: optional
- API version 9: mandatory| | packageName(deprecated) | string | Yes| No| Name of the input method package. Mandatory.
**NOTE**
This API is supported since API version 8 and deprecated since API version 9. You are advised to use **name**.| | methodId(deprecated) | string | Yes| No| Unique ID of the input method. Mandatory.
**NOTE**
This API is supported since API version 8 and deprecated since API version 9. You are advised to use **id**.| @@ -154,15 +154,15 @@ Switches to another input method. This API uses a promise to return the result. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -|target | [InputMethodProperty](#inputmethodproperty8)| Yes| Input method to switch to.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + |target | [InputMethodProperty](#inputmethodproperty8)| Yes| Input method to switch to.| **Return value** -| Type | Description | -| ----------------------------------------- | ---------------------------- | -| Promise\ | Promise used to return the result. The value **true** means that the switching is successful, and **false** means the opposite.| + | Type | Description | + | ----------------------------------------- | ---------------------------- | + | Promise\ | Promise used to return the result. The value **true** means that the switching is successful, and **false** means the opposite.| **Error codes** @@ -606,9 +606,12 @@ Describes the configuration of the editor component. When the editor component r **System capability**: SystemCapability.MiscServices.InputMethodFramework -| Name| Type| Readable| Writable| Description| +| Name| Type| Read-only| Mandatory| Description| | -------- | -------- | -------- | -------- | -------- | -| inputAttribute10+ | [InputAttribute](#inputattribute10) | Yes| Yes| Edit box attribute.| +| inputAttribute10+ | [InputAttribute](#inputattribute10) | No| Yes| Edit box attribute.| +| cursorInfo10+ | [CursorInfo](#cursorinfo10) | No| No| Cursor information.| +| selection10+ | [Range](#range10) | No| No| Text selection range.| +| windowId10+ | number | No| No| ID of the window where the editor component is located.| ## CursorInfo10+ @@ -1684,7 +1687,7 @@ try { ### off('insertText')10+ -off(type: 'insertText'): void +off(type: 'insertText', callback?: (text: string) => void): void Disables listening for the text insertion event of the input method. @@ -1692,13 +1695,18 @@ Disables listening for the text insertion event of the input method. **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
The value **'insertText'** indicates the text insertion event.| +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
The value **'insertText'** indicates the text insertion event.| +| callback | (text: string) => void | No | Callback used for disable listening, which must be the same as that passed by the **on** API. If this parameter is not specified, all callbacks corresponding to the set event are invoked.| **Example** ```js +let onInsertTextCallback = (text: string) => { + console.log(`Succeeded in subscribing insertText: ${text}`); +}; +inputMethodController.off('insertText', onInsertTextCallback); inputMethodController.off('insertText'); ``` @@ -1773,7 +1781,7 @@ try { ``` ### off('deleteLeft')10+ -off(type: 'deleteLeft'): void +off(type: 'deleteLeft', callback?: (length: number) => void): void Disables listening for the backward delete event. @@ -1781,19 +1789,24 @@ Disables listening for the backward delete event. **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
The value **'deleteLeft'** indicates the backward delete event.| +| Name | Type | Mandatory| Description | +| -------- | ------------------------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
The value **'deleteLeft'** indicates the backward delete event.| +| callback | (length: number) => void | No | Callback used for disable listening, which must be the same as that passed by the **on** API. If this parameter is not specified, all callbacks corresponding to the set event are invoked.| **Example** ```js +let onDeleteLeftCallback = (length: number) => { + console.log(`Succeeded in subscribing deleteLeft, length: ${length}`); +}; +inputMethodController.off('deleteLeft', onDeleteLeftCallback); inputMethodController.off('deleteLeft'); ``` ### off('deleteRight')10+ -off(type: 'deleteRight'): void +off(type: 'deleteRight', callback?: (length: number) => void): void Disables listening for the forward delete event. @@ -1801,19 +1814,24 @@ Disables listening for the forward delete event. **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
The value **'deleteRight'** indicates the forward delete event.| +| Name | Type | Mandatory| Description | +| -------- | ------------------------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
The value **'deleteRight'** indicates the forward delete event.| +| callback | (length: number) => void | No | Callback used for disable listening, which must be the same as that passed by the **on** API. If this parameter is not specified, all callbacks corresponding to the set event are invoked.| **Example** ```js +let onDeleteRightCallback = (length: number) => { + console.log(`Succeeded in subscribing deleteRight, length: ${length}`); +}; +inputMethodController.off('deleteRight', onDeleteRightCallback); inputMethodController.off('deleteRight'); ``` ### on('sendKeyboardStatus')10+ -on(type: 'sendKeyboardStatus', callback: (keyBoardStatus: KeyboardStatus) => void): void +on(type: 'sendKeyboardStatus', callback: (keyboardStatus: KeyboardStatus) => void): void Enables listening for the keyboard status event of the input method. This API uses an asynchronous callback to return the result. @@ -1824,7 +1842,7 @@ Enables listening for the keyboard status event of the input method. This API us | Name | Type | Mandatory| Description | | -------- | ------ | ---- | ---- | | type | string | Yes | Listening type.
The value **'sendKeyboardStatus'** indicates the keyboard status event.| -| callback | (keyBoardStatus: [KeyboardStatus](#keyboardstatus10)) => void | Yes | Callback used to return the keyboard status.
Your application needs to perform operations based on the keyboard state returned in the callback.| +| callback | (keyboardStatus: [KeyboardStatus](#keyboardstatus10)) => void | Yes | Callback used to return the keyboard status.
Your application needs to perform operations based on the keyboard state returned in the callback.| **Error codes** @@ -1838,8 +1856,8 @@ For details about the error codes, see [Input Method Framework Error Codes](../e ```js try { - inputMethodController.on('sendKeyboardStatus', (keyBoardStatus) => { - console.log(`Succeeded in subscribing sendKeyboardStatus, keyBoardStatus: ${keyBoardStatus}`); + inputMethodController.on('sendKeyboardStatus', (keyboardStatus) => { + console.log(`Succeeded in subscribing sendKeyboardStatus, keyboardStatus: ${keyboardStatus}`); }); } catch(err) { console.error(`Failed to subscribe sendKeyboardStatus: ${JSON.stringify(err)}`); @@ -1848,7 +1866,7 @@ try { ### off('sendKeyboardStatus')10+ -off(type: 'sendKeyboardStatus'): void +off(type: 'sendKeyboardStatus', callback?: (keyboardStatus: KeyboardStatus) => void): void Disables listening for the keyboard status event of the input method. @@ -1856,13 +1874,18 @@ Disables listening for the keyboard status event of the input method. **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
The value **'sendKeyboardStatus'** indicates the keyboard status event.| +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
The value **'sendKeyboardStatus'** indicates the keyboard status event.| +| callback | (keyboardStatus: [KeyboardStatus](#keyboardstatus10)) => void | No | Callback used for disable listening, which must be the same as that passed by the **on** API. If this parameter is not specified, all callbacks corresponding to the set event are invoked.| **Example** ```js +let onSendKeyboardStatus = (keyboardStatus: KeyboardStatus) => { + console.log(`Succeeded in subscribing sendKeyboardStatus, keyboardStatus: ${keyboardStatus}`); +}; +inputMethodController.off('sendKeyboardStatus', onSendKeyboardStatus); inputMethodController.off('sendKeyboardStatus'); ``` @@ -1903,7 +1926,7 @@ try { ### off('sendFunctionKey')10+ -off(type: 'sendFunctionKey'): void +off(type: 'sendFunctionKey', callback?: (functionKey: FunctionKey) => void): void Disables listening for the function key sending event of the input method. @@ -1911,13 +1934,18 @@ Disables listening for the function key sending event of the input method. **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
The value **'sendFunctionKey'** indicates the function key sending event.| +| Name | Type | Mandatory| Description | +| -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
The value **'sendFunctionKey'** indicates the function key sending event.| +| callback | (functionKey: [FunctionKey](#functionkey10)) => void | No | Callback used for disable listening, which must be the same as that passed by the **on** API. If this parameter is not specified, all callbacks corresponding to the set event are invoked.| **Example** ```js +let onSendFunctionKey = (functionKey: FunctionKey) => { + console.log(`Succeeded in subscribing sendFunctionKey, functionKey: ${functionKey.enterKeyType}`); +}; +inputMethodController.off('sendFunctionKey', onSendFunctionKey); inputMethodController.off('sendFunctionKey'); ``` @@ -1958,7 +1986,7 @@ try { ### off('moveCursor')10+ -off(type: 'moveCursor'): void +off(type: 'moveCursor', callback?: (direction: Direction) => void): void Disables listening for the cursor movement event of the input method. @@ -1969,10 +1997,15 @@ Disables listening for the cursor movement event of the input method. | Name | Type | Mandatory| Description | | ------ | ------ | ---- | ---- | | type | string | Yes | Listening type.
The value **'moveCursor'** indicates the cursor movement event.| +| callback | (direction: [Direction10+](#direction10)) => void | No| Callback used for disable listening, which must be the same as that passed by the **on** API. If this parameter is not specified, all callbacks corresponding to the set event are invoked.| **Example** ```js +let onMoveCursorCallback = (direction: Direction) => { + console.log(`Succeeded in subscribing moveCursor, direction: ${direction}`); +}; +inputMethodController.off('moveCursor', onMoveCursorCallback); inputMethodController.off('moveCursor'); ``` @@ -2013,7 +2046,7 @@ try { ### off('handleExtendAction')10+ -off(type: 'handleExtendAction'): void +off(type: 'handleExtendAction', callback?: (action: ExtendAction) => void): void Disables listening for the extended action handling event of the input method. @@ -2024,10 +2057,15 @@ Disables listening for the extended action handling event of the input method. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------- | | type | string | Yes | Listening type.
The value **'handleExtendAction'** indicates the extended action handling event.| +| callback | (action: [ExtendAction](#extendaction10)) => void | No| Callback used for disable listening, which must be the same as that passed by the **on** API. If this parameter is not specified, all callbacks corresponding to the set event are invoked.| **Example** ```js +let onHandleExtendActionCallback = (action: ExtendAction) => { + console.log(`Succeeded in subscribing handleExtendAction, action: ${action}`); +}; +inputMethodController.off('handleExtendAction', onHandleExtendActionCallback); inputMethodController.off('handleExtendAction'); ``` @@ -2056,7 +2094,7 @@ inputMethodController.on('selectByRange', (range) => { ### off('selectByRange')10+ -off(type: 'selectByRange'): void +off(type: 'selectByRange', callback?: Callback<Range>): void Disables listening for the select-by-range event. @@ -2064,13 +2102,18 @@ Disables listening for the select-by-range event. **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
The value **'selectByRange'** indicates the select-by-range event.| +| Name | Type | Mandatory| Description | +| -------- | --------------------------------- | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
The value **'selectByRange'** indicates the select-by-range event.| +| callback | Callback<[Range](#range10)> | No | Callback used for disable listening, which must be the same as that passed by the **on** API. If this parameter is not specified, all callbacks corresponding to the set event are invoked.| **Example** ```js +let onSelectByRangeCallback = (range: Range) => { + console.log(`Succeeded in subscribing selectByRange, range: ${JSON.stringify(range)}`); +}; +inputMethodController.off('selectByRange', onSelectByRangeCallback); inputMethodController.off('selectByRange'); ``` @@ -2099,7 +2142,7 @@ inputMethodController.on('selectByMovement', (movement) => { ### off('selectByMovement')10+ -off(type: 'selectByMovement'): void +off(type: 'selectByMovement', callback?: Callback<Movement>): void Disables listening for the select-by-cursor-movement event. @@ -2107,13 +2150,18 @@ Disables listening for the select-by-cursor-movement event. **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------------------------------------------------------------ | -| type | string | Yes | Listening type.
The value **'selectByMovement'** indicates the select-by-cursor-movement event.| +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
The value **'selectByMovement'** indicates the select-by-cursor-movement event.| +| callback | Callback<[Movement](#movement10)> | No | Callback used for disable listening, which must be the same as that passed by the **on** API. If this parameter is not specified, all callbacks corresponding to the set event are invoked.| **Example** ```js +let onSelectByMovementCallback = (movement: Movement) => { + console.log(`Succeeded in subscribing selectByMovement, movement.direction: ${movement.direction}`); +}; +inputMethodController.off('selectByMovement', onSelectByMovementCallback); inputMethodController.off('selectByMovement'); ``` @@ -2132,6 +2180,14 @@ Enables listening for the event of obtaining the length of text deleted backward | type | string | Yes | Listening type.
The value **'getLeftTextOfCursor'** indicates the event of obtaining the length of text deleted backward.| | callback | (length: number) => string | Yes | Callback used to obtain the text of the specified length deleted backward.
In this callback, obtain the text of the specified length on the left of the cursor in the latest state of the edit box and return the text.| +**Error codes** + +For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). + +| Error Code ID| Error Message | +| -------- | -------------------------------------- | +| 12800009 | input method client is detached. | + **Example** ```js @@ -2150,7 +2206,7 @@ try { off(type: 'getLeftTextOfCursor', callback?: (length: number) => string): void; -Disables listening for the event of obtaining the length of text deleted backward. This API uses an asynchronous callback to return the result. +Disables listening for the event of obtaining the length of text deleted backward. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -2190,6 +2246,14 @@ Enables listening for the event of obtaining the length of text deleted forward. | type | string | Yes | Listening type.
The value **'getRightTextOfCursor'** indicates the event of obtaining the length of text deleted forward.| | callback | (length: number) => string | Yes | Callback used to obtain the text of the specified length deleted forward.
In this callback, obtain the text of the specified length on the right of the cursor in the latest state of the edit box and return the text.| +**Error codes** + +For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). + +| Error Code ID| Error Message | +| -------- | -------------------------------------- | +| 12800009 | input method client is detached. | + **Example** ```js @@ -2208,7 +2272,7 @@ try { off(type: 'getRightTextOfCursor', callback?: (length: number) => string): void; -Disables listening for the event of obtaining the length of text deleted forward. This API uses an asynchronous callback to return the result. +Disables listening for the event of obtaining the length of text deleted forward. **System capability**: SystemCapability.MiscServices.InputMethodFramework @@ -2248,6 +2312,14 @@ Enables listening for the event of obtaining the index of text at the cursor. Th | type | string | Yes | Listening type.
The value **'getTextIndexAtCursor'** indicates the event of obtaining the index of text at the cursor.| | callback | () => number | Yes | Callback used to obtain the index of text at the cursor.
In this callback, obtain the index of text at the cursor in the latest state of the edit box and return the index.| +**Error codes** + +For details about the error codes, see [Input Method Framework Error Codes](../errorcodes/errorcode-inputmethod-framework.md). + +| Error Code ID| Error Message | +| -------- | -------------------------------------- | +| 12800009 | input method client is detached. | + **Example** ```js @@ -2266,7 +2338,7 @@ try { off(type: 'getTextIndexAtCursor', callback?: () => number): void; -Disables listening for the event of obtaining the index of text at the cursor. This API uses an asynchronous callback to return the result. +Disables listening for the event of obtaining the index of text at the cursor. **System capability**: SystemCapability.MiscServices.InputMethodFramework diff --git a/en/application-dev/reference/apis/js-apis-inputmethodengine.md b/en/application-dev/reference/apis/js-apis-inputmethodengine.md index 36e504d702912c310765d0afc448ebffc9a34517..7b8283d50367e9cd121bd84c714347992e6e1bb7 100644 --- a/en/application-dev/reference/apis/js-apis-inputmethodengine.md +++ b/en/application-dev/reference/apis/js-apis-inputmethodengine.md @@ -923,6 +923,50 @@ inputMethodEngine.getKeyboardDelegate().off('textChange', (text) => { }); ``` +### on('editorAttributeChanged')10+ + +on(type: 'editorAttributeChanged', callback: (attr: EditorAttribute) => void): void + +Enables listening for the edit box attribute change event. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
The value **'editorAttributeChanged'** indicates the edit box attribute change event.| +| callback | (attr: EditorAttribute) => void | Yes | Callback used to return the edit box attribute change.| + +**Example** + +```js +inputMethodEngine.getKeyboardDelegate().on('editorAttributeChanged', (attr) => { + console.log(`Succeeded in receiving attribute of editor, inputPattern = ${attr.inputPattern}, enterKeyType = ${attr.enterKeyType}`); +}); +``` + +### off('editorAttributeChanged')10+ + +off(type: 'editorAttributeChanged', callback?: (attr: EditorAttribute) => void): void + +Cancels listening for the edit box attribute change event. + +**System capability**: SystemCapability.MiscServices.InputMethodFramework + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| type | string | Yes | Listening type.
The value **'editorAttributeChanged'** indicates the edit box attribute change event.| +| callback | (attr: EditorAttribute) => void | No | Callback for the edit box attribute change event. It must correspond to the one in the **on** API.| + +**Example** + +```js +inputMethodEngine.getKeyboardDelegate().off('editorAttributeChanged'); +``` + ## Panel10+ In the following API examples, you must first use **[createPanel](#createpanel10)** to obtain a **Panel** instance, and then call the APIs using the obtained instance. diff --git a/en/application-dev/reference/apis/js-apis-intl.md b/en/application-dev/reference/apis/js-apis-intl.md index 99131363c58faef8abe196d0e20e01b176a1258e..57a49408d7da9e24242b879b6bf902c53606216b 100644 --- a/en/application-dev/reference/apis/js-apis-intl.md +++ b/en/application-dev/reference/apis/js-apis-intl.md @@ -14,7 +14,6 @@ The [i18n](js-apis-i18n.md) module provides enhanced i18n capabilities through s ```js import Intl from '@ohos.intl'; ``` -Importing an incorrect bundle can lead to unexpected API behavior. ## Locale @@ -34,7 +33,7 @@ Importing an incorrect bundle can lead to unexpected API behavior. | collation | string | Yes | No | Rule for sorting regions. The value can be any of the following: **big5han**, **compat**, **dict**, **direct**, **ducet**, **eor**, **gb2312**, **phonebk**, **phonetic**, **pinyin**, **reformed**, **searchjl**, **stroke**, **trad**, **unihan**, **zhuyin**.| | hourCycle | string | Yes | No | Time system for the locale. The value can be any of the following: **h12**, **h23**, **h11**, or **h24**.| | numberingSystem | string | Yes | No | Numbering system for the locale. The value can be any of the following: **adlm**, **ahom**, **arab**, **arabext**, **bali**, **beng**, **bhks**, **brah**, **cakm**, **cham**, **deva**, **diak**, **fullwide**, **gong**, **gonm**, **gujr**, **guru**, **hanidec**, **hmng**, **hmnp**, **java**, **kali**, **khmr**, **knda**, **lana**, **lanatham**, **laoo**, **latn**, **lepc**, **limb**, **mathbold**, **mathdbl**, **mathmono**, **mathsanb**, **mathsans**, **mlym**, **modi**, **mong**, **mroo**, **mtei**, **mymr**, **mymrshan**, **mymrtlng**, **newa**, **nkoo**, **olck**, **orya**, **osma**, **rohg**, **saur**, **segment**, **shrd**, **sind**, **sinh**, **sora**, **sund**, **takr**, **talu**, **tamldec**, **telu**, **thai**, **tibt**, **tirh**, **vaii**, **wara**, **wcho**.| -| numeric | boolean | Yes | No | Whether to apply special collation rules for numeric characters. | +| numeric | boolean | Yes | No | Whether to apply special collation rules for numeric characters. The default value is **false**. | ### constructor8+ @@ -67,7 +66,7 @@ Creates a **Locale** object. | Name | Type | Mandatory | Description | | -------------------- | -------------------------------- | ---- | ---------------------------- | | locale | string | Yes | A string containing locale information, including the language, optional script, and region. For details about the international standards and combination modes for the language, script, and country or region, see [intl Development](../../internationalization/intl-guidelines.md#setting-locale-information).| -| options | [LocaleOptions](#localeoptions6) | No | Options for creating the **Locale** object. | +| options | [LocaleOptions](#localeoptions6) | No | Options for creating the **Locale** object.| **Example** ```js @@ -162,7 +161,7 @@ Minimizes information of the **Locale** object. If the script and locale informa ## LocaleOptions6+ Represents the locale options. -In API version 9, the attributes in **LocaleOptions** are optional. +Since API version 9, the attributes in **LocaleOptions** are optional. **System capability**: SystemCapability.Global.I18n @@ -172,7 +171,7 @@ In API version 9, the attributes in **LocaleOptions** are optional. | collation | string | Yes | Yes | Collation rule. The value can be any of the following: **big5han**, **compat**, **dict**, **direct**, **ducet**, **emoji**, **eor**, **gb2312**, **phonebk**, **phonetic**, **pinyin**, **reformed**, **search**, **searchjl**, **standard**, **stroke**, **trad**, **unihan**, **zhuyin**.| | hourCycle | string | Yes | Yes | Time system for the locale. The value can be any of the following: **h11**, **h12**, **h23**, or **h24**.| | numberingSystem | string | Yes | Yes | Numbering system for the locale. The value can be any of the following: **adlm**, **ahom**, **arab**, **arabext**, **bali**, **beng**, **bhks**, **brah**, **cakm**, **cham**, **deva**, **diak**, **fullwide**, **gong**, **gonm**, **gujr**, **guru**, **hanidec**, **hmng**, **hmnp**, **java**, **kali**, **khmr**, **knda**, **lana**, **lanatham**, **laoo**, **latn**, **lepc**, **limb**, **mathbold**, **mathdbl**, **mathmono**, **mathsanb**, **mathsans**, **mlym**, **modi**, **mong**, **mroo**, **mtei**, **mymr**, **mymrshan**, **mymrtlng**, **newa**, **nkoo**, **olck**, **orya**, **osma**, **rohg**, **saur**, **segment**, **shrd**, **sind**, **sinh**, **sora**, **sund**, **takr**, **talu**, **tamldec**, **telu**, **thai**, **tibt**, **tirh**, **vaii**, **wara**, **wcho**.| -| numeric | boolean | Yes | Yes | Whether to use the 12-hour clock. | +| numeric | boolean | Yes | Yes | Whether to use the 12-hour clock. The default value is **false**. | | caseFirst | string | Yes | Yes | Whether upper case or lower case is sorted first. The value can be **upper**, **lower**, or **false**.| @@ -207,7 +206,7 @@ Creates a **DateTimeOptions** object for the specified locale. | Name | Type | Mandatory | Description | | -------------------- | ------------------------------------ | ---- | ---------------------------- | | locale | string \| Array<string> | Yes | A string containing locale information, including the language, optional script, and region.| -| options | [DateTimeOptions](#datetimeoptions6) | No | Options for creating a **DateTimeFormat** object. | +| options | [DateTimeOptions](#datetimeoptions6) | No | Options for creating a **DateTimeFormat** object. If no options are set, the default values of **year**, **month**, and **day** are **numeric**.| **Example** ```js @@ -314,7 +313,7 @@ Obtains the formatting options for **DateTimeFormat** object. ## DateTimeOptions6+ Provides the options for the **DateTimeFormat** object. -In API version 9, the attributes in **DateTimeOptions** are optional. +Since API version 9, the attributes in **DateTimeOptions** are optional. **System capability**: SystemCapability.Global.I18n @@ -326,7 +325,7 @@ In API version 9, the attributes in **DateTimeOptions** are optional. | hourCycle | string | Yes | Yes | Time system for the locale. The value can be any of the following: **h11**, **h12**, **h23**, or **h24**.| | timeZone | string | Yes | Yes | Time zone represented by a valid IANA time zone ID. | | numberingSystem | string | Yes | Yes | Numbering system for the locale. The value can be any of the following: **adlm**, **ahom**, **arab**, **arabext**, **bali**, **beng**, **bhks**, **brah**, **cakm**, **cham**, **deva**, **diak**, **fullwide**, **gong**, **gonm**, **gujr**, **guru**, **hanidec**, **hmng**, **hmnp**, **java**, **kali**, **khmr**, **knda**, **lana**, **lanatham**, **laoo**, **latn**, **lepc**, **limb**, **mathbold**, **mathdbl**, **mathmono**, **mathsanb**, **mathsans**, **mlym**, **modi**, **mong**, **mroo**, **mtei**, **mymr**, **mymrshan**, **mymrtlng**, **newa**, **nkoo**, **olck**, **orya**, **osma**, **rohg**, **saur**, **segment**, **shrd**, **sind**, **sinh**, **sora**, **sund**, **takr**, **talu**, **tamldec**, **telu**, **thai**, **tibt**, **tirh**, **vaii**, **wara**, **wcho**.| -| hour12 | boolean | Yes | Yes | Whether to use the 12-hour clock. | +| hour12 | boolean | Yes | Yes | Whether to use the 12-hour clock. If **hour12** and **hourCycle** are not set and the 24-hour clock is turned on, the default value of **hour12** is **false**. | | weekday | string | Yes | Yes | Workday display format. The value can be **long**, **short**, or **narrow**.| | era | string | Yes | Yes | Era display format. The value can be **long**, **short**, or **narrow**.| | year | string | Yes | Yes | Year display format. The value can be **numeric** or **2-digit**. | @@ -438,31 +437,31 @@ Obtains the options of the **NumberFormat** object. ## NumberOptions6+ Defines the device capability. -In API version 9, the attributes in **NumberOptions** are optional. +Since API version 9, the attributes in **NumberOptions** are optional. **System capability**: SystemCapability.Global.I18n | Name | Type | Readable | Writable | Description | | ------------------------ | ------- | ---- | ---- | ---------------------------------------- | -| locale | string | Yes | No | Locale, for example, **zh-Hans-CN**. | +| locale | string | Yes | No | Locale, for example, **zh-Hans-CN**. The default value is the system locale. | | currency | string | Yes | Yes | Currency unit, for example, **EUR**, **CNY**, or **USD**. | -| currencySign | string | Yes | Yes | Currency unit symbol. The value can be **symbol**, **narrowSymbol**, **code**, or **name**.| -| currencyDisplay | string | Yes | Yes | Currency display mode. The value can be **symbol**, **narrowSymbol**, **code**, or **name**.| +| currencySign | string | Yes | Yes | Currency unit symbol. The value can be **symbol**, **narrowSymbol**, **code**, or **name**. The default value is **symbol**.| +| currencyDisplay | string | Yes | Yes | Currency display mode. The value can be **symbol**, **narrowSymbol**, **code**, or **name**. The default value is **symbol**.| | unit | string | Yes | Yes | Unit name, for example, **meter**, **inch**, or **hectare**. | -| unitDisplay | string | Yes | Yes | Unit display format. The value can be **long**, **short**, or **narrow**.| -| unitUsage8+ | string | Yes | Yes | Unit usage scenario. The value can be any of the following: **default**, **area-land-agricult**, **area-land-commercl**, **area-land-residntl**, **length-person**, **length-person-small**, **length-rainfall**, **length-road**, **length-road-small**, **length-snowfall**, **length-vehicle**, **length-visiblty**, **length-visiblty-small**, **length-person-informal**, **length-person-small-informal**, **length-road-informal**, **speed-road-travel**, **speed-wind**, **temperature-person**, **temperature-weather**, **volume-vehicle-fuel**.| -| signDisplay | string | Yes | Yes | Number sign display format. The value can be **auto**, **never**, **always**, or **expectZero**.| -| compactDisplay | string | Yes | Yes | Compact display format. The value can be **long** or **short**. | -| notation | string | Yes | Yes | Number formatting specification. The value can be **standard**, **scientific**, **engineering**, or **compact**.| -| localeMatcher | string | Yes | Yes | Locale matching algorithm. The value can be **lookup** or **best fit**.| -| style | string | Yes | Yes | Number display format. The value can be **decimal**, **currency**, **percent**, or **unit**.| -| numberingSystem | string | Yes | Yes | Numbering system for the locale. The value can be any of the following: **adlm**, **ahom**, **arab**, **arabext**, **bali**, **beng**, **bhks**, **brah**, **cakm**, **cham**, **deva**, **diak**, **fullwide**, **gong**, **gonm**, **gujr**, **guru**, **hanidec**, **hmng**, **hmnp**, **java**, **kali**, **khmr**, **knda**, **lana**, **lanatham**, **laoo**, **latn**, **lepc**, **limb**, **mathbold**, **mathdbl**, **mathmono**, **mathsanb**, **mathsans**, **mlym**, **modi**, **mong**, **mroo**, **mtei**, **mymr**, **mymrshan**, **mymrtlng**, **newa**, **nkoo**, **olck**, **orya**, **osma**, **rohg**, **saur**, **segment**, **shrd**, **sind**, **sinh**, **sora**, **sund**, **takr**, **talu**, **tamldec**, **telu**, **thai**, **tibt**, **tirh**, **vaii**, **wara**, **wcho**.| -| useGrouping | boolean | Yes | Yes | Whether to use grouping for display. | -| minimumIntegerDigits | number | Yes | Yes | Minimum number of digits allowed in the integer part of a number. The value ranges from **1** to **21**. | -| minimumFractionDigits | number | Yes | Yes | Minimum number of digits in the fraction part of a number. The value ranges from **0** to **20**. | -| maximumFractionDigits | number | Yes | Yes | Maximum number of digits in the fraction part of a number. The value ranges from **1** to **21**. | -| minimumSignificantDigits | number | Yes | Yes | Minimum number of the least significant digits. The value ranges from **1** to **21**. | -| maximumSignificantDigits | number | Yes | Yes | Maximum number of the least significant digits. The value ranges from **1** to **21**. | +| unitDisplay | string | Yes | Yes | Unit display format. The value can be **long**, **short**, or **narrow**. The default value is **short**.| +| unitUsage8+ | string | Yes | Yes | Unit usage scenario. The value can be any of the following: **default**, **area-land-agricult**, **area-land-commercl**, **area-land-residntl**, **length-person**, **length-person-small**, **length-rainfall**, **length-road**, **length-road-small**, **length-snowfall**, **length-vehicle**, **length-visiblty**, **length-visiblty-small**, **length-person-informal**, **length-person-small-informal**, **length-road-informal**, **speed-road-travel**, **speed-wind**, **temperature-person**, **temperature-weather**, **volume-vehicle-fuel**. The default value is **default**.| +| signDisplay | string | Yes | Yes | Number sign display format. The value can be **auto**, **never**, **always**, or **expectZero**. The default value is **auto**.| +| compactDisplay | string | Yes | Yes | Compact display format. The value can be **long** or **short**. The default value is **short**. | +| notation | string | Yes | Yes | Number formatting specification. The value can be **standard**, **scientific**, **engineering**, or **compact**. The default value is **standard**.| +| localeMatcher | string | Yes | Yes | Locale matching algorithm. The value can be **lookup** or **best fit**. The default value is **best fit**.| +| style | string | Yes | Yes | Number display format. The value can be **decimal**, **currency**, **percent**, or **unit**. The default value is **decimal**.| +| numberingSystem | string | Yes | Yes | Numbering system for the locale. The value can be any of the following: **adlm**, **ahom**, **arab**, **arabext**, **bali**, **beng**, **bhks**, **brah**, **cakm**, **cham**, **deva**, **diak**, **fullwide**, **gong**, **gonm**, **gujr**, **guru**, **hanidec**, **hmng**, **hmnp**, **java**, **kali**, **khmr**, **knda**, **lana**, **lanatham**, **laoo**, **latn**, **lepc**, **limb**, **mathbold**, **mathdbl**, **mathmono**, **mathsanb**, **mathsans**, **mlym**, **modi**, **mong**, **mroo**, **mtei**, **mymr**, **mymrshan**, **mymrtlng**, **newa**, **nkoo**, **olck**, **orya**, **osma**, **rohg**, **saur**, **segment**, **shrd**, **sind**, **sinh**, **sora**, **sund**, **takr**, **talu**, **tamldec**, **telu**, **thai**, **tibt**, **tirh**, **vaii**, **wara**, **wcho**. The default value is the default numbering system of the specified locale.| +| useGrouping | boolean | Yes | Yes | Whether to use grouping for display. The default value is **auto**. | +| minimumIntegerDigits | number | Yes | Yes | Minimum number of digits allowed in the integer part of a number. The value ranges from **1** to **21**. The default value of is **1**. | +| minimumFractionDigits | number | Yes | Yes | Minimum number of digits in the fraction part of a number. The value ranges from **0** to **20**. The default value is **0**. | +| maximumFractionDigits | number | Yes | Yes | Maximum number of digits in the fraction part of a number. The value ranges from **1** to **21**. The default value is **3**. | +| minimumSignificantDigits | number | Yes | Yes | Minimum number of the least significant digits. The value ranges from **1** to **21**. The default value of is **1**. | +| maximumSignificantDigits | number | Yes | Yes | Maximum number of the least significant digits. The value ranges from **1** to **21**. The default value is **21**. | ## Collator8+ @@ -496,7 +495,7 @@ Creates a **Collator** object. | Name | Type | Mandatory | Description | | -------------------- | ------------------------------------ | ---- | ---------------------------- | | locale | string \| Array<string> | Yes | A string containing locale information, including the language, optional script, and region.| -| options | [CollatorOptions](#collatoroptions8) | No | Options for creating a **Collator** object. | +| options | [CollatorOptions](#collatoroptions8) | No | Options for creating a **Collator** object. | **Example** ```js @@ -562,19 +561,19 @@ Returns properties reflecting the locale and collation options of a **Collator** ## CollatorOptions8+ Represents the properties of a **Collator** object. -In API version 9, the attributes in **CollatorOptions** are optional. +Since API version 9, the attributes in **CollatorOptions** are optional. **System capability**: SystemCapability.Global.I18n | Name | Type | Readable | Writable | Description | | ----------------- | ------- | ---- | ---- | ---------------------------------------- | -| localeMatcher | string | Yes | Yes | Locale matching algorithm. The value can be **lookup** or **best fit**.| -| usage | string | Yes | Yes | Whether the comparison is for sorting or for searching. The value can be **sort** or **search**. | -| sensitivity | string | Yes | Yes | Differences in the strings that lead to non-zero return values. The value can be **base**, **accent**, **case**, or **letiant**.| -| ignorePunctuation | boolean | Yes | Yes | Whether punctuation is ignored. The value can be **true** or **false**. | -| collation | string | Yes | Yes | Rule for sorting regions. The value can be any of the following: **big5han**, **compat**, **dict**, **direct**, **ducet**, **eor**, **gb2312**, **phonebk**, **phonetic**, **pinyin**, **reformed**, **searchjl**, **stroke**, **trad**, **unihan**, **zhuyin**.| -| numeric | boolean | Yes | Yes | Whether numeric collation is used. The value can be **true** or **false**. | -| caseFirst | string | Yes | Yes | Whether upper case or lower case is sorted first. The value can be **upper**, **lower**, or **false**.| +| localeMatcher | string | Yes | Yes | Locale matching algorithm. The value can be **lookup** or **best fit**. The default value is **best fit**.| +| usage | string | Yes | Yes | Whether the comparison is for sorting or for searching. The value can be **sort** or **search**. The default value is **sort**. | +| sensitivity | string | Yes | Yes | Differences in the strings that lead to non-zero return values. The value can be **base**, **accent**, **case**, or **letiant**. The default value is **variant**.| +| ignorePunctuation | boolean | Yes | Yes | Whether punctuation is ignored. The value can be **true** or **false**. The default value is **false**. | +| collation | string | Yes | Yes | Rule for sorting regions. The value can be any of the following: **big5han**, **compat**, **dict**, **direct**, **ducet**, **eor**, **gb2312**, **phonebk**, **phonetic**, **pinyin**, **reformed**, **searchjl**, **stroke**, **trad**, **unihan**, **zhuyin**. The default value is **default**.| +| numeric | boolean | Yes | Yes | Whether numeric collation is used. The value can be **true** or **false**. The default value is **false**. | +| caseFirst | string | Yes | Yes | Whether upper case or lower case is sorted first. The value can be **upper**, **lower**, or **false**. The default value is **false**.| ## PluralRules8+ @@ -608,7 +607,7 @@ Creates a **PluralRules** object to obtain the singular-plural type of numbers. | Name | Type | Mandatory | Description | | -------------------- | ---------------------------------------- | ---- | ---------------------------- | | locale | string \| Array<string> | Yes | A string containing locale information, including the language, optional script, and region.| -| options | [PluralRulesOptions](#pluralrulesoptions8) | No | Options for creating a **PluralRules** object. | +| options | [PluralRulesOptions](#pluralrulesoptions8) | No | Options for creating a **PluralRules** object. | **Example** ```js @@ -654,19 +653,19 @@ Obtains a string that represents the singular-plural type of the specified numbe ## PluralRulesOptions8+ Represents the properties of a **PluralRules** object. -In API version 9, the attributes in **PluralRulesOptions** are optional. +Since API version 9, the attributes in **PluralRulesOptions** are optional. **System capability**: SystemCapability.Global.I18n | Name | Type | Readable | Writable | Description | | ------------------------ | ------ | ---- | ---- | ---------------------------------------- | -| localeMatcher | string | Yes | Yes | Locale matching algorithm. The value can be **lookup** or **best fit**.| -| type | string | Yes | Yes | Sorting type. The value can be **cardinal** or **ordinal**. | -| minimumIntegerDigits | number | Yes | Yes | Minimum number of digits allowed in the integer part of a number. The value ranges from **1** to **21**. | -| minimumFractionDigits | number | Yes | Yes | Minimum number of digits in the fraction part of a number. The value ranges from **0** to **20**. | -| maximumFractionDigits | number | Yes | Yes | Maximum number of digits in the fraction part of a number. The value ranges from **1** to **21**. | -| minimumSignificantDigits | number | Yes | Yes | Minimum number of the least significant digits. The value ranges from **1** to **21**. | -| maximumSignificantDigits | number | Yes | Yes | Maximum number of the least significant digits. The value ranges from **1** to **21**. | +| localeMatcher | string | Yes | Yes | Locale matching algorithm. The value can be **lookup** or **best fit**. The default value is **best fit**.| +| type | string | Yes | Yes | Sorting type. The value can be **cardinal** or **ordinal**. The default value is **cardinal**. | +| minimumIntegerDigits | number | Yes | Yes | Minimum number of digits allowed in the integer part of a number. The value ranges from **1** to **21**. The default value of is **1**. | +| minimumFractionDigits | number | Yes | Yes | Minimum number of digits in the fraction part of a number. The value ranges from **0** to **20**. The default value is **0**. | +| maximumFractionDigits | number | Yes | Yes | Maximum number of digits in the fraction part of a number. The value ranges from **1** to **21**. The default value is **3**. | +| minimumSignificantDigits | number | Yes | Yes | Minimum number of the least significant digits. The value ranges from **1** to **21**. The default value of is **1**. | +| maximumSignificantDigits | number | Yes | Yes | Maximum number of the least significant digits. The value ranges from **1** to **21**. The default value is **21**. | ## RelativeTimeFormat8+ @@ -795,15 +794,14 @@ Obtains the formatting options for **RelativeTimeFormat** objects. ## RelativeTimeFormatInputOptions8+ Represents the properties of a **RelativeTimeFormat** object. -In API version 9, the attributes in **RelativeTimeFormatInputOptions** are optional. +Since API version 9, the attributes in **RelativeTimeFormatInputOptions** are optional. **System capability**: SystemCapability.Global.I18n - | Name | Type | Readable | Writable | Description | | ------------- | ------ | ---- | ---- | ---------------------------------------- | -| localeMatcher | string | Yes | Yes | Locale matching algorithm. The value can be **lookup** or **best fit**.| -| numeric | string | Yes | Yes | Format of the output message. The value can be **always** or **auto**. | -| style | string | Yes | Yes | Length of an internationalized message. The value can be **long**, **short**, or **narrow**.| +| localeMatcher | string | Yes | Yes | Locale matching algorithm. The value can be **lookup** or **best fit**. The default value is **best fit**.| +| numeric | string | Yes | Yes | Format of the output message. The value can be **always** or **auto**. The default value is **always**. | +| style | string | Yes | Yes | Length of an internationalized message. The value can be **long**, **short**, or **narrow**. The default value is **long**.| ## RelativeTimeFormatResolvedOptions8+ diff --git a/en/application-dev/reference/apis/js-apis-mindSporeLite.md b/en/application-dev/reference/apis/js-apis-mindSporeLite.md index 6a80afa3976c1ee8c4fdce9e3ffa0e1288fdd62c..715e85272a6ee38728f675d0ac6c13eb388631f2 100644 --- a/en/application-dev/reference/apis/js-apis-mindSporeLite.md +++ b/en/application-dev/reference/apis/js-apis-mindSporeLite.md @@ -1,7 +1,7 @@ # @ohos.ai.mindSporeLite (Inference) MindSpore Lite is an AI engine that implements AI model inference for different hardware devices. It has been used in a wide range of fields, such as image classification, target recognition, facial recognition, and character recognition. -The **mindSporeLite** module provides APIs for the MindSpore Lite inference engine to implment model inference. +The **mindSporeLite** module provides APIs for the MindSpore Lite inference engine to implement model inference. > **NOTE** > @@ -48,7 +48,7 @@ Defines the CPU backend device option. | threadNum | number | Yes | Yes | Number of runtime threads. The default value is **2**. | | threadAffinityMode | [ThreadAffinityMode](#threadaffinitymode) | Yes | Yes | Affinity mode for binding runtime threads to CPU cores. The default value is **mindSporeLite.ThreadAffinityMode.NO_AFFINITIES**.| | threadAffinityCoreList | number[] | Yes | Yes | List of CPU cores bound to runtime threads. Set this parameter only when **threadAffinityMode** is set. If **threadAffinityMode** is set to **mindSporeLite.ThreadAffinityMode.NO_AFFINITIES**, this parameter is empty. The number in the list indicates the SN of the CPU core. The default value is **[]**.| -| precisionMode | string | Yes | Yes | Whether to enable the Float16 inference mode. The value **preferred_fp16** means to enable half-precision inference and the default value **force_fp32** means to disable half-precision inference. Other settings are not supported.| +| precisionMode | string | Yes | Yes | Whether to enable the Float16 inference mode. The value **preferred_fp16** means to enable half-precision inference and the default value **enforce_fp32** means to disable half-precision inference. Other settings are not supported.| **Float16 inference mode**: a mode that uses half-precision inference. Float16 uses 16 bits to represent a number and therefore it is also called half-precision. @@ -125,7 +125,7 @@ Loads the input model from the full path for model inference. This API uses an a ```js let context: mindSporeLite.Context = {}; -let context = {'target': ['cpu']}; +context = {'target': ['cpu']}; let model_file = '/path/to/xxx.ms'; mindSporeLite.loadModelFromFile(model_file, context, (result) => { const modelInputs = result.getInputs(); @@ -181,17 +181,17 @@ Loads the input model from the memory for inference. This API uses an asynchrono ```js import resourceManager from '@ohos.resourceManager' -@State modelName: string = 'xxx.ms'; +let modelName = '/path/to/xxx.ms'; let syscontext = globalThis.context; -syscontext.resourceManager.getRawFileContent(this.modelName).then((buffer) => { - this.modelBuffer = buffer; +syscontext.resourceManager.getRawFileContent(modelName).then((buffer) => { + let modelBuffer = buffer; + mindSporeLite.loadModelFromBuffer(modelBuffer.buffer, (result) => { + const modelInputs = result.getInputs(); + console.log(modelInputs[0].name); + }) }).catch(error => { console.error('Failed to get buffer, error code: ${error.code},message:${error.message}.'); }) -mindSporeLite.loadModelFromBuffer(this.modelBuffer.buffer, (result) => { - const modelInputs = result.getInputs(); - console.log(modelInputs[0].name); -}) ``` ## mindSporeLite.loadModelFromBuffer @@ -213,19 +213,19 @@ Loads the input model from the memory for inference. This API uses an asynchrono ```js import resourceManager from '@ohos.resourceManager' -@State modelName: string = 'xxx.ms'; +let modelName = '/path/to/xxx.ms'; let syscontext = globalThis.context; -syscontext.resourceManager.getRawFileContent(this.modelName).then((error,buffer) => { - this.modelBuffer = buffer; +syscontext.resourceManager.getRawFileContent(modelName).then((error,buffer) => { + let modelBuffer = buffer; + let context: mindSporeLite.Context = {}; + context = {'target': ['cpu']}; + mindSporeLite.loadModelFromBuffer(modelBuffer.buffer, context, (result) => { + const modelInputs = result.getInputs(); + console.log(modelInputs[0].name); + }) }).catch(error => { console.error('Failed to get buffer, error code: ${error.code},message:${error.message}.'); }) -let context: mindSporeLite.Context = {}; -context = {'target': ['cpu']}; -mindSporeLite.loadModelFromBuffer(this.modelBuffer.buffer, context, (result) => { - const modelInputs = result.getInputs(); - console.log(modelInputs[0].name); -}) ``` ## mindSporeLite.loadModelFromBuffer @@ -252,17 +252,17 @@ Loads the input model from the memory for inference. This API uses a promise to ```js import resourceManager from '@ohos.resourceManager' -@State modelName: string = 'xxx.ms'; +let modelName = '/path/to/xxx.ms'; let syscontext = globalThis.context; -syscontext.resourceManager.getRawFileContent(this.modelName).then((buffer) => { - this.modelBuffer = buffer; +syscontext.resourceManager.getRawFileContent(modelName).then((buffer) => { + let modelBuffer = buffer; + mindSporeLite.loadModelFromBuffer(modelBuffer.buffer).then((result) => { + const modelInputs = result.getInputs(); + console.log(modelInputs[0].name); + }) }).catch(error => { console.error('Failed to get buffer, error code: ${error.code},message:${error.message}.'); }) -mindSporeLite.loadModelFromBuffer(model_file).then((result) => { - const modelInputs = result.getInputs(); - console.log(modelInputs[0].name); -}) ``` ## mindSporeLite.loadModelFromFd @@ -284,7 +284,7 @@ Loads the input model based on the specified file descriptor for inference. This ```js import fs from '@ohos.file.fs'; let model_file = '/path/to/xxx.ms'; -let file = await fs.open(model_file, 0); +let file = fs.openSync(model_file, fs.OpenMode.READ_ONLY); mindSporeLite.loadModelFromFd(file.fd, (result) => { const modelInputs = result.getInputs(); console.log(modelInputs[0].name); @@ -313,7 +313,7 @@ import fs from '@ohos.file.fs'; let model_file = '/path/to/xxx.ms'; let context : mindSporeLite.Context = {}; context = {'target': ['cpu']}; -let file = await fs.open(model_file, 0); +let file = fs.openSync(model_file, fs.OpenMode.READ_ONLY); mindSporeLite.loadModelFromFd(file.fd, context, (result) => { const modelInputs = result.getInputs(); console.log(modelInputs[0].name); @@ -345,7 +345,7 @@ Loads the input model based on the specified file descriptor for inference. This ```js import fs from '@ohos.file.fs'; let model_file = '/path/to/xxx.ms'; -let file = await fs.open(model_file, 0); +let file = fs.openSync(model_file, fs.OpenMode.READ_ONLY); let mindSporeLiteModel = await mindSporeLite.loadModelFromFd(file.fd); mindSporeLite.loadModelFromFd(file.fd).then((result) => { const modelInputs = result.getInputs(); @@ -383,9 +383,9 @@ mindSporeLite.loadModelFromFile(model_file).then((result) => { ``` ### predict -predict(inputs: MSTensor[], callback: Callback<Model>): void +predict(inputs: MSTensor[], callback: Callback<MSTensor[]>): void -Executes the inference model. This API uses an asynchronous callback to return the result. +Executes the inference model. This API uses an asynchronous callback to return the result. Ensure that the model object is not reclaimed when being invoked. **System capability**: SystemCapability.AI.MindSporeLite @@ -394,20 +394,20 @@ Executes the inference model. This API uses an asynchronous callback to return t | Name| Type | Mandatory| Description | | ------ | ----------------------- | ---- | -------------------------- | | inputs | [MSTensor](#mstensor)[] | Yes | Model input, which is an **MSTensor** object.| -| callback | Callback<[Model](#model)> | Yes | Callback used to return the result, which is a **Model** object.| +| callback | Callback<[MSTensor](#mstensor)[]> | Yes | Callback used to return the result, **MSTensor** object.| **Example** ```js import resourceManager from '@ohos.resourceManager' -@State inputName: string = 'input_data.bin'; +let inputName = 'input_data.bin'; let syscontext = globalThis.context; -syscontext.resourceManager.getRawFileContent(this.inputName).then((buffer) => { - this.inputBuffer = buffer; +syscontext.resourceManager.getRawFileContent(inputName).then(async (buffer) => { + let inputBuffer = buffer; let model_file = '/path/to/xxx.ms'; let mindSporeLiteModel = await mindSporeLite.loadModelFromFile(model_file); const modelInputs = mindSporeLiteModel.getInputs(); - modelInputs[0].setData(this.inputBuffer.buffer); + modelInputs[0].setData(inputBuffer.buffer); result.predict(modelInputs, (result) => { let output = new Float32Array(result[0].getData()); for (let i = 0; i < output.length; i++) { @@ -420,7 +420,7 @@ syscontext.resourceManager.getRawFileContent(this.inputName).then((buffer) => { predict(inputs: MSTensor[]): Promise<MSTensor[]> -Executes the inference model. This API uses a promise to return the result. +Executes the inference model. This API uses a promise to return the result. Ensure that the model object is not reclaimed when being invoked. **System capability**: SystemCapability.AI.MindSporeLite @@ -440,14 +440,14 @@ Executes the inference model. This API uses a promise to return the result. ```js import resourceManager from '@ohos.resourceManager' -@State inputName: string = 'input_data.bin'; +let inputName = 'input_data.bin'; let syscontext = globalThis.context; -syscontext.resourceManager.getRawFileContent(this.inputName).then((buffer) => { - this.inputBuffer = buffer; +syscontext.resourceManager.getRawFileContent(inputName).then(async (buffer) => { + let inputBuffer = buffer; let model_file = '/path/to/xxx.ms'; let mindSporeLiteModel = await mindSporeLite.loadModelFromFile(model_file); const modelInputs = mindSporeLiteModel.getInputs(); - modelInputs[0].setData(this.inputBuffer.buffer); + modelInputs[0].setData(inputBuffer.buffer); result.predict(modelInputs).then((result) => { let output = new Float32Array(result[0].getData()); for (let i = 0; i < output.length; i++) { @@ -541,14 +541,14 @@ Obtains tensor data. ```js import resourceManager from '@ohos.resourceManager' -@State inputName: string = 'input_data.bin'; +let inputName = 'input_data.bin'; let syscontext = globalThis.context; -syscontext.resourceManager.getRawFileContent(this.inputName).then((buffer) => { - this.inputBuffer = buffer; +syscontext.resourceManager.getRawFileContent(inputName).then(async (buffer) => { + let inputBuffer = buffer; let model_file = '/path/to/xxx.ms'; let mindSporeLiteModel = await mindSporeLite.loadModelFromFile(model_file); const modelInputs = mindSporeLiteModel.getInputs(); - modelInputs[0].setData(this.inputBuffer.buffer); + modelInputs[0].setData(inputBuffer.buffer); result.predict(modelInputs).then((result) => { let output = new Float32Array(result[0].getData()); for (let i = 0; i < output.length; i++) { @@ -576,15 +576,15 @@ Sets the tensor data. ```js import resourceManager from '@ohos.resourceManager' -@State inputName: string = 'input_data.bin'; +let inputName = 'input_data.bin'; let syscontext = globalThis.context; -syscontext.resourceManager.getRawFileContent(this.inputName).then((buffer) => { - this.inputBuffer = buffer; +syscontext.resourceManager.getRawFileContent(inputName).then(async (buffer) => { + inputBuffer = buffer; + let model_file = '/path/to/xxx.ms'; + let mindSporeLiteModel = await mindSporeLite.loadModelFromFile(model_file); + const modelInputs = mindSporeLiteModel.getInputs(); + modelInputs[0].setData(inputBuffer.buffer); }) -let model_file = '/path/to/xxx.ms'; -let mindSporeLiteModel = await mindSporeLite.loadModelFromFile(model_file); -const modelInputs = mindSporeLiteModel.getInputs(); -modelInputs[0].setData(this.inputBuffer.buffer); ``` ## DataType diff --git a/en/application-dev/reference/apis/js-apis-nfcTag.md b/en/application-dev/reference/apis/js-apis-nfcTag.md index 2a9f99171413030bb3374b51fb25dff3dc5cbf60..9aeadd303e320824c99d7eb58148274bbb537e9b 100644 --- a/en/application-dev/reference/apis/js-apis-nfcTag.md +++ b/en/application-dev/reference/apis/js-apis-nfcTag.md @@ -482,6 +482,96 @@ Obtains **TagInfo** from **Want**, which is initialized by the NFC service and c | ------------------- | -------------------------------------------- | | [TagInfo](#taginfo) | **TagInfo** object obtained.| +## tag.registerForegroundDispatch10+ + +registerForegroundDispatch(elementName: [ElementName](js-apis-bundleManager-elementName.md), discTech: number[], callback: AsyncCallback<[TagInfo](#taginfo)>): void; + +Registers listening for the card reading events of an NFC tag foreground application. You can set the supported tag technologies in **discTech**, and obtain the [TagInfo](#taginfo) read in a callback.
This API must be used with [tag.unregisterForegroundDispatch](#tagunregisterforegrounddispatch10) in pairs. The registered event listening must be unregistered before the page exits the foreground or the page is destroyed. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Tag + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------ | -------- | ---- | ------------------------------------------------------- | +| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes | Information about the application page. It must contain at least the **bundleName**, **abilityName**, and **moduleName**. | +| discTech | number[] | Yes | Technologies supported by the foreground dispatch system. Each number indicates the constant value of the supported technology. Based on the value of **number**, the system sets tag technologies ([NFC_A](#technology-type-definition), [NFC_B](#technology-type-definition), and [NFC_F](#technology-type-definition), and [NFC_V](#technology-type-definition)) for NFC card read polling and disable card emulation. If the **number** length is 0, both card read polling and card emulation will be disabled.| +| callback | AsyncCallback<[TagInfo](#taginfo)> | Yes | Callback invoked to return the card read event in the foreground.| + +**Example** + +See the example of [tag.unregisterForegroundDispatch](#tagunregisterforegrounddispatch10). + +## tag.unregisterForegroundDispatch10+ + +unregisterForegroundDispatch(elementName: [ElementName](js-apis-bundleManager-elementName.md)): void; + +Unregisters the listening for card reading events of an NFC tag foreground application. The registered event listening must be unregistered before the page exits the foreground or the page is destroyed. + +**Required permissions**: ohos.permission.NFC_TAG + +**System capability**: SystemCapability.Communication.NFC.Tag + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------ | -------- | ---- | ------------------------------------------------------- | +| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes | Information about the application page. It must contain at least the **bundleName**, **abilityName**, and **moduleName**. | + +**Example** + +```js +import UIAbility from '@ohos.app.ability.UIAbility' +import tag from '@ohos.nfc.tag'; + +let elementName = null; +let discTech = [tag.NFC_A, tag.NFC_B]; // replace with the tech(s) that is needed by foreground ability +function foregroundCb(tagInfo: any) { + console.log("foreground callback: tag found tagInfo = ", JSON.stringify(tagInfo)); +} + +export default class MainAbility extends UIAbility { + OnCreate(want, launchParam) { + console.log("OnCreate"); + elementName = { + bundleName: want.bundleName, + abilityName: want.abilityName, + moduleName: want.moduleName + } + } + + onForeground() { + console.log("onForeground"); + try { + tag.registerForegroundDispatch(elementName, discTech, foregroundCb); + } catch (e) { + console.log("registerForegroundDispatch error: " + e.message); + } + } + + onBackground() { + console.log("onBackground"); + try { + tag.unregisterForegroundDispatch(elementName); + } catch (e) { + console.log("registerForegroundDispatch error: " + e.message); + } + } + + onWindowStageDestroy() { + console.log("onWindowStageDestroy"); + try { + tag.unregisterForegroundDispatch(elementName); + } catch (e) { + console.log("registerForegroundDispatch error: " + e.message); + } + } + + // override other lifecycle functions +} +``` ## tag.ndef.makeUriRecord9+ diff --git a/en/application-dev/reference/apis/js-apis-request.md b/en/application-dev/reference/apis/js-apis-request.md index 675782f3822b59be27f8ff7124b7f5d4ed062530..f2eb1a5fff829317cf67affa7980deaee7c67158 100644 --- a/en/application-dev/reference/apis/js-apis-request.md +++ b/en/application-dev/reference/apis/js-apis-request.md @@ -81,25 +81,25 @@ Uploads files. This API uses a promise to return the result. You can use [on('co **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| -| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| + | config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| **Return value** -| Type| Description| -| -------- | -------- | -| Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object.| + | Type| Description| + | -------- | -------- | + | Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400002 | bad file path. | + | ID| Error Message| + | -------- | -------- | + | 13400002 | bad file path. | **Example** @@ -141,19 +141,19 @@ Uploads files. This API uses an asynchronous callback to return the result. You **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| -| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| -| callback | AsyncCallback<[UploadTask](#uploadtask)> | Yes| Callback used to return the **UploadTask** object.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| + | config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| + | callback | AsyncCallback<[UploadTask](#uploadtask)> | Yes| Callback used to return the **UploadTask** object.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400002 | bad file path. | + | ID| Error Message| + | -------- | -------- | + | 13400002 | bad file path. | **Example** @@ -202,15 +202,15 @@ Uploads files. This API uses a promise to return the result. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| **Return value** -| Type| Description| -| -------- | -------- | -| Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object.| + | Type| Description| + | -------- | -------- | + | Promise<[UploadTask](#uploadtask)> | Promise used to return the **UploadTask** object.| **Example** @@ -249,10 +249,10 @@ Uploads files. This API uses an asynchronous callback to return the result. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| -| callback | AsyncCallback<[UploadTask](#uploadtask)> | Yes| Callback used to return the **UploadTask** object.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | config | [UploadConfig](#uploadconfig) | Yes| Upload configurations.| + | callback | AsyncCallback<[UploadTask](#uploadtask)> | Yes| Callback used to return the **UploadTask** object.| **Example** @@ -292,10 +292,10 @@ Subscribes to upload progress events. This API uses a callback to return the res **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (upload progress).| -| callback | function | Yes| Callback for the upload progress event.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (upload progress).| + | callback | function | Yes| Callback for the upload progress event.| Parameters of the callback function @@ -326,10 +326,10 @@ Subscribes to HTTP header events for an upload task. This API uses a callback to **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Type of the event to subscribe to. The value is **'headerReceive'** (response header).| -| callback | function | Yes| Callback for the HTTP Response Header event.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to subscribe to. The value is **'headerReceive'** (response header).| + | callback | function | Yes| Callback for the HTTP Response Header event.| Parameters of the callback function @@ -359,10 +359,10 @@ Subscribes to upload completion or failure events. This API uses a callback to r **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Type of the event to subscribe to. The value **'complete'** means the upload completion event, and **'fail'** means the upload failure event.| -| callback | Callback<Array<TaskState>> | Yes| Callback used to return the result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to subscribe to. The value **'complete'** means the upload completion event, and **'fail'** means the upload failure event.| + | callback | Callback<Array<TaskState>> | Yes| Callback used to return the result.| Parameters of the callback function @@ -401,10 +401,10 @@ Unsubscribes from upload progress events. This API uses a callback to return the **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (upload progress).| -| callback | function | No| Callback used to return the result.
**uploadedSize**: size of the uploaded files, in B.
**totalSize**: Total size of the files to upload, in B.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (upload progress).| + | callback | function | No| Callback used to return the result.
**uploadedSize**: size of the uploaded files, in B.
**totalSize**: Total size of the files to upload, in B.| **Example** @@ -428,10 +428,10 @@ Unsubscribes from HTTP header events for an upload task. This API uses a callbac **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Type of the event to unsubscribe from. The value is **'headerReceive'** (response header).| -| callback | function | No| Callback used to return the result.
**header**: HTTP response header.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to unsubscribe from. The value is **'headerReceive'** (response header).| + | callback | function | No| Callback used to return the result.
**header**: HTTP response header.| **Example** @@ -454,10 +454,10 @@ Unsubscribes from upload completion or failure events. This API uses a callback **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Type of the event to subscribe to. The value **'complete'** means the upload completion event, and **'fail'** means the upload failure event.| -| callback | Callback<Array<TaskState>> | No| Callback used to return the result.
**taskstates**: upload task result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to subscribe to. The value **'complete'** means the upload completion event, and **'fail'** means the upload failure event.| + | callback | Callback<Array<TaskState>> | No| Callback used to return the result.
**taskstates**: upload task result.| **Example** @@ -490,19 +490,15 @@ Deletes this upload task. This API uses a promise to return the result. **Return value** -| Type| Description| -| -------- | -------- | -| Promise<boolean> | Promise used to return the task removal result. It returns **true** if the operation is successful and returns **false** otherwise.| + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Promise used to return the task removal result. It returns **true** if the operation is successful and returns **false** otherwise.| **Example** ```js uploadTask.delete().then((result) => { - if (result) { - console.info('Succeeded in deleting the upload task.'); - } else { - console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`); - } + console.info('Succeeded in deleting the upload task.'); }).catch((err) => { console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`); }); @@ -521,9 +517,9 @@ Deletes this upload task. This API uses an asynchronous callback to return the r **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| **Example** @@ -533,11 +529,7 @@ Deletes this upload task. This API uses an asynchronous callback to return the r console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`); return; } - if (result) { - console.info('Succeeded in deleting the upload task.'); - } else { - console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`); - } + console.info('Succeeded in deleting the upload task.'); }); ``` @@ -558,19 +550,15 @@ Removes this upload task. This API uses a promise to return the result. **Return value** -| Type| Description| -| -------- | -------- | -| Promise<boolean> | Promise used to return the task removal result. It returns **true** if the operation is successful and returns **false** otherwise.| + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Promise used to return the task removal result. It returns **true** if the operation is successful and returns **false** otherwise.| **Example** ```js uploadTask.remove().then((result) => { - if (result) { - console.info('Succeeded in removing the upload task.'); - } else { - console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`); - } + console.info('Succeeded in removing the upload task.'); }).catch((err) => { console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`); }); @@ -593,9 +581,9 @@ Removes this upload task. This API uses an asynchronous callback to return the r **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| **Example** @@ -681,26 +669,26 @@ Downloads files. This API uses a promise to return the result. You can use [on(' **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| -| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| + | config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| **Return value** -| Type| Description| -| -------- | -------- | -| Promise<[DownloadTask](#downloadtask)> | Promise used to return the result.| + | Type| Description| + | -------- | -------- | + | Promise<[DownloadTask](#downloadtask)> | Promise used to return the result.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400001 | file operation error. | -| 13400002 | bad file path. | -| 13400003 | task service ability error. | + | ID| Error Message| + | -------- | -------- | + | 13400001 | file operation error. | + | 13400002 | bad file path. | + | 13400003 | task service ability error. | **Example** @@ -736,21 +724,21 @@ Downloads files. This API uses an asynchronous callback to return the result. Yo **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| -| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| -| callback | AsyncCallback<[DownloadTask](#downloadtask)> | Yes| Callback used to return the result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| + | config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| + | callback | AsyncCallback<[DownloadTask](#downloadtask)> | Yes| Callback used to return the result.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400001 | file operation error. | -| 13400002 | bad file path. | -| 13400003 | task service ability error. | + | ID| Error Message| + | -------- | -------- | + | 13400001 | file operation error. | + | 13400002 | bad file path. | + | 13400003 | task service ability error. | **Example** @@ -793,15 +781,15 @@ Downloads files. This API uses a promise to return the result. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| **Return value** -| Type| Description| -| -------- | -------- | -| Promise<[DownloadTask](#downloadtask)> | Promise used to return the result.| + | Type| Description| + | -------- | -------- | + | Promise<[DownloadTask](#downloadtask)> | Promise used to return the result.| **Example** @@ -833,10 +821,10 @@ Downloads files. This API uses an asynchronous callback to return the result. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| -| callback | AsyncCallback<[DownloadTask](#downloadtask)> | Yes| Callback used to return the result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | config | [DownloadConfig](#downloadconfig) | Yes| Download configurations.| + | callback | AsyncCallback<[DownloadTask](#downloadtask)> | Yes| Callback used to return the result.| **Example** @@ -869,10 +857,10 @@ Subscribes to download progress events. This API uses a callback to return the r **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (download progress).| -| callback | function | Yes| Callback used to return the result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to subscribe to. The value is **'progress'** (download progress).| + | callback | function | Yes| Callback used to return the result.| Parameters of the callback function @@ -903,10 +891,10 @@ Unsubscribes from download progress events. This API uses a callback to return t **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (download progress).| -| callback | function | No| Callback used to return the result.
**receivedSize**: size of the downloaded files.
**totalSize**: total size of the files to download.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to unsubscribe from. The value is **'progress'** (download progress).| + | callback | function | No| Callback used to return the result.
**receivedSize**: size of the downloaded files.
**totalSize**: total size of the files to download.| **Example** @@ -930,10 +918,10 @@ Subscribes to download events. This API uses an asynchronous callback to return **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Type of the event to subscribe to.
- **'complete'**: download task completion event.
- **'pause'**: download task pause event.
- **'remove'**: download task removal event.| -| callback | function | Yes| Callback used to return the result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to subscribe to.
- **'complete'**: download task completion event.
- **'pause'**: download task pause event.
- **'remove'**: download task removal event.| + | callback | function | Yes| Callback used to return the result.| **Example** @@ -967,10 +955,10 @@ Unsubscribes from download events. This API uses a callback to return the result **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Type of the event to unsubscribe from.
- **'complete'**: download task completion event.
- **'pause'**: download task pause event.
- **'remove'**: download task removal event.| -| callback | function | No| Callback used to return the result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to unsubscribe from.
- **'complete'**: download task completion event.
- **'pause'**: download task pause event.
- **'remove'**: download task removal event.| + | callback | function | No| Callback used to return the result.| **Example** @@ -1004,10 +992,10 @@ Subscribes to download failure events. This API uses a callback to return the re **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Type of the event to subscribe to. The value is **'fail'** (download failure).| -| callback | function | Yes| Callback for the download task failure event.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to subscribe to. The value is **'fail'** (download failure).| + | callback | function | Yes| Callback for the download task failure event.| Parameters of the callback function @@ -1037,10 +1025,10 @@ Unsubscribes from download failure events. This API uses a callback to return th **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Type of the event to unsubscribe from. The value is **'fail'** (download failure).| -| callback | function | No| Callback used to return the result.
**err**: error code of the download failure. | + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Type of the event to unsubscribe from. The value is **'fail'** (download failure).| + | callback | function | No| Callback used to return the result.
**err**: error code of the download failure. | **Example** @@ -1063,19 +1051,15 @@ Removes this download task. This API uses a promise to return the result. **Return value** -| Type| Description| -| -------- | -------- | -| Promise<boolean> | Promise used to return the task removal result.| + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Promise used to return the task removal result.| **Example** ```js downloadTask.delete().then((result) => { - if (result) { console.info('Succeeded in removing the download task.'); - } else { - console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); - } }).catch ((err) => { console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); }); @@ -1094,9 +1078,9 @@ Deletes this download task. This API uses an asynchronous callback to return the **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the task deletion result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | Yes| Callback used to return the task deletion result.| **Example** @@ -1106,11 +1090,7 @@ Deletes this download task. This API uses an asynchronous callback to return the console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); return; } - if (result) { - console.info('Succeeded in removing the download task.'); - } else { - console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); - } + console.info('Succeeded in removing the download task.'); }); ``` @@ -1127,9 +1107,9 @@ Obtains the information about this download task. This API uses a promise to ret **Return value** -| Type| Description| -| -------- | -------- | -| Promise<[DownloadInfo](#downloadinfo7)> | Promise used to return the download task information.| + | Type| Description| + | -------- | -------- | + | Promise<[DownloadInfo](#downloadinfo7)> | Promise used to return the download task information.| **Example** @@ -1154,9 +1134,9 @@ Obtains the information about this download task. This API uses an asynchronous **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | Yes| Callback used to return the download task information.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | Yes| Callback used to return the download task information.| **Example** @@ -1183,9 +1163,9 @@ Obtains the **MimeType** of this download task. This API uses a promise to retur **Return value** -| Type| Description| -| -------- | -------- | -| Promise<string> | Promise used to return the **MimeType** of the download task.| + | Type| Description| + | -------- | -------- | + | Promise<string> | Promise used to return the **MimeType** of the download task.| **Example** @@ -1210,9 +1190,9 @@ Obtains the **MimeType** of this download task. This API uses an asynchronous ca **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<string> | Yes| Callback used to return the **MimeType** of the download task.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<string> | Yes| Callback used to return the **MimeType** of the download task.| **Example** @@ -1239,19 +1219,15 @@ Pauses this download task. This API uses a promise to return the result. **Return value** -| Type| Description| -| -------- | -------- | -| Promise<boolean> | Promise used to return the download task pause result.| + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Promise used to return the download task pause result.| **Example** ```js downloadTask.suspend().then((result) => { - if (result) { - console.info('Succeeded in pausing the download task.'); - } else { - console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); - } + console.info('Succeeded in pausing the download task.'); }).catch((err) => { console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); }); @@ -1270,9 +1246,9 @@ Pauses this download task. This API uses an asynchronous callback to return the **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| **Example** @@ -1282,11 +1258,7 @@ Pauses this download task. This API uses an asynchronous callback to return the console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); return; } - if (result) { - console.info('Succeeded in pausing the download task.'); - } else { - console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); - } + console.info('Succeeded in pausing the download task.'); }); ``` @@ -1303,19 +1275,14 @@ Resumes this download task. This API uses a promise to return the result. **Return value** -| Type| Description| -| -------- | -------- | -| Promise<boolean> | Promise used to return the result.| + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Promise used to return the result.| **Example** ```js downloadTask.restore().then((result) => { - if (result) { - console.info('Succeeded in resuming the download task.') - } else { - console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); - } console.info('Succeeded in resuming the download task.') }).catch((err) => { console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); @@ -1335,9 +1302,9 @@ Resumes this download task. This API uses an asynchronous callback to return the **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| **Example** @@ -1347,11 +1314,7 @@ Resumes this download task. This API uses an asynchronous callback to return the console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); return; } - if (result) { - console.info('Succeeded in resuming the download task.'); - } else { - console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); - } + console.info('Succeeded in resuming the download task.'); }); ``` @@ -1372,19 +1335,15 @@ Removes this download task. This API uses a promise to return the result. **Return value** -| Type| Description| -| -------- | -------- | -| Promise<boolean> | Promise used to return the task removal result.| + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Promise used to return the task removal result.| **Example** ```js downloadTask.remove().then((result) => { - if (result) { - console.info('Succeeded in removing the download task.'); - } else { - console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); - } + console.info('Succeeded in removing the download task.'); }).catch ((err) => { console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); }); @@ -1407,9 +1366,9 @@ Removes this download task. This API uses an asynchronous callback to return the **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the task deletion result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | Yes| Callback used to return the task deletion result.| **Example** @@ -1418,12 +1377,8 @@ Removes this download task. This API uses an asynchronous callback to return the if(err) { console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); return; - } - if (result) { - console.info('Succeeded in removing the download task.'); - } else { - console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); - } + } + console.info('Succeeded in removing the download task.'); }); ``` @@ -1444,9 +1399,9 @@ Queries this download task. This API uses a promise to return the result. **Return value** -| Type| Description| -| -------- | -------- | -| Promise<[DownloadInfo](#downloadinfo7)> | Promise used to return the download task information.| + | Type| Description| + | -------- | -------- | + | Promise<[DownloadInfo](#downloadinfo7)> | Promise used to return the download task information.| **Example** @@ -1475,9 +1430,9 @@ Queries this download task. This API uses an asynchronous callback to return the **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | Yes| Callback used to return the download task information.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | Yes| Callback used to return the download task information.| **Example** @@ -1508,9 +1463,9 @@ Queries the **MimeType** of this download task. This API uses a promise to retur **Return value** -| Type| Description| -| -------- | -------- | -| Promise<string> | Promise used to return the **MimeType** of the download task.| + | Type| Description| + | -------- | -------- | + | Promise<string> | Promise used to return the **MimeType** of the download task.| **Example** @@ -1539,9 +1494,9 @@ Queries the **MimeType** of this download task. This API uses an asynchronous ca **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<string> | Yes| Callback used to return the **MimeType** of the download task.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<string> | Yes| Callback used to return the **MimeType** of the download task.| **Example** @@ -1572,19 +1527,15 @@ Pauses this download task. This API uses a promise to return the result. **Return value** -| Type| Description| -| -------- | -------- | -| Promise<void> | Promise used to return the download task pause result.| + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the download task pause result.| **Example** ```js downloadTask.pause().then((result) => { - if (result) { - console.info('Succeeded in pausing the download task.'); - } else { - console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); - } + console.info('Succeeded in pausing the download task.'); }).catch((err) => { console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); }); @@ -1607,9 +1558,9 @@ Pauses this download task. This API uses an asynchronous callback to return the **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<void> | Yes| Callback used to return the result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Example** @@ -1619,11 +1570,7 @@ Pauses this download task. This API uses an asynchronous callback to return the console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); return; } - if (result) { - console.info('Succeeded in pausing the download task.'); - } else { - console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); - } + console.info('Succeeded in pausing the download task.'); }); ``` @@ -1644,19 +1591,14 @@ Resumes this download task. This API uses a promise to return the result. **Return value** -| Type| Description| -| -------- | -------- | -| Promise<void> | Promise used to return the result.| + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| **Example** ```js downloadTask.resume().then((result) => { - if (result) { - console.info('Succeeded in resuming the download task.') - } else { - console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); - } console.info('Succeeded in resuming the download task.') }).catch((err) => { console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); @@ -1680,9 +1622,9 @@ Resumes this download task. This API uses an asynchronous callback to return the **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback<void> | Yes| Callback used to return the result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Example** @@ -1692,11 +1634,7 @@ Resumes this download task. This API uses an asynchronous callback to return the console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); return; } - if (result) { - console.info('Succeeded in resuming the download task.'); - } else { - console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); - } + console.info('Succeeded in resuming the download task.'); }); ``` @@ -1800,7 +1738,7 @@ Describes the form item of a task. | value | string \| [FileSpec](#filespec10) \| Array<[FileSpec](#filespec10)> | Yes| Form parameter value.| -## Conf10+ +## Config10+ Provides the configuration information of an upload or download task. **System capability**: SystemCapability.Request.FileTransferAgent @@ -1809,26 +1747,26 @@ Provides the configuration information of an upload or download task. | -------- | -------- | -------- | -------- | | action | [Action](#action10) | Yes| Task action.
- **UPLOAD**
- **DOWNLOAD**| | url | string | Yes| Resource URL. The value contains a maximum of 2048 characters.| -| title | string | No| Task title. The value contains a maximum of 256 characters. This parameter is left blank by default.| +| title | string | No| Task title. The value contains a maximum of 256 characters. The default value is a null string.| | description | string | No| Task description. The value contains a maximum of 1024 characters. The default value is a null string.| | mode | [Mode](#mode10) | No| Task mode. The default mode is background.
- For a foreground task, a callback is used for notification.
- For a background task, the system notification and network connection features (detection, recovery, and automatic retry) are provided.| | overwrite | boolean | No| Whether to overwrite an existing file during the download. The default value is **false**.
- **true**: Overwrite the existing file.
- **false**: Do not overwrite the existing file. In this case, the download fails.| | method | string | No| Standard HTTP method for the task. The value can be **GET**, **POST**, or **PUT**, which is case-insensitive.
- If the task is an upload, use **PUT** or **POST**. The default value is **PUT**.
- If the task is a download, use **GET** or **POST**. The default value is **GET**.| | headers | object | No| HTTPS headers to be included in the task.
- If the task is an upload, the default **Content-Type** is **multipart/form-data**.
- If the task is a download, the default **Content-Type** is **application/json**.| | data | string \| Array<[FormItem](#formitem10)> | No| Task data.
- If the task is a download, the value is a string, typically in JSON format (an object will be converted to a JSON string); the default value is null.
- If the task is an upload, the value is Array<[FormItem](#formitem10)>; the default value is null.| -| saveas | string | No| Path for storing downloaded files. The options are as follows:
- Relative path in the cache folder of the invoker, for example, ./xxx/yyy/zzz.html and xxx/yyy/zzz.html.
- URI (applicable when the application has the permission to access the URI), for example, **"datashare://bundle/xxx/yyy/zzz.html"**. Currently, this type is not supported.
The default value is a relative path in the cache folder of the application.| +| saveas | string | No| Path for storing downloaded files. The options are as follows:
- Relative path in the cache folder of the invoker, for example, **"./xxx/yyy/zzz.html"** and **"xxx/yyy/zzz.html"**.
- URI (applicable when the application has the permission to access the URI), for example, **"datashare://bundle/xxx/yyy/zzz.html"**. This option is not supported currently.
The default value is a relative path in the cache folder of the application.| | network | [Network](#network10) | No| Network used for the task. The default value is **ANY** (Wi-Fi or cellular).| -| metered | boolean | No| Whether the task is allowed on a metered connection. The default value is **false**.| -| roaming | boolean | No| Whether the task is allowed on a roaming network. The default value is **true**.| -| retry | boolean | No| Whether automatic retry is enabled for background tasks. The default value is **true**.| -| redirect | boolean | No| Whether redirection is allowed. The default value is **true**.| +| metered | boolean | No| Whether the task is allowed on a metered connection. The default value is **false**.
- **true**: The task is allowed on a metered connection.
- **false**: The task is not allowed on a metered connection.| +| roaming | boolean | No| Whether the task is allowed on a roaming network. The default value is **true**.
- **true**: The task is allowed on a roaming network.
- **false**: The task is not allowed on a roaming network.| +| retry | boolean | No| Whether automatic retry is enabled for the task. This parameter is only applicable to background tasks. The default value is **true**.
- **true**: Automatic retry is enabled for the task.
- **-false**: Automatic retry is not enabled for the task.| +| redirect | boolean | No| Whether redirection is allowed. The default value is **true**.
- **true**: Redirection is allowed.
- **false**: Redirection is not allowed.| | index | number | No| Path index of the task. It is usually used for resumable downloads. The default value is **0**.| | begins | number | No| File start point of the task. It is usually used for resumable downloads. The default value is **0**. The value is a closed interval.
- If the task is a download, the value is obtained by sending an HTTP range request to read the start position when the server starts to download files.
- If the task is an upload, the value is obtained at the beginning of the upload.| | ends | number | No| File end point of the task. It is usually used for resumable downloads. The default value is **-1**. The value is a closed interval.
- If the task is a download, the value is obtained by sending an HTTP range request to read the end position when the server starts to download files.
- If the task is an upload, the value is obtained at the end of the upload.| | gauge | boolean | No| Whether to send progress notifications. This parameter applies only to background tasks. The default value is **false**.
- **false**: Progress notifications are not sent. This means that a notification is sent only to indicate the result of the total task.
- **true**: Progress notifications are sent to indicate the result of each file.| | precise | boolean | No| - If this parameter is set to **true**, the task fails when the file size cannot be obtained.
- If this parameter is set to **false**, the task continues when the file size is set to **-1**.
The default value is **false**.| | token | string | No| Token of the task. If the task has a token configured, this token is required for query of the task. The value contains 8 to 2048 bytes. This parameter is left empty by default.| -| extras | object | No| Additional information of the task. This parameter is left blank by default.| +| extras | object | No| Additional information of the task. This parameter is left empty by default.| ## State10+ @@ -1838,7 +1776,7 @@ Defines the current task status. | Name| Value|Description| | -------- | -------- |-------- | -| INITIALIZED | 0x00 |The task is initialized based on the configuration specified in [Conf](#conf10).| +| INITIALIZED | 0x00 |The task is initialized based on the configuration specified in [Conf](#config10).| | WAITING | 0x10 |The task lacks resources for running or the resources for retries do not match the network status.| | RUNNING | 0x20 |The task is being executed.| | RETRYING | 0x21 |The task has failed at least once and is being executed again.| @@ -1863,7 +1801,7 @@ Describes the data structure of the task progress. | extras | object | No| Extra information of the task, for example, the header and body of the response from the server.| -## Broken10+ +## Faults10+ Defines the cause of a task failure. @@ -1878,8 +1816,22 @@ Defines the cause of a task failure. | FSIO | 0x40 |File system I/O error, for example, an error that occurs during the open, search, read, write, or close operation.| +## Filter10+ +Defines the filter criteria. + +**System capability**: SystemCapability.Request.FileTransferAgent + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| bundle | string | No| Bundle name of an application.
**System API**: This is a system API.| +| before | number | No| Unix timestamp of the end time, in milliseconds. The default value is the invoking time.| +| after | number | No| Unix timestamp of the start time, in milliseconds. The default value is the invoking time minus 24 hours.| +| state | [State](#state10) | No| Task state.| +| action | [Action](#action10) | No| Task action.
- **UPLOAD**
- **DOWNLOAD**| +| mode | [Mode](#mode10) | No| Task mode.
- **FOREGROUND**
- **BACKGROUND**| + ## TaskInfo10+ -Defines the data structure of the task information for query. The fields available varies depends on the query type. +Defines the data structure of the task information for query. The fields available vary depending on the query type. **System capability**: SystemCapability.Request.FileTransferAgent @@ -1887,8 +1839,9 @@ Defines the data structure of the task information for query. The fields availab | -------- | -------- | -------- | -------- | | uid | string | No| UID of the application. It is only available for query by system applications.
**System API**: This is a system API.| | bundle | string | No| Bundle name of the application. It is only available for query by system applications.
**System API**: This is a system API.| -| url | string | No| Task URL. It is only available for query by non-system applications. An empty string is returned for query by system applications.| -| data | string \| Array<[FormItem](#formitem10)> | No| Task value.| +| saveas | string | No| Path for storing downloaded files. The options are as follows:
- Relative path in the cache folder of the invoker, for example, **"./xxx/yyy/zzz.html"** and **"xxx/yyy/zzz.html"**.
- URI (applicable when the application has the permission to access the URI), for example, **"datashare://bundle/xxx/yyy/zzz.html"**. This option is not supported currently.
The default value is a relative path in the cache folder of the application.| +| url | string | No| Task URL.
- It can be obtained through [request.agent.show10+](#requestagentshow10-1), [request.agent.touch10+](#requestagenttouch10-1), or [request.agent.query10+](#requestagentquery10-1). When [request.agent.query10+](#requestagentquery10-1) is used, an empty string is returned.| +| data | string \| Array<[FormItem](#formitem10)> | No| Task value.
- It can be obtained through [request.agent.show10+](#requestagentshow10-1), [request.agent.touch10+](#requestagenttouch10-1), or [request.agent.query10+](#requestagentquery10-1). When [request.agent.query10+](#requestagentquery10-1) is used, an empty string is returned.| | tid | string | Yes| Task ID.| | title | string | Yes| Task title.| | description | string | Yes| Task description.| @@ -1897,11 +1850,11 @@ Defines the data structure of the task information for query. The fields availab | mimeType | string | Yes| MIME type in the task configuration.| | progress | [Progress](#progress10) | Yes| Task progress.| | gauge | boolean | Yes| Whether to send progress notifications. This parameter applies only to background tasks.| -| ctime | string | Yes| Date and time when a task is created in UTC mode. The value is generated by the system of the current device.| -| mtime | string | Yes| Date and time when a task is modified in UTC mode. The value is generated by the system of the current device.| +| ctime | number | Yes| Unix timestamp when the task is created, in milliseconds. The value is generated by the system of the current device.
Note: When [request.agent.search10+](#requestagentsearch10-1) is used for query, this value must be within the range of [after,before] for the task ID to be obtained. For details about **before** and **after**, see [Filter](#filter10). +| mtime | number | Yes| Unix timestamp when the task state changes, in milliseconds. The value is generated by the system of the current device.| | retry | boolean | Yes| Whether automatic retry is enabled for the task. This parameter applies only to background tasks.| | tries | number | Yes| Number of retries of the task.| -| broken | [Broken](#broken10) | Yes| Failure cause of the task.
- **OTHERS**: other fault.
- **DISCONNECT**: network disconnection.
- **TIMEOUT**: timeout.
- **PROTOCOL**: protocol error.
- **FSIO**: file system I/O error.| +| faults | [Faults](#faults10) | Yes| Failure cause of the task.
- **OTHERS**: other fault.
- **DISCONNECT**: network disconnection.
- **TIMEOUT**: timeout.
- **PROTOCOL**: protocol error.
- **FSIO**: file system I/O error.| | reason | string | Yes| Reason why the task is waiting, failed, stopped, or paused.| | extras | string | No| Extra information of the task| @@ -1917,7 +1870,7 @@ Task attributes include the task ID and task configuration. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | tid | string | Yes| Task ID, which is unique in the system and is automatically generated by the system.| -| conf | [Conf](#conf10) | Yes| Task configuration.| +| config | [Config](#config10) | Yes| Task configuration.| ### on('progress')10+ @@ -1930,18 +1883,18 @@ Subscribes to task progress events. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| event | string | Yes| Type of the event to subscribe to.
The value is **'progress'**, indicating the task progress.| -| callback | function | Yes| Callback used to return the data structure of the task progress.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | event | string | Yes| Type of the event to subscribe to.
The value is **'progress'**, indicating the task progress.| + | callback | function | Yes| Callback used to return the data structure of the task progress.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 21900005 | task mode error. | + | ID| Error Message| + | -------- | -------- | + | 21900005 | task mode error. | **Example** @@ -1955,7 +1908,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro path: "./taskOnTest.avi", } }]; - let conf = { + let config = { action: request.agent.Action.UPLOAD, url: 'http://127.0.0.1', title: 'taskOnTest', @@ -1980,7 +1933,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro let createOnCallback = (progress) => { console.info('upload task completed.'); }; - request.agent.create(context, conf).then((task)=> { + request.agent.create(context, config).then((task)=> { task.on('progress', createOnCallback); console.info(`Succeeded in creating a upload task. result: ${task.tid}`); }).catch((err) => { @@ -2002,18 +1955,18 @@ Subscribes to task completion events. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| event | string | Yes| Type of the event to subscribe to.
The value is **'completed'**, indicating task completion.| -| callback | function | Yes| Callback used to return the data structure of the task progress.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | event | string | Yes| Type of the event to subscribe to.
The value is **'completed'**, indicating task completion.| + | callback | function | Yes| Callback used to return the data structure of the task progress.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 21900005 | task mode error. | + | ID| Error Message| + | -------- | -------- | + | 21900005 | task mode error. | **Example** @@ -2027,7 +1980,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro path: "./taskOnTest.avi", } }]; - let conf = { + let config = { action: request.agent.Action.UPLOAD, url: 'http://127.0.0.1', title: 'taskOnTest', @@ -2052,7 +2005,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro let createOnCallback = (progress) => { console.info('upload task completed.'); }; - request.agent.create(context, conf).then((task)=> { + request.agent.create(context, config).then((task)=> { task.on('completed', createOnCallback); console.info(`Succeeded in creating a upload task. result: ${task.tid}`); }).catch((err) => { @@ -2074,18 +2027,18 @@ Subscribes to task failure events. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| event | string | Yes| Type of the event to subscribe to.
The value is **'failed'**, indicating task failure.| -| callback | function | Yes| Callback used to return the data structure of the task progress.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | event | string | Yes| Type of the event to subscribe to.
The value is **'failed'**, indicating task failure.| + | callback | function | Yes| Callback used to return the data structure of the task progress.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 21900005 | task mode error. | + | ID| Error Message| + | -------- | -------- | + | 21900005 | task mode error. | **Example** @@ -2099,7 +2052,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro path: "./taskOnTest.avi", } }]; - let conf = { + let config = { action: request.agent.Action.UPLOAD, url: 'http://127.0.0.1', title: 'taskOnTest', @@ -2124,7 +2077,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro let createOnCallback = (progress) => { console.info('upload task completed.'); }; - request.agent.create(context, conf).then((task)=> { + request.agent.create(context, config).then((task)=> { task.on('failed', createOnCallback); console.info(`Succeeded in creating a upload task. result: ${task.tid}`); }).catch((err) => { @@ -2147,18 +2100,18 @@ Unsubscribes from task progress events. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| event | string | Yes| Type of the event to subscribe to.
The value is **'progress'**, indicating the task progress.| -| callback | function | No| Callback used to return the data structure of the task progress.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | event | string | Yes| Type of the event to subscribe to.
The value is **'progress'**, indicating the task progress.| + | callback | function | No| Callback used to return the data structure of the task progress.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 21900005 | task mode error. | + | ID| Error Message| + | -------- | -------- | + | 21900005 | task mode error. | **Example** @@ -2172,7 +2125,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro path: "./taskOffTest.avi", } }]; - let conf = { + let config = { action: request.agent.Action.UPLOAD, url: 'http://127.0.0.1', title: 'taskOffTest', @@ -2197,7 +2150,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro let createOffCallback = (progress) => { console.info('upload task completed.'); }; - request.agent.create(context, conf).then((task)=> { + request.agent.create(context, config).then((task)=> { task.on('progress', createOffCallback); task.off('progress', createOffCallback); console.info(`Succeeded in creating a upload task. result: ${task.tid}`); @@ -2220,18 +2173,18 @@ Unsubscribes from task completion events. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| event | string | Yes| Type of the event to subscribe to.
The value is **'completed'**, indicating task completion.| -| callback | function | No| Callback used to return the data structure of the task progress.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | event | string | Yes| Type of the event to subscribe to.
The value is **'completed'**, indicating task completion.| + | callback | function | No| Callback used to return the data structure of the task progress.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 21900005 | task mode error. | + | ID| Error Message| + | -------- | -------- | + | 21900005 | task mode error. | **Example** @@ -2245,7 +2198,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro path: "./taskOffTest.avi", } }]; - let conf = { + let config = { action: request.agent.Action.UPLOAD, url: 'http://127.0.0.1', title: 'taskOffTest', @@ -2270,7 +2223,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro let createOffCallback = (progress) => { console.info('upload task completed.'); }; - request.agent.create(context, conf).then((task)=> { + request.agent.create(context, config).then((task)=> { task.on('completed', createOffCallback); task.off('completed', createOffCallback); console.info(`Succeeded in creating a upload task. result: ${task.tid}`); @@ -2293,18 +2246,18 @@ Unsubscribes from task failure events. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| event | string | Yes| Type of the event to subscribe to.
The value is **'failed'**, indicating task failure.| -| callback | function | No| Callback used to return the data structure of the task progress.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | event | string | Yes| Type of the event to subscribe to.
The value is **'failed'**, indicating task failure.| + | callback | function | No| Callback used to return the data structure of the task progress.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 21900005 | task mode error. | + | ID| Error Message| + | -------- | -------- | + | 21900005 | task mode error. | **Example** @@ -2318,7 +2271,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro path: "./taskOffTest.avi", } }]; - let conf = { + let config = { action: request.agent.Action.UPLOAD, url: 'http://127.0.0.1', title: 'taskOffTest', @@ -2343,7 +2296,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro let createOffCallback = (progress) => { console.info('upload task completed.'); }; - request.agent.create(context, conf).then((task)=> { + request.agent.create(context, config).then((task)=> { task.on('failed', createOffCallback); task.off('failed', createOffCallback); console.info(`Succeeded in creating a upload task. result: ${task.tid}`); @@ -2368,24 +2321,24 @@ Starts this task. This API cannot be used to start an initialized task. This API **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400003 | task service ability error. | -| 21900007 | task state error. | + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900007 | task state error. | **Example** ```js let context; - let conf = { + let config = { action: request.agent.Action.DOWNLOAD, url: 'http://127.0.0.1', title: 'taskStartTest', @@ -2407,7 +2360,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro precise: false, token: "it is a secret" }; - request.agent.create(context, conf).then((task) => { + request.agent.create(context, config).then((task) => { task.start((err) => { if (err) { console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`); @@ -2445,16 +2398,16 @@ Starts this task. This API cannot be used to start an initialized task. This API For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400003 | task service ability error. | -| 21900007 | task state error. | + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900007 | task state error. | **Example** ```js let context; - let conf = { + let config = { action: request.agent.Action.DOWNLOAD, url: 'http://127.0.0.1', title: 'taskStartTest', @@ -2476,7 +2429,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro precise: false, token: "it is a secret" }; - request.agent.create(context, conf).then((task) => { + request.agent.create(context, config).then((task) => { task.start().then(() => { console.info(`Succeeded in starting a download task.`); }).catch((err) => { @@ -2502,25 +2455,25 @@ Pauses this task. This API can be used to pause a background task that is waitin **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400003 | task service ability error. | -| 21900005 | task mode error. | -| 21900007 | task state error. | + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900005 | task mode error. | + | 21900007 | task state error. | **Example** ```js let context; - let conf = { + let config = { action: request.agent.Action.DOWNLOAD, url: 'http://127.0.0.1', title: 'taskPauseTest', @@ -2542,7 +2495,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro precise: false, token: "it is a secret" }; - request.agent.create(context, conf).then((task) => { + request.agent.create(context, config).then((task) => { task.pause((err) => { if (err) { console.error(`Failed to pause the download task, Code: ${err.code}, message: ${err.message}`); @@ -2575,17 +2528,17 @@ Pauses this task. This API can be used to pause a background task that is waitin For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400003 | task service ability error. | -| 21900005 | task mode error. | -| 21900007 | task state error. | + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900005 | task mode error. | + | 21900007 | task state error. | **Example** ```js let context; - let conf = { + let config = { action: request.agent.Action.DOWNLOAD, url: 'http://127.0.0.1', title: 'taskPauseTest', @@ -2607,7 +2560,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro precise: false, token: "it is a secret" }; - request.agent.create(context, conf).then((task) => { + request.agent.create(context, config).then((task) => { task.pause().then(() => { console.info(`Succeeded in pausing a download task. `); }).catch((err) => { @@ -2632,25 +2585,25 @@ Resumes this task. This API can be used to resume a paused background task. This **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400003 | task service ability error. | -| 21900005 | task mode error. | -| 21900007 | task state error. | + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900005 | task mode error. | + | 21900007 | task state error. | **Example** ```js let context; - let conf = { + let config = { action: request.agent.Action.DOWNLOAD, url: 'http://127.0.0.1', title: 'taskResumeTest', @@ -2672,7 +2625,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro precise: false, token: "it is a secret" }; - request.agent.create(context, conf).then((task) => { + request.agent.create(context, config).then((task) => { task.resume((err) => { if (err) { console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`); @@ -2707,17 +2660,17 @@ Resumes this task. This API can be used to resume a paused background task. This For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400003 | task service ability error. | -| 21900005 | task mode error. | -| 21900007 | task state error. | + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900005 | task mode error. | + | 21900007 | task state error. | **Example** ```js let context; - let conf = { + let config = { action: request.agent.Action.DOWNLOAD, url: 'http://127.0.0.1', title: 'taskResumeTest', @@ -2739,7 +2692,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro precise: false, token: "it is a secret" }; - request.agent.create(context, conf).then((task) => { + request.agent.create(context, config).then((task) => { task.resume().then(() => { console.info(`Succeeded in resuming a download task. `); }).catch((err) => { @@ -2762,24 +2715,24 @@ Stops this task. This API can be used to stop a running, waiting, or retrying ta **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | function | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400003 | task service ability error. | -| 21900007 | task state error. | + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900007 | task state error. | **Example** ```js let context; - let conf = { + let config = { action: request.agent.Action.DOWNLOAD, url: 'http://127.0.0.1', title: 'taskStopTest', @@ -2801,7 +2754,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro precise: false, token: "it is a secret" }; - request.agent.create(context, conf).then((task) => { + request.agent.create(context, config).then((task) => { task.stop((err) => { if (err) { console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`); @@ -2834,16 +2787,16 @@ Stops this task. This API can be used to stop a running, waiting, or retrying ta For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400003 | task service ability error. | -| 21900007 | task state error. | + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900007 | task state error. | **Example** ```js let context; - let conf = { + let config = { action: request.agent.Action.DOWNLOAD, url: 'http://127.0.0.1', title: 'taskStopTest', @@ -2865,7 +2818,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro precise: false, token: "it is a secret" }; - request.agent.create(context, conf).then((task) => { + request.agent.create(context, config).then((task) => { task.stop().then(() => { console.info(`Succeeded in stopping a download task. `); }).catch((err) => { @@ -2879,7 +2832,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro ## request.agent.create10+ -create(context: BaseContext, conf: Conf, callback: AsyncCallback<Task>): void +create(context: BaseContext, config: Config, callback: AsyncCallback<Task>): void Creates an upload or download task and adds it to the queue. An application can create a maximum of 10 tasks, and a maximum of 300 tasks can be carried. This API uses an asynchronous callback to return the result. @@ -2890,22 +2843,22 @@ Creates an upload or download task and adds it to the queue. An application can **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| conf | [Conf](#conf10) | Yes| Task configuration.| -| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| -| callback | AsyncCallback<[Task](#task10)> | Yes| Callback used to return the configuration about the created task.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | config | [Config](#config10) | Yes| Task configuration.| + | context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| + | callback | AsyncCallback<[Task](#task10)> | Yes| Callback used to return the configuration about the created task.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400001 | file operation error. | -| 13400003 | task service ability error. | -| 21900004 | application task queue full error. | -| 21900005 | task mode error. | + | ID| Error Message| + | -------- | -------- | + | 13400001 | file operation error. | + | 13400003 | task service ability error. | + | 21900004 | application task queue full error. | + | 21900005 | task mode error. | **Example** @@ -2919,7 +2872,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro path: "./reeateTest.avi", } }]; - let conf = { + let config = { action: request.agent.Action.UPLOAD, url: 'http://127.0.0.1', title: 'reeateTest', @@ -2941,12 +2894,12 @@ For details about the error codes, see [Upload and Download Error Codes](../erro precise: false, token: "it is a secret" }; - request.agent.create(context, conf, (err, task) => { + request.agent.create(context, config, (err, task) => { if (err) { console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); return; } - console.info(`Succeeded in creating a download task. result: ${task.conf}`); + console.info(`Succeeded in creating a download task. result: ${task.config}`); }); ``` @@ -2956,7 +2909,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro ## request.agent.create10+ -create(context: BaseContext, conf: Conf): Promise<Task> +create(context: BaseContext, config: Config): Promise<Task> Creates an upload or download task and adds it to the queue. An application can create a maximum of 10 tasks, and a maximum of 300 tasks can be carried. This API uses a promise to return the result. @@ -2967,10 +2920,10 @@ Creates an upload or download task and adds it to the queue. An application can **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| -| conf | [Conf](#conf10) | Yes| Task configuration.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | context | [BaseContext](js-apis-inner-application-baseContext.md) | Yes| Application-based context.| + | config | [Config](#config10) | Yes| Task configuration.| **Return value** @@ -2982,12 +2935,12 @@ Creates an upload or download task and adds it to the queue. An application can For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400001 | file operation error. | -| 13400003 | task service ability error. | -| 21900004 | application task queue full error. | -| 21900005 | task mode error. | + | ID| Error Message| + | -------- | -------- | + | 13400001 | file operation error. | + | 13400003 | task service ability error. | + | 21900004 | application task queue full error. | + | 21900005 | task mode error. | **Example** @@ -3001,7 +2954,7 @@ For details about the error codes, see [Upload and Download Error Codes](../erro path: "./reeateTest.avi", } }]; - let conf = { + let config = { action: request.agent.Action.UPLOAD, url: 'http://127.0.0.1', title: 'reeateTest', @@ -3023,8 +2976,8 @@ For details about the error codes, see [Upload and Download Error Codes](../erro precise: false, token: "it is a secret" }; - request.agent.create(context, conf).then((task)=> { - console.info(`Succeeded in creating a download task. result: ${task.conf}`); + request.agent.create(context, config).then((task)=> { + console.info(`Succeeded in creating a download task. result: ${task.config}`); }).catch((err) => { console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); }); @@ -3044,19 +2997,19 @@ Removes a specified task of the invoker. If the task is being executed, the task **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| id | string | Yes| Task ID.| -| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | id | string | Yes| Task ID.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| **Error codes** For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400003 | task service ability error. | -| 21900006 | task not found error. | + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900006 | task not found error. | **Example** @@ -3081,9 +3034,9 @@ Removes a specified task of the invoker. If the task is being executed, the task **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| id | string | Yes| Task ID.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | id | string | Yes| Task ID.| **Return value** @@ -3095,10 +3048,10 @@ Removes a specified task of the invoker. If the task is being executed, the task For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). -| ID| Error Message| -| -------- | -------- | -| 13400003 | task service ability error. | -| 21900006 | task not found error. | + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900006 | task not found error. | **Example** @@ -3110,4 +3063,322 @@ For details about the error codes, see [Upload and Download Error Codes](../erro }); ``` + +## request.agent.show10+ + +show(id: string, callback: AsyncCallback<TaskInfo>): void + +Shows the task details based on the task ID. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | id | string | Yes| Task ID.| + | callback | AsyncCallback<TaskInfo> | Yes| Callback used to return task details.| + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900006 | task not found error. | + +**Example** + + ```js + request.agent.show("123456", (err, TaskInfo) => { + if (err) { + console.error(`Failed to show a unload task, Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in showing a unload task.`); + }); + ``` + + +## request.agent.show10+ + +show(id: string): Promise<TaskInfo> + +Queries the task details based on the task ID. This API uses a promise to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | id | string | Yes| Task ID.| + +**Return value** + +| Type | Description | +| ------------------- | ------------------------- | +| Promise<TaskInfo> | Promise Promise used to return task details.| + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900006 | task not found error. | + +**Example** + + ```js + request.agent.show("123456").then((TaskInfo) => { + console.info(`Succeeded in showing a unload task.`); + }).catch((err) => { + console.error(`Failed to show a unload task, Code: ${err.code}, message: ${err.message}`); + }); + ``` + + +## request.agent.touch10+ + +touch(id: string, token: string, callback: AsyncCallback<TaskInfo>): void + +Queries the task details based on the task ID and token. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | id | string | Yes| Task ID.| + | token | string | Yes| Token for task query.| + | callback | AsyncCallback<void> | Yes| Callback used to return task details.| + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900006 | task not found error. | + +**Example** + + ```js + request.agent.touch("123456", "token", (err, TaskInfo) => { + if (err) { + console.error(`Failed to touch a unload task, Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in touching a unload task.`); + }); + ``` + + +## request.agent.touch10+ + +touch(id: string, token: string): Promise<TaskInfo> + +Queries the task details based on the task ID and token. This API uses a promise to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | id | string | Yes| Task ID.| + | token | string | Yes| Token for task query.| + +**Return value** + +| Type | Description | +| ------------------- | ------------------------- | +| Promise<TaskInfo> | Promise Promise used to return task details.| + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900006 | task not found error. | + +**Example** + + ```js + request.agent.touch("123456", "token").then((TaskInfo) => { + console.info(`Succeeded in touching a unload task. `); + }).catch((err) => { + console.error(`Failed to touch a unload task, Code: ${err.code}, message: ${err.message}`); + }); + ``` + + +## request.agent.search10+ + +search(filter: Filter, callback: AsyncCallback<Array<string>>): void + +Searches for task IDs based on [Filter](#filter10). This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | filter | [Filter](#filter10) | Yes| Filter criteria.| + | callback | AsyncCallback<Array<string>> | Yes| Callback used to return task ID matches.| + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + +**Example** + + ```js + let filter ={ + bundle:"com.example.myapplication", + action: request.agent.Action.UPLOAD, + mode:request.agent.Mode.BACKGROUND + } + request.agent.search(filter, (err, data) => { + if (err) { + console.error(`Failed to search a unload task, Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in searching a unload task. `); + }); + ``` + + +## request.agent.search10+ + +search(filter: Filter): Promise<Array<string>> + +Searches for task IDs based on [Filter](#filter10). This API uses a promise to return the result. + +**System capability**: SystemCapability.Request.FileTransferAgent + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | filter | [Filter](#filter10) | Yes| Filter criteria.| + +**Return value** + +| Type | Description | +| ------------------- | ------------------------- | +| Promise<Array<string>> | Promise Promise used to return task ID matches.| + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + +**Example** + + ```js + let filter ={ + bundle:"com.example.myapplication", + action: request.agent.Action.UPLOAD, + mode: request.agent.Mode.BACKGROUND + } + request.agent.search(filter).then((data) => { + console.info(`Succeeded in searching a unload task. `); + }).catch((err) => { + console.error(`Failed to search a unload task, Code: ${err.code}, message: ${err.message}`); + }); + ``` + + +## request.agent.query10+ + +query(id: string, callback: AsyncCallback<TaskInfo>): void + +Queries the task details based on the task ID. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.DOWNLOAD_SESSION_MANAGER or ohos.permission.UPLOAD_SESSION_MANAGER + +**System capability**: SystemCapability.Request.FileTransferAgent + +**System API**: This is a system API. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | id | string | Yes| Task ID.| + | callback | AsyncCallback<TaskInfo> | Yes| Callback used to return task details.| + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900006 | task not found error. | + +**Example** + + ```js + request.agent.query("123456", (err, TaskInfo) => { + if (err) { + console.error(`Failed to query a unload task, Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in querying a unload task. result: ${TaskInfo.uid}`); + }); + ``` + + +## request.agent.query10+ + +query(id: string): Promise<TaskInfo> + +Queries the task details based on the task ID. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.DOWNLOAD_SESSION_MANAGER or ohos.permission.UPLOAD_SESSION_MANAGER + +**System capability**: SystemCapability.Request.FileTransferAgent + +**System API**: This is a system API. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | id | string | Yes| Task ID.| + +**Return value** + +| Type | Description | +| ------------------- | ------------------------- | +| Promise<TaskInfo> | Promise Promise used to return task details.| + +**Error codes** +For details about the error codes, see [Upload and Download Error Codes](../errorcodes/errorcode-request.md). + + | ID| Error Message| + | -------- | -------- | + | 13400003 | task service ability error. | + | 21900006 | task not found error. | + +**Example** + + ```js + request.agent.query("123456",).then((TaskInfo) => { + console.info(`Succeeded in querying a unload task. result: ${TaskInfo.uid}`); + }).catch((err) => { + console.error(`Failed to query a unload task, Code: ${err.code}, message: ${err.message}`); + }); + ``` + diff --git a/en/application-dev/reference/apis/js-apis-resource-manager.md b/en/application-dev/reference/apis/js-apis-resource-manager.md index 406339fa52423ebf5b29d83f9933b47280ea7b9d..40cb3dc087b7b7a756a602925699597ec557c294 100644 --- a/en/application-dev/reference/apis/js-apis-resource-manager.md +++ b/en/application-dev/reference/apis/js-apis-resource-manager.md @@ -35,10 +35,10 @@ getResourceManager(callback: AsyncCallback<ResourceManager>): void Obtains the **ResourceManager** object of this application. This API uses an asynchronous callback to return the result. -**Model restriction**: This API can be used only in the FA model. - **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the FA model. + **Parameters** | Name | Type | Mandatory | Description | @@ -52,7 +52,7 @@ Obtains the **ResourceManager** object of this application. This API uses an asy console.log("error is " + error); return; } - mgr.getString(0x1000000, (error, value) => { + mgr.getStringValue(0x1000000, (error, value) => { if (error != null) { console.log("error is " + error); } else { @@ -70,10 +70,10 @@ getResourceManager(bundleName: string, callback: AsyncCallback<ResourceManage Obtains the **ResourceManager** object of an application based on the specified bundle name. This API uses an asynchronous callback to return the result. -**Model restriction**: This API can be used only in the FA model. - **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the FA model. + **Parameters** | Name | Type | Mandatory | Description | @@ -94,10 +94,10 @@ getResourceManager(): Promise<ResourceManager> Obtains the **ResourceManager** object of this application. This API uses a promise to return the result. -**Model restriction**: This API can be used only in the FA model. - **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the FA model. + **Return value** | Type | Description | @@ -107,7 +107,7 @@ Obtains the **ResourceManager** object of this application. This API uses a prom **Example** ```js resourceManager.getResourceManager().then(mgr => { - mgr.getString(0x1000000, (error, value) => { + mgr.getStringValue(0x1000000, (error, value) => { if (error != null) { console.log("error is " + error); } else { @@ -127,10 +127,10 @@ getResourceManager(bundleName: string): Promise<ResourceManager> Obtains the **ResourceManager** object of an application based on the specified bundle name. This API uses a promise to return the result. -**Model restriction**: This API can be used only in the FA model. - **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the FA model. + **Parameters** | Name | Type | Mandatory | Description | @@ -185,7 +185,7 @@ try { console.log("systemResourceManager getStringValue promise error is " + error); }); } catch (error) { - console.error(`systemResourceManager getStringValue failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`systemResourceManager getStringValue failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -247,16 +247,6 @@ Defines the device configuration. | direction | [Direction](#direction) | Yes | No | Screen direction of the device.| | locale | string | Yes | No | Current system language. | -**Example** - - ```js -resourceManager.getResourceManager((error, mgr) => { - mgr.getConfiguration((error, value) => { - let direction = value.direction; - let locale = value.locale; - }); - }); - ``` ## DeviceCapability @@ -271,16 +261,6 @@ Defines the device capability. | screenDensity | [ScreenDensity](#screendensity) | Yes | No | Screen density of the device.| | deviceType | [DeviceType](#devicetype) | Yes | No | Type of the device. | -**Example** - - ```js -resourceManager.getResourceManager((error, mgr) => { - mgr.getDeviceCapability((error, value) => { - let screenDensity = value.screenDensity; - let deviceType = value.deviceType; - }); - }); - ``` ## RawFileDescriptor8+ @@ -357,7 +337,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getStringValue failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getStringValue failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -401,7 +381,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getStringValue promise error is " + error); }); } catch (error) { - console.error(`promise getStringValue failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getStringValue failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -414,6 +394,8 @@ Obtains the string corresponding to the specified resource object. This API uses **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -447,7 +429,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getStringValue failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getStringValue failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -461,6 +443,8 @@ Obtains the string corresponding to the specified resource object. This API uses **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -497,7 +481,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getStringValue promise error is " + error); }); } catch (error) { - console.error(`callback getStringValue failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getStringValue failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -538,7 +522,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getStringArrayValue failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getStringArrayValue failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -582,7 +566,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getStringArrayValue promise error is " + error); }); } catch (error) { - console.error(`promise getStringArrayValue failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getStringArrayValue failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -594,6 +578,8 @@ Obtains the string array corresponding to the specified resource object. This AP **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -627,7 +613,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getStringArrayValue failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getStringArrayValue failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -639,6 +625,8 @@ Obtains the string array corresponding to the specified resource object. This AP **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -675,7 +663,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getStringArray promise error is " + error); }); } catch (error) { - console.error(`promise getStringArrayValue failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getStringArrayValue failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -714,7 +702,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getMediaContent failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getMediaContent failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -754,7 +742,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getMediaContent failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getMediaContent failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -796,7 +784,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getMediaContent promise error is " + error); }); } catch (error) { - console.error(`promise getMediaContent failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getMediaContent failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -839,7 +827,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.error(`promise getMediaContent failed, error code: ${error.code}, message: ${error.message}.`); }); } catch (error) { - console.error(`promise getMediaContent failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getMediaContent failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -851,6 +839,8 @@ Obtains the content of the media file corresponding to the specified resource ob **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -883,7 +873,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getMediaContent failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getMediaContent failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -895,6 +885,8 @@ Obtains the content of the media file with the screen density corresponding to t **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -928,7 +920,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getMediaContent failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getMediaContent failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -940,6 +932,8 @@ Obtains the content of the media file corresponding to the specified resource ob **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -975,7 +969,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getMediaContent promise error is " + error); }); } catch (error) { - console.error(`promise getMediaContent failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getMediaContent failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -987,6 +981,8 @@ Obtains the content of the media file with the screen density corresponding to t **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -1023,7 +1019,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.error(`promise getMediaContent failed, error code: ${error.code}, message: ${error.message}.`); }); } catch (error) { - console.error(`promise getMediaContent failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getMediaContent failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -1062,7 +1058,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -1102,7 +1098,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -1144,7 +1140,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getMediaContentBase64 promise error is " + error); }); } catch (error) { - console.error(`promise getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -1187,7 +1183,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.error(`promise getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`); }); } catch (error) { - console.error(`promise getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -1199,6 +1195,8 @@ Obtains the Base64 code of the image corresponding to the specified resource obj **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -1231,7 +1229,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`promise getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -1243,6 +1241,8 @@ Obtains the Base64 code of an image with the screen density corresponding to the **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -1270,13 +1270,13 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getMediaContentBase64(resource, 120, (error, value) => { if (error != null) { - console.error(`promise getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`); + console.error(`callback getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`); } else { let media = value; } }); } catch (error) { - console.error(`promise getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -1288,6 +1288,8 @@ Obtains the Base64 code of the image corresponding to the specified resource obj **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -1323,7 +1325,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getMediaContentBase64 promise error is " + error); }); } catch (error) { - console.error(`promise getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -1335,6 +1337,8 @@ Obtains the Base64 code of an image with the screen density corresponding to the **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -1371,7 +1375,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.error(`promise getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`); }); } catch (error) { - console.error(`promise getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getMediaContentBase64 failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -1391,16 +1395,18 @@ Obtains the device configuration. This API uses an asynchronous callback to retu **Example** ```ts - resourceManager.getResourceManager((error, mgr) => { - mgr.getConfiguration((error, value) => { - if (error != null) { - console.log("error is " + error); - } else { - let direction = value.direction; - let locale = value.locale; - } - }); - }); + try { + this.context.resourceManager.getConfiguration((error, value) => { + if (error != null) { + console.error("getConfiguration callback error is " + error); + } else { + let direction = value.direction; + let locale = value.locale; + } + }); + } catch (error) { + console.error("getConfiguration callback error is " + error); + } ``` @@ -1420,14 +1426,16 @@ Obtains the device configuration. This API uses a promise to return the result. **Example** ```ts - resourceManager.getResourceManager((error, mgr) => { - mgr.getConfiguration().then(value => { - let direction = value.direction; - let locale = value.locale; - }).catch(error => { - console.log("getConfiguration promise error is " + error); - }); - }); + try { + this.context.resourceManager.getConfiguration().then(value => { + let direction = value.direction; + let locale = value.locale; + }).catch(error => { + console.error("getConfiguration promise error is " + error); + }); + } catch (error) { + console.error("getConfiguration promise error is " + error); + } ``` @@ -1447,16 +1455,18 @@ Obtains the device capability. This API uses an asynchronous callback to return **Example** ```ts - resourceManager.getResourceManager((error, mgr) => { - mgr.getDeviceCapability((error, value) => { - if (error != null) { - console.log("error is " + error); - } else { - let screenDensity = value.screenDensity; - let deviceType = value.deviceType; - } - }); - }); + try { + this.context.resourceManager.getDeviceCapability((error, value) => { + if (error != null) { + console.error("getDeviceCapability callback error is " + error); + } else { + let screenDensity = value.screenDensity; + let deviceType = value.deviceType; + } + }); + } catch (error) { + console.error("getDeviceCapability callback error is " + error); + } ``` @@ -1476,17 +1486,18 @@ Obtains the device capability. This API uses a promise to return the result. **Example** ```ts - resourceManager.getResourceManager((error, mgr) => { - mgr.getDeviceCapability().then(value => { - let screenDensity = value.screenDensity; - let deviceType = value.deviceType; - }).catch(error => { - console.log("getDeviceCapability promise error is " + error); - }); - }); + try { + this.context.resourceManager.getDeviceCapability().then(value => { + let screenDensity = value.screenDensity; + let deviceType = value.deviceType; + }).catch(error => { + console.error("getDeviceCapability promise error is " + error); + }); + } catch (error) { + console.error("getDeviceCapability promise error is " + error); + } ``` - ### getPluralStringValue9+ getPluralStringValue(resId: number, num: number, callback: AsyncCallback<string>): void @@ -1524,8 +1535,8 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getPluralStringValue failed, error code: ${error.code}, message: ${error.message}.`) - } + console.error(`callback getPluralStringValue failed, error code: ${error.code}, message: ${error.message}.`); + } ``` @@ -1569,8 +1580,8 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getPluralStringValue promise error is " + error); }); } catch (error) { - console.error(`callback getPluralStringValue failed, error code: ${error.code}, message: ${error.message}.`) - } + console.error(`promise getPluralStringValue failed, error code: ${error.code}, message: ${error.message}.`); + } ``` ### getPluralStringValue9+ @@ -1581,6 +1592,8 @@ Obtains the singular-plural string corresponding to the specified resource objec **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -1615,9 +1628,8 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getPluralStringValue failed, error code: ${error.code}, message: ${error.message}.`) - } - + console.error(`callback getPluralStringValue failed, error code: ${error.code}, message: ${error.message}.`); + } ``` ### getPluralStringValue9+ @@ -1628,6 +1640,8 @@ Obtains the singular-plural string corresponding to the specified resource objec **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -1665,7 +1679,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getPluralStringValue promise error is " + error); }); } catch (error) { - console.error(`callback getPluralStringValue failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getPluralStringValue failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -1704,9 +1718,8 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getRawFileContent failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getRawFileContent failed, error code: ${error.code}, message: ${error.message}.`); } - ``` ### getRawFileContent9+ @@ -1746,7 +1759,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getRawFileContent promise error is " + error); }); } catch (error) { - console.error(`promise getRawFileContent failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getRawFileContent failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -1787,8 +1800,8 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getRawFd failed, error code: ${error.code}, message: ${error.message}.`) - }; + console.error(`callback getRawFd failed, error code: ${error.code}, message: ${error.message}.`); + } ``` ### getRawFd9+ @@ -1831,7 +1844,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco }); } catch (error) { console.error(`promise getRawFd failed, error code: ${error.code}, message: ${error.message}.`); - }; + } ``` ### getRawFileList10+ @@ -1862,15 +1875,14 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { // Passing "" means to obtain the list of files in the root directory of the raw file. this.context.resourceManager.getRawFileList("", (error, value) => { if (error != null) { - console.error(`callback getRawFileList failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getRawFileList failed, error code: ${error.code}, message: ${error.message}.`); } else { let rawFile = value; } }); } catch (error) { - console.error(`callback getRawFileList failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getRawFileList failed, error code: ${error.code}, message: ${error.message}.`); } - ``` ### getRawFileList10+ @@ -1907,71 +1919,13 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco this.context.resourceManager.getRawFileList("").then(value => { let rawFile = value; }).catch(error => { - console.error(`promise getRawFileList failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getRawFileList failed, error code: ${error.code}, message: ${error.message}.`); }); } catch (error) { - console.error(`promise getRawFileList failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getRawFileList failed, error code: ${error.code}, message: ${error.message}.`); } ``` -### closeRawFileDescriptor8+ - -closeRawFileDescriptor(path: string, callback: AsyncCallback<void>): void - -Closes the descriptor of the raw file in the **resources/rawfile** directory. This API uses an asynchronous callback to return the result. - -**System capability**: SystemCapability.Global.ResourceManager - -**Parameters** - -| Name | Type | Mandatory | Description | -| -------- | ------------------------- | ---- | ----------- | -| path | string | Yes | Path of the raw file.| -| callback | AsyncCallback<void> | Yes | Callback used to return the result. | - -**Example** - ```ts - resourceManager.getResourceManager((error, mgr) => { - mgr.closeRawFileDescriptor("test.xml", (error, value) => { - if (error != null) { - console.log("error is " + error); - } - }); - }); - ``` - -### closeRawFileDescriptor8+ - -closeRawFileDescriptor(path: string): Promise<void> - -Closes the descriptor of the raw file in the **resources/rawfile** directory. This API uses a promise to return the result. - -**System capability**: SystemCapability.Global.ResourceManager - -**Parameters** - -| Name | Type | Mandatory | Description | -| ---- | ------ | ---- | ----------- | -| path | string | Yes | Path of the raw file.| - -**Return value** - -| Type | Description | -| ------------------- | ---- | -| Promise<void> | Promise that returns no value.| - -**Example** - ```ts - resourceManager.getResourceManager((error, mgr) => { - mgr.closeRawFileDescriptor("test.xml").then(value => { - let result = value; - }).catch(error => { - console.log("closeRawFileDescriptor promise error is " + error); - }); - }); - ``` - - ### closeRawFd9+ closeRawFd(path: string, callback: AsyncCallback<void>): void @@ -2004,7 +1958,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback closeRawFd failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback closeRawFd failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2046,7 +2000,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("closeRawFd promise error is " + error); }); } catch (error) { - console.error(`promise closeRawFd failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise closeRawFd failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2060,9 +2014,11 @@ Releases a created **resourceManager** object. **Example** ```ts - resourceManager.getResourceManager((error, mgr) => { - mgr.release(); - }); + try { + this.context.resourceManager.release(); + } catch (error) { + console.error("release error is " + error); + } ``` ### getStringByName9+ @@ -2101,9 +2057,8 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getStringByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getStringByName failed, error code: ${error.code}, message: ${error.message}.`); } - ``` ### getStringByName9+ @@ -2145,7 +2100,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getStringByName promise error is " + error); }); } catch (error) { - console.error(`promise getStringByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getStringByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2185,7 +2140,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getStringArrayByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getStringArrayByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2228,7 +2183,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getStringArrayByName promise error is " + error); }); } catch (error) { - console.error(`promise getStringArrayByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getStringArrayByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2267,7 +2222,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getMediaByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getMediaByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2307,7 +2262,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getMediaByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getMediaByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2392,7 +2347,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.error(`promise getMediaByName failed, error code: ${error.code}, message: ${error.message}.`); }); } catch (error) { - console.error(`promise getMediaByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getMediaByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2431,7 +2386,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getMediaBase64ByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getMediaBase64ByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2471,7 +2426,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getMediaBase64ByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getMediaBase64ByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2513,7 +2468,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getMediaBase64ByName promise error is " + error); }); } catch (error) { - console.error(`promise getMediaBase64ByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getMediaBase64ByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2556,7 +2511,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.error(`promise getMediaBase64ByName failed, error code: ${error.code}, message: ${error.message}.`); }); } catch (error) { - console.error(`promise getMediaBase64ByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getMediaBase64ByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2597,7 +2552,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getPluralStringByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getPluralStringByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2642,7 +2597,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getPluralStringByName promise error is " + error); }); } catch (error) { - console.error(`promise getPluralStringByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getPluralStringByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2681,7 +2636,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getStringSync($r('app.string.test').id); } catch (error) { - console.error(`getStringSync failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getStringSync failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2722,7 +2677,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getStringSync($r('app.string.test').id, "format string", 10, 98.78); } catch (error) { - console.error(`getStringSync failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getStringSync failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2734,6 +2689,8 @@ Obtains the string corresponding to the specified resource object. This API retu **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -2766,7 +2723,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getStringSync(resource); } catch (error) { - console.error(`getStringSync failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getStringSync failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2778,6 +2735,8 @@ Obtains the string corresponding to the specified resource object and formats th **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -2812,7 +2771,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getStringSync(resource, "format string", 10, 98.78); } catch (error) { - console.error(`getStringSync failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getStringSync failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2851,7 +2810,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getStringByNameSync("test"); } catch (error) { - console.error(`getStringByNameSync failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getStringByNameSync failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2892,7 +2851,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getStringByNameSync("test", "format string", 10, 98.78); } catch (error) { - console.error(`getStringByNameSync failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getStringByNameSync failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -2931,7 +2890,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getBoolean($r('app.boolean.boolean_test').id); } catch (error) { - console.error(`getBoolean failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getBoolean failed, error code: ${error.code}, message: ${error.message}.`); } ``` ### getBoolean9+ @@ -2942,6 +2901,8 @@ Obtains the Boolean result corresponding to the specified resource object. This **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -2974,7 +2935,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getBoolean(resource); } catch (error) { - console.error(`getBoolean failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getBoolean failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3013,7 +2974,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getBooleanByName("boolean_test"); } catch (error) { - console.error(`getBooleanByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getBooleanByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3052,13 +3013,13 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getNumber($r('app.integer.integer_test').id); // integer refers to the original value. } catch (error) { - console.error(`getNumber failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getNumber failed, error code: ${error.code}, message: ${error.message}.`); } try { this.context.resourceManager.getNumber($r('app.float.float_test').id); // float refers to the actual pixel value. } catch (error) { - console.error(`getNumber failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getNumber failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3070,6 +3031,8 @@ Obtains the integer or float value corresponding to the specified resource objec **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -3102,7 +3065,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getNumber(resource);// integer refers to the original value; float refers to the actual pixel value. } catch (error) { - console.error(`getNumber failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getNumber failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3141,13 +3104,13 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getNumberByName("integer_test"); } catch (error) { - console.error(`getNumberByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getNumberByName failed, error code: ${error.code}, message: ${error.message}.`); } try { this.context.resourceManager.getNumberByName("float_test"); } catch (error) { - console.error(`getNumberByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getNumberByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3186,12 +3149,12 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getDrawableDescriptor($r('app.media.icon').id); } catch (error) { - console.error(`getDrawableDescriptor failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getDrawableDescriptor failed, error code: ${error.code}, message: ${error.message}.`); } try { this.context.resourceManager.getDrawableDescriptor($r('app.media.icon').id, 120); } catch (error) { - console.error(`getDrawableDescriptor failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getDrawableDescriptor failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3203,6 +3166,8 @@ Obtains the **DrawableDescriptor** object corresponding to the specified resourc **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -3235,12 +3200,12 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getDrawableDescriptor(resource); } catch (error) { - console.error(`getDrawableDescriptor failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getDrawableDescriptor failed, error code: ${error.code}, message: ${error.message}.`); } try { this.context.resourceManager.getDrawableDescriptor(resource, 120); } catch (error) { - console.error(`getDrawableDescriptor failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getDrawableDescriptor failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3279,12 +3244,12 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getDrawableDescriptorByName('icon'); } catch (error) { - console.error(`getDrawableDescriptor failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getDrawableDescriptorByName failed, error code: ${error.code}, message: ${error.message}.`); } try { this.context.resourceManager.getDrawableDescriptorByName('icon', 120); } catch (error) { - console.error(`getDrawableDescriptor failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getDrawableDescriptorByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3324,7 +3289,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getColor failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getColor failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3367,7 +3332,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getColor promise error is " + error); }); } catch (error) { - console.error(`promise getColor failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getColor failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3379,6 +3344,8 @@ Obtains the color value corresponding to the specified resource object. This API **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -3412,7 +3379,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getColor failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getColor failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3424,6 +3391,8 @@ Obtains the color value corresponding to the specified resource object. This API **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -3460,7 +3429,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getColor promise error is " + error); }); } catch (error) { - console.error(`callback getColor failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getColor failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3500,7 +3469,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco } }); } catch (error) { - console.error(`callback getColorByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`callback getColorByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3543,7 +3512,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco console.log("getColorByName promise error is " + error); }); } catch (error) { - console.error(`promise getColorByName failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`promise getColorByName failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3551,7 +3520,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco getColorSync(resId: number) : number; -Obtains the color value corresponding to the specified resource ID. The API returns the result synchronously. +Obtains the color value corresponding to the specified resource ID. This API returns the result synchronously. **System capability**: SystemCapability.Global.ResourceManager @@ -3582,7 +3551,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getColorSync($r('app.color.test').id); } catch (error) { - console.error(`getColorSync failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getColorSync failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3590,10 +3559,12 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco getColorSync(resource: Resource): number -Obtains the color value corresponding to the specified resource object. The API returns the result synchronously. +Obtains the color value corresponding to the specified resource object. This API returns the result synchronously. **System capability**: SystemCapability.Global.ResourceManager +**Model restriction**: This API can be used only in the stage model. + **Parameters** | Name | Type | Mandatory | Description | @@ -3626,7 +3597,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getColorSync(resource); } catch (error) { - console.error(`getColorSync failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getColorSync failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3634,7 +3605,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco getColorByNameSync(resName: string) : number; -Obtains the color value corresponding to the specified resource name. The API returns the result synchronously. +Obtains the color value corresponding to the specified resource name. This API returns the result synchronously. **System capability**: SystemCapability.Global.ResourceManager @@ -3665,7 +3636,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.getColorByNameSync("test"); } catch (error) { - console.error(`getColorByNameSync failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`getColorByNameSync failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -3697,8 +3668,8 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.context.resourceManager.addResource(path); } catch (error) { - console.error(`addResource failed, error code: ${error.code}, message: ${error.message}.`) - } + console.error(`addResource failed, error code: ${error.code}, message: ${error.message}.`); + } ``` ### removeResource10+ @@ -3729,7 +3700,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco try { this.resmgr.removeResource(path); } catch (error) { - console.error(`removeResource failed, error code: ${error.code}, message: ${error.message}.`) + console.error(`removeResource failed, error code: ${error.code}, message: ${error.message}.`); } ``` @@ -4191,3 +4162,64 @@ This API is deprecated since API version 9. You are advised to use [getRawFd](#g }); }); ``` + +### closeRawFileDescriptor(deprecated) + +closeRawFileDescriptor(path: string, callback: AsyncCallback<void>): void + +Closes the descriptor of the raw file in the **resources/rawfile** directory. This API uses an asynchronous callback to return the result. + +This API is deprecated since API version 9. You are advised to use [closeRawFd](#closerawfd9). + +**System capability**: SystemCapability.Global.ResourceManager + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ------------------------- | ---- | ----------- | +| path | string | Yes | Path of the raw file.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | + +**Example** + ```ts + resourceManager.getResourceManager((error, mgr) => { + mgr.closeRawFileDescriptor("test.xml", (error, value) => { + if (error != null) { + console.log("error is " + error); + } + }); + }); + ``` + +### closeRawFileDescriptor(deprecated) + +closeRawFileDescriptor(path: string): Promise<void> + +Closes the descriptor of the raw file in the **resources/rawfile** directory. This API uses a promise to return the result. + +This API is deprecated since API version 9. You are advised to use [closeRawFd](#closerawfd9-1). + +**System capability**: SystemCapability.Global.ResourceManager + +**Parameters** + +| Name | Type | Mandatory | Description | +| ---- | ------ | ---- | ----------- | +| path | string | Yes | Path of the raw file.| + +**Return value** + +| Type | Description | +| ------------------- | ---- | +| Promise<void> | Promise that returns no value.| + +**Example** + ```ts + resourceManager.getResourceManager((error, mgr) => { + mgr.closeRawFileDescriptor("test.xml").then(value => { + let result = value; + }).catch(error => { + console.log("closeRawFileDescriptor promise error is " + error); + }); + }); + ``` diff --git a/en/application-dev/reference/apis/js-apis-runninglock.md b/en/application-dev/reference/apis/js-apis-runninglock.md index 4d72733c02f607fd17f29f2c4402f059bfee981f..b922bf8e507bb1fd219097870e1520e00ba04224 100644 --- a/en/application-dev/reference/apis/js-apis-runninglock.md +++ b/en/application-dev/reference/apis/js-apis-runninglock.md @@ -16,7 +16,7 @@ import runningLock from '@ohos.runningLock'; isSupported(type: RunningLockType): boolean; -Checks whether the specified type of **RunningLock** is supported. This API uses an asynchronous callback to return the result. +Checks whether the specified type of **RunningLock** is supported. **System capability:** SystemCapability.PowerManager.PowerManager.Core @@ -26,7 +26,7 @@ Checks whether the specified type of **RunningLock** is supported. This API uses | ------ | ----------------------------------- | ---- | -------------------- | | type | [RunningLockType](#runninglocktype) | Yes | Type of the **RunningLock** object.| -**Return Value** +**Return value** | Type | Description | | ------- | --------------------------------------- | @@ -69,14 +69,6 @@ Creates a **RunningLock** object. | type | [RunningLockType](#runninglocktype) | Yes | Type of the **RunningLock** object to be created. | | callback | AsyncCallback<[RunningLock](#runninglock)> | Yes | Callback used to return the result. If a lock is successfully created, **err** is **undefined** and **data** is the created **RunningLock**. Otherwise, **err** is an error object.| -**Error codes** - -For details about the error codes, see [RunningLock Error Codes](../errorcodes/errorcode-runninglock.md). - -| ID | Error Message | -|---------|----------| -| 4900101 | If connecting to the service failed. | - **Example** ```js @@ -106,20 +98,12 @@ Creates a **RunningLock** object. | name | string | Yes | Name of the **RunningLock** object. | | type | [RunningLockType](#runninglocktype) | Yes | Type of the **RunningLock** object to be created.| -**Return Value** +**Return value** | Type | Description | | ------------------------------------------ | ------------------------------------ | | Promise<[RunningLock](#runninglock)> | Promise used to return the result.| -**Error codes** - -For details about the error codes, see [RunningLock Error Codes](../errorcodes/errorcode-runninglock.md). - -| ID | Error Message | -|---------|----------| -| 4900101 | If connecting to the service failed. | - **Example** ```js @@ -138,7 +122,7 @@ isRunningLockTypeSupported(type: RunningLockType, callback: AsyncCallback<boo > **NOTE**
This API is deprecated since API version 9. You are advised to use [runningLock.isSupported](#runninglockissupported9). -Checks whether the specified type of **RunningLock** is supported. This API uses an asynchronous callback to return the result. This API uses an asynchronous callback to return the result. +Checks whether the specified type of **RunningLock** is supported. This API uses an asynchronous callback to return the result. **System capability:** SystemCapability.PowerManager.PowerManager.Core @@ -167,7 +151,7 @@ isRunningLockTypeSupported(type: RunningLockType): Promise<boolean> > **NOTE**
This API is deprecated since API version 9. You are advised to use [runningLock.isSupported](#runninglockissupported9). -Checks whether the specified type of **RunningLock** is supported. This API uses an asynchronous callback to return the result. This API uses a promise to return the result. +Checks whether the specified type of **RunningLock** is supported. This API uses a promise to return the result. **System capability:** SystemCapability.PowerManager.PowerManager.Core @@ -177,7 +161,7 @@ Checks whether the specified type of **RunningLock** is supported. This API uses | ------ | ----------------------------------- | ---- | -------------------- | | type | [RunningLockType](#runninglocktype) | Yes | Type of the **RunningLock** object.| -**Return Value** +**Return value** | Type | Description | | ---------------------- | ---------------------------------------------------- | @@ -246,7 +230,7 @@ Creates a **RunningLock** object. | name | string | Yes | Name of the **RunningLock** object. | | type | [RunningLockType](#runninglocktype) | Yes | Type of the **RunningLock** object to be created.| -**Return Value** +**Return value** | Type | Description | | ------------------------------------------ | ------------------------------------ | @@ -354,7 +338,7 @@ Checks the hold status of the **Runninglock** object. **System capability:** SystemCapability.PowerManager.PowerManager.Core -**Return Value** +**Return value** | Type | Description | | ------- | ------------------------------------------------------------ | @@ -452,7 +436,7 @@ Checks the hold status of the **Runninglock** object. **System capability:** SystemCapability.PowerManager.PowerManager.Core -**Return Value** +**Return value** | Type | Description | | ------- | ------------------------------------------------------------ | | boolean | The value **true** indicates that the **Runninglock** object is held; and the value **false** indicates that the **Runninglock** object is released.| @@ -478,5 +462,5 @@ Enumerates the types of **RunningLock** objects. | Name | Value | Description | | --------------------------------- | ---- | ------------------------------------------------------------ | -| BACKGROUND(deprecated) | 1 | A lock that prevents the system from hibernating when the screen is off.
**NOTE**
This parameter is supported since API version 7 and deprecated since API version 10.| +| BACKGROUND(deprecated) | 1 | A lock that prevents the system from hibernating when the screen is off.
**NOTE**
This parameter is supported since API version 7 and deprecated since API version 10.| | PROXIMITY_SCREEN_CONTROL | 2 | A lock that determines whether to turn on or off the screen based on the distance away from the screen. | diff --git a/en/application-dev/reference/apis/js-apis-socket.md b/en/application-dev/reference/apis/js-apis-socket.md index f7d978eb79961eec5fc32486a6cb0af78fb6eaa9..76c7829cf8fdadad378305ba795212ac10f621ea 100644 --- a/en/application-dev/reference/apis/js-apis-socket.md +++ b/en/application-dev/reference/apis/js-apis-socket.md @@ -1,6 +1,6 @@ # # @ohos.net.socket (Socket Connection) -The **socket** module implements data transfer over TCPSocket, UDPSocket, WebSocket, and TLSSocket connections. +The **socket** module implements data transfer over TCP, UDP, Web, and TLS socket connections. > **NOTE** > @@ -34,7 +34,7 @@ let udp = socket.constructUDPSocketInstance(); ## UDPSocket7+ -Defines a UDPSocket connection. Before calling UDPSocket APIs, you need to call [socket.constructUDPSocketInstance](#socketconstructudpsocketinstance) to create a **UDPSocket** object. +Defines a UDP socket connection. Before calling UDPSocket APIs, you need to call [socket.constructUDPSocketInstance](#socketconstructudpsocketinstance) to create a **UDPSocket** object. ### bind7+ @@ -118,7 +118,7 @@ promise.then(() => { send(options: UDPSendOptions, callback: AsyncCallback\): void -Sends data over a UDPSocket connection. This API uses an asynchronous callback to return the result. +Sends data over a UDP socket connection. This API uses an asynchronous callback to return the result. Before sending data, call [UDPSocket.bind()](#bind) to bind the IP address and port. @@ -130,7 +130,7 @@ Before sending data, call [UDPSocket.bind()](#bind) to bind the IP address and p | Name | Type | Mandatory| Description | | -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | -| options | [UDPSendOptions](#udpsendoptions) | Yes | Parameters for sending data over the UDPSocket connection. For details, see [UDPSendOptions](#udpsendoptions).| +| options | [UDPSendOptions](#udpsendoptions) | Yes | Parameters for sending data over the UDP socket connection. For details, see [UDPSendOptions](#udpsendoptions).| | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** @@ -164,7 +164,7 @@ udp.send({ send(options: UDPSendOptions): Promise\ -Sends data over a UDPSocket connection. This API uses a promise to return the result. +Sends data over a UDP socket connection. This API uses a promise to return the result. Before sending data, call [UDPSocket.bind()](#bind) to bind the IP address and port. @@ -176,7 +176,7 @@ Before sending data, call [UDPSocket.bind()](#bind) to bind the IP address and p | Name | Type | Mandatory| Description | | ------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | -| options | [UDPSendOptions](#udpsendoptions) | Yes | Parameters for sending data over the UDPSocket connection. For details, see [UDPSendOptions](#udpsendoptions).| +| options | [UDPSendOptions](#udpsendoptions) | Yes | Parameters for sending data over the UDP socket connection. For details, see [UDPSendOptions](#udpsendoptions).| **Error codes** @@ -214,7 +214,7 @@ promise.then(() => { close(callback: AsyncCallback\): void -Closes a UDPSocket connection. This API uses an asynchronous callback to return the result. +Closes a UDP socket connection. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERNET @@ -243,7 +243,7 @@ udp.close(err => { close(): Promise\ -Closes a UDPSocket connection. This API uses a promise to return the result. +Closes a UDP socket connection. This API uses a promise to return the result. **Required permissions**: ohos.permission.INTERNET @@ -271,7 +271,7 @@ promise.then(() => { getState(callback: AsyncCallback\): void -Obtains the status of the UDPSocket connection. This API uses an asynchronous callback to return the result. +Obtains the status of the UDP socket connection. This API uses an asynchronous callback to return the result. > **NOTE** > This API can be called only after **bind** is successfully called. @@ -316,7 +316,7 @@ udp.bind({address: '192.168.xx.xxx', port: xxxx, family: 1}, err => { getState(): Promise\ -Obtains the status of the UDPSocket connection. This API uses a promise to return the result. +Obtains the status of the UDP socket connection. This API uses a promise to return the result. > **NOTE** > This API can be called only after **bind** is successfully called. @@ -355,7 +355,7 @@ promise.then(err => { setExtraOptions(options: UDPExtraOptions, callback: AsyncCallback\): void -Sets other properties of the UDPSocket connection. This API uses an asynchronous callback to return the result. +Sets other properties of the UDP socket connection. This API uses an asynchronous callback to return the result. > **NOTE** > This API can be called only after **bind** is successfully called. @@ -368,7 +368,7 @@ Sets other properties of the UDPSocket connection. This API uses an asynchronous | Name | Type | Mandatory| Description | | -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | -| options | [UDPExtraOptions](#udpextraoptions) | Yes | Other properties of the UDPSocket connection. For details, see [UDPExtraOptions](#udpextraoptions).| +| options | [UDPExtraOptions](#udpextraoptions) | Yes | Other properties of the UDP socket connection. For details, see [UDPExtraOptions](#udpextraoptions).| | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** @@ -408,7 +408,7 @@ udp.bind({ address: '192.168.xx.xxx', port: xxxx, family: 1 }, err => { setExtraOptions(options: UDPExtraOptions): Promise\ -Sets other properties of the UDPSocket connection. This API uses a promise to return the result. +Sets other properties of the UDP socket connection. This API uses a promise to return the result. > **NOTE** > This API can be called only after **bind** is successfully called. @@ -421,7 +421,7 @@ Sets other properties of the UDPSocket connection. This API uses a promise to re | Name | Type | Mandatory| Description | | ------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | -| options | [UDPExtraOptions](#udpextraoptions) | Yes | Other properties of the UDPSocket connection. For details, see [UDPExtraOptions](#udpextraoptions).| +| options | [UDPExtraOptions](#udpextraoptions) | Yes | Other properties of the UDP socket connection. For details, see [UDPExtraOptions](#udpextraoptions).| **Return value** @@ -464,7 +464,7 @@ promise.then(() => { on(type: 'message', callback: Callback\<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}\>): void -Enables listening for message receiving events of the UDPSocket connection. This API uses an asynchronous callback to return the result. +Subscribes to **message** events of the UDP socket connection. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -495,10 +495,10 @@ udp.on('message', value => { off(type: 'message', callback?: Callback\<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}\>): void -Disables listening for message receiving events of the UDPSocket connection. This API uses an asynchronous callback to return the result. +Unsubscribes from **message** events of the UDP socket connection. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -524,7 +524,7 @@ let callback = value => { console.log('remoteInfo: ' + JSON.stringify(value.remoteInfo)); } udp.on('message', callback); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. udp.off('message', callback); udp.off('message'); ``` @@ -533,7 +533,7 @@ udp.off('message'); on(type: 'listening' | 'close', callback: Callback\): void -Enables listening for data packet message events or close events of the UDPSocket connection. This API uses an asynchronous callback to return the result. +Subscribes to **listening** events or **close** events of the UDP socket connection. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -560,10 +560,10 @@ udp.on('close', () => { off(type: 'listening' | 'close', callback?: Callback\): void -Disables listening for data packet message events or close events of the UDPSocket connection. This API uses an asynchronous callback to return the result. +Unsubscribes from **listening** events or **close** events of the UDP socket connection. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -582,14 +582,14 @@ let callback1 = () => { console.log("on listening, success"); } udp.on('listening', callback1); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. udp.off('listening', callback1); udp.off('listening'); let callback2 = () => { console.log("on close, success"); } udp.on('close', callback2); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. udp.off('close', callback2); udp.off('close'); ``` @@ -598,7 +598,7 @@ udp.off('close'); on(type: 'error', callback: ErrorCallback): void -Enables listening for error events of the UDPSocket connection. This API uses an asynchronous callback to return the result. +Subscribes to **error** events of the UDP socket connection. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -622,10 +622,10 @@ udp.on('error', err => { off(type: 'error', callback?: ErrorCallback): void -Disables listening for error events of the UDPSocket connection. This API uses an asynchronous callback to return the result. +Unsubscribes from **error** events of the UDP socket connection. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -644,7 +644,7 @@ let callback = err => { console.log("on error, err:" + JSON.stringify(err)); } udp.on('error', callback); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. udp.off('error', callback); udp.off('error'); ``` @@ -663,7 +663,7 @@ Defines the destination address. ## UDPSendOptions7+ -Defines the parameters for sending data over the UDPSocket connection. +Defines the parameters for sending data over the UDP socket connection. **System capability**: SystemCapability.Communication.NetStack @@ -674,7 +674,7 @@ Defines the parameters for sending data over the UDPSocket connection. ## UDPExtraOptions7+ -Defines other properties of the UDPSocket connection. +Defines other properties of the UDP socket connection. **System capability**: SystemCapability.Communication.NetStack @@ -684,7 +684,7 @@ Defines other properties of the UDPSocket connection. | receiveBufferSize | number | No | Size of the receive buffer, in bytes. The default value is **0**. | | sendBufferSize | number | No | Size of the send buffer, in bytes. The default value is **0**. | | reuseAddress | boolean | No | Whether to reuse addresses. The default value is **false**. | -| socketTimeout | number | No | Timeout duration of the UDPSocket connection, in ms. The default value is **0**.| +| socketTimeout | number | No | Timeout duration of the UDP socket connection, in ms. The default value is **0**.| ## SocketStateBase7+ @@ -739,7 +739,7 @@ let tcp = socket.constructTCPSocketInstance(); ## TCPSocket7+ -Defines a TCPSocket connection. Before calling TCPSocket APIs, you need to call [socket.constructTCPSocketInstance](#socketconstructtcpsocketinstance) to create a **TCPSocket** object. +Defines a TCP socket connection. Before calling TCPSocket APIs, you need to call [socket.constructTCPSocketInstance](#socketconstructtcpsocketinstance) to create a **TCPSocket** object. ### bind7+ @@ -747,6 +747,9 @@ bind(address: NetAddress, callback: AsyncCallback\): void Binds the IP address and port number. The port number can be specified or randomly allocated by the system. This API uses an asynchronous callback to return the result. +> **NOTE** +> If the operation fails, the system randomly allocates a port number. + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.Communication.NetStack @@ -784,6 +787,9 @@ bind(address: NetAddress): Promise\ Binds the IP address and port number. The port number can be specified or randomly allocated by the system. This API uses a promise to return the result. +> **NOTE** +> If the operation fails, the system randomly allocates a port number. + **Required permissions**: ohos.permission.INTERNET **System capability**: SystemCapability.Communication.NetStack @@ -836,7 +842,7 @@ Sets up a connection to the specified IP address and port number. This API uses | Name | Type | Mandatory| Description | | -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | -| options | [TCPConnectOptions](#tcpconnectoptions) | Yes | TCPSocket connection parameters. For details, see [TCPConnectOptions](#tcpconnectoptions).| +| options | [TCPConnectOptions](#tcpconnectoptions) | Yes | TCP socket connection parameters. For details, see [TCPConnectOptions](#tcpconnectoptions).| | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** @@ -873,7 +879,7 @@ Sets up a connection to the specified IP address and port number. This API uses | Name | Type | Mandatory| Description | | ------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | -| options | [TCPConnectOptions](#tcpconnectoptions) | Yes | TCPSocket connection parameters. For details, see [TCPConnectOptions](#tcpconnectoptions).| +| options | [TCPConnectOptions](#tcpconnectoptions) | Yes | TCP socket connection parameters. For details, see [TCPConnectOptions](#tcpconnectoptions).| **Return value** @@ -904,7 +910,7 @@ promise.then(() => { send(options: TCPSendOptions, callback: AsyncCallback\): void -Sends data over a TCPSocket connection. This API uses an asynchronous callback to return the result. +Sends data over a TCP socket connection. This API uses an asynchronous callback to return the result. > **NOTE** > This API can be called only after **connect** is successfully called. @@ -917,7 +923,7 @@ Sends data over a TCPSocket connection. This API uses an asynchronous callback t | Name | Type | Mandatory| Description | | -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | -| options | [TCPSendOptions](#tcpsendoptions) | Yes | Parameters for sending data over the TCPSocket connection. For details, see [TCPSendOptions](#tcpsendoptions).| +| options | [TCPSendOptions](#tcpsendoptions) | Yes | Parameters for sending data over the TCP socket connection. For details, see [TCPSendOptions](#tcpsendoptions).| | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** @@ -950,7 +956,7 @@ tcp.connect({ address: { address: '192.168.xx.xxx', port: xxxx, family: 1 }, tim send(options: TCPSendOptions): Promise\ -Sends data over a TCPSocket connection. This API uses a promise to return the result. +Sends data over a TCP socket connection. This API uses a promise to return the result. > **NOTE** > This API can be called only after **connect** is successfully called. @@ -963,7 +969,7 @@ Sends data over a TCPSocket connection. This API uses a promise to return the re | Name | Type | Mandatory| Description | | ------- | --------------------------------------- | ---- | ------------------------------------------------------------ | -| options | [TCPSendOptions](#tcpsendoptions) | Yes | Parameters for sending data over the TCPSocket connection. For details, see [TCPSendOptions](#tcpsendoptions).| +| options | [TCPSendOptions](#tcpsendoptions) | Yes | Parameters for sending data over the TCP socket connection. For details, see [TCPSendOptions](#tcpsendoptions).| **Return value** @@ -1002,7 +1008,7 @@ promise1.then(() => { close(callback: AsyncCallback\): void -Closes a TCPSocket connection. This API uses an asynchronous callback to return the result. +Closes a TCP socket connection. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERNET @@ -1037,7 +1043,7 @@ tcp.close(err => { close(): Promise\ -Closes a TCPSocket connection. This API uses a promise to return the result. +Closes a TCP socket connection. This API uses a promise to return the result. **Required permissions**: ohos.permission.INTERNET @@ -1155,7 +1161,7 @@ promise1.then(() => { getState(callback: AsyncCallback\): void -Obtains the status of the TCPSocket connection. This API uses an asynchronous callback to return the result. +Obtains the status of the TCP socket connection. This API uses an asynchronous callback to return the result. > **NOTE** > This API can be called only after **bind** or **connect** is successfully called. @@ -1196,7 +1202,7 @@ let promise = tcp.connect({ address: { address: '192.168.xx.xxx', port: xxxx, fa getState(): Promise\ -Obtains the status of the TCPSocket connection. This API uses a promise to return the result. +Obtains the status of the TCP socket connection. This API uses a promise to return the result. > **NOTE** > This API can be called only after **bind** or **connect** is successfully called. @@ -1235,11 +1241,92 @@ promise.then(() => { }); ``` +### getSocketFd10+ + +getSocketFd(callback: AsyncCallback\): void + +Obtains the file descriptor of the **TCPSocket** object. This API uses an asynchronous callback to return the result. + +> **NOTE** +> This API can be called only after **bind** or **connect** is successfully called. + +**System capability**: SystemCapability.Communication.NetStack + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------ | ---- | ---------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, the file descriptor of the socket is returned. Otherwise, **undefined** is returned.| + +**Example** + +```js + import socket from "@ohos.net.socket"; + var tcp = socket.constructTCPSocketInstance(); + let tunnelfd = 0 + tcp.bind({ + address: "0.0.0.0", + family: 1, + }) + let connectAddress = { + address: "192.168.1.11", + port: 8888, + family: 1 + }; + tcp.connect({ + address: connectAddress, timeout: 6000 + }) + tcp.getSocketFd((data) => { + console.info("tunenlfd: " + data); + tunnelfd = data + }) +``` +### getSocketFd10+ + +getSocketFd(): Promise\ + +Obtains the file descriptor of the **TCPSocket** object. This API uses a promise to return the result. + +> **NOTE** +> This API can be called only after **bind** or **connect** is successfully called. + +**System capability**: SystemCapability.Communication.NetStack + +**Return value** + +| Type | Description | +| :----------------------------------------------- | :----------------------------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```js + import socket from "@ohos.net.socket"; + var tcp = socket.constructTCPSocketInstance(); + let tunnelfd = 0 + tcp.bind({ + address: "0.0.0.0", + family: 1, + }) + let connectAddress = { + address: "192.168.1.11", + port: 8888, + family: 1 + }; + tcp.connect({ + address: connectAddress, timeout: 6000 + }) + tcp.getSocketFd().then((data) => { + console.info("tunenlfd: " + data); + tunnelfd = data + }) +``` + ### setExtraOptions7+ setExtraOptions(options: TCPExtraOptions, callback: AsyncCallback\): void -Sets other properties of the TCPSocket connection. This API uses an asynchronous callback to return the result. +Sets other properties of the TCP socket connection. This API uses an asynchronous callback to return the result. > **NOTE** > This API can be called only after **bind** or **connect** is successfully called. @@ -1252,7 +1339,7 @@ Sets other properties of the TCPSocket connection. This API uses an asynchronous | Name | Type | Mandatory| Description | | -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| options | [TCPExtraOptions](#tcpextraoptions) | Yes | Other properties of the TCPSocket connection. For details, see [TCPExtraOptions](#tcpextraoptions).| +| options | [TCPExtraOptions](#tcpextraoptions) | Yes | Other properties of the TCP socket connection. For details, see [TCPExtraOptions](#tcpextraoptions).| | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Error codes** @@ -1291,7 +1378,7 @@ let promise = tcp.connect({ address: { address: '192.168.xx.xxx', port: xxxx, fa setExtraOptions(options: TCPExtraOptions): Promise\ -Sets other properties of the TCPSocket connection. This API uses a promise to return the result. +Sets other properties of the TCP socket connection. This API uses a promise to return the result. > **NOTE** > This API can be called only after **bind** or **connect** is successfully called. @@ -1304,7 +1391,7 @@ Sets other properties of the TCPSocket connection. This API uses a promise to re | Name | Type | Mandatory| Description | | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| options | [TCPExtraOptions](#tcpextraoptions) | Yes | Other properties of the TCPSocket connection. For details, see [TCPExtraOptions](#tcpextraoptions).| +| options | [TCPExtraOptions](#tcpextraoptions) | Yes | Other properties of the TCP socket connection. For details, see [TCPExtraOptions](#tcpextraoptions).| **Return value** @@ -1350,7 +1437,7 @@ promise.then(() => { on(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}\>): void -Enables listening for message receiving events of the TCPSocket connection. This API uses an asynchronous callback to return the result. +Subscribes to **message** events of the TCP socket connection. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -1381,10 +1468,10 @@ tcp.on('message', value => { off(type: 'message', callback?: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}\>): void -Disables listening for message receiving events of the TCPSocket connection. This API uses an asynchronous callback to return the result. +Unsubscribes from **message** events of the TCP socket connection. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -1410,7 +1497,7 @@ let callback = value => { console.log('remoteInfo: ' + JSON.stringify(value.remoteInfo)); } tcp.on('message', callback); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. tcp.off('message', callback); tcp.off('message'); ``` @@ -1419,7 +1506,7 @@ tcp.off('message'); on(type: 'connect' | 'close', callback: Callback\): void -Enables listening for connection or close events of the TCPSocket connection. This API uses an asynchronous callback to return the result. +Subscribes to connection or close events of the TCP socket connection. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -1446,10 +1533,10 @@ tcp.on('close', () => { off(type: 'connect' | 'close', callback?: Callback\): void -Disables listening for connection or close events of the TCPSocket connection. This API uses an asynchronous callback to return the result. +Unsubscribes from connection or close events of the TCP socket connection. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -1468,14 +1555,14 @@ let callback1 = () => { console.log("on connect success"); } tcp.on('connect', callback1); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. tcp.off('connect', callback1); tcp.off('connect'); let callback2 = () => { console.log("on close success"); } tcp.on('close', callback2); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. tcp.off('close', callback2); tcp.off('close'); ``` @@ -1484,7 +1571,7 @@ tcp.off('close'); on(type: 'error', callback: ErrorCallback): void -Enables listening for error events of the TCPSocket connection. This API uses an asynchronous callback to return the result. +Subscribes to **error** events of the TCP socket connection. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -1508,10 +1595,10 @@ tcp.on('error', err => { off(type: 'error', callback?: ErrorCallback): void -Disables listening for error events of the TCPSocket connection. This API uses an asynchronous callback to return the result. +Unsubscribes from **error** events of the TCP socket connection. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -1530,25 +1617,25 @@ let callback = err => { console.log("on error, err:" + JSON.stringify(err)); } tcp.on('error', callback); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. tcp.off('error', callback); tcp.off('error'); ``` ## TCPConnectOptions7+ -Defines TCPSocket connection parameters. +Defines TCP socket connection parameters. **System capability**: SystemCapability.Communication.NetStack | Name | Type | Mandatory| Description | | ------- | ---------------------------------- | ---- | -------------------------- | | address | [NetAddress](#netaddress) | Yes | Bound IP address and port number. | -| timeout | number | No | Timeout duration of the TCPSocket connection, in ms.| +| timeout | number | No | Timeout duration of the TCP socket connection, in ms.| ## TCPSendOptions7+ -Defines the parameters for sending data over the TCPSocket connection. +Defines the parameters for sending data over the TCP socket connection. **System capability**: SystemCapability.Communication.NetStack @@ -1559,7 +1646,7 @@ Defines the parameters for sending data over the TCPSocket connection. ## TCPExtraOptions7+ -Defines other properties of the TCPSocket connection. +Defines other properties of the TCP socket connection. **System capability**: SystemCapability.Communication.NetStack @@ -1567,12 +1654,12 @@ Defines other properties of the TCPSocket connection. | ----------------- | ------- | ---- | ------------------------------------------------------------ | | keepAlive | boolean | No | Whether to keep the connection alive. The default value is **false**. | | OOBInline | boolean | No | Whether to enable OOBInline. The default value is **false**. | -| TCPNoDelay | boolean | No | Whether to enable no-delay on the TCPSocket connection. The default value is **false**. | +| TCPNoDelay | boolean | No | Whether to enable no-delay on the TCP socket connection. The default value is **false**. | | socketLinger | Object | Yes | Socket linger.
- **on**: whether to enable socket linger. The value true means to enable socket linger and false means the opposite.
- **linger**: linger time, in ms. The value ranges from **0** to **65535**.
Specify this parameter only when **on** is set to **true**.| | receiveBufferSize | number | No | Size of the receive buffer, in bytes. The default value is **0**. | | sendBufferSize | number | No | Size of the send buffer, in bytes. The default value is **0**. | | reuseAddress | boolean | No | Whether to reuse addresses. The default value is **false**. | -| socketTimeout | number | No | Timeout duration of the UDPSocket connection, in ms. The default value is **0**. | +| socketTimeout | number | No | Timeout duration of the UDP socket connection, in ms. The default value is **0**. | ## socket.constructTCPSocketServerInstance10+ @@ -1602,10 +1689,10 @@ Defines a TCPSocketServer connection. Before calling TCPSocketServer APIs, you n listen(address: NetAddress, callback: AsyncCallback\): void -Binds the IP address and port number. The port number can be specified or randomly allocated by the system. The server listens to and accepts TCPSocket connections established over the socket. Multiple threads are used to process client data concurrently. This API uses an asynchronous callback to return the result. +Binds the IP address and port number. The port number can be specified or randomly allocated by the system. The server listens to and accepts TCP socket connections established over the socket. Multiple threads are used to process client data concurrently. This API uses an asynchronous callback to return the result. > **NOTE** -> The server uses this API to perform the bind, listen, and accept operations. +> The server uses this API to perform the **bind**, **listen**, and **accept** operations. If the **bind** operation fails, the system randomly allocates a port number. **Required permissions**: ohos.permission.INTERNET @@ -1647,10 +1734,10 @@ tcpServer.listen({ address: "192.168.xx.xxx", port: xxxx, family: 1 }, err => { listen(address: NetAddress): Promise\ -Binds the IP address and port number. The port number can be specified or randomly allocated by the system. The server listens to and accepts TCPSocket connections established over the socket. Multiple threads are used to process client data concurrently. This API uses a promise to return the result. +Binds the IP address and port number. The port number can be specified or randomly allocated by the system. The server listens to and accepts TCP socket connections established over the socket. Multiple threads are used to process client data concurrently. This API uses a promise to return the result. > **NOTE** -> The server uses this API to perform the bind, listen, and accept operations. +> The server uses this API to perform the **bind**, **listen**, and **accept** operations. If the **bind** operation fails, the system randomly allocates a port number. **Required permissions**: ohos.permission.INTERNET @@ -1908,7 +1995,10 @@ promise.then(() => { on(type: 'connect', callback: Callback\): void -Enables listening for TCPSocketServer connection events. This API uses an asynchronous callback to return the result. +Subscribes to TCPSocketServer connection events. This API uses an asynchronous callback to return the result. + +> **NOTE** +> This API can be called only after **listen** is successfully called. **System capability**: SystemCapability.Communication.NetStack @@ -1938,10 +2028,10 @@ tcpServer.on('connect', function(data) { off(type: 'connect', callback?: Callback\): void -Disables listening for TCPSocketServer connection events. This API uses an asynchronous callback to return the result. +Unsubscribes from TCPSocketServer connection events. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -1966,7 +2056,7 @@ let callback = data => { console.log('on connect message: ' + JSON.stringify(data)); } tcpServer.on('connect', callback); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. tcpServer.off('connect', callback); tcpServer.off('connect'); ``` @@ -1975,7 +2065,10 @@ tcpServer.off('connect'); on(type: 'error', callback: ErrorCallback): void -Enables listening for error events of the TCPSocketServer connection. This API uses an asynchronous callback to return the result. +Subscribes to **error** events of the TCPSocketServer connection. This API uses an asynchronous callback to return the result. + +> **NOTE** +> This API can be called only after **listen** is successfully called. **System capability**: SystemCapability.Communication.NetStack @@ -2005,10 +2098,10 @@ tcpServer.on('error', err => { off(type: 'error', callback?: ErrorCallback): void -Disables listening for error events of the TCPSocketServer connection. This API uses an asynchronous callback to return the result. +Unsubscribes from **error** events of the TCPSocketServer connection. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -2033,7 +2126,7 @@ let callback = err => { console.log("on error, err:" + JSON.stringify(err)); } tcpServer.on('error', callback); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. tcpServer.off('error', callback); tcpServer.off('error'); ``` @@ -2147,7 +2240,7 @@ tcpServer.on('connect', function(client) { close(callback: AsyncCallback\): void -Closes a **TCPSocketConnection** object. This API uses an asynchronous callback to return the result. +Closes a TCP socket connection. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERNET @@ -2186,7 +2279,7 @@ tcpServer.on('connect', function(client) { close(): Promise\ -Closes a **TCPSocketConnection** object. This API uses a promise to return the result. +Closes a TCP socket connection. This API uses a promise to return the result. **Required permissions**: ohos.permission.INTERNET @@ -2307,7 +2400,7 @@ tcpServer.on('connect', function(client) { on(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}\>): void -Enables listening for **message** events of a **TCPSocketConnection** object. This API uses an asynchronous callback to return the result. +Subscribes to **message** events of a **TCPSocketConnection** object. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -2346,10 +2439,10 @@ tcpServer.on('connect', function(client) { off(type: 'message', callback?: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}\>): void -Disables listening for **message** events of a **TCPSocketConnection** object. This API uses an asynchronous callback to return the result. +Unsubscribes from **message** events of a **TCPSocketConnection** object. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -2382,7 +2475,7 @@ let callback = value => { let tcpServer = socket.constructTCPSocketServerInstance(); tcpServer.on('connect', function(client) { client.on('message', callback); - // You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. + // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. client.off('message', callback); client.off('message'); }); @@ -2392,7 +2485,7 @@ tcpServer.on('connect', function(client) { on(type: 'close', callback: Callback\): void -Enables listening for **close** events of a **TCPSocketConnection** object. This API uses an asynchronous callback to return the result. +Subscribes to **close** events of a **TCPSocketConnection** object. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -2424,10 +2517,10 @@ tcpServer.on('connect', function(client) { on(type: 'close', callback: Callback\): void -Disables listening for **close** events of a **TCPSocketConnection** object. This API uses an asynchronous callback to return the result. +Unsubscribes from **close** events of a **TCPSocketConnection** object. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -2453,7 +2546,7 @@ let callback = () => { let tcpServer = socket.constructTCPSocketServerInstance(); tcpServer.on('connect', function(client) { client.on('close', callback); - // You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. + // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. client.off('close', callback); client.off('close'); }); @@ -2463,7 +2556,7 @@ tcpServer.on('connect', function(client) { on(type: 'error', callback: ErrorCallback): void -Enables listening for **error** events of a **TCPSocketConnection** object. This API uses an asynchronous callback to return the result. +Subscribes to **error** events of a **TCPSocketConnection** object. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -2495,10 +2588,10 @@ tcpServer.on('connect', function(client) { off(type: 'error', callback?: ErrorCallback): void -Disables listening for **error** events of a **TCPSocketConnection** object. This API uses an asynchronous callback to return the result. +Unsubscribes from **error** events of a **TCPSocketConnection** object. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -2524,7 +2617,7 @@ let callback = err => { let tcpServer = socket.constructTCPSocketServerInstance(); tcpServer.on('connect', function(client) { client.on('error', callback); - // You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. + // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. client.off('error', callback); client.off('error'); }); @@ -2558,7 +2651,7 @@ let tls = socket.constructTLSSocketInstance(); ## TLSSocket9+ -Defines a TLSSocket connection. Before calling TLSSocket APIs, you need to call [socket.constructTLSSocketInstance](#socketconstructtlssocketinstance9) to create a **TLSSocket** object. +Defines a TLS socket connection. Before calling TLSSocket APIs, you need to call [socket.constructTLSSocketInstance](#socketconstructtlssocketinstance9) to create a **TLSSocket** object. ### bind9+ @@ -2644,7 +2737,7 @@ promise.then(() => { getState(callback: AsyncCallback\): void -Obtains the status of the TLSSocket connection. This API uses an asynchronous callback to return the result. +Obtains the status of the TLS socket connection. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -2652,7 +2745,7 @@ Obtains the status of the TLSSocket connection. This API uses an asynchronous ca | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------ | ---- | ---------- | -| callback | AsyncCallback\<[SocketStateBase](#socketstatebase)> | Yes | Callback used to return the result. If the operation is successful, the status of the TLSSocket connection is returned. If the operation fails, an error message is returned.| +| callback | AsyncCallback\<[SocketStateBase](#socketstatebase)> | Yes | Callback used to return the result. If the operation is successful, the status of the TLS socket connection is returned. If the operation fails, an error message is returned.| **Error codes** @@ -2684,7 +2777,7 @@ tls.getState((err, data) => { getState(): Promise\ -Obtains the status of the TLSSocket connection. This API uses a promise to return the result. +Obtains the status of the TLS socket connection. This API uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -2722,7 +2815,7 @@ promise.then(() => { setExtraOptions(options: TCPExtraOptions, callback: AsyncCallback\): void -Sets other properties of the TCPSocket connection after **bind** is successfully called. This API uses an asynchronous callback to return the result. +Sets other properties of the TCP socket connection after **bind** is successfully called. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -2730,8 +2823,8 @@ Sets other properties of the TCPSocket connection after **bind** is successfully | Name | Type | Mandatory| Description | | -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| options | [TCPExtraOptions](#tcpextraoptions) | Yes | Other properties of the TCPSocket connection. For details, see [TCPExtraOptions](#tcpextraoptions).| -| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, the result of setting other properties of the TCPSocket connection is returned. If the operation fails, an error message is returned.| +| options | [TCPExtraOptions](#tcpextraoptions) | Yes | Other properties of the TCP socket connection. For details, see [TCPExtraOptions](#tcpextraoptions).| +| callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, the result of setting other properties of the TCP socket connection is returned. If the operation fails, an error message is returned.| **Error codes** @@ -2774,7 +2867,7 @@ tls.setExtraOptions({ setExtraOptions(options: TCPExtraOptions): Promise\ -Sets other properties of the TCPSocket connection after **bind** is successfully called. This API uses a promise to return the result. +Sets other properties of the TCP socket connection after **bind** is successfully called. This API uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -2782,7 +2875,7 @@ Sets other properties of the TCPSocket connection after **bind** is successfully | Name | Type | Mandatory| Description | | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| options | [TCPExtraOptions](#tcpextraoptions) | Yes | Other properties of the TCPSocket connection. For details, see [TCPExtraOptions](#tcpextraoptions).| +| options | [TCPExtraOptions](#tcpextraoptions) | Yes | Other properties of the TCP socket connection. For details, see [TCPExtraOptions](#tcpextraoptions).| **Return value** @@ -2829,7 +2922,7 @@ promise.then(() => { on(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}>): void; -Enables listening for **message** events of the TLSSocket connection. This API uses an asynchronous callback to return the result. +Subscribes to **message** events of the TLS socket connection. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -2860,10 +2953,10 @@ tls.on('message', value => { off(type: 'message', callback?: Callback\<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}\>): void -Disables listening for **message** events of the TLSSocket connection. This API uses an asynchronous callback to return the result. +Unsubscribes from **message** events of the TLS socket connection. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -2872,7 +2965,7 @@ Disables listening for **message** events of the TLSSocket connection. This API | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------------ | ---- | ----------------------------------------- | | type | string | Yes | Type of the event to subscribe to.
**message**: message receiving event.| -| callback | Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}> | No | Callback used to return the result.
**message**: received message.
**remoteInfo**: socket connection information.| +| callback | Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}> | No | Callback used to return the result.
**message**: received message.
**remoteInfo**: socket connection information.| **Example** @@ -2889,14 +2982,14 @@ let callback = value => { console.log('remoteInfo: ' + JSON.stringify(value.remoteInfo)); } tls.on('message', callback); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. tls.off('message', callback); ``` ### on('connect' | 'close')9+ on(type: 'connect' | 'close', callback: Callback\): void -Enables listening for **connect** or **close** events of the TLSSocket connection. This API uses an asynchronous callback to return the result. +Subscribes to **connect** or **close** events of the TLS socket connection. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -2923,10 +3016,10 @@ tls.on('close', () => { off(type: 'connect' | 'close', callback?: Callback\): void -Disables listening for **connect** or **close** events of the TLSSocket connection. This API uses an asynchronous callback to return the result. +Unsubscribes from **connect** or **close** events of the TLS socket connection. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -2945,14 +3038,14 @@ let callback1 = () => { console.log("on connect success"); } tls.on('connect', callback1); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. tls.off('connect', callback1); tls.off('connect'); let callback2 = () => { console.log("on close success"); } tls.on('close', callback2); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. tls.off('close', callback2); ``` @@ -2960,7 +3053,7 @@ tls.off('close', callback2); on(type: 'error', callback: ErrorCallback): void -Enables listening for error events of the TLSSocket connection. This API uses an asynchronous callback to return the result. +Subscribes to **error** events of the TLS socket connection. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -2984,10 +3077,10 @@ tls.on('error', err => { off(type: 'error', callback?: ErrorCallback): void -Disables listening for error events of the TLSSocket connection. This API uses an asynchronous callback to return the result. +Unsubscribes from **error** events of the TLS socket connection. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -3006,7 +3099,7 @@ let callback = err => { console.log("on error, err:" + JSON.stringify(err)); } tls.on('error', callback); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. tls.off('error', callback); ``` @@ -3014,7 +3107,7 @@ tls.off('error', callback); connect(options: TLSConnectOptions, callback: AsyncCallback\): void -Sets up a TLSSocket connection, and creates and initializes a TLS session after **bind** is successfully called. During this process, a TLS/SSL handshake is performed between the application and the server to implement data transmission. This API uses an asynchronous callback to return the result. +Sets up a TLS socket connection, and creates and initializes a TLS session after **bind** is successfully called. During this process, a TLS/SSL handshake is performed between the application and the server to implement data transmission. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3022,7 +3115,7 @@ Sets up a TLSSocket connection, and creates and initializes a TLS session after | Name | Type | Mandatory| Description| | -------- | ---------------------------------------| ----| --------------- | -| options | [TLSConnectOptions](#tlsconnectoptions9) | Yes | Parameters required for the TLSSocket connection.| +| options | [TLSConnectOptions](#tlsconnectoptions9) | Yes | Parameters required for the TLS socket connection.| | callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.| **Error codes** @@ -3108,7 +3201,7 @@ tlsOneWay.connect(oneWayOptions, (err, data) => { connect(options: TLSConnectOptions): Promise\ -Sets up a TLSSocket connection, and creates and initializes a TLS session after **bind** is successfully called. During this process, a TLS/SSL handshake is performed between the application and the server to implement data transmission. Both two-way and one-way authentication modes are supported. This API uses a promise to return the result. +Sets up a TLS socket connection, and creates and initializes a TLS session after **bind** is successfully called. During this process, a TLS/SSL handshake is performed between the application and the server to implement data transmission. Both two-way and one-way authentication modes are supported. This API uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3209,7 +3302,7 @@ tlsOneWay.connect(oneWayOptions).then(data => { getRemoteAddress(callback: AsyncCallback\): void -Obtains the remote address of a TLSSocket connection. This API uses an asynchronous callback to return the result. +Obtains the remote address of a TLS socket connection. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3242,7 +3335,7 @@ tls.getRemoteAddress((err, data) => { getRemoteAddress(): Promise\ -Obtains the remote address of a TLSSocket connection. This API uses a promise to return the result. +Obtains the remote address of a TLS socket connection. This API uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3274,7 +3367,7 @@ promise.then(() => { getCertificate(callback: AsyncCallback\<[X509CertRawData](#x509certrawdata9)\>): void -Obtains the local digital certificate after a TLSSocket connection is established. This API is applicable to two-way authentication. It uses an asynchronous callback to return the result. +Obtains the local digital certificate after a TLS socket connection is established. This API is applicable to two-way authentication. It uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3308,7 +3401,7 @@ tls.getCertificate((err, data) => { getCertificate():Promise\<[X509CertRawData](#x509certrawdata9)\> -Obtains the local digital certificate after a TLSSocket connection is established. This API is applicable to two-way authentication. It uses a promise to return the result. +Obtains the local digital certificate after a TLS socket connection is established. This API is applicable to two-way authentication. It uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3340,7 +3433,7 @@ tls.getCertificate().then(data => { getRemoteCertificate(callback: AsyncCallback\<[X509CertRawData](#x509certrawdata9)\>): void -Obtains the digital certificate of the server after a TLSSocket connection is established. This API uses an asynchronous callback to return the result. +Obtains the digital certificate of the server after a TLS socket connection is established. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3373,7 +3466,7 @@ tls.getRemoteCertificate((err, data) => { getRemoteCertificate():Promise\<[X509CertRawData](#x509certrawdata9)\> -Obtains the digital certificate of the server after a TLSSocket connection is established. This API uses a promise to return the result. +Obtains the digital certificate of the server after a TLS socket connection is established. This API uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3404,7 +3497,7 @@ tls.getRemoteCertificate().then(data => { getProtocol(callback: AsyncCallback\): void -Obtains the communication protocol version after a TLSSocket connection is established. This API uses an asynchronous callback to return the result. +Obtains the communication protocol version after a TLS socket connection is established. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3438,7 +3531,7 @@ tls.getProtocol((err, data) => { getProtocol():Promise\ -Obtains the communication protocol version after a TLSSocket connection is established. This API uses a promise to return the result. +Obtains the communication protocol version after a TLS socket connection is established. This API uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3470,7 +3563,7 @@ tls.getProtocol().then(data => { getCipherSuite(callback: AsyncCallback\\>): void -Obtains the cipher suite negotiated by both communication parties after a TLSSocket connection is established. This API uses an asynchronous callback to return the result. +Obtains the cipher suite negotiated by both communication parties after a TLS socket connection is established. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3505,7 +3598,7 @@ tls.getCipherSuite((err, data) => { getCipherSuite(): Promise\\> -Obtains the cipher suite negotiated by both communication parties after a TLSSocket connection is established. This API uses a promise to return the result. +Obtains the cipher suite negotiated by both communication parties after a TLS socket connection is established. This API uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3538,7 +3631,7 @@ tls.getCipherSuite().then(data => { getSignatureAlgorithms(callback: AsyncCallback\\>): void -Obtains the signing algorithm negotiated by both communication parties after a TLSSocket connection is established. This API is applicable to two-way authentication. It uses an asynchronous callback to return the result. +Obtains the signing algorithm negotiated by both communication parties after a TLS socket connection is established. This API is applicable to two-way authentication. It uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3571,7 +3664,7 @@ tls.getSignatureAlgorithms((err, data) => { getSignatureAlgorithms(): Promise\\> -Obtains the signing algorithm negotiated by both communication parties after a TLSSocket connection is established. This API is applicable to two-way authentication. It uses a promise to return the result. +Obtains the signing algorithm negotiated by both communication parties after a TLS socket connection is established. This API is applicable to two-way authentication. It uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3602,7 +3695,7 @@ tls.getSignatureAlgorithms().then(data => { send(data: string, callback: AsyncCallback\): void -Sends a message to the server after a TLSSocket connection is established. This API uses an asynchronous callback to return the result. +Sends a message to the server after a TLS socket connection is established. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3640,7 +3733,7 @@ tls.send("xxxx", (err) => { send(data: string): Promise\ -Sends a message to the server after a TLSSocket connection is established. This API uses a promise to return the result. +Sends a message to the server after a TLS socket connection is established. This API uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3681,7 +3774,7 @@ tls.send("xxxx").then(() => { close(callback: AsyncCallback\): void -Closes a TLSSocket connection. This API uses an asynchronous callback to return the result. +Closes a TLS socket connection. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3717,7 +3810,7 @@ tls.close((err) => { close(): Promise\ -Closes a TLSSocket connection. This API uses a promise to return the result. +Closes a TLS socket connection. This API uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -3815,7 +3908,7 @@ let tlsServer = socket.constructTLSSocketServerInstance(); ## TLSSocketServer10+ -Defines a TLSSocketServer connection. Before calling TLSSocketServer APIs, you need to call [socket.constructTLSSocketServerInstance](#socketconstructtlssocketserverinstance10) to create a **TLSSocketServer** object. +Defines a TLS socket server connection. Before calling TLSSocketServer APIs, you need to call [socket.constructTLSSocketServerInstance](#socketconstructtlssocketserverinstance10) to create a **TLSSocketServer** object. ### listen10+ @@ -3950,7 +4043,7 @@ tlsServer.listen(options).then(() => { getState(callback: AsyncCallback\): void -Obtains the status of the TLSSocketServer connection upon successful listening. This API uses an asynchronous callback to return the result. +Obtains the status of the TLS socket server connection upon successful listening. This API uses an asynchronous callback to return the result. > **NOTE** > This API can be called only after **listen** is successfully called. @@ -3961,7 +4054,7 @@ Obtains the status of the TLSSocketServer connection upon successful listening. | Name | Type | Mandatory| Description | | -------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | -| callback | AsyncCallback\<[SocketStateBase](#socketstatebase7)> | Yes | Callback used to return the result. If the operation is successful, the status of the TLSSocketServer connection is returned. If the operation fails, an error message is returned.| +| callback | AsyncCallback\<[SocketStateBase](#socketstatebase7)> | Yes | Callback used to return the result. If the operation is successful, the status of the TLS socket server connection is returned. If the operation fails, an error message is returned.| **Error codes** @@ -4011,7 +4104,7 @@ tlsServer.getState((err, data) => { getState(): Promise\ -Obtains the status of the TLSSocketServer connection upon successful listening. This API uses a promise to return the result. +Obtains the status of the TLS socket server connection upon successful listening. This API uses a promise to return the result. > **NOTE** > This API can be called only after **listen** is successfully called. @@ -4071,7 +4164,7 @@ promise.then(() => { setExtraOptions(options: TCPExtraOptions, callback: AsyncCallback\): void -Sets other properties of the TLSSocketServer connection upon successful listening. This API uses an asynchronous callback to return the result. +Sets other properties of the TLS socket server connection upon successful listening. This API uses an asynchronous callback to return the result. > **NOTE** > This API can be called only after **listen** is successfully called. @@ -4082,7 +4175,7 @@ Sets other properties of the TLSSocketServer connection upon successful listenin | Name | Type | Mandatory| Description | | -------- | ------------------------------------ | ---- | ------------------------------------------------ | -| options | [TCPExtraOptions](#tcpextraoptions7) | Yes | Other properties of the TLSSocketServer connection. | +| options | [TCPExtraOptions](#tcpextraoptions7) | Yes | Other properties of the TLS socket server connection. | | callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.| **Error codes** @@ -4141,7 +4234,7 @@ tlsServer.setExtraOptions({ setExtraOptions(options: TCPExtraOptions): Promise\ -Sets other properties of the TLSSocketServer connection upon successful listening. This API uses a promise to return the result. +Sets other properties of the TLS socket server connection upon successful listening. This API uses a promise to return the result. > **NOTE** > This API can be called only after **listen** is successfully called. @@ -4152,7 +4245,7 @@ Sets other properties of the TLSSocketServer connection upon successful listenin | Name | Type | Mandatory| Description | | ------- | ------------------------------------ | ---- | ------------------------------- | -| options | [TCPExtraOptions](#tcpextraoptions7) | Yes | Other properties of the TLSSocketServer connection.| +| options | [TCPExtraOptions](#tcpextraoptions7) | Yes | Other properties of the TLS socket server connection.| **Return value** @@ -4217,7 +4310,7 @@ promise.then(() => { getCertificate(callback: AsyncCallback\<[X509CertRawData](#x509certrawdata9)\>): void -Obtains the local digital certificate after a TLSSocketServer connection is established. This API uses an asynchronous callback to return the result. +Obtains the local digital certificate after a TLS socket server connection is established. This API uses an asynchronous callback to return the result. > **NOTE** > This API can be called only after **listen** is successfully called. @@ -4278,7 +4371,7 @@ tlsServer.getCertificate((err, data) => { getCertificate():Promise\<[X509CertRawData](#x509certrawdata9)\> -Obtains the local digital certificate after a TLSSocketServer connection is established. This API uses a promise to return the result. +Obtains the local digital certificate after a TLS socket server connection is established. This API uses a promise to return the result. > **NOTE** > This API can be called only after **listen** is successfully called. @@ -4338,7 +4431,7 @@ tlsServer.getCertificate().then(data => { getProtocol(callback: AsyncCallback\): void -Obtains the communication protocol version after a TLSSocketServer connection is established. This API uses an asynchronous callback to return the result. +Obtains the communication protocol version after a TLS socket server connection is established. This API uses an asynchronous callback to return the result. > **NOTE** > This API can be called only after **listen** is successfully called. @@ -4399,7 +4492,7 @@ tlsServer.getProtocol((err, data) => { getProtocol():Promise\ -Obtains the communication protocol version after a TLSSocketServer connection is established. This API uses a promise to return the result. +Obtains the communication protocol version after a TLS socket server connection is established. This API uses a promise to return the result. > **NOTE** > This API can be called only after **listen** is successfully called. @@ -4453,11 +4546,11 @@ tlsServer.getProtocol().then(data => { }); ``` -### on('connect') +### on('connect')10+ on(type: 'connect', callback: Callback\): void -Enables listening for TLSSocketServer connection events. This API uses an asynchronous callback to return the result. +Subscribes to TLS socket server connection events. This API uses an asynchronous callback to return the result. > **NOTE** > This API can be called only after **listen** is successfully called. @@ -4508,14 +4601,15 @@ tlsServer.on('connect', function(data) { }); ``` -### off('connect') +### off('connect')10+ off(type: 'connect', callback?: Callback\): void -Disables listening for TLSSocketServer connection events. This API uses an asynchronous callback to return the result. +Unsubscribes from TLS socket server connection events. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> This API can be called only after **listen** is successfully called. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -4564,16 +4658,16 @@ tlsServer.listen(options).then(() => { return; }); tlsServer.on('connect', callback); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. tlsServer.off('connect', callback); tlsServer.off('connect'); ``` -### on('error') +### on('error')10+ on(type: 'error', callback: ErrorCallback): void -Enables listening for **error** events of a **TLSSocketServer** object. This API uses an asynchronous callback to return the result. +Subscribes to **error** events of a **TLSSocketServer** object. This API uses an asynchronous callback to return the result. > **NOTE** > This API can be called only after **listen** is successfully called. @@ -4624,14 +4718,15 @@ tlsServer.on('error', err => { }); ``` -### off('error') +### off('error')10+ off(type: 'error', callback?: ErrorCallback): void -Disables listening for **error** events of a **TLSSocketServer** object. This API uses an asynchronous callback to return the result. +Unsubscribes from **error** events of a **TLSSocketServer** object. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> This API can be called only after **listen** is successfully called. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -4680,7 +4775,7 @@ tlsServer.listen(options).then(() => { return; }); tlsServer.on('error', callback); -// You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. +// You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. tlsServer.off('error', callback); tlsServer.off('error'); ``` @@ -4704,7 +4799,7 @@ Defines a **TLSSocketConnection** object, that is, the connection between the TL send(data: string, callback: AsyncCallback\): void -Sends a message to the client after a TLSSocketServer connection is established. This API uses an asynchronous callback to return the result. +Sends a message to the client after a TLS socket server connection is established. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -4712,7 +4807,7 @@ Sends a message to the client after a TLSSocketServer connection is established. | Name | Type | Mandatory| Description | | -------- | --------------------- | ---- | ------------------------------------------------ | -| data | string | Yes | Parameters for sending data over the TLSSocketServer connection. | +| data | string | Yes | Parameters for sending data over the TLS socket server connection. | | callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, no value is returned. If the operation fails, an error message is returned.| **Error codes** @@ -4767,7 +4862,7 @@ tlsServer.on('connect', function(client) { send(data: string): Promise\ -Sends a message to the server after a TLSSocketServer connection is established. This API uses a promise to return the result. +Sends a message to the server after a TLS socket server connection is established. This API uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -4775,7 +4870,7 @@ Sends a message to the server after a TLSSocketServer connection is established. | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------------------------- | -| data | string | Yes | Parameters required for the TLSSocketServer connection.| +| data | string | Yes | Parameters required for the TLS socket server connection.| **Return value** @@ -4836,7 +4931,7 @@ tlsServer.on('connect', function(client) { close(callback: AsyncCallback\): void -Closes a TLSSocketServer connection. This API uses an asynchronous callback to return the result. +Closes a TLS socket server connection. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -4897,7 +4992,7 @@ tlsServer.on('connect', function(client) { close(): Promise\ -Closes a TLSSocketServer connection. This API uses a promise to return the result. +Closes a TLS socket server connection. This API uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -4958,7 +5053,7 @@ tlsServer.on('connect', function(client) { getRemoteAddress(callback: AsyncCallback\): void -Obtains the remote address of a TLSSocketServer connection. This API uses an asynchronous callback to return the result. +Obtains the remote address of a TLS socket server connection. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -5017,7 +5112,7 @@ tlsServer.on('connect', function(client) { getRemoteAddress(): Promise\ -Obtains the remote address of a TLSSocketServer connection. This API uses a promise to return the result. +Obtains the remote address of a TLS socket server connection. This API uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -5075,7 +5170,7 @@ tlsServer.on('connect', function(client) { getRemoteCertificate(callback: AsyncCallback\<[X509CertRawData](#x509certrawdata9)\>): void -Obtains the digital certificate of the peer end after a TLSSocketServer connection is established. This API uses an asynchronous callback to return the result. It applies only to the scenario where the client sends a certificate to the server. +Obtains the digital certificate of the peer end after a TLS socket server connection is established. This API uses an asynchronous callback to return the result. It applies only to the scenario where the client sends a certificate to the server. **System capability**: SystemCapability.Communication.NetStack @@ -5134,7 +5229,7 @@ tlsServer.on('connect', function(client) { getRemoteCertificate():Promise\<[X509CertRawData](#x509certrawdata9)\> -Obtains the digital certificate of the peer end after a TLSSocketServer connection is established. This API uses a promise to return the result. It applies only to the scenario where the client sends a certificate to the server. +Obtains the digital certificate of the peer end after a TLS socket server connection is established. This API uses a promise to return the result. It applies only to the scenario where the client sends a certificate to the server. **System capability**: SystemCapability.Communication.NetStack @@ -5192,7 +5287,7 @@ tlsServer.on('connect', function(client) { getCipherSuite(callback: AsyncCallback\\>): void -Obtains the cipher suite negotiated by both communication parties after a TLSSocketServer connection is established. This API uses an asynchronous callback to return the result. +Obtains the cipher suite negotiated by both communication parties after a TLS socket server connection is established. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -5253,7 +5348,7 @@ tlsServer.on('connect', function(client) { getCipherSuite(): Promise\\> -Obtains the cipher suite negotiated by both communication parties after a TLSSocketServer connection is established. This API uses a promise to return the result. +Obtains the cipher suite negotiated by both communication parties after a TLS socket server connection is established. This API uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -5313,7 +5408,7 @@ tlsServer.on('connect', function(client) { getSignatureAlgorithms(callback: AsyncCallback\\>): void -Obtains the signing algorithm negotiated by both communication parties after a TLSSocketServer connection is established. This API uses an asynchronous callback to return the result. +Obtains the signing algorithm negotiated by both communication parties after a TLS socket server connection is established. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -5372,7 +5467,7 @@ tlsServer.on('connect', function(client) { getSignatureAlgorithms(): Promise\\> -Obtains the signing algorithm negotiated by both communication parties after a TLSSocketServer connection is established. This API uses a promise to return the result. +Obtains the signing algorithm negotiated by both communication parties after a TLS socket server connection is established. This API uses a promise to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -5430,7 +5525,7 @@ tlsServer.on('connect', function(client) { on(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}\>): void -Enables listening for **message** events of a **TLSSocketConnection** object. This API uses an asynchronous callback to return the result. +Subscribes to **message** events of a **TLSSocketConnection** object. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -5491,10 +5586,10 @@ tlsServer.on('connect', function(client) { off(type: 'message', callback?: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}\>): void -Disables listening for **message** events of a **TLSSocketConnection** object. This API uses an asynchronous callback to return the result. +Unsubscribes from **message** events of a **TLSSocketConnection** object. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -5551,7 +5646,7 @@ tlsServer.listen(options).then(() => { }); tlsServer.on('connect', function(client) { client.on('message', callback); - // You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. + // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. client.off('message', callback); client.off('message'); }); @@ -5561,7 +5656,7 @@ tlsServer.on('connect', function(client) { on(type: 'close', callback: Callback\): void -Enables listening for **close** events of a **TLSSocketConnection** object. This API uses an asynchronous callback to return the result. +Subscribes to **close** events of a **TLSSocketConnection** object. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -5615,10 +5710,10 @@ tlsServer.on('connect', function(client) { on(type: 'close', callback: Callback\): void -Disables listening for **close** events of a **TLSSocketConnection** object. This API uses an asynchronous callback to return the result. +Unsubscribes from **close** events of a **TLSSocketConnection** object. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -5668,7 +5763,7 @@ tlsServer.listen(options).then(() => { }); tlsServer.on('connect', function(client) { client.on('close', callback); - // You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. + // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. client.off('close', callback); client.off('close'); }); @@ -5678,7 +5773,7 @@ tlsServer.on('connect', function(client) { on(type: 'error', callback: ErrorCallback): void -Enables listening for **error** events of a **TLSSocketConnection** object. This API uses an asynchronous callback to return the result. +Subscribes to **error** events of a **TLSSocketConnection** object. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Communication.NetStack @@ -5732,10 +5827,10 @@ tlsServer.on('connect', function(client) { off(type: 'error', callback?: ErrorCallback): void -Disables listening for **error** events of a **TLSSocketConnection** object. This API uses an asynchronous callback to return the result. +Unsubscribes from **error** events of a **TLSSocketConnection** object. This API uses an asynchronous callback to return the result. > **NOTE** -> You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events. +> You can pass the callback of the **on** function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. **System capability**: SystemCapability.Communication.NetStack @@ -5785,7 +5880,7 @@ tlsServer.listen(options).then(() => { }); tlsServer.on('connect', function(client) { client.on('error', callback); - // You can pass the callback of the on method to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. + // You can pass the callback of the on function if you want to cancel listening for a certain type of events. If you do not pass the callback, you will cancel listening for all events. client.off('error', callback); client.off('error'); }); diff --git a/en/application-dev/reference/apis/js-apis-system-bluetooth.md b/en/application-dev/reference/apis/js-apis-system-bluetooth.md index 497e0817fcfcd1ca12c43948a8907b96871a1287..fa2b3a48fe2368b929759c72227a6e3aeefa5a6a 100644 --- a/en/application-dev/reference/apis/js-apis-system-bluetooth.md +++ b/en/application-dev/reference/apis/js-apis-system-bluetooth.md @@ -3,9 +3,9 @@ > **NOTE** > -> - The APIs of this module are no longer maintained since API version 7. You are advised to use [`@ohos.bluetooth`](js-apis-bluetooth.md). -> > - The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> +> - The APIs provided by this module are no longer maintained since API version 7. You are advised to use profile APIs of [@ohos.bluetooth.ble](js-apis-bluetooth-ble.md). ## Modules to Import diff --git a/en/application-dev/reference/apis/js-apis-usb-deprecated.md b/en/application-dev/reference/apis/js-apis-usb-deprecated.md index f5c4bc2d05b1ac5e085f573c1730882afc38a03c..09435e9ce50ace4533694004f3dcb4896236feaf 100644 --- a/en/application-dev/reference/apis/js-apis-usb-deprecated.md +++ b/en/application-dev/reference/apis/js-apis-usb-deprecated.md @@ -137,7 +137,7 @@ Checks whether the application has the permission to access the device. **Example** ```js -let devicesName="1-1"; +let devicesName= "1-1"; let bool = usb.hasRight(devicesName); console.log(bool); ``` @@ -165,7 +165,7 @@ Requests the temporary permission for the application to access a USB device. Th **Example** ```js -let devicesName="1-1"; +let devicesName= "1-1"; usb.requestRight(devicesName).then((ret) => { console.log(`requestRight = ${ret}`); }); @@ -375,7 +375,14 @@ Before you do this, call [usb.getDevices](#usbgetdevices) to obtain the USB devi **Example** ```js -let param = new usb.USBControlParams(); +let param = { + request: 0, + reqType: 0, + target:0, + value: 0, + index: 0, + data: null +}; usb.controlTransfer(devicepipe, param).then((ret) => { console.log(`controlTransfer = ${ret}`); }) @@ -500,7 +507,7 @@ Converts the USB function list in the numeric mask format to a string in Device **Example** ```js -let funcs = usb.ACM | usb.ECM; +let funcs = usb.FunctionType.ACM | usb.FunctionType.ECM; let ret = usb.usbFunctionsToString(funcs); ``` @@ -529,8 +536,12 @@ Sets the current USB function list in Device mode. **Example** ```js -let funcs = usb.HDC; -let ret = usb.setCurrentFunctions(funcs); +let funcs = usb.FunctionType.HDC; +usb.setCurrentFunctions(funcs).then(() => { + console.info('usb setCurrentFunctions successfully.'); +}).catch(err => { + console.error('usb setCurrentFunctions failed: ' + err.code + ' message: ' + err.message); +}); ``` ## usb.getCurrentFunctions9+ @@ -848,7 +859,7 @@ Enumerates power role types. | Name | Value | Description | | ------ | ---- | ---------- | -| NONE | 0 | None | +| NONE | 0 | None. | | SOURCE | 1 | External power supply.| | SINK | 2 | Internal power supply.| @@ -862,6 +873,6 @@ Enumerates data role types. | Name | Value | Description | | ------ | ---- | ------------ | -| NONE | 0 | None | +| NONE | 0 | None. | | HOST | 1 | USB host.| | DEVICE | 2 | USB device.| diff --git a/en/application-dev/reference/apis/js-apis-webview.md b/en/application-dev/reference/apis/js-apis-webview.md index ae261c21ebc5779e283e8e4e19d1355de9216cda..adea4c22a9473f43b8092d0314918537ecaa98b6 100644 --- a/en/application-dev/reference/apis/js-apis-webview.md +++ b/en/application-dev/reference/apis/js-apis-webview.md @@ -208,7 +208,6 @@ For details about the error codes, see [Webview Error Codes](../errorcodes/error | -------- | ------------------------------------- | | 17100010 | Can not post message using this port. | - ### onMessageEventExt10+ onMessageEventExt(callback: (result: WebMessageExt) => void): void @@ -358,7 +357,7 @@ window.addEventListener('message', function(event) { h5Port = event.ports[0]; // 1. Save the port number sent from the eTS side. h5Port.onmessage = function(event) { console.log("hwd In html got message"); - // 2. Receive the message sent from the ArkTS side. + // 2. Receive the message sent from the eTS side. var result = event.data; console.log("In html got message, typeof: ", typeof(result)); console.log("In html got message, result: ", (result)); @@ -401,7 +400,7 @@ window.addEventListener('message', function(event) { } }) -// Use h5Port to send a message of the string type to the ArkTS side. +// Use h5Port to send a message of the string type to the ets side. function postStringToApp() { if (h5Port) { console.log("In html send string message"); @@ -638,7 +637,7 @@ struct WebComponent { Button('loadUrl') .onClick(() => { try { - // The headers parameter is carried. + // The headers parameter is passed. this.controller.loadUrl('www.example.com', [{headerKey: "headerKey", headerValue: "headerValue"}]); } catch (error) { console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); @@ -999,7 +998,7 @@ struct WebComponent { onActive(): void -Invoked to instruct the **\** component to enter the foreground, active state. +Invoked to instruct the **\** component to enter the active foreground state. **System capability**: SystemCapability.Web.Webview.Core @@ -1348,12 +1347,14 @@ HTML file to be loaded: - Hello world! + +

@@ -3866,7 +3867,7 @@ struct WebComponent { getCertificate(): Promise> -Obtains the certificate information of the current website. When the \ component is used to load an HTTPS website, SSL certificate verification is performed. This API uses a promise to return the [X.509 certificate](./js-apis-cert.md) of the current website. +Obtains the certificate information of this website. When the **\** component is used to load an HTTPS website, SSL certificate verification is performed. This API uses a promise to return the [X.509 certificate](./js-apis-cert.md) of the current website. **System capability**: SystemCapability.Web.Webview.Core @@ -3943,7 +3944,7 @@ struct Index { } .type(ButtonType.Capsule) .onClick(() => { - //Load an HTTPS website and view the certificate information of the website. + // Load an HTTPS website and view the certificate information of the website. this.webviewCtl.loadUrl('https://www.example.com') }) .height(50) @@ -4023,7 +4024,7 @@ struct Index { getCertificate(callback: AsyncCallback>): void -Obtains the certificate information of the current website. When the \ component is used to load an HTTPS website, SSL certificate verification is performed. This API uses an asynchronous callback to return the [X.509 certificate](./js-apis-cert.md) of the current website. +Obtains the certificate information of this website. When the **\** component is used to load an HTTPS website, SSL certificate verification is performed. This API uses an asynchronous callback to return the [X.509 certificate](./js-apis-cert.md) of the website. **System capability**: SystemCapability.Web.Webview.Core @@ -4031,7 +4032,7 @@ Obtains the certificate information of the current website. When the \ comp | Name | Type | Mandatory| Description | | -------- | ---------------------------- | ---- | ---------------------------------------- | -| callback | AsyncCallback> | Yes | Callback used to obtain the X.509 certificate array of the current HTTPS website.| +| callback | AsyncCallback> | Yes | Callback used to obtain the X.509 certificate array of the current website.| **Error codes** @@ -4100,7 +4101,7 @@ struct Index { } .type(ButtonType.Capsule) .onClick(() => { - //Load an HTTPS website and view the certificate information of the website. + // Load an HTTPS website and view the certificate information of the website. this.webviewCtl.loadUrl('https://www.example.com') }) .height(50) @@ -4222,10 +4223,111 @@ struct WebComponent { } ``` +### prefetchPage10+ + +prefetchPage(url: string, additionalHeaders?: Array\): void + +Prefetches resources in the background for a page that is likely to be accessed in the near future, without executing the page JavaScript code or presenting the page. This can significantly reduce the load time for the prefetched page. + +**System capability**: SystemCapability.Web.Webview.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------------------| --------------------------------| ---- | ------------- | +| url | string | Yes | URL to be preloaded.| +| additionalHeaders | Array\<[WebHeader](#webheader)> | No | Additional HTTP headers of the URL.| + +**Error codes** + +For details about the error codes, see [Webview Error Codes](../errorcodes/errorcode-webview.md). + +| ID | Error Message | +| -------- | ------------------------------------------------------------ | +| 17100001 | Init error. The WebviewController must be associated with a Web component. | +| 17100002 | Invalid url. | + +**Example** + +```ts +// xxx.ets +import web_webview from '@ohos.web.webview' + +@Entry +@Component +struct WebComponent { + controller: web_webview.WebviewController = new web_webview.WebviewController(); + + build() { + Column() { + Button('prefetchPopularPage') + .onClick(() => { + try { + // Replace 'https://www.example.com' with a real URL for the API to work. + this.controller.prefetchPage('https://www.example.com'); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + // Replace ''www.example1.com' with a real URL for the API to work. + Web({ src: 'www.example1.com', controller: this.controller }) + } + } +} +``` + +### prepareForPageLoad10+ + +static prepareForPageLoad(url: string, preconnectable: boolean, numSockets: number): void + +Preconnects to a URL. This API can be called before the URL is loaded, to resolve the DNS and establish a socket connection, without obtaining the resources. + +**System capability**: SystemCapability.Web.Webview.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| ---------------| ------- | ---- | ------------- | +| url | string | Yes | URL to be preconnected.| +| preconnectable | boolean | Yes | Whether to perform preconnection, which involves DNS resolution and socket connection establishment. The value **true** means to perform preconnection, and **false** means the opposite.| +| numSockets | number | Yes | Number of sockets to be preconnected. The value must be greater than 0. A maximum of six socket connections are allowed.| + +**Error codes** + +For details about the error codes, see [Webview Error Codes](../errorcodes/errorcode-webview.md). + +| ID | Error Message | +| -------- | ------------------------------------------------------------ | +| 17100002 | Invalid url. | +| 171000013| The number of preconnect sockets is invalid. | + +**Example** + +```ts +// xxx.ts +import UIAbility from '@ohos.app.ability.UIAbility'; +import web_webview from '@ohos.web.webview'; + +export default class EntryAbility extends UIAbility { + onCreate(want, launchParam) { + console.log("EntryAbility onCreate") + web_webview.WebviewController.initializeWebEngine() + // Replace 'https://www.example.com' with a real URL for the API to work. + web_webview.WebviewController.prepareForPageLoad("https://www.example.com", true, 2); + globalThis.abilityWant = want + console.log("EntryAbility onCreate done") + } +} +``` + ## WebCookieManager Implements a **WebCookieManager** instance to manage behavior of cookies in **\** components. All **\** components in an application share a **WebCookieManager** instance. +> **NOTE** +> +> You must load the **\** component before calling APIs in **WebCookieManager**. + ### getCookie static getCookie(url: string): string @@ -4347,7 +4449,6 @@ Saves the cookies in the memory to the drive. This API uses an asynchronous call | -------- | ---------------------- | ---- | :------------------------------------------------- | | callback | AsyncCallback\ | Yes | Callback used to return whether the cookies are successfully saved.| - **Example** ```ts @@ -4688,6 +4789,10 @@ struct WebComponent { Implements a **WebStorage** object to manage the Web SQL database and HTML5 Web Storage APIs. All **\** components in an application share a **WebStorage** object. +> **NOTE** +> +> You must load the **\** component before calling the APIs in **WebStorage**. + ### deleteOrigin static deleteOrigin(origin : string): void @@ -5148,6 +5253,10 @@ struct WebComponent { Implements a **WebDataBase** object. +> **NOTE** +> +> You must load the **\** component before calling the APIs in **WebDataBase**. + ### getHttpAuthCredentials static getHttpAuthCredentials(host: string, realm: string): Array\ @@ -5326,6 +5435,10 @@ struct WebComponent { Implements a **GeolocationPermissions** object. +> **NOTE** +> +> You must load the **\** component before calling the APIs in **GeolocationPermissions**. + ### Required Permissions **ohos.permission.LOCATION**, **ohos.permission.APPROXIMATELY_LOCATION**, and **ohos.permission.LOCATION_IN_BACKGROUND**, which are required for accessing the location information. For details about the permissions, see [@ohos.geolocation (Geolocation)](./js-apis-geolocation.md). @@ -5739,7 +5852,6 @@ Describes the type of the returned result of script execution using [runJavaScir | ARRAY_BUFFER | 4 |Raw binary data buffer.| | ARRAY | 5 |Array type.| - ## WebMessageType10+ Describes the data type supported by the [webMessagePort](#webmessageport) API. @@ -5796,7 +5908,6 @@ For details about the error codes, see [Webview Error Codes](../errorcodes/error | -------- | ------------------------------------- | | 17100014 | The type does not match with the value of the result. | - ### getNumber10+ getNumber(): number @@ -5841,7 +5952,6 @@ For details about the error codes, see [Webview Error Codes](../errorcodes/error | -------- | ------------------------------------- | | 17100014 | The type does not match with the value of the result. | - ### getArrayBuffer10+ getArrayBuffer(): ArrayBuffer @@ -5885,7 +5995,6 @@ For details about the error codes, see [Webview Error Codes](../errorcodes/error | -------- | ------------------------------------- | | 17100014 | The type does not match with the value of the result. | - ## WebMessageExt10+ Data object received and sent by the [webMessagePort](#webmessageport) interface. @@ -5904,7 +6013,6 @@ Obtains the type of the data object. | --------------| --------------------------------------------------------- | | [WebMessageType](#webmessagetype10) | Data type supported by the [webMessagePort](#webmessageport) API.| - ### getString10+ getString(): string @@ -5927,7 +6035,6 @@ For details about the error codes, see [Webview Error Codes](../errorcodes/error | -------- | ------------------------------------- | | 17100014 | The type does not match with the value of the web message. | - ### getNumber10+ getNumber(): number @@ -5950,7 +6057,6 @@ For details about the error codes, see [Webview Error Codes](../errorcodes/error | -------- | ------------------------------------- | | 17100014 | The type does not match with the value of the web message. | - ### getBoolean10+ getBoolean(): boolean @@ -5973,7 +6079,6 @@ For details about the error codes, see [Webview Error Codes](../errorcodes/error | -------- | ------------------------------------- | | 17100014 | The type does not match with the value of the web message. | - ### getArrayBuffer10+ getArrayBuffer(): ArrayBuffer @@ -6039,7 +6144,6 @@ For details about the error codes, see [Webview Error Codes](../errorcodes/error | -------- | ------------------------------------- | | 17100014 | The type does not match with the value of the web message. | - ### setType10+ setType(type: WebMessageType): void @@ -6180,7 +6284,6 @@ Sets the error-object-type data for the data object. For the complete sample cod | -------- | ------------------------------------- | | 17100014 | The type does not match with the value of the web message. | - ## WebStorageOrigin Provides usage information of the Web SQL Database. diff --git a/en/application-dev/reference/arkui-js-lite/figures/image-animator.gif b/en/application-dev/reference/arkui-js-lite/figures/image-animator-lite.gif similarity index 100% rename from en/application-dev/reference/arkui-js-lite/figures/image-animator.gif rename to en/application-dev/reference/arkui-js-lite/figures/image-animator-lite.gif diff --git a/en/application-dev/reference/arkui-js-lite/figures/image.png b/en/application-dev/reference/arkui-js-lite/figures/image-lite.png similarity index 100% rename from en/application-dev/reference/arkui-js-lite/figures/image.png rename to en/application-dev/reference/arkui-js-lite/figures/image-lite.png diff --git a/en/application-dev/reference/arkui-js-lite/figures/list.png b/en/application-dev/reference/arkui-js-lite/figures/list-lite.png similarity index 100% rename from en/application-dev/reference/arkui-js-lite/figures/list.png rename to en/application-dev/reference/arkui-js-lite/figures/list-lite.png diff --git a/en/application-dev/reference/arkui-js-lite/figures/marquee.gif b/en/application-dev/reference/arkui-js-lite/figures/marquee-lite.gif similarity index 100% rename from en/application-dev/reference/arkui-js-lite/figures/marquee.gif rename to en/application-dev/reference/arkui-js-lite/figures/marquee-lite.gif diff --git a/en/application-dev/reference/arkui-js-lite/figures/picker-view.png b/en/application-dev/reference/arkui-js-lite/figures/picker-view-lite.png similarity index 100% rename from en/application-dev/reference/arkui-js-lite/figures/picker-view.png rename to en/application-dev/reference/arkui-js-lite/figures/picker-view-lite.png diff --git a/en/application-dev/reference/arkui-js-lite/figures/progress.png b/en/application-dev/reference/arkui-js-lite/figures/progress-lite.png similarity index 100% rename from en/application-dev/reference/arkui-js-lite/figures/progress.png rename to en/application-dev/reference/arkui-js-lite/figures/progress-lite.png diff --git a/en/application-dev/reference/arkui-js-lite/figures/qrcode.gif b/en/application-dev/reference/arkui-js-lite/figures/qrcode-lite.gif similarity index 100% rename from en/application-dev/reference/arkui-js-lite/figures/qrcode.gif rename to en/application-dev/reference/arkui-js-lite/figures/qrcode-lite.gif diff --git a/en/application-dev/reference/arkui-js-lite/figures/slider.png b/en/application-dev/reference/arkui-js-lite/figures/slider-lite.png similarity index 100% rename from en/application-dev/reference/arkui-js-lite/figures/slider.png rename to en/application-dev/reference/arkui-js-lite/figures/slider-lite.png diff --git a/en/application-dev/reference/arkui-js-lite/figures/swiper.gif b/en/application-dev/reference/arkui-js-lite/figures/swiper-lite.gif similarity index 100% rename from en/application-dev/reference/arkui-js-lite/figures/swiper.gif rename to en/application-dev/reference/arkui-js-lite/figures/swiper-lite.gif diff --git a/en/application-dev/reference/arkui-js-lite/figures/switch.gif b/en/application-dev/reference/arkui-js-lite/figures/switch-lite.gif similarity index 100% rename from en/application-dev/reference/arkui-js-lite/figures/switch.gif rename to en/application-dev/reference/arkui-js-lite/figures/switch-lite.gif diff --git a/en/application-dev/reference/arkui-js-lite/figures/text.png b/en/application-dev/reference/arkui-js-lite/figures/text-lite.png similarity index 100% rename from en/application-dev/reference/arkui-js-lite/figures/text.png rename to en/application-dev/reference/arkui-js-lite/figures/text-lite.png diff --git a/en/application-dev/reference/arkui-js-lite/js-components-basic-image-animator.md b/en/application-dev/reference/arkui-js-lite/js-components-basic-image-animator.md index 226eff9f6c284140b5c671d2135dbe212b609590..4e6246baade4ed2f36f84cedec94425a0e1e85e9 100644 --- a/en/application-dev/reference/arkui-js-lite/js-components-basic-image-animator.md +++ b/en/application-dev/reference/arkui-js-lite/js-components-basic-image-animator.md @@ -204,4 +204,4 @@ export default { }; ``` -![image-animator](figures/image-animator.gif) +![image-animator](figures/image-animator-lite.gif) diff --git a/en/application-dev/reference/arkui-js-lite/js-components-basic-image.md b/en/application-dev/reference/arkui-js-lite/js-components-basic-image.md index 9dd520dcdeed71f6de216e8d5337d54aec33668d..d62d0f7d8188886ec3ca42e593029e763ed32e78 100644 --- a/en/application-dev/reference/arkui-js-lite/js-components-basic-image.md +++ b/en/application-dev/reference/arkui-js-lite/js-components-basic-image.md @@ -71,4 +71,4 @@ Not supported } ``` -![image](figures/image.png) +![image](figures/image-lite.png) diff --git a/en/application-dev/reference/arkui-js-lite/js-components-basic-marquee.md b/en/application-dev/reference/arkui-js-lite/js-components-basic-marquee.md index 8ecc7a2e41d301f03540320244425beacc39a884..7a0734964a217b089cb46e68ef75fb0db2671f49 100644 --- a/en/application-dev/reference/arkui-js-lite/js-components-basic-marquee.md +++ b/en/application-dev/reference/arkui-js-lite/js-components-basic-marquee.md @@ -115,4 +115,4 @@ export default { } ``` -![marquee](figures/marquee.gif) +![marquee](figures/marquee-lite.gif) diff --git a/en/application-dev/reference/arkui-js-lite/js-components-basic-picker-view.md b/en/application-dev/reference/arkui-js-lite/js-components-basic-picker-view.md index e9dacebc6c419bfaeca6c8aac9c1001e0725bd1f..44d4107f34e8d264488715b1dbe6e607819250fb 100644 --- a/en/application-dev/reference/arkui-js-lite/js-components-basic-picker-view.md +++ b/en/application-dev/reference/arkui-js-lite/js-components-basic-picker-view.md @@ -142,4 +142,4 @@ export default { } ``` -![picker-view](figures/picker-view.png) +![picker-view](figures/picker-view-lite.png) diff --git a/en/application-dev/reference/arkui-js-lite/js-components-basic-progress.md b/en/application-dev/reference/arkui-js-lite/js-components-basic-progress.md index 740bc136bc0a506cc6f28f883424fb2a62b15504..adc01e07389af27a21701566e8a1197dae9c0ea1 100644 --- a/en/application-dev/reference/arkui-js-lite/js-components-basic-progress.md +++ b/en/application-dev/reference/arkui-js-lite/js-components-basic-progress.md @@ -122,4 +122,4 @@ export default { } ``` -![progress](figures/progress.png) +![progress](figures/progress-lite.png) diff --git a/en/application-dev/reference/arkui-js-lite/js-components-basic-qrcode.md b/en/application-dev/reference/arkui-js-lite/js-components-basic-qrcode.md index 16ef26d1b4263b0217c9fedfc8f04016fe7175db..84bbace4425c18e8ccabd8ee757f8c2fbfb3eb60 100644 --- a/en/application-dev/reference/arkui-js-lite/js-components-basic-qrcode.md +++ b/en/application-dev/reference/arkui-js-lite/js-components-basic-qrcode.md @@ -122,4 +122,4 @@ export default { } ``` -![qrcode](figures/qrcode.gif) +![qrcode](figures/qrcode-lite.gif) diff --git a/en/application-dev/reference/arkui-js-lite/js-components-basic-slider.md b/en/application-dev/reference/arkui-js-lite/js-components-basic-slider.md index 14a1804c4b47d769b5020fb820ac768a3f434316..1094ed2aa76bb9edf7ed234c1a70d58a91081653 100644 --- a/en/application-dev/reference/arkui-js-lite/js-components-basic-slider.md +++ b/en/application-dev/reference/arkui-js-lite/js-components-basic-slider.md @@ -99,4 +99,4 @@ export default { } ``` -![slider](figures/slider.png) +![slider](figures/slider-lite.png) diff --git a/en/application-dev/reference/arkui-js-lite/js-components-basic-switch.md b/en/application-dev/reference/arkui-js-lite/js-components-basic-switch.md index 42b4bddc549dcda654c2925d164e2eada3190910..a38365449f66b5c8ff0ba124d6d04ea469d8139e 100644 --- a/en/application-dev/reference/arkui-js-lite/js-components-basic-switch.md +++ b/en/application-dev/reference/arkui-js-lite/js-components-basic-switch.md @@ -96,4 +96,4 @@ export default { } ``` -![switch](figures/switch.gif) +![switch](figures/switch-lite.gif) diff --git a/en/application-dev/reference/arkui-js-lite/js-components-basic-text.md b/en/application-dev/reference/arkui-js-lite/js-components-basic-text.md index e5eab00c2eb0434932a0400d87f87f413d47c8ce..473bba31e3ac94bcafe904eeccaa6bc3721db566 100644 --- a/en/application-dev/reference/arkui-js-lite/js-components-basic-text.md +++ b/en/application-dev/reference/arkui-js-lite/js-components-basic-text.md @@ -96,4 +96,4 @@ export default { } ``` -![text](figures/text.png) +![text](figures/text-lite.png) diff --git a/en/application-dev/reference/arkui-js-lite/js-components-container-list.md b/en/application-dev/reference/arkui-js-lite/js-components-container-list.md index 6c256285ccf9894184218e179efd96089289d61d..e147741964843365863eaa99a312630e3a440504 100644 --- a/en/application-dev/reference/arkui-js-lite/js-components-container-list.md +++ b/en/application-dev/reference/arkui-js-lite/js-components-container-list.md @@ -120,4 +120,4 @@ export default { } ``` -![list](figures/list.png) +![list](figures/list-lite.png) diff --git a/en/application-dev/reference/arkui-js-lite/js-components-container-swiper.md b/en/application-dev/reference/arkui-js-lite/js-components-container-swiper.md index 34ad83a37b8d907b886427b183e99f4666e28327..ba9297bd4aebf8b8f9a2f3b95fb801bde9c1b8e2 100644 --- a/en/application-dev/reference/arkui-js-lite/js-components-container-swiper.md +++ b/en/application-dev/reference/arkui-js-lite/js-components-container-swiper.md @@ -109,4 +109,4 @@ export default { } ``` -![swiper](figures/swiper.gif) +![swiper](figures/swiper-lite.gif) diff --git a/en/application-dev/reference/arkui-ts/figures/TextInput.png b/en/application-dev/reference/arkui-ts/figures/TextInput.png new file mode 100644 index 0000000000000000000000000000000000000000..517cbbcea01c161bb449c67d36e6cb0c199b1bd0 Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/TextInput.png differ diff --git a/en/application-dev/reference/arkui-ts/figures/checkbox2.gif b/en/application-dev/reference/arkui-ts/figures/checkbox2.gif new file mode 100644 index 0000000000000000000000000000000000000000..9e9f08ff19d6d94644e951e6324c37a728e5d7af Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/checkbox2.gif differ diff --git a/en/application-dev/reference/arkui-ts/figures/checkboxGroup2.gif b/en/application-dev/reference/arkui-ts/figures/checkboxGroup2.gif new file mode 100644 index 0000000000000000000000000000000000000000..6a0be72b7d13e326852225ac44071e89985adab1 Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/checkboxGroup2.gif differ diff --git a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001257058417.png b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001257058417.png deleted file mode 100644 index 999ad44c80a018d45353044e13923a8566bf3cf0..0000000000000000000000000000000000000000 Binary files a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001257058417.png and /dev/null differ diff --git a/en/application-dev/reference/arkui-ts/figures/imageButtonLabelStyle.png b/en/application-dev/reference/arkui-ts/figures/imageButtonLabelStyle.png new file mode 100644 index 0000000000000000000000000000000000000000..1a0f0d9cb7ec8cee7f6f01cc7e1b409f54e129ef Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/imageButtonLabelStyle.png differ diff --git a/en/application-dev/reference/arkui-ts/figures/listItem3.jpeg b/en/application-dev/reference/arkui-ts/figures/listItem3.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..5188c9221033fb57e3e483ade647353097f9e4e4 Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/listItem3.jpeg differ diff --git a/en/application-dev/reference/arkui-ts/figures/listItemGroup2.jpeg b/en/application-dev/reference/arkui-ts/figures/listItemGroup2.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..fa3469ab517b4e1b410fcef7a21aa9f4f1baebfa Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/listItemGroup2.jpeg differ diff --git a/en/application-dev/reference/arkui-ts/figures/sidebarcontainer.png b/en/application-dev/reference/arkui-ts/figures/sidebarcontainer.png index 1cbb01859041e2028d76b49db655148cf4eb3062..d6ca07b72655b49f58047d74b0995c58fd99f607 100644 Binary files a/en/application-dev/reference/arkui-ts/figures/sidebarcontainer.png and b/en/application-dev/reference/arkui-ts/figures/sidebarcontainer.png differ diff --git a/en/application-dev/reference/arkui-ts/figures/textAreaCustomKeyboard.png b/en/application-dev/reference/arkui-ts/figures/textAreaCustomKeyboard.png new file mode 100644 index 0000000000000000000000000000000000000000..6f0e9d679a5c498ee54c6ceba8b2f3675706d9d2 Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/textAreaCustomKeyboard.png differ diff --git a/en/application-dev/reference/arkui-ts/figures/textInput.gif b/en/application-dev/reference/arkui-ts/figures/textInput.gif deleted file mode 100644 index d980afbcb988222e44af1b359388a0ed6492264e..0000000000000000000000000000000000000000 Binary files a/en/application-dev/reference/arkui-ts/figures/textInput.gif and /dev/null differ diff --git a/en/application-dev/reference/arkui-ts/figures/textInputCustomKeyboard.png b/en/application-dev/reference/arkui-ts/figures/textInputCustomKeyboard.png new file mode 100644 index 0000000000000000000000000000000000000000..716529aac87850e48b8befb630bfece0d2acb87d Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/textInputCustomKeyboard.png differ diff --git a/en/application-dev/reference/arkui-ts/figures/textpicker1.gif b/en/application-dev/reference/arkui-ts/figures/textpicker1.gif new file mode 100644 index 0000000000000000000000000000000000000000..80a0ffbea07135408e9497e70cc3291e77690ab5 Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/textpicker1.gif differ diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-button.md b/en/application-dev/reference/arkui-ts/ts-basic-components-button.md index 66e4eae88f46e6b63652d9ebfd8fadc24df2b529..3a3d6c0ad09cb2ec333d162a1b612b65744fc7b3 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-button.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-button.md @@ -169,3 +169,41 @@ struct SwipeGestureExample { ``` ![ifButton](figures/ifButton.gif) + +### Example 3 + +```ts +// xxx.ets +@Entry +@Component +struct buttonTestDemo { + @State txt: string = 'overflowTextOverlengthTextOverflow.Clip'; + @State widthShortSize: number = 200; + + build() { + Row() { + Column() { + Button(this.txt) + .width(this.widthShortSize) + .height(100) + .labelStyle({ overflow: TextOverflow.Clip, + maxLines: 1, + minFontSize: 20, + maxFontSize: 20, + font: { + size: 20, + weight: FontWeight.Bolder, + family: 'cursive', + style: FontStyle.Italic + } + }) + .fontSize(40) + } + .width('100%') + } + .height('100%') + } +} +``` + +![image-20230711171138661](figures/imageButtonLabelStyle.png) diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-checkbox.md b/en/application-dev/reference/arkui-ts/ts-basic-components-checkbox.md index 2ad1d1ce835fe6c0fcffa7379860711cb49d396d..8760713a108b8fcdf718acb414dee0bbd54c9c7b 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-checkbox.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-checkbox.md @@ -39,9 +39,9 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the In addition to the [universal events](ts-universal-events-click.md), the following attributes are supported. -| Name | Description | +| Name | Description | | -------------------------------------------- | ------------------------------------------------------------ | -| onChange(callback: (value: boolean) => void) | Triggered when the selected status of the check box changes.
- The value **true** means that the check box is selected.
- The value **false** means that the check box is not selected.
Since API version 9, this API is supported in ArkTS widgets. | +| onChange(callback: (value: boolean) => void) | Triggered when the selected status of the check box changes.
- The value **true** means that the check box is selected.
- The value **false** means that the check box is not selected.
Since API version 9, this API is supported in ArkTS widgets.| ## MarkStyle10+ @@ -53,6 +53,8 @@ In addition to the [universal events](ts-universal-events-click.md), the followi ## Example +### Example 1 + ```ts // xxx.ets @Entry @@ -80,3 +82,51 @@ struct CheckboxExample { ![](figures/checkbox.gif) + +### Example 2 + +```ts +// xxx.ets +@Entry +@Component +struct Index { + + build() { + Row() { + Column() { + Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { + Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) + .selectedColor(0x39a2db) + .onChange((value: boolean) => { + console.info('Checkbox1 change is'+ value) + }) + .mark({ + strokeColor:Color.Black, + size: 50, + strokeWidth: 5 + }) + .unselectedColor(Color.Red) + .width(30) + .height(30) + Text('Checkbox1').fontSize(20) + } + Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { + Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) + .selectedColor(0x39a2db) + .onChange((value: boolean) => { + console.info('Checkbox2 change is' + value) + }) + .width(30) + .height(30) + Text('Checkbox2').fontSize(20) + } + } + .width('100%') + } + .height('100%') + } +} +``` + + +![](figures/checkbox2.gif) diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-checkboxgroup.md b/en/application-dev/reference/arkui-ts/ts-basic-components-checkboxgroup.md index 37da4ad0bdf5b41ae99f617a6d06789fb075c922..5a8f52093e36bc198bb47b5fefdb60f0aac56cfd 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-checkboxgroup.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-checkboxgroup.md @@ -72,6 +72,8 @@ Since API version 9, this API is supported in ArkTS widgets. ## Example +### Example 1 + ```ts // xxx.ets @Entry @@ -124,4 +126,77 @@ struct CheckboxExample { } } ``` -![checkboxgroup](figures/checkboxgroup.gif) +![checkboxGroup](figures/checkboxGroup.gif) + +### Example 2 + +```ts +// xxx.ets +@Entry +@Component +struct Index { + + build() { + Row() { + Column() { + Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { + CheckboxGroup({ group: 'checkboxGroup' }) + .selectedColor(Color.Orange) + .onChange((itemName: CheckboxGroupResult) => { + console.info("checkbox group content" + JSON.stringify(itemName)) + }) + .mark({ + strokeColor:Color.Black, + size: 40, + strokeWidth: 5 + }) + .unselectedColor(Color.Red) + .width(30) + .height(30) + Text('Select All').fontSize(20) + }.margin({right:15}) + Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { + Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) + .selectedColor(0x39a2db) + .onChange((value: boolean) => { + console.info('Checkbox1 change is'+ value) + }) + .mark({ + strokeColor:Color.Black, + size: 50, + strokeWidth: 5 + }) + .unselectedColor(Color.Red) + .width(30) + .height(30) + Text('Checkbox1').fontSize(20) + } + Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { + Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) + .selectedColor(0x39a2db) + .onChange((value: boolean) => { + console.info('Checkbox2 change is' + value) + }) + .width(30) + .height(30) + Text('Checkbox2').fontSize(20) + } + Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { + Checkbox({ name: 'checkbox3', group: 'checkboxGroup' }) + .selectedColor(0x39a2db) + .onChange((value: boolean) => { + console.info('Checkbox3 change is' + value) + }) + .width(30) + .height(30) + Text('Checkbox3').fontSize(20) + } + } + .width('100%') + } + .height('100%') + } +} +``` + +![checkboxGroup](figures/checkboxGroup2.gif) diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-formcomponent.md b/en/application-dev/reference/arkui-ts/ts-basic-components-formcomponent.md index 85870111712e90def229a040901f9ba0d41bbcf2..d75762999a60eebdcb3dc87de0aeca332cd6e6ab 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-formcomponent.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-formcomponent.md @@ -42,7 +42,7 @@ Creates a **FormComponent** instance to display the provided widget. | Name | Type | Mandatory| Description | | --------- | ------------------------------- | ---- | ----------------------------------------------------------------------- | -| id | number | Yes | Widget ID. Set this parameter to **0** for a new widget. | +| id | number | Yes | Widget ID. Set this parameter to **0** for a new widget.
**NOTE**
Different widget hosts cannot use the same ID.
If a widget host uses the same ID for two widgets, the one added later is displayed. | | name | string | Yes | Widget name. | | bundle | string | Yes | Bundle name of the widget. | | ability | string | Yes | Ability name of the widget. | diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-gauge.md b/en/application-dev/reference/arkui-ts/ts-basic-components-gauge.md index 6cf611c47dfd4d3d08b3124ec50e38b0ca1a4da7..9cbbc56e8002500fabc1bc85bb978006454cf06e 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-gauge.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-gauge.md @@ -68,7 +68,7 @@ struct GaugeExample { // Set the value parameter to 75 and the value attribute to 25. The attribute setting is used. Gauge({ value: 75 }) - .value(25) // If both the attribute and parameter are set, the parameter setting is used. + .value(25) // If both the attribute and parameter are set, the attribute setting is used. .width(200).height(200) .colors([[0x317AF7, 1], [0x5BA854, 1], [0xE08C3A, 1], [0x9C554B, 1]]) diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-navigation.md b/en/application-dev/reference/arkui-ts/ts-basic-components-navigation.md index 258657481a3284bd235a93c0a6e13c9ab9fd9088..cad8cd31309b0e6098e0ab5b521d5c6f10ce0843 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-navigation.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-navigation.md @@ -43,22 +43,22 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the | hideToolBar | boolean | Whether to hide the toolbar.
Default value: **false**
**true**: Hide the toolbar.
**false**: Display the toolbar.| | hideTitleBar | boolean | Whether to hide the title bar.
Default value: **false**
**true**: Hide the title bar.
**false**: Display the title bar.| | hideBackButton | boolean | Whether to hide the back button.
Default value: **false**
**true**: Hide the back button.
**false**: Display the back button.
The back button in the title bar of the **\** component cannot be hidden.
**NOTE**
The back button works only when **titleMode** is set to **NavigationTitleMode.Mini**.| -| navBarWidth9+ | [Length](ts-types.md#length) | Width of the navigation bar.
Default value: **200**
Unit: vp
**NOTE**
This attribute is valid only when the **\** component is split.| +| navBarWidth9+ | [Length](ts-types.md#length) | Width of the navigation bar.
Default value: **240**
Unit: vp
**NOTE**
This attribute is valid only when the **\** component is split.| | navBarPosition9+ | [NavBarPosition](#navbarposition) | Position of the navigation bar.
Default value: **NavBarPosition.Start**
**NOTE**
This attribute is valid only when the **\** component is split.| -| mode9+ | [NavigationMode](#navigationmode) | Display mode of the navigation bar.
Default value: **NavigationMode.Auto**
At the default settings, the component adapts to a single column or two columns based on the component width.| +| mode9+ | [NavigationMode](#navigationmode) | Display mode of the navigation bar.
Default value: **NavigationMode.Auto**
At the default settings, the component adapts to a single column or two columns based on the component width.
**NOTE**
Available options are **Stack**, **Split**, and **Auto**.| | backButtonIcon9+ | string \| [PixelMap](../apis/js-apis-image.md#pixelmap7) \| [Resource](ts-types.md#resource) | Back button icon on the navigation bar. The back button in the title bar of the **\** component cannot be hidden.| | hideNavBar9+ | boolean | Whether to hide the navigation bar. This attribute is valid only when **mode** is set to **NavigationMode.Split**.| | navDestination10+ | builder: (name: string, param: unknown) => void | Creates a **\** component.
**NOTE**
The **builder** function is used, with the **name** and **param** parameters passed in. In the builder, a layer of custom components can be included outside the **\** component. However, no attributes or events can be set for the custom components. Otherwise, only blank components are displayed.| -| navBarWidthRange10+ | [[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)] | Minimum and maximum widths of the navigation bar.
Default value: **240** for the minimum value; 40% of the component width (not greater than 432) for the maximum value
Unit: vp
Priority rules:
Custom value > Default value
Minimum value > Maximum value
navBar > content
If values conflict, the global value takes precedence, and the local minimum value depends on the container size.| -| minContentWidth10+ | [Dimension](ts-types.md#dimension10) | Minimum width of the navigation bar content area.
Default value: **360**
Unit: vp
Priority rules:
Custom value > Default value
Minimum value > Maximum value
navBar > content
If values conflict, the global value takes precedence, and the local minimum value depends on the container size.
Breakpoint calculation in Auto mode: default 600vp = minNavBarWidth (240vp) + minContentWidth (360vp)| +| navBarWidthRange10+ | [[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)] | Minimum and maximum widths of the navigation bar (valid in dual-column mode).
Default value: **240** for the minimum value; 40% of the component width (not greater than 432) for the maximum value
Unit: vp
Priority rules:
Custom value > Default value
Minimum value > Maximum value
navBar > content
If values conflict, the global value takes precedence, and the local minimum value depends on the container size.| +| minContentWidth10+ | [Dimension](ts-types.md#dimension10) | Minimum width of the navigation bar content area (valid in dual-column mode).
Default value: **360**
Unit: vp
Priority rules:
Custom value > Default value
Minimum value > Maximum value
navBar > content
If values conflict, the global value takes precedence, and the local minimum value depends on the container size.
Breakpoint calculation in Auto mode: default 600 vp = minNavBarWidth (240 vp) + minContentWidth (360 vp)| ## NavPathStack10+ Implements a navigation stack. -### push10+ +### pushPath10+ -push(info: NavPathInfo): void +pushPath(info: NavPathInfo): void Pushes the NavDestination page information specified by **info** to the stack. @@ -68,9 +68,9 @@ Pushes the NavDestination page information specified by **info** to the stack. | ------ | ----------------------- | ---- | --------------- | | info | [NavPathInfo](#navpathinfo10) | Yes | Information about the navigation destination page. | -### pushName10+ +### pushPathByName10+ -pushName(name: string, param: unknown): void +pushPathByName(name: string, param: unknown): void Pushes the navigation destination page specified by **name** to the navigation stack. @@ -94,9 +94,9 @@ Pops the top element out of the navigation stack. | NavPathInfo | Returns the information about the navigation destination page at the top of the stack.| | undefined | Returns **undefined** if the navigation stack is empty.| -### popTo10+ +### popToName10+ -popTo(name: string): number +popToName(name: string): number Returns the navigation stack to the first navigation destination page that matches the value of **name**. @@ -319,11 +319,11 @@ constructor(name: string, param: unknown) ## NavigationMode -| Name | Description | -| ----- | ---------------------------------------- | +| Name | Description | +| ----- | ------------------------------------------------------------ | | Stack | The navigation bar and content area are displayed independently of each other, which are equivalent to two pages. | -| Split | The navigation bar and content area are displayed in different columns. | -| Auto | When the window width is greater than or equal to 520 vp, Split mode is used. Otherwise, the Stack mode is used.| +| Split | The navigation bar and content area are displayed in different columns. | +| Auto | In API version 9 and earlier versions: When the window width is greater than or equal to 520 vp, the Split mode is used. In other cases, the Stack mode is used.
In API version 10 and later versions: When the window width is greater than or equal to 600 vp, the Split mode is used. In other cases, the Stack mode is used. 600 vp = minNavBarWidth (240 vp) + minContentWidth (360 vp).| ## TitleHeight diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-textarea.md b/en/application-dev/reference/arkui-ts/ts-basic-components-textarea.md index 8b904ffd03ba102894adeec6e8745ab9cdae687d..32dab9e0af0b4e4e8066358aefc1a758333899a7 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-textarea.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-textarea.md @@ -37,11 +37,14 @@ Among the [universal attributes](ts-universal-attributes-size.md) and [universal | caretColor | [ResourceColor](ts-types.md#resourcecolor) | Color of the caret in the text box.
Default value: **'#007DFF'** | | inputFilter8+ | {
value: [ResourceStr](ts-types.md#resourcestr),
error?: (value: string) => void
} | Regular expression for input filtering. Only inputs that comply with the regular expression can be displayed. Other inputs are filtered out. The specified regular expression can match single characters, but not strings.
- **value**: regular expression to set.
- **error**: filtered-out content to return when regular expression matching fails.| | copyOption9+ | [CopyOptions](ts-appendix-enums.md#copyoptions9) | Whether copy and paste is allowed.
Default value: **CopyOptions.LocalDevice**
If this attribute is set to **CopyOptions.None**, the paste operation is allowed, but the copy and cut operations are not.| -| maxLength10+ | number | Maximum number of characters in the text input.
By default, there is no maximum number of characters.| +| maxLength10+ | number | Maximum number of characters in the text input.
By default, there is no maximum number of characters.
When the maximum number of characters is reached, no more characters can be entered, and the border turns red.| | showCounter10+ | boolean | Whether to show the number of entered characters when **maxLength** is set.
Default value: **false** | | style10+ | [TextContentStyle](ts-appendix-enums.md#textcontentstyle10) | Style of the component.
Default value: **TextContentStyle.DEFAULT** | | enableKeyboardOnFocus10+ | boolean | Whether to enable the input method when the component obtains focus.
Default value: **true** | | selectionMenuHidden10+ | boolean | Whether to display the text selection menu when the text box is long-pressed or right-clicked.
Default value: **false**| +| barState10+ | [BarState](ts-appendix-enums.md#BarState) | Scrollbar state when the inline input style is used.
Default value: **BarState.Auto**| +| maxLines10+ | number | Maximum number of lines that can be displayed when the inline input style is used.
Default value: **3**| +| customKeyboard10+ | [CustomBuilder](ts-types.md#custombuilder8) | Custom keyboard.
**NOTE**
When a custom keyboard is set, activating the text box opens the specified custom component, instead of the system input method.
The custom keyboard's height can be set through the **height** attribute of the custom component's root node, and its width is fixed at the default value.
The custom keyboard is displayed on top of the current page, without compressing or raising the page.
The custom keyboard cannot obtain the focus, but it blocks gesture events.
By default, the custom keyboard is closed when the input component loses the focus. You can also use the [TextAreaController](#textareacontroller8).[stopEditing](#stopediting10) API to close the keyboard.| > **NOTE** > @@ -225,3 +228,47 @@ struct TextAreaExample { ``` ![maxLength](figures/maxLength.png) + + +### Example 3 + +```ts +// xxx.ets +@Entry +@Component +struct TextAreaExample { + controller: TextAreaController = new TextAreaController() + @State inputValue: string = "" + + // Create a custom keyboard component. + @Builder CustomKeyboardBuilder() { + Column() { + Button('x').onClick(() => { + // Disable the custom keyboard. + this.controller.stopEditing() + }) + Grid() { + ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item) => { + GridItem() { + Button(item + "") + .width(110).onClick(() => { + this.inputValue += item + }) + } + }) + }.maxCount(3).columnsGap(10).rowsGap(10).padding(5) + }.backgroundColor(Color.Gray) + } + + build() { + Column() { + TextArea({ controller: this.controller, text: this.inputValue}) + // Bind the custom keyboard. + .customKeyboard(this.CustomKeyboardBuilder()).margin(10).border({ width: 1 }) + .height(200) + } + } +} +``` + +![customKeyboard](figures/textAreaCustomKeyboard.png) diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-textinput.md b/en/application-dev/reference/arkui-ts/ts-basic-components-textinput.md index c5a20c371a9ed6420cdfe33200a596bf53104806..f8a2a0cba6a7b5dd36ff165a3df05cfd11dfede2 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-textinput.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-textinput.md @@ -40,17 +40,20 @@ Among the [universal attributes](ts-universal-attributes-size.md) and [universal | inputFilter8+ | {
value: [ResourceStr](ts-types.md#resourcestr),
error?: (value: string) => void
} | Regular expression for input filtering. Only inputs that comply with the regular expression can be displayed. Other inputs are filtered out. The regular expression can match single characters, but not strings.
- **value**: regular expression to set.
- **error**: filtered-out content to return when regular expression matching fails.| | copyOption9+ | [CopyOptions](ts-appendix-enums.md#copyoptions9) | Whether copy and paste is allowed.
Default value: **CopyOptions.LocalDevice**
If this attribute is set to **CopyOptions.None**, the paste operation is allowed, but not the copy or cut operation.| | showPasswordIcon9+ | boolean | Whether to display the password icon at the end of the password text box.
Default value: **true**| -| style9+ | [TextInputStyle](#textinputstyle9) \| [TextContentStyle](ts-appendix-enums.md#textcontentstyle10) | Text input style.
Default value: **TextInputStyle.Default**| +| style9+ | [TextInputStyle](#textinputstyle9) \| [TextContentStyle](ts-appendix-enums.md#textcontentstyle10) | Text input style.
Default value: **TextInputStyle.Default**
In the case of **TextInputStyle.Inline**, setting the text alignment mode is not available.| | textAlign9+ | [TextAlign](ts-appendix-enums.md#textalign) | Horizontal alignment of the text.
Default value: **TextAlign.Start**
**NOTE**
Available options are **TextAlign.Start**, **TextAlign.Center**, and **TextAlign.End**.
To set vertical alignment for the text, use the [align](ts-universal-attributes-location.md) attribute. The **align** attribute alone does not control the horizontal position of the text. In other words, **Alignment.TopStart**, **Alignment.Top**, and **Alignment.TopEnd** produce the same effect, top-aligning the text; **Alignment.Start**, **Alignment.Center**, and **Alignment.End** produce the same effect, centered-aligning the text vertically; **Alignment.BottomStart**, **Alignment.Bottom**, and **Alignment.BottomEnd** produce the same effect, bottom-aligning the text. | | selectedBackgroundColor10+ | [ResourceColor](ts-types.md#resourcecolor) | Background color of the selected text.
If the opacity is not set, the color is opaque. For example, **0x80000000** indicates black with 50% opacity.| | caretStyle10+ | {
width: [Length](ts-types.md#length)
} | Caret style. | | caretPosition10+ | number | Caret position.| -| showUnit10+ | [CustomBuilder](ts-types.md#CustomBuilder8) | Unit for content in the component.
By default, there is no unit.| +| showUnit10+ | [CustomBuilder](ts-types.md#CustomBuilder8) | Unit for content in the component.
By default, there is no unit.| | showError10+ | string \| undefined | Error text displayed when an error occurs.
By default, no error text is displayed.| | showUnderline10+ | boolean | Whether to show an underline.
Default value: **false**| | passwordIcon10+ | [PasswordIcon](#passwordicon10) | Password icon to display at the end of the password text box.
By default, the system-provided icon is used.| | enableKeyboardOnFocus10+ | boolean | Whether to enable the input method when the component obtains focus.
Default value: **true** | | selectionMenuHidden10+ | boolean | Whether to display the text selection menu when the text box is long-pressed or right-clicked.
Default value: **false**| +| barState10+ | [BarState](ts-appendix-enums.md#BarState) | Scrollbar state when the inline input style is used.
Default value: **BarState.Auto**| +| maxLines10+ | number | Maximum number of lines that can be displayed when the inline input style is used.
Default value: **3**| +| customKeyboard10+ | [CustomBuilder](ts-types.md#custombuilder8) | Custom keyboard.
**NOTE**
When a custom keyboard is set, activating the text box opens the specified custom component, instead of the system input method, and the **enterKeyType** attribute setting for the system keyboard will not take effect.
The custom keyboard's height can be set through the **height** attribute of the custom component's root node, and its width is fixed at the default value.
The custom keyboard is displayed on top of the current page, without compressing or raising the page.
The custom keyboard cannot obtain the focus, but it blocks gesture events.
By default, the custom keyboard is closed when the input component loses the focus. You can also use the [TextInputController](#textinputcontroller8).[stopEditing](#stopediting10) API to close the keyboard.| > **NOTE** > @@ -71,7 +74,7 @@ Among the [universal attributes](ts-universal-attributes-size.md) and [universal | Name | Description | | ------------------ | ------------- | | Normal | Normal input mode.
The value can contain digits, letters, underscores (_), spaces, and special characters.| -| Password | Password input mode. The value can contain digits, letters, underscores (_), spaces, and special characters. An eye icon is used to show or hide the password, and the password is hidden behind dots by default.| +| Password | Password input mode. The value can contain digits, letters, underscores (_), spaces, and special characters. An eye icon is used to show or hide the password, and the password is hidden behind dots by default. The password input mode does not support underlines.| | Email | Email address input mode. The value can contain digits, letters, underscores (_), and at signs (@). Only one at sign (@) is allowed.| | Number | Digit input mode. | | PhoneNumber9+ | Phone number input mode.
The value can contain digits, plus signs (+), hyphens (-), asterisks (*), and number signs (#). The length is not limited.| @@ -81,7 +84,7 @@ Among the [universal attributes](ts-universal-attributes-size.md) and [universal | Name | Description | | ------------------ | ------------- | | Default | Default style. The caret width is fixed at 1.5 vp, and the caret height is subject to the background height and font size of the selected text. | -| Inline | Inline input style. The background height of the selected text is the same as the height of the text box. | +| Inline | Inline input style. The background height of the selected text is the same as the height of the text box.
This style is used in scenarios where editing and non-editing states are obvious, for example, renaming in the file list view.| ## PasswordIcon10+ @@ -241,7 +244,7 @@ struct TextInputExample { } ``` -![textInput](figures/textInput.gif) +![TextInput](figures/TextInput.png) ### Example 2 @@ -294,3 +297,45 @@ struct TextInputExample { ``` ![showUnit](figures/showUnit.png) + +### Example 3 + +```ts +// xxx.ets +@Entry +@Component +struct TextInputExample { + controller: TextInputController = new TextInputController() + @State inputValue: string = "" + + // Create a custom keyboard component. + @Builder CustomKeyboardBuilder() { + Column() { + Button('x').onClick(() => { + // Disable the custom keyboard. + this.controller.stopEditing() + }) + Grid() { + ForEach([1, 2, 3, 4, 5, 6, 7, 8, 9, '*', 0, '#'], (item) => { + GridItem() { + Button(item + "") + .width(110).onClick(() => { + this.inputValue += item + }) + } + }) + }.maxCount(3).columnsGap(10).rowsGap(10).padding(5) + }.backgroundColor(Color.Gray) + } + + build() { + Column() { + TextInput({ controller: this.controller, text: this.inputValue }) + // Bind the custom keyboard. + .customKeyboard(this.CustomKeyboardBuilder()).margin(10).border({ width: 1 }) + } + } +} +``` + +![customKeyboard](figures/textInputCustomKeyboard.png) diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-textpicker.md b/en/application-dev/reference/arkui-ts/ts-basic-components-textpicker.md index ac4939dac0b575bc416c3fa85a2d1c777a43947e..d33e3188d979660311d0d98df6af7593859d0420 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-textpicker.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-textpicker.md @@ -50,7 +50,8 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the | disappearTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width for the top and bottom items.
Default value:
{
color: '#ff182431',
font: {
size: '14fp',
weight: FontWeight.Regular
}
} | | textStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width of all items except the top, bottom, and selected items.
Default value:
{
color: '#ff182431',
font: {
size: '16fp',
weight: FontWeight.Regular
}
} | | selectedTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | Font color, font size, and font width of the selected item.
Default value:
{
color: '#ff007dff',
font: {
size: '20vp',
weight: FontWeight.Medium
}
} | -| selectedIndex10+ | number \| number[] | Sets the index value of the default selected item in the array. The priority is higher than that of the selected value in options.
**NOTE**
For a single-column picker, use a value of the number type. For a multi-column (linked) picker, use a value of the number[] type.| +| selectedIndex10+ | number \| number[] | Index of the default selected item in the array. Its priority is higher than that of the selected value in **options**.
**NOTE**
For a single-column picker, use a value of the number type. For a multi-column (linked) picker, use a value of the number[] type.| +| canLoop10+ | boolean | Whether to support scroll looping. The value **true** means to support scroll looping, and **false** means the opposite.
Default value: **true**| ## Events @@ -60,11 +61,63 @@ In addition to the [universal events](ts-universal-events-click.md), the followi | -------- | -------- | | onAccept(callback: (value: string, index: number) => void)(deprecated) | Triggered when the OK button in the dialog box is clicked.
- **value**: value of the selected item.
- **index**: index of the selected item.
This API is deprecated since API version 10.
**NOTE**
This event can be triggered only in the [text picker dialog box](ts-methods-textpicker-dialog.md).| | onCancel(callback: () => void)(deprecated) | Triggered when the Cancel button in the dialog box is clicked.
This API is deprecated since API version 10.
**NOTE**
This event can be triggered only in the [text picker dialog box](ts-methods-textpicker-dialog.md).| -| onChange(callback: (value: string \| string[]10+, index: number \| number[]10+) => void) | Triggered when an item in the picker is selected.
- **value**: value of the selected item. (For a multi-column picker, **value** is of the array type.)
- **index**: index of the selected item. (For a multi-column picker, **index** is of the array type.)
**NOTE**
When the picker contains text only or both text and imagery, **value** indicates the text value of the selected item.When the picker contains imagery only, **value** is empty.| +| onChange(callback: (value: string \| string[]10+, index: number \| number[]10+) => void) | Triggered when an item in the picker is selected.
- **value**: value of the selected item. (For a multi-column picker, **value** is of the array type.)
- **index**: index of the selected item. (For a multi-column picker, **index** is of the array type.)
**NOTE**
When the picker contains text only or both text and imagery, **value** indicates the text value of the selected item. When the picker contains imagery only, **value** is empty.| ## Example +```ts +// xxx.ets +@Entry +@Component +struct TextPickerExample { + private select: number = 1 + private apfruits: string[] = ['apple1', 'apple2', 'apple3', 'apple4'] + private orfruits: string[] = ['orange1', 'orange2', 'orange3', 'orange4'] + private pefruits: string[] = ['peach1', 'peach2', 'peach3', 'peach4'] + private multi: string[][] = [this.apfruits, this.orfruits, this.pefruits] + private cascade: TextCascadePickerRangeContent[] = [ + { + text: 'Category 1', + children: [{ text: 'Subcategory 1', children: [{ text: 'Subcategory 2' }, { text: 'Subcategory 3' }, { text: 'Subcategory 4' }] }, + { text: 'Item 1', children: [{ text: ''Item 2' }, { text: ''Item 3' }, { text: ''Item 4' }] }] + }, + { + text: 'Category 2', + children: [{ text: 'Subcategory 1', children: [{ text: 'Subcategory 2' }, { text: 'Subcategory 3' }, { text: 'Subcategory 4' }] }, + { text: 'Item 1', children: [{ text: ''Item 2' }, { text: ''Item 3' }, { text: ''Item 4' }] }] + }, + { + text: 'Category 3', + children: [{ text: 'Subcategory 1', children: [{ text: 'Subcategory 2' }, { text: 'Subcategory 3' }, { text: 'Subcategory 4' }] }, + { text: 'Item 1', children: [{ text: ''Item 2' }, { text: ''Item 3' }, { text: ''Item 4' }] }] + } + ] + + build() { + Column() { + + TextPicker({ range: this.apfruits, selected: this.select }) + .onChange((value: string, index: number) => { + console.info('Picker item changed, value: ' + value + ', index: ' + index) + }).margin({ bottom: 50 }) + + TextPicker({ range: this.multi }) + .onChange((value: string | string[], index: number | number[]) => { + console.info('TextPicker multi-column: onChange' + JSON.stringify(value) + ',' + 'index:' + JSON.stringify(index)) + }).margin({ bottom: 50 }) + + TextPicker({ range: this.cascade }) + .onChange((value: string | string[], index: number | number[]) => { + console.info('TextPicker multi-column linkage: onChange' + JSON.stringify(value) + ',' + 'index:' + JSON.stringify(index)) + }) + } + } +} +``` + +![textpicker](figures/textpicker.gif) + ```ts // xxx.ets @Entry @@ -79,9 +132,12 @@ struct TextPickerExample { .onChange((value: string, index: number) => { console.info('Picker item changed, value: ' + value + ', index: ' + index) }) - } + .disappearTextStyle({color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}) + .textStyle({color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}) + .selectedTextStyle({color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}) + }.width('100%').height('100%') } } ``` -![en-us_image_0000001257058417](figures/en-us_image_0000001257058417.png) +![textpicker](figures/textpicker1.gif) diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-web.md b/en/application-dev/reference/arkui-ts/ts-basic-components-web.md index 2d6b3bab8f6c8dfeef3c2b65b3068d1546d4b652..b3c50c96f5760173ce05f46a39423aaef86d1e3b 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-web.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-web.md @@ -107,32 +107,31 @@ Web(options: { src: ResourceStr, controller: WebviewController | WebController}) ``` 2. Modify the **EntryAbility.ts** file. + The following uses **filesDir** as an example to describe how to obtain the path of the sandbox. For details about how to obtain other paths, see [Obtaining Application File Paths](../../application-models/application-context-stage.md#obtaining-application-file-paths). + ```ts + // xxx.ts + import UIAbility from '@ohos.app.ability.UIAbility'; + import web_webview from '@ohos.web.webview'; + + export default class EntryAbility extends UIAbility { + onCreate(want, launchParam) { + // Bind filesDir to the globalThis object to implement data synchronization between the UIAbility component and the UI. + globalThis.filesDir = this.context.filesDir + console.log("Sandbox path is " + globalThis.filesDir) + } + } + ``` - The following uses **filesDir** as an example to describe how to obtain the path of the sandbox. For details about how to obtain other paths, see [Obtaining Application File Paths](../../application-models/application-context-stage.md#obtaining-application-file-paths). - ```ts - // xxx.ts - import UIAbility from '@ohos.app.ability.UIAbility'; - import web_webview from '@ohos.web.webview'; - - export default class EntryAbility extends UIAbility { - onCreate(want, launchParam) { - // Bind filesDir to the globalThis object to implement data synchronization between the UIAbility component and the UI. - globalThis.filesDir = this.context.filesDir - console.log("Sandbox path is " + globalThis.filesDir) - } - } - ``` - - HTML file to be loaded: - ```html - - - - -

Hello World

- - - ``` + HTML file to be loaded: + ```html + + + + +

Hello World

+ + + ``` ## Attributes @@ -672,12 +671,16 @@ Sets whether to display the vertical scrollbar, including the default system scr ``` -### password +### password(deprecated) password(password: boolean) Sets whether the password should be saved. This API is a void API. +> **NOTE** +> +> This API is deprecated since API version 10, and no new API is provided as a substitute. + ### cacheMode cacheMode(cacheMode: CacheMode) @@ -993,7 +996,6 @@ Sets the minimum logical font size for the web page. } ``` - ### webFixedFont9+ webFixedFont(family: string) @@ -1244,18 +1246,26 @@ Sets whether to enable forcible dark mode for the web page. By default, this fea } ``` -### tableData +### tableData(deprecated) tableData(tableData: boolean) Sets whether form data should be saved. This API is a void API. -### wideViewModeAccess +> **NOTE** +> +> This API is deprecated since API version 10, and no new API is provided as a substitute. + +### wideViewModeAccess(deprecated) wideViewModeAccess(wideViewModeAccess: boolean) Sets whether to support the viewport attribute of the HTML **\** tag. This API is a void API. +> **NOTE** +> +> This API is deprecated since API version 10, and no new API is provided as a substitute. + ### pinchSmooth9+ pinchSmooth(isEnabled: boolean) @@ -1386,7 +1396,6 @@ Sets the web-based media playback policy, including the validity period for auto **Example** - ```ts // xxx.ets import web_webview from '@ohos.web.webview' @@ -1941,7 +1950,6 @@ Called when an HTTP error (the response code is greater than or equal to 400) oc onPageBegin(callback: (event?: { url: string }) => void) - Called when the web page starts to be loaded. This API is called only for the main frame content, and not for the iframe or frameset content. **Parameters** @@ -1976,7 +1984,6 @@ Called when the web page starts to be loaded. This API is called only for the ma onPageEnd(callback: (event?: { url: string }) => void) - Called when the web page loading is complete. This API takes effect only for the main frame content. **Parameters** @@ -2979,7 +2986,7 @@ If opening a new window is not needed, set the parameter to **null** when callin ```ts // xxx.ets import web_webview from '@ohos.web.webview' - + // There are two components on the same page. When the WebComponent object opens a new window, the NewWebViewComp object is displayed. @CustomDialog struct NewWebViewComp { @@ -3335,8 +3342,8 @@ Called when the web page content is first rendered. Column() { Web({ src:'www.example.com', controller: this.controller }) .onFirstContentfulPaint(event => { - console.log("onFirstContentfulPaint:" + "[navigationStartTick]:" + - event.navigationStartTick + ", [firstContentfulPaintMs]:" + + console.log("onFirstContentfulPaint:" + "[navigationStartTick]:" + + event.navigationStartTick + ", [firstContentfulPaintMs]:" + event.firstContentfulPaintMs) }) } @@ -3415,7 +3422,156 @@ Called when the **\** component obtains the focus. } } ``` +### onScreenCaptureRequest10+ + +onScreenCaptureRequest(callback: (event?: { handler: ScreenCaptureHandler }) => void) + +Called when a screen capture request is received. + +**Parameters** + +| Name | Type | Description | +| ------- | ---------------------------------------- | -------------- | +| handler | [ScreenCaptureHandler](#screencapturehandler10) | User operation.| + +**Example** + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview' + + @Entry + @Component + struct WebComponent { + controller: web_webview.WebviewController = new web_webview.WebviewController() + build() { + Column() { + Web({ src: 'www.example.com', controller: this.controller }) + .onScreenCaptureRequest((event) => { + AlertDialog.show({ + title: 'title: ' + event.handler.getOrigin(), + message: 'text', + primaryButton: { + value: 'deny', + action: () => { + event.handler.deny() + } + }, + secondaryButton: { + value: 'onConfirm', + action: () => { + event.handler.grant({ captureMode: WebCaptureMode.HOME_SCREEN }) + } + }, + cancel: () => { + event.handler.deny() + } + }) + }) + } + } + } + ``` +### onOverScroll10+ + +onOverScroll(callback: (event: {xOffset: number, yOffset: number}) => void) + +Called to indicate the offset by which the web page overscrolls. + +**Parameters** + +| Name | Type | Description | +| ------- | ------ | ------------ | +| xOffset | number | Horizontal overscroll offset based on the leftmost edge of the web page.| +| yOffset | number | Vertical overscroll offset based on the top edge of the web page.| + +**Example** + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview' + + @Entry + @Component + struct WebComponent { + controller: web_webview.WebviewController = new web_webview.WebviewController() + build() { + Column() { + Web({ src: 'www.example.com', controller: this.controller }) + .onOverScroll((event) => { + console.info("x = " + event.xOffset) + console.info("y = " + event.yOffset) + }) + } + } + } + ``` + +### onControllerAttached10+ + +onControllerAttached(callback: () => void) + +Called when the controller is successfully bound to the **\** component. The controller must be WebviewController. +As the web page is not yet loaded when this callback is called, APIs for operating the web page cannot be used in the callback, for example, [zoomIn](../apis/js-apis-webview.md#zoomin) and [zoomOut]. (../apis/js-apis-webview.md#zoomout). Other APIs, such as [loadUrl] (../apis/js-apis-webview.md#loadurl) and [getWebId] (../apis/js-apis-webview.md#getwebid), which do not involve web page operations, can be used properly. + +**Example** + +The following example uses **loadUrl** in the callback to load the web page. + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview' + + @Entry + @Component + struct WebComponent { + controller: web_webview.WebviewController = new web_webview.WebviewController() + + build() { + Column() { + Web({ src: '', controller: this.controller }) + .onControllerAttached(() => { + this.controller.loadUrl($rawfile("index.html")); + }) + } + } + } + ``` +The following example uses **getWebId** in the callback + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview' + + @Entry + @Component + struct WebComponent { + controller: web_webview.WebviewController = new web_webview.WebviewController() + + build() { + Column() { + Web({ src: $rawfile("index.html"), controller: this.controller }) + .onControllerAttached(() => { + try { + let id = this.controller.getWebId(); + console.log("id: " + id); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + } + } + } + ``` + HTML file to be loaded: + ```html + + + + +

Hello World

+ + + ``` ## ConsoleMessage Implements the **ConsoleMessage** object. For the sample code, see [onConsole](#onconsole). @@ -3470,7 +3626,7 @@ Obtains the path and name of the web page source file. ## JsResult -Implements the **JsResult** object, which indicates the result returned to the **\** component to indicate the user operation performed in the dialog box. For the sample code, see [onAlert](#onalert). +Implements the **JsResult** object, which indicates the result returned to the **\** component to indicate the user operation performed in the dialog box. For the sample code, see [onAlert Event](#onalert). ### handleCancel @@ -3635,7 +3791,6 @@ Describes the request/response header returned by the **\** component. | headerKey | string | Key of the request/response header. | | headerValue | string | Value of the request/response header.| - ## WebResourceResponse Implements the **WebResourceResponse** object. For the sample code, see [onHttpErrorReceive](#onhttperrorreceive). @@ -4010,6 +4165,42 @@ Grants the permission for resources requested by the web page. | --------- | --------------- | ---- | ---- | ------------- | | resources | Array\ | Yes | - | List of resources that can be requested by the web page with the permission to grant.| +## ScreenCaptureHandler10+ + +Implements the **ScreenCaptureHandler** object for accepting or rejecting a screen capture request. For the sample code, see [onScreenCaptureRequest Event](#onscreencapturerequest10). + +### deny10+ + +deny(): void + +Rejects this screen capture request. + +### getOrigin10+ + +getOrigin(): string + +Obtains the origin of this web page. + +**Return value** + +| Type | Description | +| ------ | ------------ | +| string | Origin of the web page that requests the permission.| + +### grant10+ + +grant(config: ScreenCaptureConfig): void + +**Required permissions**: ohos.permission.MICROPHONE, ohos.permission.CAPTURE_SCREEN + +Grants the screen capture permission. + +**Parameters** + +| Name | Type | Mandatory | Default Value | Description | +| --------- | --------------- | ---- | ---- | ------------- | +| config | [ScreenCaptureConfig](#screencaptureconfig10) | Yes | - | Screen capture configuration.| + ## ContextMenuSourceType9+ | Name | Description | | -------------------- | ---------- | @@ -4327,6 +4518,7 @@ Enumerates the error codes returned by **onSslErrorEventReceive** API. | --------- | ------------- | -------------------------- | | MidiSysex | MIDI SYSEX resource.| Currently, only permission events can be reported. MIDI devices are not yet supported.| | VIDEO_CAPTURE10+ | Video capture resource, such as a camera.| | +| AUDIO_CAPTURE10+ | Audio capture resource, such as a microphone.| | ## WebDarkMode9+ | Name | Description | @@ -4335,6 +4527,12 @@ Enumerates the error codes returned by **onSslErrorEventReceive** API. | On | The web dark mode is enabled. | | Auto | The web dark mode setting follows the system settings. | +## WebCaptureMode10+ + +| Name | Description | +| --------- | ------------- | +| HOME_SCREEN | Capture of the home screen.| + ## WebMediaOptions10+ Describes the web-based media playback policy. @@ -4344,6 +4542,14 @@ Describes the web-based media playback policy. | resumeInterval | number | Yes | Yes | No |Validity period for automatically resuming a paused web audio, in seconds. The maximum validity period is 60 seconds. Due to the approximate value, the validity period may have a deviation of less than 1 second.| | audioExclusive | boolean | Yes | Yes | No | Whether the audio of multiple **\** instances in an application is exclusive. | +## ScreenCaptureConfig10+ + +Provides the web screen capture configuration. + +| Name | Type | Readable| Writable| Mandatory| Description | +| -------------- | --------- | ---- | ---- | --- | ---------------------------- | +| captureMode | [WebCaptureMode](#webcapturemode10) | Yes | Yes | Yes | Web screen capture mode.| + ## DataResubmissionHandler9+ Implements the **DataResubmissionHandler** object for resubmitting or canceling the web form data. @@ -4653,7 +4859,7 @@ This API is deprecated since API version 9. You are advised to use [forward deleteJavaScriptRegister(name: string) -Deletes a specific application JavaScript object that is registered with the window through **registerJavaScriptProxy**. The deletion takes effect immediately, with no need for invoking the[refresh](#refreshdeprecated) API. +Deletes a specific application JavaScript object that is registered with the window through **registerJavaScriptProxy**. The deletion takes effect immediately, with no need for invoking the [refresh](#refreshdeprecated) API. This API is deprecated since API version 9. You are advised to use [deleteJavaScriptRegister9+](../apis/js-apis-webview.md#deletejavascriptregister) instead. diff --git a/en/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md b/en/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md index 7f0b8291246271cef1d8b9e82394004c051cf491..5630bcc7f24f2b40dca403a2b14cba04e37a8213 100644 --- a/en/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md +++ b/en/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md @@ -40,13 +40,13 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Description | | ---------------------------------------- | ---------------------------------------- | ---------------------------------------- | -| [fillStyle](#fillstyle) | string \|number10+ \|[CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](ts-components-canvas-canvaspattern.md#canvaspattern) | Style to fill an area.
- When the type is string, this attribute indicates the color of the fill area.
- When the type is number, this attribute indicates the color of the fill area.
- When the type is **CanvasGradient**, this attribute indicates a gradient object, which is created using the **[createLinearGradient](#createlineargradient)** API.
- When the type is **CanvasPattern**, this attribute indicates a pattern, which is created using the **[createPattern](#createpattern)** API.
Since API version 9, this API is supported in ArkTS widgets.| -| [lineWidth](#linewidth) | number | Line width. | -| [strokeStyle](#strokestyle) | string \|number10+ \|[CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](ts-components-canvas-canvaspattern.md#canvaspattern) | Stroke style.
- When the type is string, this attribute indicates the stroke color.
- When the type is number, this attribute indicates the stroke color.
- When the type is **CanvasGradient**, this attribute indicates a gradient object, which is created using the **[createLinearGradient](#createlineargradient)** API.
- When the type is **CanvasPattern**, this attribute indicates a pattern, which is created using the **[createPattern](#createpattern)** API.
Since API version 9, this API is supported in ArkTS widgets.| +| [fillStyle](#fillstyle) | string \|number10+ \|[CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](ts-components-canvas-canvaspattern.md#canvaspattern) | Style to fill an area.
- When the type is string, this attribute indicates the color of the fill area.
Default value: **'black'**
- When the type is number, this attribute indicates the color of the fill area.
Default value: **'#000000'**
- When the type is **CanvasGradient**, this attribute indicates a gradient object, which is created using the **[createLinearGradient](#createlineargradient)** API.
- When the type is **CanvasPattern**, this attribute indicates a pattern, which is created using the **[createPattern](#createpattern)** API.
Since API version 9, this API is supported in ArkTS widgets.| +| [lineWidth](#linewidth) | number | Line width.
Default value: **1(px)** | +| [strokeStyle](#strokestyle) | string \|number10+ \|[CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](ts-components-canvas-canvaspattern.md#canvaspattern) | Stroke style.
- When the type is string, this attribute indicates the stroke color.
Default value: **'black'**
- When the type is number, this attribute indicates the stroke color.
Default value: **'#000000'**
- When the type is **CanvasGradient**, this attribute indicates a gradient object, which is created using the **[createLinearGradient](#createlineargradient)** API.
- When the type is **CanvasPattern**, this attribute indicates a pattern, which is created using the **[createPattern](#createpattern)** API.
Since API version 9, this API is supported in ArkTS widgets.| | [lineCap](#linecap) | CanvasLineCap | Style of the line endpoints. The options are as follows:
- **'butt'**: The endpoints of the line are squared off.
- **'round'**: The endpoints of the line are rounded.
- **'square'**: The endpoints of the line are squared off by adding a box with an equal width and half the height of the line's thickness.
Default value: **'butt'**
Since API version 9, this API is supported in ArkTS widgets.| | [lineJoin](#linejoin) | CanvasLineJoin | Style of the shape used to join line segments. The options are as follows:
- **'round'**: The shape used to join line segments is a sector, whose radius at the rounded corner is equal to the line width.
- **'bevel'**: The shape used to join line segments is a triangle. The rectangular corner of each line is independent.
- **'miter'**: The shape used to join line segments has a mitered corner by extending the outside edges of the lines until they meet. You can view the effect of this attribute in **miterLimit**.
Default value: **'miter'**
Since API version 9, this API is supported in ArkTS widgets.| | [miterLimit](#miterlimit) | number | Maximum miter length. The miter length is the distance between the inner corner and the outer corner where two lines meet.
Default value: **10**
Since API version 9, this API is supported in ArkTS widgets.| -| [font](#font) | string | Font style.
Syntax: ctx.font='font-size font-family'
- (Optional) **font-size**: font size and row height. The unit can only be pixels.
- (Optional) **font-family**: font family.
Syntax: ctx.font='font-style font-weight font-size font-family'
- (Optional) **font-style**: font style. Available values are **'normal'** and **'italic'**.
- (Optional) **font-weight**: font weight. Available values are as follows: **'normal'**, **'bold'**, **'bolder'**, **'lighter'**, **'100'**, **'200'**, **'300'**, **'400'**, **'500'**, **'600'**, **'700'**, **'800'**, **'900'**.
- (Optional) **font-size**: font size and row height. The unit must be specified and can only be px or vp.
- (Optional) **font-family**: font family. Available values are **'sans-serif'**, **'serif'**, and **'monospace'**.
Default value: **'normal normal 14px sans-serif'**
Since API version 9, this API is supported in ArkTS widgets.| +| [font](#font) | string | Font style.
Syntax: ctx.font='font-size font-family'
- (Optional) **font-size**: font size and row height. The unit can only be px.
- (Optional) **font-family**: font family.
Syntax: ctx.font='font-style font-weight font-size font-family'
- (Optional) **font-style**: font style. Available values are **'normal'** and **'italic'**.
- (Optional) **font-weight**: font weight. Available values are as follows: **'normal'**, **'bold'**, **'bolder'**, **'lighter'**, **'100'**, **'200'**, **'300'**, **'400'**, **'500'**, **'600'**, **'700'**, **'800'**, **'900'**.
- (Optional) **font-size**: font size and row height. The unit must be specified and can only be px or vp.
- (Optional) **font-family**: font family. Available values are **'sans-serif'**, **'serif'**, and **'monospace'**.
Default value: **'normal normal 14px sans-serif'**
Since API version 9, this API is supported in ArkTS widgets.| | [textAlign](#textalign) | CanvasTextAlign | Text alignment mode. Available values are as follows:
- **'left'**: The text is left-aligned.
- **'right'**: The text is right-aligned.
- **'center'**: The text is center-aligned.
- **'start'**: The text is aligned with the start bound.
- **'end'**: The text is aligned with the end bound.
In the **ltr** layout mode, the value **'start'** equals **'left'**. In the **rtl** layout mode, the value **'start'** equals **'right'**.
Default value: **'left'**
Since API version 9, this API is supported in ArkTS widgets.| | [textBaseline](#textbaseline) | CanvasTextBaseline | Horizontal alignment mode of text. Available values are as follows:
- **'alphabetic'**: The text baseline is the normal alphabetic baseline.
- **'top'**: The text baseline is on the top of the text bounding box.
- **'hanging'**: The text baseline is a hanging baseline over the text.
- **'middle'**: The text baseline is in the middle of the text bounding box.
**'ideographic'**: The text baseline is the ideographic baseline. If a character exceeds the alphabetic baseline, the ideographic baseline is located at the bottom of the excess character.
- **'bottom'**: The text baseline is at the bottom of the text bounding box. Its difference from the ideographic baseline is that the ideographic baseline does not consider letters in the next line.
Default value: **'alphabetic'**
Since API version 9, this API is supported in ArkTS widgets.| | [globalAlpha](#globalalpha) | number | Opacity.
**0.0**: completely transparent.
**1.0**: completely opaque.
Since API version 9, this API is supported in ArkTS widgets.| @@ -59,8 +59,8 @@ Since API version 9, this API is supported in ArkTS widgets. | [imageSmoothingEnabled](#imagesmoothingenabled) | boolean | Whether to adjust the image smoothness during image drawing. The value **true** means to enable this feature, and **false** means the opposite.
Default value: **true**
Since API version 9, this API is supported in ArkTS widgets.| | [height](#height) | number | Component height.
Unit: vp
Since API version 9, this API is supported in ArkTS widgets.| | [width](#width) | number | Component width.
Unit: vp
Since API version 9, this API is supported in ArkTS widgets.| -| [imageSmoothingQuality](#imagesmoothingquality) | ImageSmoothingQuality | Quality of image smoothing. This attribute works only when **imageSmoothingEnabled** is set to **true**. Available values are as follows:
- **'low'**: low quality.
- **'medium'**: medium quality.
- **'high'**: high quality.
Default value: **'low'**
Since API version 9, this API is supported in ArkTS widgets.| -| [direction](#direction) | CanvasDirection | Text direction used for drawing text. Available values are as follows:
- **'inherit'**: The text direction is inherited from the **\** component.
- **'ltr'**: The text direction is from left to right.
- **'rtl'**: The text direction is from right to left.
Default value: **'inherit'**
Since API version 9, this API is supported in ArkTS widgets.| +| [imageSmoothingQuality](#imagesmoothingquality) |[ImageSmoothingQuality](ts-appendix-enums.md#imagesmoothingquality8) | Quality of image smoothing. This attribute works only when **imageSmoothingEnabled** is set to **true**.
Default value: **ImageSmoothingQuality.low**
Since API version 9, this API is supported in ArkTS widgets.| +| [direction](#direction) | [CanvasDirection](ts-appendix-enums.md#canvasdirection8) | Text direction used for drawing text.
Default value: **CanvasDirection.inherit**
Since API version 9, this API is supported in ArkTS widgets.| | [filter](#filter) | string | Filter effect. Available values are as follows:
- **'none'**: no filter effect.
- **'blur'**: applies the Gaussian blur for the image.
- **'brightness'**: applies a linear multiplication to the image to make it look brighter or darker.
- **'contrast'**: adjusts the image contrast.
- **'grayscale'**: converts the image to a grayscale image.
- **'hue-rotate'**: applies hue rotation to the image.
- **'invert'**: inverts the input image.
- **'opacity'**: sets the opacity of the image.
- **'saturate'**: sets the saturation of the image.
- **'sepia'**: converts the image to dark brown.
Default value: **'none'**
Since API version 9, this API is supported in ArkTS widgets.| > **NOTE** @@ -719,6 +719,136 @@ struct WidthExample { ![en-us_image_canvas_width](figures/en-us_image_canvas_width.png) +### imageSmoothingQuality + +```ts + // xxx.ets + @Entry + @Component + struct ImageSmoothingQualityDemo { + private settings: RenderingContextSettings = new RenderingContextSettings(true); + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); + private img:ImageBitmap = new ImageBitmap("common/images/example.jpg"); + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + let ctx = this.context + ctx.imageSmoothingEnabled = true + ctx.imageSmoothingQuality = 'high' + ctx.drawImage(this.img, 0, 0, 400, 200) + }) + } + .width('100%') + .height('100%') + } + } +``` + +![ImageSmoothingQualityDemo](figures/ImageSmoothingQualityDemo.jpeg) + + +### direction + +```ts + // xxx.ets + @Entry + @Component + struct DirectionDemo { + private settings: RenderingContextSettings = new RenderingContextSettings(true); + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + let ctx = this.context + ctx.font = '48px serif'; + ctx.textAlign = 'start' + ctx.fillText("Hi ltr!", 200, 50); + + ctx.direction = "rtl"; + ctx.fillText("Hi rtl!", 200, 100); + }) + } + .width('100%') + .height('100%') + } + } +``` + +![directionDemo](figures/directionDemo.jpeg) + + +### filter + +```ts + // xxx.ets + @Entry + @Component + struct FilterDemo { + private settings: RenderingContextSettings = new RenderingContextSettings(true); + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); + private img:ImageBitmap = new ImageBitmap("common/images/example.jpg"); + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + let ctx = this.context + let img = this.img + + ctx.drawImage(img, 0, 0, 100, 100); + + ctx.filter = 'grayscale(50%)'; + ctx.drawImage(img, 100, 0, 100, 100); + + ctx.filter = 'sepia(60%)'; + ctx.drawImage(img, 200, 0, 100, 100); + + ctx.filter = 'saturate(30%)'; + ctx.drawImage(img, 0, 100, 100, 100); + + ctx.filter = 'hue-rotate(90degree)'; + ctx.drawImage(img, 100, 100, 100, 100); + + ctx.filter = 'invert(100%)'; + ctx.drawImage(img, 200, 100, 100, 100); + + ctx.filter = 'opacity(25%)'; + ctx.drawImage(img, 0, 200, 100, 100); + + ctx.filter = 'brightness(0.4)'; + ctx.drawImage(img, 100, 200, 100, 100); + + ctx.filter = 'contrast(200%)'; + ctx.drawImage(img, 200, 200, 100, 100); + + ctx.filter = 'blur(5px)'; + ctx.drawImage(img, 0, 300, 100, 100); + + let result = ctx.toDataURL() + console.info(result) + }) + } + .width('100%') + .height('100%') + } + } +``` + +![filterDemo](figures/filterDemo.jpeg) + ## Methods @@ -734,8 +864,8 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | ------ | ------ | ---- | ---- | ------------- | -| x | number | Yes | 0 | X-coordinate of the upper left corner of the rectangle.| -| y | number | Yes | 0 | Y-coordinate of the upper left corner of the rectangle.| +| x | number | Yes | 0 | X coordinate of the upper left corner of the rectangle.| +| y | number | Yes | 0 | Y coordinate of the upper left corner of the rectangle.| | width | number | Yes | 0 | Width of the rectangle. | | height | number | Yes | 0 | Height of the rectangle. | @@ -780,8 +910,8 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | ---- | ------ | ---- | ---- | ------------ | -| x | number | Yes | 0 | X-coordinate of the upper left corner of the rectangle.| -| y | number | Yes | 0 | Y-coordinate of the upper left corner of the rectangle.| +| x | number | Yes | 0 | X coordinate of the upper left corner of the rectangle.| +| y | number | Yes | 0 | Y coordinate of the upper left corner of the rectangle.| | w | number | Yes | 0 | Width of the rectangle. | | h | number | Yes | 0 | Height of the rectangle. | @@ -826,8 +956,8 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | ---- | ------ | ---- | ---- | ------------- | -| x | number | Yes | 0 | X-coordinate of the upper left corner of the rectangle.| -| y | number | Yes | 0 | Y-coordinate of the upper left corner of the rectangle.| +| x | number | Yes | 0 | X coordinate of the upper left corner of the rectangle.| +| y | number | Yes | 0 | Y coordinate of the upper left corner of the rectangle.| | w | number | Yes | 0 | Width of the rectangle. | | h | number | Yes | 0 | Height of the rectangle. | @@ -875,8 +1005,8 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | -------- | ------ | ---- | ---- | --------------- | | text | string | Yes | '' | Text to draw. | -| x | number | Yes | 0 | X-coordinate of the lower left corner of the text.| -| y | number | Yes | 0 | Y-coordinate of the lower left corner of the text.| +| x | number | Yes | 0 | X coordinate of the lower left corner of the text.| +| y | number | Yes | 0 | Y coordinate of the lower left corner of the text.| | maxWidth | number | No | - | Maximum width allowed for the text. | **Example** @@ -922,8 +1052,8 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | -------- | ------ | ---- | ---- | --------------- | | text | string | Yes | '' | Text to draw. | -| x | number | Yes | 0 | X-coordinate of the lower left corner of the text.| -| y | number | Yes | 0 | Y-coordinate of the lower left corner of the text.| +| x | number | Yes | 0 | X coordinate of the lower left corner of the text.| +| y | number | Yes | 0 | Y coordinate of the lower left corner of the text.| | maxWidth | number | No | - | Maximum width of the text to be drawn. | **Example** @@ -1130,8 +1260,8 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | ---- | ------ | ---- | ---- | --------- | -| x | number | Yes | 0 | X-coordinate of the target position.| -| y | number | Yes | 0 | Y-coordinate of the target position.| +| x | number | Yes | 0 | X coordinate of the target position.| +| y | number | Yes | 0 | Y coordinate of the target position.| **Example** @@ -1177,8 +1307,8 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | ---- | ------ | ---- | ---- | --------- | -| x | number | Yes | 0 | X-coordinate of the target position.| -| y | number | Yes | 0 | Y-coordinate of the target position.| +| x | number | Yes | 0 | X coordinate of the target position.| +| y | number | Yes | 0 | Y coordinate of the target position.| **Example** @@ -1319,12 +1449,12 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | ---- | ------ | ---- | ---- | -------------- | -| cp1x | number | Yes | 0 | X-coordinate of the first parameter of the bezier curve.| -| cp1y | number | Yes | 0 | Y-coordinate of the first parameter of the bezier curve.| -| cp2x | number | Yes | 0 | X-coordinate of the second parameter of the bezier curve.| -| cp2y | number | Yes | 0 | Y-coordinate of the second parameter of the bezier curve.| -| x | number | Yes | 0 | X-coordinate of the end point on the bezier curve. | -| y | number | Yes | 0 | Y-coordinate of the end point on the bezier curve. | +| cp1x | number | Yes | 0 | X coordinate of the first parameter of the bezier curve.| +| cp1y | number | Yes | 0 | Y coordinate of the first parameter of the bezier curve.| +| cp2x | number | Yes | 0 | X coordinate of the second parameter of the bezier curve.| +| cp2y | number | Yes | 0 | Y coordinate of the second parameter of the bezier curve.| +| x | number | Yes | 0 | X coordinate of the end point on the bezier curve. | +| y | number | Yes | 0 | Y coordinate of the end point on the bezier curve. | **Example** @@ -1370,10 +1500,10 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | ---- | ------ | ---- | ---- | ----------- | -| cpx | number | Yes | 0 | X-coordinate of the bezier curve parameter.| -| cpy | number | Yes | 0 | Y-coordinate of the bezier curve parameter.| -| x | number | Yes | 0 | X-coordinate of the end point on the bezier curve.| -| y | number | Yes | 0 | Y-coordinate of the end point on the bezier curve.| +| cpx | number | Yes | 0 | X coordinate of the bezier curve parameter.| +| cpy | number | Yes | 0 | Y coordinate of the bezier curve parameter.| +| x | number | Yes | 0 | X coordinate of the end point on the bezier curve.| +| y | number | Yes | 0 | Y coordinate of the end point on the bezier curve.| **Example** @@ -1419,8 +1549,8 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | ---------------- | ------- | ---- | ----- | ---------- | -| x | number | Yes | 0 | X-coordinate of the center point of the arc.| -| y | number | Yes | 0 | Y-coordinate of the center point of the arc.| +| x | number | Yes | 0 | X coordinate of the center point of the arc.| +| y | number | Yes | 0 | Y coordinate of the center point of the arc.| | radius | number | Yes | 0 | Radius of the arc. | | startAngle | number | Yes | 0 | Start radian of the arc. | | endAngle | number | Yes | 0 | End radian of the arc. | @@ -1469,10 +1599,10 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | ------ | ------ | ---- | ---- | --------------- | -| x1 | number | Yes | 0 | X-coordinate of the first point on the arc.| -| y1 | number | Yes | 0 | Y-coordinate of the first point on the arc.| -| x2 | number | Yes | 0 | X-coordinate of the second point on the arc.| -| y2 | number | Yes | 0 | Y-coordinate of the second point on the arc.| +| x1 | number | Yes | 0 | X coordinate of the first point on the arc.| +| y1 | number | Yes | 0 | Y coordinate of the first point on the arc.| +| x2 | number | Yes | 0 | X coordinate of the second point on the arc.| +| y2 | number | Yes | 0 | Y coordinate of the second point on the arc.| | radius | number | Yes | 0 | Radius of the arc. | **Example** @@ -1518,8 +1648,8 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | ---------------- | ------- | ---- | ----- | ---------------------------------------- | -| x | number | Yes | 0 | X-coordinate of the ellipse center. | -| y | number | Yes | 0 | Y-coordinate of the ellipse center. | +| x | number | Yes | 0 | X coordinate of the ellipse center. | +| y | number | Yes | 0 | Y coordinate of the ellipse center. | | radiusX | number | Yes | 0 | Ellipse radius on the x-axis. | | radiusY | number | Yes | 0 | Ellipse radius on the y-axis. | | rotation | number | Yes | 0 | Rotation angle of the ellipse. The unit is radian. | @@ -1570,8 +1700,8 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | ---- | ------ | ---- | ---- | ------------- | -| x | number | Yes | 0 | X-coordinate of the upper left corner of the rectangle.| -| y | number | Yes | 0 | Y-coordinate of the upper left corner of the rectangle.| +| x | number | Yes | 0 | X coordinate of the upper left corner of the rectangle.| +| y | number | Yes | 0 | Y coordinate of the upper left corner of the rectangle.| | w | number | Yes | 0 | Width of the rectangle. | | h | number | Yes | 0 | Height of the rectangle. | @@ -1802,97 +1932,6 @@ Since API version 9, this API is supported in ArkTS widgets. ![en-us_image_000000127777779](figures/en-us_image_000000127777779.png) -### filter - -filter(filter: string): void - -Provides filter effects. - -Since API version 9, this API is supported in ArkTS widgets. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ------ | ------ | ---- | ---- | ---------------------------------------- | -| filter | string | Yes | - | Filter functions. Available values are as follows:
- **'none'**: no filter effect.
- **'blur'**: applies the Gaussian blur for the image.
- **'brightness'**: applies a linear multiplication to the image to make it look brighter or darker.
- **'contrast'**: adjusts the image contrast.
- **'grayscale'**: converts the image to a grayscale image.
- **'hue-rotate'**: applies hue rotation to the image.
- **'invert'**: inverts the input image.
- **'opacity'**: sets the opacity of the image.
- **'saturate'**: sets the saturation of the image.
- **'sepia'**: converts the image to dark brown.
Default value: **'none'**| - -**Example** -```ts - // xxx.ets - @Entry - @Component - struct FilterDemo { - private settings: RenderingContextSettings = new RenderingContextSettings(true); - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); - private img:ImageBitmap = new ImageBitmap("common/images/example.jpg"); - - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() =>{ - let ctx = this.context - let img = this.img - - ctx.drawImage(img, 0, 0, 100, 100); - - ctx.filter = 'grayscale(50%)'; - ctx.drawImage(img, 100, 0, 100, 100); - - ctx.filter = 'sepia(60%)'; - ctx.drawImage(img, 200, 0, 100, 100); - - ctx.filter = 'saturate(30%)'; - ctx.drawImage(img, 0, 100, 100, 100); - - ctx.filter = 'hue-rotate(90degree)'; - ctx.drawImage(img, 100, 100, 100, 100); - - ctx.filter = 'invert(100%)'; - ctx.drawImage(img, 200, 100, 100, 100); - - ctx.filter = 'opacity(25%)'; - ctx.drawImage(img, 0, 200, 100, 100); - - ctx.filter = 'brightness(0.4)'; - ctx.drawImage(img, 100, 200, 100, 100); - - ctx.filter = 'contrast(200%)'; - ctx.drawImage(img, 200, 200, 100, 100); - - ctx.filter = 'blur(5px)'; - ctx.drawImage(img, 0, 300, 100, 100); - - let result = ctx.toDataURL() - console.info(result) - }) - } - .width('100%') - .height('100%') - } - } -``` - -![filterDemo](figures/filterDemo.jpeg) - - -### getTransform - -getTransform(): Matrix2D - -Obtains the current transformation matrix being applied to the context. This API is a void API. - -Since API version 9, this API is supported in ArkTS widgets. - -**Return value** - -| Type | Description | -| ---------------------------------------- | ----- | -| [Matrix2D](ts-components-canvas-matrix2d.md#Matrix2D) | **Matrix2D** object.| - - ### resetTransform resetTransform(): void @@ -1902,47 +1941,6 @@ Resets the current transform to the identity matrix. This API is a void API. Since API version 9, this API is supported in ArkTS widgets. -### direction - -direction(direction: CanvasDirection): void - -Sets the current text direction used to draw text. - -Since API version 9, this API is supported in ArkTS widgets. - -**Example** -```ts - // xxx.ets - @Entry - @Component - struct DirectionDemo { - private settings: RenderingContextSettings = new RenderingContextSettings(true); - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); - - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() =>{ - let ctx = this.context - ctx.font = '48px serif'; - ctx.textAlign = 'start' - ctx.fillText("Hi ltr!", 200, 50); - - ctx.direction = "rtl"; - ctx.fillText("Hi rtl!", 200, 100); - }) - } - .width('100%') - .height('100%') - } - } -``` - -![directionDemo](figures/directionDemo.jpeg) - ### rotate rotate(angle: number): void @@ -2152,7 +2150,7 @@ Since API version 9, this API is supported in ArkTS widgets. setTransform(transform?: Matrix2D): void -Resets the current transformation to the identity matrix, and then creates a new transformation matrix based on the specified **Matrix2D** object. This API is a void API. +Resets the current transformation to the identity matrix, and then creates a new transformation matrix based on the specified **Matrix2D** object. Since API version 9, this API is supported in ArkTS widgets. @@ -2162,6 +2160,66 @@ Since API version 9, this API is supported in ArkTS widgets. | --------- | ---------------------------------------- | ---- | ---- | ----- | | transform | [Matrix2D](ts-components-canvas-matrix2d.md#Matrix2D) | No | null | Transformation matrix.| +### getTransform + +getTransform(): Matrix2D + +Obtains the current transformation matrix being applied to the context. + +Since API version 9, this API is supported in ArkTS widgets. + +**Return value** + +| Type | Description | +| ---------------------------------------- | ----- | +| [Matrix2D](ts-components-canvas-matrix2d.md#Matrix2D) | **Matrix2D** object.| + +**Example** + + ```ts + // xxx.ets + @Entry + @Component + struct TransFormDemo { + private settings: RenderingContextSettings = new RenderingContextSettings(true); + private context1: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); + private context2: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Text('context1'); + Canvas(this.context1) + .width('230vp') + .height('120vp') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.context1.fillRect(50, 50, 50, 50); + this.context1.setTransform(1.2, Math.PI/8, Math.PI/6, 0.5, 30, -25); + this.context1.fillRect(50, 50, 50, 50); + }) + Text('context2'); + Canvas(this.context2) + .width('230vp') + .height('120vp') + .backgroundColor('#0ffff0') + .onReady(() =>{ + this.context2.fillRect(50, 50, 50, 50); + let storedTransform = this.context1.getTransform(); + console.log("Matrix [scaleX = " + storedTransform.scaleX + ", scaleY = " + storedTransform.scaleY + + ", rotateX = " + storedTransform.rotateX + ", rotateY = " + storedTransform.rotateY + + ", translateX = " + storedTransform.translateX + ", translateY = " + storedTransform.translateY + "]") + this.context2.setTransform(storedTransform); + this.context2.fillRect(50,50,50,50); + }) + } + .width('100%') + .height('100%') + } + } + ``` + + ![en-us_image_0000001219982726.png](figures/en-us_image_0000001219982726.png) + ### translate translate(x: number, y: number): void @@ -2225,12 +2283,12 @@ Since API version 9, this API is supported in ArkTS widgets, except that **Pixel | Name | Type | Mandatory | Default Value | Description | | ----- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | | image | [ImageBitmap](ts-components-canvas-imagebitmap.md) or [PixelMap](../apis/js-apis-image.md#pixelmap7)| Yes | null | Image resource. For details, see **ImageBitmap** or PixelMap. | -| sx | number | No | 0 | X-coordinate of the upper left corner of the rectangle used to crop the source image. | -| sy | number | No | 0 | Y-coordinate of the upper left corner of the rectangle used to crop the source image. | +| sx | number | No | 0 | X coordinate of the upper left corner of the rectangle used to crop the source image. | +| sy | number | No | 0 | Y coordinate of the upper left corner of the rectangle used to crop the source image. | | sw | number | No | 0 | Target width to crop the source image. | | sh | number | No | 0 | Target height to crop the source image. | -| dx | number | Yes | 0 | X-coordinate of the upper left corner of the drawing area on the canvas. | -| dy | number | Yes | 0 | Y-coordinate of the upper left corner of the drawing area on the canvas. | +| dx | number | Yes | 0 | X coordinate of the upper left corner of the drawing area on the canvas. | +| dy | number | Yes | 0 | Y coordinate of the upper left corner of the drawing area on the canvas. | | dw | number | No | 0 | Width of the drawing area. If the width of the drawing area is different from that of the cropped image, the latter will be stretched or compressed to the former.| | dh | number | No | 0 | Height of the drawing area. If the height of the drawing area is different from that of the cropped image, the latter will be stretched or compressed to the former.| @@ -2310,8 +2368,8 @@ Obtains the **[PixelMap](../apis/js-apis-image.md#pixelmap7)** object created wi | Name | Type | Mandatory | Default Value | Description | | ---- | ------ | ---- | ---- | --------------- | -| sx | number | Yes | 0 | X-coordinate of the upper left corner of the output area.| -| sy | number | Yes | 0 | Y-coordinate of the upper left corner of the output area.| +| sx | number | Yes | 0 | X coordinate of the upper left corner of the output area.| +| sy | number | Yes | 0 | Y coordinate of the upper left corner of the output area.| | sw | number | Yes | 0 | Width of the output area. | | sh | number | Yes | 0 | Height of the output area. | @@ -2333,8 +2391,8 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | ---- | ------ | ---- | ---- | --------------- | -| sx | number | Yes | 0 | X-coordinate of the upper left corner of the output area.| -| sy | number | Yes | 0 | Y-coordinate of the upper left corner of the output area.| +| sx | number | Yes | 0 | X coordinate of the upper left corner of the output area.| +| sy | number | Yes | 0 | Y coordinate of the upper left corner of the output area.| | sw | number | Yes | 0 | Width of the output area. | | sh | number | Yes | 0 | Height of the output area. | @@ -2537,52 +2595,6 @@ Since API version 9, this API is supported in ArkTS widgets. ![en-us_image_000000127777778](figures/en-us_image_000000127777778.png) - -### imageSmoothingQuality - -imageSmoothingQuality(quality: imageSmoothingQuality) - -Sets the quality of image smoothing. - -Since API version 9, this API is supported in ArkTS widgets. - - **Parameters** - -| Name | Type | Description | -| ------- | --------------------- | ---------------------------------------- | -| quality | imageSmoothingQuality | Quality of image smoothing.
- **'low'**: low quality.
- **'medium'**: medium quality.
- **'high'**: high quality.| - -**Example** -```ts - // xxx.ets - @Entry - @Component - struct ImageSmoothingQualityDemo { - private settings: RenderingContextSettings = new RenderingContextSettings(true); - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings); - private img:ImageBitmap = new ImageBitmap("common/images/example.jpg"); - - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() =>{ - let ctx = this.context - ctx.imageSmoothingEnabled = true - ctx.imageSmoothingQuality = 'high' - ctx.drawImage(this.img, 0, 0, 400, 200) - }) - } - .width('100%') - .height('100%') - } - } -``` - -![ImageSmoothingQualityDemo](figures/ImageSmoothingQualityDemo.jpeg) - ### transferFromImageBitmap transferFromImageBitmap(bitmap: ImageBitmap): void @@ -2775,10 +2787,10 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | ---- | ------ | ---- | ---- | -------- | -| x0 | number | Yes | 0 | X-coordinate of the start point.| -| y0 | number | Yes | 0 | Y-coordinate of the start point.| -| x1 | number | Yes | 0 | X-coordinate of the end point.| -| y1 | number | Yes | 0 | Y-coordinate of the end point.| +| x0 | number | Yes | 0 | X coordinate of the start point.| +| y0 | number | Yes | 0 | Y coordinate of the start point.| +| x1 | number | Yes | 0 | X coordinate of the end point.| +| y1 | number | Yes | 0 | Y coordinate of the end point.| **Example** @@ -2826,11 +2838,11 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Type | Mandatory | Default Value | Description | | ---- | ------ | ---- | ---- | ----------------- | -| x0 | number | Yes | 0 | X-coordinate of the center of the start circle. | -| y0 | number | Yes | 0 | Y-coordinate of the center of the start circle. | +| x0 | number | Yes | 0 | X coordinate of the center of the start circle. | +| y0 | number | Yes | 0 | Y coordinate of the center of the start circle. | | r0 | number | Yes | 0 | Radius of the start circle, which must be a non-negative finite number.| -| x1 | number | Yes | 0 | X-coordinate of the center of the end circle. | -| y1 | number | Yes | 0 | Y-coordinate of the center of the end circle. | +| x1 | number | Yes | 0 | X coordinate of the center of the end circle. | +| y1 | number | Yes | 0 | Y coordinate of the center of the end circle. | | r1 | number | Yes | 0 | Radius of the end circle, which must be a non-negative finite number.| **Example** @@ -2877,8 +2889,8 @@ Creates a conic gradient. | Name | Type | Mandatory | Default Value | Description | | ---------- | ------ | ---- | ---- | ----------------------------------- | | startAngle | number | Yes | 0 | Angle at which the gradient starts, in radians. The angle measurement starts horizontally from the right side of the center and moves clockwise.| -| x | number | Yes | 0 | X-coordinate of the center of the conic gradient, in vp. | -| y | number | Yes | 0 | X-coordinate of the center of the conic gradient, in vp. | +| x | number | Yes | 0 | X coordinate of the center of the conic gradient, in vp. | +| y | number | Yes | 0 | Y coordinate of the center of the conic gradient, in vp. | **Example** diff --git a/en/application-dev/reference/arkui-ts/ts-container-listitem.md b/en/application-dev/reference/arkui-ts/ts-container-listitem.md index cd8ef63993cdbfdc654453e9d647bd2fdb5ac7d1..86b924cdc24f71291ed592877833a14b6d5448b3 100644 --- a/en/application-dev/reference/arkui-ts/ts-container-listitem.md +++ b/en/application-dev/reference/arkui-ts/ts-container-listitem.md @@ -76,12 +76,11 @@ For a list in horizontal layout, it refers to the delete item displayed below (o | Name | Type | Mandatory| Description | | -------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| deleteAreaDistance | [Length](ts-types.md#length) | No| Swipe distance threshold for deleting the list item.
Default value: **56vp**
**NOTE**
This parameter cannot be set in percentage.
If the value is greater than the list item width minus the width of **swipeAction**, or is less than or equal to 0, the delete area will not be set.| -| onDelete | () => void | No| Callback invoked when the list item is released while in the delete area.
**NOTE**
This callback is invoked only when the list item is released in a position that meets or goes beyond the specified swipe distance threshold (which must be valid) for deleting the list item.| -| onEntryDeleteArea | () => void | No| Callback invoked each time the list item enters the delete area.| -| onExitDeleteArea | () => void | No|Callback invoked each time the list item exits the delete area.| +| actionAreaDistance | [Length](ts-types.md#length) | No| Swipe distance threshold for deleting the list item.
Default value: **56vp**
**NOTE**
This parameter cannot be set in percentage.
If the value is greater than the list item width minus the width of **swipeAction**, or is less than or equal to 0, the delete area will not be set.| +| onAction | () => void | No| Callback invoked when the list item is released while in the delete area.
**NOTE**
This callback is invoked only when the list item is released in a position that meets or goes beyond the specified swipe distance threshold (which must be valid) for deleting the list item.| +| onEnterActionArea | () => void | No| Callback invoked each time the list item enters the delete area.| +| onExitActionArea | () => void | No|Callback invoked each time the list item exits the delete area.| | builder | CustomBuilder | No|Swipe action item displayed when the list item is swiped left or right (in vertical list layout) or up or down (in horizontal list layout).| -| useDefaultDeleteAnimation | boolean | No|Whether to use the default delete animation.
Default value: **true**| ## ListItemOptions10+ | Name | Type | Mandatory| Description | @@ -101,9 +100,10 @@ For a list in horizontal layout, it refers to the delete item displayed below (o | -------- | -------- | | onSelect(event: (isSelected: boolean) => void)8+ | Triggered when the selected state of the **\** changes.
**isSelected**: Returns **true** if the **\** is selected by mouse drag; returns **false** otherwise.| - ## Example +### Example 1 + ```ts // xxx.ets @Entry @@ -130,6 +130,8 @@ struct ListItemExample { ![en-us_image_0000001219864159](figures/en-us_image_0000001219864159.gif) +### Example 2 + ```ts // xxx.ets @@ -165,19 +167,18 @@ struct ListItemExample2 { .swipeAction({ end: { builder: this.itemEnd.bind(this, item), - useDefaultDeleteAnimation: true, - onDelete: () => { + onAction: () => { animateTo({ duration: 1000 }, () => { let index = this.arr.indexOf(item) this.arr.splice(index, 1) }) }, - deleteAreaDistance: 80, - onEnterDeleteArea: () => { + actionAreaDistance: 80, + onEnterActionArea: () => { this.enterEndDeleteAreaString = "enterEndDeleteArea" this.exitEndDeleteAreaString = "not exitEndDeleteArea" }, - onExitDeleteArea: () => { + onExitActionArea: () => { this.enterEndDeleteAreaString = "not enterEndDeleteArea" this.exitEndDeleteAreaString = "exitEndDeleteArea" } @@ -196,3 +197,43 @@ struct ListItemExample2 { } ``` ![deleteListItem](figures/deleteListItem.gif) + +### Example 3 + +```ts +// xxx.ets +@Entry +@Component +struct ListItemExample3 { + private arr: any = [ListItemStyle.CARD, ListItemStyle.CARD,ListItemStyle.NONE] + build() { + Column() { + List({ space: "4vp", initialIndex: 0 }) { + ListItemGroup({style:ListItemGroupStyle.CARD}){ + ForEach(this.arr, (itemStyle,index) => { + ListItem({style:itemStyle}) { + Text(""+index) + .width("100%") + .textAlign(TextAlign.Center) + } + }) + } + ForEach(this.arr, (itemStyle,index) => { + ListItem({style:itemStyle}) { + Text(""+index) + .width("100%") + .textAlign(TextAlign.Center) + } + }) + } + .width('100%') + .multiSelectable(true) + .backgroundColor(0xDCDCDC) // List in light blue + } + .width('100%') + .padding({ top: 5 }) + } +} + +``` +![ListItemStyle](figures/listItem3.jpeg) diff --git a/en/application-dev/reference/arkui-ts/ts-container-listitemgroup.md b/en/application-dev/reference/arkui-ts/ts-container-listitemgroup.md index 48ed2249eb25c786c2bcd5f8cb900bd4e4b1589a..9f3ff104bab488a2bcc3f4e02f3ddd572742ba34 100644 --- a/en/application-dev/reference/arkui-ts/ts-container-listitemgroup.md +++ b/en/application-dev/reference/arkui-ts/ts-container-listitemgroup.md @@ -8,9 +8,9 @@ The **\** component is used to display list item groups. It must ## Usage Guidelines -If the **listDirection** attribute of the parent **\** component is set to **Axis.Vertical**, the **height** attribute of the **\** component cannot be set. The height of a **\** component is the sum of its header height, footer height, and total height of the list items. If the **listDirection** attribute of the parent **\** component is set to **Axis.Horizontal**, the **width** attribute of the **\** component cannot be set. The width of a **\** component is the sum of its header width, footer width, and total width of the list items. +If the **listDirection** attribute of the parent **\** component is set to **Axis.Vertical**, the **height** attribute of the **\** component is fixed at the sum of the component's header height, footer height, and total height of the list items. If the **listDirection** attribute of the parent **\** component is set to **Axis.Horizontal**, the **width** attribute of the **\** component is fixed at the sum of the component's header width, footer width, and total width of the list items. -The list items in the **\** component cannot be edited, selected, or dragged. That is, the **editable** and **selectable** attributes of these list items do not take effect. +The list items in the **\** component cannot be edited or dragged. That is, their **editable** attribute does not take effect. ## Child Components @@ -27,8 +27,8 @@ ListItemGroup(options?: {header?: CustomBuilder, footer?: CustomBuilder, space?: | ------------------- | --------------------------------------------------- | ---- | ------------------------------------------------------------ | | header | [CustomBuilder](ts-types.md#custombuilder8) | No | Header of the list item group. | | footer | [CustomBuilder](ts-types.md#custombuilder8) | No | Footer of the list item group. | -| space | number \| string | No | Spacing between list items. This parameter is valid only between list items, but not between a header and list item or between a footer and list item.| -| style10+ | [ListItemGroupStyle](#listitemgroupstyle10) | No | Style of the list item group.
Default value: **ListItemGroupStyle.NONE**
If this parameter is set to **ListItemGroupStyle.NONE**, no style is applied.
If this parameter is set to **ListItemGroupStyle.CARD**, the default card style is applied, but only when **ListItemStyle.CARD** is set for [\](ts-container-listitem.md).
It can be in focus, hover, press, selected, or disable style depending on the state.
**NOTE**
In the default card style, the list has its **listDirection** attribute fixed at **Axis.Vertical** and **alignListItem** attribute at **ListItemAlign.Center**; the **header** and **footer** parameters cannot be set for the list item group. | +| space | number \| string | No | Spacing between list items. This parameter is valid only between list items, but not between the header and list item or between the footer and list item.| +| style10+ | [ListItemGroupStyle](#listitemgroupstyle10) | No | Style of the list item group.
Default value: **ListItemGroupStyle.NONE**
If this parameter is set to **ListItemGroupStyle.NONE**, no style is applied.
If this parameter is set to **ListItemGroupStyle.CARD**, the default card style is applied, but only when **ListItemStyle.CARD** is set for [\](ts-container-listitem.md).
In the default card style, list items can be in focus, hover, press, selected, or disable style depending on their state.
**NOTE**
In the default card style, the parent **\** component has its **listDirection** attribute fixed at **Axis.Vertical** and its **alignListItem** attribute defaulted at **ListItemAlign.Center**; the **header** and **footer** parameters cannot be set for the list item group. | ## Attributes @@ -45,7 +45,7 @@ ListItemGroup(options?: {header?: CustomBuilder, footer?: CustomBuilder, space?: > **NOTE** > -> The **\** component does not support the universal attribute **[aspectRatio](ts-universal-attributes-layout-constraints.md)**. +> The **\** component does not support the universal attribute [aspectRatio](ts-universal-attributes-layout-constraints.md). > > If the main axis of **\** runs in the vertical direction, the [height](ts-universal-attributes-size.md) setting does not take effect. > @@ -54,6 +54,8 @@ ListItemGroup(options?: {header?: CustomBuilder, footer?: CustomBuilder, space?: ## Example +### Example 1 + ```ts // xxx.ets @Entry @@ -119,3 +121,55 @@ struct ListItemGroupExample { ``` ![en-us_image_0000001219864159](figures/en-us_image_listitemgroup.gif) + +### Example 2 + +```ts +// xxx.ets +@Entry +@Component +struct ListItemGroupExample2 { + private arr: any = [ + { + style:ListItemGroupStyle.CARD, + itemStyles:[ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.CARD] + }, + { + style:ListItemGroupStyle.CARD, + itemStyles:[ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE] + }, + { + style:ListItemGroupStyle.CARD, + itemStyles:[ListItemStyle.CARD, ListItemStyle.NONE, ListItemStyle.CARD] + }, + { + style:ListItemGroupStyle.NONE, + itemStyles:[ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE] + } + ] + build() { + Column() { + List({ space: "4vp", initialIndex: 0 }) { + ForEach(this.arr, (item,index) => { + ListItemGroup({ style:item.style }) { + ForEach(item.itemStyles, (itemStyle,itemIndex) => { + ListItem({style:itemStyle}) { + Text("Item "+(itemIndex+1)+" in group "+(index+1)) + .width("100%") + .textAlign(TextAlign.Center) + } + }, item => item) + } + }) + } + .width('100%') + .multiSelectable(true) + .backgroundColor(0xDCDCDC) // List in light blue + } + .width('100%') + .padding({ top: 5 }) + } +} + +``` +![ListItemGroupStyle](figures/listItemGroup2.jpeg) diff --git a/en/application-dev/reference/arkui-ts/ts-container-sidebarcontainer.md b/en/application-dev/reference/arkui-ts/ts-container-sidebarcontainer.md index da83e2257a34430922c41df0ed57fc91aa8a137e..3735991eeea0045115f085c11f63f9452d861f18 100644 --- a/en/application-dev/reference/arkui-ts/ts-container-sidebarcontainer.md +++ b/en/application-dev/reference/arkui-ts/ts-container-sidebarcontainer.md @@ -45,13 +45,13 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the | showSideBar | boolean | Whether to display the sidebar.
Default value: **true**
Since API version 10, this attribute supports [$$](../../quick-start/arkts-two-way-sync.md) for two-way binding of variables.| | controlButton | [ButtonStyle](#buttonstyle) | Attributes of the sidebar control button.| | showControlButton | boolean | Whether to display the sidebar control button.
Default value: **true**| -| sideBarWidth | number \| [Length](ts-types.md#length)9+ | Width of the sidebar.
Default value: **240vp**
Unit: vp
**NOTE**
In API version 9 and earlier versions, the default value is **200vp**. In API version 10, the default value is **240vp**.
A value less than 0 evaluates to the default value.
The value must comply with the width constraints. If it is not within the valid range, the value closest to the set one is used.
The width of the sidebar, whether it is specified or kept at the default, takes precedence over that of the sidebar child components.| -| minSideBarWidth | number \| [Length](ts-types.md#length)9+ | Minimum width of the sidebar.
Default value: **240vp**
Unit: vp
**NOTE**
In API version 9 and earlier versions, the default value is **200vp**. In API version 10, the default value is **240vp**.
A value less than 0 evaluates to the default value.
The value cannot exceed the width of the sidebar container itself. Otherwise, the width of the sidebar container itself is used.
When set, the minimum width of the sidebar takes precedence over that of the sidebar child components. If it is not set, however, the minimum width of the sidebar child component takes precedence.| -| maxSideBarWidth | number \| [Length](ts-types.md#length)9+ | Maximum width of the sidebar.
Default value: **280vp**
Unit: vp
**NOTE**
A value less than 0 evaluates to the default value.
The value cannot exceed the width of the sidebar container itself. Otherwise, the width of the sidebar container itself is used.
When set, the maximum width of the sidebar takes precedence over that of the sidebar child components. If it is not set, however, the maximum width of the sidebar child component takes precedence.| +| sideBarWidth | number \| [Length](ts-types.md#length)9+ | Width of the sidebar.
Default value: **240vp**
Unit: vp
**NOTE**
In API version 9 and earlier versions, the default value is **200vp**. In API version 10, the default value is **240vp**.
A value less than 0 evaluates to the default value.
The value must comply with the width constraints. If it is not within the valid range, the value closest to the set one is used.
The width of the sidebar, whether it is specified or kept at the default value, takes precedence over that of the sidebar child components.| +| minSideBarWidth | number \| [Length](ts-types.md#length)9+ | Minimum width of the sidebar.
Default value: **240vp**
Unit: vp
**NOTE**
In API version 9 and earlier versions, the default value is **200vp**. In API version 10, the default value is **240vp**.
A value less than 0 evaluates to the default value.
The value cannot exceed the width of the sidebar container itself. Otherwise, the width of the sidebar container itself is used.
**minSideBarWidth**, whether it is specified or kept at the default value, takes precedence over **minWidth** of the sidebar child components.| +| maxSideBarWidth | number \| [Length](ts-types.md#length)9+ | Maximum width of the sidebar.
Default value: **280vp**
Unit: vp
**NOTE**
A value less than 0 evaluates to the default value.
The value cannot exceed the width of the sidebar container itself. Otherwise, the width of the sidebar container itself is used.
**maxSideBarWidth**, whether it is specified or kept at the default value, takes precedence over **maxWidth** of the sidebar child components.| | autoHide9+ | boolean | Whether to automatically hide the sidebar when it is dragged to be smaller than the minimum width.
Default value: **true**
**NOTE**
The value is subject to the **minSideBarWidth** attribute method. If it is not set in **minSideBarWidth**, the default value is used.
Whether the sidebar should be hidden is determined when it is being dragged. When its width is less than the minimum width, the damping effect is required to trigger hiding (a distance out of range).| | sideBarPosition9+ | [SideBarPosition](#sidebarposition9) | Position of the sidebar.
Default value: **SideBarPosition.Start**| | divider10+ | [DividerStyle](#dividerstyle10) \| null | Divider style.
- **DividerStyle** (default): The divider is displayed.
- **null**: The divider is not displayed.| -| minContentWidth10+ | [Dimension](ts-types.md#dimension10) | Minimum width of the content area of the sidebar container.
Default value: **360vp**
Unit: vp
**NOTE**
A value less than 0 evaluates to the default value.
In Embed mode, when the component size is increased, only the content area is enlarged; when the component size is decreased, the content area is shrunk until its width reaches the value defined by **minContentWidth**, and then the sidebar is shrunk until its width reaches the value defined by **minSideBarWidth**; if the component size is further decreased, while respecting the minimum width of the sidebar, the content area is further shrunk until it is 0 vp large.
minContentWidth takes precedence over maxSideBarWidth and sideBarWidth of the sidebar. If minContentWidth is not set, the priority of the default value is lower than that of minSideBarWidth and maxSideBarWidth.| +| minContentWidth10+ | [Dimension](ts-types.md#dimension10) | Minimum width of the content area of the sidebar container.
Default value: **360vp**
Unit: vp
**NOTE**
If this attribute is set to a value less than 0, the default value is used. If this attribute is not set, the value **0vp** is used.
In Embed mode, when the component size is increased, only the content area is enlarged; when the component size is decreased, the content area is shrunk until its width reaches the value defined by **minContentWidth**, and then the sidebar is shrunk until its width reaches the value defined by **minSideBarWidth**; if the component size is further decreased, while respecting the minimum width of the sidebar, the content area is further shrunk, with the content clipped, until it is 0 vp large.
**minContentWidth**, whether it is specified or kept at the default value, takes precedence over **minSideBarWidth** and **sideBarWidth** of the sidebar. | ## ButtonStyle @@ -83,7 +83,7 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the > The settings of the [universal size attributes](ts-universal-attributes-size.md) **width** and **height** do not take effect for the sidebar child component. > The settings do not take effect for the sidebar content area either. By default, the sidebar content area takes up the remaining space of the sidebar container. > -> If the attribute method is not used, the sidebar is displayed depending on the size. +> If the **showSideBar** attribute is not set, the sidebar's visibility is subject to its size. > > - If the size is less than 520 vp, the sidebar is not displayed by default. > - If the size is greater than or equal to 520 vp, the sidebar is displayed by default. @@ -127,8 +127,6 @@ struct SideBarContainerExample { }.width('100%') .justifyContent(FlexAlign.SpaceEvenly) .backgroundColor('#19000000') - - Column() { Text('SideBarContainer content text1').fontSize(25) Text('SideBarContainer content text2').fontSize(25) @@ -148,6 +146,7 @@ struct SideBarContainerExample { .onChange((value: boolean) => { console.info('status:' + value) }) + .divider({strokeWidth: '1vp', color: Color.Gray, startMargin: '4vp', endMargin: '4vp'}) } } ``` diff --git a/en/application-dev/reference/arkui-ts/ts-methods-action-sheet.md b/en/application-dev/reference/arkui-ts/ts-methods-action-sheet.md index 05c6a8e612ead7cd031b37c1fe52c3ba302bd52d..44ff79e8bc80a7f2c88dc380febfc916c93aa87b 100644 --- a/en/application-dev/reference/arkui-ts/ts-methods-action-sheet.md +++ b/en/application-dev/reference/arkui-ts/ts-methods-action-sheet.md @@ -22,7 +22,7 @@ Defines and shows the action sheet. | ---------- | -------------------------- | ------- | ----------------------------- | | title | [Resource](ts-types.md#resource) \| string | Yes | Title of the dialog box.| | message | [Resource](ts-types.md#resource) \| string | Yes | Content of the dialog box. | -| autoCancel | boolean | No | Whether to close the dialog box when the overlay is clicked.
Default value: **true**| +| autoCancel | boolean | No | Whether to close the dialog box when the overlay is clicked.
Default value: **true**
The value **true** means to close the dialog box when the overlay is clicked, and **false** means the opposite.| | confirm | {
value: [ResourceStr](ts-types.md#resourcestr),
action: () => void
} | No | Text content of the confirm button and callback upon button clicking.
Default value:
**value**: button text.
**action**: callback upon button clicking.| | cancel | () => void | No | Callback invoked when the dialog box is closed after the overlay is clicked. | | alignment | [DialogAlignment](ts-methods-alert-dialog-box.md#dialogalignment) | No | Alignment mode of the dialog box in the vertical direction.
Default value: **DialogAlignment.Bottom**| diff --git a/en/application-dev/reference/arkui-ts/ts-methods-alert-dialog-box.md b/en/application-dev/reference/arkui-ts/ts-methods-alert-dialog-box.md index 23371f6c72aba355a27702582aea203ebaa42698..282865563a52e5e7b0d78d5387fe09898c57b31c 100644 --- a/en/application-dev/reference/arkui-ts/ts-methods-alert-dialog-box.md +++ b/en/application-dev/reference/arkui-ts/ts-methods-alert-dialog-box.md @@ -25,8 +25,8 @@ You can set the text content and response callback for an alert dialog box. | confirm | {
value: [ResourceStr](ts-types.md#resourcestr),
fontColor?: [ResourceColor](ts-types.md#resourcecolor),
backgroundColor?: [ResourceColor](ts-types.md#resourcecolor),
action: () => void
} | No | Text content, text color, background color, and click callback of the confirm button.| | cancel | () => void | No | Callback invoked when the dialog box is closed after the overlay is clicked.| | alignment | [DialogAlignment](#dialogalignment) | No | Alignment mode of the dialog box in the vertical direction.
Default value: **DialogAlignment.Default**| -| offset | [Offset](ts-types.md#offset) | No | Offset of the dialog box relative to the alignment position.| -| gridCount | number | No | Number of grid columns occupied by the width of the dialog box.| +| offset | [Offset](ts-types.md#offset) | No | Offset of the dialog box relative to the alignment position.
Default value: **{ dx: 0 , dy: 0 }**| +| gridCount | number | No | Number of grid columns occupied by the width of the dialog box.
Default value: **4**| ## AlertDialogParamWithButtons | Name | Type | Mandatory | Description | @@ -35,7 +35,7 @@ You can set the text content and response callback for an alert dialog box. | message | [ResourceStr](ts-types.md#resourcestr) | Yes | Content of the dialog box. | | autoCancel | boolean | No | Whether to close the dialog box when the overlay is clicked.
Default value: **true** | | primaryButton | {
value: [ResourceStr](ts-types.md#resourcestr),
fontColor?: [ResourceColor](ts-types.md#resourcecolor),
backgroundColor?: [ResourceColor](ts-types.md#resourcecolor),
action: () => void;
} | No| Text content, text color, background color, and click callback of the primary button.| -| secondaryButton | {
value: [ResourceStr](ts-types.md#resourcestr),
fontColor?: [ResourceColor](ts-types.md#resourcecolor),
backgroundColor?: [ResourceColor](ts-types.md#resourcecolor),
action: () => void;
} | No | Text content, text color, background color, and click callback of the primary button.| +| secondaryButton | {
value: [ResourceStr](ts-types.md#resourcestr),
fontColor?: [ResourceColor](ts-types.md#resourcecolor),
backgroundColor?: [ResourceColor](ts-types.md#resourcecolor),
action: () => void;
} | No | Text content, text color, background color, and click callback of the secondary button.| | cancel | () => void | No | Callback invoked when the dialog box is closed after the overlay is clicked. | | alignment | [DialogAlignment](#dialogalignment) | No | Alignment mode of the dialog box in the vertical direction.
Default value: **DialogAlignment.Default**| | offset | [Offset](ts-types.md#offset) | No | Offset of the dialog box relative to the alignment position.| diff --git a/en/application-dev/reference/arkui-ts/ts-methods-textpicker-dialog.md b/en/application-dev/reference/arkui-ts/ts-methods-textpicker-dialog.md index c4eb8a23c9fa6473b7c20eb31277ccca64feb4d6..d7f72416274ed1afe326857b10edbf6acd6cdb9f 100644 --- a/en/application-dev/reference/arkui-ts/ts-methods-textpicker-dialog.md +++ b/en/application-dev/reference/arkui-ts/ts-methods-textpicker-dialog.md @@ -22,11 +22,12 @@ Shows a text picker in the given settings. | -------- | -------- | -------- | -------- | | range | string[] \| [Resource](ts-types.md#resource)\|[TextPickerRangeContent](ts-basic-components-textpicker.md#textpickerrangecontent10)[]10+ | Yes| Data selection range of the picker. This parameter cannot be set to an empty array. If set to an empty array, it will not be displayed.
**NOTE**
The Resource type supports only [strarray.json](../../quick-start/resource-categories-and-access.md#resource-group-subdirectories).| | selected | number | No| Index of the selected item.
Default value: **0**| -| value | string | No | Text of the selected item. This parameter does not take effect when the **selected** parameter is set. If the value is not within the range, the first item in the range is used instead.| +| value | string | No | Text of the selected item. This parameter does not take effect when the **selected** parameter is set. If the value is not within the range, the first item in the range is used instead.
**NOTE**
This parameter works only when the picker contains text only. | | defaultPickerItemHeight | number \| string | No| Height of the picker item.| | disappearTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width for the top and bottom items.
Default value:
{
color: '#ff182431',
font: {
size: '14fp',
weight: FontWeight.Regular
}
} | | textStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width of all items except the top, bottom, and selected items.
Default value:
{
color: '#ff182431',
font: {
size: '16fp',
weight: FontWeight.Regular
}
} | | selectedTextStyle10+ | [PickerTextStyle](ts-basic-components-datepicker.md#pickertextstyle10) | No| Font color, font size, and font width of the selected item.
Default value:
{
color: '#ff007dff',
font: {
size: '20vp',
weight: FontWeight.Medium
}
} | +| canLoop10+ | boolean | No| Whether to support scroll looping. The value **true** means to support scroll looping, and **false** means the opposite.
Default value: **true**| | onAccept | (value: [TextPickerResult](#textpickerresult)) => void | No| Callback invoked when the OK button in the dialog box is clicked.| | onCancel | () => void | No| Callback invoked when the Cancel button in the dialog box is clicked.| | onChange | (value: [TextPickerResult](#textpickerresult)) => void | No| Callback invoked when the selected item changes.| @@ -57,6 +58,9 @@ struct TextPickerDialogExample { TextPickerDialog.show({ range: this.fruits, selected: this.select, + disappearTextStyle: {color: Color.Red, font: {size: 15, weight: FontWeight.Lighter}}, + textStyle: {color: Color.Black, font: {size: 20, weight: FontWeight.Normal}}, + selectedTextStyle: {color: Color.Blue, font: {size: 30, weight: FontWeight.Bolder}}, onAccept: (value: TextPickerResult) => { // Set select to the index of the item selected when the OK button is touched. In this way, when the text picker dialog box is displayed again, the selected item is the one last confirmed. this.select = value.index diff --git a/en/application-dev/reference/arkui-ts/ts-universal-attributes-accessibility.md b/en/application-dev/reference/arkui-ts/ts-universal-attributes-accessibility.md index 6f7f0a960d436ee2606ef4c0d8e8ac315a2dcf36..da8f863359f832d07123f996d4a810cd8ac71b8e 100644 --- a/en/application-dev/reference/arkui-ts/ts-universal-attributes-accessibility.md +++ b/en/application-dev/reference/arkui-ts/ts-universal-attributes-accessibility.md @@ -11,9 +11,9 @@ You can set accessibility attributes and events for components. | Name| Type| Description| | -------- | -------- | -------- | | accessibilityGroup | boolean | Accessibility group. If this attribute is set to **true**, the component and all its child components form an entire selectable component, and the accessibility service will no longer be available for the content of its child components.
Default value: **false**| -| accessibilityText | string | Accessibility text. If a component does not contain text information, it will not be read when the component is selected by the screen reader. In this case, the screen reader user cannot know which component is selected. To solve this problem, you can set this attribute for components without text information. When the component is selected by the screen reader, the specified accessibility text will be read, informing the user which component is selected.
**NOTE**
If a component with this attribute set contains text information, only the accessibility text will be read.
If a component with its **accessibilityGroup** attribute set to **true** does not have **accessibilityText** set and does not contain text information, text concatenation will be performed on its child components (depth first).| -| accessibilityDescription | string | Accessibility description. You can specify further explanation of the current component, for example, possible operation consequences, especially those that cannot be learned from component attributes and accessibility text. You can set a detailed description text for the attribute of the component to help users understand the operation to be performed. If a component contains both text information and the accessibility description, the text is read first and then the accessibility description, when the component is selected.| -| accessibilityLevel | string | Accessibility importance, which is used to decide whether a component can be identified by the accessibility service.
The options are as follows:
**"auto"**: The value is converted to **"yes"** or **"no"** based on the component.
**"yes"**: The current component is selectable for the accessibility service.
**"no"**: The current component is not selectable for the accessibility service.
**"no-hide-descendants"**: The current component and all its child components are not selectable for the accessibility service.
**Default value**: **"auto"**
**NOTE**
When the **accessibilityLevel** attribute of the following components is set to **"auto"**, they are selectable for the accessibility service: Checkbox, CheckboxGroup, Gauge, Marquee, MenuItem, MenuItemGroup, Menu, Navigation, DatePicker, Progress, Radio, Rating, ScrollBar, Select, Slider, Stepper, Text, TextClock, TextPicker, TextTimer, TimePicker, Toggle, Web. | +| accessibilityText | string | Accessibility text. If a component does not contain text information, it will not be read when the component is selected by the screen reader. In this case, the screen reader user cannot know which component is selected. To solve this problem, you can set this attribute for components without text information. When the component is selected by the screen reader, the specified accessibility text will be read, informing the user which component is selected.
Default value: **""**
**NOTE**
If a component with this attribute set contains text information, only the accessibility text will be read.
If a component with its **accessibilityGroup** attribute set to **true** does not have **accessibilityText** set and does not contain text information, text concatenation will be performed on its child components (depth first).| +| accessibilityDescription | string | Accessibility description. You can specify further explanation of the current component, for example, possible operation consequences, especially those that cannot be learned from component attributes and accessibility text. If a component contains both text information and the accessibility description, the text is read first and then the accessibility description, when the component is selected.
Default value: **""**| +| accessibilityLevel | string | Accessibility importance, which is used to decide whether a component can be identified by the accessibility service.
The options are as follows:
**"auto"**: The value is converted to **"yes"** or **"no"** based on the component.
**"yes"**: The current component is selectable for the accessibility service.
**"no"**: The current component is not selectable for the accessibility service.
**"no-hide-descendants"**: The current component and all its child components are not selectable for the accessibility service.
**Default value**: **"auto"**
**NOTE**
When the **accessibilityLevel** attribute of the following components is set to **"auto"**, they are selectable for the accessibility service: Checkbox, CheckboxGroup, Gauge, Marquee, MenuItem, MenuItemGroup, Menu, Navigation, DatePicker, Progress, Radio, Rating, ScrollBar, Select, Slider, Stepper, Text, TextClock, TextPicker, TextTimer, TimePicker, Toggle, Web.| ## Example diff --git a/en/application-dev/reference/arkui-ts/ts-universal-component-visible-area-change-event.md b/en/application-dev/reference/arkui-ts/ts-universal-component-visible-area-change-event.md index 1d34a1ae15448105d23e77989c031daf50ace78e..142cce8d875f6ff7ca2f5248e3450061376fe4f9 100644 --- a/en/application-dev/reference/arkui-ts/ts-universal-component-visible-area-change-event.md +++ b/en/application-dev/reference/arkui-ts/ts-universal-component-visible-area-change-event.md @@ -11,7 +11,7 @@ The visible area change event of a component refers to the change in the visual | Name | Description | | ---------------------------------------- | ---------------------------------------- | -| onVisibleAreaChange(ratios: Array\, event: (isVisible: boolean, currentRatio: number) => void) | Called when the visual area of the component changes.
- **ratios**: threshold array. Each threshold represents a ratio of the component's visible area (that is, the area of the component that is visible on screen) to the component's total area. This callback is invoked when the ratio of the component's visible area to its total area is greater than or less than the threshold. The value range of the threshold is [0.0, 1.0]. If the threshold set exceeds this range, the value **0.0** or **1.0** will be used.
- **isVisible**: indicates whether the ratio of the component's visible area to its total area is greater than the threshold. The value **true** means that the ratio is greater than the threshold, and **false** means that the ratio is less than the threshold.
- **currentRatio**: ratio of the component's visible area to its total area when this callback is invoked.| +| onVisibleAreaChange(ratios: Array\, event: (isVisible: boolean, currentRatio: number) => void) | Called when the visual area of the component changes.
- **ratios**: threshold array. Each threshold represents a ratio of the component's visible area (that is, the area of the component that is visible on screen) to the component's total area. This callback is invoked when the ratio of the component's visible area to its total area is greater than or less than the threshold. The value range of the threshold is [0.0, 1.0]. If the threshold set exceeds this range, the value **0.0** or **1.0** will be used.
- **isVisible**: whether the ratio of the component's visible area to its total area is greater than the threshold. The value **true** means that the ratio is greater than the threshold, and **false** means that the ratio is less than the threshold.
- **currentRatio**: ratio of the component's visible area to its total area when this callback is invoked.
**NOTE**
This API applies only to the scenario where the component layout area exceeds or is not within the current screen display area. It does not apply to the scenario where the area becomes invisible due to component stacking or the visible area exceeds the allowed range as a result of calling transformation APIs such as **offset** or **translate**.| ## Example @@ -98,7 +98,7 @@ struct ScrollExample { .scrollable(ScrollDirection.Vertical) .scrollBar(BarState.On) .scrollBarColor(Color.Gray) - .scrollBarWidth(30) + .scrollBarWidth(10) .onScroll((xOffset: number, yOffset: number) => { console.info(xOffset + ' ' + yOffset) }) diff --git a/en/application-dev/reference/errorcodes/errorcode-resource-manager.md b/en/application-dev/reference/errorcodes/errorcode-resource-manager.md index 0087cce7e7069ed7efcab185e3c51be883dee13e..23d0479485e3628c0a1d22ac41ec3b1157c7d11a 100644 --- a/en/application-dev/reference/errorcodes/errorcode-resource-manager.md +++ b/en/application-dev/reference/errorcodes/errorcode-resource-manager.md @@ -177,3 +177,21 @@ System resources are not loaded to the sandbox path of the application process. **Solution** Check whether the application process contains the sandbox path of system resources. + +## 9001010 Invalid Overlay Path + +**Error Message** + +Overlay resource path is invalid. + +**Description** + +This error code is reported if the specified overlay path is invalid. + +**Possible Causes** + +The path does not exist or is not in the installation path of the application. + +**Solution** + +Check the location of the specified overlay path. diff --git a/en/application-dev/reference/errorcodes/errorcode-webview.md b/en/application-dev/reference/errorcodes/errorcode-webview.md index de75c73269bcad4b4777c237b729543bc871b24d..216adc30e558829714579a2e6bc56ad6d9b02bd4 100644 --- a/en/application-dev/reference/errorcodes/errorcode-webview.md +++ b/en/application-dev/reference/errorcodes/errorcode-webview.md @@ -230,23 +230,23 @@ The related JS database API is not used. 2. If the JS database API is used, find out the failure cause, for example, check whether **databaseAccess** is enabled. -## 17100013 Memory Allocation Failure +## 17100013 Invalid Number of Sockets During Preconnection **Error Message** -New failed, out of memeory. +The number of preconnect sockets is invalid. **Description** -Memory allocation failed due to insufficient memory. +This error code is reported when the number of sockets to be preconnected is invalid. **Possible Causes** -The data to send is too large. +The number of sockets is less than or equal to 0 or greater than 6. **Solution** -Check the length of the data to be sent. +Make sure the specified number of sockets is greater than 0 and less than or equal to 6. ## 17100014 Type and Value Mismatch @@ -257,7 +257,7 @@ The type does not match with the value of the message. **Description** -The type and value of the message do not match. +This error code is reported when the type and value of the message do not match. **Possible Causes** @@ -266,3 +266,22 @@ The value of the obtained message does not match the type of the message. **Solution** Call the API based on the message type to obtain the message value. For example, if the type is **BOOLEAN**, call the **GetBoolean** API to obtain the Boolean value. + + +## 17100015 Memory Allocation Failure + +**Error Message** + +New failed, out of memeory. + +**Description** + +This error code is reported when memory allocation failed due to insufficient memory. + +**Possible Causes** + +The data to send is too large. + +**Solution** + +Check the length of the data to be sent. diff --git a/en/application-dev/reference/syscap-list.md b/en/application-dev/reference/syscap-list.md index 05401cbad764f67867ba93e3714e4c3b3496d107..20db2390b2f28e74e8737a76e821808b6b517866 100644 --- a/en/application-dev/reference/syscap-list.md +++ b/en/application-dev/reference/syscap-list.md @@ -951,10 +951,15 @@ Device security level management | ------- | ------ | ------ | ---- | ---- | ------ | ------------ | ------ | | Yes | No | Yes | Yes | No | Yes | No | No | -## SystemCapability.Security.Huks -Hardware Unique Key (HUK) management +## SystemCapability.Security.Huks.Core +Device key management - core capabilities +| Default | Sports Watch| Smart Watch| Tablet| Head Unit| Smart TV| Smart Vision | Router | +| ------- | ------ | ------ | ---- | ---- | ------ | ------------ | ------ | +| Yes | Yes | Yes | Yes | No | Yes | No | No | +## SystemCapability.Security.Huks.Extension +Device key management - extended capabilities | Default | Sports Watch| Smart Watch| Tablet| Head Unit| Smart TV| Smart Vision | Router | | ------- | ------ | ------ | ---- | ---- | ------ | ------------ | ------ | | Yes | No | Yes | Yes | No | Yes | No | No | diff --git a/en/application-dev/ui/figures/relative-layout.png b/en/application-dev/ui/figures/relative-layout.png index a790ca8d5e78d1f659b61175a4e2d424522dec51..c1e98364d71fe4e6774e80af7be5ef959f9f7d68 100644 Binary files a/en/application-dev/ui/figures/relative-layout.png and b/en/application-dev/ui/figures/relative-layout.png differ diff --git a/en/application-dev/web/web-in-page-app-function-invoking.md b/en/application-dev/web/web-in-page-app-function-invoking.md index 59db2424cf051bcbe9c858c09e8c719939477c49..e5132f18e4a2a2e668233d1da7f8405d6dc611e2 100644 --- a/en/application-dev/web/web-in-page-app-function-invoking.md +++ b/en/application-dev/web/web-in-page-app-function-invoking.md @@ -89,7 +89,7 @@ The following example registers the **test()** function with the frontend page. > **NOTE** > - > If you use [registerJavaScriptProxy()](../reference/apis/js-apis-webview.md#registerjavascriptproxy) to register a function, call **[refresh()]**(../reference/apis/js-apis-webview.md#refresh) for the function to take effect. + > If you use [registerJavaScriptProxy()](../reference/apis/js-apis-webview.md#registerjavascriptproxy) to register a function, call [refresh()](../reference/apis/js-apis-webview.md#refresh) for the function to take effect. - Sample code for invoking application functions on the **index.html** frontend page: @@ -103,7 +103,7 @@ The following example registers the **test()** function with the frontend page.