diff --git a/README.md b/README.md index 9351f7f58964229343c0dbfc3c9875e212a4a54f..a9f000cbfb9135b87307c440d21779f2fc2f07e2 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ This repository stores device and application development documents provided by - master: the latest version. - - OpenHarmony 3.2 Beta5. [Learn more](en/release-notes/OpenHarmony-v3.2-beta5.md) + - OpenHarmony 3.2 Release. [Learn more](en/release-notes/OpenHarmony-v3.2-release.md) - OpenHarmony 3.1 Release. [Learn more](en/release-notes/OpenHarmony-v3.1-release.md) diff --git a/en/application-dev/Readme-EN.md b/en/application-dev/Readme-EN.md index 73bbd2d608562535e3272c1a659bcebbd39b125a..f71b814661e652486bf1a61ee3e7c7dd23dbcf4a 100644 --- a/en/application-dev/Readme-EN.md +++ b/en/application-dev/Readme-EN.md @@ -24,6 +24,12 @@ - [Multi-HAP Usage Rules](quick-start/multi-hap-rules.md) - [Multi-HAP Operation Mechanism and Data Communication Modes](quick-start/multi-hap-principles.md) - [Application Installation and Uninstallation Process](quick-start/application-package-install-uninstall.md) + - Shared Package + - [Shared Package Overview](quick-start/shared-guide.md) + - [HAR](quick-start/har-package.md) + - HSP + - [In-Application HSP Development](quick-start/in-app-hsp.md) + - [Inter-Application HSP Development (for System Applications Only)](quick-start/cross-app-hsp.md) - Application Configuration Files in Stage Model - [Application Configuration File Overview (Stage Model)](quick-start/application-configuration-file-overview-stage.md) - [app.json5 Configuration File](quick-start/app-configuration-file.md) @@ -36,18 +42,44 @@ - [Resource Categories and Access](quick-start/resource-categories-and-access.md) - Learning ArkTS - [Getting Started with ArkTS](quick-start/arkts-get-started.md) - - ArkTS Syntax (Declarative UI) - - [Basic UI Description](quick-start/arkts-basic-ui-description.md) - - State Management - - [Basic Concepts](quick-start/arkts-state-mgmt-concepts.md) - - [State Management with Page-level Variables](quick-start/arkts-state-mgmt-page-level.md) - - [State Management with Application-level Variables](quick-start/arkts-state-mgmt-application-level.md) - - [Dynamic UI Element Building](quick-start/arkts-dynamic-ui-elememt-building.md) - - [Rendering Control](quick-start/arkts-rendering-control.md) - - [Restrictions and Extensions](quick-start/arkts-restrictions-and-extensions.md) + - Basic Syntax + - [Basic Syntax Overview](quick-start/arkts-basic-syntax-overview.md) + - [Declarative UI Description](quick-start/arkts-declarative-ui-description.md) + - Custom Component + - [Creating a Custom Component](quick-start/arkts-create-custom-components.md) + - [Page and Custom Component Lifecycle](quick-start/arkts-page-custom-components-lifecycle.md) + - [\@Builder: Custom Builder Function](quick-start/arkts-builder.md) + - [\@BuilderParam: @Builder Function Reference](quick-start/arkts-builderparam.md) + - [\@Styles: Definition of Resusable Styles](quick-start/arkts-style.md) + - [\@Extend: Extension of Built-in Components](quick-start/arkts-extend.md) + - [stateStyles: Polymorphic Style](quick-start/arkts-statestyles.md) + - State Management + - [State Management Overview](quick-start/arkts-state-management-overview.md) + - Component State Management + - [\@State: State Owned by Component](quick-start/arkts-state.md) + - [\@Prop: One-Way Synchronization from Parent to Child Components](quick-start/arkts-prop.md) + - [\@Link: Two-Way Synchronization Between Parent and Child Components](quick-start/arkts-link.md) + - [\@Provide and \@Consume: Two-Way Synchronization with Descendant Components](quick-start/arkts-provide-and-consume.md) + - [\@Observed and \@ObjectLink: Observing Attribute Changes in Nested Class Objects](quick-start/arkts-observed-and-objectlink.md) + - Application State Management + - [Application State Management Overview](quick-start/arkts-application-state-management-overview.md) + - [LocalStorage: UI State Storage](quick-start/arkts-localstorage.md) + - [AppStorage: Application-wide UI State Storage](quick-start/arkts-appstorage.md) + - [PersistentStorage: Application State Persistence](quick-start/arkts-persiststorage.md) + - [Environment: Device Environment Query](quick-start/arkts-environment.md) + - Other State Management Features + - [Overview of Other State Management Features](quick-start/arkts-other-state-mgmt-functions-overview.md) + - [\@Watch: Getting Notified of State Variable Changes](quick-start/arkts-watch.md) + - [$$ Syntax: Two-Way Synchronization of Built-in Components](quick-start/arkts-two-way-sync.md) + - Rendering Control + - [Rendering Control Overview](quick-start/arkts-rendering-control-overview.md) + - [if/else: Conditional Rendering](quick-start/arkts-rendering-control-ifelse.md) + - [ForEach: Rendering of Repeated Content](quick-start/arkts-rendering-control-foreach.md) + - [LazyForEach: Lazy Data Loading](quick-start/arkts-rendering-control-lazyforeach.md) - Development - [Application Models](application-models/Readme-EN.md) - [UI Development](ui/Readme-EN.md) + - [Web](web/Readme-EN.md) - [Notification](notification/Readme-EN.md) - [Window Manager](windowmanager/Readme-EN.md) - [WebGL](webgl/Readme-EN.md) @@ -81,8 +113,10 @@ - [ArkTS and JS APIs](reference/apis/Readme-EN.md) - [Error Codes](reference/errorcodes/Readme-EN.md) - Native APIs + - [Native APIs](reference/native-apis/Readme-EN.md) - [Standard Libraries](reference/native-lib/third_party_libc/musl.md) - [Node_API](reference/native-lib/third_party_napi/napi.md) - [FAQs](faqs/Readme-EN.md) - Contribution - [How to Contribute](../contribute/documentation-contribution.md) + \ No newline at end of file diff --git a/en/application-dev/application-models/extensionability-overview.md b/en/application-dev/application-models/extensionability-overview.md index a287fe9ac7a590bb8675a0ae0f459463ade4ff1b..d176b2d5322b215ab3d730b59cfc5a8e1f6dfb99 100644 --- a/en/application-dev/application-models/extensionability-overview.md +++ b/en/application-dev/application-models/extensionability-overview.md @@ -25,7 +25,8 @@ An [ExtensionAbilityType](../reference/apis/js-apis-bundleManager.md#extensionab - [EnterpriseAdminExtensionAbility](../reference/apis/js-apis-EnterpriseAdminExtensionAbility.md): ExtensionAbility component of the enterprise_admin type, which provides APIs for processing enterprise management events, such as application installation events on devices and events indicating too many incorrect screen-lock password attempts. -> **NOTE**
+> **NOTE** +> > 1. Third-party applications cannot implement ServiceExtensionAbility, DataShareExtensionAbility, StaticSubscriberExtensionAbility, or WindowExtensionAbility. > > 2. To implement transaction processing in the background for a third-party application, use background tasks rather than ServiceExtensionAbility. For details, see [Background Task](../task-management/background-task-overview.md). @@ -45,7 +46,7 @@ The following uses [InputMethodExtensionAbility](../reference/apis/js-apis-input ## Implementing ExtensionAbility of the Specified Type -The following uses [FormExtensionAbility](../reference/apis/js-apis-app-form-formExtensionAbility.md) as an example. The widget framework provides the base class [FormExtensionAbility](../reference/apis/js-apis-app-form-formExtensionAbility.md). You derive this base class to create your own class (such as **MyFormExtensionAbility**), implement the callbacks, such as **onCreate()** and **onUpdateForm()**, to provide specific widget functionalities. For details, see [FormExtensionAbility](Widget-development-stage.md). +The following uses [FormExtensionAbility](../reference/apis/js-apis-app-form-formExtensionAbility.md) as an example. The widget framework provides the base class [FormExtensionAbility](../reference/apis/js-apis-app-form-formExtensionAbility.md). You derive this base class to create your own class (such as **MyFormExtensionAbility**), implement the callbacks, such as **onCreate()** and **onUpdateForm()**, to provide specific widget functionalities. For details, see [FormExtensionAbility](service-widget-overview.md). You do not need to care when to add or delete a widget. The lifecycle of the FormExtensionAbility instance and the lifecycle of the ExtensionAbility process where the FormExtensionAbility instance is located are scheduled and managed by FormManagerService. @@ -63,3 +64,5 @@ You do not need to care when to add or delete a widget. The lifecycle of the For > - The two FormExtensionAbility components run in an independent process. > > - The two ImeExtensionAbility components run in an independent process. + + \ No newline at end of file diff --git a/en/application-dev/connectivity/Readme-EN.md b/en/application-dev/connectivity/Readme-EN.md index 7176cb8fb438cbe8beec5b36bdd290c0b01bbd1f..59df854e8a37289cc9dcf55ed2f7d8110a7c84d0 100755 --- a/en/application-dev/connectivity/Readme-EN.md +++ b/en/application-dev/connectivity/Readme-EN.md @@ -9,6 +9,7 @@ - [Network Sharing](net-sharing.md) - [Ethernet Connection](net-ethernet.md) - [Network Connection Management](net-connection-manager.md) + - [mDNS Management](net-mdns.md) - IPC & RPC - [IPC & RPC Overview](ipc-rpc-overview.md) - [IPC & RPC Development](ipc-rpc-development-guideline.md) diff --git a/en/application-dev/connectivity/net-mdns.md b/en/application-dev/connectivity/net-mdns.md new file mode 100644 index 0000000000000000000000000000000000000000..16aa29609d0826388b244a7daebbcb1f849ed27e --- /dev/null +++ b/en/application-dev/connectivity/net-mdns.md @@ -0,0 +1,156 @@ +# MDNS Management + +## Introduction + +Multicast DNS (mDNS) provides functions such as adding, removing, discovering, and resolving local services on a LAN. +- Local service: a service provider on a LAN, for example, a printer or scanner. + +Typical MDNS management scenarios include: + +- Managing local services on a LAN, such as adding, removing, and resolving local services. +- Discovering local services and listening to the status changes of local services of the specified type through the **DiscoveryService** object. + +> **NOTE** +> To maximize the application running efficiency, most API calls are called asynchronously in callback or promise mode. The following code examples use the callback mode. For details about the APIs, see [mDNS Management](../reference/apis/js-apis-net-mdns.md). + +The following describes the development procedure specific to each application scenario. + +## Available APIs + +For the complete list of APIs and example code, see [mDNS Management](../reference/apis/js-apis-net-mdns.md). + +| Type| API| Description| +| ---- | ---- | ---- | +| ohos.net.mdns | addLocalService(context: Context, serviceInfo: LocalServiceInfo, callback: AsyncCallback\): void | Adds an mDNS service. This API uses an asynchronous callback to return the result.| +| ohos.net.mdns | removeLocalService(context: Context, serviceInfo: LocalServiceInfo, callback: AsyncCallback\): void | Removes an mDNS service. This API uses an asynchronous callback to return the result.| +| ohos.net.mdns | createDiscoveryService(context: Context, serviceType: string): DiscoveryService | Creates a **DiscoveryService** object, which is used to discover mDNS services of the specified type.| +| ohos.net.mdns | resolveLocalService(context: Context, serviceInfo: LocalServiceInfo, callback: AsyncCallback\): void | Resolves an mDNS service. This API uses an asynchronous callback to return the result.| +| ohos.net.mdns.DiscoveryService | startSearchingMDNS(): void | Searches for mDNS services on the LAN.| +| ohos.net.mdns.DiscoveryService | stopSearchingMDNS(): void | Stops searching for mDNS services on the LAN.| +| ohos.net.mdns.DiscoveryService | on(type: 'discoveryStart', callback: Callback<{serviceInfo: LocalServiceInfo, errorCode?: MdnsError}>): void | Enables listening for **discoveryStart** events.| +| ohos.net.mdns.DiscoveryService | on(type: 'discoveryStop', callback: Callback<{serviceInfo: LocalServiceInfo, errorCode?: MdnsError}>): void | Enables listening for **discoveryStop** events.| +| ohos.net.mdns.DiscoveryService | on(type: 'serviceFound', callback: Callback\): void | Enables listening for **serviceFound** events.| +| ohos.net.mdns.DiscoveryService | on(type: 'serviceLost', callback: Callback\): void | Enables listening for **serviceLost** events.| + +## Managing Local Services + +1. Connect the device to the Wi-Fi network. +2. Import the **mdns** namespace from **@ohos.net.mdns**. +3. Call **addLocalService** to add a local service. +4. (Optional) Call **resolveLocalService** to resolve the local service for the IP address of the local network. +5. Call **removeLocalService** to remove the local service. + +```js +// Import the mdns namespace from @ohos.net.mdns. +import mdns from '@ohos.net.mdns' + +// Obtain the context of the FA model. +import featureAbility from '@ohos.ability.featureAbility'; +let context = featureAbility.getContext(); + +// Obtain the context of the stage model. +import UIAbility from '@ohos.app.ability.UIAbility'; +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage){ + globalThis.context = this.context; + } +} +let context = globalThis.context; + +// Create a LocalService object. +let localServiceInfo = { + serviceType: "_print._tcp", + serviceName: "servicename", + port: 5555, + host: { + address: "10.14.**.***", + }, + serviceAttribute: [{ + key: "111", + value: [1] + }] +} + +// Call addLocalService to add a local service. +mdns.addLocalService(context, localServiceInfo, function (error, data) { + console.log(JSON.stringify(error)); + console.log(JSON.stringify(data)); +}); + +// (Optional) Call resolveLocalService to resolve the local service. +mdns.resolveLocalService(context, localServiceInfo, function (error, data) { + console.log(JSON.stringify(error)); + console.log(JSON.stringify(data)); +}); + +// Call removeLocalService to remove the local service. +mdns.removeLocalService(context, localServiceInfo, function (error, data) { + console.log(JSON.stringify(error)); + console.log(JSON.stringify(data)); +}); +``` + +## Discovering Local Services + +1. Connect the device to the Wi-Fi network. +2. Import the **mdns** namespace from **@ohos.net.mdns**. +3. Create a **DiscoveryService** object, which is used to discover mDNS services of the specified type. +4. Subscribe to mDNS service discovery status changes. +5. Enable discovery of mDNS services on the LAN. +6. Stop searching for mDNS services on the LAN. + +```js +// Import the mdns namespace from @ohos.net.mdns. +import mdns from '@ohos.net.mdns' + +// Obtain the context of the FA model. +import featureAbility from '@ohos.ability.featureAbility'; +let context = featureAbility.getContext(); + +// Obtain the context of the stage model. +import UIAbility from '@ohos.app.ability.UIAbility'; +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage){ + globalThis.context = this.context; + } +} +let context = globalThis.context; + +// Create a LocalService object. +let localServiceInfo = { + serviceType: "_print._tcp", + serviceName: "servicename", + port: 5555, + host: { + address: "10.14.**.***", + }, + serviceAttribute: [{ + key: "111", + value: [1] + }] +} + +// Create a DiscoveryService object, which is used to discover mDNS services of the specified type. +let serviceType = "_print._tcp"; +let discoveryService = mdns.createDiscoveryService(context, serviceType); + +// Subscribe to mDNS service discovery status changes. +discoveryService.on('discoveryStart', (data) => { + console.log(JSON.stringify(data)); +}); +discoveryService.on('discoveryStop', (data) => { + console.log(JSON.stringify(data)); +}); +discoveryService.on('serviceFound', (data) => { + console.log(JSON.stringify(data)); +}); +discoveryService.on('serviceLost', (data) => { + console.log(JSON.stringify(data)); +}); + +// Enable discovery of mDNS services on the LAN. +discoveryService.startSearchingMDNS(); + +// Stop searching for mDNS services on the LAN. +discoveryService.stopSearchingMDNS(); +``` diff --git a/en/application-dev/connectivity/net-mgmt-overview.md b/en/application-dev/connectivity/net-mgmt-overview.md index 0ad30c35cc9b4d5e90b2c8fe90cac7ca2e413a57..043d41768f89dd851839eae893b7ba4409395f5e 100644 --- a/en/application-dev/connectivity/net-mgmt-overview.md +++ b/en/application-dev/connectivity/net-mgmt-overview.md @@ -2,13 +2,14 @@ Network management functions include: -- [HTTP data request](http-request.md): Initiates a data request through HTTP. -- [WebSocket connection](websocket-connection.md): Establishes a bidirectional connection between the server and client through WebSocket. -- [Socket connection](socket-connection.md): Transmits data through Socket. -- [Network policy management](net-policy-management.md): Restricts network capabilities by setting network policies, including cellular network policy, sleep/power-saving mode policy, and background network policy, and resets network policies as needed. -- [Network sharing](net-sharing.md): Shares a device's Internet connection with other connected devices by means of Wi-Fi hotspot, Bluetooth, and USB sharing, and queries the network sharing state and shared mobile data volume. -- [Ethernet connection](net-ethernet.md): Provides wired network capabilities, which allow you to set the IP address, subnet mask, gateway, and Domain Name System (DNS) server of a wired network. -- [Network connection management](net-connection-manager.md): Provides basic network management capabilities, including management of Wi-Fi/cellular/Ethernet connection priorities, network quality evaluation, subscription to network connection status changes, query of network connection information, and DNS resolution. +- [HTTP data request](http-request.md): initiates a data request through HTTP. +- [WebSocket connection](websocket-connection.md): establishes a bidirectional connection between the server and client through WebSocket. +- [Socket connection](socket-connection.md): transmits data through Socket. +- [Network policy management](net-policy-management.md): restricts network capabilities by setting network policies, including cellular network policy, sleep/power-saving mode policy, and background network policy, and resets network policies as needed. +- [Network sharing](net-sharing.md): shares a device's Internet connection with other connected devices by means of Wi-Fi hotspot, Bluetooth, and USB sharing, and queries the network sharing state and shared mobile data volume. +- [Ethernet connection](net-ethernet.md): provides wired network capabilities, which allow you to set the IP address, subnet mask, gateway, and Domain Name System (DNS) server of a wired network. +- [Network connection management](net-connection-manager.md): provides basic network management capabilities, including management of Wi-Fi/cellular/Ethernet connection priorities, network quality evaluation, subscription to network connection status changes, query of network connection information, and DNS resolution. +- [mDNS management](net-mdns.md): provides Multicast DNS (mDNS) management capabilities, such as adding, removing, discovering, and resolving local services on a LAN. ## Constraints diff --git a/en/application-dev/database/Readme-EN.md b/en/application-dev/database/Readme-EN.md index b397b5b38682c9910724ea70e4759fe9a9aaf06e..77e1d8f9738d949ce9b0f0396bf66f99b9bf924e 100644 --- a/en/application-dev/database/Readme-EN.md +++ b/en/application-dev/database/Readme-EN.md @@ -5,7 +5,7 @@ - [Overview of Application Data Persistence](app-data-persistence-overview.md) - [Persisting Preferences Data](data-persistence-by-preferences.md) - [Persisting KV Store Data](data-persistence-by-kv-store.md) - - [Persisting RDB Store Data] (data-persistence-by-rdb-store.md) + - [Persisting RDB Store Data](data-persistence-by-rdb-store.md) - Distributed Application Data Synchronization - [Distributed Application Data Synchronization Overview](sync-app-data-across-devices-overview.md) - [Cross-Device Synchronization of KV Stores](data-sync-of-kv-store.md) @@ -16,7 +16,7 @@ - [Database Backup and Restoration](data-backup-and-restore.md) - [Database Encryption](data-encryption.md) - [Access Control by Device and Data Level](access-control-by-device-and-data-level.md) -- Cross-Application Data Sharing (Available Only for System Applications) +- Cross-Application Data Sharing (for System Applications Only) - [Cross-Application Data Sharing Overview](share-device-data-across-apps-overview.md) - [Sharing Data Using DataShareExtensionAbility](share-data-by-datashareextensionability.md) - [Sharing Data in Silent Access](share-data-by-silent-access.md) diff --git a/en/application-dev/database/data-persistence-by-kv-store.md b/en/application-dev/database/data-persistence-by-kv-store.md index 358661e83d952349220a45c0d8ac065f422e3f70..804fb6b12764b95cec9566bdc165234284d32a8d 100644 --- a/en/application-dev/database/data-persistence-by-kv-store.md +++ b/en/application-dev/database/data-persistence-by-kv-store.md @@ -21,22 +21,24 @@ The key-value (KV) database stores data in the form of KV pairs. You can use KV The following table lists the APIs used for KV data persistence. Most of the APIs are executed asynchronously, using a callback or promise to return the result. The following table uses the callback-based APIs as an example. For more information about the APIs, see [Distributed KV Store](../reference/apis/js-apis-distributedKVStore.md). -| API| Description| +| API| Description| | -------- | -------- | -| createKVManager(config: KVManagerConfig): KVManager | Creates a **KvManager** instance to manage database objects.| -| getKVStore<T>(storeId: string, options: Options, callback: AsyncCallback<T>): void | Creates and obtains a KV store of the specified type.| -| put(key: string, value: Uint8Array\|string\|number\|boolean, callback: AsyncCallback<void>): void | Adds a KV pair of the specified type to this KV store.| -| get(key: string, callback: AsyncCallback<Uint8Array\|string\|boolean\|number>): void | Obtains the value of the specified key.| -| delete(key: string, callback: AsyncCallback<void>): void | Deletes a KV pair based on the specified key.| +| createKVManager(config: KVManagerConfig): KVManager | Creates a **KvManager** instance to manage database objects.| +| getKVStore<T>(storeId: string, options: Options, callback: AsyncCallback<T>): void | Creates and obtains a KV store of the specified type.| +| put(key: string, value: Uint8Array\|string\|number\|boolean, callback: AsyncCallback<void>): void | Adds a KV pair of the specified type to this KV store.| +| get(key: string, callback: AsyncCallback<Uint8Array\|string\|boolean\|number>): void | Obtains the value of the specified key.| +| delete(key: string, callback: AsyncCallback<void>): void | Deletes a KV pair based on the specified key.| ## How to Develop -1. Create a **KvManager** instance to manage database objects. Example: +1. Create a **KvManager** instance to manage database objects. + + Example: Stage model: - + ```js // Import the module. import distributedKVStore from '@ohos.data.distributedKVStore'; @@ -67,7 +69,7 @@ The following table lists the APIs used for KV data persistence. Most of the API FA model: - + ```js // Import the module. import distributedKVStore from '@ohos.data.distributedKVStore'; @@ -90,8 +92,10 @@ The following table lists the APIs used for KV data persistence. Most of the API } ``` -2. Create and obtain a KV store. Example: - +2. Create and obtain a KV store. + + Example: + ```js try { const options = { @@ -116,8 +120,10 @@ The following table lists the APIs used for KV data persistence. Most of the API } ``` -3. Use **put()** to add data to the KV store. Example: - +3. Use **put()** to add data to the KV store. + + Example: + ```js const KEY_TEST_STRING_ELEMENT = 'key_test_string'; const VALUE_TEST_STRING_ELEMENT = 'value_test_string'; @@ -138,8 +144,10 @@ The following table lists the APIs used for KV data persistence. Most of the API > > The **put()** method adds a KV pair if the specified key does not exists and changes the value if the the specified key already exists. -4. Use **get()** to obtain the value of a key. Example: - +4. Use **get()** to obtain the value of a key. + + Example: + ```js const KEY_TEST_STRING_ELEMENT = 'key_test_string'; const VALUE_TEST_STRING_ELEMENT = 'value_test_string'; @@ -163,8 +171,10 @@ The following table lists the APIs used for KV data persistence. Most of the API } ``` -5. Use **delete()** to delete the data of the specified key. Example: - +5. Use **delete()** to delete the data of the specified key. + + Example: + ```js const KEY_TEST_STRING_ELEMENT = 'key_test_string'; const VALUE_TEST_STRING_ELEMENT = 'value_test_string'; diff --git a/en/application-dev/database/data-persistence-by-preferences.md b/en/application-dev/database/data-persistence-by-preferences.md index a0c4aafbae9314363b44cd99e3abc563a21d2abe..a8258270a7e2bcfc2305c156ce8e3314d03bb311 100644 --- a/en/application-dev/database/data-persistence-by-preferences.md +++ b/en/application-dev/database/data-persistence-by-preferences.md @@ -10,7 +10,9 @@ The **Preferences** module provides APIs for processing data in the form of key- User applications call **Preference** through the JS interface to read and write data files. You can load the data of a **Preferences** persistence file to a **Preferences** instance. Each file uniquely corresponds to an instance. The system stores the instance in memory through a static container until the instance is removed from the memory or the file is deleted. The following figure illustrates how **Preference** works. - **Figure 1** Preferences working mechanism +The preference persistent file of an application is stored in the application sandbox. You can use **context** to obtain the file path. For details, see [Obtaining the Application Development Path](../application-models/application-context-stage.md#obtaining-the-application-development-path). + +**Figure 1** Preferences working mechanism ![preferences](figures/preferences.jpg) @@ -28,23 +30,23 @@ User applications call **Preference** through the JS interface to read and write The following table lists the APIs used for preferences data persistence. Most of the APIs are executed asynchronously, using a callback or promise to return the result. The following table uses the callback-based APIs as an example. For more information about the APIs, see [User Preferences](../reference/apis/js-apis-data-preferences.md). - | API| Description| +| API| Description| | -------- | -------- | -| getPreferences(context: Context, name: string, callback: AsyncCallback<Preferences>): void | Obtain a **Preferences** instance.| -| put(key: string, value: ValueType, callback: AsyncCallback<void>): void | Writes data to the Preferences instance. You can use **flush()** to persist the **Preferences** instance data.| -| has(key: string, callback: AsyncCallback<boolean>): void | Checks whether the **Preferences** instance contains a KV pair with the given key. The key cannot be empty.| -| get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void | Obtains the value of the specified key. If the value is null or not of the default value type, **defValue** is returned.| -| delete(key: string, callback: AsyncCallback<void>): void | Deletes the KV pair with the given key from the **Preferences** instance.| -| flush(callback: AsyncCallback<void>): void | Flushes the data of this **Preferences** instance to a file for data persistence.| -| on(type: 'change', callback: Callback<{ key : string }>): void | Subscribes to data changes of the specified key. When the value of the specified key is changed and saved by **flush()**, a callback will be invoked to return the new data.| -| off(type: 'change', callback?: Callback<{ key : string }>): void | Unsubscribes from data changes.| -| deletePreferences(context: Context, name: string, callback: AsyncCallback<void>): void | Deletes a **Preferences** instance from memory. If the **Preferences** instance has a persistent file, this API also deletes the persistent file.| +| getPreferences(context: Context, name: string, callback: AsyncCallback<Preferences>): void | Obtain a **Preferences** instance.| +| put(key: string, value: ValueType, callback: AsyncCallback<void>): void | Writes data to the Preferences instance. You can use **flush()** to persist the **Preferences** instance data.| +| has(key: string, callback: AsyncCallback<boolean>): void | Checks whether the **Preferences** instance contains a KV pair with the given key. The key cannot be empty.| +| get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void | Obtains the value of the specified key. If the value is null or not of the default value type, **defValue** is returned.| +| delete(key: string, callback: AsyncCallback<void>): void | Deletes the KV pair with the given key from the **Preferences** instance.| +| flush(callback: AsyncCallback<void>): void | Flushes the data of this **Preferences** instance to a file for data persistence.| +| on(type: 'change', callback: Callback<{ key : string }>): void | Subscribes to data changes of the specified key. When the value of the specified key is changed and saved by **flush()**, a callback will be invoked to return the new data.| +| off(type: 'change', callback?: Callback<{ key : string }>): void | Unsubscribes from data changes.| +| deletePreferences(context: Context, name: string, callback: AsyncCallback<void>): void | Deletes a **Preferences** instance from memory. If the **Preferences** instance has a persistent file, this API also deletes the persistent file.| ## How to Develop 1. Import the **@ohos.data.preferences** module. - + ```js import dataPreferences from '@ohos.data.preferences'; ``` @@ -53,7 +55,7 @@ The following table lists the APIs used for preferences data persistence. Most o Stage model: - + ```js import UIAbility from '@ohos.app.ability.UIAbility'; @@ -77,7 +79,7 @@ The following table lists the APIs used for preferences data persistence. Most o FA model: - + ```js import featureAbility from '@ohos.ability.featureAbility'; @@ -108,7 +110,7 @@ The following table lists the APIs used for preferences data persistence. Most o Example: - + ```js try { preferences.has('startup', function (err, val) { @@ -157,11 +159,11 @@ The following table lists the APIs used for preferences data persistence. Most o } ``` -5. Deletes data. +5. Delete data. Use delete() to delete a KV pair.
Example: - + ```js try { preferences.delete('startup', (err) => { @@ -232,7 +234,7 @@ The following table lists the APIs used for preferences data persistence. Most o Example: - + ```js try { dataPreferences.deletePreferences(this.context, 'mystore', (err, val) => { @@ -245,4 +247,4 @@ The following table lists the APIs used for preferences data persistence. Most o } catch (err) { console.error(`Failed to delete preferences. Code:${err.code}, message:${err.message}`); } - ``` + ``` \ No newline at end of file diff --git a/en/application-dev/database/data-persistence-by-rdb-store.md b/en/application-dev/database/data-persistence-by-rdb-store.md index d74e79a53c78d4bc0cc7cb2cb6dd95ea7a9ba1fb..dd374f26a10e64b62d84f111513f3d3c528017df 100644 --- a/en/application-dev/database/data-persistence-by-rdb-store.md +++ b/en/application-dev/database/data-persistence-by-rdb-store.md @@ -18,7 +18,7 @@ A relational database (RDB) store is used to store data in complex relational mo **RelationalStore** provides APIs for applications to perform data operations. With SQLite as the underlying persistent storage engine, **RelationalStore** provides SQLite database features, including transactions, indexes, views, triggers, foreign keys, parameterized queries, prepared SQL statements, and more. **Figure 1** Working mechanism - + ![relationStore_local](figures/relationStore_local.jpg) @@ -37,15 +37,15 @@ A relational database (RDB) store is used to store data in complex relational mo The following table lists the APIs used for RDB data persistence. Most of the APIs are executed asynchronously, using a callback or promise to return the result. The following table uses the callback-based APIs as an example. For more information about the APIs, see [RDB Store](../reference/apis/js-apis-data-relationalStore.md). -| API| Description| +| API| Description| | -------- | -------- | -| getRdbStore(context: Context, config: StoreConfig, callback: AsyncCallback<RdbStore>): void | Obtains a **RdbStore** instance to implement RDB store operations. You can set **RdbStore** parameters based on actual requirements and use **RdbStore** APIs to perform data operations.| -| executeSql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<void>):void | Executes an SQL statement that contains specified arguments but returns no value.| -| insert(table: string, values: ValuesBucket, callback: AsyncCallback<number>):void | Inserts a row of data into a table.| -| update(values: ValuesBucket, predicates: RdbPredicates, callback: AsyncCallback<number>):void | Updates data in the RDB store based on the specified **RdbPredicates** instance.| -| delete(predicates: RdbPredicates, callback: AsyncCallback<number>):void | Deletes data from the RDB store based on the specified **RdbPredicates** instance.| -| query(predicates: RdbPredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>):void | Queries data in the RDB store based on specified conditions.| -| deleteRdbStore(context: Context, name: string, callback: AsyncCallback<void>): void | Deletes an RDB store.| +| getRdbStore(context: Context, config: StoreConfig, callback: AsyncCallback<RdbStore>): void | Obtains a **RdbStore** instance to implement RDB store operations. You can set **RdbStore** parameters based on actual requirements and use **RdbStore** APIs to perform data operations.| +| executeSql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<void>):void | Executes an SQL statement that contains specified arguments but returns no value.| +| insert(table: string, values: ValuesBucket, callback: AsyncCallback<number>):void | Inserts a row of data into a table.| +| update(values: ValuesBucket, predicates: RdbPredicates, callback: AsyncCallback<number>):void | Updates data in the RDB store based on the specified **RdbPredicates** instance.| +| delete(predicates: RdbPredicates, callback: AsyncCallback<number>):void | Deletes data from the RDB store based on the specified **RdbPredicates** instance.| +| query(predicates: RdbPredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>):void | Queries data in the RDB store based on specified conditions.| +| deleteRdbStore(context: Context, name: string, callback: AsyncCallback<void>): void | Deletes an RDB store.| ## How to Develop @@ -53,7 +53,7 @@ The following table lists the APIs used for RDB data persistence. Most of the AP 1. Obtain an **RdbStore** instance.
Example: Stage model: - + ```js import relationalStore from '@ohos.data.relationalStore'; // Import the module. import UIAbility from '@ohos.app.ability.UIAbility'; @@ -84,7 +84,7 @@ The following table lists the APIs used for RDB data persistence. Most of the AP FA model: - + ```js import relationalStore from '@ohos.data.relationalStore'; // Import the module. import featureAbility from '@ohos.ability.featureAbility'; @@ -119,7 +119,7 @@ The following table lists the APIs used for RDB data persistence. Most of the AP > - When an application calls **getRdbStore()** to obtain an RDB store instance for the first time, the corresponding database file is generated in the application sandbox. If you want to move the files of an RDB store to another place for view, you must also move the temporary files with finename extensions **-wal** or **-shm** in the same directory. Once an application is uninstalled, the database files and temporary files generated by the application on the device are also removed. 2. Use **insert()** to insert data to the RDB store. Example: - + ```js const valueBucket = { 'NAME': 'Lisa', @@ -142,8 +142,10 @@ The following table lists the APIs used for RDB data persistence. Most of the AP 3. Modify or delete data based on the specified **Predicates** instance. - Use **update()** to modify data and **delete()** to delete data. Example: - + Use **update()** to modify data and **delete()** to delete data. + + Example: + ```js // Modify data. const valueBucket = { @@ -176,8 +178,10 @@ The following table lists the APIs used for RDB data persistence. Most of the AP 4. Query data based on the conditions specified by **Predicates**. - Use **query()** to query data. The data obtained is returned in a **ResultSet** object. Example: - + Use **query()** to query data. The data obtained is returned in a **ResultSet** object. + + Example: + ```js let predicates = new relationalStore.RdbPredicates('EMPLOYEE'); predicates.equalTo('NAME', 'Rose'); @@ -197,11 +201,13 @@ The following table lists the APIs used for RDB data persistence. Most of the AP 5. Delete the RDB store. - Use **deleteRdbStore()** to delete the RDB store and related database files. Example: + Use **deleteRdbStore()** to delete the RDB store and related database files. - Stage model: + Example: - + Stage model: + + ```js import UIAbility from '@ohos.app.ability.UIAbility'; @@ -215,12 +221,12 @@ The following table lists the APIs used for RDB data persistence. Most of the AP console.info('Succeeded in deleting RdbStore.'); }); } - } +} ``` FA model: - - + + ```js import featureAbility from '@ohos.ability.featureAbility'; diff --git a/en/application-dev/database/data-sync-of-kv-store.md b/en/application-dev/database/data-sync-of-kv-store.md index f6b2d2c55dca745843d55d37bc3a96166bc3e4ff..e9b4fff51f15ca2339715c626c9e4e4bba7e4d45 100644 --- a/en/application-dev/database/data-sync-of-kv-store.md +++ b/en/application-dev/database/data-sync-of-kv-store.md @@ -68,7 +68,7 @@ When data is added, deleted, or modified, a notification is sent to the subscrib - The KV stores do not support custom conflict resolution policies for applications. -- A maximum of 16 distributed KV stores can be opened simultaneously for an application. +- A maximum of 16 KV stores can be opened simultaneously for an application. - Each KV store supports a maximum of eight callbacks for subscription of data change notifications. @@ -79,19 +79,19 @@ When data is added, deleted, or modified, a notification is sent to the subscrib The following table lists the APIs for cross-device data synchronization of the single KV store. Most of the APIs are executed asynchronously, using a callback or promise to return the result. The following table uses the callback-based APIs as an example. For more information about the APIs, see [Distributed KV Store](../reference/apis/js-apis-distributedKVStore.md). -| API| Description| +| API| Description| | -------- | -------- | -| createKVManager(config: KVManagerConfig): KVManager | Creates a **KvManager** instance to manage database objects.| -| getKVStore<T>(storeId: string, options: Options, callback: AsyncCallback<T>): void | Creates and obtains a KV store of the specified type.| -| put(key: string, value: Uint8Array\|string\|number\|boolean, callback: AsyncCallback<void>): void | Inserts and updates data.| -| on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void | Subscribes to data changes in the KV store.| -| get(key: string, callback: AsyncCallback<boolean \| string \| number \| Uint8Array>): void | Queries the value of the specified key.| -| sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void | Triggers a manual synchronization of the KV store.| +| createKVManager(config: KVManagerConfig): KVManager | Creates a **KvManager** instance to manage database objects.| +| getKVStore<T>(storeId: string, options: Options, callback: AsyncCallback<T>): void | Creates and obtains a KV store of the specified type.| +| put(key: string, value: Uint8Array\|string\|number\|boolean, callback: AsyncCallback<void>): void | Inserts and updates data.| +| on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void | Subscribes to data changes in the KV store.| +| get(key: string, callback: AsyncCallback<boolean \| string \| number \| Uint8Array>): void | Queries the value of the specified key.| +| sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void | Triggers a manual synchronization of the KV store.| ## How to Develop -The following uses a single KV store as an example to describe how to implement cross-device data synchronization. The following describes the development process. +The following uses a single KV store as an example to describe how to implement cross-device data synchronization. The development process is as follows. ![kvStore_development_process](figures/kvStore_development_process.png) @@ -100,7 +100,7 @@ The following uses a single KV store as an example to describe how to implement > The data on a device can be synchronized only to the devices whose data security labels are not higher than the security level of the device. For details, see [Access Control Mechanism in Cross-Device Synchronization](sync-app-data-across-devices-overview.md#access-control-mechanism-in-cross-device-synchronization). 1. Import the module. - + ```js import distributedKVStore from '@ohos.data.distributedKVStore'; ``` @@ -115,7 +115,7 @@ The following uses a single KV store as an example to describe how to implement 1. Create a **kvManagerConfig** object based on the application context. 2. Create a **KvManager** instance. - + ```js // Obtain the context of the stage model. import UIAbility from '@ohos.app.ability.UIAbility'; @@ -152,7 +152,7 @@ The following uses a single KV store as an example to describe how to implement 1. Declare the ID of the distributed KV store to create. 2. Disable the auto synchronization function (**autoSync:false**) to facilitate subsequent verification of the synchronization function. If synchronization is required, call the **sync()** interface. - + ```js try { const options = { @@ -179,7 +179,7 @@ The following uses a single KV store as an example to describe how to implement ``` 5. Subscribe to changes of distributed data. - + ```js try { kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_ALL, (data) => { @@ -195,7 +195,7 @@ The following uses a single KV store as an example to describe how to implement 1. Construct the key and value to be written to the single KV store. 2. Write KV pairs to the single KV store. - + ```js const KEY_TEST_STRING_ELEMENT = 'key_test_string'; const VALUE_TEST_STRING_ELEMENT = 'value_test_string'; @@ -217,7 +217,7 @@ The following uses a single KV store as an example to describe how to implement 1. Construct the key to be queried from the single KV store. 2. Query data from the single KV store. - + ```js const KEY_TEST_STRING_ELEMENT = 'key_test_string'; const VALUE_TEST_STRING_ELEMENT = 'value_test_string'; @@ -249,7 +249,7 @@ The following uses a single KV store as an example to describe how to implement > > If manual synchronization is used, **deviceIds** is obtained by using [devManager.getTrustedDeviceListSync](../reference/apis/js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are all system interfaces and available only to system applications. - + ```js import deviceManager from '@ohos.distributedHardware.deviceManager'; diff --git a/en/application-dev/database/share-data-by-datashareextensionability.md b/en/application-dev/database/share-data-by-datashareextensionability.md index 923cac5257b040d5c3c425f26505648135b5f14f..7f70ab30d4c04c421c1e18032a0da13e590f80a7 100644 --- a/en/application-dev/database/share-data-by-datashareextensionability.md +++ b/en/application-dev/database/share-data-by-datashareextensionability.md @@ -16,7 +16,8 @@ There are two roles in **DataShare**: - Data consumer: accesses the data provided by the provider using [createDataShareHelper()](../reference/apis/js-apis-data-dataShare.md#datasharecreatedatasharehelper). -**Figure 1** Data sharing mechanism +**Figure 1** Data sharing mechanism + ![dataShare](figures/dataShare.jpg) - The **DataShareExtensionAbility** module, as the data provider, implements services related to data sharing between applications. @@ -125,15 +126,15 @@ override the service implementation as required. For example, if the data provid **Table 1** Fields in module.json5 - | Field| Description| Mandatory| + | Field| Description| Mandatory| | -------- | -------- | -------- | - | name | Ability name, corresponding to the **ExtensionAbility** class name derived from **Ability**.| Yes| - | type | Ability type. The value is **dataShare**, indicating the development is based on the **datashare** template.| Yes| - | uri | URI used for communication. It is the unique identifier for the data consumer to connect to the provider.| Yes| - | exported | Whether it is visible to other applications. Data sharing is allowed only when the value is **true**.| Yes| - | readPermission | Permission required for accessing data. If this parameter is not set, the read permission is not verified by default.| No| - | writePermission | Permission required for modifying data. If this parameter is not set, write permission verification is not performed by default.| No| - | metadata | Configuration for silent access, including the **name** and **resource** fields.
The **name** field identifies the configuration, which has a fixed value of **ohos.extension.dataShare**.
The **resource** field has a fixed value of **$profile:data_share_config**, which indicates that the profile name is **data_share_config.json**.| **metadata** is mandatory when the ability launch type is **singleton**. For details about the ability launch type, see **launchType** in the [Internal Structure of the abilities Attribute](../quick-start/module-structure.md#internal-structure-of-the-abilities-attribute).| + | name | Ability name, corresponding to the **ExtensionAbility** class name derived from **Ability**.| Yes| + | type | Ability type. The value is **dataShare**, indicating the development is based on the **datashare** template.| Yes| + | uri | URI used for communication. It is the unique identifier for the data consumer to connect to the provider.| Yes| + | exported | Whether it is visible to other applications. Data sharing is allowed only when the value is **true**.| Yes| + | readPermission | Permission required for accessing data. If this parameter is not set, the read permission is not verified by default.| No| + | writePermission | Permission required for modifying data. If this parameter is not set, write permission verification is not performed by default.| No| + | metadata | Configuration for silent access, including the **name** and **resource** fields.
The **name** field identifies the configuration, which has a fixed value of **ohos.extension.dataShare**.
The **resource** field has a fixed value of **$profile:data_share_config**, which indicates that the profile name is **data_share_config.json**.| **metadata** is mandatory when the ability launch type is **singleton**. For details about the ability launch type, see **launchType** in the [Internal Structure of the abilities Attribute](../quick-start/module-structure.md#internal-structure-of-the-abilities-attribute).| **module.json5 example** diff --git a/en/application-dev/dfx/apprecovery-guidelines.md b/en/application-dev/dfx/apprecovery-guidelines.md index 5c297d3357d83feb0b6c1465f67ec2b085ade7b3..e5e7b5274361a25009d33b694943b59ef2d9d8a1 100644 --- a/en/application-dev/dfx/apprecovery-guidelines.md +++ b/en/application-dev/dfx/apprecovery-guidelines.md @@ -9,7 +9,7 @@ Application recovery helps to restore the application state and save temporary d In API version 9, application recovery is supported only for a single ability of the application developed using the stage model. Application state saving and automatic restart are performed when a JsError occurs. -In API version 10, application recovery is also supported for multiple abilities of the application developed using the stage model. Application state storage and restore are performed when an AppFreeze occurs. If an application is killed in control mode, the application state will be restored upon next startup. +In API version 10, application recovery is applicable to multiple abilities of an application developed using the stage model. Application state storage and restore are performed when an AppFreeze occurs. If an application is killed in control mode, the application state will be restored upon next startup. ## Available APIs @@ -221,3 +221,20 @@ export default class EntryAbility extends Ability { } } ``` + +#### Restart Flag for the Failed Ability + +If the failed ability is restarted again, the [ABILITY_RECOVERY_RESTART](../reference/apis/js-apis-app-ability-wantConstant.md#wantconstantparams) flag will be added as a **parameters** member for the **want** parameter in **onCreate** and its value is **true**. + +```ts +import UIAbility from '@ohos.app.ability.UIAbility'; +import wantConstant from '@ohos.app.ability.wantConstant'; +export default class EntryAbility extends UIAbility { + onCreate(want, launchParam) { + if (want.parameters[wantConstant.Params.ABILITY_RECOVERY_RESTART] != undefined && + want.parameters[wantConstant.Params.ABILITY_RECOVERY_RESTART] == true) { + console.log("This ability need to recovery"); + } + } +} +``` diff --git a/en/application-dev/dfx/errormanager-guidelines.md b/en/application-dev/dfx/errormanager-guidelines.md index 4679cfcfc78893590fe73eab770e49fc68a1a828..8509fff09e51cd31665e80fab6dce0f2472ab08d 100644 --- a/en/application-dev/dfx/errormanager-guidelines.md +++ b/en/application-dev/dfx/errormanager-guidelines.md @@ -23,7 +23,8 @@ When an asynchronous callback is used, the return value can be processed directl | API | Description | | ------------------------------ | ------------------------------------------------------------ | -| onUnhandledException(errMsg: string): void | Called when an application generates an uncaught exception after being registered.| +| onUnhandledException(errMsg: string): void | Called when an uncaught exception is reported after the application is registered.| +| onException?(errObject: Error): void | Called when an application exception is reported to the JavaScript layer after the application is registered.| ### Result Codes for Unregistering an Observer @@ -43,6 +44,13 @@ let registerId = -1; let callback = { onUnhandledException: function (errMsg) { console.log(errMsg); + }, + onException: function (errorObj) { + console.log('onException, name: ', errorObj.name); + console.log('onException, message: ', errorObj.message); + if (typeof(errorObj.stack) === 'string') { + console.log('onException, stack: ', errorObj.stack); + } } } diff --git a/en/application-dev/faqs/Readme-EN.md b/en/application-dev/faqs/Readme-EN.md index 63535a32ae16eca13b03d20b4bce93569e2fe1d0..e76f1f1205949c45dcea65c19878e16cc77b7bf8 100644 --- a/en/application-dev/faqs/Readme-EN.md +++ b/en/application-dev/faqs/Readme-EN.md @@ -2,7 +2,7 @@ - [Programming Languages](faqs-language.md) - [Ability Framework Development](faqs-ability.md) -- [Bundle Management Development](faqs-bundle.md) +- [Resource Manager Development](faqs-globalization.md) - [ArkUI (ArkTS) Development](faqs-ui-ets.md) - [ArkUI Web Component (ArkTS) Development](faqs-web-arkts.md) - [ArkUI (JavaScript) Development](faqs-ui-js.md) @@ -10,12 +10,9 @@ - [Graphics and Image Development](faqs-graphics.md) - [File Management Development](faqs-file-management.md) - [Media Development](faqs-media.md) -- [Network and Connection Development](faqs-connectivity.md) -- [Data Management Development](faqs-data-management.md) -- [Device Management Development](faqs-device-management.md) +- [Network Management Development](faqs-network-management.md) - [DFX Development](faqs-dfx.md) -- [Intl Development](faqs-international.md) - [Native API Usage](faqs-native.md) +- [Startup Development](faqs-startup.md) - [Usage of Third- and Fourth-Party Libraries](faqs-third-party-library.md) - [IDE Usage](faqs-ide.md) -- [Development Board](faqs-development-board.md) \ No newline at end of file diff --git a/en/application-dev/faqs/faqs-connectivity.md b/en/application-dev/faqs/faqs-connectivity.md deleted file mode 100644 index 31e1db2e15e82875427d52a92dd26bcfeb69c34e..0000000000000000000000000000000000000000 --- a/en/application-dev/faqs/faqs-connectivity.md +++ /dev/null @@ -1,33 +0,0 @@ -# Network and Connection Development - - - -## What are the data formats supported by extraData in an HTTP request? - -Applicable to: OpenHarmony SDK 3.2.2.5, stage model of API version 9 - -**extraData** indicates additional data in an HTTP request. It varies depending on the HTTP request method. - -- If the HTTP request uses a POST or PUT method, **extraData** serves as the content of the HTTP request. - -- If the HTTP request uses a GET, OPTIONS, DELETE, TRACE, or CONNECT method, **extraData** serves as a supplement to the HTTP request parameters and will be added to the URL when the request is sent. - -- If you pass in a string object, **extraData** contains the string encoded on your own. - - -## What does error code 28 mean for an HTTP request? - -Applicable to: OpenHarmony SDK 3.2.2.5, stage model of API version 9 - -Error code 28 refers to **CURLE_OPERATION_TIMEDOUT**, which means a cURL operation timeout. For details, see any HTTP status code description available. - -Reference: [Response Codes](../reference/apis/js-apis-http.md#responsecode) and [Curl Error Codes](https://curl.se/libcurl/c/libcurl-errors.html) - - -## What does error code 6 mean for the response of \@ohos.net.http.d.ts? - -Applicable to: OpenHarmony SDK 3.2.3.5 - -Error code 6 indicates a failure to resolve the host in the address. You can ping the URL carried in the request to check whether the host is accessible. - -Reference: [Response Codes](../reference/apis/js-apis-http.md#responsecode) and [Curl Error Codes](https://curl.se/libcurl/c/libcurl-errors.html) diff --git a/en/application-dev/faqs/faqs-data-management.md b/en/application-dev/faqs/faqs-data-management.md deleted file mode 100644 index 47f0b7ce20cd54a1cee4eb521801d4e7ca94e04b..0000000000000000000000000000000000000000 --- a/en/application-dev/faqs/faqs-data-management.md +++ /dev/null @@ -1,76 +0,0 @@ -# Data Management Development - -## How Do I Save PixelMap Data to a Database? - -Applicable to: OpenHarmony SDK 3.2.3.5 - -You can convert a **PixelMap** into an **ArrayBuffer** and save the **ArrayBuffer** to your database. - -Reference: [readPixelsToBuffer](../reference/apis/js-apis-image.md#readpixelstobuffer7-1) - -## How Do I Obtain RDB Store Files? - -Applicable to: OpenHarmony SDK 3.2.3.5, stage model of API version 9 - -Run the hdc_std command to copy the .db, .db-shm, and .db-wal files in **/data/app/el2/100/database/*bundleName*/entry/db/**, and then use the SQLite tool to open the files. - -Example: - -``` - hdc_std file recv /data/app/el2/100/database/com.xxxx.xxxx/entry/db/test.db ./test.db -``` - -## Does the Database Has a Lock Mechanism? - -Applicable to: OpenHarmony SDK 3.2.5.5, stage model of API version 9 - -The distributed data service (DDS), relational database (RDB) store, and preferences provided OpenHarmony have a lock mechanism. You do not need to bother with the lock mechanism during the development. - -## What Is a Transaction in an RDB Store? - -Applicable to: all versions - -When a large number of operations are performed in an RDB store, an unexpected exception may cause a failure of some data operations and loss of certain data. As a result, the application may become abnormal or even crash. - -A transaction is a group of tasks serving as a single logical unit. It eliminates the failure of some of the operations and loss of associated data. - -## What Data Types Does an RDB Store Support? - -Applicable to: OpenHarmony SDK 3.0 or later, stage model of API version 9 - -An RDB store supports data of the number, string, and Boolean types. The number array supports data of the Double, Long, Float, Int, or Int64 type, with a maximum precision of 17 decimal digits. - -## How Do I View Database db Files? - -Applicable to: OpenHarmony SDK 3.2.6.5, stage model of API version 9 - -1. Run the **hdc_std shell** command. - -2. Obtain the absolute path or sandbox path of the database. - -The absolute path is **/data/app/el2//database/**. The default **** is **100**. - -To obtain the sandbox path, run the **ps -ef | grep hapName** command to obtain the process ID of the application. - -The database sandbox path is **/proc//root/data/storage/el2/database/**. - -3. Run the **find ./ -name "\*.db"** command in the absolute path or sandbox path of the database. - -## How Do I Store Long Text Data? - -Applicable to: OpenHarmony SDK 3.2.5.5, API version 9 - -- Preferences support a string of up to 8192 bytes. - -- The KV store supports a value of up to 4 MB. - -Reference: [Preference Overview](../database/database-preference-overview.md) and [Distributed Data Service Overview](../database/database-mdds-overview.md) - -## How Do I Develop DataShare on the Stage Model - -Applicable to: OpenHarmony SDK 3.2.5.5, API version 9 - -The DataShare on the stage model cannot be used with the **DataAbility** for the FA model. The connected server application must be implemented by using **DataShareExtensionAbility**. - -Reference: [DataShare Development](../database/database-datashare-guidelines.md) - diff --git a/en/application-dev/faqs/faqs-development-board.md b/en/application-dev/faqs/faqs-development-board.md deleted file mode 100644 index 0a2a29db5ba68e57e2eee790485ae682ac78b6c0..0000000000000000000000000000000000000000 --- a/en/application-dev/faqs/faqs-development-board.md +++ /dev/null @@ -1,50 +0,0 @@ -# Development Board Usage - -## How do I take screenshots on a development board? - -Applicable to: OpenHarmony SDK 3.2.2.5, stage model of API version 9 - -- Method 1: Click the screenshot button in the Control Panel from the development board UI. The screenshot is displayed in Gallery. - -- Method 2: Run the screenshot script. Connect to the development board to a computer running Windows. Create a text file on the computer, copy the following script content to the file, change the file name extension to **.bat** (the HDC environment variables must be configured in advance), and click **Run**. The screenshot is saved to the same directory as the **.bat** script file. - Example: - - ``` - set filepath=/data/%date:~0,4%%date:~5,2%%date:~8,2%%time:~1,1%%time:~3,2%%time:~6,2%.png - echo %filepath% - : pause - hdc_std shell snapshot_display -f %filepath% - : pause - hdc_std file recv %filepath% . - : pause - ``` - -## How do I adjust Previewer in DevEco Studio so that the preview looks the same as what's displayed on a real RK3568 development board? - -Applicable to: DevEco Studio 3.0.0.991 - -1. Create a profile in Previewer. - - ![en-us_image_0000001361254285](figures/en-us_image_0000001361254285.png) - -2. Set the profile parameters as follows: - - Device type : default - - Resolution: 720\*1280 - - DPI: 240 - -## What should I do if Device Manager incorrectly identifies a development board as FT232R USB UART even when the development board already has a driver installed? - -Possible cause: The USB serial driver of the development version is not installed. - -Solution: Search for **FT232R USB UART**, and download and install the driver. - -## How do I complete authentication when logging in to the development board? - -Applicable to: OpenHarmony SDK 3.2.2.5 - -When connecting to the network that requires authentication, open any web page in the browser to access the authentication page. - -If there is no browser on the development board, you can install the [sample browser application](https://gitee.com/openharmony/app_samples/tree/master/device/Browser). diff --git a/en/application-dev/faqs/faqs-device-management.md b/en/application-dev/faqs/faqs-device-management.md deleted file mode 100644 index ea71edd6c9940437e197be35e60a6638c73ae88d..0000000000000000000000000000000000000000 --- a/en/application-dev/faqs/faqs-device-management.md +++ /dev/null @@ -1,48 +0,0 @@ -# Device Management Development - -## How do I obtain the DPI of a device? - -Applicable to: OpenHarmony 3.2 Beta5, stage model of API version 9 - -Import the **@ohos.display** module and call the **getDefaultDisplaySync** API. - -**Example** - -``` -import display from '@ohos.display'; -let displayClass = null; -try { - displayClass = display.getDefaultDisplaySync(); - console.info('Test densityDPI:' + JSON.stringify(data.densityDPI)); -} catch (exception) { - console.error('Failed to obtain the default display object. Code: ' + JSON.stringify(exception)); -} -``` - -## How do I obtain the type of the device where the application is running? - -Applicable to: OpenHarmony SDK 3.2.2.5, stage model of API version 9 - -Import the **\@ohos.deviceInfo** module and call the **deviceInfo.deviceType** API. - -For details, see [Device Information](../reference/apis/js-apis-device-info.md). - -## How do I obtain the system version of a device? - -Applicable to: OpenHarmony SDK 3.2.5.5, stage model of API version 9 - -Use the **osFullName** attribute of the [deviceInfo](../reference/apis/js-apis-device-info.md) object. - -## How do I obtain the UDID of an OpenHarmony device? - -Applicable to: OpenHarmony SDK3.0, stage model of API version 9 - -- To obtain the UDID of the connected device, run the **hdc shell bm get --udid** command. - -- For details about how to obtain the UDID from code, see [udid](../reference/apis/js-apis-device-info.md). - -## How do I develop a shortcut key function? - -Applicable to: OpenHarmony SDK 3.2.6.5, stage model of API version 9 - -To develop a shortcut key function, use the APIs in [Input Consumer](../reference/apis/js-apis-inputconsumer.md). diff --git a/en/application-dev/faqs/faqs-dfx.md b/en/application-dev/faqs/faqs-dfx.md index 9fc12a1b1c26e109240702cca50e50b77495bdf5..51945bd8d0b9742703696d19fd2cc1f52add112d 100644 --- a/en/application-dev/faqs/faqs-dfx.md +++ b/en/application-dev/faqs/faqs-dfx.md @@ -1,54 +1,27 @@ # DFX Development -## How do I locate the fault when the application crashes? +## How do I flush HiLog information to disks? -Applicable to: OpenHarmony SDK 3.2.5.5 +Applicable to: OpenHarmony 3.2 Beta (API version 9) -1. Locate the crash-related code based on the service log. +**Symptom** -2. View the error information in the crash file, which is located at **/data/log/faultlog/faultlogger/**. +How do I flush HiLog information to disks? -## Why cannot access controls in the UiTest test framework? +**Solution** -Applicable to: OpenHarmony SDK 3.2.5.5 +Run the **hilog -w start -f ckTest -l 1M -n 5 -m zlib -j 11** command. -Check whether **persist.ace.testmode.enabled** is turned on. +The log file is saved in the **/data/log/hilog/** directory. -Run **hdc\_std shell param get persist.ace.testmode.enabled**. +Parameter description: -If the value is **0**, run the **hdc\_std shell param set persist.ace.testmode.enabled 1** to enable the test mode. - - -## Why is private displayed in logs when the format parameter type of HiLog in C++ code is %d or %s? - -When format parameters such as **%d** and **%s** are directly used, the standard system uses **private** to replace the actual data for printing by default to prevent data leakage. To print the actual data, replace **%d** with **%{public}d** or replace **%s** with **%{public}s**. - -## What should I do if the hilog.debug log cannot be printed? - -Applicable to: OpenHarmony SDK 3.2.5.5, stage model of API version 9 - -Run **hdc_std shell hilog -b D** to turn on the debugging switch. - -## Is HiLog or console recommended for log printing? How do I set the domain if HiLog is used? - -Applicable to: OpenHarmony SDK 3.2.2.5 - -You are advised to use the [HiLog](../reference/apis/js-apis-hilog.md) for log printing. For details about how to set the **domain** parameter, see the [Development Guide](../reference/apis/js-apis-hilog.md#hilogisloggable). - -## What is the maximum length of a log record when HiLog is used? Is it configurable? - -Applicable to: OpenHarmony SDK 3.2.2.5 - -The maximum length of a log record is 1,024 characters, and it is not changeable. - -## Can I separate multiple strings by spaces in the tag parameter of the HiLog API? - -Applicable to: OpenHarmony SDK 3.2.6.5, stage model of API version 9 - -No. Separating multiple strings by spaces is not allowed. - -## How do I print real data if HiLog does not contain data labeled by {public}? - -Applicable to: OpenHarmony SDK 3.2.6.5, stage model of API version 9 - -Run **hdc\_std shell hilog -p off** to disable logging of data labeled by {public}. +``` +-**-w**: Starts a log flushing task. **start** means to start the task, and **stop** means to stop the task. +-**-f**: Sets the log file name. +-**-l**: Sets the size of a single log file. The unit can be B, KB, MB, or GB. +-**-n**: Sets the maximum number of log files. When the number of log files exceeds the specified value, the earliest log file will be overwritten. The value range is [2,1000]. +-**-m**: Specifies the log file compression algorithm. +-**-j**: Specifies the task ID. The value ranges from **10** to **0xffffffffff**. +For more details about parameters, run the **hilog --help** command. +``` diff --git a/en/application-dev/faqs/faqs-globalization.md b/en/application-dev/faqs/faqs-globalization.md new file mode 100644 index 0000000000000000000000000000000000000000..b4d06ab98cbb1b24f4f0384ed893126c334ff383 --- /dev/null +++ b/en/application-dev/faqs/faqs-globalization.md @@ -0,0 +1,118 @@ +# Resource Manager Development + +## How do I read an XML file in rawfile and convert the data in it to the string type? + +Applicable to: OpenHarmony 3.2 Beta 5 (API version 9) + +**Solution** + +Call **getRawFileContent** of the **ResourceManager** module to obtain the data in the XML file, and then use **String.fromCharCode** to convert the data to the string type. + +**Sample Code** + +``` +resourceManager.getRawFileContent('test.xml', (error, value) => { + if (error != null) { + console.log("error is " + error); + } else { + let rawFile = value; + let xml = String.fromCharCode.apply(null, rawFile) + } +}); +``` + +**Reference** + +[Resource Manager](../reference/apis/js-apis-resource-manager.md) + +## How do I obtain resources in the stage model? + +Applicable to: OpenHarmony 3.1 Beta 5 (API version 9) + +**Solution** + +The stage model allows an application to obtain a **ResourceManager** object based on **context** and call its resource management APIs without first importing the required bundle. This mode does not apply to the FA model. + +**Sample Code** + +``` +const context = getContext(this) as any +context + .resourceManager + .getString($r('app.string.entry_desc').id) + .then(value => { + this.message = value.toString() +}) +``` + +## How do I obtain the path of the resource directory by using an API? + +Applicable to: OpenHarmony 3.1 Beta 5 (API version 9) + +**Symptom** + +How do I obtain the path of the **resource** directory so that I can manage the files in it by using the file management API? + +**Solution** + +Because the application is installed in HAP mode and the HAP package is not decompressed after the installation is complete, the resource path cannot be obtained when the program is running. + +To obtain the path of the **resource** directory, try either of the following ways: + +1. Use **\$r** or **\$rawfile** for access. This method applies to static access, during which the **resource** directory remains unchanged when the application is running. + +2. Use **ResourceManager** for access. This method applies to dynamic access, during which the **resource** directory dynamically changes when the application is running. + +**Reference** + +[Resource Categories and Access](../quick-start/resource-categories-and-access.md) and [Resource Manager](../reference/apis/js-apis-resource-manager.md) + +## Why does getPluralString return an incorrect value? + +Applicable to: OpenHarmony 3.2 Beta 5 (API version 9) + +**Symptom** + +The value obtained by the **getPluralString** is **other**, which is incorrect. + +**Solution** + +The **getPluralString** API is effective only when the system language is English. + +## How do I obtain the customized string fields in the resources directory? + +Applicable to: OpenHarmony 3.2 Beta 5 (API version 9) + +**Solution** + +Use **getStringValue** of the **ResourceManager** module. + +**Reference** + +[Resource Manager](../reference/apis/js-apis-resource-manager.md#getstringvalue9) + +## How do I reference resources such as images and text in AppScope? + +Applicable to: OpenHarmony 3.2 Beta 5 (API version 9) + +**Solution** + +Reference resources in the **\$r\('app.type.name'\)** format. Wherein, **type** indicates the resource type, such as color, string, and media, and **name** indicates the resource name. + +## How do I convert resources to strings? + +Applicable to: OpenHarmony 3.2 Beta 5 (API version 9) + +**Solution** + +For a qualifier directory, use **this.context.resourceManager.getStringSync\(\$r\('app.string.test'\).id\)** to covert resources to strings synchronously. Note that the **\$r\('app.string.test', 2\)** mode is not supported. + +**Reference** + +[Resource Manager](../reference/apis/js-apis-resource-manager.md#getstringsync9) + +## Can $ be used to reference constants in the form\_config.json file? + +Applicable to: OpenHarmony 3.2 Beta 5 (API version 9) + +**\$** cannot be used to reference constants in the **form\_config.json** file. diff --git a/en/application-dev/faqs/faqs-international.md b/en/application-dev/faqs/faqs-international.md deleted file mode 100644 index 546402921ce3a2cd9f9972721727a84d9a31295a..0000000000000000000000000000000000000000 --- a/en/application-dev/faqs/faqs-international.md +++ /dev/null @@ -1,19 +0,0 @@ -# Intl Development - -## How resources in AppScope, such as images and text, are referenced? - -Applicable to: OpenHarmony SDK 3.2.5.5, stage model of API version 9 - -Resources are referenced in the **$r('app.type.name')** format. Where, **type** indicates the resource type, such as color, string, and media, and **name** indicates the resource name. - -## How do I convert the resource type to string? - -Applicable to: OpenHarmony SDK3.0, stage model of API version 9 - -If the resource type is set to **string**, the qualifier directory can be set as **this.context.resourceManager.getStringSync(\\$r('app.string.test').id)** and can be converted synchronously. The **\$r('app.string.test', 2)** mode is not supported. For more usage methods, see [Resource Manager](../reference/apis/js-apis-resource-manager.md#getstringsync9). - -## Why should I do if the constants referenced by $ in the form_config.json file does not take effect? - -Applicable to: OpenHarmony SDK 3.2.6.5, API9 Stage model - -In the **form\_config.json** file, **$** cannot be used to reference constants. diff --git a/en/application-dev/faqs/faqs-language.md b/en/application-dev/faqs/faqs-language.md index 6d3ded94a76155feae22d761bdb63422e07f0316..686283d7f8b41fa7abc4f4c78f74eed1240014d8 100644 --- a/en/application-dev/faqs/faqs-language.md +++ b/en/application-dev/faqs/faqs-language.md @@ -85,8 +85,6 @@ Applicable to: OpenHarmony SDK 3.2.3.5, stage model of API version 9 Objects imported to abilities and pages are packaged into two different closures, that is, two global objects. In this case, a static variable referenced by the abilities is not the same object as that referenced by the pages. Therefore, global variables cannot be defined by defining static variables in the class. You are advised to use AppStorage to manage global variables. -Reference: [State Management with Application-level Variables](../quick-start/arkts-state-mgmt-application-level.md) - ## How do I obtain resources in the stage model? Applicable to: OpenHarmony SDK 3.2.3.5, stage model of API version 9 @@ -181,7 +179,7 @@ Similar to **new Date().getTime()**, **systemTime.getCurrentTime(false)** return Applicable to: OpenHarmony SDK 3.2.6.5, stage model of API version 9 -If no parameter is passed when assigning a value to the **@BuilderParam** decorated attribute (for example, **content: this.specificParam**), define the type of the attribute as a function without a return value (for example, **@BuilderParam content: () => voi**). If any parameter is passed when assigning a value to the **@BuilderParam** decorated attribute (for example, **callContent: this.specificParam1("111")**), define the type of the attribute as **any** (for example, **@BuilderParam callContent: any**). For details, see [BuilderParam](../quick-start/arkts-dynamic-ui-elememt-building.md#builderparam8). +If no parameter is passed when assigning a value to the **@BuilderParam** decorated attribute (for example, **content: this.specificParam**), define the type of the attribute as a function without a return value (for example, **@BuilderParam content: () => voi**). If any parameter is passed when assigning a value to the **@BuilderParam** decorated attribute (for example, **callContent: this.specificParam1("111")**), define the type of the attribute as **any** (for example, **@BuilderParam callContent: any**). ## How does ArkTS convert a string into a byte array? @@ -251,7 +249,6 @@ Applicable to: OpenHarmony SDK 3.2.5.5, stage model of API version 9 To listen for in-depth changes of **@State** decorated variables, you can use **@Observed** and **@ObjectLink** decorators. - ## How do I implement character string encoding and decoding? Applicable to: OpenHarmony SDK 3.2.5.5, stage model of API version 9 diff --git a/en/application-dev/faqs/faqs-network-management.md b/en/application-dev/faqs/faqs-network-management.md new file mode 100644 index 0000000000000000000000000000000000000000..dd585f87cc40f2942404cc51c3fcb15bcf04d55e --- /dev/null +++ b/en/application-dev/faqs/faqs-network-management.md @@ -0,0 +1,222 @@ +# Network Management Development + +## What are the data formats supported by extraData in an HTTP request? + +Applicable to: OpenHarmony 3.2 Beta (API version 9) + +**Solution** + +**extraData** indicates additional data in an HTTP request. It varies depending on the HTTP request method. + +- If the HTTP request uses a POST or PUT method, **extraData** serves as the content of the HTTP request. +- If the HTTP request uses a GET, OPTIONS, DELETE, TRACE, or CONNECT method, **extraData** serves as a supplement to the HTTP request parameters and will be added to the URL when the request is sent. +- If you pass in a string object, **extraData** contains the string encoded on your own. + +## What does error code 28 mean in the response to an HTTP request? + +Applicable to: OpenHarmony 3.2 Beta (API version 9) + +**Symptom** + +Error code 28 is reported after an HTTP request is initiated. + +**Solution** + +Error code 28 indicates **CURLE\_OPERATION\_TIMEDOUT**, which means a libcurl library operation timeout. For details, see any HTTP status code description available. + +**Reference** + +[Common HTTP Response Codes](../reference/apis/js-apis-http.md#responsecode) and [Curl Error Codes](https://curl.se/libcurl/c/libcurl-errors.html) + +## What does error code 6 mean in the response to an HTTP request? + +Applicable to: OpenHarmony 3.2 Beta (API version 9) + +**Symptom** + +Error code 6 is reported after an HTTP request is initiated. + +**Solution** + +Error code 6 indicates a failure to resolve the host in the address. You can ping the URL carried in the request to check whether the host is accessible. + +**Reference** + +[Common HTTP Response Codes](../reference/apis/js-apis-http.md#responsecode) and [Curl Error Codes](https://curl.se/libcurl/c/libcurl-errors.html) + +## How are parameters passed to queryParams of the POST request initiated by @ohos/axios? + +Applicable to: OpenHarmony 3.2 Beta (API version 9) + +**Symptom** + +How are parameters passed to **queryParams** when the third-party component @ohos/axios initiates a POST request? + +**Solution** + +- Method 1: Have the **axios.post** API receive only one parameter. The **Url.URLSearchParams** parameter needs to be converted into a string and appended to the end of the URL. + + ``` + let params:Url.URLSearchParams = new Url.URLSearchParams() + params.append('ctl', 'sug') + params.append('query', 'wangjunkai') + params.append('cfrom', '1099a') + axios.post('http://10.100.195.234:3000/save?' + params.toString()).then(res => { + this.message = "request result: " + JSON.stringify(res.data); + }).catch(err => { + this.message = "request error: " + err.message; + }) + ``` + +- Method 2: Have the **axios** API receive only one **config** object. The request parameters are written in **params** of the **config** object. + + ``` + axios({ + url: 'http://10.100.195.234:3000/save', + method: 'post', + params: { + ctl: 'sug', + query: 'wangjunkai', + cfrom: '1099a' + } + }).then(res => { + this.message = "request result: " + JSON.stringify(res.data); + }).catch(err => { + this.message = "request error: " + err.message; + }) + ``` + + +## What should I do if no data is returned after connection.getNetCapabilities\(mNetHandle\) is called? + +Applicable to: OpenHarmony 3.2 Beta 2 (API version 9) + +**Symptom** + +No data is returned after **connection.getNetCapabilities\(\)** is called. What should I do? + +**Possible Cause** + +This problem is due to incorrect pointing of the **this** object. You are expected to use **\(err,data\)=\>\{\}** instead of **function\(err,data\)** to access the callback function to obtain the return result. The reason is that the function declared by **function** has its own **this** object and therefore cannot point to the **globalThis** object. + +**Solution** + +Change **function\(err,data\)** to **\(err,data\)** for the second parameter of **getNetCapabilities**. + +## How is data in HTTP requests transmitted in JSON format? + +Applicable to: OpenHarmony 3.2 Beta (API version 9) + +**Solution** + +In the HTTP message header, **Content-Type** is used to indicate the media type information. It tells the server how to process the requested data and tells the client (usually a browser) how to parse the response data, for example, displaying an image, parsing HTML, or displaying only the text. + +To transmit data in HTTP requests in JSON format, set **Content-Type** to **application/json**. + +``` +this.options = { + method: http.RequestMethod.GET, + extraData: this.extraData, + header: { 'Content-Type': 'application/json' }, + readTimeout: 50000, + connectTimeout: 50000 +} +``` + +## How do I upload photos taken by a camera to the server? + +Applicable to: OpenHarmony 3.2 Beta 5 (API version 9) + +**Symptom** + +After an application calls the camera to take a photo, how do I upload the photo to the server? + +**Solution** + +After the application is started and the permission is obtained, have the system access the remote server and transfer the locally saved photos to the remote server through the upload API. + +**Reference** + +[Upload and Download](../reference/apis/js-apis-request.md) + +## What should I do if calling connection.hasDefaultNet\(\) fails even when the network is normal? + +Applicable to: OpenHarmony 3.2 Beta (API version 9) + +**Symptom** + +The network connection is normal, and web pages can be opened properly on the browser. However, calling the **hasDefaultNet** fails, and the callback function returns an error. + +**Solution** + +Declare the **ohos.permission.GET\_NETWORK\_INFO** permission when calling **connection.hasDefaultNet**. + +For details, see [Applying for Permissions](../security/accesstoken-guidelines.md). + +## What does netId mean in the netHandle object returned by connection.getDefaultNet? + +Applicable to: OpenHarmony 3.2 Beta (API version 9) + +**Symptom** + +What are the meanings of the values of **netId**, such as **0** and **100**? + +**Solution** + +If the value of **netId** is **0**, no network connection is available. In such a case, check and rectify network faults. If the value is greater than or equal to **100**, the network connection is normal. + +## How do I use HTTP requests to obtain data from the network? + +Applicable to: OpenHarmony 3.2 Beta (API version 9) + +**Solution** + +Use the **@ohos.net.http** module to initiate an HTTP request. + +1. Import the **http** module and create an HTTP request. +2. Set the request URL and parameters and initiate the HTTP request. +3. Obtain the response and parse the data. + +**Reference** + +[HTTP Data Request](../connectivity/http-request.md) + +## How do I encapsulate network requests by using JavaScript? + +Applicable to: OpenHarmony 3.2 Beta (API version 9) + +**Solution** + +OpenHarmony supports the JavaScript development mode. You can directly use JavaScript to encapsulate network requests. For details, see [Network Connection](../reference/apis/js-apis-http.md). + +## How do I write network requests when developing a JavaScript-based application for smart watches? + +Applicable to: OpenHarmony 3.2 Beta (API version 9) + +**Solution** + +OpenHarmony supports the JavaScript development mode. You can directly use JavaScript to encapsulate network requests. For details, see [Network Connection](../reference/apis/js-apis-http.md). + +## Why does an application fail to start after the ohos.permission.NOTIFICATION\_CONTROLLER permission is declared? + +Applicable to: OpenHarmony 3.2 Beta (API version 9) + +**Symptom** + +When an application is started, the following error message is reported w: error: install failed due to grant request permissions failed. + +**Solution** + +The **ohos.permission.NOTIFICATION\_CONTROLLER** permission is a **system core** permission and is not available for third-party applications. + +## What should I do if an error is reported when wifi.getIpInfo\(\).ipAddress is used in the Wi-Fi module? + +Applicable to: OpenHarmony 3.2 Beta (API version 9) + +**Symptom** + +When **wifi.getIpInfo\(\).ipAddress** is used in the Wi-Fi module, the following error message is reported: Error: assertion \(wifiDevicePtr != nullptr\) failed: Wifi device instance is null. + +**Solution** + +This problem is due to insufficient permissions. Check whether you have applied for the required permissions. For details, see [Permission Management](../security/accesstoken-overview.md). diff --git a/en/application-dev/faqs/faqs-startup.md b/en/application-dev/faqs/faqs-startup.md new file mode 100644 index 0000000000000000000000000000000000000000..3d0d9d2cf8b59cb7f1b3b3c778b963c509958ced --- /dev/null +++ b/en/application-dev/faqs/faqs-startup.md @@ -0,0 +1,43 @@ +# Startup Development + +## How do I obtain the system version of a device? + +Applicable to: OpenHarmony 3.2 Beta 5 (API version 9) + +**Solution** + +You can obtain the system version of a device through the **osFullName** attribute of the [deviceInfo](../reference/apis/js-apis-device-info.md) object. + +**Sample Code** + +``` +import deviceInfo from '@ohos.deviceInfo' +let v = deviceInfo.osFullName +``` + +## How do I obtain the UDID of a device? + +Applicable to: OpenHarmony 3.2 Beta 5 (API version 9) + +**Solution** + +- Method 1: Run the **hdc shell bm get --udid** command. +- Method 2: Obtain the value from the code. For details, see [udid](../reference/apis/js-apis-device-info.md). + +## How do I obtain device information? + +Applicable to: OpenHarmony 3.2 Beta 5 (API version 9) + +You can call **deviceInfo** to obtain device information, such as the device model. + +**Reference** + +[Device Information](../reference/apis/js-apis-device-info.md) + +## How do I prevent application development from being interrupted by screen saving? + +Applicable to: OpenHarmony 3.2 Beta 5 (API version 9) + +**Solution** + +Run the **hdc shell "power-shell setmode 602"** command to turn off screen saving. diff --git a/en/application-dev/file-management/Readme-EN.md b/en/application-dev/file-management/Readme-EN.md index 1e644dbac0ff2cf0e9f9deb205d234abc716ac08..bdc1bc7c1b00195bc24c71396f4fed78b93de15a 100644 --- a/en/application-dev/file-management/Readme-EN.md +++ b/en/application-dev/file-management/Readme-EN.md @@ -1,4 +1,4 @@ -# File +# File Management - [File Management Overview](file-management-overview.md) - Application File @@ -20,4 +20,4 @@ - Distributed File System - [Distributed File System Overview](distributed-fs-overview.md) - [Setting the Security Level of a Distributed File](set-security-label.md) - - [Access Files Across Devices](file-access-across-devices.md) + - [Accessing Files Across Devices](file-access-across-devices.md) diff --git a/en/application-dev/file-management/app-sandbox-directory.md b/en/application-dev/file-management/app-sandbox-directory.md index 7d06b330aa085aa34045c5491b5855160744f44a..3424dfbc9ec457e5ab6839e521fde5caad0dd3ae 100644 --- a/en/application-dev/file-management/app-sandbox-directory.md +++ b/en/application-dev/file-management/app-sandbox-directory.md @@ -73,7 +73,7 @@ The following figure shows the application file directories. The path of a file | distributedfiles | distributedFilesDir | Distributed file directory| Directory in **el2** for saving the application files that can be directly accessed across devices.
This directory is cleared when the application is uninstalled.| | files | filesDir | Application file directory| Directory for saving the application's persistent files on the device.
This directory is cleared when the application is uninstalled.| | cache | cacheDir | Application cache file directory| Directory for caching the downloaded files of the application or saving the cache files regenerated on the device.
This directory is automatically cleared when the size of the **cache** directory reaches the quota or the system storage space reaches a certain threshold. The user can also clear this directory by using a system space management application.
The application needs to check whether the file still exists and determine whether to cache the file again.| - | preferences | preferencesDir | Preferences file directory| Directory for saving common application configuration and user preference data managed by using database APIs.
This directory is cleared when the application is uninstalled. For details, see [Data Persistence by User Preferences](../database/data-persistence-by-preferences.md).| + | preferences | preferencesDir | Preferences file directory| Directory for saving common application configuration and user preference data managed by using database APIs.
This directory is cleared when the application is uninstalled. For details, see [Persisting Preferences Data](../database/data-persistence-by-preferences.md).| | temp | tempDir | Temporary file directory| Directory for saving the files generated and required during the application's runtime on the device.
This directory is cleared when the application exits.| The application file paths are used in the following scenarios: @@ -92,5 +92,3 @@ The following figure shows the application file directories. The path of a file Used to store application preferences data, including preference files and configuration files. This directory applied to storing only a small amount of data. - Temporary file directory
Used to store temporarily generated data of an application, including cached database data and images, temporary log files, downloaded application installation package files. The data stored in this directory is deleted after being used. - - \ No newline at end of file diff --git a/en/application-dev/file-management/file-access-across-devices.md b/en/application-dev/file-management/file-access-across-devices.md index 434af1a2920a9f9144dfa6e29bcf57edbd57bd93..840078f5f982d55a9d9a3713fafa49d632d352f8 100644 --- a/en/application-dev/file-management/file-access-across-devices.md +++ b/en/application-dev/file-management/file-access-across-devices.md @@ -1,4 +1,4 @@ -# Access Files Across Devices +# Accessing Files Across Devices The distributed file system provides cross-device file access capabilities for applications. For the same application installed on multiple devices, you can implement read and write of the files in the application's distributed directory (**/data/storage/el2/distributedfiles/**) across devices by using [ohos.file.fs](app-file-access.md). For example, device A and device B are installed with the same application. After device A and device B are connected to form a Virtual Device, the application on device A can access the files of the same application on Device B. What you need to do is place the files to the distributed directory. diff --git a/en/application-dev/file-management/file-management-overview.md b/en/application-dev/file-management/file-management-overview.md index a159a3348eb7892a68a334c64ae0b69288e24d1d..2fbd4b4a036de1f20f8aa64825ab1dcb60f23414 100644 --- a/en/application-dev/file-management/file-management-overview.md +++ b/en/application-dev/file-management/file-management-overview.md @@ -23,6 +23,3 @@ The file systems can be classified into the following types based on the file st **Figure 1** Files in an OS ![File classification model](figures/file-classification-model.png) - - - \ No newline at end of file diff --git a/en/application-dev/file-management/set-security-label.md b/en/application-dev/file-management/set-security-label.md index 94ad527767e443b532330e207a45653980cdfa71..af819fba397d47f81b0ebe005e67f9e6c8ebef39 100644 --- a/en/application-dev/file-management/set-security-label.md +++ b/en/application-dev/file-management/set-security-label.md @@ -1,6 +1,6 @@ # Setting the Security Level of a Distributed File -The security capabilities vary with devices. For example, small embedded devices provide fewer security capabilities than tablets. The security requirements also vary with data. For example, personal health information and bank card information are not expected to be accessed by devices of lower security levels. OpenHarmony provides a complete set of standards for data and device classification and custom data transfer policies for different devices. For details, see [Data and Device Security Classification](../database/access-control-by-device-and-data-level.md). +The security capabilities vary with devices. For example, small embedded devices provide fewer security capabilities than tablets. The security requirements also vary with data. For example, personal health information and bank card information are not expected to be accessed by devices of lower security levels. OpenHarmony provides a complete set of standards for data and device classification and custom data transfer policies for different devices. For details, see [Data Security Labels and Device Security Levels](../database/access-control-by-device-and-data-level.md). ## Available APIs @@ -39,4 +39,3 @@ securityLabel.setSecurityLabel(filePath, 's0').then(() => { console.error(`Failed to setSecurityLabel. Code: ${err.code}, message: ${err.message}`); }); ``` - \ No newline at end of file diff --git a/en/application-dev/media/Readme-EN.md b/en/application-dev/media/Readme-EN.md index f3a233ca129527db112459ab5110df49b8e1052d..efc78832291fda395506dc0864af4fae0f068621 100755 --- a/en/application-dev/media/Readme-EN.md +++ b/en/application-dev/media/Readme-EN.md @@ -45,11 +45,11 @@ - [Session Management](camera-session-management.md) - [Camera Preview](camera-preview.md) - [Camera Photographing](camera-shooting.md) - - [Video Recording](camera-recording.md) + - [Camera Recording](camera-recording.md) - [Camera Metadata](camera-metadata.md) - Best Practices - [Camera Photographing Sample](camera-shooting-case.md) - - [Video Recording Sample](camera-recording-case.md) + - [Camera Recording Sample](camera-recording-case.md) - Image - [Image Overview](image-overview.md) - [Image Decoding](image-decoding.md) diff --git a/en/application-dev/media/camera-recording-case.md b/en/application-dev/media/camera-recording-case.md index 4d284f7e675fe0693240bbb678391147926652e7..7aedbf5688812c47542ee627329b137325f17bbc 100644 --- a/en/application-dev/media/camera-recording-case.md +++ b/en/application-dev/media/camera-recording-case.md @@ -1,4 +1,4 @@ -# Video Recording Sample +# Camera Recording Sample ## Development Process diff --git a/en/application-dev/media/camera-recording.md b/en/application-dev/media/camera-recording.md index 421ff990bf45b372dd39cd3346e29b636f292762..208b0664204ef2f74bb1160702053bde61fdf316 100644 --- a/en/application-dev/media/camera-recording.md +++ b/en/application-dev/media/camera-recording.md @@ -1,4 +1,4 @@ -# Video Recording +# Camera Recording Video recording is also an important function of the camera application. Video recording is the process of cyclic capturing of frames. To smooth videos, you can follow step 4 in [Camera Photographing](camera-shooting.md) to set the resolution, flash, focal length, photo quality, and rotation angle. diff --git a/en/application-dev/napi/figures/rawfile1.png b/en/application-dev/napi/figures/rawfile1.png new file mode 100644 index 0000000000000000000000000000000000000000..9f29f7875cd983f967b7a3b27b5898bfce76c9f3 Binary files /dev/null and b/en/application-dev/napi/figures/rawfile1.png differ diff --git a/en/application-dev/napi/rawfile-guidelines.md b/en/application-dev/napi/rawfile-guidelines.md index c585b162a2dc483ca72a5369170b2ee0f43a01a1..ccd517b40d77362b94b76001cf921f134a0cf237 100644 --- a/en/application-dev/napi/rawfile-guidelines.md +++ b/en/application-dev/napi/rawfile-guidelines.md @@ -1,14 +1,12 @@ # Raw File Development - - ## When to Use -This document describes how to use the native Rawfile APIs to manage raw file directories and files in OpenHarmony. You can use the APIs to traverse, open, search for, read, and close raw files. +This document describes how to use the native Rawfile APIs to manage raw file directories and files in OpenHarmony. You can use Rawfile APIs to perform operations such as traversing the file list, opening, searching for, reading, and closing raw files. ## Available APIs -| API | Description | +| Name | Description | | :----------------------------------------------------------- | :--------------------------------------- | | NativeResourceManager *OH_ResourceManager_InitNativeResourceManager(napi_env env, napi_value jsResMgr) | Initializes the native resource manager. | | RawDir *OH_ResourceManager_OpenRawDir(const NativeResourceManager *mgr, const char *dirName) | Opens a raw file directory. | @@ -27,60 +25,289 @@ This document describes how to use the native Rawfile APIs to manage raw file di ## How to Develop -1. Add the header file. + The following describes how to obtain the raw file list, raw file content, and raw file descriptor on the JavaScript side as an example. + +1. Create a project. + +![Creating a C++ application](figures/rawfile1.png) + +2. Add dependencies. + +After a project is created, the **cpp** directory is created under the project. The directory contains files such as **libentry/index.d.ts**, **hello.cpp**, and **CMakeLists.txt**. + +1. Open the **src/main/cpp/CMakeLists.txt** file, and add **librawfile.z.so** and **libhilog_ndk.z.so** to **target_link_libraries**. ```c++ - #include "raw_file_manager.h" + target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so librawfile.z.so) ``` - - -2. Call **OH_ResourceManager_InitNativeResourceManager(napi_env env, napi_value jsResMgr)** to obtain a **NativeResourceManager** instance. +2. Open the **src/main/cpp/types/libentry/index.d.ts** file, and declare the application functions **getFileList**, **getRawFileContent**, and **getRawFileDescriptor**. - ```js - // Import the JS resource manager from the JS head file and pass it to the C++ file. - import resManager from '@ohos.resourceManager' - import rawfileTest from 'librawFileTest.so' - resManager.getResourceManager().then(resmgr => { - rawfileTest.testRawFile("test", resmgr, (error, value) => { - console.log("test rawFile"); - }) - }); - ``` - - ```c++ - // Obtain and parse the parameters in the C++ file. - NativeResourceManager* nativeResourceManager = nullptr; - std::string path; - if (i == 0 && valueType == napi_string) { - // Parse the first parameter, which is the file or directory path relative to the raw file directory. - ...... - path = buf.data(); - } else if (i == 1 && valueType == napi_object) { - // Parse the second parameter, which is the JS resource manager. - nativeResourceManager = OH_ResourceManager_InitNativeResourceManager(env, argv[i]); + ```c++ + import resourceManager from '@ohos.resourceManager'; + export const getFileList: (resmgr: resourceManager.ResourceManager, path: string) => Array; + export const getRawFileContent: (resmgr: resourceManager.ResourceManager, path: string) => Uint8Array; + export const getRawFileDescriptor: (resmgr: resourceManager.ResourceManager, path: string) => resourceManager.RawFileDescriptor; + ``` + +3. Modify the source file. + +1. Open the **src/main/cpp/hello.cpp** file. During initialization, the file maps the external JavaScript APIs **getFileList**, **getRawFileContent**, and **getRawFileDescriptor** to C++ native APIs **GetFileList**, **GetRawFileContent**, and **GetRawFileDescriptor**. + + ```c++ + EXTERN_C_START + static napi_value Init(napi_env env, napi_value exports) + { + napi_property_descriptor desc[] = { + { "getFileList", nullptr, GetFileList, nullptr, nullptr, nullptr, napi_default, nullptr }, + { "getRawFileContent", nullptr, GetRawFileContent, nullptr, nullptr, nullptr, napi_default, nullptr }, + { "getRawFileDescriptor", nullptr, GetRawFileDescriptor, nullptr, nullptr, nullptr, napi_default, nullptr } + }; + + napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); + return exports; } + EXTERN_C_END ``` +2. Add the three functions to the **src/main/cpp/hello.cpp** file. + + ```c++ + static napi_value GetFileList(napi_env env, napi_callback_info info) + static napi_value GetRawFileContent(napi_env env, napi_callback_info info) + static napi_value GetRawFileDescriptor(napi_env env, napi_callback_info info) + ``` + +3. Obtain JavaScript resource objects from the **hello.cpp** file, and convert them to native resource objects. Then, call the native APIs to obtain the raw file list, raw file content, and raw file descriptor {fd, offset, length}. The sample code is as follows: + + ```c++ + // Example 1: Use GetFileList to obtain the raw file list. + static napi_value GetFileList(napi_env env, napi_callback_info info) + { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "NDKTest Begin"); + size_t requireArgc = 3; + size_t argc = 2; + napi_value argv[2] = { nullptr }; + // Obtain arguments of the native API. + napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr); + + // Obtain argv[0], which specifies conversion of the JavaScript resource object (that is, OH_ResourceManager_InitNativeResourceManager) to a native object. + NativeResourceManager *mNativeResMgr = OH_ResourceManager_InitNativeResourceManager(env, argv[0]); + + // Obtain argv[1], which specifies the relative path of the raw file. + size_t strSize; + char strBuf[256]; + napi_get_value_string_utf8(env, argv[1], strBuf, sizeof(strBuf), &strSize); + std::string dirName(strBuf, strSize); + + // Obtain the corresponding rawDir pointer object. + RawDir* rawDir = OH_ResourceManager_OpenRawDir(mNativeResMgr, dirName.c_str()); + + // Obtain the number of files and folders in rawDir. + int count = OH_ResourceManager_GetRawFileCount(rawDir); + + // Traverse rawDir to obtain the list of file names and save it. + std::vector tempArray; + for(int i = 0; i < count; i++) { + std::string filename = OH_ResourceManager_GetRawFileName(rawDir, i); + tempArray.emplace_back(filename); + } + + napi_value fileList; + napi_create_array(env, &fileList); + for (size_t i = 0; i < tempArray.size(); i++) { + napi_value jsString; + napi_create_string_utf8(env, tempArray[i].c_str(), NAPI_AUTO_LENGTH, &jsString); + napi_set_element(env, fileList, i, jsString); + } + + // Close the rawDir pointer object. + OH_ResourceManager_CloseRawDir(rawDir); + OH_ResourceManager_ReleaseNativeResourceManager(mNativeResMgr); + return fileList; + } + + // Example 2: Use rawDir pointer object to obtain the content of the raw file. + napi_value CreateJsArrayValue(napi_env env, std::unique_ptr &data, long length) + { + napi_value buffer; + napi_status status = napi_create_external_arraybuffer(env, data.get(), length, + [](napi_env env, void *data, void *hint) { + delete[] static_cast(data); + }, nullptr, &buffer); + if (status != napi_ok) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "Failed to create external array buffer"); + return nullptr; + } + napi_value result = nullptr; + status = napi_create_typedarray(env, napi_uint8_array, length, buffer, 0, &result); + if (status != napi_ok) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "Failed to create media typed array"); + return nullptr; + } + data.release(); + return result; + } + static napi_value GetRawFileContent(napi_env env, napi_callback_info info) + { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "GetFileContent Begin"); + size_t requireArgc = 3; + size_t argc = 2; + napi_value argv[2] = { nullptr }; + // Obtain arguments of the native API. + napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr); + + // Obtain argv[0], which specifies conversion of the JavaScript resource object (that is, OH_ResourceManager_InitNativeResourceManager) to a native object. + NativeResourceManager *mNativeResMgr = OH_ResourceManager_InitNativeResourceManager(env, argv[0]); + size_t strSize; + char strBuf[256]; + napi_get_value_string_utf8(env, argv[1], strBuf, sizeof(strBuf), &strSize); + std::string filename(strBuf, strSize); + + // Obtain the raw file pointer object. + RawFile *rawFile = OH_ResourceManager_OpenRawFile(mNativeResMgr, filename.c_str()); + if (rawFile != nullptr) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "OH_ResourceManager_OpenRawFile success"); + } + // Obtain the size of the raw file and apply for memory. + long len = OH_ResourceManager_GetRawFileSize(rawFile); + std::unique_ptr data= std::make_unique(len); + // Read the raw file. + int res = OH_ResourceManager_ReadRawFile(rawFile, data.get(), len); + // Close the raw file pointer object. + OH_ResourceManager_CloseRawFile(rawFile); + OH_ResourceManager_ReleaseNativeResourceManager(mNativeResMgr); + // Convert the native object to a JavaScript object. + return CreateJsArrayValue(env, data, len); + } + + // Example 3: Use GetRawFileDescriptor to obtain the FD of the raw file. + napi_value createJsFileDescriptor(napi_env env, RawFileDescriptor &descriptor) + { + napi_value result; + napi_status status = napi_create_object(env, &result); + if (status != napi_ok) { + return result; + } + + napi_value fd; + status = napi_create_int32(env, descriptor.fd, &fd); + if (status != napi_ok) { + return result; + } + status = napi_set_named_property(env, result, "fd", fd); + if (status != napi_ok) { + return result; + } + + napi_value offset; + status = napi_create_int64(env, descriptor.start, &offset); + if (status != napi_ok) { + return result; + } + status = napi_set_named_property(env, result, "offset", offset); + if (status != napi_ok) { + return result; + } + + napi_value length; + status = napi_create_int64(env, descriptor.length, &length); + if (status != napi_ok) { + return result; + } + status = napi_set_named_property(env, result, "length", length); + if (status != napi_ok) { + return result; + } + return result; + } + static napi_value GetRawFileDescriptor(napi_env env, napi_callback_info info) + { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "NDKTest GetRawFileDescriptor Begin"); + size_t requireArgc = 3; + size_t argc = 2; + napi_value argv[2] = { nullptr }; + // Obtain arguments of the native API. + napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr); + + napi_valuetype valueType; + napi_typeof(env, argv[0], &valueType); + // Obtain the native resourceManager object. + NativeResourceManager *mNativeResMgr = OH_ResourceManager_InitNativeResourceManager(env, argv[0]); + size_t strSize; + char strBuf[256]; + napi_get_value_string_utf8(env, argv[1], strBuf, sizeof(strBuf), &strSize); + std::string filename(strBuf, strSize); + // Obtain the raw file pointer object. + RawFile *rawFile = OH_ResourceManager_OpenRawFile(mNativeResMgr, filename.c_str()); + if (rawFile != nullptr) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "OH_ResourceManager_OpenRawFile success"); + } + // Obtain the FD of the raw file, that is, RawFileDescriptor {fd, offset, length}. + RawFileDescriptor descriptor; + OH_ResourceManager_GetRawFileDescriptor(rawFile, descriptor); + // Close the raw file pointer object. + OH_ResourceManager_CloseRawFile(rawFile); + OH_ResourceManager_ReleaseNativeResourceManager(mNativeResMgr); + // Convert the native object to a JavaScript object. + return createJsFileDescriptor(env,descriptor); + } + ``` + +4. Call APIs on the JavaScript side. + +1. Open **src\main\ets\pages\index.ets**, and import **libentry.so**. + +2. Obtain the JavaScript resource object, that is, **resourceManager**. +3. Call **getFileList**, that is, the native API declared in **src/main/cpp/types/libentry/index.d.ts**. When calling the API, pass the JavaScript resource object and the relative path of the raw file. The sample code is as follows: + + ```js + import hilog from '@ohos.hilog'; + import testNapi from 'libentry.so' // Import the libentry.so file. + @Entry + @Component + struct Index { + @State message: string = 'Hello World' + private resmgr = getContext().resourceManager; // Obtain the JavaScript resource object. + build() { + Row() { + Column() { + Text(this.message) + .fontSize(50) + .fontWeight(FontWeight.Bold) + .onClick(() => { + hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO); + let rawfilelist = testNapi.getFileList(this.resmgr, ""); // Pass the JavaScript resource object and the relative path of the raw file. + console.log("rawfilelist" + rawfilelist); + let rawfileContet = testNapi.getRawFileContent(this.resmgr, "rawfile1.txt"); + console.log("rawfileContet" + rawfileContet); + let rawfileDescriptor = testNapi.getRawFileDescriptor(this.resmgr, "rawfile1.txt"); + console.log("getRawFileDescriptor" + rawfileDescriptor.fd, rawfileDescriptor.offset, rawfileDescriptor.length); + }) + } + .width('100%') + } + .height('100%') + } + } + ``` + +## Using C++ Functions -3. Call **OH_ResourceManager_OpenRawDir** to obtain a **RawDir** instance based on the **NativeResourceManager** instance. +1. Call **OH_ResourceManager_OpenRawDir** to obtain a **RawDir** instance based on the **NativeResourceManager** instance. ```c++ RawDir* rawDir = OH_ResourceManager_OpenRawDir(nativeResourceManager, path.c_str()); ``` - - -4. Call **OH_ResourceManager_GetRawFileCount** to obtain the total number of raw files in the directory based on the **RawDir** instance. +2. Call **OH_ResourceManager_GetRawFileCount** to obtain the total number of raw files in the directory based on the **RawDir** instance. ```c++ int count = OH_ResourceManager_GetRawFileCount(rawDir); ``` - - -5. Call **OH_ResourceManager_GetRawFileName** to obtain the name of the raw file with the specified index. +3. Call **OH_ResourceManager_GetRawFileName** to obtain the name of the raw file with the specified index. ```c++ for (int index = 0; index < count; index++) { @@ -88,85 +315,65 @@ This document describes how to use the native Rawfile APIs to manage raw file di } ``` - - -6. Call **OH_ResourceManager_OpenRawFile** to obtain a **RawFile** instance with the specified file name. +4. Call **OH_ResourceManager_OpenRawFile** to obtain a **RawFile** instance with the specified file name. ```c++ RawFile* rawFile = OH_ResourceManager_OpenRawFile(nativeResourceManager, fileName.c_str()); ``` - - -7. Call **OH_ResourceManager_GetRawFileSize** to obtain the size of the raw file. +5. Call **OH_ResourceManager_GetRawFileSize** to obtain the size of the raw file. ```c++ long rawFileSize = OH_ResourceManager_GetRawFileSize(rawFile); ``` - - -8. Call **OH_ResourceManager_SeekRawFile** to seek a read/write position in the raw file based on the specified offset. +6. Call **OH_ResourceManager_SeekRawFile** to seek a read/write position in the raw file based on the specified offset. ```c++ int position = OH_ResourceManager_SeekRawFile(rawFile, 10, 0); int position = OH_ResourceManager_SeekRawFile(rawFile, 0 , 1); int position = OH_ResourceManager_SeekRawFile(rawFile, -10, 2); ``` - - -9. Call **OH_ResourceManager_GetRawFileOffset** to obtain the raw file offset. +7. Call **OH_ResourceManager_GetRawFileOffset** to obtain the raw file offset. ```c++ long rawFileOffset = OH_ResourceManager_GetRawFileOffset(rawFile) ``` - - -10. Call **OH_ResourceManager_ReadRawFile** to read the raw file. +8. Call **OH_ResourceManager_ReadRawFile** to read the raw file. ```c++ std::unique_ptr mediaData = std::make_unique(rawFileSize); long rawFileOffset = OH_ResourceManager_ReadRawFile(rawFile, mediaData.get(), rawFileSize); ``` - - -11. Call **OH_ResourceManager_CloseRawFile** to close the file to release resources. +9. Call **OH_ResourceManager_CloseRawFile** to close the file to release resources. ```c++ OH_ResourceManager_CloseRawFile(rawFile); ``` - - -12. Call **OH_ResourceManager_CloseRawDir** to close the raw file directory. +10. Call **OH_ResourceManager_CloseRawDir** to close the raw file directory. ```c++ OH_ResourceManager_CloseRawDir(rawDir); ``` - - -13. Call **OH_ResourceManager_GetRawFileDescriptor** to obtain the FD of the raw file. +11. Call **OH_ResourceManager_GetRawFileDescriptor** to obtain the FD of the raw file. ```c++ RawFileDescriptor descriptor; bool result = OH_ResourceManager_GetRawFileDescriptor(rawFile, descriptor); ``` - - -14. Call **OH_ResourceManager_ReleaseRawFileDescriptor** to release the FD of the raw file. +12. Call **OH_ResourceManager_ReleaseRawFileDescriptor** to release the FD of the raw file. ```c++ OH_ResourceManager_ReleaseRawFileDescriptor(descriptor); ``` - - -15. Call **OH_ResourceManager_ReleaseNativeResourceManager** to release the native resource manager. +13. Call **OH_ResourceManager_ReleaseNativeResourceManager** to release the native resource manager. ```c++ OH_ResourceManager_ReleaseNativeResourceManager(nativeResourceManager); diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index 16ca26e360b85d5f7b1e73b91882c1f839fecd04..d4984c913c6513270302417d873cf25d8ba2e60e 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -237,7 +237,7 @@ - [@ohos.file.environment (Directory Environment Capability)](js-apis-file-environment.md) - [@ohos.file.fileAccess (User File Access and Management)](js-apis-fileAccess.md) - [@ohos.file.fileExtensionInfo (User File Extension Information)](js-apis-fileExtensionInfo.md) - - [@ohos.file.fileUri (File URI)](js-apis-file-fileUri.md) + - [@ohos.file.fileuri (File URI)](js-apis-file-fileuri.md) - [@ohos.file.fs (File Management)](js-apis-file-fs.md) - [@ohos.file.hash (File Hash Processing)](js-apis-file-hash.md) - [@ohos.file.picker (File Picker)](js-apis-file-picker.md) diff --git a/en/application-dev/reference/apis/figures/printing-logs.png b/en/application-dev/reference/apis/figures/printing-logs.png new file mode 100644 index 0000000000000000000000000000000000000000..6eb89772d315b440636e8ceeda928e5db6b34e40 Binary files /dev/null and b/en/application-dev/reference/apis/figures/printing-logs.png differ diff --git a/en/application-dev/reference/apis/js-apis-app-ability-abilityDelegatorRegistry.md b/en/application-dev/reference/apis/js-apis-app-ability-abilityDelegatorRegistry.md index 76614085293fe0065dafea4a2e3a9d0d8559be0f..54785d5ddb6a24dba26fff11e436f7a222ae96f2 100644 --- a/en/application-dev/reference/apis/js-apis-app-ability-abilityDelegatorRegistry.md +++ b/en/application-dev/reference/apis/js-apis-app-ability-abilityDelegatorRegistry.md @@ -53,10 +53,10 @@ let want = { abilityName: 'EntryAbility' }; abilityDelegator.startAbility(want, (err) => { - if (!err || err.code === 0) { - console.log('Success start ability.'); - } else { + if (err) { console.error('Failed start ability, error: ${JSON.stringify(err)}'); + } else { + console.log('Success start ability.'); } }); ``` diff --git a/en/application-dev/reference/apis/js-apis-app-ability-appManager.md b/en/application-dev/reference/apis/js-apis-app-ability-appManager.md index f3e739c76ad25996ed767b71c0099ee7ca425abc..2cc4bb1b4d4820be0103db98e66b5a70dfed429b 100644 --- a/en/application-dev/reference/apis/js-apis-app-ability-appManager.md +++ b/en/application-dev/reference/apis/js-apis-app-ability-appManager.md @@ -40,7 +40,7 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error import appManager from '@ohos.app.ability.appManager'; appManager.isRunningInStabilityTest((err, flag) => { - if (err && err.code !== 0) { + if (err) { console.error('isRunningInStabilityTest fail, err: ${JSON.stringify(err)}'); } else { console.log('The result of isRunningInStabilityTest is: ${JSON.stringify(flag)}'); @@ -146,7 +146,7 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error import appManager from '@ohos.app.ability.appManager'; appManager.isRamConstrainedDevice((err, data) => { - if (err && err.code !== 0) { + if (err) { console.error('isRamConstrainedDevice fail, err: ${JSON.stringify(err)}'); } else { console.log('The result of isRamConstrainedDevice is: ${JSON.stringify(data)}'); @@ -216,7 +216,7 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error import appManager from '@ohos.app.ability.appManager'; appManager.getAppMemorySize((err, data) => { - if (err && err.code !== 0) { + if (err) { console.error('getAppMemorySize fail, err: ${JSON.stringify(err)}'); } else { console.log('The size of app memory is: ${JSON.stringify(data)}'); @@ -290,7 +290,7 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error import appManager from '@ohos.app.ability.appManager'; appManager.getRunningProcessInformation((err, data) => { - if (err && err.code !== 0) { + if (err) { console.error('getRunningProcessInformation fail, err: ${JSON.stringify(err)}'); } else { console.log('The process running information is: ${JSON.stringify(data)}'); @@ -489,7 +489,7 @@ try { // 2. Deregister the application state observer. function unregisterApplicationStateObserverCallback(err) { - if (err && err.code !== 0) { + if (err) { console.error('unregisterApplicationStateObserverCallback fail, err: ${JSON.stringify(err)}'); } else { console.log('unregisterApplicationStateObserverCallback success.'); @@ -612,7 +612,7 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error import appManager from '@ohos.app.ability.appManager'; function getForegroundApplicationsCallback(err, data) { - if (err && err.code !== 0) { + if (err) { console.error('getForegroundApplicationsCallback fail, err: ${JSON.stringify(err)}'); } else { console.log('getForegroundApplicationsCallback success, data: ${JSON.stringify(data)}'); @@ -745,7 +745,7 @@ import appManager from '@ohos.app.ability.appManager'; let bundleName = 'bundleName'; let accountId = 0; function killProcessWithAccountCallback(err, data) { - if (err && err.code !== 0) { + if (err) { console.error('killProcessWithAccountCallback fail, err: ${JSON.stringify(err)}'); } else { console.log('killProcessWithAccountCallback success.'); @@ -788,7 +788,7 @@ import appManager from '@ohos.app.ability.appManager'; let bundleName = 'bundleName'; function killProcessesByBundleNameCallback(err, data) { - if (err && err.code !== 0) { + if (err) { console.error('killProcessesByBundleNameCallback fail, err: ${JSON.stringify(err)}'); } else { console.log('killProcessesByBundleNameCallback success.'); @@ -884,7 +884,7 @@ import appManager from '@ohos.app.ability.appManager'; let bundleName = 'bundleName'; function clearUpApplicationDataCallback(err, data) { - if (err && err.code !== 0) { + if (err) { console.error('clearUpApplicationDataCallback fail, err: ${JSON.stringify(err)}'); } else { console.log('clearUpApplicationDataCallback success.'); diff --git a/en/application-dev/reference/apis/js-apis-distributedKVStore.md b/en/application-dev/reference/apis/js-apis-distributedKVStore.md index 2db407ff033f6f64ae96c71e8228d770f1242ed4..d1911570c6460214f6d814583359a889dd75d8c8 100644 --- a/en/application-dev/reference/apis/js-apis-distributedKVStore.md +++ b/en/application-dev/reference/apis/js-apis-distributedKVStore.md @@ -23,7 +23,7 @@ import distributedKVStore from '@ohos.data.distributedKVStore'; ## KVManagerConfig -Defines the **KVManager** instance configuration, including the bundle name of the invoker and the application context. +Provides the **KVManager** instance configuration, including the bundle name of the invoker and the application context. **System capability**: SystemCapability.DistributedDataManager.KVStore.Core @@ -127,7 +127,7 @@ Enumerates the distributed KV store types. | Name | Description | | -------------------- | ------------------------------------------------------------ | -| DEVICE_COLLABORATION | Device KV store.
The device KV store manages data by device, which eliminates conflicts. Data can be queried by device.
**System capability**: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore | +| DEVICE_COLLABORATION | Device KV store.
The device KV store manages data by device, which eliminates conflicts. Data can be queried by device.
**System capability**: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore| | SINGLE_VERSION | Single KV store.
The single KV store does not differentiate data by device. If entries with the same key are modified on different devices, the value will be overwritten.
**System capability**: SystemCapability.DistributedDataManager.KVStore.Core | ## SecurityLevel @@ -136,7 +136,7 @@ Enumerates the KV store security levels. **System capability**: SystemCapability.DistributedDataManager.KVStore.Core -| Name | Description | +| Name | Description | | ---: | ------------------------------------------------------------ | | S1 | Low security level. Disclosure, tampering, corruption, or loss of the data may cause minor impact on an individual or group.
Examples: gender and nationality information, and user application records | | S2 | Medium security level. Disclosure, tampering, corruption, or loss of the data may cause major impact on an individual or group.
Examples: mailing addresses and nicknames of individuals | @@ -2028,7 +2028,7 @@ try { deviceId(deviceId:string):Query Creates a **Query** object with the device ID as the key prefix. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -2817,7 +2817,7 @@ try { removeDeviceData(deviceId: string, callback: AsyncCallback<void>): void Deletes data of a device. This API uses an asynchronous callback to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -2869,7 +2869,7 @@ try { removeDeviceData(deviceId: string): Promise<void> Deletes data of a device. This API uses a promise to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -4548,7 +4548,7 @@ try { sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void Synchronizes the KV store manually. For details about the synchronization modes of KV stores, see [Cross-Device Synchronization of KV Stores](../../database/data-sync-of-kv-store.md). -> **NOTE**
+> **NOTE** > > The value of **deviceIds** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. @@ -4617,7 +4617,7 @@ deviceManager.createDeviceManager('bundleName', (err, value) => { sync(deviceIds: string[], query: Query, mode: SyncMode, delayMs?: number): void Synchronizes the KV store manually. This API returns the result synchronously. For details about the synchronization modes of KV stores, see [Cross-Device Synchronization of KV Stores](../../database/data-sync-of-kv-store.md). -> **NOTE**
+> **NOTE** > > The value of **deviceIds** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. @@ -4735,7 +4735,7 @@ Subscribes to synchronization complete events. | Name | Type | Mandatory| Description | | ------------ | --------------------------------------------- | ---- | ------------------------------------------------------ | | event | string | Yes | Event to subscribe to. The value is **syncComplete**, which indicates a synchronization complete event.| -| syncCallback | Callback<Array<[string, number]>> | Yes | Callback invoked to return the synchronization complete event. | +| syncCallback | Callback<Array<[string, number]>> | Yes | Callback invoked to return the synchronization complete event.| **Example** @@ -4769,7 +4769,7 @@ Unsubscribes from data changes. | Name | Type | Mandatory| Description | | -------- | --------------------------------------------------------- | ---- | -------------------------------------------------------- | | event | string | Yes | Event to unsubscribe from. The value is **dataChange**, which indicates a data change event.| -| listener | Callback<[ChangeNotification](#changenotification)> | No | Callback for data changes. | +| listener | Callback<[ChangeNotification](#changenotification)> | No | Callback for the data change event. | **Error codes** @@ -5044,7 +5044,7 @@ try { get(deviceId: string, key: string, callback: AsyncCallback<boolean | string | number | Uint8Array>): void Obtains a string value that matches the specified device ID and key. This API uses an asynchronous callback to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -5099,7 +5099,7 @@ try { get(deviceId: string, key: string): Promise<boolean | string | number | Uint8Array> Obtains a string value that matches the specified device ID and key. This API uses a promise to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -5279,7 +5279,7 @@ try { getEntries(deviceId: string, keyPrefix: string, callback: AsyncCallback<Entry[]>): void Obtains all KV pairs that match the specified device ID and key prefix. This API uses an asynchronous callback to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -5346,7 +5346,7 @@ try { getEntries(deviceId: string, keyPrefix: string): Promise<Entry[]> Obtains all KV pairs that match the specified device ID and key prefix. This API uses a promise to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -5542,7 +5542,7 @@ try { getEntries(deviceId: string, query: Query, callback: AsyncCallback<Entry[]>): void Obtains the KV pairs that match the specified device ID and **Query** object. This API uses an asynchronous callback to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -5614,7 +5614,7 @@ try { getEntries(deviceId: string, query: Query): Promise<Entry[]> Obtains the KV pairs that match the specified device ID and **Query** object. This API uses a promise to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -5822,7 +5822,7 @@ try { getResultSet(deviceId: string, keyPrefix: string, callback: AsyncCallback<KVStoreResultSet>): void Obtains a **KVStoreResultSet** object that matches the specified device ID and key prefix. This API uses an asynchronous callback to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -5877,7 +5877,7 @@ try { getResultSet(deviceId: string, keyPrefix: string): Promise<KVStoreResultSet> Obtains a **KVStoreResultSet** object that matches the specified device ID and key prefix. This API uses a promise to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -5933,7 +5933,7 @@ try { getResultSet(deviceId: string, query: Query, callback: AsyncCallback<KVStoreResultSet>): void Obtains a **KVStoreResultSet** object that matches the specified device ID and **Query** object. This API uses an asynchronous callback to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -6009,7 +6009,7 @@ try { getResultSet(deviceId: string, query: Query): Promise<KVStoreResultSet> Obtains a **KVStoreResultSet** object that matches the specified device ID and **Query** object. This API uses a promise to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -6152,7 +6152,7 @@ try { getResultSet(query: Query, callback:AsyncCallback<KVStoreResultSet>): void Obtains a **KVStoreResultSet** object that matches the specified **Query** object for this device. This API uses an asynchronous callback to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -6341,7 +6341,7 @@ try { getResultSet(deviceId: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void Obtains a **KVStoreResultSet** object that matches the specified predicate object and device ID. This API uses an asynchronous callback to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -6402,7 +6402,7 @@ try { getResultSet(deviceId: string, predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet> Obtains a **KVStoreResultSet** object that matches the specified predicate object and device ID. This API uses a promise to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -6583,7 +6583,7 @@ try { getResultSize(deviceId: string, query: Query, callback: AsyncCallback<number>): void; Obtains the number of results that matches the specified device ID and **Query** object. This API uses an asynchronous callback to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -6650,7 +6650,7 @@ try { getResultSize(deviceId: string, query: Query): Promise<number> Obtains the number of results that matches the specified device ID and **Query** object. This API uses a promise to return the result. -> **NOTE**
+> **NOTE** > > **deviceId** is obtained by [deviceManager.getTrustedDeviceListSync](js-apis-device-manager.md#gettrusteddevicelistsync). The APIs of the **deviceManager** module are system interfaces and available only to system applications. > For details about how to obtain **deviceId**, see [sync()](#sync). @@ -6712,4 +6712,3 @@ try { console.error(`Failed to get resultSize.code is ${e.code},message is ${e.message}`); } ``` - \ No newline at end of file diff --git a/en/application-dev/reference/apis/js-apis-effectKit.md b/en/application-dev/reference/apis/js-apis-effectKit.md index 4bd7c4e7f9ae45e5eef12715f6c54442ff708445..7535b67ab2c14e9596ba59dbfcf6068def89faa0 100644 --- a/en/application-dev/reference/apis/js-apis-effectKit.md +++ b/en/application-dev/reference/apis/js-apis-effectKit.md @@ -29,7 +29,7 @@ Creates a **Filter** instance based on the pixel map. | Name | Type | Mandatory| Description | | ------- | ----------------- | ---- | -------- | -| source | [image.PixelMap](js-apis-image.md#pixelmap7) | Yes | **PixelMap** instance created by the image module. | +| source | [image.PixelMap](js-apis-image.md#pixelmap7) | Yes | **PixelMap** instance created by the image module. An instance can be obtained by decoding an image or directly created. For details, see [Image Overview](../../media/image-overview.md). | **Return value** @@ -61,7 +61,7 @@ Creates a **ColorPicker** instance based on the pixel map. This API uses a promi | Name | Type | Mandatory| Description | | -------- | ----------- | ---- | -------------------------- | -| source | [image.PixelMap](js-apis-image.md#pixelmap7) | Yes | **PixelMap** instance created by the image module.| +| source | [image.PixelMap](js-apis-image.md#pixelmap7) | Yes | **PixelMap** instance created by the image module. An instance can be obtained by decoding an image or directly created. For details, see [Image Overview](../../media/image-overview.md).| **Return value** @@ -95,7 +95,7 @@ Creates a **ColorPicker** instance based on the pixel map. This API uses an asyn | Name | Type | Mandatory| Description | | -------- | ------------------ | ---- | -------------------------- | -| source | [image.PixelMap](js-apis-image.md#pixelmap7) | Yes |**PixelMap** instance created by the image module. | +| source | [image.PixelMap](js-apis-image.md#pixelmap7) | Yes |**PixelMap** instance created by the image module. An instance can be obtained by decoding an image or directly created. For details, see [Image Overview](../../media/image-overview.md). | | callback | AsyncCallback\<[ColorPicker](#colorpicker)> | Yes | Callback used to return the **ColorPicker** instance created.| **Example** 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 6910779cd902d3368ad743ef1f6e4e179f2caf19..994fbe9f8f56a215515692808c776b470b653e5e 100644 --- a/en/application-dev/reference/apis/js-apis-enterprise-accountManager.md +++ b/en/application-dev/reference/apis/js-apis-enterprise-accountManager.md @@ -1,6 +1,6 @@ # @ohos.enterprise.accountManager (Account Management) -The **accountManager** module provides account management capabilities for enterprise devices. Only the enterprise device administrator applications can call the APIs provided by this module. +The **accountManager** module provides APIs for account management of enterprise devices. Only the device administrator applications can call the APIs provided by this module. > **NOTE** > @@ -16,7 +16,7 @@ import accountManager from '@ohos.enterprise.accountManager'; disallowAddLocalAccount(admin: Want, disallow: boolean, callback: AsyncCallback<void>): void -Disallows local accounts. This API uses an asynchronous callback to return the result. +Forbids 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 @@ -28,15 +28,15 @@ Disallows local accounts. This API uses an asynchronous callback to return the r | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | -| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | -| disallow | boolean | Yes | Whether to disallow local accounts. The value **true** means disallow local accounts; the value **false** means the opposite. | +| 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. | | 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 application of the device. | | 9200002 | The administrator application does not have permission to manage the device.| @@ -59,7 +59,7 @@ accountManager.disallowAddLocalAccount(admin, true, (error) => { disallowAddLocalAccount(admin: Want, disallow: boolean): Promise<void> -Disallows local accounts. This API uses a promise to return the result. +Forbids 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 @@ -71,23 +71,23 @@ Disallows local accounts. 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.| -| disallow | boolean | Yes | Whether to disallow local accounts. The value **true** means disallow local accounts; the value **false** means the opposite. | +| 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. | **Return value** | Type | Description | | --------------------- | ------------------------- | -| Promise<void> | Promise that returns no value. | +| 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 | +| 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. | +| 9200001 | The application is not an administrator application of the device. | +| 9200002 | The administrator application does not have permission to manage the device.| **Example** 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 a783a5a457c8537f76a20c02e6ac88db1f5fa3fe..03ce0c6ac23379d8c5d223d52b68edf88ca05a68 100644 --- a/en/application-dev/reference/apis/js-apis-enterprise-dateTimeManager.md +++ b/en/application-dev/reference/apis/js-apis-enterprise-dateTimeManager.md @@ -1,6 +1,6 @@ # @ohos.enterprise.dateTimeManager (System Time Management) -The **dateTimeManager** module provides APIs for system time management, which can only be called by device administrator applications. +The **dateTimeManager** module provides APIs for system time management. Only the enterprise device administrator applications can call the APIs provided by this module. > **NOTE** > @@ -30,7 +30,7 @@ Sets the system time. This API uses an asynchronous callback to return the resul | ----- | ----------------------------------- | ---- | ------- | | admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| | time | number | Yes| Timestamp (ms).| -| callback | AsyncCallback\ | Yes| Callback used to return the result. If the setting is successful, **err** is **null**. Otherwise, **err** is an error object.| +| callback | AsyncCallback\ | Yes| Callback used to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| **Error codes** @@ -101,3 +101,181 @@ dateTimeManager.setDateTime(wantTemp, 1526003846000).then(() => { console.log("error code:" + error.code + " error message:" + error.message); }) ``` + +## dateTimeManager.disallowModifyDateTime10+ + +disallowModifyDateTime(admin: Want, disallow: boolean, callback: AsyncCallback\): void + +Disables modification of the system time. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.ENTERPRISE_SET_DATETIME + +**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.| +| 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.| +| callback | AsyncCallback\ | Yes| Callback used 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", +}; +dateTimeManager.disallowModifyDateTime(wantTemp, true, (error) => { + if (error) { + console.log("error code:" + error.code + " error message:" + error.message); + } +}) +``` + +## dateTimeManager.disallowModifyDateTime10+ + +disallowModifyDateTime(admin: Want, disallow: boolean): Promise\ + +Disables modification of the system time. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.ENTERPRISE_SET_DATETIME + +**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.| +| 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.| + +**Return value** + +| Type | Description | +| ----- | ----------------------------------- | +| Promise\ | that returns no value. If the operation fails, an error object is thrown.| + +**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", +}; +dateTimeManager.disallowModifyDateTime(wantTemp, true).then(() => { +}).catch((error) => { + console.log("error code:" + error.code + " error message:" + error.message); +}) +``` + +## dateTimeManager.isModifyDateTimeDisallowed10+ + +isModifyDateTimeDisallowed(admin: Want, callback: AsyncCallback\): void + +Checks whether modification of the system time is disabled. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.ENTERPRISE_SET_DATETIME + +**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\ | Yes| Callback used to return the result. The value **true** means that modification of the system time is disabled, and **false** means the opposite.| + +**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", +}; +dateTimeManager.isModifyDateTimeDisallowed(wantTemp, (error) => { + if (error) { + console.log("error code:" + error.code + " error message:" + error.message); + } +}) +``` + +## dateTimeManager.isModifyDateTimeDisallowed10+ + +isModifyDateTimeDisallowed(admin: Want): Promise\ + +Checks whether modification of the system time is disabled. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.ENTERPRISE_SET_DATETIME + +**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\ | Promise Promise used to return the result. The value **true** means that modification of the system time is disabled, and **false** means the opposite.| + +**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", +}; +dateTimeManager.disallowModifyDateTime(wantTemp).then(() => { +}).catch((error) => { + console.log("error code:" + error.code + " error message:" + error.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 8e527defb2e34a3269b08f19c6bbd049569cff2e..cf5ecc67a009f4a8f12722ddbb7db823beaa9785 100644 --- a/en/application-dev/reference/apis/js-apis-enterprise-networkManager.md +++ b/en/application-dev/reference/apis/js-apis-enterprise-networkManager.md @@ -1,6 +1,6 @@ # @ohos.enterprise.networkManager (Network Management) -The **networkManager** module provides network management capabilities for enterprise devices, including obtaining the device IP address and MAC address. Only the enterprise device administrator applications can call the APIs provided by this module. +The **networkManager** module provides APIs for network management of enterprise devices, including obtaining the device IP address and MAC address. Only the device administrator applications can call the APIs provided by this module. > **NOTE** > @@ -16,7 +16,7 @@ import networkManager from '@ohos.enterprise.networkManager'; getAllNetworkInterfaces(admin: Want, callback: AsyncCallback<Array<string>>): void -Obtains all active network interfaces. This API uses an asynchronous callback to return the result. +Obtains all active network interfaces through a device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.GET_NETWORK_INFO @@ -28,14 +28,14 @@ Obtains all active network interfaces. This API uses an asynchronous callback to | 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 active network interfaces obtained. | +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application that obtains the information. | +| 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. | **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 application of the device. | | 9200002 | The administrator application does not have permission to manage the device.| @@ -60,7 +60,7 @@ networkManager.getAllNetworkInterfaces(admin, (error, result) => { getAllNetworkInterfaces(admin: Want): Promise<Array<string>> -Obtains all active network interfaces. This API uses a promise to return the result. +Obtains all active network interfaces through a device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_NETWORK_INFO @@ -72,19 +72,19 @@ Obtains all active network interfaces. This API uses a promise to return the res | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | -| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application that obtains the information.| **Return value** | Type | Description | | --------------------- | ------------------------- | -| Promise<Array<string>> | Promise used to return the active network interfaces obtained. | +| Promise<Array<string>> | Promise used to return an array of network interfaces obtained. | **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 application of the device. | | 9200002 | The administrator application does not have permission to manage the device.| @@ -107,7 +107,7 @@ networkManager.getAllNetworkInterfaces(wantTemp).then((result) => { getIpAddress(admin: Want, networkInterface: string, callback: AsyncCallback<string>): void -Obtains the IP address of a device. This API uses an asynchronous callback to return the result. +Obtains the device IP address based on the given network interface through a device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.GET_NETWORK_INFO @@ -119,15 +119,15 @@ Obtains the IP address of a device. This API uses an asynchronous callback to re | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | -| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application that obtains the information. | | networkInterface | string | Yes | Network interface. | -| callback | AsyncCallback<string> | Yes | Callback invoked to return the device IP address obtained. | +| 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** 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 application of the device. | | 9200002 | The administrator application does not have permission to manage the device.| @@ -152,7 +152,7 @@ networkManager.getIpAddress(wantTemp, "eth0", (error, result) => { getIpAddress(admin: Want, networkInterface: string): Promise<string> -Obtains the IP address of a device. This API uses a promise to return the result. +Obtains the device IP address based on the given network interface through a device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_NETWORK_INFO @@ -164,7 +164,7 @@ Obtains the IP address of a device. 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.| +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application that obtains the information.| | networkInterface | string | Yes | Network interface. | **Return value** @@ -177,7 +177,7 @@ Obtains the IP address of a device. This API uses a promise to return the result 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 application of the device. | | 9200002 | The administrator application does not have permission to manage the device.| @@ -200,7 +200,7 @@ networkManager.getIpAddress(wantTemp, "eth0").then((result) => { getMac(admin: Want, networkInterface: string, callback: AsyncCallback<string>): void -Obtains the MAC address of a device. This API uses an asynchronous callback to return the result. +Obtains the device MAC address based on the given network interface through a device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_NETWORK_INFO @@ -212,15 +212,15 @@ Obtains the MAC address of a device. This API uses an asynchronous callback to r | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------- | -| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application that obtains the information. | | networkInterface | string | Yes | Network interface. | -| callback | AsyncCallback<string> | Yes | Callback invoked to return the device MAC address obtained. | +| 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** 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 application of the device. | | 9200002 | The administrator application does not have permission to manage the device.| @@ -245,7 +245,7 @@ networkManager.getMac(wantTemp, "eth0", (error, result) => { getIpAddress(admin: Want, networkInterface: string): Promise<string> -Obtains the MAC address of a device. This API uses a promise to return the result. +Obtain the device MAC address based on the given network interface through a device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_GET_NETWORK_INFO @@ -257,7 +257,7 @@ Obtains the MAC address of a device. This API uses a promise to return the resul | Name | Type | Mandatory | Description | | ----- | ----------------------------------- | ---- | ------- | -| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| +| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application that obtains the information.| | networkInterface | string | Yes | Network interface. | **Return value** @@ -270,7 +270,7 @@ Obtains the MAC address of a device. This API uses a promise to return the resul 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 application of the device. | | 9200002 | The administrator application does not have permission to manage the device.| 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 ae2fac2d6079953025a59cc2eea5b37841e3901c..2f701bc29d707d801def9950042c720cb6754c12 100644 --- a/en/application-dev/reference/apis/js-apis-enterprise-wifiManager.md +++ b/en/application-dev/reference/apis/js-apis-enterprise-wifiManager.md @@ -1,6 +1,6 @@ # @ohos.enterprise.wifiManager (Wi-Fi Management) -The **wifiManager** module provides Wi-Fi management capabilities for enterprise devices. Only the enterprise device administrator applications can call the APIs provided by this module. +The **wifiManager** module provides APIs for Wi-Fi management of enterprise devices. Only the device administrator applications can call the APIs provided by this module. > **NOTE** > @@ -16,7 +16,7 @@ import wifiManager from '@ohos.enterprise.wifiManager'; isWifiActive(admin: Want, callback: AsyncCallback<boolean>): void -Checks whether Wi-Fi is active. This API uses an asynchronous callback to return the result. +Checks whether Wi-Fi is active through a device administrator application. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_WIFI @@ -35,7 +35,7 @@ Checks whether Wi-Fi is active. This API uses an asynchronous callback to return 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 application of the device. | | 9200002 | The administrator application does not have permission to manage the device. | @@ -60,7 +60,7 @@ wifiManager.isWifiActive(wantTemp, (error, result) => { isWifiActive(admin: Want): Promise<boolean> -Checks whether Wi-Fi is active. This API uses a promise to return the result. +Checks whether Wi-Fi is active through a device administrator application. This API uses a promise to return the result. **Required permissions**: ohos.permission.ENTERPRISE_SET_WIFI @@ -84,7 +84,7 @@ Checks whether Wi-Fi is active. This API uses a promise to return the result. 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 application of the device. | | 9200002 | The administrator application does not have permission to manage the device. | @@ -127,7 +127,7 @@ Sets Wi-Fi to connect to the specified network. This API uses an asynchronous ca 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 application of the device. | | 9200002 | The administrator application does not have permission to manage the device. | @@ -176,13 +176,13 @@ Sets Wi-Fi to connect to the specified network. This API uses a promise to retur | 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** 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 application of the device. | | 9200002 | The administrator application does not have permission to manage the device. | diff --git a/en/application-dev/reference/apis/js-apis-file-fileUri.md b/en/application-dev/reference/apis/js-apis-file-fileuri.md similarity index 100% rename from en/application-dev/reference/apis/js-apis-file-fileUri.md rename to en/application-dev/reference/apis/js-apis-file-fileuri.md 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 d210887e3e92e5baea3dd6c7c45ad709e7244587..897d38e76b6614eaa3f4078cbbcb4b5f6ddc893b 100644 --- a/en/application-dev/reference/apis/js-apis-file-fs.md +++ b/en/application-dev/reference/apis/js-apis-file-fs.md @@ -2,7 +2,8 @@ The **fs** module provides APIs for file operations, including basic file management, directory management, file information statistics, and data read and write using a stream. -> **NOTE**
+> **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. ## Modules to Import @@ -11,10 +12,6 @@ The **fs** module provides APIs for file operations, including basic file manage import fs from '@ohos.file.fs'; ``` -## Error Code Description - -The APIs of this module supports processing of error codes. For details about the error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). - ## Guidelines Before using the APIs provided by this module to perform operations on a file or folder, obtain the application sandbox path of the file or folder as follows: @@ -61,9 +58,13 @@ Obtains detailed file information. This API uses a promise to return the result. **Return value** - | Type | Description | - | ---------------------------- | ---------- | - | Promise<[Stat](#stat)> | Promise used to return the file information obtained.| +| Type | Description | +| ---------------------------- | ---------- | +| Promise<[Stat](#stat)> | Promise used to return the file information obtained.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -91,6 +92,10 @@ Obtains detailed file information. This API uses an asynchronous callback to ret | file | string\|number | Yes | Application sandbox path or FD of the file. | | callback | AsyncCallback<[Stat](#stat)> | Yes | Callback invoked to return the file information obtained.| +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -117,12 +122,15 @@ Obtains detailed file information synchronously. | ------ | ------ | ---- | -------------------------- | | file | string\|number | Yes | Application sandbox path or FD of the file.| - **Return value** - | Type | Description | - | ------------- | ---------- | - | [Stat](#stat) | File information obtained.| +| Type | Description | +| ------------- | ---------- | +| [Stat](#stat) | File information obtained.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -147,9 +155,13 @@ Checks whether a file exists. This API uses a promise to return the result. **Return value** - | Type | Description | - | ------------------- | ---------------------------- | - | Promise<boolean> | Promise used to return the result. The value **true** means the file exists; the value **false** means the opposite.| +| Type | Description | +| ------------------- | ---------------------------- | +| Promise<boolean> | Promise used to return the result. The value **true** means the file exists; the value **false** means the opposite.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -164,7 +176,6 @@ Checks whether a file exists. This API uses a promise to return the result. }); ``` - ## fs.access access(path: string, callback: AsyncCallback<boolean>): void @@ -178,7 +189,11 @@ Checks whether a file exists. This API uses an asynchronous callback to return t | Name | Type | Mandatory| Description | | -------- | ------------------------- | ---- | ------------------------------------------------------------ | | path | string | Yes | Application sandbox path of the file. | -| callback | AsyncCallback<boolean> | Yes | Callback invoked to return the result. | +| callback | AsyncCallback<boolean> | Yes | Callback invoked to return the result. The value **true** means the file exists; the value **false** means the opposite.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -211,9 +226,13 @@ Synchronously checks whether a file exists. **Return value** - | Type | Description | - | ------------------- | ---------------------------- | - | boolean | Returns **true** if the file exists; returns **false** otherwise.| +| Type | Description | +| ------------------- | ---------------------------- | +| boolean | Returns **true** if the file exists; returns **false** otherwise.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -240,15 +259,19 @@ Closes a file. This API uses a promise to return the result. **Parameters** - | Name | Type | Mandatory | Description | - | ---- | ------ | ---- | ------------ | - | file | [File](#file)\|number | Yes | File object or FD of the file to close.| +| Name | Type | Mandatory | Description | +| ---- | ------ | ---- | ------------ | +| file | [File](#file)\|number | Yes | File object or FD of the file to close.| **Return value** - | Type | Description | - | ------------------- | ---------------------------- | - | Promise<void> | Promise that returns no value.| +| Type | Description | +| ------------------- | ---------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -273,10 +296,14 @@ Closes a file. This API uses an asynchronous callback to return the result. **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ------------------------- | ---- | ------------ | - | file | [File](#file)\|number | Yes | File object or FD of the file to close.| - | callback | AsyncCallback<void> | Yes | Callback invoked when the file is closed asynchronously.| +| Name | Type | Mandatory | Description | +| -------- | ------------------------- | ---- | ------------ | +| file | [File](#file)\|number | Yes | File object or FD of the file to close.| +| callback | AsyncCallback<void> | Yes | Callback invoked when the file is closed asynchronously.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -302,9 +329,13 @@ Synchronously closes a file. **Parameters** - | Name | Type | Mandatory | Description | - | ---- | ------ | ---- | ------------ | - | file | [File](#file)\|number | Yes | File object or FD of the file to close.| +| Name | Type | Mandatory | Description | +| ---- | ------ | ---- | ------------ | +| file | [File](#file)\|number | Yes | File object or FD of the file to close.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -324,17 +355,21 @@ Copies a file. This API uses a promise to return the result. **Parameters** - | Name | Type | Mandatory | Description | - | ---- | -------------------------- | ---- | ---------------------------------------- | - | src | string\|number | Yes | Path or FD of the file to copy. | - | dest | string\|number | Yes | Destination path of the file or FD of the file created. | - | mode | number | No | Whether to overwrite the file of the same name in the destination path. The default value is **0**, which is the only value supported.
**0**: overwrite the file of the same name.| +| Name | Type | Mandatory | Description | +| ---- | -------------------------- | ---- | ---------------------------------------- | +| src | string\|number | Yes | Path or FD of the file to copy. | +| dest | string\|number | Yes | Destination path of the file or FD of the file created. | +| mode | number | No | Whether to overwrite the file of the same name in the destination path. The default value is **0**, which is the only value supported.
**0**: overwrite the file of the same name.| **Return value** - | Type | Description | - | ------------------- | ---------------------------- | - | Promise<void> | Promise that returns no value.| +| Type | Description | +| ------------------- | ---------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -358,12 +393,16 @@ Copies a file. This API uses an asynchronous callback to return the result. **Parameters** - | Name | Type | Mandatory | Description | - | -------- | -------------------------- | ---- | ---------------------------------------- | - | src | string\|number | Yes | Path or FD of the file to copy. | - | dest | string\|number | Yes | Destination path of the file or FD of the file created. | - | mode | number | No | Whether to overwrite the file of the same name in the destination path. The default value is **0**, which is the only value supported.
**0**: overwrite the file with the same name and truncate the part that is not overwritten.| - | callback | AsyncCallback<void> | Yes | Callback invoked when the file is copied asynchronously. | +| Name | Type | Mandatory | Description | +| -------- | -------------------------- | ---- | ---------------------------------------- | +| src | string\|number | Yes | Path or FD of the file to copy. | +| dest | string\|number | Yes | Destination path of the file or FD of the file created. | +| mode | number | No | Whether to overwrite the file of the same name in the destination path. The default value is **0**, which is the only value supported.
**0**: overwrite the file with the same name and truncate the part that is not overwritten.| +| callback | AsyncCallback<void> | Yes | Callback invoked when the file is copied asynchronously. | + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -390,11 +429,15 @@ Synchronously copies a file. **Parameters** - | Name | Type | Mandatory | Description | - | ---- | -------------------------- | ---- | ---------------------------------------- | - | src | string\|number | Yes | Path or FD of the file to copy. | - | dest | string\|number | Yes | Destination path of the file or FD of the file created. | - | mode | number | No | Whether to overwrite the file of the same name in the destination path. The default value is **0**, which is the only value supported.
**0**: overwrite the file with the same name and truncate the part that is not overwritten.| +| Name | Type | Mandatory | Description | +| ---- | -------------------------- | ---- | ---------------------------------------- | +| src | string\|number | Yes | Path or FD of the file to copy. | +| dest | string\|number | Yes | Destination path of the file or FD of the file created. | +| mode | number | No | Whether to overwrite the file of the same name in the destination path. The default value is **0**, which is the only value supported.
**0**: overwrite the file with the same name and truncate the part that is not overwritten.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -404,7 +447,6 @@ Synchronously copies a file. fs.copyFileSync(srcPath, dstPath); ``` - ## fs.mkdir mkdir(path: string): Promise<void> @@ -421,9 +463,13 @@ Creates a directory. This API uses a promise to return the result. **Return value** - | Type | Description | - | ------------------- | ---------------------------- | - | Promise<void> | Promise that returns no value.| +| Type | Description | +| ------------------- | ---------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -436,7 +482,6 @@ Creates a directory. This API uses a promise to return the result. }); ``` - ## fs.mkdir mkdir(path: string, callback: AsyncCallback<void>): void @@ -452,6 +497,10 @@ Creates a directory. This API uses an asynchronous callback to return the result | path | string | Yes | Application sandbox path of the directory. | | callback | AsyncCallback<void> | Yes | Callback invoked when the directory is created asynchronously. | +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -465,7 +514,6 @@ Creates a directory. This API uses an asynchronous callback to return the result }); ``` - ## fs.mkdirSync mkdirSync(path: string): void @@ -480,6 +528,10 @@ Synchronously creates a directory. | ------ | ------ | ---- | ------------------------------------------------------------ | | path | string | Yes | Application sandbox path of the directory. | +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -487,7 +539,6 @@ Synchronously creates a directory. fs.mkdirSync(dirPath); ``` - ## fs.open open(path: string, mode?: number): Promise<File> @@ -505,9 +556,13 @@ Opens a file. This API uses a promise to return the result. File uniform resourc **Return value** - | Type | Description | - | --------------------- | ----------- | - | Promise<[File](#file)> | Promise used to return the file object.| +| Type | Description | +| --------------------- | ----------- | +| Promise<[File](#file)> | Promise used to return the file object.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -536,6 +591,10 @@ Opens a file. This API uses an asynchronous callback to return the result. File | 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.| +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -566,9 +625,13 @@ Synchronously opens a file. File URIs are supported. **Return value** - | Type | Description | - | ------ | ----------- | - | [File](#file) | File object opened.| +| Type | Description | +| ------ | ----------- | +| [File](#file) | File object opened.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -597,9 +660,13 @@ Reads data from a file. This API uses a promise to return the result. **Return value** - | Type | Description | - | ---------------------------------- | ------ | - | Promise<number> | Promise used to return the data read.| +| Type | Description | +| ---------------------------------- | ------ | +| Promise<number> | Promise used to return the data read.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -626,12 +693,16 @@ Reads data from a file. This API uses an asynchronous callback to return the res **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ---------------------------------------- | ---- | ---------------------------------------- | - | 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.| - | callback | AsyncCallback<number> | Yes | Callback invoked when the data is read asynchronously. | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| 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.| +| callback | AsyncCallback<number> | Yes | Callback invoked when the data is read asynchronously. | + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -650,7 +721,6 @@ Reads data from a file. This API uses an asynchronous callback to return the res }); ``` - ## fs.readSync readSync(fd: number, buffer: ArrayBuffer, options?: { offset?: number; length?: number; }): number @@ -661,17 +731,21 @@ Synchronously reads data from a file. **Parameters** - | Name | Type | Mandatory | Description | - | ------- | ----------- | ---- | ---------------------------------------- | - | 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.| +| Name | Type | Mandatory | Description | +| ------- | ----------- | ---- | ---------------------------------------- | +| 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.| **Return value** - | Type | Description | - | ------ | -------- | - | number | Length of the data read.| +| Type | Description | +| ------ | -------- | +| number | Length of the data read.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -683,7 +757,6 @@ Synchronously reads data from a file. fs.closeSync(file); ``` - ## fs.rmdir rmdir(path: string): Promise<void> @@ -700,9 +773,13 @@ Deletes a directory. This API uses a promise to return the result. **Return value** - | Type | Description | - | ------------------- | ---------------------------- | - | Promise<void> | Promise that returns no value.| +| Type | Description | +| ------------------- | ---------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -715,7 +792,6 @@ Deletes a directory. This API uses a promise to return the result. }); ``` - ## fs.rmdir rmdir(path: string, callback: AsyncCallback<void>): void @@ -731,6 +807,10 @@ Deletes a directory. This API uses an asynchronous callback to return the result | path | string | Yes | Application sandbox path of the directory.| | callback | AsyncCallback<void> | Yes | Callback invoked when the directory is deleted asynchronously. | +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -744,7 +824,6 @@ Deletes a directory. This API uses an asynchronous callback to return the result }); ``` - ## fs.rmdirSync rmdirSync(path: string): void @@ -759,6 +838,10 @@ Synchronously deletes a directory. | ------ | ------ | ---- | -------------------------- | | path | string | Yes | Application sandbox path of the directory.| +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -766,7 +849,6 @@ Synchronously deletes a directory. fs.rmdirSync(dirPath); ``` - ## fs.unlink unlink(path: string): Promise<void> @@ -783,9 +865,13 @@ Deletes a file. This API uses a promise to return the result. **Return value** - | Type | Description | - | ------------------- | ---------------------------- | - | Promise<void> | Promise that returns no value.| +| Type | Description | +| ------------------- | ---------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -798,7 +884,6 @@ Deletes a file. This API uses a promise to return the result. }); ``` - ## fs.unlink unlink(path: string, callback: AsyncCallback<void>): void @@ -814,6 +899,10 @@ Deletes a file. This API uses an asynchronous callback to return the result. | path | string | Yes | Application sandbox path of the file.| | callback | AsyncCallback<void> | Yes | Callback invoked when the file is deleted asynchronously. | +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -827,7 +916,6 @@ Deletes a file. This API uses an asynchronous callback to return the result. }); ``` - ## fs.unlinkSync unlinkSync(path: string): void @@ -842,6 +930,10 @@ Synchronously deletes a file. | ------ | ------ | ---- | -------------------------- | | path | string | Yes | Application sandbox path of the file.| +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -860,17 +952,21 @@ Writes data into a file. This API uses a promise to return the result. **Parameters** - | Name | Type | Mandatory | Description | - | ------- | ------------------------------- | ---- | ---------------------------------------- | - | 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.| +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------------------------------------- | +| 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.| **Return value** - | Type | Description | - | --------------------- | -------- | - | Promise<number> | Promise used to return the length of the data written.| +| Type | Description | +| --------------------- | -------- | +| Promise<number> | Promise used to return the length of the data written.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -885,7 +981,6 @@ Writes data into a file. This API uses a promise to return the result. }); ``` - ## fs.write write(fd: number, buffer: ArrayBuffer|string, options?: { offset?: number; length?: number; encoding?: string; }, callback: AsyncCallback<number>): void @@ -896,12 +991,16 @@ Writes data into a file. This API uses an asynchronous callback to return the re **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ------------------------------- | ---- | ---------------------------------------- | - | 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.| - | callback | AsyncCallback<number> | Yes | Callback invoked when the data is written asynchronously. | +| Name | Type | Mandatory | Description | +| -------- | ------------------------------- | ---- | ---------------------------------------- | +| 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.| +| callback | AsyncCallback<number> | Yes | Callback invoked when the data is written asynchronously. | + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -918,7 +1017,6 @@ Writes data into a file. This API uses an asynchronous callback to return the re }); ``` - ## fs.writeSync writeSync(fd: number, buffer: ArrayBuffer|string, options?: { offset?: number; length?: number; encoding?: string; }): number @@ -929,17 +1027,21 @@ Synchronously writes data into a file. **Parameters** - | Name | Type | Mandatory | Description | - | ------- | ------------------------------- | ---- | ---------------------------------------- | - | 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.| +| Name | Type | Mandatory | Description | +| ------- | ------------------------------- | ---- | ---------------------------------------- | +| 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.| **Return value** - | Type | Description | - | ------ | -------- | - | number | Length of the data written in the file.| +| Type | Description | +| ------ | -------- | +| number | Length of the data written in the file.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -968,9 +1070,13 @@ Truncates a file. This API uses a promise to return the result. **Return value** - | Type | Description | - | ------------------- | ---------------------------- | - | Promise<void> | Promise that returns no value.| +| Type | Description | +| ------------------- | ---------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -984,7 +1090,6 @@ Truncates a file. This API uses a promise to return the result. }); ``` - ## fs.truncate truncate(file: string|number, len?: number, callback: AsyncCallback<void>): void @@ -1001,6 +1106,10 @@ Truncates a file. This API uses an asynchronous callback to return the result. | len | number | No | File length, in bytes, after truncation. The default value is **0**.| | callback | AsyncCallback<void> | Yes | Callback that returns no value. | +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -1015,7 +1124,6 @@ Truncates a file. This API uses an asynchronous callback to return the result. }); ``` - ## fs.truncateSync truncateSync(file: string|number, len?: number): void @@ -1031,6 +1139,10 @@ Synchronously truncates a file. | file | string\|number | Yes | Application sandbox path or FD of the file. | | len | number | No | File length, in bytes, after truncation. The default value is **0**.| +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -1039,7 +1151,6 @@ Synchronously truncates a file. fs.truncateSync(filePath, len); ``` - ## fs.readText readText(filePath: string, options?: { offset?: number; length?: number; encoding?: string; }): Promise<string> @@ -1057,9 +1168,13 @@ Reads the text content of a file. This API uses a promise to return the result. **Return value** - | Type | Description | - | --------------------- | ---------- | - | Promise<string> | Promise used to return the content read.| +| Type | Description | +| --------------------- | ---------- | +| Promise<string> | Promise used to return the content read.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1072,7 +1187,6 @@ Reads the text content of a file. This API uses a promise to return the result. }); ``` - ## fs.readText readText(filePath: string, options?: { offset?: number; length?: number; encoding?: string; }, callback: AsyncCallback<string>): void @@ -1089,6 +1203,10 @@ Reads the text content of a file. This API uses an asynchronous callback to retu | 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.| | callback | AsyncCallback<string> | Yes | Callback invoked to return the content read. | +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -1102,7 +1220,6 @@ Reads the text content of a file. This API uses an asynchronous callback to retu }); ``` - ## fs.readTextSync readTextSync(filePath: string, options?: { offset?: number; length?: number; encoding?: string; }): string @@ -1120,9 +1237,13 @@ Synchronously reads the text of a file. **Return value** - | Type | Description | - | ------ | -------------------- | - | string | Promise used to return the content of the file read.| +| Type | Description | +| ------ | -------------------- | +| string | Promise used to return the content of the file read.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1148,9 +1269,13 @@ Obtains information about a symbolic link. This API uses a promise to return the **Return value** - | Type | Description | - | ---------------------------- | ---------- | - | Promise<[Stat](#stat)> | Promise used to return the symbolic link information obtained. For details, see **stat**.| +| Type | Description | +| ---------------------------- | ---------- | +| Promise<[Stat](#stat)> | Promise used to return the symbolic link information obtained. For details, see **stat**.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1163,7 +1288,6 @@ Obtains information about a symbolic link. This API uses a promise to return the }); ``` - ## fs.lstat lstat(path: string, callback: AsyncCallback<Stat>): void @@ -1179,6 +1303,10 @@ Obtains information about a symbolic link. This API uses an asynchronous callbac | path | string | Yes | Application sandbox path of the file.| | callback | AsyncCallback<[Stat](#stat)> | Yes | Callback invoked to return the symbolic link information obtained. | +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -1208,9 +1336,13 @@ Obtains information about a symbolic link synchronously. **Return value** - | Type | Description | - | ------------- | ---------- | - | [Stat](#stat) | File information obtained.| +| Type | Description | +| ------------- | ---------- | +| [Stat](#stat) | File information obtained.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1236,9 +1368,13 @@ Renames a file or folder. This API uses a promise to return the result. **Return value** - | Type | Description | - | ------------------- | ---------------------------- | - | Promise<void> | Promise that returns no value.| +| Type | Description | +| ------------------- | ---------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1268,6 +1404,10 @@ Renames a file or folder. This API uses an asynchronous callback to return the r | newPath | string | Yes | Application sandbox path of the renamed file. | | callback | AsyncCallback<void> | Yes | Callback invoked when the file is asynchronously renamed. | +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -1297,6 +1437,10 @@ Renames a file or folder synchronously. | oldPath | string | Yes | Application sandbox path of the file to rename.| | newPath | string | Yes | Application sandbox path of the renamed file. | +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -1305,7 +1449,6 @@ Renames a file or folder synchronously. fs.renameSync(srcFile, dstFile); ``` - ## fs.fsync fsync(fd: number): Promise<void> @@ -1316,15 +1459,19 @@ Flushes data of a file to disk. This API uses a promise to return the result. **Parameters** - | Name | Type | Mandatory | Description | - | ---- | ------ | ---- | ------------ | - | fd | number | Yes | FD of the file.| +| Name | Type | Mandatory | Description | +| ---- | ------ | ---- | ------------ | +| fd | number | Yes | FD of the file.| **Return value** - | Type | Description | - | ------------------- | ---------------------------- | - | Promise<void> | Promise that returns no value.| +| Type | Description | +| ------------------- | ---------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1338,7 +1485,6 @@ Flushes data of a file to disk. This API uses a promise to return the result. }); ``` - ## fs.fsync fsync(fd: number, callback: AsyncCallback<void>): void @@ -1349,10 +1495,14 @@ Flushes data of a file to disk. This API uses an asynchronous callback to return **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ------------------------- | ---- | --------------- | - | fd | number | Yes | FD of the file. | - | Callback | AsyncCallback<void> | Yes | Callback invoked when the file data is synchronized in asynchronous mode.| +| Name | Type | Mandatory | Description | +| -------- | ------------------------- | ---- | --------------- | +| fd | number | Yes | FD of the file. | +| Callback | AsyncCallback<void> | Yes | Callback invoked when the file data is synchronized in asynchronous mode.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1380,9 +1530,13 @@ Flushes data of a file to disk synchronously. **Parameters** - | Name | Type | Mandatory | Description | - | ---- | ------ | ---- | ------------ | - | fd | number | Yes | FD of the file.| +| Name | Type | Mandatory | Description | +| ---- | ------ | ---- | ------------ | +| fd | number | Yes | FD of the file.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1393,7 +1547,6 @@ Flushes data of a file to disk synchronously. fs.closeSync(file); ``` - ## fs.fdatasync fdatasync(fd: number): Promise<void> @@ -1404,15 +1557,19 @@ Flushes data of a file to disk. This API uses a promise to return the result. ** **Parameters** - | Name | Type | Mandatory | Description | - | ---- | ------ | ---- | ------------ | - | fd | number | Yes | FD of the file.| +| Name | Type | Mandatory | Description | +| ---- | ------ | ---- | ------------ | +| fd | number | Yes | FD of the file.| **Return value** - | Type | Description | - | ------------------- | ---------------------------- | - | Promise<void> | Promise that returns no value.| +| Type | Description | +| ------------------- | ---------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1427,7 +1584,6 @@ Flushes data of a file to disk. This API uses a promise to return the result. ** }); ``` - ## fs.fdatasync fdatasync(fd: number, callback: AsyncCallback<void>): void @@ -1438,10 +1594,14 @@ Flushes data of a file to disk. This API uses an asynchronous callback to return **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ------------------------------- | ---- | ----------------- | - | fd | number | Yes | FD of the file. | - | callback | AsyncCallback<void> | Yes | Callback invoked when the file data is synchronized in asynchronous mode.| +| Name | Type | Mandatory | Description | +| -------- | ------------------------------- | ---- | ----------------- | +| fd | number | Yes | FD of the file. | +| callback | AsyncCallback<void> | Yes | Callback invoked when the file data is synchronized in asynchronous mode.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1468,9 +1628,13 @@ Synchronizes data in a file synchronously. **Parameters** - | Name | Type | Mandatory | Description | - | ---- | ------ | ---- | ------------ | - | fd | number | Yes | FD of the file.| +| Name | Type | Mandatory | Description | +| ---- | ------ | ---- | ------------ | +| fd | number | Yes | FD of the file.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1481,7 +1645,6 @@ Synchronizes data in a file synchronously. fs.closeSync(file); ``` - ## fs.symlink symlink(target: string, srcPath: string): Promise<void> @@ -1499,9 +1662,13 @@ Creates a symbolic link based on a file path. This API uses a promise to return **Return value** - | Type | Description | - | ------------------- | ---------------------------- | - | Promise<void> | Promise that returns no value.| +| Type | Description | +| ------------------- | ---------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1531,6 +1698,10 @@ Creates a symbolic link based on a file path. This API uses an asynchronous call | srcPath | string | Yes | Application sandbox path of the symbolic link. | | callback | AsyncCallback<void> | Yes | Callback invoked when the symbolic link is created asynchronously.| +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -1560,6 +1731,10 @@ Synchronously creates a symbolic link based on a file path. | target | string | Yes | Application sandbox path of the source file. | | srcPath | string | Yes | Application sandbox path of the symbolic link.| +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -1581,24 +1756,28 @@ Lists all files in a directory. This API uses a promise to return the result.
- **0**: Throw an exception if the destination directory has folders of the same names with the source folder.
- **1**: Throw an exception if the destination directory has files of the same names with the source folder. All files without conflicts in the source folder are moved to the destination folder, and all files without conflicts in the destination folder are retained. The **data** in the error thrown provides information about the conflict files.
- **2**: Forcibly overwrite the files with the same names in the destination folder. The files with the the same names in the destination folder are overwritten forcibly; the files without conflicts in the destination folder are retained.
- **3**: Forcibly overwrite the destination folder. Move the source folder to the destination directory and make the destination folder completely the same as the source folder. All the original files in the destination folder are not retained.| +| Name | Type | Mandatory | Description | +| ------ | ------ | ---- | --------------------------- | +| src | string | Yes | Application sandbox path of the source folder.| +| dest | string | Yes | Application sandbox path of the destination folder.| +| mode | number | No | Mode for moving the folder. The default value is **0**.
- **0**: Throw an exception if the destination directory has folders of the same names with the source folder.
- **1**: Throw an exception if the destination directory has files of the same names with the source folder. All files without conflicts in the source folder are moved to the destination folder, and all files without conflicts in the destination folder are retained. The **data** in the error thrown provides information about the conflict files.
- **2**: Forcibly overwrite the files with the same names in the destination folder. The files with the the same names in the destination folder are overwritten forcibly; the files without conflicts in the destination folder are retained.
- **3**: Forcibly overwrite the destination folder. Move the source folder to the destination directory and make the destination folder completely the same as the source folder. All the original files in the destination folder are not retained.| **Return value** - | Type | Description | - | ------------------- | ---------------------------- | - | Promise<void> | Promise that returns no value.| +| Type | Description | +| ------------------- | ---------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1776,12 +1967,16 @@ Moves a folder. This API uses an asynchronous callback to return the result. **Parameters** - | Name | Type | Mandatory | Description | - | ------ | ------ | ---- | --------------------------- | - | src | string | Yes | Application sandbox path of the source folder.| - | dest | string | Yes | Application sandbox path of the destination folder.| - | mode | number | No | Whether to overwrite the file of the same name in the destination directory. The default value is **0**.
- **0**: Throw an exception if the destination directory has folders of the same names with the source folder.
- **1**: Throw an exception if the destination directory has files of the same names with the source folder. All files without conflicts in the source folder are moved to the destination folder, and all files without conflicts in the destination folder are retained. The **data** in the error thrown provides information about the conflict files.
- **2**: Forcibly overwrite the files with the same names in the destination folder. The files with the the same names in the destination folder are overwritten forcibly; the files without conflicts in the destination folder are retained.
- **3**: Forcibly overwrite the destination folder. Move the source folder to the destination directory and make the destination folder completely the same as the source folder. All the original files in the destination folder are not retained.| - | callback | AsyncCallback<void> | Yes | Callback invoked when the folder is moved. | +| Name | Type | Mandatory | Description | +| ------ | ------ | ---- | --------------------------- | +| src | string | Yes | Application sandbox path of the source folder.| +| dest | string | Yes | Application sandbox path of the destination folder.| +| mode | number | No | Mode for moving the folder. The default value is **0**.
- **0**: Throw an exception if the destination directory has folders of the same names with the source folder.
- **1**: Throw an exception if the destination directory has files of the same names with the source folder. All files without conflicts in the source folder are moved to the destination folder, and all files without conflicts in the destination folder are retained. The **data** in the error thrown provides information about the conflict files.
- **2**: Forcibly overwrite the files with the same names in the destination folder. The files with the the same names in the destination folder are overwritten forcibly; the files without conflicts in the destination folder are retained.
- **3**: Forcibly overwrite the destination folder. Move the source folder to the destination directory and make the destination folder completely the same as the source folder. All the original files in the destination folder are not retained.| +| callback | AsyncCallback<void> | Yes | Callback invoked when the folder is moved. | + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1813,17 +2008,21 @@ Moves a file. This API uses a promise to return the result. **Parameters** - | Name | Type | Mandatory | Description | - | ------ | ------ | ---- | --------------------------- | - | src | string | Yes | Application sandbox path of the source file.| - | dest | string | Yes | Application sandbox path of the destination file.| - | mode | number | No | Whether to overwrite the file of the same name in the destination directory. The value **0** means to overwrite the file of the same name in the destination directory. The value **1** means to throw an exception if a file of the same name exists in the destination directory. The default value is **0**.| +| Name | Type | Mandatory | Description | +| ------ | ------ | ---- | --------------------------- | +| src | string | Yes | Application sandbox path of the source file.| +| dest | string | Yes | Application sandbox path of the destination file.| +| mode | number | No | Whether to overwrite the file of the same name in the destination directory. The value **0** means to overwrite the file of the same name in the destination directory. The value **1** means to throw an exception if a file of the same name exists in the destination directory. The default value is **0**.| **Return value** - | Type | Description | - | ------------------- | ---------------------------- | - | Promise<void> | Promise that returns no value.| +| Type | Description | +| ------------------- | ---------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1847,12 +2046,16 @@ Moves a file. This API uses an asynchronous callback to return the result. **Parameters** - | Name | Type | Mandatory | Description | - | ------ | ------ | ---- | --------------------------- | - | src | string | Yes | Application sandbox path of the source file.| - | dest | string | Yes | Application sandbox path of the destination file.| - | mode | number | No | Whether to overwrite the file of the same name in the destination directory. The value **0** means to overwrite the file of the same name in the destination directory. The value **1** means to throw an exception if a file of the same name exists in the destination directory. The default value is **0**.| - | callback | AsyncCallback<void> | Yes | Callback invoked when the file is moved. | +| Name | Type | Mandatory | Description | +| ------ | ------ | ---- | --------------------------- | +| src | string | Yes | Application sandbox path of the source file.| +| dest | string | Yes | Application sandbox path of the destination file.| +| mode | number | No | Whether to overwrite the file of the same name in the destination directory. The value **0** means to overwrite the file of the same name in the destination directory. The value **1** means to throw an exception if a file of the same name exists in the destination directory. The default value is **0**.| +| callback | AsyncCallback<void> | Yes | Callback invoked when the file is moved. | + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1878,11 +2081,15 @@ Moves a file synchronously. **Parameters** - | Name | Type | Mandatory | Description | - | ------ | ------ | ---- | --------------------------- | - | src | string | Yes | Application sandbox path of the source file.| - | dest | string | Yes | Application sandbox path of the destination file.| - | mode | number | No | Whether to overwrite the file of the same name in the destination directory. The value **0** means to overwrite the file of the same name in the destination directory. The value **1** means to throw an exception if a file of the same name exists in the destination directory. The default value is **0**.| +| Name | Type | Mandatory | Description | +| ------ | ------ | ---- | --------------------------- | +| src | string | Yes | Application sandbox path of the source file.| +| dest | string | Yes | Application sandbox path of the destination file.| +| mode | number | No | Whether to overwrite the file of the same name in the destination directory. The value **0** means to overwrite the file of the same name in the destination directory. The value **1** means to throw an exception if a file of the same name exists in the destination directory. The default value is **0**.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1903,15 +2110,19 @@ Creates a temporary directory. This API uses a promise to return the result. **Parameters** - | Name | Type | Mandatory | Description | - | ------ | ------ | ---- | --------------------------- | - | prefix | string | Yes | A randomly generated string used to replace "XXXXXX" in a directory.| +| Name | Type | Mandatory | Description | +| ------ | ------ | ---- | --------------------------- | +| prefix | string | Yes | A randomly generated string used to replace "XXXXXX" in a directory.| **Return value** - | Type | Description | - | --------------------- | ---------- | - | Promise<string> | Promise used to return the unique directory generated.| +| Type | Description | +| --------------------- | ---------- | +| Promise<string> | Promise used to return the unique directory generated.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1923,7 +2134,6 @@ Creates a temporary directory. This API uses a promise to return the result. }); ``` - ## fs.mkdtemp mkdtemp(prefix: string, callback: AsyncCallback<string>): void @@ -1934,10 +2144,14 @@ Creates a temporary directory. This API uses an asynchronous callback to return **Parameters** - | Name | Type | Mandatory | Description | - | -------- | --------------------------- | ---- | --------------------------- | - | prefix | string | Yes | A randomly generated string used to replace "XXXXXX" in a directory.| - | callback | AsyncCallback<string> | Yes | Callback invoked when a temporary directory is created asynchronously. | +| Name | Type | Mandatory | Description | +| -------- | --------------------------- | ---- | --------------------------- | +| prefix | string | Yes | A randomly generated string used to replace "XXXXXX" in a directory.| +| callback | AsyncCallback<string> | Yes | Callback invoked when a temporary directory is created asynchronously. | + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -1961,21 +2175,25 @@ Synchronously creates a temporary directory. **Parameters** - | Name | Type | Mandatory | Description | - | ------ | ------ | ---- | --------------------------- | - | prefix | string | Yes | A randomly generated string used to replace "XXXXXX" in a directory.| +| Name | Type | Mandatory | Description | +| ------ | ------ | ---- | --------------------------- | +| prefix | string | Yes | A randomly generated string used to replace "XXXXXX" in a directory.| **Return value** - | Type | Description | - | ------ | ---------- | - | string | Unique path generated.| +| Type | Description | +| ------ | ---------- | +| string | Unique path generated.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** ```js let res = fs.mkdtempSync(pathDir + "/XXXXXX"); - ``` + ``` ## fs.createStream @@ -1994,9 +2212,13 @@ Creates a stream based on the file path. This API uses a promise to return the r **Return value** - | Type | Description | - | --------------------------------- | --------- | - | Promise<[Stream](#stream)> | Promise used to return the result.| +| Type | Description | +| --------------------------------- | --------- | +| Promise<[Stream](#stream)> | Promise used to return the result.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2026,6 +2248,10 @@ Creates a stream based on the file path. This API uses an asynchronous callback | 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 created asynchronously. | +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -2056,9 +2282,13 @@ Synchronously creates a stream based on the file path. **Return value** - | Type | Description | - | ------------------ | --------- | - | [Stream](#stream) | Stream opened.| +| Type | Description | +| ------------------ | --------- | +| [Stream](#stream) | Stream opened.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2072,22 +2302,26 @@ Synchronously creates a stream based on the file path. fdopenStream(fd: number, mode: string): Promise<Stream> -Opens a stream based on the file descriptor. This API uses a promise to return the result. +Opens a stream based on the FD. This API uses a promise to return the result. **System capability**: SystemCapability.FileManagement.File.FileIO **Parameters** - | Name | Type | Mandatory | Description | - | ---- | ------ | ---- | ---------------------------------------- | - | 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).| +| Name | Type | Mandatory | Description | +| ---- | ------ | ---- | ---------------------------------------- | +| 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).| **Return value** - | Type | Description | - | --------------------------------- | --------- | - | Promise<[Stream](#stream)> | Promise used to return the result.| +| Type | Description | +| --------------------------------- | --------- | +| Promise<[Stream](#stream)> | Promise used to return the result.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2102,22 +2336,25 @@ Opens a stream based on the file descriptor. This API uses a promise to return t }); ``` - ## fs.fdopenStream fdopenStream(fd: number, mode: string, callback: AsyncCallback<Stream>): void -Opens a stream based on the file descriptor. This API uses an asynchronous callback to return the result. +Opens a stream based on the FD. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.FileManagement.File.FileIO **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ---------------------------------------- | ---- | ---------------------------------------- | - | 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 open asynchronously. | +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ---------------------------------------- | +| 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 open asynchronously. | + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2138,22 +2375,26 @@ Opens a stream based on the file descriptor. This API uses an asynchronous callb fdopenStreamSync(fd: number, mode: string): Stream -Synchronously opens a stream based on the file descriptor. +Synchronously opens a stream based on the FD. **System capability**: SystemCapability.FileManagement.File.FileIO **Parameters** - | Name | Type | Mandatory | Description | - | ---- | ------ | ---- | ---------------------------------------- | - | 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).| +| Name | Type | Mandatory | Description | +| ---- | ------ | ---- | ---------------------------------------- | +| 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).| **Return value** - | Type | Description | - | ------------------ | --------- | - | [Stream](#stream) | Stream opened.| +| Type | Description | +| ------------------ | --------- | +| [Stream](#stream) | Stream opened.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2176,17 +2417,21 @@ Creates a **Watcher** object to observe file or directory changes. **Parameters** - | Name | Type | Mandatory | Description | - | ---- | ------ | ---- | ---------------------------------------- | - | path | string | Yes | Application sandbox path of the file or directory to observe. | - | events | number | Yes | Events to observe. Multiple events can be separated by a bitwise OR operator (|)|.
- **0x1: IN_ACCESS**: A file is accessed.
- **0x2: IN_MODIFY**: The file content is modified.
- **0x4: IN_ATTRIB**: Metadata is changed.
- **0x8: IN_CLOSE_WRITE**: The file opened for writing is closed.
- **0x10: IN_CLOSE_NOWRITE**: The file or directory not opened for writing is closed.
- **0x20: IN_OPEN**: A file or directory is opened.
- **0x40: IN_MOVED_FROM**: A file in the observed directory is moved.
- **0x80: IN_MOVED_TO**: A file is moved to the observed directory.
- **0x100: IN_CREATE**: A file or directory is created in the observed directory.
- **0x200: IN_DELETE**: A file or directory is deleted from the observed directory.
- **0x400: IN_DELETE_SELF**: The observed directory is deleted. After the directory is deleted, the listening stops.
- **0x800: IN_MOVE_SELF**: The observed file or directory is moved. After the file or directory is moved, the listening continues.
- **0xfff: IN_ALL_EVENTS**: All events.| - | listener | WatchEventListener | Yes | Callback invoked when an observed event occurs. The callback will be invoked each time an observed event occurs. | +| Name | Type | Mandatory | Description | +| ---- | ------ | ---- | ---------------------------------------- | +| path | string | Yes | Application sandbox path of the file or directory to observe. | +| events | number | Yes | Events to observe. Multiple events can be separated by a bitwise OR operator (|)|.
- **0x1: IN_ACCESS**: A file is accessed.
- **0x2: IN_MODIFY**: The file content is modified.
- **0x4: IN_ATTRIB**: Metadata is changed.
- **0x8: IN_CLOSE_WRITE**: The file opened for writing is closed.
- **0x10: IN_CLOSE_NOWRITE**: The file or directory not opened for writing is closed.
- **0x20: IN_OPEN**: A file or directory is opened.
- **0x40: IN_MOVED_FROM**: A file in the observed directory is moved.
- **0x80: IN_MOVED_TO**: A file is moved to the observed directory.
- **0x100: IN_CREATE**: A file or directory is created in the observed directory.
- **0x200: IN_DELETE**: A file or directory is deleted from the observed directory.
- **0x400: IN_DELETE_SELF**: The observed directory is deleted. After the directory is deleted, the listening stops.
- **0x800: IN_MOVE_SELF**: The observed file or directory is moved. After the file or directory is moved, the listening continues.
- **0xfff: IN_ALL_EVENTS**: All events.| +| listener | WatchEventListener | Yes | Callback invoked when an observed event occurs. The callback will be invoked each time an observed event occurs. | **Return value** - | Type | Description | - | ------------------ | --------- | - | [Watcher](#watcher10) | **Watcher** object created.| +| Type | Description | +| ------------------ | --------- | +| [Watcher](#watcher10) | **Watcher** object created.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2218,10 +2463,10 @@ Called when an observed event occurs. **Parameters** - | Name | Type | Mandatory | Description | - | ---- | ------ | ---- | ---------------------------------------- | - | event | WatchEvent | Yes | Event for the callback to invoke. | - +| Name | Type | Mandatory | Description | +| ---- | ------ | ---- | ---------------------------------------- | +| event | WatchEvent | Yes | Event for the callback to invoke. | + ## WatchEvent10+ Defines the event to observe. @@ -2245,7 +2490,7 @@ Represents detailed file information. Before calling any API of the **Stat()** c ### Attributes | Name | Type | Readable | Writable | Description | -| ------ | ------ | ---- | ---- | ---------------------------------------- | +| ------ | ------ | ---- | ---- | ---------------------------------------- | | ino | number | Yes | No | File ID. Different files on the same device have different **ino**s.| | | mode | number | Yes | No | File permissions. The meaning of each bit is as follows:
- **0o400**: The owner has the read permission on a regular file or a directory entry.
- **0o200**: The owner has the permission to write a regular file or create and delete a directory entry.
- **0o100**: The owner has the permission to execute a regular file or search for the specified path in a directory.
- **0o040**: The user group has the read permission on a regular file or a directory entry.
- **0o020**: The user group has the permission to write a regular file or create and delete a directory entry.
- **0o010**: The user group has the permission to execute a regular file or search for the specified path in a directory.
- **0o004**: Other users have the permission to read a regular file or read a directory entry.
- **0o002**: Other users have the permission to write a regular file or create and delete a directory entry.
- **0o001**: Other users have the permission to execute a regular file or search for the specified path in a directory.| | uid | number | Yes | No | ID of the file owner.| @@ -2255,7 +2500,6 @@ Represents detailed file information. Before calling any API of the **Stat()** c | mtime | number | Yes | No | Time of the last modification to the file. The value is the number of seconds elapsed since 00:00:00 on January 1, 1970. | | ctime | number | Yes | No | Time of the last status change of the file. The value is the number of seconds elapsed since 00:00:00 on January 1, 1970. | - ### isBlockDevice isBlockDevice(): boolean @@ -2266,9 +2510,13 @@ Checks whether this file is a block special file. A block special file supports **Return value** - | Type | Description | - | ------- | ---------------- | - | boolean | Whether the file is a block special file.| +| Type | Description | +| ------- | ---------------- | +| boolean | Whether the file is a block special file.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2287,9 +2535,13 @@ Checks whether this file is a character special file. A character special file s **Return value** - | Type | Description | - | ------- | ----------------- | - | boolean | Whether the file is a character special file.| +| Type | Description | +| ------- | ----------------- | +| boolean | Whether the file is a character special file.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2298,7 +2550,6 @@ Checks whether this file is a character special file. A character special file s let isCharacterDevice = fs.statSync(filePath).isCharacterDevice(); ``` - ### isDirectory isDirectory(): boolean @@ -2309,9 +2560,13 @@ Checks whether this file is a directory. **Return value** - | Type | Description | - | ------- | ------------- | - | boolean | Whether the file is a directory.| +| Type | Description | +| ------- | ------------- | +| boolean | Whether the file is a directory.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2320,7 +2575,6 @@ Checks whether this file is a directory. let isDirectory = fs.statSync(dirPath).isDirectory(); ``` - ### isFIFO isFIFO(): boolean @@ -2331,9 +2585,13 @@ Checks whether this file is a named pipe (or FIFO). Named pipes are used for int **Return value** - | Type | Description | - | ------- | --------------------- | - | boolean | Whether the file is a FIFO.| +| Type | Description | +| ------- | --------------------- | +| boolean | Whether the file is a FIFO.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2342,7 +2600,6 @@ Checks whether this file is a named pipe (or FIFO). Named pipes are used for int let isFIFO = fs.statSync(filePath).isFIFO(); ``` - ### isFile isFile(): boolean @@ -2353,9 +2610,13 @@ Checks whether this file is a regular file. **Return value** - | Type | Description | - | ------- | --------------- | - | boolean | Whether the file is a regular file.| +| Type | Description | +| ------- | --------------- | +| boolean | Whether the file is a regular file.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2364,7 +2625,6 @@ Checks whether this file is a regular file. let isFile = fs.statSync(filePath).isFile(); ``` - ### isSocket isSocket(): boolean @@ -2375,9 +2635,13 @@ Checks whether this file is a socket. **Return value** - | Type | Description | - | ------- | -------------- | - | boolean | Whether the file is a socket.| +| Type | Description | +| ------- | -------------- | +| boolean | Whether the file is a socket.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2386,7 +2650,6 @@ Checks whether this file is a socket. let isSocket = fs.statSync(filePath).isSocket(); ``` - ### isSymbolicLink isSymbolicLink(): boolean @@ -2397,9 +2660,13 @@ Checks whether this file is a symbolic link. **Return value** - | Type | Description | - | ------- | --------------- | - | boolean | Whether the file is a symbolic link.| +| Type | Description | +| ------- | --------------- | +| boolean | Whether the file is a symbolic link.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2412,7 +2679,6 @@ Checks whether this file is a symbolic link. Provides a stream for file operations. Before calling any API of the **Stream** class, use **createStream()** to create a **Stream** instance synchronously or asynchronously. - ### close close(): Promise<void> @@ -2423,9 +2689,13 @@ Closes the stream. This API uses a promise to return the result. **Return value** - | Type | Description | - | ------------------- | ------------- | - | Promise<void> | Promise used to return the stream close result.| +| Type | Description | +| ------------------- | ------------- | +| Promise<void> | Promise used to return the stream close result.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2439,7 +2709,6 @@ Closes the stream. This API uses a promise to return the result. }); ``` - ### close close(callback: AsyncCallback<void>): void @@ -2450,9 +2719,13 @@ Closes the stream. This API uses an asynchronous callback to return the result. **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ------------------------- | ---- | ------------- | - | callback | AsyncCallback<void> | Yes | Callback invoked when the stream is closed asynchronously.| +| Name | Type | Mandatory | Description | +| -------- | ------------------------- | ---- | ------------- | +| callback | AsyncCallback<void> | Yes | Callback invoked when the stream is closed asynchronously.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2476,6 +2749,10 @@ Synchronously closes the stream. **System capability**: SystemCapability.FileManagement.File.FileIO +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -2494,9 +2771,13 @@ Flushes the stream. This API uses a promise to return the result. **Return value** - | Type | Description | - | ------------------- | ------------- | - | Promise<void> | Promise used to return the stream flushing result.| +| Type | Description | +| ------------------- | ------------- | +| Promise<void> | Promise used to return the stream flushing result.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2510,7 +2791,6 @@ Flushes the stream. This API uses a promise to return the result. }); ``` - ### flush flush(callback: AsyncCallback<void>): void @@ -2521,9 +2801,13 @@ Flushes the stream. This API uses an asynchronous callback to return the result. **Parameters** - | Name | Type | Mandatory | Description | - | -------- | ------------------------- | ---- | -------------- | - | callback | AsyncCallback<void> | Yes | Callback invoked when the stream is asynchronously flushed.| +| Name | Type | Mandatory | Description | +| -------- | ------------------------- | ---- | -------------- | +| callback | AsyncCallback<void> | Yes | Callback invoked when the stream is asynchronously flushed.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2547,6 +2831,10 @@ Synchronously flushes the stream. **System capability**: SystemCapability.FileManagement.File.FileIO +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -2565,16 +2853,20 @@ Writes data into the stream. This API uses a promise to return the result. **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 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.| +| 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.| **Return value** - | Type | Description | - | --------------------- | -------- | - | Promise<number> | Promise used to return the length of the data written.| +| Type | Description | +| --------------------- | -------- | +| Promise<number> | Promise used to return the length of the data written.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2588,7 +2880,6 @@ Writes data into the stream. This API uses a promise to return the result. }); ``` - ### write write(buffer: ArrayBuffer|string, options?: { offset?: number; length?: number; encoding?: string; }, callback: AsyncCallback<number>): void @@ -2599,11 +2890,15 @@ Writes data into the stream. This API uses an asynchronous callback to return th **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 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. | +| 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.| +| callback | AsyncCallback<number> | Yes | Callback invoked when the data is written asynchronously. | + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2631,16 +2926,20 @@ Synchronously writes data into the stream. **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 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.| +| 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.| **Return value** - | Type | Description | - | ------ | -------- | - | number | Length of the data written in the file.| +| Type | Description | +| ------ | -------- | +| number | Length of the data written in the file.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2660,16 +2959,20 @@ Reads data from the stream. This API uses a promise to return the result. **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): position of the data to read in the file. By default, data is read from the current position.| +| 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.| **Return value** - | Type | Description | - | ---------------------------------- | ------ | - | Promise<number> | Promise used to return the data read.| +| Type | Description | +| ---------------------------------- | ------ | +| Promise<number> | Promise used to return the data read.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2685,7 +2988,6 @@ Reads data from the stream. This API uses a promise to return the result. }); ``` - ### read read(buffer: ArrayBuffer, options?: { position?: number; offset?: number; length?: number; }, callback: AsyncCallback<number>): void @@ -2696,11 +2998,15 @@ Reads data from the stream. This API uses an asynchronous callback to return the **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): position of the data to read in the file. 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. | +| 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.| +| callback | AsyncCallback<number> | Yes | Callback invoked when data is read asynchronously from the stream. | + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2728,16 +3034,20 @@ Synchronously reads data from the stream. **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): position of the data to read in the file. By default, data is read from the current position.
| +| 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.
| **Return value** - | Type | Description | - | ------ | -------- | - | number | Length of the data read.| +| Type | Description | +| ------ | -------- | +| number | Length of the data read.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2769,15 +3079,19 @@ Applies an exclusive lock or a shared lock on this file in blocking mode. This A **Parameters** - | Name | Type | Mandatory | Description | - | ------- | ----------- | ---- | ---------------------------------------- | - | exclusive | boolean | No | Lock to apply. The value **true** means an exclusive lock, and the value **false** (default) means a shared lock. | +| Name | Type | Mandatory | Description | +| ------- | ----------- | ---- | ---------------------------------------- | +| exclusive | boolean | No | Lock to apply. The value **true** means an exclusive lock, and the value **false** (default) means a shared lock. | **Return value** - | Type | Description | - | ---------------------------------- | ------ | - | Promise<void> | Promise that returns no value.| +| Type | Description | +| ---------------------------------- | ------ | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2800,10 +3114,14 @@ Applies an exclusive lock or a shared lock on this file in blocking mode. This A **Parameters** - | Name | Type | Mandatory | Description | - | ------- | ----------- | ---- | ---------------------------------------- | - | exclusive | boolean | No | Lock to apply. The value **true** means an exclusive lock, and the value **false** (default) means a shared lock. | - | callback | AsyncCallback<void> | Yes | Callback invoked when the file is locked. | +| Name | Type | Mandatory | Description | +| ------- | ----------- | ---- | ---------------------------------------- | +| exclusive | boolean | No | Lock to apply. The value **true** means an exclusive lock, and the value **false** (default) means a shared lock. | +| callback | AsyncCallback<void> | Yes | Callback invoked when the file is locked. | + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2828,9 +3146,13 @@ Applies an exclusive lock or a shared lock on this file in non-blocking mode. **Parameters** - | Name | Type | Mandatory | Description | - | ------- | ----------- | ---- | ---------------------------------------- | - | exclusive | boolean | No | Lock to apply. The value **true** means an exclusive lock, and the value **false** (default) means a shared lock. | +| Name | Type | Mandatory | Description | +| ------- | ----------- | ---- | ---------------------------------------- | +| exclusive | boolean | No | Lock to apply. The value **true** means an exclusive lock, and the value **false** (default) means a shared lock. | + +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -2848,6 +3170,10 @@ Unlocks this file synchronously. **System capability**: SystemCapability.FileManagement.File.FileIO +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -2871,6 +3197,10 @@ Starts listening. **System capability**: SystemCapability.FileManagement.File.FileIO +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js @@ -2890,6 +3220,10 @@ Stops listening. **System capability**: SystemCapability.FileManagement.File.FileIO +**Error codes** + +For details about error codes, see "Basic File I/O Error Codes" in [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js diff --git a/en/application-dev/reference/apis/js-apis-geolocation.md b/en/application-dev/reference/apis/js-apis-geolocation.md index de7d46dc6b83bb64d24cb5a0e6c5c1857616c329..55231a6428aa7afde89de961a4b51d127e50d9ce 100644 --- a/en/application-dev/reference/apis/js-apis-geolocation.md +++ b/en/application-dev/reference/apis/js-apis-geolocation.md @@ -1,4 +1,4 @@ -# Geolocation +# @ohos.geolocation (Geolocation) The **geolocation** module provides a wide array of location services, including GNSS positioning, network positioning, geocoding, reverse geocoding, and geofencing. diff --git a/en/application-dev/reference/apis/js-apis-inner-application-abilityDelegator.md b/en/application-dev/reference/apis/js-apis-inner-application-abilityDelegator.md index 550e888888a944644c79cefec596c0f5df28ca64..ecefd737a3d799824efeadcb903cc032038c87a9 100644 --- a/en/application-dev/reference/apis/js-apis-inner-application-abilityDelegator.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-abilityDelegator.md @@ -6,6 +6,12 @@ The **AbilityDelegator** module provides APIs for managing **AbilityMonitor** in > > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. +## Modules to Import + +```ts +import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; +``` + ## Usage An **AbilityDelegator** object is obtained by calling [getAbilityDelegator](js-apis-app-ability-abilityDelegatorRegistry.md#abilitydelegatorregistrygetabilitydelegator) in **AbilityDelegatorRegistry**. @@ -30,10 +36,18 @@ Adds an **AbilityMonitor** instance. This API uses an asynchronous callback to r | monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| | callback | AsyncCallback\ | Yes | Callback used to return the result. | +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | AddAbilityMonitor failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; function onAbilityCreateCallback(data) { console.info('onAbilityCreateCallback, data: ${JSON.stringify(data)}'); @@ -70,10 +84,18 @@ Adds an **AbilityMonitor** instance. This API uses a promise to return the resul | -------------- | ------------------- | | Promise\ | Promise used to return the result.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | AddAbilityMonitor failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; function onAbilityCreateCallback(data) { console.info('onAbilityCreateCallback'); @@ -105,10 +127,18 @@ Removes an **AbilityMonitor** instance. This API uses an asynchronous callback t | monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| | callback | AsyncCallback\ | Yes | Callback used to return the result. | +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | RemoveAbilityMonitor failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; function onAbilityCreateCallback(data) { console.info('onAbilityCreateCallback'); @@ -145,10 +175,18 @@ Removes an **AbilityMonitor** instance. This API uses a promise to return the re | -------------- | ------------------- | | Promise\ | Promise used to return the result.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | RemoveAbilityMonitor failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + - Example ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; function onAbilityCreateCallback(data) { console.info('onAbilityCreateCallback'); @@ -180,10 +218,18 @@ Waits for the **Ability** instance that matches the **AbilityMonitor** instance | monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| | callback | AsyncCallback\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result. | +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | WaitAbilityMonitor failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; function onAbilityCreateCallback(data) { console.info('onAbilityCreateCallback'); @@ -196,7 +242,7 @@ let monitor = { abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); abilityDelegator.waitAbilityMonitor(monitor, (error : any, data : any) => { - if (error && error.code !== 0) { + if (error) { console.error('waitAbilityMonitor fail, error: ${JSON.stringify(error)}'); } else { console.log('waitAbilityMonitor success, data: ${JSON.stringify(data)}'); @@ -220,10 +266,18 @@ Waits a period of time for the **Ability** instance that matches the **AbilityMo | timeout | number | No | Maximum waiting time, in milliseconds. | | callback | AsyncCallback\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result. | +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | WaitAbilityMonitor failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let timeout = 100; function onAbilityCreateCallback(data) { @@ -268,10 +322,18 @@ Waits a period of time for the **Ability** instance that matches the **AbilityMo | ----------------------------------------------------------- | -------------------------- | | Promise\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Promise used to return the **Ability** instance.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | WaitAbilityMonitor failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; function onAbilityCreateCallback(data) { console.info('onAbilityCreateCallback'); @@ -305,7 +367,7 @@ Obtains the application context. **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); let context = abilityDelegator.getAppContext(); @@ -334,7 +396,7 @@ Obtains the lifecycle state of an ability. **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let ability; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); @@ -360,10 +422,18 @@ Obtains the top ability of this application. This API uses an asynchronous callb | -------- | ------------------------------------------------------------ | ---- | ------------------ | | callback | AsyncCallback\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | GetCurrentTopAbility failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let ability; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); @@ -387,10 +457,18 @@ Obtains the top ability of this application. This API uses a promise to return t | ----------------------------------------------------------- | -------------------------------------- | | Promise\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Promise used to return the top ability.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | GetCurrentTopAbility failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let ability; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); @@ -415,10 +493,30 @@ Starts an ability. This API uses an asynchronous callback to return the result. | want | [Want](js-apis-application-want.md) | Yes | **Want** parameter for starting the ability. | | callback | AsyncCallback\ | Yes | Callback used to return the result.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000001 | The specified ability does not exist. | +| 16000002 | Incorrect ability type. | +| 16000004 | Can not start invisible component. | +| 16000005 | The specified process does not have the permission. | +| 16000006 | Cross-user operations are not allowed. | +| 16000008 | The crowdtesting application expires. | +| 16000009 | An ability cannot be started or stopped in Wukong mode. | +| 16000010 | The call with the continuation flag is forbidden. | +| 16000011 | The context does not exist. | +| 16000050 | Internal error. | +| 16000053 | The ability is not on the top of the UI. | +| 16000055 | Installation-free timed out. | +| 16200001 | The caller has been released. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let want = { bundleName: 'bundleName', abilityName: 'abilityName' @@ -450,10 +548,30 @@ Starts an ability. This API uses a promise to return the result. | -------------- | ------------------- | | Promise\ | Promise used to return the result.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000001 | The specified ability does not exist. | +| 16000002 | Incorrect ability type. | +| 16000004 | Can not start invisible component. | +| 16000005 | The specified process does not have the permission. | +| 16000006 | Cross-user operations are not allowed. | +| 16000008 | The crowdtesting application expires. | +| 16000009 | An ability cannot be started or stopped in Wukong mode. | +| 16000010 | The call with the continuation flag is forbidden. | +| 16000011 | The context does not exist. | +| 16000050 | Internal error. | +| 16000053 | The ability is not on the top of the UI. | +| 16000055 | Installation-free timed out. | +| 16200001 | The caller has been released. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let want = { bundleName: 'bundleName', abilityName: 'abilityName' @@ -480,10 +598,18 @@ Schedules the lifecycle state of an ability to **Foreground**. This API uses an | ability | UIAbility | Yes | Target ability. | | callback | AsyncCallback\ | Yes | Callback used to return the result.
\- **true**: The operation is successful.
\- **false**: The operation failed.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | DoAbilityForeground failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let ability; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); @@ -516,10 +642,18 @@ Schedules the lifecycle state of an ability to **Foreground**. This API uses a p | ----------------- | ------------------------------------------------------------ | | Promise\ | Promise used to return the result.
\- **true**: The operation is successful.
\- **false**: The operation failed.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | DoAbilityForeground failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let ability; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); @@ -547,10 +681,18 @@ Schedules the lifecycle state of an ability to **Background**. This API uses an | ability | UIAbility | Yes | Target ability. | | callback | AsyncCallback\ | Yes | Callback used to return the result.
\- **true**: The operation is successful.
\- **false**: The operation failed.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | DoAbilityBackground failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let ability; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); @@ -583,10 +725,18 @@ Schedules the lifecycle state of an ability to **Background**. This API uses a p | ----------------- | ------------------------------------------------------------ | | Promise\ | Promise used to return the result.
\- **true**: The operation is successful.
\- **false**: The operation failed.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | DoAbilityBackground failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let ability; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); @@ -616,7 +766,7 @@ Prints log information to the unit test console. **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let msg = 'msg'; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); @@ -641,7 +791,7 @@ Prints log information to the unit test console. This API uses an asynchronous c **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let msg = 'msg'; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); @@ -673,7 +823,7 @@ Prints log information to the unit test console. This API uses a promise to retu **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let msg = 'msg'; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); @@ -700,7 +850,7 @@ Executes a shell command. This API uses an asynchronous callback to return the r **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let cmd = 'cmd'; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); @@ -728,7 +878,7 @@ Executes a shell command with the timeout period specified. This API uses an asy **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let cmd = 'cmd'; let timeout = 100; @@ -762,7 +912,7 @@ Executes a shell command with the timeout period specified. This API uses a prom **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let cmd = 'cmd'; let timeout = 100; @@ -788,10 +938,18 @@ Finishes the test and prints log information to the unit test console. This API | code | number | Yes | Log code. | | callback | AsyncCallback\ | Yes | Callback used to return the result.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | FinishTest failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let msg = 'msg'; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); @@ -821,10 +979,18 @@ Finishes the test and prints log information to the unit test console. This API | -------------- | ------------------- | | Promise\ | Promise used to return the result.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | FinishTest failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let msg = 'msg'; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); @@ -848,10 +1014,18 @@ Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes | monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| | callback | AsyncCallback\ | Yes | Callback used to return the result. | +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | AddAbilityStageMonitor failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let monitor = { moduleName: 'moduleName', @@ -884,10 +1058,18 @@ Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes | -------------- | ------------------- | | Promise\ | Promise used to return the result.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | AddAbilityStageMonitor failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let monitor = { moduleName: 'moduleName', @@ -915,10 +1097,18 @@ Removes an **AbilityStageMonitor** instance from the application memory. This AP | monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| | callback | AsyncCallback\ | Yes | Callback used to return the result. | +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | RemoveAbilityStageMonitor failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let monitor = { moduleName: 'moduleName', @@ -951,10 +1141,18 @@ Removes an **AbilityStageMonitor** object from the application memory. This API | -------------- | ------------------- | | Promise\ | Promise used to return the result.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | RemoveAbilityStageMonitor failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let monitor = { moduleName: 'moduleName', @@ -982,10 +1180,18 @@ Waits for an **AbilityStage** instance that matches the conditions set in an **A | monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| | callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, an **AbilityStage** instance is returned. Otherwise, no value is returned. | +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | WaitAbilityStageMonitor failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; function onAbilityCreateCallback(data) { console.info('onAbilityCreateCallback'); @@ -1023,10 +1229,18 @@ Waits for an **AbilityStage** instance that matches the conditions set in an **A | -------------- | ------------------- | | Promise\ | Promise used to return the result. If the operation is successful, an **AbilityStage** instance is returned. Otherwise, no value is returned.| +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | WaitAbilityStageMonitor failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; function onAbilityCreateCallback(data) { console.info('onAbilityCreateCallback'); @@ -1059,10 +1273,18 @@ Waits a period of time for an **AbilityStage** instance that matches the conditi | timeout | number | No | Maximum waiting time, in milliseconds.| | callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, an **AbilityStage** instance is returned. Otherwise, no value is returned. | +**Error codes** + +| ID| Error Message| +| ------- | -------- | +| 16000100 | WaitAbilityStageMonitor failed. | + +For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + **Example** ```ts -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let timeout = 100; function onAbilityCreateCallback(data) { diff --git a/en/application-dev/reference/apis/js-apis-inner-application-abilityMonitor.md b/en/application-dev/reference/apis/js-apis-inner-application-abilityMonitor.md index e64c3175c7934190d70af04156c149741c87697c..476fb18d73deaf6c82912be806ce31eb8891095f 100644 --- a/en/application-dev/reference/apis/js-apis-inner-application-abilityMonitor.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-abilityMonitor.md @@ -6,6 +6,12 @@ The **AbilityMonitor** module provides monitors for abilities that meet specifie > > 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. +## Modules to Import + +```ts +import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; +``` + ## Usage **AbilityMonitor** can be used as an input parameter of [addAbilityMonitor](js-apis-inner-application-abilityDelegator.md#addabilitymonitor9) in **abilityDelegator** to listen for lifecycle changes of an ability. @@ -43,9 +49,9 @@ let monitor = { onAbilityCreate: onAbilityCreateCallback }; -let abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); abilityDelegator.addAbilityMonitor(monitor, (error : any) => { - if (error && error.code !== 0) { + if (error) { console.error('addAbilityMonitor fail, error: ${JSON.stringify(error)}'); } }); diff --git a/en/application-dev/reference/apis/js-apis-inner-application-abilityRunningInfo.md b/en/application-dev/reference/apis/js-apis-inner-application-abilityRunningInfo.md index f041998eb633cf8d00b45613b666ca563189dd77..337f71f71550f8d8b7e5031fe1091b2da38e3056 100644 --- a/en/application-dev/reference/apis/js-apis-inner-application-abilityRunningInfo.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-abilityRunningInfo.md @@ -6,6 +6,12 @@ The **AbilityRunningInfo** module defines the running information and state of a > > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. +## Modules to Import + +```ts +import abilitymanager from '@ohos.app.ability.abilityManager'; +``` + ## Usage The ability running information is obtained by calling [getAbilityRunningInfos](js-apis-app-ability-abilityManager.md#getabilityrunninginfos) in **abilityManager**. @@ -31,7 +37,7 @@ The ability running information is obtained by calling [getAbilityRunningInfos]( import abilitymanager from '@ohos.app.ability.abilityManager'; abilitymanager.getAbilityRunningInfos((error, data) => { - if (error && error.code !== 0) { + if (error) { console.error('getAbilityRunningInfos fail, error: ${JSON.stringify(error)}'); } else { console.log('getAbilityRunningInfos success, data: ${JSON.stringify(data)}'); diff --git a/en/application-dev/reference/apis/js-apis-inner-application-abilityStageMonitor.md b/en/application-dev/reference/apis/js-apis-inner-application-abilityStageMonitor.md index 90fa9dc102e3f38498451bcf23a117321be08be9..c462bb3e3e3ee33d99a8e84db77ff656e4bdc80c 100644 --- a/en/application-dev/reference/apis/js-apis-inner-application-abilityStageMonitor.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-abilityStageMonitor.md @@ -1,6 +1,7 @@ # AbilityStageMonitor -The **AbilityStageMonitor** module provides conditions for matching **AbilityStage** instances. The most recently matched **AbilityStage** instance is saved in an **AbilityStageMonitor** instance. +The **AbilityStageMonitor** module provides conditions for matching **AbilityStage** instances. The most recently matched **AbilityStage** instance is saved in an **AbilityStageMonitor** instance. + **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -20,7 +21,7 @@ let monitor = { let abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); abilityDelegator.waitAbilityStageMonitor(monitor, (error, data) => { - if (error && error.code !== 0) { + if (error) { console.error('waitAbilityStageMonitor fail, error: ${JSON.stringify(error)}'); } else { console.log('waitAbilityStageMonitor success, data: ${JSON.stringify(data)}'); diff --git a/en/application-dev/reference/apis/js-apis-inner-application-processInformation.md b/en/application-dev/reference/apis/js-apis-inner-application-processInformation.md index d2ee664b5fade510aabf9a0113e4ce406e2f6af4..3c3822f6ca370ff23cdda5631cb06f926db2b284 100644 --- a/en/application-dev/reference/apis/js-apis-inner-application-processInformation.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-processInformation.md @@ -6,6 +6,12 @@ The **ProcessInformation** module defines the running information of a process. > > 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. +## Modules to Import + +```ts +import appManager from '@ohos.app.ability.appManager'; +``` + ## How to Use The process information is obtained by calling [getRunningProcessInformation](js-apis-app-ability-appManager.md#appmanagergetrunningprocessinformation9) of the **appManager** module. @@ -14,7 +20,7 @@ The process information is obtained by calling [getRunningProcessInformation](js import appManager from '@ohos.app.ability.appManager'; appManager.getRunningProcessInformation((error, data) => { - if (error && error.code !== 0) { + if (error) { console.error('getRunningProcessInformation fail, error: ${JSON.stringify(error)}'); } else { console.log('getRunningProcessInformation success, data: ${JSON.stringify(data)}'); diff --git a/en/application-dev/reference/apis/js-apis-inner-application-shellCmdResult.md b/en/application-dev/reference/apis/js-apis-inner-application-shellCmdResult.md index ca376d9776ffc064b82468e7c3af596a86faba53..1692916d936d2688792a9a793f75bb4855e215a3 100644 --- a/en/application-dev/reference/apis/js-apis-inner-application-shellCmdResult.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-shellCmdResult.md @@ -6,6 +6,12 @@ The **ShellCmdResult** module provides the shell command execution result. > > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. +## Modules to Import + +```ts +import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; +``` + **System capability**: SystemCapability.Ability.AbilityRuntime.Core | Name | Type | Readable| Writable| Description | @@ -20,12 +26,12 @@ The result is obtained by calling [executeShellCommand](js-apis-inner-applicatio **Example** ```ts import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; -let abilityDelegator; +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; let cmd = 'cmd'; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); abilityDelegator.executeShellCommand(cmd, (error: any, data: any) => { - if (error && error.code !== 0) { + if (error) { console.error('executeShellCommand fail, error: ${JSON.stringify(error)}'); } else { console.log('executeShellCommand success, data: ${JSON.stringify(data)}'); diff --git a/en/application-dev/reference/apis/js-apis-logs.md b/en/application-dev/reference/apis/js-apis-logs.md index 48cc7954e1b4315f0e12d9571395decf9592b90d..b2d837bae04d378938b355d535971cf6d56e48c5 100644 --- a/en/application-dev/reference/apis/js-apis-logs.md +++ b/en/application-dev/reference/apis/js-apis-logs.md @@ -1,30 +1,41 @@ -# console (Log) +# console (Log Printing) -> **NOTE**
-> The APIs of this module are no longer maintained since API version 7. You are advised to use ['@ohos.hilog](js-apis-hilog.md)' instead. +The **console** module provides basic log printing capabilities and supports log printing by log level. + +If you want to use more advanced log printing services, for example, filtering logs by the specified ID, you are advised to use [`@ohos.hilog`](js-apis-hilog.md). + +> **NOTE** +> +> The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## console.debug debug(message: string): void -Prints debug logs. +Prints debug-level logs. + +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** -- Parameters - | Name | Type | Mandatory | Description | - | ------- | ------ | ---- | ----------- | - | message | string | Yes | Text to print.| +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| message | string | Yes | Text to print.| ## console.log log(message: string): void -Prints debug logs. +Prints debug-level logs. -- Parameters - | Name | Type | Mandatory | Description | - | ------- | ------ | ---- | ----------- | - | message | string | Yes | Text to print.| +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| message | string | Yes | Text to print.| ## console.info @@ -33,10 +44,13 @@ info(message: string): void Prints info-level logs. -- Parameters - | Name | Type | Mandatory | Description | - | ------- | ------ | ---- | ----------- | - | message | string | Yes | Text to print.| +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| message | string | Yes | Text to print.| ## console.warn @@ -45,10 +59,13 @@ warn(message: string): void Prints warn-level logs. -- Parameters - | Name | Type | Mandatory | Description | - | ------- | ------ | ---- | ----------- | - | message | string | Yes | Text to print.| +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| message | string | Yes | Text to print.| ## console.error @@ -57,13 +74,16 @@ error(message: string): void Prints error-level logs. -- Parameters - | Name | Type | Mandatory | Description | - | ------- | ------ | ---- | ----------- | - | message | string | Yes | Text to print.| +**System capability**: SystemCapability.ArkUI.ArkUI.Full + +**Parameters** +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| message | string | Yes | Text to print.| -## Example + +**Example** ``` export default { @@ -78,4 +98,261 @@ export default { Switch to the HiLog window at the bottom of HUAWEI DevEco Studio. Specifically, select the current device and process, set the log level to Info, and enter Hello World in the search box. Logs that meet the search criteria are displayed, as shown in the following figure. -![en-us_image_0000001200913929](figures/en-us_image_0000001200913929.png) +![Printing logs](figures/printing-logs.png) + +## console.assert10+ + +assert(value?: Object, ...arguments: Object[]): void + +If **value** is false, the subsequent content will be printed. + +**System capability**: SystemCapability.Utils.Lang + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| value | Object | No | Value| +| arguments | Object | No | Prints error messages.| + +**Example** +``` +console.assert(true, 'does nothing'); + +console.assert(false, 'console %s work', 'didn\'t'); +// Assertion console:ohos didn't work + +console.assert(); +// Assertion failed +``` +## console.count10+ + +count(label?: string): void + +Adds a counter by the specified label name to count the number of times **console.count()** is called. The default value is **default**. + +**System capability**: SystemCapability.Utils.Lang + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| label | string | No | Counter label name.| + +**Example** +``` +console.count() +// default: 1 +console.count('default') +// default: 2 +console.count('abc') +// abc: 1 +console.count('xyz') +// xyz: 1 +console.count('abc') +abc: 2 +console.count() +// default: 3 +``` + +## console.countReset10+ + +countReset(label?: string): void + +Resets a counter by the specified label name. The default value is **default**. + +**System capability**: SystemCapability.Utils.Lang + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| label | string | No | Counter label name.| + +**Example** +``` +console.count('abc'); +// abc: 1 +console.countReset('abc'); +console.count('abc'); +// abc: 1 +``` + +## console.dir10+ + +dir(dir?: Object): void + +Prints content of the specified object. + +**System capability**: SystemCapability.Utils.Lang + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| dir | Object | No | Object whose content needs to be printed.| + +## console.dirxml10+ + +dirxml(...arguments: Object[]): void + +Calls **console.log()** and passes the received parameters to it. This API does not produce any content of the XML format. + +**System capability**: SystemCapability.Utils.Lang + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| arguments | Object | No | Information to be printed.| + +## console.group10+ + +group(...arguments: Object[]): void + +Creates an inline group so that subsequent lines are indented by the value specified by **groupIndentation**. +If the information to be printed is provided, the information is printed without extra indentation. + +**System capability**: SystemCapability.Utils.Lang + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| arguments | Object | No | Information to be printed.| +## console.groupCollapsed10+ + +groupCollapsed(...arguments: Object[]): void + +Creates a collapsed inline group. + +**System capability**: SystemCapability.Utils.Lang + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| arguments | Object | No | Information to be printed.| + +## console.groupEnd10+ + +groupEnd(): void + +Exits an inline group so that subsequent lines are not indented by the value specified by **groupIndentation** . + +**System capability**: SystemCapability.Utils.Lang + +## console.table10+ + +table(tableData?: Object): void + +Prints data in a table. + +**System capability**: SystemCapability.Utils.Lang + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| tableData | Object | No | Data to be printed in a table.| + +**Example** +``` +console.table([1, 2, 3]); +// ┌─────────┬────────┐ +// │ (index) │ Values │ +// ├─────────┼────────┤ +// │ 0 │ 1 │ +// │ 1 │ 2 │ +// │ 2 │ 3 │ +// └─────────┴────────┘ + +console.table({ a: [1, 2, 3, 4, 5], b: 5, c: { e: 5 } }); + +// ┌─────────┬───┬───┬───┬───┬───┬───┬────────┐ +// │ (index) │ 0 │ 1 │ 2 │ 3 │ 4 │ e │ Values │ +// ├─────────┼───┼───┼───┼───┼───┼───┼────────┤ +// │ a │ 1 │ 2 │ 3 │ 4 │ 5 │ │ │ +// │ b │ │ │ │ │ │ │ 5 │ +// │ c │ │ │ │ │ │ 5 │ │ +// └─────────┴───┴───┴───┴───┴───┴───┴────────┘ +``` +## console.time10+ + +time(label?: string): void + +Starts a timer to track the duration of an operation. The default value is **default**. You can use **console.timeEnd()** to disable the timer and print the result. + +**System capability**: SystemCapability.Utils.Lang + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| label | string | No | Timer label.| + +## console.timeEnd10+ + +timeEnd(label?: string): void + +Stops the timer started by **console.time()** and prints the result. The default value is **default**. + +**System capability**: SystemCapability.Utils.Lang + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| label | string | No | Timer label.| + +**Example** +``` +console.time('abc'); +console.timeEnd('abc'); +// abc: 225.438ms +``` + +## console.timeLog10+ + +timeLog(label?: string, ...arguments: Object[]): void + +Prints the elapsed time and other logs for the timer started by **console.time()**. + +**System capability**: SystemCapability.Utils.Lang + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| label | string | No | Timer label.| +| arguments | Object | No | Logs to be printed.| + +**Example** +``` +console.time('timer1'); +const value = aaa (); // Return 17. +console.timeLog('timer1', value); +// timer1: 365.227ms 17 +console.timeEnd('timer1'); +// timer1: 513.22ms +``` + +## console.trace10+ + +trace(...arguments: Object[]): void + +Creates a stack trace. + +**System capability**: SystemCapability.Utils.Lang + +**Parameters** + +| Name | Type | Mandatory | Description | +| ------- | ------ | ---- | ----------- | +| arguments | Object | No | Logs to be printed.| + +**Example** +``` +console.trace(); +console.trace("Show the trace"); +``` 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 0cd8b2df9f10074df34a7405be624953b7feb233..76d9a3456aaa7c24beb2f57aee57e6106f4957fa 100644 --- a/en/application-dev/reference/apis/js-apis-resource-manager.md +++ b/en/application-dev/reference/apis/js-apis-resource-manager.md @@ -13,7 +13,7 @@ The Resource Manager module provides APIs to obtain information about applicatio import resourceManager from '@ohos.resourceManager'; ``` -## How to Use +## Instruction Since API version 9, the stage model allows an application to obtain a **ResourceManager** object based on **context** and call its resource management APIs without first importing the required bundle. This approach, however, is not applicable to the FA model. For the FA model, you need to import the required bundle and then call the [getResourceManager](#resourcemanagergetresourcemanager) API to obtain a **ResourceManager** object. For details about how to reference context in the stage model, see [Context in the Stage Model](../../application-models/application-context-stage.md). @@ -78,7 +78,7 @@ Obtains the **ResourceManager** object of an application based on the specified | Name | Type | Mandatory | Description | | ---------- | ---------------------------------------- | ---- | ----------------------------- | -| bundleName | string | Yes | Bundle name of the target application. | +| bundleName | string | Yes | Bundle name of the application. | | callback | AsyncCallback<[ResourceManager](#resourcemanager)> | Yes | Callback used to return the result.| **Example** @@ -135,7 +135,7 @@ Obtains the **ResourceManager** object of an application based on the specified | Name | Type | Mandatory | Description | | ---------- | ------ | ---- | ------------- | -| bundleName | string | Yes | Bundle name of the target application.| +| bundleName | string | Yes | Bundle name of the application.| **Return value** @@ -171,12 +171,12 @@ Enumerates the device types. | Name | Value | Description | | -------------------- | ---- | ---- | -| DEVICE_TYPE_PHONE | 0x00 | Phone. | -| DEVICE_TYPE_TABLET | 0x01 | Tablet. | -| DEVICE_TYPE_CAR | 0x02 | Head unit. | -| DEVICE_TYPE_PC | 0x03 | PC. | -| DEVICE_TYPE_TV | 0x04 | TV. | -| DEVICE_TYPE_WEARABLE | 0x06 | Wearable. | +| DEVICE_TYPE_PHONE | 0x00 | Phone | +| DEVICE_TYPE_TABLET | 0x01 | Tablet | +| DEVICE_TYPE_CAR | 0x02 | Head unit | +| DEVICE_TYPE_PC | 0x03 | PC | +| DEVICE_TYPE_TV | 0x04 | TV | +| DEVICE_TYPE_WEARABLE | 0x06 | Wearable | ## ScreenDensity @@ -278,7 +278,7 @@ Defines the capability of accessing application resources. > **NOTE** > -> - The methods involved in **ResourceManager** are applicable only to the TypeScript-based declarative development paradigm. +> - The APIs involved in **ResourceManager** are applicable only to the TypeScript-based declarative development paradigm. > > - Resource files are defined in the **resources** directory of the project. You can obtain the resource ID using **$r(resource address).id**, for example, **$r('app.string.test').id**. @@ -645,7 +645,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco getMediaContent(resId: number, callback: AsyncCallback<Uint8Array>): void -Obtains the content of the media file corresponding to the specified resource name. This API uses an asynchronous callback to return the result. +Obtains the content of the media file corresponding to the specified resource ID. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Global.ResourceManager @@ -1234,9 +1234,9 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco ``` -### getPluralString9+ +### getPluralStringValue9+ -getPluralString(resource: Resource, num: number): Promise<string> +getPluralStringValue(resource: Resource, num: number): Promise<string> Obtains the singular-plural string corresponding to the specified resource object based on the specified number. This API uses a promise to return the result. @@ -1273,10 +1273,10 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco id: $r('app.plural.test').id }; try { - this.context.resourceManager.getPluralString(resource, 1).then(value => { + this.context.resourceManager.getPluralStringValue(resource, 1).then(value => { let str = value; }).catch(error => { - console.log("getPluralString promise error is " + error); + console.log("getPluralStringValue promise error is " + error); }); } catch (error) { console.error(`callback getPluralStringValue failed, error code: ${error.code}, message: ${error.message}.`) @@ -1658,7 +1658,7 @@ Obtains the string corresponding to the specified resource name. This API uses a | Type | Description | | --------------------- | ---------- | -| Promise<string> | Promise used to return the result.| +| Promise<string> | String corresponding to the resource name.| For details about the error codes, see [Resource Manager Error Codes](../errorcodes/errorcode-resource-manager.md). @@ -1770,7 +1770,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco getMediaByName(resName: string, callback: AsyncCallback<Uint8Array>): void -Obtains the content of the media file corresponding to the specified resource name. This API uses an asynchronous callback to return the result. +Obtains the content of the media file corresponding to the specified resource ID. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Global.ResourceManager @@ -2036,7 +2036,7 @@ Obtains the string corresponding to the specified resource ID. This API returns | Type | Description | | ------ | ----------- | -| string | String corresponding to the specified resource ID.| +| string | Promise used to return the result.| For details about the error codes, see [Resource Manager Error Codes](../errorcodes/errorcode-resource-manager.md). @@ -2070,7 +2070,7 @@ Obtains the string corresponding to the specified resource ID and formats the st | Name | Type | Mandatory | Description | | ----- | ------ | ---- | ----- | | resId | number | Yes | Resource ID.| -| args | Array | No | Arguments for formatting strings.
Supported arguments:
-%d, %f, %s, and %%
Note: %% is used to translate %.
Example: %%d is translated into the %d string.| +| args | Array | No | Arguments for formatting strings.
Supported arguments:
-%d, %f, %s, and %%
Note: **%%** is used to translate **%**.
Example: **%%d** is translated into the **%d** string.| **Return value** @@ -2116,7 +2116,7 @@ Obtains the string corresponding to the specified resource object. This API retu | Type | Description | | ------ | ---------------- | -| string | String corresponding to the resource object.| +| string | Promise used to return the result.| For details about the error codes, see [Resource Manager Error Codes](../errorcodes/errorcode-resource-manager.md). @@ -2155,7 +2155,7 @@ Obtains the string corresponding to the specified resource object and formats th | Name | Type | Mandatory | Description | | -------- | ---------------------- | ---- | ---- | | resource | [Resource](#resource9) | Yes | Resource object.| -| args | Array | No | Arguments for formatting strings.
Supported arguments:
-%d, %f, %s, and %%
Note: %% is used to translate %.
Example: %%d is translated into the %d string.| +| args | Array | No | Arguments for formatting strings.
Supported arguments:
-%d, %f, %s, and %%
Note: **%%** is used to translate **%**.
Example: **%%d** is translated into the **%d** string.| **Return value** @@ -2206,7 +2206,7 @@ Obtains the string corresponding to the specified resource name. This API return | Type | Description | | ------ | ---------- | -| string | String corresponding to the resource name.| +| string | String corresponding to the specified resource name.| For details about the error codes, see [Resource Manager Error Codes](../errorcodes/errorcode-resource-manager.md). @@ -2240,7 +2240,7 @@ Obtains the string corresponding to the specified resource name and formats the | Name | Type | Mandatory | Description | | ------- | ------ | ---- | ---- | | resName | string | Yes | Resource name.| -| args | Array | No | Arguments for formatting strings.
Supported arguments:
-%d, %f, %s, and %%
Note: %% is used to translate %.
Example: %%d is translated into the %d string.| +| args | Array | No | Arguments for formatting strings.
Supported arguments:
-%d, %f, %s, and %%
Note: **%%** is used to translate **%**.
Example: **%%d** is translated into the **%d** string.| **Return value** @@ -2406,8 +2406,8 @@ Obtains the integer or float value corresponding to the specified resource ID. T **Return value** | Type | Description | -| ------ | ---------- | -| number | Integer or float value corresponding to the specified resource ID.| +| ------ | ---------- | +| number | Integer or float value corresponding to the specified resource ID. Wherein, the integer value is the original value, and the float value is the actual pixel value.| For details about the error codes, see [Resource Manager Error Codes](../errorcodes/errorcode-resource-manager.md). @@ -2422,13 +2422,13 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco **Example** ```ts try { - this.context.resourceManager.getNumber($r('app.integer.integer_test').id); + 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}.`) } try { - this.context.resourceManager.getNumber($r('app.float.float_test').id); + 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}.`) } @@ -2452,7 +2452,7 @@ Obtains the integer or float value corresponding to the specified resource objec | Type | Description | | ------ | --------------- | -| number | Integer or float value corresponding to the specified resource object.| +| number | Integer or float value corresponding to the specified resource object. Wherein, the integer value is the original value, and the float value is the actual pixel value.| For details about the error codes, see [Resource Manager Error Codes](../errorcodes/errorcode-resource-manager.md). @@ -2472,7 +2472,7 @@ For details about the error codes, see [Resource Manager Error Codes](../errorco id: $r('app.integer.integer_test').id }; try { - this.context.resourceManager.getNumber(resource); + 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}.`) } @@ -2666,7 +2666,7 @@ getString(resId: number, callback: AsyncCallback<string>): void Obtains the string corresponding to the specified resource ID. This API uses an asynchronous callback to return the result. -This API is deprecated since API version 9. You are advised to use [getStringValue](#getstringvalue9) instead. +This API is deprecated since API version 9. You are advised to use [getStringValue](#getstringvalue9). **System capability**: SystemCapability.Global.ResourceManager @@ -2697,7 +2697,7 @@ getString(resId: number): Promise<string> Obtains the string corresponding to the specified resource ID. This API uses a promise to return the result. -This API is deprecated since API version 9. You are advised to use [getStringValue](#getstringvalue9-1) instead. +This API is deprecated since API version 9. You are advised to use [getStringValue](#getstringvalue9-1). **System capability**: SystemCapability.Global.ResourceManager @@ -2731,7 +2731,7 @@ getStringArray(resId: number, callback: AsyncCallback<Array<string>> Obtains the string array corresponding to the specified resource ID. This API uses an asynchronous callback to return the result. -This API is deprecated since API version 9. You are advised to use [getStringArrayValue](#getstringarrayvalue9) instead. +This API is deprecated since API version 9. You are advised to use [getStringArrayValue](#getstringarrayvalue9). **System capability**: SystemCapability.Global.ResourceManager @@ -2762,7 +2762,7 @@ getStringArray(resId: number): Promise<Array<string>> Obtains the string array corresponding to the specified resource ID. This API uses a promise to return the result. -This API is deprecated since API version 9. You are advised to use [getStringArrayValue](#getstringarrayvalue9-1) instead. +This API is deprecated since API version 9. You are advised to use [getStringArrayValue](#getstringarrayvalue9-1). **System capability**: SystemCapability.Global.ResourceManager @@ -2794,9 +2794,9 @@ This API is deprecated since API version 9. You are advised to use [getStringArr getMedia(resId: number, callback: AsyncCallback<Uint8Array>): void -Obtains the content of the media file corresponding to the specified resource name. This API uses an asynchronous callback to return the result. +Obtains the content of the media file corresponding to the specified resource ID. This API uses an asynchronous callback to return the result. -This API is deprecated since API version 9. You are advised to use [getMediaContent](#getmediacontent9) instead. +This API is deprecated since API version 9. You are advised to use [getMediaContent](#getmediacontent9). **System capability**: SystemCapability.Global.ResourceManager @@ -2827,7 +2827,7 @@ getMedia(resId: number): Promise<Uint8Array> Obtains the content of the media file corresponding to the specified resource ID. This API uses a promise to return the result. -This API is deprecated since API version 9. You are advised to use [getMediaContent](#getmediacontent9-1) instead. +This API is deprecated since API version 9. You are advised to use [getMediaContent](#getmediacontent9-1). **System capability**: SystemCapability.Global.ResourceManager @@ -2861,7 +2861,7 @@ getMediaBase64(resId: number, callback: AsyncCallback<string>): void Obtains the Base64 code of the image corresponding to the specified resource ID. This API uses an asynchronous callback to return the result. -This API is deprecated since API version 9. You are advised to use [getMediaContentBase64](#getmediacontentbase649) instead. +This API is deprecated since API version 9. You are advised to use [getMediaContentBase64](#getmediacontentbase649). **System capability**: SystemCapability.Global.ResourceManager @@ -2892,7 +2892,7 @@ getMediaBase64(resId: number): Promise<string> Obtains the Base64 code of the image corresponding to the specified resource ID. This API uses a promise to return the result. -This API is deprecated since API version 9. You are advised to use [getMediaContentBase64](#getmediacontentbase649-1) instead. +This API is deprecated since API version 9. You are advised to use [getMediaContentBase64](#getmediacontentbase649-1). **System capability**: SystemCapability.Global.ResourceManager @@ -2926,7 +2926,7 @@ getPluralString(resId: number, num: number): Promise<string> Obtains the singular-plural string corresponding to the specified resource ID based on the specified number. This API uses a promise to return the result. -This API is deprecated since API version 9. You are advised to use [getPluralStringValue](#getpluralstringvalue9) instead. +This API is deprecated since API version 9. You are advised to use [getPluralStringValue](#getpluralstringvalue9). **System capability**: SystemCapability.Global.ResourceManager @@ -2961,7 +2961,7 @@ getPluralString(resId: number, num: number, callback: AsyncCallback<string> Obtains the singular-plural string corresponding to the specified resource ID based on the specified number. This API uses an asynchronous callback to return the result. -This API is deprecated since API version 9. You are advised to use [getPluralStringValue](#getpluralstringvalue9-1) instead. +This API is deprecated since API version 9. You are advised to use [getPluralStringValue](#getpluralstringvalue9-1). **System capability**: SystemCapability.Global.ResourceManager @@ -2993,7 +2993,7 @@ getRawFile(path: string, callback: AsyncCallback<Uint8Array>): void Obtains the content 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 [getRawFileContent](#getrawfilecontent9) instead. +This API is deprecated since API version 9. You are advised to use [getRawFileContent](#getrawfilecontent9). **System capability**: SystemCapability.Global.ResourceManager @@ -3024,7 +3024,7 @@ getRawFile(path: string): Promise<Uint8Array> Obtains the content 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 [getRawFileContent](#getrawfilecontent9-1) instead. +This API is deprecated since API version 9. You are advised to use [getRawFileContent](#getrawfilecontent9-1). **System capability**: SystemCapability.Global.ResourceManager @@ -3058,7 +3058,7 @@ getRawFileDescriptor(path: string, callback: AsyncCallback<RawFileDescriptor& Obtains 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 [getRawFd](#getrawfd9) instead. +This API is deprecated since API version 9. You are advised to use [getRawFd](#getrawfd9). **System capability**: SystemCapability.Global.ResourceManager @@ -3090,7 +3090,7 @@ getRawFileDescriptor(path: string): Promise<RawFileDescriptor> Obtains 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 [getRawFd](#getrawfd9-1) instead. +This API is deprecated since API version 9. You are advised to use [getRawFd](#getrawfd9-1). **System capability**: SystemCapability.Global.ResourceManager diff --git a/en/application-dev/reference/apis/js-apis-uiappearance.md b/en/application-dev/reference/apis/js-apis-uiappearance.md index 3bac964627675b3475e273551d06b146636b410d..ebbdc971840c8f3669bc19dbba0ebd0d95b28d60 100644 --- a/en/application-dev/reference/apis/js-apis-uiappearance.md +++ b/en/application-dev/reference/apis/js-apis-uiappearance.md @@ -1,4 +1,4 @@ -# UI Appearance +# @ohos.uiAppearance (UI Appearance) The **uiAppearance** module provides basic capabilities for managing the system appearance. It allows for color mode configuration currently, and will introduce more features over time. diff --git a/en/application-dev/reference/apis/js-apis-uripermissionmanager.md b/en/application-dev/reference/apis/js-apis-uripermissionmanager.md new file mode 100644 index 0000000000000000000000000000000000000000..638fe99e48efc36559d81b9b53b16293500c64c3 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-uripermissionmanager.md @@ -0,0 +1,143 @@ +# @ohos.application.uriPermissionManager (URI Permission 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 **uriPermissionManager** module provides APIs for granting permissions on a file to or revoking the granted permission from an application. The file is identified by a uniform resource identifier (URI). + + +## Modules to Import + + +```js +import UriPermissionManager from '@ohos.application.uriPermissionManager'; +``` + + +## uriPermissionManager.grantUriPermission + +grantUriPermission(uri: string, flag: wantConstant.Flags, accessTokenId: number, callback: AsyncCallback<number>): void + +Grants permission on the file of the specified URI to an application. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | uri | string | Yes| URI of the file, for example, **fileshare:///com.samples.filesharetest.FileShare/person/10**.| + | flag | [wantConstant.Flags](js-apis-ability-wantConstant.md#wantconstantflags) | Yes| Read or write permission on the file to grant.| + | targetBundleName | string | Yes| Bundle name of the application, to which the permission is granted.| + | callback | AsyncCallback<number> | Yes| Callback invoked to return the result. If the operation is successful, **0** is returned; otherwise, **-1** is returned.| + +**Example** + + ```js + import WantConstant from '@ohos.ability.wantConstant'; + let targetBundleName = 'com.example.test_case1' + let uri = "fileshare:///com.samples.filesharetest.FileShare/person/10" + uriPermissionManager.grantUriPermission(uri, WantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, targetBundleName, (result) => { + console.log("result.code = " + result.code) + }) + ``` + + +## uriPermissionManager.grantUriPermission + +grantUriPermission(uri: string, flag: wantConstant.Flags, accessTokenId: number): Promise<number> + +Grants permission on the file of the specified URI to an application. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | uri | string | Yes| URI of the file, for example, **fileshare:///com.samples.filesharetest.FileShare/person/10**.| + | flag | [wantConstant.Flags](js-apis-ability-wantConstant.md#wantconstantflags) | Yes| Read or write permission on the file to grant.| + | targetBundleName | string | Yes| Bundle name of the application, to which the permission is granted.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<number> | Promise used to return the result. If the operation is successful, **0** is returned; otherwise, **-1** is returned.| + +**Example** + + ```js + import WantConstant from '@ohos.ability.wantConstant'; + let targetBundleName = 'com.example.test_case1' + let uri = "fileshare:///com.samples.filesharetest.FileShare/person/10" + uriPermissionManager.grantUriPermission(uri, wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION, targetBundleName) + .then((data) => { + console.log('Verification succeeded.' + data) + }).catch((error) => { + console.log('Verification failed.'); + }) + ``` +## uriPermissionManager.revokeUriPermission + +revokeUriPermission(uri: string, accessTokenId: number, callback: AsyncCallback<number>): void + +Revokes the permission on the file of the specified URI from an application. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | uri | string | Yes| URI of the file, for example, **fileshare:///com.samples.filesharetest.FileShare/person/10**.| + | targetBundleName | string | Yes| Bundle name of the application, from which the permission is revoked.| + | callback | AsyncCallback<number> | Yes| Callback invoked to return the result. If the operation is successful, **0** is returned; otherwise, **-1** is returned.| + +**Example** + + ```js + import WantConstant from '@ohos.ability.wantConstant'; + let targetBundleName = 'com.example.test_case1' + let URI = "fileshare:///com.samples.filesharetest.FileShare/person/10" + uriPermissionManager.revokeUriPermission(uri, targetBundleName, (result) => { + console.log("result.code = " + result.code) + }) + ``` + + +## uriPermissionManager.revokeUriPermission + +revokeUriPermission(uri: string, flag: wantConstant.Flags, accessTokenId: number): Promise<number> + +Revokes the permission on the file of the specified URI from an application. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | uri | string | Yes| URI of the file, for example, **fileshare:///com.samples.filesharetest.FileShare/person/10**.| + | targetBundleName | string | Yes| Bundle name of the application, from which the permission is revoked.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<number> | Promise used to return the result. If the operation is successful, **0** is returned; otherwise, **-1** is returned.| + +**Example** + + ```js + import WantConstant from '@ohos.ability.wantConstant'; + let targetBundleName = 'com.example.test_case1' + let uri = "fileshare:///com.samples.filesharetest.FileShare/person/10" + uriPermissionManager.revokeUriPermission(uri, targetBundleName) + .then((data) => { + console.log('Verification succeeded.' + data) + }).catch((error) => { + console.log('Verification failed.'); + }) + ``` diff --git a/en/application-dev/reference/apis/js-apis-window.md b/en/application-dev/reference/apis/js-apis-window.md index 26fd78b642da4a588bec3a06e12a1b591681da62..d00c77b95c8870f0c97404a0e08d2ba3d449160b 100644 --- a/en/application-dev/reference/apis/js-apis-window.md +++ b/en/application-dev/reference/apis/js-apis-window.md @@ -54,7 +54,7 @@ Defines the parameters for creating a subwindow or system window. | ---------- | -------------------------- | -- | ----------------------------------- | | name | string | Yes| Name of the window. | | windowType | [WindowType](#windowtype7) | Yes| Type of the window. | -| ctx | [BaseContext](js-apis-inner-application-baseContext.md) | No| Current application context. If this parameter is not set, no context is used.
You do not need to set this parameter to create a subwindow in the FA model or a system window in the stage model. | +| ctx | [BaseContext](js-apis-inner-application-baseContext.md) | No| Current application context. If this parameter is not set, no context is used.
You do not need to set this parameter to create a subwindow in the FA model
or a system window in the stage model.| | displayId | number | No| ID of the current physical screen. If this parameter is not set, the default value **-1** is used.| | parentId | number | No| ID of the parent window. If this parameter is not set, the default value **-1** is used. | @@ -66,7 +66,7 @@ Enumerates the types of the area where the window cannot be displayed. | Name | Value | Description | | -------------------------------- | ---- | ------------------------------------------------------------ | -| TYPE_SYSTEM | 0 | Default area of the system. Generally, the status bar, navigation bar, and Dock bar are included. The default area may vary according to the device in use.| +| TYPE_SYSTEM | 0 | Default area of the system. Generally, the status bar and navigation bar are included. The default area may vary according to the device in use.| | TYPE_CUTOUT | 1 | Notch. | | TYPE_SYSTEM_GESTURE9+ | 2 | Gesture area. | | TYPE_KEYBOARD9+ | 3 | Soft keyboard area. | @@ -108,10 +108,10 @@ Describes the properties of the status bar and navigation bar. | Name | Type| Mandatory| Description | | -------------------------------------- | -------- | ---- | ------------------------------------------------------------ | -| statusBarColor | string | No | Background color of the status bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, **#00FF00** or **#FF00FF00**. The default value is **#0x66000000**.| +| statusBarColor | string | No | Background color of the status bar. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **#00FF00** or **#FF00FF00**. The default value is **#0x66000000**.| | isStatusBarLightIcon7+ | boolean | No | Whether any icon on the status bar is highlighted. The value **true** means that the icon is highlighted, and **false** means the opposite. The default value is **false**.| | statusBarContentColor8+ | string | No | Color of the text on the status bar. After this property is set, the setting of **isStatusBarLightIcon** is invalid. The default value is **0xE5FFFFFF**.| -| navigationBarColor | string | No | Background color of the navigation bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, **#00FF00** or **#FF00FF00**. The default value is **#0x66000000**.| +| navigationBarColor | string | No | Background color of the navigation bar. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **#00FF00** or **#FF00FF00**. The default value is **#0x66000000**.| | isNavigationBarLightIcon7+ | boolean | No | Whether any icon on the navigation bar is highlighted. The value **true** means that the icon is highlighted, and **false** means the opposite. The default value is **false**.| | navigationBarContentColor8+ | string | No | Color of the text on the navigation bar. After this property is set, the setting of **isNavigationBarLightIcon** is invalid. The default value is **0xE5FFFFFF**.| @@ -164,7 +164,7 @@ Describes the callback for a single system bar. | type | [WindowType](#windowtype7) | Yes | No | Type of the system bar whose properties are changed. Only the status bar and navigation bar are supported.| | isEnable | boolean | Yes | No | Whether the system bar is displayed. The value **true** means that the system bar is displayed, and **false** means the opposite.| | region | [Rect](#rect7) | Yes | No | Current position and size of the system bar. | -| backgroundColor | string | Yes | No | Background color of the system bar. The value is a hexadecimal RGB or aRGB color value and is case insensitive, for example, **#00FF00** or **#FF00FF00**.| +| backgroundColor | string | Yes | No | Background color of the system bar. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **#00FF00** or **#FF00FF00**.| | contentColor | string | Yes | No | Color of the text on the system bar. | ## SystemBarTintState8+ @@ -300,8 +300,6 @@ Describes the translation parameters. Enumerates the window lifecycle states. -**System API**: This is a system API. - **System capability**: SystemCapability.WindowManager.WindowManager.Core | Name | Value| Description | @@ -832,6 +830,148 @@ try { } ``` +## window.on('gestureNavigationEnabledChange')10+ + +on(type: 'gestureNavigationEnabledChange', callback: Callback<boolean>): void + +Enables listening for gesture navigation status changes. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | ----------------------------------------------------------------------------- | +| type | string | Yes | Event type. The value is fixed at **'gestureNavigationEnabledChange'**, indicating the gesture navigation status change event. | +| callback | Callback<boolean> | Yes | Callback used to return the gesture navigation status. The value **true** means that the gesture navigation status is changed to enabled, and **false** means that the gesture navigation status is changed to disabled.| + +**Example** + +```js +try { + window.on('gestureNavigationEnabledChange', (data) => { + console.info('Succeeded in enabling the listener for gesture navigation status changes. Data: ' + JSON.stringify(data)); + }); +} catch (exception) { + console.error('Failed to enable the listener for gesture navigation status changes. Cause: ' + JSON.stringify(exception)); +} +``` + +## window.off('gestureNavigationEnabledChange')10+ + +off(type: 'gestureNavigationEnabledChange', callback?: Callback<boolean>): void + +Disables the listening for gesture navigation status changes. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | -- | ------------------------------------------------------------ | +| type | string | Yes| Event type. The value is fixed at **'gestureNavigationEnabledChange'**, indicating the gesture navigation status change event.| +| callback | Callback<boolean> | No| Callback function that has been used for registering the listener. If this parameter is passed in, only the listener registered using this callback function is removed; otherwise, all gesture navigation status change listeners are removed.| + +**Example** + +```js +try { + window.off('gestureNavigationEnabledChange'); +} catch (exception) { + console.error('Failed to disable the listener for gesture navigation status changes. Cause: ' + JSON.stringify(exception)); +} +``` + +## window.setGestureNavigationEnabled10+ +setGestureNavigationEnabled(enable: boolean, callback: AsyncCallback<void>): void + +Enables or disables gesture navigation. This API uses an asynchronous callback to return the result. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | -------------- | +| enable | boolean | Yes | Whether to enable gesture navigation. The value **true** means to enable gesture navigation, and **false** means the opposite.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result.| + +**Error codes** + +For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md). + +| ID| Error Message| +| ------- | --------------------------------------------- | +| 1300002 | This window state is abnormal. | +| 1300003 | This window manager service works abnormally. | + +**Example** + +```js +try { + window.setGestureNavigationEnabled(true, (err) => { + if(err.code) { + console.error('Failed to set gesture navigation enabled. Cause: ' + JSON.stringify(err)); + return; + } + console.info('Succeeded in setting gesture navigation enabled.'); + }); +} catch (exception) { + console.error('Failed to set gesture navigation enabled. Cause: ' + JSON.stringify(exception)); +} +``` + +## window.setGestureNavigationEnabled10+ +setGestureNavigationEnabled(enable: boolean): Promise<void> + +Enables or disables gesture navigation. This API uses a promise to return the result. + +**System API**: This is a system API. + +**System capability**: SystemCapability.WindowManager.WindowManager.Core + +**Parameters** + +| Name| Type | Mandatory | Description | +| ------ | ------- | ---- | -------------------- | +| enable | boolean | Yes | Whether to enable gesture navigation. The value **true** means to enable gesture navigation, and **false** means the opposite.| + +**Return value** + +| Type | Description | +| ------------------- | ------------------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about the error codes, see [Window Error Codes](../errorcodes/errorcode-window.md). + +| ID| Error Message| +| ------- | -------------------------------------------- | +| 1300002 | This window state is abnormal. | +| 1300003 | This window manager service works abnormally. | + +**Example** + +```js +try { + let promise = window.setGestureNavigationEnabled(true); + promise.then(()=> { + console.info('Succeeded in setting gesture navigation enabled.'); + }).catch((err)=>{ + console.error('Failed to set gesture navigation enabled. Cause: ' + JSON.stringify(err)); + }); +} catch (exception) { + console.error('Failed to set gesture navigation enabled. Cause: ' + JSON.stringify(exception)); +} +``` + ## window.create(deprecated) create(id: string, type: WindowType, callback: AsyncCallback<Window>): void @@ -1910,7 +2050,9 @@ try { setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void -Sets whether to enable the full-screen mode for the window layout. This API uses an asynchronous callback to return the result. +Sets whether the window layout is immersive. This API uses an asynchronous callback to return the result. +An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. +A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -1918,7 +2060,7 @@ Sets whether to enable the full-screen mode for the window layout. This API uses | Name| Type| Mandatory| Description| | ------------------ | ------------------------- | -- | --------- | -| isLayoutFullScreen | boolean | Yes| Whether to enable the full-screen mode for the window layout, in which the status bar and navigation bar are displayed. The value **true** means to enable the full-screen mode for the window layout, and **false** means the opposite.| +| isLayoutFullScreen | boolean | Yes| Whether the window layout is immersive. (The status bar and navigation bar of the immersive layout are still displayed.) The value **true** means that the window layout is immersive, and **false** means the opposite.| | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Error codes** @@ -1951,7 +2093,9 @@ try { setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void> -Sets whether to enable the full-screen mode for the window layout. This API uses a promise to return the result. +Sets whether the window layout is immersive. This API uses a promise to return the result. +An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. +A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. **System capability**: SystemCapability.WindowManager.WindowManager.Core @@ -1959,7 +2103,7 @@ Sets whether to enable the full-screen mode for the window layout. This API uses | Name| Type| Mandatory| Description| | ------------------ | ------- | -- | ------------------------------------------------------------------------------------------------ | -| isLayoutFullScreen | boolean | Yes| Whether to enable the full-screen mode for the window layout, in which the status bar and navigation bar are displayed. The value **true** means to enable the full-screen mode for the window layout, and **false** means the opposite.| +| isLayoutFullScreen | boolean | Yes| Whether the window layout is immersive. (The status bar and navigation bar of the immersive layout are still displayed.) The value **true** means that the window layout is immersive, and **false** means the opposite.| **Return value** @@ -2361,7 +2505,7 @@ Loads content from a page associated with a local storage to this window. This A | Name | Type | Mandatory| Description | | -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | | path | string | Yes | Path of the page from which the content will be loaded. | -| storage | [LocalStorage](../../quick-start/arkts-state-mgmt-application-level.md#localstorage) | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.| +| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.| | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** @@ -2407,7 +2551,7 @@ Loads content from a page associated with a local storage to this window. This A | Name | Type | Mandatory| Description | | ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | | path | string | Yes | Path of the page from which the content will be loaded. | -| storage | [LocalStorage](../../quick-start/arkts-state-mgmt-application-level.md#localstorage) | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.| +| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application.| **Return value** @@ -3335,7 +3479,7 @@ Sets the background color for this window. In the stage model, this API must be | Name| Type| Mandatory| Description| | ----- | ------ | -- | ----------------------------------------------------------------------- | -| color | string | Yes| Background color to set. The value is a hexadecimal RGB or aRGB color code and is case insensitive, for example, **#00FF00** or **#FF00FF00**.| +| color | string | Yes| Background color to set. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **#00FF00** or **#FF00FF00**.| **Error codes** @@ -4019,7 +4163,7 @@ promise.then((pixelMap)=> { opacity(opacity: number): void -Sets the opacity for this window. +Sets the opacity for this window. This API can be used only when you [customize an animation to be played during the display or hiding of a system window](../../windowmanager/system-window-stage.md#customizing-an-animation-to-be-played-during-the-display-or-hiding-of-a-system-window). **System API**: This is a system API. @@ -4027,9 +4171,9 @@ Sets the opacity for this window. **Parameters** -| Name | Type | Mandatory | Description | -| ------- | ------ | --------- | ------------------------------------------------- | -| opacity | number | Yes | Opacity to set. The value ranges from 0.0 to 1.0. | +| Name | Type | Mandatory | Description | +| ------- | ------ | --------- | ------------------------------------------------------------ | +| opacity | number | Yes | Opacity to set. The value ranges from 0.0 to 1.0. The value **0.0** means completely transparent, and **1.0** means completely opaque. | **Error codes** @@ -4054,7 +4198,7 @@ try { scale(scaleOptions: ScaleOptions): void -Sets the scale parameters for this window. +Sets the scale parameters for this window. This API can be used only when you [customize an animation to be played during the display or hiding of a system window](../../windowmanager/system-window-stage.md#customizing-an-animation-to-be-played-during-the-display-or-hiding-of-a-system-window). **System API**: This is a system API. @@ -4095,7 +4239,7 @@ try { rotate(rotateOptions: RotateOptions): void -Sets the rotation parameters for this window. +Sets the rotation parameters for this window. This API can be used only when you [customize an animation to be played during the display or hiding of a system window](../../windowmanager/system-window-stage.md#customizing-an-animation-to-be-played-during-the-display-or-hiding-of-a-system-window). **System API**: This is a system API. @@ -4137,7 +4281,7 @@ try { translate(translateOptions: TranslateOptions): void -Sets the translation parameters for this window. +Sets the translation parameters for this window. This API can be used only when you [customize an animation to be played during the display or hiding of a system window](../../windowmanager/system-window-stage.md#customizing-an-animation-to-be-played-during-the-display-or-hiding-of-a-system-window). **System API**: This is a system API. @@ -4145,9 +4289,9 @@ Sets the translation parameters for this window. **Parameters** -| Name | Type | Mandatory | Description | -| ---------------- | -------------------------------------- | --------- | ------------------------------ | -| translateOptions | [TranslateOptions](#translateoptions9) | Yes | Translation parameters to set. | +| Name | Type | Mandatory | Description | +| ---------------- | -------------------------------------- | --------- | ------------------------------------------- | +| translateOptions | [TranslateOptions](#translateoptions9) | Yes | Translation parameters. The unit is pixels. | **Error codes** @@ -4303,7 +4447,6 @@ try { } catch (exception) { console.error('Failed to set backdrop blur. Cause: ' + JSON.stringify(exception)); } - ``` ### setBackdropBlurStyle9+ @@ -4339,7 +4482,6 @@ try { } catch (exception) { console.error('Failed to set backdrop blur style. Cause: ' + JSON.stringify(exception)); } - ``` ### setShadow9+ @@ -4357,7 +4499,7 @@ Sets the shadow for the window borders. | Name | Type | Mandatory | Description | | ------- | ------ | --------- | ------------------------------------------------------------ | | radius | number | Yes | Radius of the shadow. The value is greater than or equal to 0. The value **0** means that the shadow is disabled for the window borders. | -| color | string | No | Color of the shadow. The value is a hexadecimal RGB or aRGB color code and is case insensitive, for example, **#00FF00** or **#FF00FF00**. | +| color | string | No | Color of the shadow. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **#00FF00** or **#FF00FF00**. | | offsetX | number | No | Offset of the shadow along the x-axis, in pixels. | | offsetY | number | No | Offset of the shadow along the y-axis, in pixels. | @@ -4378,7 +4520,6 @@ try { } catch (exception) { console.error('Failed to set shadow. Cause: ' + JSON.stringify(exception)); } - ``` ### setCornerRadius9+ @@ -4414,7 +4555,6 @@ try { } catch (exception) { console.error('Failed to set corner radius. Cause: ' + JSON.stringify(exception)); } - ``` ### raiseToAppTop10+ @@ -4454,7 +4594,6 @@ windowClass.raiseToAppTop((err) => { } console.info('Succeeded in raising the window to app top.'); }); - ``` ### raiseToAppTop10+ @@ -4493,9 +4632,7 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to raise the window to app top. Cause: ' + JSON.stringify(err)); }); - ``` - ### setAspectRatio10+ setAspectRatio(ratio: number): Promise<void> @@ -4541,7 +4678,6 @@ try { } catch (exception) { console.error('Failed to set the aspect ratio of window. Cause: ' + JSON.stringify(exception)); } - ``` ### setAspectRatio10+ @@ -4585,7 +4721,6 @@ try { } catch (exception) { console.error('Failed to set the aspect ratio of window. Cause: ' + JSON.stringify(exception)); } - ``` ### resetAspectRatio10+ @@ -4626,7 +4761,6 @@ try { } catch (exception) { console.error('Failed to reset the aspect ratio of window. Cause: ' + JSON.stringify(exception)); } - ``` ### resetAspectRatio10+ @@ -4668,7 +4802,6 @@ try { } catch (exception) { console.error('Failed to reset the aspect ratio of window. Cause: ' + JSON.stringify(exception)); } - ``` ### setWaterMarkFlag10+ @@ -4717,7 +4850,6 @@ try { } catch (exception) { console.error('Failed to set water mark flag of window. Cause: ' + JSON.stringify(exception)); } - ``` ### setWaterMarkFlag10+ @@ -4762,7 +4894,6 @@ try { } catch (exception) { console.error('Failed to set water mark flag of window. Cause: ' + JSON.stringify(exception)); } - ``` ### show(deprecated) @@ -4793,7 +4924,6 @@ windowClass.show((err) => { } console.info('Succeeded in showing the window.'); }); - ``` ### show(deprecated) @@ -4823,7 +4953,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to show the window. Cause: ' + JSON.stringify(err)); }); - ``` ### destroy(deprecated) @@ -4854,7 +4983,6 @@ windowClass.destroy((err) => { } console.info('Succeeded in destroying the window.'); }); - ``` ### destroy(deprecated) @@ -4884,7 +5012,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to destroy the window. Cause: ' + JSON.stringify(err)); }); - ``` ### moveTo(deprecated) @@ -4919,7 +5046,6 @@ windowClass.moveTo(300, 300, (err)=>{ } console.info('Succeeded in moving the window.'); }); - ``` ### moveTo(deprecated) @@ -4958,7 +5084,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to move the window. Cause: ' + JSON.stringify(err)); }); - ``` ### resetSize(deprecated) @@ -4999,7 +5124,6 @@ windowClass.resetSize(500, 1000, (err) => { } console.info('Succeeded in changing the window size.'); }); - ``` ### resetSize(deprecated) @@ -5044,7 +5168,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to change the window size. Cause: ' + JSON.stringify(err)); }); - ``` ### setWindowType(deprecated) @@ -5079,7 +5202,6 @@ windowClass.setWindowType(type, (err) => { } console.info('Succeeded in setting the window type.'); }); - ``` ### setWindowType(deprecated) @@ -5118,7 +5240,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to set the window type. Cause: ' + JSON.stringify(err)); }); - ``` ### getProperties(deprecated) @@ -5149,7 +5270,6 @@ windowClass.getProperties((err, data) => { } console.info('Succeeded in obtaining the window properties. Data: ' + JSON.stringify(data)); }); - ``` ### getProperties(deprecated) @@ -5179,7 +5299,6 @@ promise.then((data)=> { }).catch((err)=>{ console.error('Failed to obtain the window properties. Cause: ' + JSON.stringify(err)); }); - ``` ### getAvoidArea(deprecated) @@ -5212,7 +5331,6 @@ windowClass.getAvoidArea(type, (err, data) => { } console.info('Succeeded in obtaining the area. Data:' + JSON.stringify(data)); }); - ``` ### getAvoidArea(deprecated) @@ -5249,7 +5367,6 @@ promise.then((data)=> { }).catch((err)=>{ console.error('Failed to obtain the area. Cause:' + JSON.stringify(err)); }); - ``` ### setFullScreen(deprecated) @@ -5282,7 +5399,6 @@ windowClass.setFullScreen(isFullScreen, (err) => { } console.info('Succeeded in enabling the full-screen mode.'); }); - ``` ### setFullScreen(deprecated) @@ -5319,14 +5435,15 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to enable the full-screen mode. Cause: ' + JSON.stringify(err)); }); - ``` ### setLayoutFullScreen(deprecated) setLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void -Sets whether to enable the full-screen mode for the window layout. This API uses an asynchronous callback to return the result. +Sets whether the window layout is immersive. This API uses an asynchronous callback to return the result. +An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. +A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. > **NOTE** > @@ -5338,7 +5455,7 @@ Sets whether to enable the full-screen mode for the window layout. This API uses | Name | Type | Mandatory | Description | | ------------------ | ------------------------- | --------- | ------------------------------------------------------------ | -| isLayoutFullScreen | boolean | Yes | Whether to enable the full-screen mode for the window layout, in which the status bar and navigation bar are displayed. The value **true** means to enable the full-screen mode for the window layout, and **false** means the opposite. | +| isLayoutFullScreen | boolean | Yes | Whether the window layout is immersive. (The status bar and navigation bar of the immersive layout are still displayed.) The value **true** means that the window is immersive, and **false** means the opposite. | | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Example** @@ -5352,14 +5469,15 @@ windowClass.setLayoutFullScreen(isLayoutFullScreen, (err) => { } console.info('Succeeded in setting the window layout to full-screen mode.'); }); - ``` ### setLayoutFullScreen(deprecated) setLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void> -Sets whether to enable the full-screen mode for the window layout. This API uses a promise to return the result. +Sets whether the window layout is immersive. This API uses a promise to return the result. +An immersive layout means that the layout does not avoid the status bar and navigation bar, and components may overlap with them. +A non-immersive layout means that the layout avoids the status bar and navigation bar, and components do not overlap with them. > **NOTE** > @@ -5371,7 +5489,7 @@ Sets whether to enable the full-screen mode for the window layout. This API uses | Name | Type | Mandatory | Description | | ------------------ | ------- | --------- | ------------------------------------------------------------ | -| isLayoutFullScreen | boolean | Yes | Whether to enable the full-screen mode for the window layout, in which the status bar and navigation bar are displayed. The value **true** means to enable the full-screen mode for the window layout, and **false** means the opposite. | +| isLayoutFullScreen | boolean | Yes | Whether the window layout is immersive. (The status bar and navigation bar of the immersive layout are still displayed.) The value **true** means that the window is immersive, and **false** means the opposite. | **Return value** @@ -5389,7 +5507,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err)); }); - ``` ### setSystemBarEnable(deprecated) @@ -5423,7 +5540,6 @@ windowClass.setSystemBarEnable(names, (err) => { } console.info('Succeeded in setting the system bar to be invisible.'); }); - ``` ### setSystemBarEnable(deprecated) @@ -5461,7 +5577,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to set the system bar to be invisible. Cause:' + JSON.stringify(err)); }); - ``` ### setSystemBarProperties(deprecated) @@ -5500,7 +5615,6 @@ windowClass.setSystemBarProperties(SystemBarProperties, (err) => { } console.info('Succeeded in setting the system bar properties.'); }); - ``` ### setSystemBarProperties(deprecated) @@ -5543,7 +5657,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(err)); }); - ``` ### loadContent(deprecated) @@ -5575,7 +5688,6 @@ windowClass.loadContent('pages/page2/page2', (err) => { } console.info('Succeeded in loading the content.'); }); - ``` ### loadContent(deprecated) @@ -5611,7 +5723,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to load the content. Cause: ' + JSON.stringify(err)); }); - ``` ### isShowing(deprecated) @@ -5642,7 +5753,6 @@ windowClass.isShowing((err, data) => { } console.info('Succeeded in checking whether the window is showing. Data: ' + JSON.stringify(data)); }); - ``` ### isShowing(deprecated) @@ -5672,7 +5782,6 @@ promise.then((data)=> { }).catch((err)=>{ console.error('Failed to check whether the window is showing. Cause: ' + JSON.stringify(err)); }); - ``` ### on('systemAvoidAreaChange')(deprecated) @@ -5700,7 +5809,6 @@ Enables listening for changes to the area where the window cannot be displayed. windowClass.on('systemAvoidAreaChange', (data) => { console.info('Succeeded in enabling the listener for system avoid area changes. Data: ' + JSON.stringify(data)); }); - ``` ### off('systemAvoidAreaChange')(deprecated) @@ -5726,7 +5834,6 @@ Disables listening for changes to the area where the window cannot be displayed. ```js windowClass.off('systemAvoidAreaChange'); - ``` ### isSupportWideGamut(deprecated) @@ -5757,7 +5864,6 @@ windowClass.isSupportWideGamut((err, data) => { } console.info('Succeeded in checking whether the window support WideGamut Data: ' + JSON.stringify(data)); }); - ``` ### isSupportWideGamut(deprecated) @@ -5787,7 +5893,6 @@ promise.then((data)=> { }).catch((err)=>{ console.error('Failed to check whether the window support WideGamut. Cause: ' + JSON.stringify(err)); }); - ``` ### setColorSpace(deprecated) @@ -5819,7 +5924,6 @@ windowClass.setColorSpace(window.ColorSpace.WIDE_GAMUT, (err) => { } console.info('Succeeded in setting window colorspace.'); }); - ``` ### setColorSpace(deprecated) @@ -5855,7 +5959,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to set window colorspace. Cause: ' + JSON.stringify(err)); }); - ``` ### getColorSpace(deprecated) @@ -5886,7 +5989,6 @@ windowClass.getColorSpace((err, data) => { } console.info('Succeeded in getting window colorspace. Cause:' + JSON.stringify(data)); }); - ``` ### getColorSpace(deprecated) @@ -5916,7 +6018,6 @@ promise.then((data)=> { }).catch((err)=>{ console.error('Failed to get window colorspace. Cause: ' + JSON.stringify(err)); }); - ``` ### setBackgroundColor(deprecated) @@ -5935,7 +6036,7 @@ Sets the background color for this window. This API uses an asynchronous callbac | Name | Type | Mandatory | Description | | -------- | ------------------------- | --------- | ------------------------------------------------------------ | -| color | string | Yes | Background color to set. The value is a hexadecimal RGB or aRGB color code and is case insensitive, for example, **#00FF00** or **#FF00FF00**. | +| color | string | Yes | Background color to set. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **#00FF00** or **#FF00FF00**. | | callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Example** @@ -5949,7 +6050,6 @@ windowClass.setBackgroundColor(color, (err) => { } console.info('Succeeded in setting the background color.'); }); - ``` ### setBackgroundColor(deprecated) @@ -5968,7 +6068,7 @@ Sets the background color for this window. This API uses a promise to return the | Name | Type | Mandatory | Description | | ----- | ------ | --------- | ------------------------------------------------------------ | -| color | string | Yes | Background color to set. The value is a hexadecimal RGB or aRGB color code and is case insensitive, for example, **#00FF00** or **#FF00FF00**. | +| color | string | Yes | Background color to set. The value is a hexadecimal RGB or ARGB color code and is case insensitive, for example, **#00FF00** or **#FF00FF00**. | **Return value** @@ -5986,7 +6086,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to set the background color. Cause: ' + JSON.stringify(err)); }); - ``` ### setBrightness(deprecated) @@ -6019,7 +6118,6 @@ windowClass.setBrightness(brightness, (err) => { } console.info('Succeeded in setting the brightness.'); }); - ``` ### setBrightness(deprecated) @@ -6056,7 +6154,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to set the brightness. Cause: ' + JSON.stringify(err)); }); - ``` ### setDimBehind(deprecated) @@ -6088,7 +6185,6 @@ windowClass.setDimBehind(0.5, (err) => { } console.info('Succeeded in setting the dimness.'); }); - ``` ### setDimBehind(deprecated) @@ -6124,7 +6220,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to set the dimness. Cause: ' + JSON.stringify(err)); }); - ``` ### setFocusable(deprecated) @@ -6157,7 +6252,6 @@ windowClass.setFocusable(isFocusable, (err) => { } console.info('Succeeded in setting the window to be focusable.'); }); - ``` ### setFocusable(deprecated) @@ -6194,7 +6288,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to set the window to be focusable. Cause: ' + JSON.stringify(err)); }); - ``` ### setKeepScreenOn(deprecated) @@ -6227,7 +6320,6 @@ windowClass.setKeepScreenOn(isKeepScreenOn, (err) => { } console.info('Succeeded in setting the screen to be always on.'); }); - ``` ### setKeepScreenOn(deprecated) @@ -6264,7 +6356,6 @@ promise.then(() => { }).catch((err)=>{ console.info('Failed to set the screen to be always on. Cause: ' + JSON.stringify(err)); }); - ``` ### setOutsideTouchable(deprecated) @@ -6296,7 +6387,6 @@ windowClass.setOutsideTouchable(true, (err) => { } console.info('Succeeded in setting the area to be touchable.'); }); - ``` ### setOutsideTouchable(deprecated) @@ -6332,7 +6422,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to set the area to be touchable. Cause: ' + JSON.stringify(err)); }); - ``` ### setPrivacyMode(deprecated) @@ -6365,7 +6454,6 @@ windowClass.setPrivacyMode(isPrivacyMode, (err) => { } console.info('Succeeded in setting the window to privacy mode.'); }); - ``` ### setPrivacyMode(deprecated) @@ -6402,7 +6490,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to set the window to privacy mode. Cause: ' + JSON.stringify(err)); }); - ``` ### setTouchable(deprecated) @@ -6435,7 +6522,6 @@ windowClass.setTouchable(isTouchable, (err) => { } console.info('Succeeded in setting the window to be touchable.'); }); - ``` ### setTouchable(deprecated) @@ -6472,7 +6558,6 @@ promise.then(()=> { }).catch((err)=>{ console.error('Failed to set the window to be touchable. Cause: ' + JSON.stringify(err)); }); - ``` ## WindowStageEventType9+ @@ -6542,7 +6627,6 @@ export default class EntryAbility extends UIAbility { }); } }; - ``` ### getMainWindow9+ @@ -6590,7 +6674,6 @@ export default class EntryAbility extends UIAbility { }); } }; - ``` ### getMainWindowSync9+ @@ -6635,7 +6718,6 @@ export default class EntryAbility extends UIAbility { }; } }; - ``` ### createSubWindow9+ @@ -6690,9 +6772,7 @@ export default class EntryAbility extends UIAbility { }; } }; - ``` - ### createSubWindow9+ createSubWindow(name: string): Promise<Window> @@ -6748,7 +6828,6 @@ export default class EntryAbility extends UIAbility { }; } }; - ``` ### getSubWindow9+ @@ -6796,9 +6875,7 @@ export default class EntryAbility extends UIAbility { }); } }; - ``` - ### getSubWindow9+ getSubWindow(): Promise<Array<Window>> @@ -6843,9 +6920,7 @@ export default class EntryAbility extends UIAbility { }) } }; - ``` - ### loadContent9+ loadContent(path: string, storage: LocalStorage, callback: AsyncCallback<void>): void @@ -6858,11 +6933,11 @@ Loads content from a page associated with a local storage to the main window in **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | -| path | string | Yes | Path of the page from which the content will be loaded. | -| storage | [LocalStorage](../../quick-start/arkts-state-mgmt-application-level.md#localstorage) | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application. | -| callback | AsyncCallback<void> | Yes | Callback used to return the result. | +| Name | Type | Mandatory | Description | +| -------- | ------------------------------------------------------- | --------- | ------------------------------------------------------------ | +| path | string | Yes | Path of the page from which the content will be loaded. | +| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | Yes | A storage unit, which provides storage for variable state properties and non-variable state properties of an application. | +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Error codes** @@ -6899,7 +6974,6 @@ export default class EntryAbility extends UIAbility { }; } }; - ``` ### loadContent9+ @@ -6914,10 +6988,10 @@ Loads content from a page associated with a local storage to the main window in **Parameters** -| Name | Type | Mandatory | Description | -| ------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | -| path | string | Yes | Path of the page from which the content will be loaded. | -| storage | [LocalStorage](../../quick-start/arkts-state-mgmt-application-level.md#localstorage) | No | A storage unit, which provides storage for variable state properties and non-variable state properties of an application. | +| Name | Type | Mandatory | Description | +| ------- | ------------------------------------------------------- | --------- | ------------------------------------------------------------ | +| path | string | Yes | Path of the page from which the content will be loaded. | +| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | No | A storage unit, which provides storage for variable state properties and non-variable state properties of an application. | **Return value** @@ -6959,7 +7033,6 @@ export default class EntryAbility extends UIAbility { }; } }; - ``` ### loadContent9+ @@ -7011,7 +7084,6 @@ export default class EntryAbility extends UIAbility { }; } }; - ``` ### on('windowStageEvent')9+ @@ -7061,7 +7133,6 @@ export default class EntryAbility extends UIAbility { }; } }; - ``` ### off('windowStageEvent')9+ @@ -7108,7 +7179,6 @@ export default class EntryAbility extends UIAbility { }; } }; - ``` ### disableWindowDecor()9+ @@ -7145,7 +7215,6 @@ export default class EntryAbility extends UIAbility { windowStage.disableWindowDecor(); } }; - ``` ### setShowOnLockScreen()9+ @@ -7192,9 +7261,7 @@ export default class EntryAbility extends UIAbility { }; } }; - ``` - ## TransitionContext9+ Provides the context for the transition animation. @@ -7255,7 +7322,6 @@ controller.animationForShown = (context : window.TransitionContext) => { } console.info('complete transition end'); }; - ``` ## TransitionController9+ @@ -7306,7 +7372,6 @@ controller.animationForShown = (context : window.TransitionContext) => { ); console.info('complete transition end'); }; - ``` ### animationForHidden9+ @@ -7353,4 +7418,6 @@ controller.animationForHidden = (context : window.TransitionContext) => { ) console.info('complete transition end'); }; -``` \ No newline at end of file +``` + + \ No newline at end of file diff --git a/en/application-dev/reference/arkui-ts/figures/en-us_image2_0000001219982725.PNG b/en/application-dev/reference/arkui-ts/figures/en-us_image2_0000001219982725.PNG index 310eae1cbaec0f37b61787a9cfa6ddf032c887d4..97b4e3e93daf8eb2b3d73a6776b56a4b745f0ba6 100644 Binary files a/en/application-dev/reference/arkui-ts/figures/en-us_image2_0000001219982725.PNG and b/en/application-dev/reference/arkui-ts/figures/en-us_image2_0000001219982725.PNG differ diff --git a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001184628104.png b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001184628104.png index ef4a4905fb4c0c1a6559bb622c523282ef01ee27..c334da3c021801a8c3c741bc5d2fbf76bcfe0455 100644 Binary files a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001184628104.png and b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001184628104.png differ diff --git a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001219744193.png b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001219744193.png index 17a7767c1f69c12ccfb0c1436110a9e22b848c26..4279bc045cae702953a3b0fd6d0e25450b27d945 100644 Binary files a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001219744193.png and b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001219744193.png differ diff --git a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001219982725.png b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001219982725.png index 048fdc4749a41e0675390e66e61b5d63953ed8e1..f5116e56dcaf8e48edc8f1d62a70160d8b84fba0 100644 Binary files a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001219982725.png and b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001219982725.png differ diff --git a/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001239032420.png b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001239032420.png new file mode 100644 index 0000000000000000000000000000000000000000..faf9e54e927094688fc3d086903d27cc895760f1 Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/en-us_image_0000001239032420.png differ diff --git a/en/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md b/en/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md index 765bafdcd9cb284148d243bc45f18b224f458fb0..6f899761e3609c2ee9a91fa2e9d8d2d04d105ee0 100644 --- a/en/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md +++ b/en/application-dev/reference/arkui-ts/ts-canvasrenderingcontext2d.md @@ -12,6 +12,8 @@ Use **RenderingContext** to draw rectangles, text, images, and other objects on CanvasRenderingContext2D(setting: RenderingContextSetting) +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Description | @@ -25,34 +27,36 @@ RenderingContextSettings(antialias?: boolean) Configures the settings of a **CanvasRenderingContext2D** object, including whether to enable antialiasing. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Description | | --------- | ------- | ---- | ----------------------------- | -| antialias | boolean | No | Whether to enable antialiasing.
Default value: **false** | +| antialias | boolean | No | Whether to enable antialiasing.
Default value: **false**| ## Attributes | Name | Type | Description | | ----------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -| [fillStyle](#fillstyle) | string \| [CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#canvaspattern) | Style to fill an area.
- When the type is string, 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.| +| [fillStyle](#fillstyle) | string \|number10+ \|[CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#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 \| [CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#canvaspattern) | Stroke style.
- When the type is string, 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.| -| [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'**| -| [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'**| -| [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**| -| [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 can only be pixels.
- (Optional) **font-family**: font family. Available values are **'sans-serif'**, **'serif'**, and **'monospace'**.
Default value: **'normal normal 14px sans-serif'**| -| [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'**| -| [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'**| -| [globalAlpha](#globalalpha) | number | Opacity.
**0.0**: completely transparent.
**1.0**: completely opaque. | -| [lineDashOffset](#linedashoffset) | number | Offset of the dashed line. The precision is float.
Default value: **0.0** | -| [globalCompositeOperation](#globalcompositeoperation) | string | Composition operation type. Available values are as follows: **'source-over'**, **'source-atop'**, **'source-in'**, **'source-out'**, **'destination-over'**, **'destination-atop'**, **'destination-in'**, **'destination-out'**, **'lighter'**, **'copy'**, and **'xor'**.
Default value: **'source-over'**| -| [shadowBlur](#shadowblur) | number | Blur level during shadow drawing. A larger value indicates a more blurred effect. The precision is float.
Default value: **0.0**| -| [shadowColor](#shadowcolor) | string | Shadow color. | -| [shadowOffsetX](#shadowoffsetx) | number | X-axis shadow offset relative to the original object. | -| [shadowOffsetY](#shadowoffsety) | number | Y-axis shadow offset relative to the original object. | -| [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**| +| [strokeStyle](#strokestyle) | string \|number10+ \|[CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#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.| +| [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 can only be pixels.
- (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.| +| [lineDashOffset](#linedashoffset) | number | Offset of the dashed line. The precision is float.
Default value: **0.0**
Since API version 9, this API is supported in ArkTS widgets.| +| [globalCompositeOperation](#globalcompositeoperation) | string | Composition operation type. Available values are as follows: **'source-over'**, **'source-atop'**, **'source-in'**, **'source-out'**, **'destination-over'**, **'destination-atop'**, **'destination-in'**, **'destination-out'**, **'lighter'**, **'copy'**, and **'xor'**.
Default value: **'source-over'**
Since API version 9, this API is supported in ArkTS widgets.| +| [shadowBlur](#shadowblur) | number | Blur level during shadow drawing. A larger value indicates a more blurred effect. The precision is float.
Default value: **0.0**
Since API version 9, this API is supported in ArkTS widgets.| +| [shadowColor](#shadowcolor) | string | Shadow color.
Since API version 9, this API is supported in ArkTS widgets.| +| [shadowOffsetX](#shadowoffsetx) | number | X-axis shadow offset relative to the original object.
Since API version 9, this API is supported in ArkTS widgets.| +| [shadowOffsetY](#shadowoffsety) | number | Y-axis shadow offset relative to the original object.
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.| > **NOTE** > @@ -77,7 +81,7 @@ struct FillStyleExample { .backgroundColor('#ffff00') .onReady(() =>{ this.context.fillStyle = '#0000ff' - this.context.fillRect(20, 160, 150, 100) + this.context.fillRect(20, 20, 150, 100) }) } .width('100%') @@ -657,6 +661,8 @@ fillRect(x: number, y: number, w: number, h: number): void Fills a rectangle on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -701,6 +707,8 @@ strokeRect(x: number, y: number, w: number, h: number): void Draws an outlined rectangle on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -745,6 +753,8 @@ clearRect(x: number, y: number, w: number, h: number): void Clears the content in a rectangle on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -791,6 +801,8 @@ fillText(text: string, x: number, y: number, maxWidth?: number): void Draws filled text on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory| Default Value| Description | @@ -836,6 +848,8 @@ strokeText(text: string, x: number, y: number, maxWidth?:number): void Draws a text stroke on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory| Default Value| Description | @@ -881,6 +895,8 @@ measureText(text: string): TextMetrics Measures the specified text to obtain its width. This API returns a **TextMetrics** object. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name| Type | Mandatory| Default Value| Description | @@ -889,9 +905,9 @@ Measures the specified text to obtain its width. This API returns a **TextMetric **Return value** -| Type | Description | -| ----------- | ---------------- | -| TextMetrics | **TextMetrics** object.| +| Type | Description | +| ----------- | ------------------------------------------------------------ | +| TextMetrics | **TextMetrics** object.
Since API version 9, this API is supported in ArkTS widgets.| **TextMetrics** @@ -951,6 +967,8 @@ stroke(path?: Path2D): void Strokes a path. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -997,6 +1015,8 @@ beginPath(): void Creates a drawing path. +Since API version 9, this API is supported in ArkTS widgets. + **Example** ```ts @@ -1037,6 +1057,8 @@ moveTo(x: number, y: number): void Moves a drawing path to a target position on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1082,6 +1104,8 @@ lineTo(x: number, y: number): void Connects the current point to a target position using a straight line. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1127,6 +1151,8 @@ closePath(): void Draws a closed path. +Since API version 9, this API is supported in ArkTS widgets. + **Example** ```ts @@ -1167,12 +1193,14 @@ createPattern(image: ImageBitmap, repetition: string | null): CanvasPattern | nu Creates a pattern for image filling based on a specified source image and repetition mode. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory| Description | | ---------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ | | image | [ImageBitmap](ts-components-canvas-imagebitmap.md) | Yes | Source image. For details, see **ImageBitmap**. | -| repetition | string | Yes | Repetition mode. The value can be **'repeat'**, **'repeat-x'**, **'repeat-y'**, or **'no-repeat'**.
Default value: **''**| +| repetition | string | Yes | Repetition mode. The value can be **'repeat'**, **'repeat-x'**, **'repeat-y'**, **'no-repeat'**, **'clamp'**, or **'mirror'**.
Default value: **''**| **Return value** @@ -1218,6 +1246,8 @@ bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, Draws a cubic bezier curve on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1267,6 +1297,8 @@ quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void Draws a quadratic curve on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1314,6 +1346,8 @@ arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, Draws an arc on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1362,6 +1396,8 @@ arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void Draws an arc based on the radius and points on the arc. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1409,6 +1445,8 @@ ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number Draws an ellipse in the specified rectangular region on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1459,6 +1497,8 @@ rect(x: number, y: number, w: number, h: number): void Creates a rectangle on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1504,6 +1544,8 @@ fill(fillRule?: CanvasFillRule): void Fills the area inside a closed path on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1545,6 +1587,8 @@ fill(path: Path2D, fillRule?: CanvasFillRule): void Fills the area inside a closed path on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1598,6 +1642,8 @@ clip(fillRule?: CanvasFillRule): void Sets the current path to a clipping area. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1641,6 +1687,8 @@ clip(path: Path2D, fillRule?: CanvasFillRule): void Sets the current path to a clipping path. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1653,35 +1701,35 @@ Sets the current path to a clipping path. ```ts // xxx.ets -@Entry -@Component -struct Clip { - 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 region = new Path2D() - region.moveTo(30, 90) - region.lineTo(110, 20) - region.lineTo(240, 130) - region.lineTo(60, 130) - region.lineTo(190, 20) - region.lineTo(270, 90) - region.closePath() - this.context.clip(region,"evenodd") - this.context.fillStyle = "rgb(0,255,0)" - this.context.fillRect(0, 0, this.context.width, this.context.height) - }) + @Entry + @Component + struct Clip { + 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 region = new Path2D() + region.moveTo(30, 90) + region.lineTo(110, 20) + region.lineTo(240, 130) + region.lineTo(60, 130) + region.lineTo(190, 20) + region.lineTo(270, 90) + region.closePath() + this.context.clip(region,"evenodd") + this.context.fillStyle = "rgb(0,255,0)" + this.context.fillRect(0, 0, this.context.width, this.context.height) + }) + } + .width('100%') + .height('100%') } - .width('100%') - .height('100%') } -} ``` ![en-us_image_000000127777779](figures/en-us_image_000000127777779.png) @@ -1693,6 +1741,8 @@ filter(filter: string): void Provides filter effects. This API is a void API. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1706,6 +1756,8 @@ 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. + ### resetTransform @@ -1713,6 +1765,8 @@ resetTransform(): void 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 @@ -1720,6 +1774,8 @@ direction(direction: CanvasDirection): void Sets the current text direction used to draw text. This API is a void API. +Since API version 9, this API is supported in ArkTS widgets. + ### rotate @@ -1727,6 +1783,8 @@ rotate(angle: number): void Rotates a canvas clockwise around its coordinate axes. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1769,6 +1827,8 @@ scale(x: number, y: number): void Scales the canvas based on the given scale factors. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1814,6 +1874,8 @@ transform(a: number, b: number, c: number, d: number, e: number, f: number): voi Defines a transformation matrix. To transform a graph, you only need to set parameters of the matrix. The coordinates of the graph are multiplied by the matrix values to obtain new coordinates of the transformed graph. You can use the matrix to implement multiple transform effects. +Since API version 9, this API is supported in ArkTS widgets. + > **NOTE** > > The following formulas calculate coordinates of the transformed graph. **x** and **y** represent coordinates before transformation, and **x'** and **y'** represent coordinates after transformation. @@ -1875,6 +1937,8 @@ setTransform(a: number, b: number, c: number, d: number, e: number, f: number): Resets the existing transformation matrix and creates a new transformation matrix by using the same parameters as the **transform()** API. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1932,6 +1996,8 @@ translate(x: number, y: number): void Moves the origin of the coordinate system. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1980,7 +2046,7 @@ drawImage(image: ImageBitmap | PixelMap, sx: number, sy: number, sw: number, sh: Draws an image on the canvas. -Since API version 9, this API is supported in ArkTS widgets. +Since API version 9, this API is supported in ArkTS widgets, except that **PixelMap** objects are not supported. **Parameters** @@ -2033,6 +2099,8 @@ createImageData(sw: number, sh: number): ImageData Creates an **[ImageData](ts-components-canvas-imagedata.md)** object with the specified dimensions. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -2045,6 +2113,8 @@ createImageData(imageData: ImageData): ImageData Creates an **[ImageData](ts-components-canvas-imagedata.md)** object. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -2085,6 +2155,8 @@ getImageData(sx: number, sy: number, sw: number, sh: number): ImageData Obtains the **[ImageData](ts-components-canvas-imagedata.md)** object created with the pixels within the specified area on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -2105,29 +2177,29 @@ Obtains the **[ImageData](ts-components-canvas-imagedata.md)** object created wi ```ts // xxx.ets -@Entry -@Component -struct GetImageData { - private settings: RenderingContextSettings = new RenderingContextSettings(true) - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - private img:ImageBitmap = new ImageBitmap("/common/images/1234.png") + @Entry + @Component + struct GetImageData { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private img:ImageBitmap = new ImageBitmap("/common/images/1234.png") - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() =>{ - this.context.drawImage(this.img,0,0,130,130) - var imagedata = this.context.getImageData(50,50,130,130) - this.context.putImageData(imagedata,150,150) - }) + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.context.drawImage(this.img,0,0,130,130) + var imagedata = this.context.getImageData(50,50,130,130) + this.context.putImageData(imagedata,150,150) + }) + } + .width('100%') + .height('100%') } - .width('100%') - .height('100%') } -} ``` ![en-us_image_000000127777780](figures/en-us_image_000000127777780.png) @@ -2141,6 +2213,8 @@ putImageData(imageData: ImageData, dx: number, dy: number, dirtyX: number, dirty Puts an **[ImageData](ts-components-canvas-imagedata.md)** object onto a rectangular area on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -2195,6 +2269,8 @@ setLineDash(segments: number[]): void Sets the dash line style. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Description | @@ -2238,6 +2314,8 @@ getLineDash(): number[] Obtains the dash line style. +Since API version 9, this API is supported in ArkTS widgets. + **Return value** | Type | Description | @@ -2249,40 +2327,40 @@ Obtains the dash line style. ```ts // xxx.ets -@Entry -@Component -struct CanvasGetLineDash { - @State message: string = 'Hello World' - private settings: RenderingContextSettings = new RenderingContextSettings(true) - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + @Entry + @Component + struct CanvasGetLineDash { + @State message: string = 'Hello World' + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - build() { - Row() { - Column() { - Text(this.message) - .fontSize(50) - .fontWeight(FontWeight.Bold) - .onClick(()=>{ - console.error('before getlinedash clicked') - let res = this.context.getLineDash() - console.error(JSON.stringify(res)) - }) - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() => { - this.context.arc(100, 75, 50, 0, 6.28) - this.context.setLineDash([10,20]) - this.context.stroke() - let res = this.context.getLineDash() - }) + build() { + Row() { + Column() { + Text(this.message) + .fontSize(50) + .fontWeight(FontWeight.Bold) + .onClick(()=>{ + console.error('before getlinedash clicked') + let res = this.context.getLineDash() + console.error(JSON.stringify(res)) + }) + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() => { + this.context.arc(100, 75, 50, 0, 6.28) + this.context.setLineDash([10,20]) + this.context.stroke() + let res = this.context.getLineDash() + }) + } + .width('100%') } - .width('100%') + .height('100%') } - .height('100%') } -} ``` ![en-us_image_000000127777778](figures/en-us_image_000000127777778.png) @@ -2294,6 +2372,8 @@ imageSmoothingQuality(quality: imageSmoothingQuality) Sets the quality of image smoothing. This API is a void API. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Description | @@ -2308,6 +2388,8 @@ transferFromImageBitmap(bitmap: ImageBitmap): void Displays the specified **ImageBitmap** object. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Description | @@ -2377,26 +2459,26 @@ Since API version 9, this API is supported in ArkTS widgets. ```ts // xxx.ets -@Entry -@Component -struct ToDataURL { - private settings: RenderingContextSettings = new RenderingContextSettings(true) - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + @Entry + @Component + struct ToDataURL { + 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(() =>{ - var dataURL = this.context.toDataURL() - }) + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + var dataURL = this.context.toDataURL() + }) + } + .width('100%') + .height('100%') } - .width('100%') - .height('100%') } -} ``` @@ -2406,6 +2488,8 @@ restore(): void Restores the saved drawing context. +Since API version 9, this API is supported in ArkTS widgets. + **Example** ```ts @@ -2444,6 +2528,8 @@ save(): void Saves all states of the canvas in the stack. This API is usually called when the drawing state needs to be saved. +Since API version 9, this API is supported in ArkTS widgets. + **Example** ```ts @@ -2482,6 +2568,8 @@ createLinearGradient(x0: number, y0: number, x1: number, y1: number): void Creates a linear gradient. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -2513,7 +2601,7 @@ Creates a linear gradient. grad.addColorStop(0.5, '#ffffff') grad.addColorStop(1.0, '#00ff00') this.context.fillStyle = grad - this.context.fillRect(0, 0, 500, 500) + this.context.fillRect(0, 0, 400, 400) }) } .width('100%') @@ -2531,6 +2619,8 @@ createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, Creates a linear gradient. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -2564,7 +2654,7 @@ Creates a linear gradient. grad.addColorStop(0.5, '#ffffff') grad.addColorStop(1.0, '#00ff00') this.context.fillStyle = grad - this.context.fillRect(0, 0, 500, 500) + this.context.fillRect(0, 0, 440, 440) }) } .width('100%') @@ -2575,7 +2665,55 @@ Creates a linear gradient. ![en-us_image_0000001257058405](figures/en-us_image_0000001257058405.png) +### createConicGradient10+ + +createConicGradient(startAngle: number, x: number, y: number): CanvasGradient + +Creates a conic gradient. + +**Parameters** + +| 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 | Y-coordinate of the center of the conic gradient, in vp. | + +**Example** + +```ts +// xxx.ets +@Entry +@Component +struct CanvasExample { + 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('#ffffff') + .onReady(() => { + var grad = this.context.createConicGradient(0, 50, 80) + grad.addColorStop(0.0, '#ff0000') + grad.addColorStop(0.5, '#ffffff') + grad.addColorStop(1.0, '#00ff00') + this.context.fillStyle = grad + this.context.fillRect(0, 30, 100, 100) + }) + } + .width('100%') + .height('100%') + } +} +``` + + ![en-us_image_0000001239032419](figures/en-us_image_0000001239032420.png) ## CanvasPattern Defines an object created using the **[createPattern](#createpattern)** API. + +Since API version 9, this API is supported in ArkTS widgets. diff --git a/en/application-dev/reference/arkui-ts/ts-components-canvas-canvasgradient.md b/en/application-dev/reference/arkui-ts/ts-components-canvas-canvasgradient.md index 3dfd9e208ee1de61b82e2509041469caeef030a9..35211ab1665ca4dbee56199a3c449ae9ff2a8a0b 100644 --- a/en/application-dev/reference/arkui-ts/ts-components-canvas-canvasgradient.md +++ b/en/application-dev/reference/arkui-ts/ts-components-canvas-canvasgradient.md @@ -47,7 +47,7 @@ struct Page45 { grad.addColorStop(0.5, '#ffffff') grad.addColorStop(1.0, '#00ff00') this.context.fillStyle = grad - this.context.fillRect(0, 0, 500, 500) + this.context.fillRect(0, 0, 400, 400) }) } .width('100%') diff --git a/en/application-dev/reference/arkui-ts/ts-components-canvas-imagedata.md b/en/application-dev/reference/arkui-ts/ts-components-canvas-imagedata.md index 7e03641e1383e7df649a64c9a579808840953650..0f7986996d4ff127d1fe37ced8785e23ba3fbcef 100644 --- a/en/application-dev/reference/arkui-ts/ts-components-canvas-imagedata.md +++ b/en/application-dev/reference/arkui-ts/ts-components-canvas-imagedata.md @@ -24,29 +24,29 @@ An **ImageData** object stores pixel data rendered on a canvas. ```ts // xxx.ets -@Entry -@Component -struct Translate { - private settings: RenderingContextSettings = new RenderingContextSettings(true) - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - private img:ImageBitmap = new ImageBitmap("/common/images/1234.png") - - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() =>{ - this.context.drawImage(this.img,0,0,130,130) - var imagedata = this.context.getImageData(50,50,130,130) - this.context.putImageData(imagedata,150,150) - }) + @Entry + @Component + struct Translate { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private img:ImageBitmap = new ImageBitmap("common/images/1234.png") + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.context.drawImage(this.img,0,0,130,130) + var imagedata = this.context.getImageData(50,50,130,130) + this.context.putImageData(imagedata,150,150) + }) + } + .width('100%') + .height('100%') } - .width('100%') - .height('100%') } -} ``` ![en-us_image_000000127777780](figures/en-us_image_000000127777780.png) diff --git a/en/application-dev/reference/arkui-ts/ts-components-canvas-path2d.md b/en/application-dev/reference/arkui-ts/ts-components-canvas-path2d.md index eedbf1762231bd583008cc4ed96bbc544bbb2a63..8631b826c6359daa2e4ade620b193e9e4033c2be 100644 --- a/en/application-dev/reference/arkui-ts/ts-components-canvas-path2d.md +++ b/en/application-dev/reference/arkui-ts/ts-components-canvas-path2d.md @@ -1,8 +1,8 @@ # Path2D -**Path2D** allows you to describe a path through an existing path. This path can be drawn through the **stroke** API of **Canvas**. +**Path2D** allows you to describe a path through an existing path. This path can be drawn through the **stroke** or **fill** API of **Canvas**. -> **NOTE** +> **NOTE** > > The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. @@ -18,11 +18,11 @@ Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| Name| Type| Mandatory| Default Value| Description| -| -------- | -------- | -------- | -------- | -------- | -| path | path2D | Yes| - | Path to be added to this path.| -| transform | Matrix2D | No| null | Transformation matrix of the new path.| - + | Name| Type| Mandatory| Default Value| Description| + | -------- | -------- | -------- | -------- | -------- | + | path | path2D | Yes| - | Path to be added to this path.| + | transform | Matrix2D | No| null | Transformation matrix of the new path.| + **Example** @@ -109,10 +109,10 @@ Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| Name| Type| Mandatory| Default Value| Description| -| -------- | -------- | -------- | -------- | -------- | -| x | number | Yes| 0 | X-coordinate of the target point.| -| y | number | Yes| 0 | Y-coordinate of the target point.| + | Name| Type| Mandatory| Default Value| Description| + | -------- | -------- | -------- | -------- | -------- | + | x | number | Yes| 0 | X-coordinate of the target point.| + | y | number | Yes| 0 | Y-coordinate of the target point.| **Example** @@ -158,10 +158,10 @@ Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| Name| Type| Mandatory| Default Value| Description| -| -------- | -------- | -------- | -------- | -------- | -| x | number | Yes| 0 | X-coordinate of the target point.| -| y | number | Yes| 0 | Y-coordinate of the target point.| + | Name| Type| Mandatory| Default Value| Description| + | -------- | -------- | -------- | -------- | -------- | + | x | number | Yes| 0 | X-coordinate of the target point.| + | y | number | Yes| 0 | Y-coordinate of the target point.| **Example** @@ -208,14 +208,14 @@ Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| 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.| + | 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.| **Example** @@ -259,12 +259,12 @@ Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| 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.| + | 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.| **Example** @@ -308,14 +308,14 @@ Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| 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.| -| 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.| -| counterclockwise | boolean | No| false | Whether to draw the arc counterclockwise.| + | 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.| + | 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.| + | counterclockwise | boolean | No| false | Whether to draw the arc counterclockwise.| **Example** @@ -358,13 +358,13 @@ Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| 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.| -| radius | number | Yes| 0 | Radius of the arc.| + | 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.| + | radius | number | Yes| 0 | Radius of the arc.| **Example** @@ -407,16 +407,16 @@ Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| 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.| -| 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.| -| startAngle | number | Yes| 0 | Angle of the start point for drawing the ellipse. The unit is radian.| -| endAngle | number | Yes| 0 | Angle of the end point for drawing the ellipse. The unit is radian.| -| counterclockwise | boolean | No| false | Whether to draw the ellipse counterclockwise.
**true**: Draw the ellipse counterclockwise.
**false**: Draw the ellipse clockwise.| + | 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.| + | 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.| + | startAngle | number | Yes| 0 | Angle of the start point for drawing the ellipse. The unit is radian.| + | endAngle | number | Yes| 0 | Angle of the end point for drawing the ellipse. The unit is radian.| + | counterclockwise | boolean | No| false | Whether to draw the ellipse counterclockwise.
**true**: Draw the ellipse counterclockwise.
**false**: Draw the ellipse clockwise.| **Example** @@ -459,12 +459,12 @@ Since API version 9, this API is supported in ArkTS widgets. **Parameters** -| 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.| -| w | number | Yes| 0 | Width of the rectangle.| -| h | number | Yes| 0 | Height of the rectangle.| + | 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.| + | w | number | Yes| 0 | Width of the rectangle.| + | h | number | Yes| 0 | Height of the rectangle.| **Example** diff --git a/en/application-dev/reference/arkui-ts/ts-container-grid.md b/en/application-dev/reference/arkui-ts/ts-container-grid.md index db7aaa87e31c0e1cc15c90035a6b210a00faf8e1..d70db0cd88744a19259ef30153ae50eff5f49fbe 100644 --- a/en/application-dev/reference/arkui-ts/ts-container-grid.md +++ b/en/application-dev/reference/arkui-ts/ts-container-grid.md @@ -9,7 +9,23 @@ The **\** component consists of cells formed by rows and columns. You can ## Child Components -This component contains the child component **[\](ts-container-griditem.md)**. +The **\** component accepts only **\<[GridItem](ts-container-griditem.md)>** as its child components. + +> **NOTE** +> +> Below are the rules for calculating the indexes of the child components of **\**: +> +> The index increases in ascending order of child components. +> +> In the **if/else** statement, only the child components in the branch where the condition is met participate in the index calculation. +> +> In the **ForEach** or **LazyForEach** statement, the indexes of all expanded subnodes are calculated. +> +> If the values of [if/else](../../quick-start/arkts-rendering-control-ifelse.md), [ForEach](../../quick-start/arkts-rendering-control-foreach.md), and [LazyForEach](../../quick-start/arkts-rendering-control-lazyforeach.md) change, the indexes of subnodes are updated. +> +> Child components of **\** whose **visibility** attribute is set to **Hidden** or **None** are included in the index calculation. +> +> Child components of **\** whose **visibility** attribute is set to **None** are not displayed, but still take up the corresponding cells. ## APIs @@ -18,9 +34,9 @@ Grid(scroller?: Scroller) **Parameters** -| Name | Type | Mandatory | Description | -| --------- | ---------------------------------------- | ---- | ----------------------- | -| scroller | [Scroller](ts-container-scroll.md#scroller) | No | Scroller, which can be bound to scrollable components.| +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | +| scroller | [Scroller](ts-container-scroll.md#scroller) | No | Controller, which can be bound to scrollable components.
**NOTE**
The scroller cannot be bound to other [scrollable components](ts-container-list.md).| ## Attributes @@ -28,41 +44,57 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the | Name| Type| Description| | -------- | -------- | -------- | -| columnsTemplate | string | Number of columns in the current grid layout. If this attribute is not set, one column is used by default.
For example, **'1fr 1fr 2fr'** indicates three columns, with the first column taking up 1/4 of the parent component's full width, the second column 1/4, and the third column 2/4.| -| rowsTemplate | string | Number of rows in the current grid layout. If this attribute is not set, one row is used by default.
For example, **'1fr 1fr 2fr'** indicates three rows, with the first row taking up 1/4 of the parent component's full height, the second row 1/4, and the third row 2/4.| -| columnsGap | Length | Gap between columns.
Default value: **0**| -| rowsGap | Length | Gap between rows.
Default value: **0**| -| scrollBar | [BarState](ts-appendix-enums.md#barstate) | Scrollbar status.
Default value: **BarState.Off**| -| scrollBarColor | string \| number \| Color | Color of the scrollbar.| -| scrollBarWidth | string \| number | Width of the scrollbar.| -| cachedCount | number | Number of grid items to be preloaded. For details, see [Minimizing White Blocks During Swiping](../../ui/ui-ts-performance-improvement-recommendation.md#minimizing-white-blocks-during-swiping).
Default value: **1**| -| editMode 8+ | boolean | Whether to enter editing mode. In editing mode, the user can drag the **[\](ts-container-griditem.md)** in the **\** component.
Default value: **false** | +| columnsTemplate | string | Number of columns in the current grid layout. If this attribute is not set, one column is used by default.
For example, **'1fr 1fr 2fr'** indicates three columns, with the first column taking up 1/4 of the parent component's full width, the second column 1/4, and the third column 2/4.
**NOTE**
If this attribute is set to **'0fr'**, the column width is 0, and grid item in the column is not displayed. If this attribute is set to any other invalid value, the grid item is displayed as one column.| +| rowsTemplate | string | Number of rows in the current grid layout. If this attribute is not set, one row is used by default.
For example, **'1fr 1fr 2fr'** indicates three rows, with the first row taking up 1/4 of the parent component's full height, the second row 1/4, and the third row 2/4.
**NOTE**
If this attribute is set to **'0fr'**, the row width is 0, and grid item in the row is not displayed. If this attribute is set to any other invalid value, the grid item is displayed as one row.| +| columnsGap | [Length](ts-types.md#length) | Gap between columns.
Default value: **0**
**NOTE**
A value less than 0 evaluates to the default value.| +| rowsGap | [Length](ts-types.md#length) | Gap between rows.
Default value: **0**
**NOTE**
A value less than 0 evaluates to the default value.| +| scrollBar | [BarState](ts-appendix-enums.md#barstate) | Scrollbar status.
Default value: **BarState.Off** | +| scrollBarColor | string \| number \| [Color](ts-appendix-enums.md#color) | Color of the scrollbar.| +| scrollBarWidth | string \| number | Width of the scrollbar. After the width is set, the scrollbar is displayed with the set width in normal state and pressed state.
Default value: **4**
Unit: vp| +| cachedCount | number | Number of grid items to be preloaded (cached). It works only in [LazyForEach](../../quick-start/arkts-rendering-control-lazyforeach.md). For details, see [Minimizing White Blocks During Swiping](../../ui/arkts-performance-improvement-recommendation.md#minimizing-white-blocks-during-swiping).
Default value: **1**
**NOTE**
The number of the grid items to be cached before and after the currently displayed one equals the value of **cachedCount** multiplied by the number of columns.
Grid items that exceed the display and cache range are released.
A value less than 0 evaluates to the default value.| +| editMode 8+ | boolean | Whether to enter editing mode. In editing mode, the user can drag the **\<[GridItem](ts-container-griditem.md)>** in the **\** component.
Default value: **false**| | layoutDirection8+ | [GridDirection](#griddirection8) | Main axis direction of the grid.
Default value: **GridDirection.Row**| -| maxCount8+ | number | When **layoutDirection** is **Row** or **RowReverse**: maximum number of columns that can be displayed.
When **layoutDirection** is **Column** or **ColumnReverse**: maximum number of rows that can be displayed.
Default value: **Infinity**| -| minCount8+ | number | When **layoutDirection** is **Row** or **RowReverse**: minimum number of columns that can be displayed.
When **layoutDirection** is **Column** or **ColumnReverse**: maximum number of rows that can be displayed.
Default value: **1**| +| maxCount8+ | number | When **layoutDirection** is **Row** or **RowReverse**: maximum number of columns that can be displayed.
When **layoutDirection** is **Column** or **ColumnReverse**: maximum number of rows that can be displayed.
Default value: **Infinity**
**NOTE**
If the value of **maxCount** is smaller than that of **minCount**, the default values of **maxCount** and **minCount** are used.
A value less than 0 evaluates to the default value.| +| minCount8+ | number | When **layoutDirection** is **Row** or **RowReverse**: minimum number of columns that can be displayed.
When **layoutDirection** is **Column** or **ColumnReverse**: minimum number of rows that can be displayed.
Default value: **1**
**NOTE**
A value less than 0 evaluates to the default value.| | cellLength8+ | number | When **layoutDirection** is **Row** or **RowReverse**: fixed height per row.
When **layoutDirection** is **Column** or **ColumnReverse**: fixed width per column.
Default value: size of the first element| | multiSelectable8+ | boolean | Whether to enable mouse frame selection.
Default value: **false**
- **false**: The mouse frame selection is disabled.
- **true**: The mouse frame selection is enabled.| -| supportAnimation8+ | boolean | Whether to enable animation.
Default value: **false**| +| supportAnimation8+ | boolean | Whether to enable animation. Currently, the grid item drag animation is supported.
Default value: **false**| Depending on the settings of the **rowsTemplate** and **columnsTemplate** attributes, the **\** component supports the following layout modes: 1. **rowsTemplate** and **columnsTemplate** are both set - The **\** displays only elements in a fixed number of rows and columns and cannot be scrolled. For example, if both **rowsTemplate** and **columnsTemplate** are set to **"1fr 1fr"**, only four elements (two rows and two columns) are displayed. - - In this mode, the following attributes do not take effect: **layoutDirection**, **maxCount**, minCount, and **cellLength**. +- The **\** component displays only elements in a fixed number of rows and columns and cannot be scrolled. +- In this mode, the following attributes do not take effect: **layoutDirection**, **maxCount**, **minCount**, and **cellLength**. +- If the width and height of a grid are not set, the grid adapts to the size of its parent component by default. +- The size of the grid rows and columns is the size of the grid content area minus the gap between rows and columns. It is allocated based on the proportion of each row and column. +- By default, the grid items fill the entire grid. +- In this mode, if a grid item has both **rowStart** and **columnStart** set, it is placed in the position based on the settings. If a grid item already exists in this position, overlapping occurs. +- If a grid item has only **rowStart** or **columnStart** set, the system traverses the previous grid item layout to search for an idle position that meets the settings. If no idle position meets the requirements, the grid item is not laid out. +- If a grid item has neither **rowStart** nor **columnStart** set, the system traverses the previous grid item layout to search for an idle position. If no idle position is available, the grid item is not laid out. +- If a grid item has **rowEnd** set but not **rowStart**, **rowStart** is considered as set to the same value as **rowEnd**. If a grid item has **columnEnd** set but not **columnStart**, **columnStart** is considered as set to the same value as **columnEnd**. 2. Either **rowsTemplate** or **columnsTemplate** is set - The **\** arranges elements in the specified direction and allows for scrolling to display excess elements. For example, if the **\** has 10 elements and **columnsTemplate** is set to **"1fr 1fr 1fr"**, it contains three columns. The elements are arranged in the same direction as the main axis runs down the columns. Elements outside the **\** area can be viewed through scrolling. - - In this mode, the following attributes do not take effect: **layoutDirection**, **maxCount**, **minCount**, and **cellLength**. +- The **\** component arranges elements in the specified direction and allows for scrolling to display excess elements. +- If **columnsTemplate** is set, the component scrolls vertically, the main axis runs vertically, and the cross axis runs horizontally. +- If **rowsTemplate** is set, the component scrolls horizontally, the main axis runs horizontally, and the cross axis runs vertically. +- In this mode, the following attributes do not take effect: **layoutDirection**, **maxCount**, minCount, and **cellLength**. +- The cross axis size of the grid is the cross axis size of the grid content area minus the gaps along the cross axis. It is allocated based on the proportion of each row and column. +- The main axis size of the grid is the maximum height of all grid items in the cross axis direction of the current grid. +- In this mode, if a grid item has both **rowStart** and **columnStart** set, it is placed in the position based on the settings. If a grid item already exists in this position, overlapping occurs. +- If a grid item has only **rowStart** or **columnStart** set, the system traverses the previous grid item layout to search for an idle position that meets the settings. +- If a grid item has neither **rowStart** nor **columnStart** set, the system traverses the previous grid item layout to search for an idle position. +- If a grid item has **rowEnd** set but not **rowStart**, **rowStart** is considered as set to the same value as **rowEnd**. If a grid item has **columnEnd** set but not **columnStart**, **columnStart** is considered as set to the same value as **columnEnd**. 3. Neither **rowsTemplate** nor **columnsTemplate** is set - The **\** arranges elements in the direction specified by **layoutDirection **. The number of columns is jointly determined by the grid width, width of the first element, **minCount**, **maxCount**, and **columnsGap**. The number of rows is jointly determined by the grid height, height of the first element, **cellLength**, and **rowsGap**. Elements outside the determined range of rows and columns are not displayed and cannot be viewed through scrolling. - - In this mode, only the following attributes take effect: **layoutDirection**, **maxCount**, **minCount**, **cellLength**, **editMode**, **columnsGap**, and **rowsGap**. +- The **\** component arranges elements in the direction specified by **layoutDirection**. The number of columns is jointly determined by the grid width, width of the first element, **minCount**, **maxCount**, and **columnsGap**. +- The number of rows is jointly determined by the grid height, height of the first element, **cellLength**, and **rowsGap**. Elements outside the determined range of rows and columns are not displayed and cannot be viewed through scrolling. +- In this mode, only the following attributes take effect: **layoutDirection**, **maxCount**, **minCount**, **cellLength**, **editMode**, **columnsGap**, and **rowsGap**. +- When **layoutDirection** is set to **Row**, elements are arranged from left to right. When a row is full, a new row will be added. If the remaining height is insufficient, no more elements will be laid out, and the top of the content is centered. +- When **layoutDirection** is set to **Column**, elements are arranged from top to bottom. When a column is full, a new column will be added. If the remaining height is insufficient, no more elements will be laid out, and the top of the content is centered. +- In this mode, **rowStart** and **columnStart** of the grid item do not take effect. ## GridDirection8+ @@ -73,14 +105,18 @@ Depending on the settings of the **rowsTemplate** and **columnsTemplate** attrib | RowReverse | Reverse horizontal layout, where the child components are arranged from right to left as the main axis runs along the rows.| | ColumnReverse | Reverse vertical layout, where the child components are arranged from bottom up as the main axis runs down the columns.| +> **NOTE** +> +> The default value of the universal attribute [clip](ts-universal-attributes-sharp-clipping.md) is **true** for the **\** component. + ## Events In addition to the [universal events](ts-universal-events-click.md), the following events are supported. | Name| Description| | -------- | -------- | -| onScrollIndex(event: (first: number) => void) | Triggered when the start item of the grid changes.
- **first**: index of the start item of the grid.| -| onItemDragStart(event: (event: ItemDragInfo, itemIndex: number) => (() => any) \| void) | Triggered when a grid item starts to be dragged.
- **event**: See [ItemDragInfo](#itemdraginfo).
- **itemIndex**: index of the dragged element.| +| onScrollIndex(event: (first: number) => void) | Triggered when the start item of the grid changes. It is triggered once when the grid is initialized.
- **first**: index of the start item of the grid.
If it changes, this event will be triggered.| +| onItemDragStart(event: (event: ItemDragInfo, itemIndex: number) => (() => any) \| void) | Triggered when a grid item starts to be dragged.
- **event**: See [ItemDragInfo](#itemdraginfo).
- **itemIndex**: index of the dragged element.
**NOTE**
If **void** is returned, the drag operation cannot be performed.
This event is triggered when the user long presses a grid item.| | onItemDragEnter(event: (event: ItemDragInfo) => void) | Triggered when the dragged item enters the drop target of the grid.
- **event**: See [ItemDragInfo](#itemdraginfo).| | onItemDragMove(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number) => void) | Triggered when the dragged item moves over the drop target of the grid.
- **event**: See [ItemDragInfo](#itemdraginfo).
- **itemIndex**: initial position of the dragged item.
- **insertIndex**: index of the position to which the dragged item will be dropped.| | onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void) | Triggered when the dragged item exits the drop target of the grid.
- **event**: See [ItemDragInfo](#itemdraginfo).
- **itemIndex**: index of the dragged item.| @@ -90,8 +126,8 @@ In addition to the [universal events](ts-universal-events-click.md), the followi | Name | Type | Description | | ---------- | ---------- | ---------- | -| x | number | X-coordinate of the dragged item. | -| y | number | Y-coordinate of the dragged item. | +| x | number | X coordinate of the dragged item. | +| y | number | Y coordinate of the dragged item. | ## Example diff --git a/en/application-dev/reference/arkui-ts/ts-container-list.md b/en/application-dev/reference/arkui-ts/ts-container-list.md index 09d9024fb37381dfd67e4bf34688092d94c491fb..25d75ce08f639ab0aeba31c2bf035f4e9a060f1e 100644 --- a/en/application-dev/reference/arkui-ts/ts-container-list.md +++ b/en/application-dev/reference/arkui-ts/ts-container-list.md @@ -12,6 +12,24 @@ The **\** component provides a list container that presents a series of li This component supports the **[\](ts-container-listitem.md)** and **[\](ts-container-listitemgroup.md)** child components. +> **NOTE** +> +> Below are the rules for calculating the indexes of the child components of **\**: +> +> The index increases in ascending order of child components. +> +> In the **if/else** statement, only the child components in the branch where the condition is met participate in the index calculation. +> +> In the **ForEach** or **LazyForEach** statement, the indexes of all expanded subnodes are calculated. +> +> If the values of [if/else](../../quick-start/arkts-rendering-control-ifelse.md), [ForEach](../../quick-start/arkts-rendering-control-foreach.md), and [LazyForEach](../../quick-start/arkts-rendering-control-lazyforeach.md) change, the indexes of subnodes are updated. +> +> Each **\** component is taken as a whole and assigned an index, and the indexes of the list items within are not included in the index calculation. +> +> Child components of **\** whose **visibility** attribute is set to **Hidden** or **None** are included in the index calculation. +> +> Child components of **\** whose **visibility** attribute is set to **None** are not displayed, but the spacing above and below them still takes effect. + ## APIs @@ -23,9 +41,9 @@ Since API version 9, this API is supported in ArkTS widgets. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| space | number \| string | No| Spacing between list items.
Default value: **0**| -| initialIndex | number | No| Item displayed at the beginning of the viewport when the current list is loaded for the first time, that is, the first item to be displayed. If the value set is greater than the sequence number of the last item, the setting does not take effect.
Default value: **0**| -| scroller | [Scroller](ts-container-scroll.md#scroller) | No| Scroller, which can be bound to scrollable components.| +| space | number \| string | No| Spacing between list items along the main axis.
Default value: **0**
**NOTE**
If this parameter is set to a percentage or a negative number other than -1, the default value is used.
If the value of **space** is less than the width of the list divider, the latter is used as the spacing.| +| initialIndex | number | No| Item displayed at the beginning of the viewport when the current list is loaded for the first time, that is, the first item to be displayed.
Default value: **0**
**NOTE**
If this parameter is set to a negative value other than -1 or is greater than the index value of the last item in the current list, the value is invalid. In this case, the default value is used.| +| scroller | [Scroller](ts-container-scroll.md#scroller) | No| Scroller, which can be bound to scrollable components.
**NOTE**
The scroller cannot be bound to other scrollable components. | ## Attributes @@ -34,16 +52,16 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the | Name| Type| Description| | -------- | -------- | -------- | | listDirection | [Axis](ts-appendix-enums.md#axis) | Direction in which the list items are arranged.
Default value: **Axis.Vertical**
Since API version 9, this API is supported in ArkTS widgets.| -| divider | {
strokeWidth: [Length](ts-types.md#length),
color?:[ResourceColor](ts-types.md#resourcecolor),
startMargin?: Length,
endMargin?: Length
} \| null | Style of the divider for the list items. By default, there is no divider.
- **strokeWidth**: stroke width of the divider.
- **color**: color of the divider.
- **startMargin**: distance between the divider and the start edge of the list.
- **endMargin**: distance between the divider and the end edge of the list.
Since API version 9, this API is supported in ArkTS widgets.| -| scrollBar | [BarState](ts-appendix-enums.md#barstate) | Scrollbar status.
Default value: **BarState.Off**
Since API version 9, this API is supported in ArkTS widgets.| -| cachedCount | number | Number of list items or list item groups to be preloaded. A list item group is calculated as a whole, and all list items of the group are preloaded at the same time. For details, see [Minimizing White Blocks During Swiping](../../ui/ui-ts-performance-improvement-recommendation.md#minimizing-white-blocks-during-swiping).
Default value: **1**
Since API version 9, this API is supported in ArkTS widgets.| +| divider | {
strokeWidth: [Length](ts-types.md#length),
color?:[ResourceColor](ts-types.md#resourcecolor),
startMargin?: Length,
endMargin?: Length
} \| null | Style of the divider for the list items. By default, there is no divider. This attribute cannot be set in percentage.
- **strokeWidth**: stroke width of the divider.
- **color**: color of the divider.
- **startMargin**: distance between the divider and the start edge of the list.
- **endMargin**: distance between the divider and the end edge of the list.
Since API version 9, this API is supported in ArkTS widgets.
The sum of **endMargin** and **startMargin** cannot exceed the column width.
**startMargin** and **endMargin** cannot be set in percentage.
The divider is drawn between list items along the main axis, and not above the first list item and below the last list item.
In multi-column mode, the value of **startMargin** is calculated from the start edge of the cross axis of each column. In other cases, it is calculated from the start edge of the cross axis of the list.| +| scrollBar | [BarState](ts-appendix-enums.md#barstate) | Scrollbar status.
Default value: **BarState.Off**
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
In API version 9 and earlier versions, the default value is **BarState.Off**. In API version 10, the default value is **BarState.Auto**.| +| cachedCount | number | Number of list items or list item groups to be preloaded (cached). It works only in [LazyForEach](../../quick-start/arkts-rendering-control-lazyforeach.md). A list item group is calculated as a whole, and all list items of the group are preloaded at the same time. For details, see [Minimizing White Blocks During Swiping](../../ui/arkts-performance-improvement-recommendation.md#minimizing-white-blocks-during-swiping).
Default value: **1**
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
In single-column mode, the number of the list items to be cached before and after the currently displayed one equals the value of **cachedCount**.
In multi-column mode, the number of the list items to be cached is the value of **cachedCount** multiplied by the number of columns.| | editMode(deprecated) | boolean | Whether to enter editing mode.
This API is deprecated since API version 9.
Default value: **false**| -| edgeEffect | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | Scroll effect.
Default value: **EdgeEffect.Spring**
Since API version 9, this API is supported in ArkTS widgets.| +| edgeEffect | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | Scroll effect. The spring effect and shadow effect are supported.
Default value: **EdgeEffect.Spring**
Since API version 9, this API is supported in ArkTS widgets.| | chainAnimation | boolean | Whether to display chained animations on this list when it slides or its top or bottom is dragged. The list items are separated with even space, and one item animation starts after the previous animation during basic sliding interactions. The chained animation effect is similar with spring physics.
Default value: **false**
- **false**: No chained animations are displayed.
- **true**: Chained animations are displayed.
Since API version 9, this API is supported in ArkTS widgets.| | multiSelectable8+ | boolean | Whether to enable mouse frame selection.
Default value: **false**
- **false**: The mouse frame selection is disabled.
- **true**: The mouse frame selection is enabled.
Since API version 9, this API is supported in ArkTS widgets.| -| lanes9+ | number \| [LengthConstrain](ts-types.md#lengthconstrain) | In the following description, **listDirection** is set to **Axis.Vertical**:
Number of columns in which the list items are arranged along the cross axis.
Default value: **1**
The rules are as follows:
- If the value is set to a number, the column width is determined based on the specified number and the cross-axis width of the **\** component.
- If the value is set to {minLength, maxLength}, the number of columns is adjusted adaptively based on the width of the **\** component, ensuring that the width respects the {minLength, maxLength} constraints during adaptation. The **minLength** constraint is prioritized. For example, if **lanes** is set to **{minLength: 40vp, maxLength: 60vp}** and the width of the **\** component is 70 vp, the list items are arranged in one column with their alignment compliant with the **alignListItem** settings. If the width of the **\** component is changed to 80 vp, which is twice the value of **minLength**, the list items are arranged in two columns.
This API is supported in ArkTS widgets.| -| alignListItem9+ | ListItemAlign | Alignment mode of list items along the cross axis when: Cross-axis width of the **\** component > Cross-axis width of list items x Value of **lanes**.
Default value: **ListItemAlign.Start**
This API is supported in ArkTS widgets.| -| sticky9+ | StickyStyle | Whether to pin the header to the top or the footer to the bottom in the **\** component. This attribute is used together with the **[\](ts-container-listitemgroup.md)** component.
Default value: **StickyStyle.None**
This API is supported in ArkTS widgets.
**NOTE**
The **sticky** attribute can be set to **StickyStyle.Header** or \| **StickyStyle.Footer** to support both the pin-to-top and pin-to-bottom features.| +| lanes9+ | number \| [LengthConstrain](ts-types.md#lengthconstrain) | In the following description, **listDirection** is set to **Axis.Vertical**:
Number of columns in which the list items are arranged along the cross axis.
Default value: **1**
The rules are as follows:
- If the value is set to a number, the column width is calculated by dividing the cross-axis width of the **\** component by the specified number.
- If the value is set to {minLength, maxLength}, the number of columns is adjusted adaptively based on the width of the **\** component, ensuring that the width respects the {minLength, maxLength} constraints during adaptation. The **minLength** constraint is prioritized.
- If the value is set to {minLength, maxLength}, and the cross-axis width constraint of the parent component is infinite, the parent component is arranged by column, and the column width is calculated based on the maximum width of list items in the display area.
- Each list item group occupies one row in multi-column mode. Its child list items are arranged based on the **lanes** attribute of the list.
- If the value is set to {minLength, maxLength}, the number of columns is calculated based on the cross-axis width of the list item group. If the cross-axis width of the list item group is different from that of the list, the number of columns in the list item group may be different from that in the list.
This API is supported in ArkTS widgets. | +| alignListItem9+ | [ListItemAlign](#listitemalign9) | Alignment mode of list items along the cross axis when: Cross-axis width of the **\** component > Cross-axis width of list items x Value of **lanes**.
Default value: **ListItemAlign.Start**
This API is supported in ArkTS widgets.| +| sticky9+ | [StickyStyle](#stickystyle9) | Whether to pin the header to the top or the footer to the bottom in the **\** component. This attribute is used together with the **[\](ts-container-listitemgroup.md)** component.
Default value: **StickyStyle.None**
This API is supported in ArkTS widgets.
**NOTE**
The **sticky** attribute can be set to **StickyStyle.Header** or \| **StickyStyle.Footer** to support both the pin-to-top and pin-to-bottom features.| ## ListItemAlign9+ @@ -62,21 +80,23 @@ This API is supported in ArkTS widgets. | Name | Description | | ------ | -------------------------------------- | | None | In the **\** component, the header is not pinned to the top, and the footer is not pinned to the bottom.| -| Header | In the **\** component, the header is pinned to the top.| -| Footer | In the **\** component, the footer is pinned to the bottom.| - +| Header | In the **\** component, the header is pinned to the top, and the footer is not pinned to the bottom.| +| Footer | In the **\** component, the footer is pinned to the bottom, and the header is not pinned to the top.| +> **NOTE** +> +> The default value of the universal attribute [clip](ts-universal-attributes-sharp-clipping.md) is **true** for the **\** component. ## Events | Name| Description| | -------- | -------- | | onItemDelete(deprecated)(event: (index: number) => boolean) | Triggered when a list item is deleted.
This API is deprecated since API version 9.
- **index**: index of the deleted list item.| -| onScroll(event: (scrollOffset: number, scrollState: ScrollState) => void) | Triggered when the list scrolls.
- **scrollOffset**: scroll offset.
- **[scrollState](#scrollstate)**: current scroll state.
Since API version 9, this API is supported in ArkTS widgets.| -| onScrollIndex(event: (start: number, end: number) => void) | Triggered when scrolling starts.
When calculating the index value, the **\** accounts for one index value as a whole, and the index values of the list items within are not calculated.
- **start**: index of the scroll start position.
- **end**: index of the scroll end position.
Since API version 9, this API is supported in ArkTS widgets.| -| onReachStart(event: () => void) | Triggered when the list reaches the start position.
Since API version 9, this API is supported in ArkTS widgets.| -| onReachEnd(event: () => void) | Triggered when the list reaches the end position.
Since API version 9, this API is supported in ArkTS widgets.| -| onScrollFrameBegin9+(event: (offset: number, state: ScrollState) => { offsetRemain }) | Triggered when the list starts to scroll. The input parameters indicate the amount by which the list will scroll. The event handler then works out the amount by which the list needs to scroll based on the real-world situation and returns the result.
\- **offset**: amount to scroll by.
\- **state**: current sliding status.
- **offsetRemain**: actual amount by which the list scrolls.
This API is supported in ArkTS widgets.
**NOTE**
If **listDirection** is set to **Axis.Vertical**, the return value is the amount by which the list needs to scroll in the vertical direction. If **listDirection** is set to **Axis.Horizontal**, the return value is the amount by which the list needs to scroll in the horizontal direction.| +| onScroll(event: (scrollOffset: number, scrollState: ScrollState) => void) | Triggered when the list scrolls.
- **scrollOffset**: scroll offset of each frame. The offset is positive when the list is scrolled up and negative when the list is scrolled down.
- **[scrollState](#scrollstate)**: current scroll state.
This event is not triggered when **ScrollEdge** and **ScrollToIndex** are called by using the controller. In other cases, this event is triggered when scrolling occurs.
Since API version 9, this API is supported in ArkTS widgets.| +| onScrollIndex(event: (start: number, end: number) => void) | Triggered when a child component enters or exits from the list display area.
During index calculation, each **\** component is taken as a whole and assigned an index, and the indexes of the list items within are not included in the calculation.
- **start**: index of the scroll start position.
- **end**: index of the scroll end position.
This event is triggered once when the list is initialized and when the index of the first list item or the next list item in the list display area changes.
When the list edge effect is the spring effect, the **onScrollIndex** event is not triggered when the user scrolls the list to the edge or releases the list to rebound.
Since API version 9, this API is supported in ArkTS widgets.| +| onReachStart(event: () => void) | Triggered when the list reaches the start position.
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
This event is triggered once when **initialIndex** is **0** during list initialization and once when the list scrolls to the start position. When the list edge effect is the spring effect, this event is triggered once when the list passes the start position and is triggered again when the list returns to the start position.| +| onReachEnd(event: () => void) | Triggered when the list reaches the end position.
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
When the list edge effect is the spring effect, this event is triggered once when the list passes the end position and is triggered again when the list returns to the end position.| +| onScrollFrameBegin9+(event: (offset: number, state: ScrollState) => { offsetRemain }) | Triggered when the list starts to scroll. The input parameters indicate the amount by which the list will scroll. The event handler then works out the amount by which the list needs to scroll based on the real-world situation and returns the result.
\- **offset**: amount to scroll by, in vp.
\- **state**: current sliding status.
- **offsetRemain**: actual amount by which the list scrolls, in vp.
This event is triggered when the user starts dragging the list or the list starts inertial scrolling. This event is not triggered when the list rebounds or the scrolling controller is used.
This API is supported in ArkTS widgets.
**NOTE**
If **listDirection** is set to **Axis.Vertical**, the return value is the amount by which the list needs to scroll in the vertical direction. If **listDirection** is set to **Axis.Horizontal**, the return value is the amount by which the list needs to scroll in the horizontal direction.| | onScrollStart9+(event: () => void) | Triggered when the list starts scrolling initiated by the user's finger dragging the **\** component or its scrollbar. This event is also triggered when the animation contained in the scrolling triggered by [Scroller](ts-container-scroll.md#scroller) starts.
This API is supported in ArkTS widgets.| | onScrollStop(event: () => void) | Triggered when the list stops scrolling after the user's finger leaves the screen. This event is also triggered when the animation contained in the scrolling triggered by [Scroller](ts-container-scroll.md#scroller) stops.
Since API version 9, this API is supported in ArkTS widgets.| | onItemMove(event: (from: number, to: number) => boolean) | Triggered when a list item moves.
- **from**: index of the item before moving.
- **to**: index of the item after moving.| @@ -84,7 +104,7 @@ This API is supported in ArkTS widgets. | onItemDragEnter(event: (event: ItemDragInfo) => void) | Triggered when the dragged item enters the drop target of the list.
- **event**: See [ItemDragInfo](ts-container-grid.md#itemdraginfo).| | onItemDragMove(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number) => void) | Triggered when the dragged item moves over the drop target of the list.
- **event**: See [ItemDragInfo](ts-container-grid.md#itemdraginfo).
- **itemIndex**: initial position of the dragged item.
- **insertIndex**: index of the position to which the dragged item will be dropped.| | onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void) | Triggered when the dragged item exits the drop target of the list.
- **event**: See [ItemDragInfo](ts-container-grid.md#itemdraginfo).
- **itemIndex**: index of the list item.| -| onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void) | Triggered when the dragged item is dropped on the drop target of the list.
- **event**: See [ItemDragInfo](ts-container-grid.md#itemdraginfo).
- **itemIndex**: initial position of the dragged item.
- **insertIndex**: index of the position to which the dragged item will be dropped.
- **isSuccess**: whether the dragged item is successfully dropped.| +| onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void) | Triggered when the dragged item is dropped on the drop target of the list.
- **event**: See [ItemDragInfo](ts-container-grid.md#itemdraginfo).
- **itemIndex**: initial position of the dragged item.
- **insertIndex**: index of the position to which the dragged item will be dropped.
- **isSuccess**: whether the dragged item is successfully dropped.
**NOTE**
During dragging across lists, **true** is returned if the drop target is bound to **onItemDrop**. Otherwise, **false** is returned. During dragging within a list, **isSuccess** is the return value of the **onItemMove** event.| ## ScrollState @@ -92,13 +112,13 @@ Since API version 9, this API is supported in ArkTS widgets. | Name | Description | | ------ | ------------------------- | -| Idle | Not scrolling. | -| Scroll | Finger dragging. | -| Fling | Inertial scrolling. | +| Idle | Not scrolling. Triggered when the API provided by the controller is used to scroll the list or when the scrollbar is dragged.| +| Scroll | Finger dragging. Triggered when the user drags the list to scroll.| +| Fling | Inertial scrolling. Triggered when inertial scrolling occurs or when the list bounces back after being released from a quick swipe.| > **NOTE** > -> To enable the editable mode for a list, the following conditions must be met: (This feature is deprecated since API version 9.) +> To enable the editable mode for a list, the following conditions must be met: > > - **editMode** is set to **true**. > @@ -108,7 +128,7 @@ Since API version 9, this API is supported in ArkTS widgets. > > To enable dragging for a list item, the following conditions must be met: > -> - **editMode** is set to **true**. (This is not required since API version 9.) +> - **editMode** is set to **true**. > > - The list item is bound to the **onDragStart** event and the event returns a floating UI during event callback. @@ -183,7 +203,7 @@ struct ListLanesExample { .lanes({ minLength: 40, maxLength: 40 }) .alignListItem(this.alignListItem) - Button("Click to modify alignListItem: "+ this.alignListItem).onClick(() => { + Button("Change alignListItem: "+ this.alignListItem).onClick(() => { if (this.alignListItem == ListItemAlign.Start) { this.alignListItem = ListItemAlign.Center } else if (this.alignListItem == ListItemAlign.Center) { diff --git a/en/application-dev/reference/arkui-ts/ts-drawing-components-line.md b/en/application-dev/reference/arkui-ts/ts-drawing-components-line.md index fec90d36ae1f8b6ebdd3464142a29dbe9bbfd2e7..f17d6856796e158066f4cbe1e20e046fa8d562ff 100644 --- a/en/application-dev/reference/arkui-ts/ts-drawing-components-line.md +++ b/en/application-dev/reference/arkui-ts/ts-drawing-components-line.md @@ -39,7 +39,7 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the | strokeDashArray | Array<Length> | [] | Stroke dashes.
Since API version 9, this API is supported in ArkTS widgets.| | strokeDashOffset | number \| string | 0 | Offset of the start point for drawing the stroke.
Since API version 9, this API is supported in ArkTS widgets.| | strokeLineCap | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | LineCapStyle.Butt | Cap style of the stroke.
Since API version 9, this API is supported in ArkTS widgets.| -| strokeLineJoin | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | LineJoinStyle.Miter | Join style of the stroke.
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
This attribute does not work for the **\** component, which does not have corners. | +| strokeLineJoin | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | LineJoinStyle.Miter | Join style of the stroke.
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
This attribute does not work for the **\** component, which does not have corners.| | strokeMiterLimit | number \| string | 4 | Limit value when the sharp angle is drawn as a miter.
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
This attribute does not take effect because the **\** component cannot be used to draw a shape with a sharp angle.| | strokeOpacity | number \| string \| [Resource](ts-types.md#resource)| 1 | Stroke opacity.
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
The value range is [0.0, 1.0]. If the set value is less than 0.0, **0.0** will be used. If the set value is greater than 1.0, **1.0** will be used.| | strokeWidth | Length | 1 | Stroke width.
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
The value cannot be a percentage.| diff --git a/en/application-dev/reference/arkui-ts/ts-drawing-components-shape.md b/en/application-dev/reference/arkui-ts/ts-drawing-components-shape.md index d97d69beb73a8ac5c3a0a1c52c701287f056f827..c1d54675e22bf4d55b17ccde9727b318c028186f 100644 --- a/en/application-dev/reference/arkui-ts/ts-drawing-components-shape.md +++ b/en/application-dev/reference/arkui-ts/ts-drawing-components-shape.md @@ -21,7 +21,7 @@ The following child components are supported: **[\](ts-drawing-components- Shape(value?: PixelMap) -Since API version 9, this API is supported in ArkTS widgets. +Since API version 9, this API is supported in ArkTS widgets, except that **PixelMap** objects are not supported. **Parameters** @@ -52,8 +52,6 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the ## Example -### Example 1 - ```ts // xxx.ets @Entry diff --git a/en/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md b/en/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md index 9aa9657ae94666cded17944174a3574223e46a77..4c996f22ce50e78e700feef8e334d0961579af7e 100644 --- a/en/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md +++ b/en/application-dev/reference/arkui-ts/ts-offscreencanvasrenderingcontext2d.md @@ -12,6 +12,8 @@ Use **OffscreenCanvasRenderingContext2D** to draw rectangles, images, and text o OffscreenCanvasRenderingContext2D(width: number, height: number, setting: RenderingContextSettings) +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory| Description | @@ -23,25 +25,25 @@ OffscreenCanvasRenderingContext2D(width: number, height: number, setting: Render ## Attributes -| Name | Type | Description | +| Name | Type | Description | | ----------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -| [fillStyle](#fillstyle) | string \| [CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#canvaspattern) | Style to fill an area.
- When the type is **string**, this attribute indicates the color of the filling 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. | -| [lineWidth](#linewidth) | number | Line width. | -| [strokeStyle](#strokestyle) | string \| [CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#canvaspattern) | Stroke style.
- When the type is **\**, this parameter 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. | -| [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, and each endpoint has added a rectangle whose length is the same as the line thickness and whose width is half of the line thickness.
- Default value: **'butt'** | -| [lineJoin](#linejoin) | CanvasLineJoin | Style of the shape used to join line segments. The options are as follows:
- **round**: The intersection is a sector, whose radius at the rounded corner is equal to the line width.
- **bevel**: The intersection is a triangle. The rectangular corner of each line is independent.
- **miter**: The intersection has a miter 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'** | -| [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** | -| [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 can only be pixels.
- (Optional) **font-family**: font family. Available values are **sans-serif**, **serif**, and **monospace**.
Default value: **'normal normal 14px sans-serif'** | -| [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.
**NOTE**
In the **ltr** layout mode, the value **'start'** equals **'left'**. In the **rtl** layout mode, the value **'start'** equals **'right'**.
- Default value: **'left'** | -| [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'** | -| [globalAlpha](#globalalpha) | number | Opacity.
**0.0**: completely transparent.
**1.0**: completely opaque. | -| [lineDashOffset](#linedashoffset) | number | Offset of the dashed line. The precision is float.
- Default value: **0.0** | -| [globalCompositeOperation](#globalcompositeoperation) | string | Composition operation type. Available values are as follows: **'source-over'**, **'source-atop'**, **'source-in'**, **'source-out'**, **'destination-over'**, **'destination-atop'**, **'destination-in'**, **'destination-out'**, **'lighter'**, **'copy'**, and **'xor'**.
- Default value: **'source-over'** | -| [shadowBlur](#shadowblur) | number | Blur level during shadow drawing. A larger value indicates a more blurred effect. The precision is float.
- Default value: **0.0** | -| [shadowColor](#shadowcolor) | string | Shadow color. | -| [shadowOffsetX](#shadowoffsetx) | number | X-axis shadow offset relative to the original object. | -| [shadowOffsetY](#shadowoffsety) | number | Y-axis shadow offset relative to the original object. | -| [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** | +| [fillStyle](#fillstyle) | string \|number10+ \|[CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#canvaspattern) | Style to fill an area.
- When the type is **string**, this attribute indicates the color of the filling area.
- When the type is **number**, this attribute indicates the color of the filling 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.
Since API version 9, this API is supported in ArkTS widgets.| +| [strokeStyle](#strokestyle) | string \|number10+ \|[CanvasGradient](ts-components-canvas-canvasgradient.md) \| [CanvasPattern](#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.| +| [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, and each endpoint has added a rectangle whose length is the same as the line thickness and whose width is half of the line 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 intersection is a sector, whose radius at the rounded corner is equal to the line width.
- **bevel**: The intersection is a triangle. The rectangular corner of each line is independent.
- **miter**: The intersection has a miter 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 can only be pixels.
- (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.
**NOTE**

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. | +| [lineDashOffset](#linedashoffset) | number | Offset of the dashed line. The precision is float.
- Default value: **0.0**
Since API version 9, this API is supported in ArkTS widgets.| +| [globalCompositeOperation](#globalcompositeoperation) | string | Composition operation type. Available values are as follows: **'source-over'**, **'source-atop'**, **'source-in'**, **'source-out'**, **'destination-over'**, **'destination-atop'**, **'destination-in'**, **'destination-out'**, **'lighter'**, **'copy'**, and **'xor'**.
- Default value: **'source-over'**
Since API version 9, this API is supported in ArkTS widgets.| +| [shadowBlur](#shadowblur) | number | Blur level during shadow drawing. A larger value indicates a more blurred effect. The precision is float.
- Default value: **0.0**
Since API version 9, this API is supported in ArkTS widgets.| +| [shadowColor](#shadowcolor) | string | Shadow color.
Since API version 9, this API is supported in ArkTS widgets.| +| [shadowOffsetX](#shadowoffsetx) | number | X-axis shadow offset relative to the original object.
Since API version 9, this API is supported in ArkTS widgets.| +| [shadowOffsetY](#shadowoffsety) | number | Y-axis shadow offset relative to the original object.
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.| > **NOTE** > For **fillStyle**, **shadowColor**, and **strokeStyle**, the value format of the string type is 'rgb(255, 255, 255)', 'rgba(255, 255, 255, 1.0)', '\#FFFFFF'. @@ -66,7 +68,7 @@ struct FillStyleExample { .backgroundColor('#ffff00') .onReady(() =>{ this.offContext.fillStyle = '#0000ff' - this.offContext.fillRect(20, 160, 150, 100) + this.offContext.fillRect(20, 20, 150, 100) var image = this.offContext.transferToImageBitmap() this.context.transferFromImageBitmap(image) }) @@ -700,6 +702,8 @@ fillRect(x: number, y: number, w: number, h: number): void Fills a rectangle on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -747,6 +751,8 @@ strokeRect(x: number, y: number, w: number, h: number): void Draws an outlined rectangle on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -794,6 +800,8 @@ clearRect(x: number, y: number, w: number, h: number): void Clears the content in a rectangle on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -843,6 +851,8 @@ fillText(text: string, x: number, y: number, maxWidth?: number): void Draws filled text on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -891,6 +901,8 @@ strokeText(text: string, x: number, y: number): void Draws a text stroke on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -939,6 +951,8 @@ measureText(text: string): TextMetrics Returns a **TextMetrics** object used to obtain the width of specified text. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -947,9 +961,9 @@ Returns a **TextMetrics** object used to obtain the width of specified text. **Return value** -| Type | Description | -| ----------- | ------- | -| TextMetrics | **TextMetrics** object.| +| Type | Description | +| ----------- | ------------------------------------------------------------ | +| TextMetrics | **TextMetrics** object.
Since API version 9, this API is supported in ArkTS widgets.| **TextMetrics** attributes @@ -1009,6 +1023,8 @@ stroke(path?: Path2D): void Strokes a path. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1058,6 +1074,8 @@ beginPath(): void Creates a drawing path. +Since API version 9, this API is supported in ArkTS widgets. + **Example** ```ts @@ -1101,6 +1119,8 @@ moveTo(x: number, y: number): void Moves a drawing path to a target position on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1149,6 +1169,8 @@ lineTo(x: number, y: number): void Connects the current point to a target position using a straight line. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1197,6 +1219,8 @@ closePath(): void Draws a closed path. +Since API version 9, this API is supported in ArkTS widgets. + **Example** ```ts @@ -1240,12 +1264,14 @@ createPattern(image: ImageBitmap, repetition: string | null): CanvasPattern | nu Creates a pattern for image filling based on a specified source image and repetition mode. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | | ---------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | | image | [ImageBitmap](ts-components-canvas-imagebitmap.md) | Yes | null | Source image. For details, see **ImageBitmap**. | -| repetition | string | Yes | "" | Repetition mode. The value can be **"repeat"**, **"repeat-x"**, **"repeat-y"**, or **"no-repeat"**.| +| repetition | string | Yes | "" | Repetition mode. The value can be **'repeat'**, **'repeat-x'**, **'repeat-y'**, **'no-repeat'**, **'clamp'**, or **'mirror'**.| **Return value** @@ -1294,6 +1320,8 @@ bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, Draws a cubic bezier curve on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1346,6 +1374,8 @@ quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void Draws a quadratic curve on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1396,6 +1426,8 @@ arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, Draws an arc on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1447,6 +1479,8 @@ arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void Draws an arc based on the radius and points on the arc. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1497,6 +1531,8 @@ ellipse(x: number, y: number, radiusX: number, radiusY: number, rotation: number Draws an ellipse in the specified rectangular region on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1549,6 +1585,8 @@ rect(x: number, y: number, w: number, h: number): void Creates a rectangle on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1597,6 +1635,8 @@ fill(fillRule?: CanvasFillRule): void Fills the area inside a closed path on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1638,6 +1678,8 @@ fill(path: Path2D, fillRule?: CanvasFillRule): void Fills the area inside a closed path on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1695,6 +1737,8 @@ clip(fillRule?: CanvasFillRule): void Sets the current path to a clipping path. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1741,6 +1785,8 @@ clip(path:Path2D, fillRule?: CanvasFillRule): void Sets a closed path to a clipping path. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1752,39 +1798,39 @@ Sets a closed path to a clipping path. ```ts // xxx.ets -@Entry -@Component -struct Clip { - private settings: RenderingContextSettings = new RenderingContextSettings(true) - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + @Entry + @Component + struct Clip { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() =>{ - let region = new Path2D() - region.moveTo(30, 90) - region.lineTo(110, 20) - region.lineTo(240, 130) - region.lineTo(60, 130) - region.lineTo(190, 20) - region.lineTo(270, 90) - region.closePath() - this.offContext.clip(region,"evenodd") - this.offContext.fillStyle = "rgb(0,255,0)" - this.offContext.fillRect(0, 0, 600, 600) - var image = this.offContext.transferToImageBitmap() - this.context.transferFromImageBitmap(image) - }) + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + let region = new Path2D() + region.moveTo(30, 90) + region.lineTo(110, 20) + region.lineTo(240, 130) + region.lineTo(60, 130) + region.lineTo(190, 20) + region.lineTo(270, 90) + region.closePath() + this.offContext.clip(region,"evenodd") + this.offContext.fillStyle = "rgb(0,255,0)" + this.offContext.fillRect(0, 0, 600, 600) + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) + }) + } + .width('100%') + .height('100%') } - .width('100%') - .height('100%') } -} ``` ![en-us_image_000000127777779](figures/en-us_image_000000127777779.png) @@ -1797,6 +1843,8 @@ filter(filter: string): void Sets a filter for the image on the canvas. This API is a void API. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1810,6 +1858,8 @@ 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. + ### resetTransform @@ -1817,6 +1867,8 @@ resetTransform(): void 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 @@ -1824,6 +1876,8 @@ direction(direction: CanvasDirection): void Sets the text direction for drawing text. This API is a void API. +Since API version 9, this API is supported in ArkTS widgets. + ### rotate @@ -1831,6 +1885,8 @@ rotate(angle: number): void Rotates a canvas clockwise around its coordinate axes. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1876,6 +1932,8 @@ scale(x: number, y: number): void Scales the canvas based on scale factors. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -1924,6 +1982,8 @@ transform(a: number, b: number, c: number, d: number, e: number, f: number): voi Defines a transformation matrix. To transform a graph, you only need to set parameters of the matrix. The coordinates of the graph are multiplied by the matrix values to obtain new coordinates of the transformed graph. You can use the matrix to implement multiple transform effects. +Since API version 9, this API is supported in ArkTS widgets. + > **NOTE** > > The following formulas calculate coordinates of the transformed graph. **x** and **y** represent coordinates before transformation, and **x'** and **y'** represent coordinates after transformation. @@ -1988,6 +2048,8 @@ setTransform(a: number, b: number, c: number, d: number, e: number, f: number): Resets the existing transformation matrix and creates a new transformation matrix by using the same parameters as the **transform()** API. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -2041,6 +2103,8 @@ translate(x: number, y: number): void Moves the origin of the coordinate system. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -2092,6 +2156,8 @@ drawImage(image: ImageBitmap | PixelMap, sx: number, sy: number, sw: number, sh: Draws an image on the canvas. +Since API version 9, this API is supported in ArkTS widgets, except that **PixelMap** objects are not supported. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -2145,9 +2211,11 @@ createImageData(sw: number, sh: number): ImageData Creates an **[ImageData](ts-components-canvas-imagedata.md)** object with the specified dimensions. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** -| Name | Type | Mandatory | Default Value | Description | +| Parameters | Type | Mandatory | Default Value | Description | | ---- | ------ | ---- | ---- | ------------- | | sw | number | Yes | 0 | Width of the **ImageData** object.| | sh | number | Yes | 0 | Height of the **ImageData** object.| @@ -2157,6 +2225,8 @@ createImageData(imageData: ImageData): ImageData Creates an **[ImageData](ts-components-canvas-imagedata.md)** object by copying an existing **ImageData** object. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -2190,6 +2260,27 @@ Obtains the **[PixelMap](../apis/js-apis-image.md#pixelmap7)** object created wi | ---------------------------------------- | ------------ | | [PixelMap](../apis/js-apis-image.md#pixelmap7) | **PixelMap** object.| +### setPixelMap + +setPixelMap(value?: PixelMap): void + +Draws the input [PixelMap](../apis/js-apis-image.md#pixelmap7) object on the canvas. + + **Parameters** + +| 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.| +| sw | number | Yes | 0 | Width of the output area. | +| sh | number | Yes | 0 | Height of the output area. | + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------------ | +| [PixelMap](../apis/js-apis-image.md#pixelmap7) | **PixelMap** object.| + ### getImageData @@ -2197,6 +2288,8 @@ getImageData(sx: number, sy: number, sw: number, sh: number): ImageData Obtains the **[ImageData](ts-components-canvas-imagedata.md)** object created with the pixels within the specified area on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -2217,32 +2310,32 @@ Obtains the **[ImageData](ts-components-canvas-imagedata.md)** object created wi ```ts // xxx.ets -@Entry -@Component -struct GetImageData { - private settings: RenderingContextSettings = new RenderingContextSettings(true) - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) - private img:ImageBitmap = new ImageBitmap("/common/images/1234.png") + @Entry + @Component + struct GetImageData { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + private img:ImageBitmap = new ImageBitmap("/common/images/1234.png") - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() =>{ - this.offContext.drawImage(this.img,0,0,130,130) - var imagedata = this.offContext.getImageData(50,50,130,130) - this.offContext.putImageData(imagedata,150,150) - var image = this.offContext.transferToImageBitmap() - this.context.transferFromImageBitmap(image) - }) + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.offContext.drawImage(this.img,0,0,130,130) + var imagedata = this.offContext.getImageData(50,50,130,130) + this.offContext.putImageData(imagedata,150,150) + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) + }) + } + .width('100%') + .height('100%') } - .width('100%') - .height('100%') } -} ``` ![en-us_image_000000127777780](figures/en-us_image_000000127777780.png) @@ -2256,6 +2349,8 @@ putImageData(imageData: Object, dx: number, dy: number, dirtyX: number, dirtyY: Puts an **[ImageData](ts-components-canvas-imagedata.md)** object onto a rectangular area on the canvas. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -2311,6 +2406,8 @@ setLineDash(segments: number[]): void Sets the dash line style. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Description | @@ -2320,31 +2417,31 @@ Sets the dash line style. **Example** ```ts -@Entry -@Component -struct SetLineDash { - private settings: RenderingContextSettings = new RenderingContextSettings(true) - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) - - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() =>{ - this.offContext.arc(100, 75, 50, 0, 6.28) - this.offContext.setLineDash([10,20]) - this.offContext.stroke() - var image = this.offContext.transferToImageBitmap() - this.context.transferFromImageBitmap(image) - }) + @Entry + @Component + struct SetLineDash { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.offContext.arc(100, 75, 50, 0, 6.28) + this.offContext.setLineDash([10,20]) + this.offContext.stroke() + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) + }) + } + .width('100%') + .height('100%') } - .width('100%') - .height('100%') } -} ``` ![en-us_image_000000127777772](figures/en-us_image_000000127777772.png) @@ -2355,6 +2452,8 @@ getLineDash(): number[] Obtains the dash line style. +Since API version 9, this API is supported in ArkTS widgets. + **Return value** | Type | Description | @@ -2365,42 +2464,42 @@ Obtains the dash line style. ```ts // xxx.ets -@Entry -@Component -struct OffscreenCanvasGetLineDash { - @State message: string = 'Hello World' - private settings: RenderingContextSettings = new RenderingContextSettings(true) - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) - build() { - Row() { - Column() { - Text(this.message) - .fontSize(50) - .fontWeight(FontWeight.Bold) - .onClick(()=>{ - console.error('before getlinedash clicked') - let res = this.offContext.getLineDash() - console.error(JSON.stringify(res)) - }) - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() => { - this.offContext.arc(100, 75, 50, 0, 6.28) - this.offContext.setLineDash([10,20]) - this.offContext.stroke() - let res = this.offContext.getLineDash() - var image = this.offContext.transferToImageBitmap() - this.context.transferFromImageBitmap(image) - }) + @Entry + @Component + struct OffscreenCanvasGetLineDash { + @State message: string = 'Hello World' + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + build() { + Row() { + Column() { + Text(this.message) + .fontSize(50) + .fontWeight(FontWeight.Bold) + .onClick(()=>{ + console.error('before getlinedash clicked') + let res = this.offContext.getLineDash() + console.error(JSON.stringify(res)) + }) + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() => { + this.offContext.arc(100, 75, 50, 0, 6.28) + this.offContext.setLineDash([10,20]) + this.offContext.stroke() + let res = this.offContext.getLineDash() + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) + }) + } + .width('100%') } - .width('100%') + .height('100%') } - .height('100%') } -} ``` ![en-us_image_000000127777778](figures/en-us_image_000000127777778.png) @@ -2430,28 +2529,28 @@ Since API version 9, this API is supported in ArkTS widgets. **Example** ```ts -// xxx.ets -@Entry -@Component -struct ToDataURL { - private settings: RenderingContextSettings = new RenderingContextSettings(true) - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + // xxx.ets + @Entry + @Component + struct ToDataURL { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() =>{ - var dataURL = this.offContext.toDataURL() - }) + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + var dataURL = this.offContext.toDataURL() + }) + } + .width('100%') + .height('100%') } - .width('100%') - .height('100%') } -} ``` @@ -2461,6 +2560,8 @@ imageSmoothingQuality(quality: imageSmoothingQuality) Sets the quality of image smoothing. This API is a void API. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Description | @@ -2524,37 +2625,39 @@ restore(): void Restores the saved drawing context. +Since API version 9, this API is supported in ArkTS widgets. + **Example** ```ts // xxx.ets -@Entry -@Component -struct CanvasExample { - private settings: RenderingContextSettings = new RenderingContextSettings(true) - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) - - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() =>{ - this.offContext.save() // save the default state - this.offContext.fillStyle = "#00ff00" - this.offContext.fillRect(20, 20, 100, 100) - this.offContext.restore() // restore to the default state - this.offContext.fillRect(150, 75, 100, 100) - var image = this.offContext.transferToImageBitmap() - this.context.transferFromImageBitmap(image) - }) + @Entry + @Component + struct CanvasExample { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.offContext.save() // save the default state + this.offContext.fillStyle = "#00ff00" + this.offContext.fillRect(20, 20, 100, 100) + this.offContext.restore() // restore to the default state + this.offContext.fillRect(150, 75, 100, 100) + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) + }) + } + .width('100%') + .height('100%') } - .width('100%') - .height('100%') } -} ``` ![en-us_image_000000127777781](figures/en-us_image_000000127777781.png) @@ -2565,37 +2668,39 @@ save(): void Saves the current drawing context. +Since API version 9, this API is supported in ArkTS widgets. + **Example** ```ts // xxx.ets -@Entry -@Component -struct CanvasExample { - private settings: RenderingContextSettings = new RenderingContextSettings(true) - private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) - private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) - - build() { - Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { - Canvas(this.context) - .width('100%') - .height('100%') - .backgroundColor('#ffff00') - .onReady(() =>{ - this.offContext.save() // save the default state - this.offContext.fillStyle = "#00ff00" - this.offContext.fillRect(20, 20, 100, 100) - this.offContext.restore() // restore to the default state - this.offContext.fillRect(150, 75, 100, 100) - var image = this.offContext.transferToImageBitmap() - this.context.transferFromImageBitmap(image) - }) + @Entry + @Component + struct CanvasExample { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffff00') + .onReady(() =>{ + this.offContext.save() // save the default state + this.offContext.fillStyle = "#00ff00" + this.offContext.fillRect(20, 20, 100, 100) + this.offContext.restore() // restore to the default state + this.offContext.fillRect(150, 75, 100, 100) + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) + }) + } + .width('100%') + .height('100%') } - .width('100%') - .height('100%') } -} ``` ![en-us_image_000000127777781](figures/en-us_image_000000127777781.png) @@ -2606,6 +2711,8 @@ createLinearGradient(x0: number, y0: number, x1: number, y1: number): void Creates a linear gradient. +Since API version 9, this API is supported in ArkTS widgets. + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -2638,7 +2745,7 @@ Creates a linear gradient. grad.addColorStop(0.5, '#ffffff') grad.addColorStop(1.0, '#00ff00') this.offContext.fillStyle = grad - this.offContext.fillRect(0, 0, 500, 500) + this.offContext.fillRect(0, 0, 400, 400) var image = this.offContext.transferToImageBitmap() this.context.transferFromImageBitmap(image) }) @@ -2658,7 +2765,9 @@ createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, Creates a linear gradient. - **Parameters** +Since API version 9, this API is supported in ArkTS widgets. + + **Parameters** | Name | Type | Mandatory | Default Value | Description | | ---- | ------ | ---- | ---- | ----------------- | @@ -2669,7 +2778,7 @@ Creates a linear gradient. | 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** + **Example** ```ts // xxx.ets @@ -2692,7 +2801,7 @@ Creates a linear gradient. grad.addColorStop(0.5, '#ffffff') grad.addColorStop(1.0, '#00ff00') this.offContext.fillStyle = grad - this.offContext.fillRect(0, 0, 500, 500) + this.offContext.fillRect(0, 0, 440, 440) var image = this.offContext.transferToImageBitmap() this.context.transferFromImageBitmap(image) }) @@ -2705,7 +2814,59 @@ Creates a linear gradient. ![en-us_image_0000001238952407](figures/en-us_image_0000001238952407.png) +### createConicGradient10+ + +createConicGradient(startAngle: number, x: number, y: number): CanvasGradient + +Creates a conic gradient. + +**Parameters** + +| 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 | Y-coordinate of the center of the conic gradient, in vp. | + +**Example** + +```ts +// xxx.ets +@Entry +@Component +struct OffscreenCanvasConicGradientPage { + private settings: RenderingContextSettings = new RenderingContextSettings(true) + private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) + + private offContext: OffscreenCanvasRenderingContext2D = new OffscreenCanvasRenderingContext2D(600, 600, this.settings) + + build() { + Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { + Canvas(this.context) + .width('100%') + .height('100%') + .backgroundColor('#ffffff') + .onReady(() =>{ + var grad = this.offContext.createConicGradient(0, 50, 80) + grad.addColorStop(0.0, '#ff0000') + grad.addColorStop(0.5, '#ffffff') + grad.addColorStop(1.0, '#00ff00') + this.offContext.fillStyle = grad + this.offContext.fillRect(0, 30, 100, 100) + var image = this.offContext.transferToImageBitmap() + this.context.transferFromImageBitmap(image) + }) + } + .width('100%') + .height('100%') + } +} +``` + + ![en-us_image_0000001239032419](figures/en-us_image_0000001239032420.png) ## CanvasPattern Defines an object created using the **[createPattern](#createpattern)** API. + +Since API version 9, this API is supported in ArkTS widgets. diff --git a/en/application-dev/reference/arkui-ts/ts-universal-attributes-size.md b/en/application-dev/reference/arkui-ts/ts-universal-attributes-size.md index ef361829897dcbf29396cb14d654051bea2f41c6..875a75dd8059e56227fd9559368a073487c74c47 100644 --- a/en/application-dev/reference/arkui-ts/ts-universal-attributes-size.md +++ b/en/application-dev/reference/arkui-ts/ts-universal-attributes-size.md @@ -12,12 +12,12 @@ The size attributes set the width, height, and margin of a component. | Name | Type | Description | | -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -| width | [Length](ts-types.md#length) | Width of the component. By default, the width required to fully hold the component content is used. If the width of the component is greater than that of the parent container, the range of the parent container is drawn.
Since API version 9, this API is supported in ArkTS widgets.| -| height | [Length](ts-types.md#length) | Height of the component. By default, the height required to fully hold the component content is used. If the height of the component is greater than that of the parent container, the range of the parent container is drawn.
Since API version 9, this API is supported in ArkTS widgets.| -| size | {
width?: [Length](ts-types.md#length),
height?: [Length](ts-types.md#length)
} | Size of the component.
Since API version 9, this API is supported in ArkTS widgets.| -| padding | [Padding](ts-types.md#padding) \| [Length](ts-types.md#length) | Padding of the component.
When the parameter is of the **Length** type, the four paddings take effect.
Default value: **0**
When **padding** is set to a percentage, the width of the parent container is used as the basic value.
Since API version 9, this API is supported in ArkTS widgets.| -| margin | [Margin](ts-types.md#margin) \| [Length](ts-types.md#length) | Margin of the component.
When the parameter is of the **Length** type, the four margins take effect.
Default value: **0**
When **margin** is set to a percentage, the width of the parent container is used as the basic value.
Since API version 9, this API is supported in ArkTS widgets.| -| constraintSize | {
minWidth?: [Length](ts-types.md#length),
maxWidth?: [Length](ts-types.md#length),
minHeight?: [Length](ts-types.md#length),
maxHeight?: [Length](ts-types.md#length)
} | Constraint size of the component, which is used to limit the size range during component layout. **constraintSize** takes precedence over **width** and **height**. If the value of **minWidth** is greater than that of **maxWidth**, only the value of **minWidth** takes effect. The same rule applies to **minHeight** and **maxHeight**.
Default value:
{
minWidth: 0,
maxWidth: Infinity,
minHeight: 0,
maxHeight: Infinity
}
Since API version 9, this API is supported in ArkTS widgets.| +| width | [Length](ts-types.md#length) | Width of the component. By default, the width required to fully hold the component content is used. If the width of the component is greater than that of the parent container, the range of the parent container is drawn.
Since API version 9, this API is supported in ArkTS widgets.
Since API version 10, this API supports the calc calculation feature.| +| height | [Length](ts-types.md#length) | Height of the component. By default, the height required to fully hold the component content is used. If the height of the component is greater than that of the parent container, the range of the parent container is drawn.
Since API version 9, this API is supported in ArkTS widgets.
Since API version 10, this API supports the calc calculation feature.| +| size | {
width?: [Length](ts-types.md#length),
height?: [Length](ts-types.md#length)
} | Size of the component.
Since API version 9, this API is supported in ArkTS widgets.
Since API version 10, this API supports the calc calculation feature.| +| padding | [Padding](ts-types.md#padding) \| [Length](ts-types.md#length) | Padding of the component.
When the parameter is of the **Length** type, the four paddings take effect.
Default value: **0**
When **padding** is set to a percentage, the width of the parent container is used as the basic value.
Since API version 9, this API is supported in ArkTS widgets.
Since API version 10, this API supports the calc calculation feature.| +| margin | [Margin](ts-types.md#margin) \| [Length](ts-types.md#length) | Margin of the component.
When the parameter is of the **Length** type, the four margins take effect.
Default value: **0**
When **margin** is set to a percentage, the width of the parent container is used as the basic value.
Since API version 9, this API is supported in ArkTS widgets.
Since API version 10, this API supports the calc calculation feature.| +| constraintSize | {
minWidth?: [Length](ts-types.md#length),
maxWidth?: [Length](ts-types.md#length),
minHeight?: [Length](ts-types.md#length),
maxHeight?: [Length](ts-types.md#length)
} | Constraint size of the component, which is used to limit the size range during component layout. **constraintSize** takes precedence over **width** and **height**. If the value of **minWidth** is greater than that of **maxWidth**, only the value of **minWidth** takes effect. The same rule applies to **minHeight** and **maxHeight**.
Default value:
{
minWidth: 0,
maxWidth: Infinity,
minHeight: 0,
maxHeight: Infinity
}
Since API version 9, this API is supported in ArkTS widgets.
Since API version 10, this API supports the calc calculation feature.| | layoutWeight | number \| string | Weight of the component during layout. When the container size is determined, the container space is allocated along the main axis among the component and sibling components based on the layout weight, and the component size setting is ignored.
Default value: **0**
Since API version 9, this API is supported in ArkTS widgets.
**NOTE**
This attribute is valid only for the **\**, **\**, and **\** layouts.
The value can be a number greater than or equal to 0 or a string that can be converted to a number.| diff --git a/en/application-dev/security/permission-list.md b/en/application-dev/security/permission-list.md index fc3d8593e3bfcf75888d985d69c556db2dbe15b4..f598c23376424ab5dbcb99e99691584ce444dc7d 100644 --- a/en/application-dev/security/permission-list.md +++ b/en/application-dev/security/permission-list.md @@ -436,7 +436,7 @@ Allows an application to obtain the sensitive permissions that have been granted ## ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS_EXTENSION -Allows an application to set attributes for the applications of other users. +Allows an application to set the attributes of applications of other users. **Permission level**: system_core @@ -496,7 +496,7 @@ Allows an application to read data from a gyroscope sensor or uncalibrated gyros ## ohos.permission.INSTALL_BUNDLE -Allows an application to install and uninstall other applications. +Allows an application to install and uninstall other applications (except enterprise InHouse applications). **Permission level**: system_core @@ -974,6 +974,26 @@ Allows the device administrator to set bundle installation policies. **Enable via ACL**: TRUE +## ohos.permission.ENTERPRISE_SET_NETWORK + +Allows the device administrator application to set network information. + +**Permission level**: system_basic + +**Authorization mode**: system_grant + +**Enable via ACL**: TRUE + +## ohos.permission.ENTERPRISE_MANAGE_SET_APP_RUNNING_POLICY + +Allows the device administrator application to set application running policies. + +**Permission level**: system_basic + +**Authorization mode**: system_grant + +**Enable via ACL**: TRUE + ## ohos.permission.NFC_TAG Allows an application to read NFC tag information. @@ -1146,7 +1166,7 @@ Allows an application to add, remove, and modify call logs. ## ohos.permission.WRITE_CONTACTS -Allows an application to add, remove, and modify contacts. +Allows an application to add, remove, and modify Contacts. **Permission level**: system_basic @@ -1500,7 +1520,7 @@ Allows an application to manage private credentials and query certificate status ## ohos.permission.ACCESS_PUSH_SERVICE -Allows an application to to access the Ability of the push service. +Allows an application to access the Ability of the push service. **Permission level**: system_basic @@ -1628,6 +1648,26 @@ Allows an application to have backup and restore capabilities. **Enable via ACL**: TRUE +## ohos.permission.CLOUDFILE_SYNC_MANAGER + +Allows an application to obtain the device-cloud synchronization management capability. + +**Permission level**: system_basic + +**Authorization mode**: system_grant + +**Enable via ACL**: TRUE + +## ohos.permission.CLOUDFILE_SYNC + +Allows an application to perform device-cloud synchronization. + +**Permission level**: system_basic + +**Authorization mode**: system_grant + +**Enable via ACL**: TRUE + ## ohos.permission.FILE_ACCESS_MANAGER Allows a file management application to access user data files through the FAF. @@ -1640,7 +1680,7 @@ Allows a file management application to access user data files through the FAF. ## ohos.permission.MANAGE_AUDIO_CONFIG -Allows an application to to mute microphones globally. +Allows an application to mute microphones globally. **Permission level**: system_basic @@ -1757,3 +1797,83 @@ Allows an application to use ultrasonic sensing. **Authorization mode**: system_grant **Enable ACL**: FALSE + +## ohos.permission.INSTALL_ENTERPRISE_BUNDLE + +Allows an application to install and uninstall enterprise InHouse applications. + +**Permission level**: system_core + +**Authorization mode**: system_grant + +**Enable via ACL**: TRUE + +## ohos.permission.PROXY_AUTHORIZATION_URI + +Allows the application proxy to authorize the URI. + +**Permission level**: system_basic + +**Authorization mode**: system_grant + +**Enable ACL**: FALSE + +## ohos.permission.GET_INSTALLED_BUNDLE_LIST + +Allows an application to obtain the list of installed applications. + +**Permission level**: system_basic + +**Authorization mode**: user_grant + +**Enable via ACL**: TRUE + +## ohos.permission.MANAGE_DISTRIBUTED_ACCOUNTS + +Allows an application to manage distributed account information. + +**Permission level**: system_basic + +**Authorization mode**: system_grant + +**Enable via ACL**: TRUE + +## ohos.permission.GET_DISTRIBUTED_ACCOUNTS + +Allows an application to obtain distributed account information. + +**Permission level**: system_basic + +**Authorization mode**: system_grant + +**Enable via ACL**: TRUE + +## ohos.permission.GET_LOCAL_ACCOUNTS + +Allows an application to obtain local account information. + +**Permission level**: system_basic + +**Authorization mode**: system_grant + +**Enable via ACL**: TRUE + +## ohos.permission.READ_HIVIEW_SYSTEM + +Allows an application to access HiView data. + +**Permission level**: system_basic + +**Authorization mode**: system_grant + +**Enable via ACL**: TRUE + +## ohos.permission.WRITE_HIVIEW_SYSTEM + +Allows an application to modify HiView data. + +**Permission level**: system_basic + +**Authorization mode**: system_grant + +**Enable via ACL**: TRUE diff --git a/en/application-dev/ui/arkts-performance-improvement-recommendation.md b/en/application-dev/ui/arkts-performance-improvement-recommendation.md new file mode 100644 index 0000000000000000000000000000000000000000..8d144767653ac90a89d9e72a83a292228c024a11 --- /dev/null +++ b/en/application-dev/ui/arkts-performance-improvement-recommendation.md @@ -0,0 +1,318 @@ +# Recommendations for Improving Performance + +Poor-performing code may work, but will take away from your application performance. This topic presents a line-up of recommendations that you can take to improve your implementation, thereby avoiding possible performance drop. + +## Lazy Loading + +When developing a long list, use of loop rendering, as in the code snippet below, can greatly slow down page loading and increase server load. + +```ts +@Entry +@Component +struct MyComponent { + @State arr: number[] = Array.from(Array(100), (v,k) =>k); // Construct an array of 0 to 99. + build() { + List() { + ForEach(this.arr, (item: number) => { + ListItem() { + Text(`item value: ${item}`) + } + }, (item: number) => item.toString()) + } + } +} +``` + +The preceding code snippet loads all of the 100 list elements at a time during page loading. This is generally not desirable. Instead, what we need is to load data from the data source and create corresponding components on demand. This can be achieved through lazy loading. The sample code is as follows: + +```ts +class BasicDataSource implements IDataSource { + private listeners: DataChangeListener[] = [] + + public totalCount(): number { + return 0 + } + + public getData(index: number): any { + return undefined + } + + registerDataChangeListener(listener: DataChangeListener): void { + if (this.listeners.indexOf(listener) < 0) { + console.info('add listener') + this.listeners.push(listener) + } + } + + unregisterDataChangeListener(listener: DataChangeListener): void { + const pos = this.listeners.indexOf(listener); + if (pos >= 0) { + console.info('remove listener') + this.listeners.splice(pos, 1) + } + } + + notifyDataReload(): void { + this.listeners.forEach(listener => { + listener.onDataReloaded() + }) + } + + notifyDataAdd(index: number): void { + this.listeners.forEach(listener => { + listener.onDataAdd(index) + }) + } + + notifyDataChange(index: number): void { + this.listeners.forEach(listener => { + listener.onDataChange(index) + }) + } + + notifyDataDelete(index: number): void { + this.listeners.forEach(listener => { + listener.onDataDelete(index) + }) + } + + notifyDataMove(from: number, to: number): void { + this.listeners.forEach(listener => { + listener.onDataMove(from, to) + }) + } +} + +class MyDataSource extends BasicDataSource { + private dataArray: string[] = ['item value: 0', 'item value: 1', 'item value: 2'] + + public totalCount(): number { + return this.dataArray.length + } + + public getData(index: number): any { + return this.dataArray[index] + } + + public addData(index: number, data: string): void { + this.dataArray.splice(index, 0, data) + this.notifyDataAdd(index) + } + + public pushData(data: string): void { + this.dataArray.push(data) + this.notifyDataAdd(this.dataArray.length - 1) + } +} + +@Entry +@Component +struct MyComponent { + private data: MyDataSource = new MyDataSource() + + build() { + List() { + LazyForEach(this.data, (item: string) => { + ListItem() { + Row() { + Text(item).fontSize(20).margin({ left: 10 }) + } + } + .onClick(() => { + this.data.pushData('item value: ' + this.data.totalCount()) + }) + }, item => item) + } + } +} +``` + +![LazyForEach1](figures/LazyForEach1.gif) + +The preceding code initializes only three list elements during page loading and loads a new list item each time a list element is clicked. + +## Prioritizing Conditional Rendering over Visibility Control + +Use of the visibility attribute to hide or show a component, as in the code snippet below, results in re-creation of the component, leading to performance drop. + +```ts +@Entry +@Component +struct MyComponent { + @State isVisible: Visibility = Visibility.Visible; + + build() { + Column() { + Button ("Show/Hide") + .onClick(() => { + if (this.isVisible == Visibility.Visible) { + this.isVisible = Visibility.None + } else { + this.isVisible = Visibility.Visible + } + }) + Row().visibility(this.isVisible) + .width(300).height(300).backgroundColor(Color.Pink) + }.width('100%') + } +} +``` + +To avoid the preceding issue, use the **if** statement instead. The sample code is as follows: + +```ts +@Entry +@Component +struct MyComponent { + @State isVisible: boolean = true; + + build() { + Column() { + Button ("Show/Hide") + .onClick(() => { + this.isVisible = !this.isVisible + }) + if (this.isVisible) { + Row() + .width(300).height(300).backgroundColor(Color.Pink) + } + }.width('100%') + } +} +``` + +![isVisible](figures/isVisible.gif) + +## Prioritizing Flex over Column/Row + +By default, the flex container needs to re-lay out flex items to comply with the **flexShrink** and **flexGrow** settings. This may result in drop in rendering performance. + +```ts +@Entry +@Component +struct MyComponent { + build() { + Flex({ direction: FlexDirection.Column }) { + Flex().width(300).height(200).backgroundColor(Color.Pink) + Flex().width(300).height(200).backgroundColor(Color.Yellow) + Flex().width(300).height(200).backgroundColor(Color.Grey) + } + } +} +``` + +To avoid the preceding issue, replace **Flex** with **Column** and **Row**, which can create the same page layout as **Flex** does. + +```ts +@Entry +@Component +struct MyComponent { + build() { + Column() { + Row().width(300).height(200).backgroundColor(Color.Pink) + Row().width(300).height(200).backgroundColor(Color.Yellow) + Row().width(300).height(200).backgroundColor(Color.Grey) + } + } +} +``` + +![flex1](figures/flex1.PNG) + +## Setting Width and Height for \ Components + +When a **\** component is nested within a **\** component, all of its content will be loaded if its width and height is not specified, which may result in performance drop. + +```ts +@Entry +@Component +struct MyComponent { + private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; + + build() { + Scroll() { + List() { + ForEach(this.arr, (item) => { + ListItem() { + Text(`item value: ${item}`).fontSize(30).margin({ left: 10 }) + }.height(100) + }, (item) => item.toString()) + } + }.backgroundColor(Color.Pink) + } +} +``` + +Therefore, in the above scenario, you are advised to set the width and height for the **\** component as follows: + +```ts +@Entry +@Component +struct MyComponent { + private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; + + build() { + Scroll() { + List() { + ForEach(this.arr, (item) => { + ListItem() { + Text(`item value: ${item}`).fontSize(30).margin({ left: 10 }) + }.height(100) + }, (item) => item.toString()) + }.width('100%').height(500) + }.backgroundColor(Color.Pink) + } +} +``` + +![list1](figures/list1.gif) + +## Minimizing White Blocks During Swiping + +To minimize white blocks during swiping, expand the UI loading range by increasing the value of **cachedCount** for the **\** and **\** components. **cachedCount** indicates the number of list or grid items preloaded outside of the screen. +If an item needs to request an online image, set **cachedCount** as appropriate so that the image is downloaded in advance before the item comes into view on the screen, thereby reducing the number of white blocks. +The following is an example of using **cachedCount**: + +```ts +@Entry +@Component +struct MyComponent { + private source: MyDataSource = new MyDataSource(); + + build() { + List() { + LazyForEach(this.source, item => { + ListItem() { + Text("Hello" + item) + .fontSize(50) + .onAppear(() => { + console.log("appear:" + item) + }) + } + }) + }.cachedCount(3) // Increase the number of list or grid items preloaded outside of the screen. + } +} + +class MyDataSource implements IDataSource { + data: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]; + + public totalCount(): number { + return this.data.length + } + + public getData(index: number): any { + return this.data[index] + } + + registerDataChangeListener(listener: DataChangeListener): void { + } + + unregisterDataChangeListener(listener: DataChangeListener): void { + } +} +``` +![list2](figures/list2.gif) + +**Instructions** +A greater **cachedCount** value may result in higher CPU and memory overhead of the UI. Adjust the value by taking into account both the comprehensive performance and user experience. diff --git a/en/application-dev/ui/ui-js-building-ui-component.md b/en/application-dev/ui/ui-js-building-ui-component.md index 752b8c4e4d527c9ffa0357fa9474aa1430bca6d9..71099ca5fe3206d7531d328c364e4163436fd50b 100644 --- a/en/application-dev/ui/ui-js-building-ui-component.md +++ b/en/application-dev/ui/ui-js-building-ui-component.md @@ -11,26 +11,11 @@ You can also customize a new component through proper combination of components Components can be classified into the following types based on their functions. -| Type | Components | -| -------- | -------- | +| Type | Components | +| --------- | ---------------------------------------- | | Container | badge, dialog, div, form, list, list-item, list-item-group, panel, popup, refresh, stack, stepper, stepper-item, swiper, tabs, tab-bar, tab-content | -| Basic | button, chart, divider, image, image-animator, input, label, marquee, menu, option, picker, picker-view, piece, progress, qrcode, rating, richtext, search, select, slider, span, switch, text, textarea, toolbar, toolbar-item, toggle | -| Media | video | -| Canvas | canvas | -| Grid | grid-container, grid-row, grid-col | -| SVG | svg, rect, circle, ellipse, path, line, polyline, polygon, text, tspan, textPath, animate, animateMotion, animateTransform | -## Samples - -The following samples are provided to help you better understand how to develop components: - -- [`JsPanel`: Content Display Panel (JavaScript, API 8)](https://gitee.com/openharmony/app_samples/tree/master/UI/JsPanel) -- [`Popup`: JavaScript Bubble (API 8)](https://gitee.com/openharmony/app_samples/tree/master/UI/Popup) -- [`RefreshContainer`: Refresh Container (JavaScript, API 8)](https://gitee.com/openharmony/app_samples/tree/master/UI/RefreshContainer) -- [`JSComponments`: JavaScript Bubble (API 8)](https://gitee.com/openharmony/app_samples/tree/master/UI/JSComponments) -- [`JsUserRegistration`: User Registration (JavaScript, API 8)](https://gitee.com/openharmony/app_samples/tree/master/UI/JsUserRegistration) -- [`ECG`: Heart Rate Detection (JavaScript, API 7)](https://gitee.com/openharmony/app_samples/tree/master/common/ECG) - -- [`Badge`: Badge (JavaScript, API 8)](https://gitee.com/openharmony/app_samples/tree/master/UI/Badge) -- [`JsVideo`: JsVideo (API 8)](https://gitee.com/openharmony/app_samples/tree/master/media/JsVideo) -- [Rating (JavaScript)](https://gitee.com/openharmony/codelabs/tree/master/JSUI/RatingApplication) -- [Simple Video Player](https://gitee.com/openharmony/codelabs/tree/master/Media/VideoOpenHarmony) +| Basic | button, chart, divider, image, image-animator, input, label, marquee, menu, option, picker, picker-view, piece, progress, qrcode, rating, richtext, search, select, slider, span, switch, text, textarea, toolbar, toolbar-item, toggle | +| Media | video | +| Canvas | canvas | +| Grid | grid-container, grid-row, grid-col | +| SVG | svg, rect, circle, ellipse, path, line, polyline, polygon, text, tspan, textPath, animate, animateMotion, animateTransform | \ No newline at end of file diff --git a/en/application-dev/web/Readme-EN.md b/en/application-dev/web/Readme-EN.md new file mode 100644 index 0000000000000000000000000000000000000000..e003a42ecdbe48166e7603ea1e879739010e8228 --- /dev/null +++ b/en/application-dev/web/Readme-EN.md @@ -0,0 +1,17 @@ +# Web + +- [Web Component Overview](web-component-overview.md) +- [Loading Pages by Using the Web Component](web-page-loading-with-web-components.md) +- Setting Basic Attributes and Events + - [Setting the Dark Mode](web-set-dark-mode.md) + - [Uploading Files](web-file-upload.md) + - [Opening Pages in a New Window](web-open-in-new-window.md) + - [Managing Location Permissions](web-geolocation-permission.md) +- Using Frontend Page JavaScript Code on the Application + - [Invoking Frontend Page Functions on the Application](web-in-app-frontend-page-function-invoking.md) + - [Invoking Application Functions on the Frontend Page](web-in-page-app-function-invoking.md) + - [Establishing a Data Channel Between the Application and Frontend Page](web-app-page-data-channel.md) +- [Managing Page Redirection and Browsing History Navigation](web-redirection-and-browsing-history-mgmt.md) +- [Managing Cookies and Data Storage](web-cookie-and-data-storage-mgmt.md) +- [Customizing Page Request Responses](web-resource-interception-request-mgmt.md) +- [Debugging Frontend Pages by Using DevTools](web-debugging-with-devtools.md) diff --git a/en/application-dev/web/figures/debug-effect.png b/en/application-dev/web/figures/debug-effect.png new file mode 100644 index 0000000000000000000000000000000000000000..32c46cadbb99a6623532f50d14fa0750854c9a5d Binary files /dev/null and b/en/application-dev/web/figures/debug-effect.png differ diff --git a/en/application-dev/web/figures/resource-path.png b/en/application-dev/web/figures/resource-path.png new file mode 100644 index 0000000000000000000000000000000000000000..602c750894581e13296cb7cb77e9714f143983f9 Binary files /dev/null and b/en/application-dev/web/figures/resource-path.png differ diff --git a/en/application-dev/web/web-app-page-data-channel.md b/en/application-dev/web/web-app-page-data-channel.md new file mode 100644 index 0000000000000000000000000000000000000000..f26c635fdf294c9237342381355538da950ad281 --- /dev/null +++ b/en/application-dev/web/web-app-page-data-channel.md @@ -0,0 +1,143 @@ +# Establishing a Data Channel Between the Application and the Frontend Page + + +The [createWebMessagePorts()](../reference/apis/js-apis-webview.md#createwebmessageports) API allows you to create message ports to implement communication between the application and frontend page. + + +In the following example, **createWebMessagePorts** is used to create message ports on the application and [postMessage()](../reference/apis/js-apis-webview.md#postmessage) is used to forward one of the message ports to the frontend page so that the application and frontend page can exchange messages with each other over the port. + + +- Application code: + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview'; + + @Entry + @Component + struct WebComponent { + controller: web_webview.WebviewController = new web_webview.WebviewController(); + ports: web_webview.WebMessagePort[]; + @State sendFromEts: string = 'Send this message from ets to HTML'; + @State receivedFromHtml: string = 'Display received message send from HTML'; + + build() { + Column() { + // Display the content received from the HTML side. + Text(this.receivedFromHtml) + // Send the content in the text box to the HTML side. + TextInput({placeholder: 'Send this message from ets to HTML'}) + .onChange((value: string) => { + this.sendFromEts = value; + }) + + Button('postMessage') + .onClick(() => { + try { + // 1. Create two message ports. + this.ports = this.controller.createWebMessagePorts(); + // 2. Register a callback for the message port (for example, port 1) on the application. + this.ports[1].onMessageEvent((result: web_webview.WebMessage) => { + let msg = 'Got msg from HTML:'; + if (typeof(result) === 'string') { + console.info(`received string message from html5, string is: ${result}`); + msg = msg + result; + } else if (typeof(result) === 'object') { + if (result instanceof ArrayBuffer) { + console.info(`received arraybuffer from html5, length is: ${result.byteLength}`); + msg = msg + 'lenght is ' + result.byteLength; + } else { + console.info('not support'); + } + } else { + console.info('not support'); + } + this.receivedFromHtml = msg; + }) + // 3. Send the other message port (for example, port 0) to the HTML side, which then saves the message port. + this.controller.postMessage('__init_port__', [this.ports[0]], '*'); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + + // 4. Use the message port on the application to send messages to the message port that has been sent to the HTML side. + Button('SendDataToHTML') + .onClick(() => { + try { + if (this.ports && this.ports[1]) { + this.ports[1].postMessageEvent(this.sendFromEts); + } else { + console.error(`ports is null, Please initialize first`); + } + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + Web({ src: $rawfile('xxx.html'), controller: this.controller }) + } + } + } + ``` + +- Frontend page code: + + ```html + + + + + + WebView Message Port Demo + + + + + +

WebView Message Port Demo

+
+
+
+
+

display received message send from ets

+ + + ``` diff --git a/en/application-dev/web/web-component-overview.md b/en/application-dev/web/web-component-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..187661ee6c6f9f98411d89c67052615e04d14bca --- /dev/null +++ b/en/application-dev/web/web-component-overview.md @@ -0,0 +1,14 @@ +# Web Component Overview + + +In addition to displaying web page content on applications, the **Web** component provides you with some other helpful functions, including: + + +- **Page loading**: provides a full set of basic frontend page loading capabilities, which allow you to load network pages, local pages, and HTML text data. + +- **Page interaction**: supports a wide range of page interaction modes, which allow you to set the dark mode for frontend pages, load pages in a new window, manage location permissions and cookies, and use frontend page JavaScript code on the application. + +- **Page debugging**: uses DevTools to debug frontend pages. + + +To help you better understand the features of the **Web** component, the following sections will exemplify use of the **Web** component in common application scenarios. diff --git a/en/application-dev/web/web-cookie-and-data-storage-mgmt.md b/en/application-dev/web/web-cookie-and-data-storage-mgmt.md new file mode 100644 index 0000000000000000000000000000000000000000..e5d402724d420bae4157fe18f56e9de6e00adac6 --- /dev/null +++ b/en/application-dev/web/web-cookie-and-data-storage-mgmt.md @@ -0,0 +1,131 @@ +# Managing Cookies and Data Storage + + +## Cookie Management + +A cookie is a segment of data sent from the server to the client to uniquely identify a user during network access. The client may hold the data and provide it to the server at later interactions so that the server can quickly identify the client identity and status. + +The **Web** component provides the **WebCookieManager** class for you to manage cookie information, which is stored in the **/proc/{pid}/root/data/storage/el2/base/cache/web/Cookiesd** file in the application sandbox path. + +The following uses [setCookie()](../reference/apis/js-apis-webview.md#setcookie) as an example to describe how to set a cookie's value to **test** for **www.example.com**. For details about functions and usage of other APIs, see [WebCookieManager()](../reference/apis/js-apis-webview.md#webcookiemanager). + + +```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('setCookie') + .onClick(() => { + try { + web_webview.WebCookieManager.setCookie('https://www.example.com', 'value=test'); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + Web({ src: 'www.example.com', controller: this.controller }) + } + } +} +``` + + +## Cache and Storage Management + +Network resource requests are relatively time-consuming during website access. You can use store resources locally by means of cache and Dom Storage to fasten the access to the same website. + + +### Cache + +Use [cacheMode()](../reference/arkui-ts/ts-basic-components-web.md#cachemode) to configure the cache mode for page resources. Four cache modes are supported: + +- **Default**: Page resources in a cache that has not expired are preferentially used. If the cache does not exist, page resources are obtained from the network. + +- **None**: Page resources are loaded from the cache. If the cache does not exist, page resources are obtained from the network. + +- **Online**: Page resources are not loaded from the cache. All resources are obtained from the network. + +- **Only**: Page resources are only loaded from the cache. + + +In the following example, the cache mode is set to **None**. + + + +```ts +// xxx.ets +import web_webview from '@ohos.web.webview'; + +@Entry +@Component +struct WebComponent { + @State mode: CacheMode = CacheMode.None; + controller: web_webview.WebviewController = new web_webview.WebviewController(); + build() { + Column() { + Web({ src: 'www.example.com', controller: this.controller }) + .cacheMode(this.mode) + } + } +} +``` + + + To obtain up-to-date resources, you can use [removeCache()](../reference/apis/js-apis-webview.md#removecache) to clear cached resources. The sample code is as follows: + +```ts +// xxx.ets +import web_webview from '@ohos.web.webview'; + +@Entry +@Component +struct WebComponent { + @State mode: CacheMode = CacheMode.None; + controller: web_webview.WebviewController = new web_webview.WebviewController(); + build() { + Column() { + Button('removeCache') + .onClick(() => { + try { + // If this parameter is set to true, the cache in both the ROM and RAM is cleared. If this parameter is set to false, only the cache in the RAM is cleared. + this.controller.removeCache(true); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + Web({ src: 'www.example.com', controller: this.controller }) + .cacheMode(this.mode) + } + } +} +``` + + +### Dom Storage + +Dom Storage falls into Session Storage and Local Storage. Wherein, Session Storage applies to the temporary data, and its data storage and release follow the session lifecycle; Local Storage applies to the persistent data, which is flushed to the application directory. In both storage modes, data is stored in a form of key-value pair, and is usually used when a page that needs to be stored on the client is accessed. You can use [domStorageAccess()](../reference/arkui-ts/ts-basic-components-web.md#domstorageaccess) to enable Dom Storage. The following is the sample code: + + + +```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 }) + .domStorageAccess(true) + } + } +} +``` diff --git a/en/application-dev/web/web-debugging-with-devtools.md b/en/application-dev/web/web-debugging-with-devtools.md new file mode 100644 index 0000000000000000000000000000000000000000..3a38a48ab12cfd740bba0d5b99cf8140d4224e4b --- /dev/null +++ b/en/application-dev/web/web-debugging-with-devtools.md @@ -0,0 +1,45 @@ +# Debugging Frontend Pages by Using DevTools + + +The **Web** component supports debugging of web frontend pages by using DevTools, a web frontend development and debugging tool that allows you to debug an application's frontend pages on a PC. Before you do this, use [setWebDebuggingAccess()](../reference/apis/js-apis-webview.md#setwebdebuggingaccess) to enable frontend page debugging for the **Web** component. + + +To use DevTools for frontend page debugging, perform the following steps: + + +1. Enable web frontend page debugging in the application code. + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview'; + + @Entry + @Component + struct WebComponent { + controller: web_webview.WebviewController = new web_webview.WebviewController(); + aboutToAppear() { + // Enable web frontend page debugging. + web_webview.WebviewController.setWebDebuggingAccess(true); + } + build() { + Column() { + Web({ src: 'www.example.com', controller: this.controller }) + } + } + } + ``` + +2. Connect your device to a PC, and configure port mapping on the PC as follows: + + ``` + // Configure port mapping. + hdc fport tcp:9222 tcp:9222 + // View port mapping. + hdc fport ls + ``` + +3. Enter **chrome://inspect/\#devices** in the address box of the Chrome browser on the PC. Once the device is identified, you can get started with page debugging. The debugging effect is as follows: + + **Figure 1** Page debugging effect + + ![debug-effect](figures/debug-effect.png) diff --git a/en/application-dev/web/web-file-upload.md b/en/application-dev/web/web-file-upload.md new file mode 100644 index 0000000000000000000000000000000000000000..e06f0345b2dfdbd5fd59548ed31c19bacd89f5f0 --- /dev/null +++ b/en/application-dev/web/web-file-upload.md @@ -0,0 +1,52 @@ +# Uploading Files + + +The **Web** component supports file uploading on a frontend page. You can use [onShowFileSelector()](../reference/arkui-ts/ts-basic-components-web.md#onshowfileselector9) to process file upload requests sent from a frontend page. + + +In the following example, when a user clicks the **Upload** button on the frontend page, the application receives a file upload request through [onShowFileSelector()](../reference/arkui-ts/ts-basic-components-web.md#onshowfileselector9), which carries the path of the local file to be uploaded. + + +- Application code: + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview'; + @Entry + @Component + struct WebComponent { + controller: WebController = new WebController() + build() { + Column() { + // Load the local.html page. + Web({ src: $rawfile('local.html'), controller: this.controller }) + .onShowFileSelector((event) => { + // Set the path of the local file to be uploaded. + let fileList: Array = [ + 'xxx/test.png', + ] + event.result.handleFileList(fileList) + return true; + }) + } + } + } + ``` + + +- Code of the **local.html** page: + + ```html + + + + + Document + + + + +
+ + + ``` diff --git a/en/application-dev/web/web-geolocation-permission.md b/en/application-dev/web/web-geolocation-permission.md new file mode 100644 index 0000000000000000000000000000000000000000..0f157cccaab4e33bab16fe22ecde03fb725b2f76 --- /dev/null +++ b/en/application-dev/web/web-geolocation-permission.md @@ -0,0 +1,73 @@ +# Managing Location Permissions + + +The **Web** component provides the location permission management capability. You can use [onGeolocationShow()](../reference/arkui-ts/ts-basic-components-web.md#ongeolocationshow) to manage the location permission specific to a website. Based on the API response, the **Web** component determines whether to grant the location permission to the frontend page. To obtain the device location, you need to declare the [ohos.permission.LOCATION](../security/accesstoken-guidelines.md) permission. + + +In the following example, when a user clicks the **Get Location** button on the frontend page, the **Web** component notifies the application of the location permission request in a pop-up window. + + +- Frontend page code: + + ```html + + + +

Location information

+ + + + + ``` + + +- Application code: + + ```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('getLocation.html'), controller:this.controller }) + .geolocationAccess(true) + .onGeolocationShow((event) => { // Notification of the location permission request + AlertDialog.show({ + title: 'Location Permission', + message:'Grant access to the device location?', + primaryButton: { + value: 'cancel', + action: () => { + event.geolocation.invoke(event.origin, false, false); // Deny access to the device location. + } + }, + secondaryButton: { + value: 'ok', + action: () => { + event.geolocation.invoke(event.origin, true, false); // Allow access to the device location. + } + }, + cancel: () => { + event.geolocation.invoke(event.origin, false, false); // Deny access to the device location. + } + }) + }) + } + } + } + ``` diff --git a/en/application-dev/web/web-in-app-frontend-page-function-invoking.md b/en/application-dev/web/web-in-app-frontend-page-function-invoking.md new file mode 100644 index 0000000000000000000000000000000000000000..66e9ef25c171a346586d3294c3a9f3919a0726ab --- /dev/null +++ b/en/application-dev/web/web-in-app-frontend-page-function-invoking.md @@ -0,0 +1,48 @@ +# Invoking Frontend Page Functions on the Application + + +You can call [runJavaScript()](../reference/apis/js-apis-webview.md#runjavascript) on an application to call JavaScript functions of frontend pages. + + +In the following example, when a user clicks the **runJavaScript** button on the application, the **htmlTest()** API of the frontend page will be triggered. + + +- Frontend page code: + + ```html + + + + + + + + ``` + + +- Application code: + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview'; + + @Entry + @Component + struct WebComponent { + webviewController: web_webview.WebviewController = new web_webview.WebviewController(); + + build() { + Column() { + Web({ src: $rawfile('index.html'), controller: this.webviewController}) + Button('runJavaScript') + .onClick(() => { + this.webviewController.runJavaScript('htmlTest()'); + }) + } + } + } + ``` 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 new file mode 100644 index 0000000000000000000000000000000000000000..6ef1ed5fa8f5e5fad67e96d20189209ca51016e1 --- /dev/null +++ b/en/application-dev/web/web-in-page-app-function-invoking.md @@ -0,0 +1,113 @@ +# Invoking Application Functions on the Frontend Page + + +You can use the **Web** component to register application code with frontend pages. After the registration is done, frontend pages can use the registered object names to call application functions. + + +Two methods are available for registering the application code:
Call [javaScriptProxy()](../reference/arkui-ts/ts-basic-components-web.md#javascriptproxy) during **Web** component initialization.
Call [registerJavaScriptProxy()](../reference/apis/js-apis-webview.md#registerjavascriptproxy) after **Web** component initialization. + + +The following example registers the **test()** function with the frontend page. This way, the **test()** function can be triggered and run on the frontend page. + + +- Sample code for using [javaScriptProxy()](../reference/arkui-ts/ts-basic-components-web.md#javascriptproxy): + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview'; + + @Entry + @Component + struct WebComponent { + webviewController: web_webview.WebviewController = new web_webview.WebviewController(); + // Declare the object to be registered. + testObj = { + test: () => { + return 'ArkTS Hello World!'; + } + } + + build() { + Column() { + // Load the local index.html page. + Web({ src: $rawfile('index.html'), controller: this.webviewController}) + // Inject the object to the web client. + .javaScriptProxy({ + object: this.testObj, + name: "testObjName", + methodList: ["test"], + controller: this.webviewController + }) + } + } + } + ``` + + +- Sample code for using [registerJavaScriptProxy()](../reference/apis/js-apis-webview.md#registerjavascriptproxy): + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview'; + + @Entry + @Component + struct Index { + webviewController: web_webview.WebviewController = new web_webview.WebviewController(); + testObj = { + test: (data) => { + return "ArkUI Web Component"; + }, + toString: () => { + console.info('Web Component toString'); + } + } + + build() { + Column() { + Button('refresh') + .onClick(() => { + try { + this.webviewController.refresh(); + } catch (error) { + console.error(`Errorcode: ${error.code}, Message: ${error.message}`); + } + }) + Button('Register JavaScript To Window') + .onClick(() => { + try { + this.webviewController.registerJavaScriptProxy(this.testObj, "objName", ["test", "toString"]); + } catch (error) { + console.error(`Errorcode: ${error.code}, Message: ${error.message}`); + } + }) + Web({ src: $rawfile('index.html'), controller: this.webviewController }) + } + } + } + ``` + + > **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. + + +- Sample code for invoking application functions on the **index.htm** frontend page: + + ```html + + + + + +

+ + + + ``` diff --git a/en/application-dev/web/web-open-in-new-window.md b/en/application-dev/web/web-open-in-new-window.md new file mode 100644 index 0000000000000000000000000000000000000000..b1162d7788b365c261fee072282d70ce14d6fe3b --- /dev/null +++ b/en/application-dev/web/web-open-in-new-window.md @@ -0,0 +1,69 @@ +# Opening Pages in a New Window + + +The **Web** component provides the capability of opening pages in a new window. You can call [multiWindowAccess()](../reference/arkui-ts/ts-basic-components-web.md#multiwindowaccess9) to specify whether to allow a web page to be opened in a new window. When a new window is opened in the **Web** component, the application will receive a window opening event through [onWindowNew()](../reference/arkui-ts/ts-basic-components-web.md#onwindownew9). You need to add the code for processing the window opening request in the event callback. + + +> **NOTE** +> +> - If [allowWindowOpenMethod()](../reference/arkui-ts/ts-basic-components-web.md#allowwindowopenmethod10) is set to **true**, you can open a new window in the frontend page by invoking its JavaScript functions. +> +> - If you do not want to open a new window in [onWindowNew()](../reference/arkui-ts/ts-basic-components-web.md#onwindownew9), set the return value of [ControllerHandler.setWebController()](../reference/arkui-ts/ts-basic-components-web.md#setwebcontroller9) to **null**. + + +In the following example, when a user clicks the **Open Page in New Window** button, the application receives a window opening event in the [onWindowNew()](../reference/arkui-ts/ts-basic-components-web.md#onwindownew9) callback. + + +- Application code: + + For details about how to create a window, see [Web Development Examples] (https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Web/Browser). + + ```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("window.html"), controller: this.controller }) + .multiWindowAccess(true) + .onWindowNew((event) => { + console.info("onWindowNew..."); + var popController: web_webview.WebviewController = new web_webview.WebviewController(); + // Create a window, associate it with popController, and have popController returned to the Web component. If you do not need to open a new window, set the return value to event.handler.setWebController(null). + event.handler.setWebController(popController); + }) + } + } + } + ``` + + +- Code of the **window.html** page: + + ```html + + + + + WindowEvent + + + + + + + + ``` diff --git a/en/application-dev/web/web-page-loading-with-web-components.md b/en/application-dev/web/web-page-loading-with-web-components.md new file mode 100644 index 0000000000000000000000000000000000000000..ce80eff340649a3ba02dc20e5f0e990ae9bd4e71 --- /dev/null +++ b/en/application-dev/web/web-page-loading-with-web-components.md @@ -0,0 +1,140 @@ +# Loading Pages by Using the Web Component + + +Page loading is a basic function of the **Web** component. Depending on the data source, page loading falls into three types: loading of network pages, loading of local pages, and loading of HTML rich text data. + + +If acquisition of network resources is involved in page loading, you need to declare the [ohos.permission.INTERNET](../security/accesstoken-guidelines.md) permission. + + +## Loading Network Pages + +You can specify the default network page to be loaded when creating a **Web** component. After the default network page is loaded, call [loadUrl()](../reference/apis/js-apis-webview.md#loadurl) if you want to change the network page displayed by the **Web** component. + + +In the following example, after the **www.example.com** page is loaded by the **Web** component, **loadUrl** is called to change the displayed page to **www.example1.com**. + + + +```ts +// xxx.ets +import web_webview from '@ohos.web.webview'; + +@Entry +@Component +struct WebComponent { + webviewController: web_webview.WebviewController = new web_webview.WebviewController(); + + build() { + Column() { + Button('loadUrl') + .onClick(() => { + try { + // Upon button clicking, call loadUrl to redirect to www.example1.com. + this.webviewController.loadUrl('www.example1.com'); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + // When creating a Web component, set the default network page to be loaded to www.example.com. + Web({ src: 'www.example.com', controller: this.webviewController}) + } + } +} +``` + + +## Loading Local Pages + +Local page files are stored in the application's **rawfile** directory. You can specify the local page to be loaded by default when creating a **Web** component. After page loading is complete, you can call [loadUrl()](../reference/apis/js-apis-webview.md#loadurl) to change the displayed page of the **Web** component. + + +The following example shows how to load a local page file. + + +- Local page file in the application's resources/rawfile directory: + + **Figure 1** Path of local page files + + ![resource-path](figures/resource-path.png) + + +- Application code: + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview'; + + @Entry + @Component + struct WebComponent { + webviewController: web_webview.WebviewController = new web_webview.WebviewController(); + + build() { + Column() { + Button('loadUrl') + .onClick(() => { + try { + // Upon button clicking, call loadUrl to redirect to local1.html. + this.webviewController.loadUrl($rawfile("local1.html")); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + // When creating a Web component, load the local.html file through $rawfile. + Web({ src: $rawfile("local.html"), controller: this.webviewController }) + } + } + } + ``` + + +- Code of the **local.html** page: + + ```html + + + + +

Hello World

+ + + ``` + + +## Loading HTML Rich Text Data + +The **Web** component provides the [loadData()](../reference/apis/js-apis-webview.md#loaddata) API for you to load HTML rich text data. This API is applicable if you want to display some page sections instead of the entire 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() { + Button('loadData') + .onClick(() => { + try { + // Upon button clicking, call loadData to load HTML rich text data. + this.controller.loadData( + 'Source:
source
', + 'text/html', + 'UTF-8' + ); + } catch (error) { + console.error(`ErrorCode: ${error.code}, Message: ${error.message}`); + } + }) + // When creating a Web component, set the default network page to be loaded to www.example.com. + Web({ src: 'www.example.com', controller: this.controller }) + } + } +} +``` diff --git a/en/application-dev/web/web-redirection-and-browsing-history-mgmt.md b/en/application-dev/web/web-redirection-and-browsing-history-mgmt.md new file mode 100644 index 0000000000000000000000000000000000000000..6edb18eed157d0525bb19c815fae26f51a66d6fa --- /dev/null +++ b/en/application-dev/web/web-redirection-and-browsing-history-mgmt.md @@ -0,0 +1,157 @@ +# Managing Page Redirection and Browsing History Navigation + + +## History Navigation + +When a user clicks a web page link on the frontend page, the **Web** component automatically opens and loads the target website by default. When the current page is assigned a new loading link, the address of the accessed web page is automatically recorded. You can call [forward()](../reference/apis/js-apis-webview.md#forward) or [backward()](../reference/apis/js-apis-webview.md#backward) to browse the previous or next history record. + + In the following example, when a user clicks the button, **backward()** is called to go back to the previous page. + +```ts +// xxx.ets +import web_webview from '@ohos.web.webview'; + +@Entry +@Component +struct WebComponent { + webviewController: web_webview.WebviewController = new web_webview.WebviewController(); + build() { + Column() { + Button('loadData') + .onClick(() => { + if (this.webviewController.accessBackward()) { + this.webviewController.backward(); + return true; + } + }) + Web({ src: 'https://www.example.com/cn/', controller: this.webviewController}) + } + } +} +``` + + +If a previous record exists, [accessBackward()](../reference/apis/js-apis-webview.md#accessbackward) will return **true**. Similarly, you can call [accessForward()](../reference/apis/js-apis-webview.md#accessforward) to check whether a next record exists. If you skip the check, [forward()](../reference/apis/js-apis-webview.md#forward) and [backward()](../reference/apis/js-apis-webview.md#backward) will not trigger any action if the user has navigated to the end of history records. + + +## Page Redirection + +The **Web** component provides the [onUrlLoadIntercept()](../reference/arkui-ts/ts-basic-components-web.md#onurlloadintercept) API to redirect you from one page to another. + +In the following example, the frontend page **route.html** is loaded on to the application home page **Index.ets**, and the user is redirected to the application page **ProfilePage.ets** when clicking the link on the **route.html** page. + +- Code of the **index.ets** page: + + ```ts + // index.ets + import web_webview from '@ohos.web.webview'; + import router from '@ohos.router'; + @Entry + @Component + struct WebComponent { + webviewController: web_webview.WebviewController = new web_webview.WebviewController(); + + build() { + Column() { + Web({ src: $rawfile('route.html'), controller: this.webviewController }) + .onUrlLoadIntercept((event) => { + let url: string = event.data as string; + if (url.indexOf('native://') === 0) { + // Redirect to another page. + router.pushUrl({ url:url.substring(9) }) + return true; + } + return false; + }) + } + } + } + ``` + +- Code of the **route.html** page: + + ```html + + + + + + + + ``` + +- Code of the **ProfilePage.ets** page: + + ```ts + @Entry + @Component + struct ProfilePage { + @State message: string = 'Hello World'; + + build() { + Column() { + Text(this.message) + .fontSize(20) + } + } + } + ``` + + +## Cross-Application Redirection + +The **Web** component supports redirection from one application to another. + +In the following example, when a user clicks the link on the frontend page **call.html**, the user will be redirected to the dial screen of the phone app. + +- Application code: + + ```ts + // xxx.ets + import web_webview from '@ohos.web.webview'; + import call from '@ohos.telephony.call'; + + @Entry + @Component + struct WebComponent { + webviewController: web_webview.WebviewController = new web_webview.WebviewController(); + + build() { + Column() { + Web({ src: $rawfile('xxx.html'), controller: this.webviewController}) + .onUrlLoadIntercept((event) => { + let url: string = event.data as string; + // Check whether the link is redirecting to the dial screen of the phone app. + if (url.indexOf('tel://') === 0) { + // Redirect to the dial screen. + call.makeCall(url.substring(6), (err) => { + if (!err) { + console.info('make call succeeded.'); + } else { + console.info('make call fail, err is:' + JSON.stringify(err)); + } + }); + return true; + } + return false; + }) + } + } + } + ``` + +- Code of the **call.html** page: + + ```html + + + + + + + + ``` diff --git a/en/application-dev/web/web-resource-interception-request-mgmt.md b/en/application-dev/web/web-resource-interception-request-mgmt.md new file mode 100644 index 0000000000000000000000000000000000000000..c0e01e9ab290bae4a48cc3aad6b7419bae2340d1 --- /dev/null +++ b/en/application-dev/web/web-resource-interception-request-mgmt.md @@ -0,0 +1,70 @@ +# Customizing Page Request Responses + + +The **Web** component supports customization of the response to intercepted page requests. You can call [onInterceptRequest()](../reference/arkui-ts/ts-basic-components-web.md#oninterceptrequest9) to customize web page responses, file resource responses, etc. + + +When a resource loading request is initiated on a web page, the application layer will receive the request. The application layer then constructs a local resource response and sends it to the web kernel. On receiving the response, the web kernel parses the response and loads page resources accordingly. + + +In the following example, the **Web** component intercepts the web page request **https://www.intercept.com/test.html** and constructs a custom response in the application code. + + +- Code of the **example.html** page: + + ```html + + + + + example + + + diff --git a/en/device-dev/driver/driver-hdf-load.md b/en/device-dev/driver/driver-hdf-load.md index 8c99bf1088e9a40b50528123b701df2121d77b33..45c814433a6bf34d29cd842f522aa5f8a107e937 100644 --- a/en/device-dev/driver/driver-hdf-load.md +++ b/en/device-dev/driver/driver-hdf-load.md @@ -27,4 +27,9 @@ typedef enum { ### Sequential Loading (Default) -The **priority** field (ranging from 0 to 200) in the configuration file determines the loading sequence of a host and a driver. For the drivers in different hosts, the drivers in the host with a smaller priority value are loaded first. For the drivers in the same host, the driver with a smaller priority value is loaded first. +The **priority** field (ranging from 0 to 200) in the configuration file determines the loading sequence of a host and a driver. For the drivers in different hosts, the driver with a smaller priority value is loaded first. For the drivers in the same host, the driver with a smaller priority value is loaded first. + +### Exception Recovery (User-Mode Driver) +The policies for restoring from a driver service exception are as follows: +- If **preload** is set to **0** (**DEVICE_PRELOAD_ENABLE**) or **1** (**DEVICE_PRELOAD_ENABLE_STEP2**) for the driver service, the startup module starts the host and reloads the service. +- If **preload** is set to **2** (**DEVICE_PRELOAD_DISABLE**), the service module needs to register an HDF service status listener. When receiving a notification on service exit, the service module calls **LoadDevice()** to reload the service. diff --git a/en/device-dev/subsystems/subsys-power-battery-level-customization.md b/en/device-dev/subsystems/subsys-power-battery-level-customization.md index 9bf7ec042827f0994f20c4a4212e8a8a041c619c..ab4d120d2d550ecd2b4f47f01329b89e8d3046ba 100644 --- a/en/device-dev/subsystems/subsys-power-battery-level-customization.md +++ b/en/device-dev/subsystems/subsys-power-battery-level-customization.md @@ -8,6 +8,7 @@ By default, OpenHarmony provides the battery level based on the current battery ### Constraints + The configuration path for battery level customization is subject to the [configuration policy](https://gitee.com/openharmony/customization_config_policy). In this development guide, `/vendor` is used as an example of the configuration path. During actual development, you need to modify the customization path based on the product configuration policy. ## How to Develop @@ -36,7 +37,7 @@ The following uses [DAYU200](https://gitee.com/openharmony/vendor_hihope/tree/ma ├── battery_config.json ``` -3. Write the custom `battery_config.json` file by referring to the `battery_config.json` file in the default folder of battery level configuration. For example: +3. Write the custom `battery_config.json` file by referring to the [battery_config.json](https://gitee.com/openharmony/powermgr_battery_manager/blob/master/services/native/profile/battery_config.json) file in the default folder of battery level configuration. For example: ```json { @@ -54,7 +55,7 @@ The following uses [DAYU200](https://gitee.com/openharmony/vendor_hihope/tree/ma **Table 1** Battery level configuration - | Battery Bevel| Battery Volume| Description| + | Battery Level| Battery Volume| Description| | -------- | -------- | -------- | | shutdown | 5 | Power-off battery level| | critical | 10 | Extremely low battery level| @@ -65,7 +66,7 @@ The following uses [DAYU200](https://gitee.com/openharmony/vendor_hihope/tree/ma | full | 100 | Full battery level| -4. Write the `BUILD.gn` file by referring to the `BUILD.gn` in the default folder of battery level configuration to pack the `battery_config.json` file to the `//vendor/etc/battery` directory. The configuration is as follows: +4. Write the `BUILD.gn` file by referring to the [BUILD.gn](https://gitee.com/openharmony/powermgr_battery_manager/blob/master/services/native/profile/BUILD.gn) file in the default folder of battery level configuration to pack the `battery_config.json` file to the `//vendor/etc/battery` directory. The configuration is as follows: ```shell import("//build/ohos.gni") # Reference build/ohos.gni. @@ -292,6 +293,8 @@ The following uses [DAYU200](https://gitee.com/openharmony/vendor_hihope/tree/ma ## Reference During development, you can refer to the [default battery level configuration](https://gitee.com/openharmony/powermgr_battery_manager/blob/master/services/native/profile/battery_config.json), as shown below: + + ```json { "soc": { @@ -306,4 +309,4 @@ During development, you can refer to the [default battery level configuration](h } ``` -Packing path: `/system/etc/battery` +Packing path: /system/etc/battery diff --git a/en/device-dev/subsystems/subsys-power-level-LED-color.md b/en/device-dev/subsystems/subsys-power-level-LED-color.md index ea940bed43c65616f61dcd15c0d16f892c7593a6..3d82bd2258f4dbb64d7e43e19a1dfd8612cbdfc4 100644 --- a/en/device-dev/subsystems/subsys-power-level-LED-color.md +++ b/en/device-dev/subsystems/subsys-power-level-LED-color.md @@ -8,6 +8,7 @@ OpenHarmony provides the battery level and LED color mapping by default. Some pr ### Constraints + The configuration path for battery level customization is subject to the [configuration policy](https://gitee.com/openharmony/customization_config_policy). In this development guide, `/vendor` is used as an example of the configuration path. During actual development, you need to modify the customization path based on the product configuration policy. ## How to Develop @@ -36,7 +37,7 @@ The following uses [DAYU200](https://gitee.com/openharmony/vendor_hihope/tree/ma ├── battery_config.json ``` -3. Write the custom `battery_config.json` file by referring to the `battery_config.json` file in the default folder of battery level and LED color mapping configuration. For example: +3. Write the custom `battery_config.json` file by referring to the [battery_config.json](https://gitee.com/openharmony/powermgr_battery_manager/blob/master/services/native/profile/battery_config.json) file in the default folder of battery level and LED color mapping configuration. For example: ```json { @@ -57,18 +58,23 @@ The following uses [DAYU200](https://gitee.com/openharmony/vendor_hihope/tree/ma } ``` - **Table 1** Description of the battery level and LED color mapping configuration + **Table 1** Description of battery levels - | Item| Description| + | Battery Level| Description| | -------- | -------- | | low | Low battery level| | normal | Normal battery level| | high | High battery level| + + **Table 2** Configuration items for the battery level range and LED color + + | Configuration Item| Description| + | -------- | -------- | | soc | Battery level range| | rgb | LED RGB combination| -4. Write the `BUILD.gn` file by referring to the `BUILD.gn` in the default folder of battery level and LED color mapping configuration to pack the `battery_config.json` file to the `//vendor/etc/battery` directory. The configuration is as follows: +4. Write the `BUILD.gn` file by referring to the [BUILD.gn](https://gitee.com/openharmony/powermgr_battery_manager/blob/master/services/native/profile/BUILD.gn) file in the default folder of battery level and LED color mapping configuration to pack the `battery_config.json` file to the `//vendor/etc/battery` directory. The configuration is as follows: ```shell import("//build/ohos.gni") # Reference build/ohos.gni. @@ -207,6 +213,8 @@ The following uses [DAYU200](https://gitee.com/openharmony/vendor_hihope/tree/ma ## Reference During development, you can refer to the [default battery level and LED color mapping configuration](https://gitee.com/openharmony/powermgr_battery_manager/blob/master/services/native/profile/battery_config.json), as shown below: + + ```json { "light": { @@ -226,4 +234,4 @@ During development, you can refer to the [default battery level and LED color ma } ``` -Packing path: `/system/etc/battery` +Packing path: /system/etc/battery diff --git a/en/readme/arkui.md b/en/readme/arkui.md index b4c8f0ef37ae2c3d86d30eb68284f53f73ca1472..ba16aacc24c12faae73b28dbe13cbf3bd69fd7f7 100644 --- a/en/readme/arkui.md +++ b/en/readme/arkui.md @@ -2,7 +2,7 @@ ## Introduction -ArkUI is a UI development framework that provides what you'll need to develop application UIs in OpenHarmony, including UI components, animations, drawing, interaction events, and JavaScript API extension mechanisms. ArkUI comes with two development paradigms: eTS-based declarative development paradigm (declarative development paradigm for short) and JavaScript-compatible web-like development paradigm (web-like development paradigm for short). +ArkUI is a UI development framework that provides what you'll need to develop application UIs in OpenHarmony, including UI components, animations, drawing, interaction events, and JavaScript API extension mechanisms. ArkUI comes with two development paradigms: ArkTS-based declarative development paradigm (declarative development paradigm for short) and JavaScript-compatible web-like development paradigm (web-like development paradigm for short). **Framework Structure** diff --git a/en/release-notes/OpenHarmony-v1-1-4-LTS.md b/en/release-notes/OpenHarmony-v1-1-4-LTS.md index a8486ba44ef69cd7e01a9f0861b18dc367b22e72..b83172b04cb3b9d507ca509614325c4ee76bd5da 100644 --- a/en/release-notes/OpenHarmony-v1-1-4-LTS.md +++ b/en/release-notes/OpenHarmony-v1-1-4-LTS.md @@ -66,7 +66,7 @@ This version does not involve API updates. ### Chip and Development Board Adaptation -For details about the adaptation status, see [SIG-Devboard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). +For details about the adaptation status, see [SIG_DevBoard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). ## Resolved Issues diff --git a/en/release-notes/OpenHarmony-v1.1.5-LTS.md b/en/release-notes/OpenHarmony-v1.1.5-LTS.md index dadbc5274c180bc19692d613776e14d6159bd296..bf6e63c4bdee8dd475b574a23f7ed0f170e61ac1 100644 --- a/en/release-notes/OpenHarmony-v1.1.5-LTS.md +++ b/en/release-notes/OpenHarmony-v1.1.5-LTS.md @@ -69,7 +69,7 @@ This version does not involve API updates. ### Chip and Development Board Adaptation -For details about the adaptation status, see [SIG-Devboard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). +For details about the adaptation status, see [SIG_DevBoard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). ## Resolved Issues diff --git a/en/release-notes/OpenHarmony-v3.0-LTS.md b/en/release-notes/OpenHarmony-v3.0-LTS.md index 3aaab58808b76f7626d27ba09156d49f10da348d..4eda50c36ba79e52b2fcae3fd63ffc45ee33646d 100644 --- a/en/release-notes/OpenHarmony-v3.0-LTS.md +++ b/en/release-notes/OpenHarmony-v3.0-LTS.md @@ -132,7 +132,7 @@ For details, see [JS API Differences](api-diff/v3.0-LTS/js-apidiff-v3.0-lts.md). ### Chip and Development Board Adaptation -For details about the adaptation status, see [SIG-Devboard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). +For details about the adaptation status, see [SIG_DevBoard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). ## Resolved Issues diff --git a/en/release-notes/OpenHarmony-v3.0.1-LTS.md b/en/release-notes/OpenHarmony-v3.0.1-LTS.md index 1a8cb139b23ac9a0bd13736a4b448add7b3321ec..cd207ad519e0e6199f2bae7bb1fd802e35d9ceca 100644 --- a/en/release-notes/OpenHarmony-v3.0.1-LTS.md +++ b/en/release-notes/OpenHarmony-v3.0.1-LTS.md @@ -71,7 +71,7 @@ This version does not involve API updates. ### Chip and Development Board Adaptation -For details about the adaptation status, see [SIG-Devboard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). +For details about the adaptation status, see [SIG_DevBoard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). ## Resolved Issues diff --git a/en/release-notes/OpenHarmony-v3.0.2-LTS.md b/en/release-notes/OpenHarmony-v3.0.2-LTS.md index dd5541c0bf72ce1c57d839bcd9b8b505e1a8d603..49822c1b4886a576d63665aa67d5403fdec488c4 100644 --- a/en/release-notes/OpenHarmony-v3.0.2-LTS.md +++ b/en/release-notes/OpenHarmony-v3.0.2-LTS.md @@ -72,7 +72,7 @@ This version does not involve API updates. ### Chip and Development Board Adaptation -For details about the adaptation status, see [SIG-Devboard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). +For details about the adaptation status, see [SIG_DevBoard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). ## Resolved Issues diff --git a/en/release-notes/OpenHarmony-v3.0.3-LTS.md b/en/release-notes/OpenHarmony-v3.0.3-LTS.md index c627586d19f3aa8f20d29dcf2a4bab663f8f2b21..356ce5ce7908d7c287ecc442abefb10c8388776d 100644 --- a/en/release-notes/OpenHarmony-v3.0.3-LTS.md +++ b/en/release-notes/OpenHarmony-v3.0.3-LTS.md @@ -72,7 +72,7 @@ This version does not involve API updates. ### Chip and Development Board Adaptation -For details about the adaptation status, see [SIG-Devboard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). +For details about the adaptation status, see [SIG_DevBoard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). ## Resolved Issues diff --git a/en/release-notes/OpenHarmony-v3.0.5-LTS.md b/en/release-notes/OpenHarmony-v3.0.5-LTS.md index e6a12274ff12404246e45fe75c3ddf5dac48591d..7c39ba86e60722e6bb8db69e2dc03be5d4ad4921 100644 --- a/en/release-notes/OpenHarmony-v3.0.5-LTS.md +++ b/en/release-notes/OpenHarmony-v3.0.5-LTS.md @@ -100,7 +100,7 @@ This version does not involve API updates. ### Chip and Development Board Adaptation -For details about the adaptation status, see [SIG-Devboard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). +For details about the adaptation status, see [SIG_DevBoard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). ## Resolved Issues diff --git a/en/release-notes/OpenHarmony-v3.0.6-LTS.md b/en/release-notes/OpenHarmony-v3.0.6-LTS.md index 761dd2a27971c41c3ae1eff1ff1db65fb79d0d21..bab09251b9a0b2f5db0d420c96d59b1e86e7aa56 100644 --- a/en/release-notes/OpenHarmony-v3.0.6-LTS.md +++ b/en/release-notes/OpenHarmony-v3.0.6-LTS.md @@ -91,7 +91,7 @@ This version does not involve API updates. ### Chip and Development Board Adaptation -For details about the adaptation status, see [SIG-Devboard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). +For details about the adaptation status, see [SIG_DevBoard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). ## Fixed Security Vulnerabilities diff --git a/en/release-notes/OpenHarmony-v3.0.7-LTS.md b/en/release-notes/OpenHarmony-v3.0.7-LTS.md index 0fa47366882cc0d9e3482d0dac4866df69ebacf3..47d2f1d36bfbad0b1e6c8a36cc16dc04e3c3ae21 100644 --- a/en/release-notes/OpenHarmony-v3.0.7-LTS.md +++ b/en/release-notes/OpenHarmony-v3.0.7-LTS.md @@ -91,7 +91,7 @@ This version does not involve API updates. ### Chip and Development Board Adaptation -For details about the adaptation status, see [SIG-Devboard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). +For details about the adaptation status, see [SIG_DevBoard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). ## Fixed Security Vulnerabilities diff --git a/en/release-notes/OpenHarmony-v3.0.8-LTS.md b/en/release-notes/OpenHarmony-v3.0.8-LTS.md index e95c84a7c8ef73e26fc4af5dbf690ee99b1f7c5e..cb1b559176011ea9511ceb13774fe6feab7af03b 100644 --- a/en/release-notes/OpenHarmony-v3.0.8-LTS.md +++ b/en/release-notes/OpenHarmony-v3.0.8-LTS.md @@ -91,7 +91,7 @@ This version does not involve API updates. ### Chip and Development Board Adaptation -For details about the adaptation status, see [SIG-Devboard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). +For details about the adaptation status, see [SIG_DevBoard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard.md). ## Fixed Security Vulnerabilities diff --git a/en/release-notes/OpenHarmony-v3.1-beta.md b/en/release-notes/OpenHarmony-v3.1-beta.md index a940747b0b6ab44ea21f19f6923966140403bca8..f166a0b1693e3ee8b9e4c0ea1e62c03ec4138067 100644 --- a/en/release-notes/OpenHarmony-v3.1-beta.md +++ b/en/release-notes/OpenHarmony-v3.1-beta.md @@ -100,28 +100,28 @@ This version has the following updates to OpenHarmony 3.0 LTS. | Subsystem| Standard System| Mini and Small Systems| | -------- | -------- | -------- | | Bundle management framework| - I4MBSE: Provides the home screen bundle management client.
- I4MBSF: Supports cache clearing.
- I4MBSG: Supports installation package information query.
- I4MBSD: Supports multi-HAP installation.
- I4MBSH: Supports signature verification during multi-HAP installation.
- I4MBSC: Supports the **srcPath** field for modules and abilities.| NA | -| Distributed Scheduler subsystem| -I4MBRW: Samgr supports intra-process system ability list control.
-I4MBRV: Samgr supports maintenance of the system service status list.
-I4MBRZ: Samgr supports initialization of the full service list.
-I4MBRY: Samgr supports maintenance of the system process status list.
-I4MBRX: Samgr supports loading a specific system service.| NA | -| DeviceProfile subsystem| -I4NY23: Insertion, deletion, and query of local device profiles.
-I4NY1X: Query of remote device profiles.
-I4NY1T: Subscription to remote profile changes.
-I4NY1W: Cross-device profile synchronization.| NA | -| Account subsystem| -I4MBQW: Application account addition and deletion.
-I4MBQV: Restrictions on the basic information about application accounts.
-I4MBQU: Application account subscription and unsubscription.
-I4MBQT: Application account function setting and content modification.
-I4MBQS: Application account information query.
-I4IT3U: Basic information management for application accounts.| NA | -| Pan-sensor subsystem| -I3NJ96: Acceleration sensor data reporting.
-I3NJ8H: Gyroscope sensor data reporting.
-I3NJ7J: Ambient light sensor data reporting.
-I3NJ76: Magnetic field sensor data reporting.
-I4MBRP: Magnetic declination and dip.
-I4MBRQ: Horizontal intensity and total intensity of the magnetic field.| NA | +| Distributed Scheduler subsystem| - I4MBRW: Samgr supports intra-process system ability list control.
- I4MBRV: Samgr supports maintenance of the system service status list.
- I4MBRZ: Samgr supports initialization of the full service list.
- I4MBRY: Samgr supports maintenance of the system process status list.
- I4MBRX: Samgr supports loading a specific system service. | NA | +| DeviceProfile subsystem| - I4NY23: Insertion, deletion, and query of local device profiles.
- I4NY1X: Query of remote device profiles.
- I4NY1T: Subscription to remote profile changes.
- I4NY1W: Cross-device profile synchronization. | NA | +| Account subsystem| - I4MBQW: Application account addition and deletion.
- I4MBQV: Restrictions on the basic information about application accounts.
- I4MBQU: Application account subscription and unsubscription.
- I4MBQT: Application account function setting and content modification.
- I4MBQS: Application account information query.
- I4IT3U: Basic information management for application accounts. | NA | +| Pan-sensor subsystem| - I3NJ96: Acceleration sensor data reporting.
- I3NJ8H: Gyroscope sensor data reporting.
- I3NJ7J: Ambient light sensor data reporting.
- I3NJ76: Magnetic field sensor data reporting.
- I4MBRP: Magnetic declination and dip.
- I4MBRQ: Horizontal intensity and total intensity of the magnetic field. | NA | | USB subsystem| I410OZ:
- Querying the list of connected USB devices.
- Obtaining the temporary permission to access USB devices.
- Setting USB device configurations and interfaces.
- Data transfer using USB devices.| NA | | Multi-language Runtime subsystem| - I4MBUK: The default runtime of JS/TS is changed from quickjs to ARK.
- I4MBUJ: The memory reclaim capability of ARK runtime is enhanced. The concurrent marking and concurrent compression algorithms are supported. Some regions can be selected for compression GC, reducing the GC pause time by 30%.| NA | | Globalization subsystem| - Added globalization features: singular and plural rules, string sorting, phone number processing, calendar and local calendar, weights and measures and formatting, locale representations and attributes, time segment formatting, alphabet retrieval, Unicode character attributes, wrapping and line feed.
- Supports system resources and rawfile resources.| NA | -| DSoftBus subsystem| -I4FZ29: DSoftBus provides the Ext API for transmission.
-I4FZ25: DSoftBus supports network switching.| -I4FZ29: DSoftBus provides the Ext API for transmission.
-I4FZ25: DSoftBus supports network switching.| -| Startup subsystem| NA | -I3XGJH: init basic environment building.
-I3XGKV: System parameter management.
-I3XGLN: init script management.
-I3XGMQ: Basic permission management.
-I3XGN8: Boot image building and loading.
-I3XGKV: uevent management.
-I3XGNM: Burning mode.| -| Media subsystem| NA | -I4BX5Z: HiStreamer supports audio playback and control.
-I4BX8A: HiStreamer supports playback of MP3 and WAV audio files.
-I4BX9E: HiStreamer playback engine framework requirements are met.
-I4DK89: HiStreamer plugin framework requirements are met.
-I4DK8D: HiStreamer performance and DFX requirements are met.| +| DSoftBus subsystem| - I4FZ29: DSoftBus provides the Ext API for transmission.
- I4FZ25: DSoftBus supports network switching. | - I4FZ29: DSoftBus provides the Ext API for transmission.
- I4FZ25: DSoftBus supports network switching. | +| Startup subsystem| NA | - I3XGJH: init basic environment building.
- I3XGKV: System parameter management.
- I3XGLN: init script management.
- I3XGMQ: Basic permission management.
- I3XGN8: Boot image building and loading.
- I3XGKV: uevent management.
- I3XGNM: Burning mode. | +| Media subsystem| NA | - I4BX5Z: HiStreamer supports audio playback and control.
- I4BX8A: HiStreamer supports playback of MP3 and WAV audio files.
- I4BX9E: HiStreamer playback engine framework requirements are met.
- I4DK89: HiStreamer plugin framework requirements are met.
- I4DK8D: HiStreamer performance and DFX requirements are met. | | Graphics subsystem| New design of the OpenHarmony graphics stack:
Added the background rendering feature to the UI framework.
Supports the access to the background rendering module of RenderService from ArkUI components.| NA | -| Kernel subsystem| Kernel (Linux 5.10):
-I4LUG4: Supports Contiguous Memory Area (CMA) reuse. (Currently, only Hi3516D V300 is supported.)
-I4LX4G: Supports anonymous Virtual Memory Area (VMA) naming. (Currently, only Hi3516D V300 is supported.)| -I3ND6Y: Optimized OS kernel and driver startup performance.| -| Startup subsystem| NA | -I3NTCT: The Linux init process supports hot swap.| -| Distributed Data Management subsystem| NA | -I4H3JJ: Provides distributed objects for small-system devices.| -| Telephony subsystem| NA | -I4JQ2N: Provides HTTP JS APIs.
-I4JQ3G: Supports HTTP 2.0.| +| Kernel subsystem| Kernel (Linux 5.10):
- I4LUG4: Supports Contiguous Memory Area (CMA) reuse. (Currently, only Hi3516D V300 is supported.)
- I4LX4G: Supports anonymous Virtual Memory Area (VMA) naming. (Currently, only Hi3516D V300 is supported.) | - I3ND6Y: Optimized OS kernel and driver startup performance. | +| Startup subsystem| NA | - I3NTCT: The Linux init process supports hot swap. | +| Distributed Data Management subsystem| NA | - I4H3JJ: Provides distributed objects for small-system devices. | +| Telephony subsystem| NA | - I4JQ2N: Provides HTTP JS APIs.
- I4JQ3G: Supports HTTP 2.0. | | Misc Services subsystem| I4MBQE:
Enables applications to read the system time.
Enables applications to read the system time zone.
Provides time change notifications.
Provides time zone change notifications.
Provides minute change notifications.| NA | -| Compilation and Building subsystem| I4K7E3: Provides a unified compilation command as the compilation entry.
-I4KCNB: Supports the unified gn template.| -I4MBQN: Supports a unified compilation entry and uses **build.sh** to compile mini- and small-system devices.
-I4MBQP: Supports a unified compilation process.
-I4MBQR: Supports unified product configuration.| -| File Storage subsystem| -I4MBS2: Provides StatFS JS interfaces for obtaining the total space and free space of a device.| NA | -| Driver subsystem| -I4L3KK: The drive capability of sensor components is enhanced. The sensor sampling rate can be dynamically configured, the three-axis direction can be statically configured, and the ambient light gain can be adjusted.
-I4L3LF: The sensor driver model capability is enhanced to support cross-process service obtaining and invoking of sensor HDIs.
-I4MBTS: Provides more capabilities for HDF input devices and supports data reporting of joystick devices.
-I4MBTR: The default reference implementation of the Display HDI interface for the standard system is provided based on the DRM display architecture, which helps vendors to adapt the HDI.
-I4HPR7: Provides the hcs macro parsing mechanism. During compilation, the hc-gen tool is used to parse the driver parameters into parameters involved in the macro definition. The driver accesses these macro definition parameters through the hcs macro-format interface.
-I4KVJQ: Supports system-level sleep/wakeup of the Linux and LiteOS kernels.
-I4L3ZZF: Supports synchronous/asynchronous power management invoking and provides a synchronous/asynchronous mechanism for HDF device sleep/wakeup management.| -I4L3KK: The drive capability of sensor components is enhanced. The sensor sampling rate can be dynamically configured, the three-axis direction can be statically configured, and the ambient light gain can be adjusted.
Provides more capabilities for HDF input devices (running on Linux) and supports data reporting of joystick devices.
-I4HPR7: Provides the hcs macro parsing mechanism. During compilation, the hc-gen tool is used to parse the driver parameters into parameters involved in the macro definition. The driver accesses these macro definition parameters through the hcs macro-format interface.
-I4KVJQ: Supports system-level sleep/wakeup of the Linux and LiteOS kernels.
-I4L3ZZF: Supports synchronous/asynchronous power management invoking and provides a synchronous/asynchronous mechanism for HDF device sleep/wakeup management.| +| Compilation and Building subsystem| - I4K7E3: Provides a unified compilation command as the compilation entry.
- I4KCNB: Supports the unified gn template. | - I4MBQN: Supports a unified compilation entry and uses **build.sh** to compile mini- and small-system devices.
- I4MBQP: Supports a unified compilation process.
- I4MBQR: Supports unified product configuration. | +| File Storage subsystem| - I4MBS2: Provides StatFS JS interfaces for obtaining the total space and free space of a device. | NA | +| Driver subsystem| - I4L3KK: The drive capability of sensor components is enhanced. The sensor sampling rate can be dynamically configured, the three-axis direction can be statically configured, and the ambient light gain can be adjusted.
- I4L3LF: The sensor driver model capability is enhanced to support cross-process service obtaining and invoking of sensor HDIs.
- I4MBTS: Provides more capabilities for HDF input devices and supports data reporting of joystick devices.
- I4MBTR: The default reference implementation of the Display HDI interface for the standard system is provided based on the DRM display architecture, which helps vendors to adapt the HDI.
- I4HPR7: Provides the hcs macro parsing mechanism. During compilation, the hc-gen tool is used to parse the driver parameters into parameters involved in the macro definition. The driver accesses these macro definition parameters through the hcs macro-format interface.
- I4KVJQ: Supports system-level sleep/wakeup of the Linux and LiteOS kernels.
- I4L3ZZF: Supports synchronous/asynchronous power management invoking and provides a synchronous/asynchronous mechanism for HDF device sleep/wakeup management. | - I4L3KK: The drive capability of sensor components is enhanced. The sensor sampling rate can be dynamically configured, the three-axis direction can be statically configured, and the ambient light gain can be adjusted.
Provides more capabilities for HDF input devices (running on Linux) and supports data reporting of joystick devices.
- I4HPR7: Provides the hcs macro parsing mechanism. During compilation, the hc-gen tool is used to parse the driver parameters into parameters involved in the macro definition. The driver accesses these macro definition parameters through the hcs macro-format interface.
- I4KVJQ: Supports system-level sleep/wakeup of the Linux and LiteOS kernels.
- I4L3ZZF: Supports synchronous/asynchronous power management invoking and provides a synchronous/asynchronous mechanism for HDF device sleep/wakeup management. | | ArkUI| - I4MBUY: Added **target** to the event to obtain the size.
- I4MBUZ: The **\** component supports cache setting.
- I4MBV1: The **\** component supports synchronous and asynchronous rendering setting.
- I4MBV3: Added the component polymorphic style setting to the style setting feature.
- I4MBV5: Added the pop-up text for menu content extension to the **\** component.
- I4MBV6: Added the custom container components to the component customization feature.
- I4MBV7: Added scroll bar style customization.
- I4MBV8: Added switching forbidden for the **\** component.
- I4MBV9: Added tab bar content customization for the **\** component.
- I4MBVA: Added title bar setting for the **\** component.
- I4MBVB: Added toolbar display/hide control for the **\** component.
- I4MBVC: Added content customization for the **\** component.
- I4MBVD: Added the SysCap declaration compilation feature.
- I4MBVE: Added the JSSDK compilation feature.
- I4MBVF: Added the **Config.json** compilation feature.
- I4MBVG: Added the breakpoint debugging feature for single-instance debugging.
- I4MBVH: Added the attach debugging feature for single-instance debugging.
- I4MBVI: Added the declarative paradigm compilation feature to support compilation and verification.
- I4MBVJ: Added the JS module shared compilation feature.
- I4MBVK: Added the HAR reference and compilation feature.
- I4MBVL: Added the HPM reference and compilation feature.
- I4MBVN: Added the vertical display of the slider bar.
- I4MBVO: Added the content customization feature for the **\** component.
- I4MBVP: Added the drawing capability for the **\** component.
- I4MBVQ: Enhanced the capabilities of the **\** component.
- I4MBVR: Added the touch target setting.
- I4MBVS: Added the support for Lottie animation.
- I4MBVT: Added the feature for obtaining the component size.
- I4MBVU: Added content customization to the **\** component.
- I4MBVV: Added the support for the **\** gesture.
- I4MBVW: Added the inspector capability for UI preview.
- I4MBVX: Added the non-route file preview feature.
- I4MBVY: Added the NAPI preview feature.
- I4MBVZ: Added the declarative paradigm preview feature with the basic preview supported.
- I4MBW2: Added the declarative paradigm hot loading feature for modification to the existing nodes.
- I4MBW3: Added the declarative paradigm hot loading feature for node addition.
- I4MBW4: Added the declarative paradigm hot loading feature for node deletion.
- I4MBW5: Added the component preview feature and the page component preview.
Added the universal attribute **touchable** to specify whether a component is touchable.
Added the basic component **\**.
Added the basic component **\**.
Added the basic component **\