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/abilitystage.md b/en/application-dev/application-models/abilitystage.md index 9a4e71d3fa696ee6f2707545b80456df34fe85ac..769c6b4540856a553ca30f02c0a689e1c32f2307 100644 --- a/en/application-dev/application-models/abilitystage.md +++ b/en/application-dev/application-models/abilitystage.md @@ -12,7 +12,7 @@ AbilityStage is not automatically generated in the default project of DevEco Stu 1. In the **ets** directory of the **Module** project, right-click and choose **New > Directory** to create a directory named **myabilitystage**. -2. In the **myabilitystage** directory, right-click and choose **New > ts File** to create a file named **MyAbilityStage.ts**. +2. In the **myabilitystage** directory, right-click and choose **New > TypeScript File** to create a file named **MyAbilityStage.ts**. 3. Open the **MyAbilityStage.ts** file, and import the dependency package of AbilityStage. Customize a class that inherits from AbilityStage, and add the required lifecycle callbacks. The following code snippet adds the **onCreate()** lifecycle callback. @@ -20,17 +20,17 @@ AbilityStage is not automatically generated in the default project of DevEco Stu import AbilityStage from '@ohos.app.ability.AbilityStage'; export default class MyAbilityStage extends AbilityStage { - onCreate() { - // When the HAP of the application is loaded for the first time, initialize the module. - } - onAcceptWant(want) { - // Triggered only for the ability with the specified launch type. - return "MyAbilityStage"; - } + onCreate() { + // When the HAP of the application is loaded for the first time, initialize the module. + } + onAcceptWant(want) { + // Triggered only for the ability with the specified launch type. + return "MyAbilityStage"; + } } ``` -4. Set **srcEntry** in the [module.json5 file](../quick-start/module-configuration-file.md) to the code path of the module. +4. In the [module.json5 file](../quick-start/module-configuration-file.md), set **srcEntry** to specify the code path of the module as the entry for loading the HAP. ```json { "module": { @@ -42,7 +42,6 @@ AbilityStage is not automatically generated in the default project of DevEco Stu } ``` - [AbilityStage](../reference/apis/js-apis-app-ability-abilityStage.md) has the lifecycle callback [onCreate()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageoncreate) and the event callbacks [onAcceptWant()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant), [onConfigurationUpdated()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonconfigurationupdate), and [onMemoryLevel()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonmemorylevel). @@ -53,7 +52,6 @@ AbilityStage is not automatically generated in the default project of DevEco Stu - **onConfigurationUpdated()** event callback: triggered when the global system configuration changes. The global system configuration, such as the system language and theme, are defined in the [Configuration](../reference/apis/js-apis-app-ability-configuration.md) class before project configuration. - **onMemoryLevel()** event callback: triggered when the system adjusts the memory. - When an application is switched to the background, it is cached in the background. This adversely affects the overall system performance. When system resources are insufficient, the system reclaims memory from applications in multiple ways. For example, the system may stop applications to release memory for executing key tasks. To further maintain the balance of the system memory and prevent the system from stopping application processes, you can subscribe to the system memory changes in the **onMemoryLevel()** lifecycle callback of AbilityStage to release unnecessary resources. @@ -62,8 +60,8 @@ When an application is switched to the background, it is cached in the backgroun import AbilityStage from '@ohos.app.ability.AbilityStage'; export default class MyAbilityStage extends AbilityStage { - onMemoryLevel(level) { - // Release unnecessary memory based on the change of available system memory. - } + onMemoryLevel(level) { + // Release unnecessary memory based on the change of available system memory. + } } ``` diff --git a/en/application-dev/application-models/application-context-stage.md b/en/application-dev/application-models/application-context-stage.md index 5308d1899a46ffb9907a18bd74a7920627ac720b..cc19530d99ca4bf2005fcb4b5084c9e83b445193 100644 --- a/en/application-dev/application-models/application-context-stage.md +++ b/en/application-dev/application-models/application-context-stage.md @@ -84,7 +84,7 @@ The following table describes the application development paths obtained from co | Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| bundleCodeDir | string | Yes | No | Path for storing the application's installation package, that is, installation directory of the application on the internal storage. | +| bundleCodeDir | string | Yes | No | Path for storing the application's installation package, that is, installation directory of the application on the internal storage. Do not access resource files by concatenating paths. Use [@ohos.resourceManager] instead. | | cacheDir | string | Yes| No| Path for storing the application's cache files, that is, cache directory of the application on the internal storage.
It is the content of **Storage** of an application under **Settings > Apps & services > Apps**.| | filesDir | string | Yes | No | Path for storing the application's common files, that is, file directory of the application on the internal storage.
Files in this directory may be synchronized to other directories during application migration or backup.| | preferencesDir | string | Yes | Yes | Path for storing the application's preference files, that is, preferences directory of the application. | @@ -187,13 +187,13 @@ The base class **Context** provides [createBundleContext(bundleName:string)](../ > **NOTE** > > To obtain the context of another application: - > + > > - Request the **ohos.permission.GET_BUNDLE_INFO_PRIVILEGED** permission. For details, see [Declaring Permissions in the Configuration File](../security/accesstoken-guidelines.md#declaring-permissions-in-the-configuration-file). - > + > > - This is a system API and cannot be called by third-party applications. For example, application information displayed on the home screen includes the application name and icon. The home screen application calls the foregoing method to obtain the context information, so as to obtain the resource information including the application name and icon. - + ```ts import UIAbility from '@ohos.app.ability.UIAbility'; @@ -248,7 +248,7 @@ The base class **Context** provides [createBundleContext(bundleName:string)](../ In the DFX statistics scenario of an application, if you need to collect statistics on the stay duration and access frequency of a page, you can subscribe to UIAbility lifecycle changes in a process. -[ApplicationContext](../reference/apis/js-apis-inner-application-applicationContext) provides APIs for subscribing to UIAbility lifecycle changes in a process. When the UIAbility lifecycle changes in a process, for example, being created or destroyed, becoming visible or invisible, or gaining or losing focus, the corresponding callback is triggered. Each time the callback is registered, a listener lifecycle ID is returned, with the value incremented by 1 each time. When the number of listeners exceeds the upper limit (2^63-1), **-1** is returned. The following uses [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md) as an example. +[ApplicationContext](../reference/apis/js-apis-inner-application-applicationContext.md) provides APIs for subscribing to UIAbility lifecycle changes in a process. When the UIAbility lifecycle changes in a process, for example, being created or destroyed, becoming visible or invisible, or gaining or losing focus, the corresponding callback is triggered. Each time the callback is registered, a listener lifecycle ID is returned, with the value incremented by 1 each time. When the number of listeners exceeds the upper limit (2^63-1), **-1** is returned. The following uses [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md) as an example. ```ts diff --git a/en/application-dev/application-models/component-startup-rules.md b/en/application-dev/application-models/component-startup-rules.md index 26b2446893aea096611f896e878ef15888830afa..bddf63dbc69ea243733e6f60f67f92a854833bf7 100644 --- a/en/application-dev/application-models/component-startup-rules.md +++ b/en/application-dev/application-models/component-startup-rules.md @@ -23,8 +23,8 @@ In view of this, OpenHarmony formulates a set of component startup rules, as fol - **Before starting a component of another application, verify the visible field of the target component.** - - If the **visible** field of the target component is **false**, verify the **ohos.permission.START_INVISIBLE_ABILITY** permission. - - For details, see [Component Visible Configuration](../quick-start/module-configuration-file.md#abilities). + - If the **exported** field of the target component is **false**, verify the **ohos.permission.START_INVISIBLE_ABILITY** permission. + - For details, see [Component exported Configuration](../quick-start/module-configuration-file.md#abilities). - **Before starting a component of a background application, verify the BACKGROUND permission.** - An application is considered as a foreground application only when the application process gains focus or its UIAbility component is running in the foreground. @@ -37,8 +37,8 @@ In view of this, OpenHarmony formulates a set of component startup rules, as fol > **NOTE** > > - Component startup control has been implemented since OpenHarmony v3.2 Release. -> -> - The new component startup rules are more strict than the original ones. You must be familiar with the new startup rules to prevent service exceptions. +> +> - The new component startup rules are more strict than the original ones. You must be familiar with the new startup rules to prevent service exceptions. ## Intra-Device Component Startup Rules diff --git a/en/application-dev/application-models/datashareextensionability.md b/en/application-dev/application-models/datashareextensionability.md index f671848f890277af92fc23869c5db0d57b02a316..bea3de69c6d7ad375206fb1d53bcc36c2624989d 100644 --- a/en/application-dev/application-models/datashareextensionability.md +++ b/en/application-dev/application-models/datashareextensionability.md @@ -1,4 +1,4 @@ # DataShareExtensionAbility (for System Applications Only) -DataShareExtensionAbility provides the data sharing capability. System applications can implement a DataShareExtensionAbility or access an existing DataShareExtensionAbility in the system. Third-party applications can only access an existing DataShareExtensionAbility. For details, see [DataShare Development](../database/database-datashare-guidelines.md). +DataShareExtensionAbility provides the data sharing capability. System applications can implement a DataShareExtensionAbility or access an existing DataShareExtensionAbility in the system. Third-party applications can only access an existing DataShareExtensionAbility. For details, see [Cross-Application Data Sharing Overview](../database/share-device-data-across-apps-overview.md). 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/application-models/figures/mission-and-multiton.png b/en/application-dev/application-models/figures/mission-and-multiton.png new file mode 100644 index 0000000000000000000000000000000000000000..e50f9d44d475711c17bfe56394fddd8a6c7b784c Binary files /dev/null and b/en/application-dev/application-models/figures/mission-and-multiton.png differ diff --git a/en/application-dev/application-models/figures/uiability-launch-type1.png b/en/application-dev/application-models/figures/uiability-launch-type1.png deleted file mode 100644 index c4f5aa4b9a988d8e7148b504c4dcc163961cb103..0000000000000000000000000000000000000000 Binary files a/en/application-dev/application-models/figures/uiability-launch-type1.png and /dev/null differ diff --git a/en/application-dev/application-models/figures/uiability-launch-type2.png b/en/application-dev/application-models/figures/uiability-launch-type2.png deleted file mode 100644 index 6f0e43d24f745aee41601cc48f4bc138572fbeb5..0000000000000000000000000000000000000000 Binary files a/en/application-dev/application-models/figures/uiability-launch-type2.png and /dev/null differ diff --git a/en/application-dev/application-models/hop-multi-device-collaboration.md b/en/application-dev/application-models/hop-multi-device-collaboration.md index adbaef7a927f61bc04b7b9066264f8367ef90d76..b761037182f27367e9c01488de41aaa23b6b25d2 100644 --- a/en/application-dev/application-models/hop-multi-device-collaboration.md +++ b/en/application-dev/application-models/hop-multi-device-collaboration.md @@ -5,7 +5,7 @@ Multi-device coordination involves the following scenarios: -- [Starting UIAbility and ServiceExtensionAbility Across Devices (No Data Returned)](#starting-uiability-and-serviceextensionability-across-devices-no-data-returned) +- [Starting UIAbility or ServiceExtensionAbility Across Devices (No Data Returned)](#starting-uiability-or-serviceextensionability-across-devices-no-data-returned) - [Starting UIAbility Across Devices (Data Returned)](#starting-uiability-across-devices-data-returned) @@ -31,9 +31,9 @@ The figure below shows the multi-device collaboration process. - For better user experience, you are advised to use the **want** parameter to transmit data smaller than 100 KB. -## Starting UIAbility and ServiceExtensionAbility Across Devices (No Data Returned) +## Starting UIAbility or ServiceExtensionAbility Across Devices (No Data Returned) -On device A, touch the **Start** button provided by the initiator application to start a specified UIAbility on device B. +On device A, touch the **Start** button provided by the initiator application to start a specified UIAbility or ServiceExtensionAbility on device B. ### Available APIs @@ -42,7 +42,9 @@ On device A, touch the **Start** button provided by the initiator application to | **API**| **Description**| | -------- | -------- | -| startAbility(want: Want, callback: AsyncCallback<void>): void; | Starts UIAbility and ServiceExtensionAbility. This API uses an asynchronous callback to return the result.| +| startAbility(want: Want, callback: AsyncCallback<void>): void; | Starts a UIAbility or ServiceExtensionAbility. This API uses an asynchronous callback to return the result.| +| stopServiceExtensionAbility(want: Want, callback: AsyncCallback<void>): void; | Stops a ServiceExtensionAbility. This API uses an asynchronous callback to return the result.| +| stopServiceExtensionAbility(want: Want): Promise<void>; | Stops a ServiceExtensionAbility. This API uses a promise to return the result.| ### How to Develop @@ -81,7 +83,7 @@ On device A, touch the **Start** button provided by the initiator application to } ``` -4. Set the target component parameters, and call [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) to start UIAbility or ServiceExtensionAbility. +4. Set the target component parameters, and call [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) to start a UIAbility or ServiceExtensionAbility. ```ts let want = { @@ -98,6 +100,22 @@ On device A, touch the **Start** button provided by the initiator application to }) ``` +5. Call stopServiceExtensionAbility(../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstopserviceextensionability) to stop the ServiceExtensionAbility when it is no longer required on device B. (This API cannot be used to stop a UIAbility. Users must manually stop a UIAbility through task management.) + + ```ts + let want = { + deviceId: getRemoteDeviceId(), + bundleName: 'com.example.myapplication', + abilityName: 'FuncAbility', + moduleName: 'module1', // moduleName is optional. + } + // Stop the ServiceExtensionAbility started by calling startAbility(). + this.context.stopServiceExtensionAbility(want).then(() => { + console.info("stop service extension ability success") + }).catch((err) => { + console.info("stop service extension ability err is " + JSON.stringify(err)) + }) + ``` ## Starting UIAbility Across Devices (Data Returned) @@ -121,7 +139,7 @@ On device A, touch the **Start** button provided by the initiator application to 2. Display a dialog box to ask authorization from the user when the application is started for the first time. For details, see [Requesting User Authorization](../security/accesstoken-guidelines.md#requesting-user-authorization). -3. Set the target component parameters on the initiator, and call **startAbilityForResult()** to start the target UIAbility. **data** in the asynchronous callback is used to receive the information returned by the target UIAbility to the initiator UIAbility after the target UIAbility terminates itself. For details about how to implement **getRemoteDeviceId()**, see [Starting UIAbility and ServiceExtensionAbility Across Devices (No Data Returned)](#starting-uiability-and-serviceextensionability-across-devices-no-data-returned). +3. Set the target component parameters on the initiator, and call **startAbilityForResult()** to start the target UIAbility. **data** in the asynchronous callback is used to receive the information returned by the target UIAbility to the initiator UIAbility after the target UIAbility terminates itself. For details about how to implement **getRemoteDeviceId()**, see [Starting UIAbility or ServiceExtensionAbility Across Devices (No Data Returned)](#starting-uiability-or-serviceextensionability-across-devices-no-data-returned). ```ts let want = { @@ -253,7 +271,7 @@ A system application can connect to a service on another device by calling [conn let connectionId = this.context.connectServiceExtensionAbility(want, options); ``` - For details about how to implement **getRemoteDeviceId()**, see [Starting UIAbility and ServiceExtensionAbility Across Devices (No Data Returned)](#starting-uiability-and-serviceextensionability-across-devices-no-data-returned). + For details about how to implement **getRemoteDeviceId()**, see [Starting UIAbility or ServiceExtensionAbility Across Devices (No Data Returned)](#starting-uiability-or-serviceextensionability-across-devices-no-data-returned). 5. Disconnect the connection. Use **disconnectServiceExtensionAbility()** to disconnect from the background service. @@ -313,12 +331,12 @@ The following describes how to implement multi-device collaboration through cros ```json "abilities":[{ "name": ".CalleeAbility", - "srcEntrance": "./ets/CalleeAbility/CalleeAbility.ts", + "srcEntry": "./ets/CalleeAbility/CalleeAbility.ts", "launchType": "singleton", "description": "$string:CalleeAbility_desc", "icon": "$media:icon", "label": "$string:CalleeAbility_label", - "visible": true + "exported": true }] ``` 2. Import the **UIAbility** module. @@ -438,7 +456,7 @@ The following describes how to implement multi-device collaboration through cros } ``` - For details about how to implement **getRemoteDeviceId()**, see [Starting UIAbility and ServiceExtensionAbility Across Devices (No Data Returned)](#starting-uiability-and-serviceextensionability-across-devices-no-data-returned). + For details about how to implement **getRemoteDeviceId()**, see [Starting UIAbility or ServiceExtensionAbility Across Devices (No Data Returned)](#starting-uiability-or-serviceextensionability-across-devices-no-data-returned). 5. Sends agreed parcelable data to the CalleeAbility. 1. The parcelable data can be sent to the CalleeAbility with or without a return value. The method and parcelable data must be consistent with those of the CalleeAbility. The following example describes how to send data to the CalleeAbility. diff --git a/en/application-dev/application-models/lifecycleapp-switch.md b/en/application-dev/application-models/lifecycleapp-switch.md index 892a8915bfed9927c2707364bdaffa1547f71bf6..9d89597ef5a77246ec7450261916061062d24d8d 100644 --- a/en/application-dev/application-models/lifecycleapp-switch.md +++ b/en/application-dev/application-models/lifecycleapp-switch.md @@ -1,17 +1,17 @@ # LifecycleApp Switching - | API in the FA Model| Corresponding d.ts File in the Stage Model| Corresponding API in the Stage Model| +| API in the FA Model| Corresponding d.ts File in the Stage Model| Corresponding API in the Stage Model| | -------- | -------- | -------- | | onShow?(): void; | \@ohos.window.d.ts | [on(eventType: 'windowStageEvent', callback: Callback<WindowStageEventType>): void;](../reference/apis/js-apis-window.md#onwindowstageevent9)
Listens for the switching to the [foreground](../reference/apis/js-apis-window.md#windowstageeventtype9).| | onHide?(): void; | \@ohos.window.d.ts | [on(eventType: 'windowStageEvent', callback: Callback<WindowStageEventType>): void;](../reference/apis/js-apis-window.md#onwindowstageevent9)
Listens for the switching to the [background](../reference/apis/js-apis-window.md#windowstageeventtype9).| -| onDestroy?(): void; | \@ohos.app.ability.UIAbility.d.ts | [onDestroy(): void;](../reference/apis/js-apis-app-ability-uiAbility.md#abilityondestroy) | +| onDestroy?(): void; | \@ohos.app.ability.UIAbility.d.ts | [onDestroy(): void;](../reference/apis/js-apis-app-ability-uiAbility.md#abilityondestroy) | | onCreate?(): void; | \@ohos.app.ability.UIAbility.d.ts | [onCreate(want: Want, param: AbilityConstant.LaunchParam): void;](../reference/apis/js-apis-app-ability-uiAbility.md#abilityoncreate) | | onWindowDisplayModeChanged?(isShownInMultiWindow: boolean, newConfig: resourceManager.Configuration): void; | There is no corresponding API in the stage model.| No corresponding API is provided.| | onStartContinuation?(): boolean; | There is no corresponding API in the stage model.| In the stage model, an application does not need to detect whether the continuation is successful (detected when the application initiates the continuation request). Therefore, the **onStartContinuation()** callback is deprecated.| | onSaveData?(data: Object): boolean; | \@ohos.app.ability.UIAbility.d.ts | [onContinue(wantParam : {[key: string]: any}): AbilityConstant.OnContinueResult;](../reference/apis/js-apis-app-ability-uiAbility.md#abilityoncontinue) | | onCompleteContinuation?(result: number): void; | application\ContinueCallback.d.ts | [onContinueDone(result: number): void;](../reference/apis/js-apis-distributedMissionManager.md#continuecallback) | -| onRestoreData?(data: Object): void; | \@ohos.app.ability.UIAbility.d.ts | [onCreate(want: Want, param: AbilityConstant.LaunchParam): void;](../reference/apis/js-apis-app-ability-uiAbility.md#abilityoncreate)
[onNewWant(want: Want, launchParams: AbilityConstant.LaunchParam): void;](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant)
In standard or singleton mode, the target ability completes data restoration in the **onCreate()** callback. In the callback, **launchParam.launchReason** is used to determine whether it is a continuation-based launch scenario. If it is, the data saved before continuation can be obtained from the **want** parameter.| +| onRestoreData?(data: Object): void; | \@ohos.app.ability.UIAbility.d.ts | [onCreate(want: Want, param: AbilityConstant.LaunchParam): void;](../reference/apis/js-apis-app-ability-uiAbility.md#abilityoncreate)
[onNewWant(want: Want, launchParams: AbilityConstant.LaunchParam): void;](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant)
In multiton or singleton mode, the target ability completes data restoration in the **onCreate()** callback. In the callback, **launchParam.launchReason** is used to determine whether it is a continuation-based launch scenario. If it is, the data saved before continuation can be obtained from the **want** parameter.| | onRemoteTerminated?(): void; | application\ContinueCallback.d.ts | [onContinueDone(result: number): void;](../reference/apis/js-apis-distributedMissionManager.md#continuecallback) | | onSaveAbilityState?(outState: PacMap): void; | \@ohos.app.ability.UIAbility.d.ts | [onSaveState(reason: AbilityConstant.StateType, wantParam : {[key: string]: any}): AbilityConstant.OnSaveResult;](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonsavestate) | | onRestoreAbilityState?(inState: PacMap): void; | \@ohos.app.ability.UIAbility.d.ts | [onCreate(want: Want, param: AbilityConstant.LaunchParam): void;](../reference/apis/js-apis-app-ability-uiAbility.md#abilityoncreate)
After the application is restarted, the **onCreate()** callback is triggered. In the callback, **launchParam.launchReason** is used to determine whether it is a self-recovery scenario. If it is, the data saved before the restart can be obtained from the **want** parameter.| diff --git a/en/application-dev/application-models/mission-management-launch-type.md b/en/application-dev/application-models/mission-management-launch-type.md index 267ed5011fe28cdc576e6caca85a526450110867..199de6eefead9fc056adf8d08c49f792a54a4a83 100644 --- a/en/application-dev/application-models/mission-management-launch-type.md +++ b/en/application-dev/application-models/mission-management-launch-type.md @@ -8,16 +8,19 @@ The following describes how the mission list manager manages the UIAbility insta - **singleton**: Only one UIAbility instance exists for an application. **Figure 1** Missions and singleton mode + ![mission-and-singleton](figures/mission-and-singleton.png) -- **standard**: Each time [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called, a **UIAbility** instance is created in the application process. +- **multiton**: Each time [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called, a **UIAbility** instance is created in the application process. + + **Figure 2** Missions and multiton mode - **Figure 2** Missions and standard mode - ![mission-and-standard](figures/mission-and-standard.png) + ![mission-and-multiton](figures/mission-and-multiton.png) -- **specified**: The ([onAcceptWant](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant)) method of [AbilityStage](abilitystage.md) determines whether to create an instance. +- **specified**: The ([onAcceptWant()](../reference/apis/js-apis-app-ability-abilityStage.md#abilitystageonacceptwant)) method of [AbilityStage](abilitystage.md) determines whether to create an instance. **Figure 3** Missions and specified mode + ![mission-and-specified](figures/mission-and-specified.png) diff --git a/en/application-dev/application-models/mission-set-icon-name-for-task-snapshot.md b/en/application-dev/application-models/mission-set-icon-name-for-task-snapshot.md index 9fdc03477c0552f523a0ee9c40c6fa5b8d7c4363..c98d39ff8348f330d58138db89afcc2a0d5995ca 100644 --- a/en/application-dev/application-models/mission-set-icon-name-for-task-snapshot.md +++ b/en/application-dev/application-models/mission-set-icon-name-for-task-snapshot.md @@ -8,7 +8,7 @@ Figure 1 Mission snapshot of a UIAbility ![](figures/mission-list-recent.png) -You can also use [UIAbilityContext.setMissionIcon()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionicon) and [UIAbilityContext.setMissionLabel()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionlabel) to customize the icon and name for a mission snapshot. For example, for a UIAbility instance with the launch type set to **standard**, you can configure the icon and name for each mission snapshot based on different functions. +You can also use [UIAbilityContext.setMissionIcon()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionicon) and [UIAbilityContext.setMissionLabel()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionlabel) to customize the icon and name for a mission snapshot. For example, for a UIAbility instance in multiton mode, you can configure the icon and name for each mission snapshot based on different functions. This document describes the following operations: @@ -48,4 +48,4 @@ The display effect is shown below. Figure 3 Mission snapshot name -![](figures/mission-set-task-snapshot-label.png) \ No newline at end of file +![](figures/mission-set-task-snapshot-label.png) diff --git a/en/application-dev/application-models/module-switch.md b/en/application-dev/application-models/module-switch.md index a6e532e94827198880cb772c174725b2a89c469b..9f31f892cda1a077301773a129f4f7915cd25c82 100644 --- a/en/application-dev/application-models/module-switch.md +++ b/en/application-dev/application-models/module-switch.md @@ -3,7 +3,7 @@ When switching an application from the FA model to the stage model, you must migrate the configurations under the **module** tag in the **config.json** file to the **module** tag in the **module.json5** file. -### **Table 1** module comparison +### Table 1 module Comparison | Field Name in the FA Model| Field Description| Field Name in the Stage Model| Difference| | -------- | -------- | -------- | -------- | @@ -21,13 +21,13 @@ When switching an application from the FA model to the stage model, you must mig | shortcuts | Shortcuts of the application.| shortcut_config.json| In the stage model, the **shortcut_config.json** file is defined in **resources/base/profile** in the development view.| | reqPermissions | Permissions that the application requests from the system when it is running.| requestPermissions | The field name is changed.| | colorMode | Color mode of the application.| / | This configuration is not supported in the stage model.| -| distroFilter | Distribution rules of the application.| distroFilter_config.json| In the stage model, the **distroFilter_config.json** file is defined in **resources/base/profile** in the development view.| +| distributionFilter | Distribution rules of the application.| distroFilter_config.json| In the stage model, the **distroFilter_config.json** file is defined in **resources/base/profile** in the development view.| | reqCapabilities | Device capabilities required for running the application.| / | This configuration is not supported in the stage model.| | commonEvents | Common events.| common_event_config.json| In the stage model, the **common_event_config.json** file is defined in **resources/base/profile** in the development view.| | entryTheme | Keyword of an OpenHarmony internal theme.| / | This configuration is not supported in the stage model.| -### Table 2 metaData comparison +### Table 2 metaData Comparison | Field Name Under metaData in the FA Model| Field Description| Field Name Under metaData in the Stage Model| Difference| | -------- | -------- | -------- | -------- | @@ -35,7 +35,7 @@ When switching an application from the FA model to the stage model, you must mig | results | Metadata of the ability return value.| / | This configuration is not supported in the stage model.| | customizeData | Custom metadata of the parent component. **parameters** and **results** cannot be configured in **application**.| metadata | See [Table 3](#table-3-comparison-between-customizedata-under-metadata-in-the-fa-model-and-metadata-in-the-stage-model).| -### Table 3 Comparison between customizeData under metaData in the FA model and metadata in the stage model +### Table 3 Comparison Between customizeData Under metaData in the FA Model and metadata in the Stage Model | Field Name Under customizeData in metaData in the FA Model| Field Description| Field Name Under metaData in the Stage Model| Difference| | -------- | -------- | -------- | -------- | @@ -44,14 +44,14 @@ When switching an application from the FA model to the stage model, you must mig | extra | Format of the current custom data. The value is the resource value of **extra**.| resource | The field name is changed. For details, see [Table 4](#table 4-metadata-examples).| -### Table 4 metaData examples +### Table 4 metaData Examples | Example in the FA Model| Example in the Stage Model| | -------- | -------- | | "meteData": {
"customizeDate": [{
"name": "label",
"value": "string",
"extra": "$string:label",
}]
} | "meteData": [{
"name": "label",
"value": "string",
"resource": "$string:label",
}] | -### Table 5 abilities comparison +### Table 5 abilities Comparison | Field Name Under abilities in the FA Model| Field Description| Field Name Under abilities in the Stage Model| Difference| | -------- | -------- | -------- | -------- | @@ -71,5 +71,5 @@ When switching an application from the FA model to the stage model, you must mig | formsEnabled | Whether the ability can provide widgets.| / | This configuration is not supported in the stage model.| | forms | Information about the widgets used by the ability. This field is valid only when **formsEnabled** is set to **true**.| form_config.json| In the stage model, the **form_config.json** file is defined in **resources/base/profile** in the development view.| | srcLanguage | Programming language used to develop the ability.| / | This configuration is not supported in the stage model.| -| srcPath | Path of the JS component code corresponding to the ability.| srcEntrance | Path of the JS code corresponding to the ability.| +| srcPath | Path of the JS component code corresponding to the ability.| srcEntry | Path of the JS code corresponding to the ability.| | uriPermission | Application data that the ability can access.| / | This configuration is not supported in the stage model.| diff --git a/en/application-dev/application-models/pageability-launch-type.md b/en/application-dev/application-models/pageability-launch-type.md index 5241a7cabefbf3e68e6a3f413b8892ef5f6ff8d3..3b75ff6a60899f19f08aad5235fb3dc49632cb01 100644 --- a/en/application-dev/application-models/pageability-launch-type.md +++ b/en/application-dev/application-models/pageability-launch-type.md @@ -5,10 +5,10 @@ Depending on the launch type, the action performed when the PageAbility starts d **Table 1** PageAbility launch types -| Launch Type| Description| -| -------- | -------- | -| singleton | Each time **startAbility()** is called, if an ability instance of this type already exists in the application process, the instance is reused. There is only one ability instance of this type in **Recents**.
A typical scenario is as follows: When a user opens a video playback application and watches a video, returns to the home screen, and opens the video playback application again, the video that the user watched before returning to the home screen is still played.| -| standard | Default type. Each time **startAbility()** is called, a new ability instance is created in the application process. Multiple ability instances of this type are displayed in **Recents**.
A typical scenario is as follows: When a user opens a document application and touches **New**, a new document task is created. Multiple new document missions are displayed in **Recents**.| +| Launch Type| Meaning | Description| +| -------- | -------- | -------- | +| singleton | Singleton mode| Each time **startAbility()** is called, if an ability instance of this type already exists in the application process, the instance is reused. There is only one ability instance of this type in **Recents**.
A typical scenario is as follows: When a user opens a video playback application and watches a video, returns to the home screen, and opens the video playback application again, the video that the user watched before returning to the home screen is still played.| +| standard | Multiton mode| Default type. Each time **startAbility()** is called, a new ability instance is created in the application process. Multiple ability instances of this type are displayed in **Recents**.
A typical scenario is as follows: When a user opens a document application and touches **New**, a new document task is created. Multiple new document missions are displayed in **Recents**.| You can set **launchType** in the **config.json** file to configure the launch type. The sample code is as follows: @@ -19,8 +19,8 @@ You can set **launchType** in the **config.json** file to configure the launch t // ... "abilities": [ { - // singleton mode. - // standard mode. + // singleton means the singleton mode. + // standard means the multiton mode. "launchType": "standard", // ... } @@ -30,7 +30,8 @@ You can set **launchType** in the **config.json** file to configure the launch t ``` -When the PageAbility is started for the first time (either in standard or singleton mode), the [PageAbility lifecycle callbacks](pageability-lifecycle.md#table13118194914476) are triggered. When it is not started for the first time in singleton mode, the **onNewWant()** callback (as described in the table below) is triggered, but the **onCreate()** callback is not. +When the PageAbility is started in multiton mode or it is started in singleton mode for the first time, the [PageAbility lifecycle callbacks](pageability-lifecycle.md#table13118194914476) are triggered. When it is not started for the first time in singleton mode, the **onNewWant()** callback (as described in the table below) is triggered, but the **onCreate()** callback is not. + **Table 2** Callbacks specific to the singleton mode diff --git a/en/application-dev/application-models/process-model-stage.md b/en/application-dev/application-models/process-model-stage.md index bbfa0602aecb127c5e484f0ebbdcb166f81310f7..03da480722de124a1ede58da52e74cd48c5f23f0 100644 --- a/en/application-dev/application-models/process-model-stage.md +++ b/en/application-dev/application-models/process-model-stage.md @@ -15,7 +15,8 @@ The OpenHarmony process model is shown below. > NOTE > -> You can create ServiceExtensionAbility and DataShareExtensionAbility only for system applications. +> - You can create ServiceExtensionAbility and DataShareExtensionAbility only for system applications. +> - To view information about all running processes, run the **hdc shell** command to enter the shell CLI of the device, and run the **ps -ef** command. A system application can apply for multi-process permissions (as shown in the following figure) and configure a custom process for an HAP. UIAbility, DataShareExtensionAbility, and ServiceExtensionAbility in the HAP run in the custom process. Different HAPs run in different processes by configuring different process names. diff --git a/en/application-dev/application-models/redirection-rules.md b/en/application-dev/application-models/redirection-rules.md index d7456653640942bca333a28f7f6d5262ec4d63f3..4e9f65a8b3439fe4dde4761fbcb3d341151ba4f3 100644 --- a/en/application-dev/application-models/redirection-rules.md +++ b/en/application-dev/application-models/redirection-rules.md @@ -33,4 +33,4 @@ To enable an ability to be called by any application, configure the **config.jso ``` -If the ability contains **skills**, you are advised to set **visible** to **true** so that the ability can be [implicitly started](explicit-implicit-want-mappings.md#matching-rules-of-implicit-want) by other applications. If this attribute is set to **false**, the system returns **PERMISSION_DENIED** when other applications attempt to start the ability. In this case, a system application can request the [START_INVISIBLE_ABILITY](../security/permission-list.md) permission to start the ability. Example abilities with **visible** set to **false** are home screen, voice assistant, or search assistant. +If the ability contains **skills**, you are advised to set **visible** to **true** so that the ability can be [implicitly started](explicit-implicit-want-mappings.md) by other applications. If this attribute is set to **false**, the system returns **PERMISSION_DENIED** when other applications attempt to start the ability. In this case, a system application can request the [START_INVISIBLE_ABILITY](../security/permission-list.md) permission to start the ability. Example abilities with **visible** set to **false** are home screen, voice assistant, or search assistant. diff --git a/en/application-dev/application-models/serviceextensionability.md b/en/application-dev/application-models/serviceextensionability.md index 9ff7a0ae5d6df7574da19565c81411236dba3dda..2e9aaeb48100d86d0cd1c7a0e69ea01bf4ef2340 100644 --- a/en/application-dev/application-models/serviceextensionability.md +++ b/en/application-dev/application-models/serviceextensionability.md @@ -1,125 +1,151 @@ # ServiceExtensionAbility +## Overview -[ServiceExtensionAbility](../reference/apis/js-apis-app-ability-serviceExtensionAbility.md) is an ExtensionAbility component of the service type that provides extension capabilities related to background services. +[ServiceExtensionAbility](../reference/apis/js-apis-app-ability-serviceExtensionAbility.md) is an ExtensionAbility component of the SERVICE type that provides capabilities related to background services. It holds an internal [ServiceExtensionContext](../reference/apis/js-apis-inner-application-serviceExtensionContext.md), through which a variety of APIs are provided for external systems. +In this document, the started ServiceExtensionAbility component is called the server, and the component that starts ServiceExtensionAbility is called the client. -ServiceExtensionAbility can be started or connected by other application components to process transactions in the background based on the request of the caller. System applications can call the [startServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#abilitycontextstartserviceextensionability) method to start background services or call the [connectServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#abilitycontextconnectserviceextensionability) method to connect to background services. Third-party applications can call only **connectServiceExtensionAbility()** to connect to background services. The differences between starting and connecting to background services are as follows: +A ServiceExtensionAbility can be started or connected by other components to process transactions in the background based on the request of the caller. System applications can call the [startServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartserviceextensionability) method to start background services or call the [connectServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectserviceextensionability) method to connect to background services. Third-party applications can call only **connectServiceExtensionAbility()** to connect to background services. The differences between starting and connecting to background services are as follows: +- **Starting**: In the case that AbilityA starts ServiceB, they are weakly associated. After AbilityA exits, ServiceB can still exist. -- In the case that AbilityA starts ServiceB, they are weakly associated. After AbilityA exits, ServiceB can still exist. +- **Connecting**: In the case that AbilityA connects to ServiceB, they are strongly associated. After AbilityA exits, ServiceB also exits. -- In the case that AbilityA connects to ServiceB, they are strongly associated. After AbilityA exits, ServiceB also exits. +Note the following: +- If a ServiceExtensionAbility is started only by means of connecting, its lifecycle is controlled by the client. A new connection is set up each time the client calls the [connectServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectserviceextensionability) method. When the client exits or calls the [disconnectServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextdisconnectserviceextensionability) method, the connection is disconnected. After all connections are disconnected, the ServiceExtensionAbility automatically exits. -Each type of ExtensionAbility has its own context. ServiceExtensionAbility has [ServiceExtensionContext](../reference/apis/js-apis-inner-application-serviceExtensionContext.md). In this document, the started ServiceExtensionAbility component is called the server, and the component that starts ServiceExtensionAbility is called the client. - - -This topic describes how to use ServiceExtensionAbility in the following scenarios: - - -- [Implementing a Background Service (for System Applications Only)](#implementing-a-background-service-for-system-applications-only) - -- [Starting a Background Service (for System Applications Only)](#starting-a-background-service-for-system-applications-only) - -- [Connecting to a Background Service](#connecting-to-a-background-service) - +- Once a ServiceExtensionAbility is started by means of starting, it will not exit automatically. System applications can call the [stopServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstopserviceextensionability) method to stop it. > **NOTE** -> - OpenHarmony does not support third-party applications in implementing ServiceExtensionAbility. If you want to implement transaction processing in the background, use background tasks. For details, see [Background Task](../task-management/background-task-overview.md). -> +> +> - Currently, third-party applications cannot implement ServiceExtensionAbility. If you want to implement transaction processing in the background, use background tasks. For details, see [Background Task](../task-management/background-task-overview.md). > - UIAbility of a third-party application can connect to ServiceExtensionAbility provided by the system through the context. -> > - Third-party applications can connect to ServiceExtensionAbility provided by the system only when they gain focus in the foreground. - -## Implementing a Background Service (for System Applications Only) +## Lifecycle [ServiceExtensionAbility](../reference/apis/js-apis-app-ability-serviceExtensionAbility.md) provides the callbacks **onCreate()**, **onRequest()**, **onConnect()**, **onDisconnect()**, and **onDestory()**. Override them as required. The following figure shows the lifecycle of ServiceExtensionAbility. - **Figure 1** ServiceExtensionAbility lifecycle +**Figure 1** ServiceExtensionAbility lifecycle ![ServiceExtensionAbility-lifecycle](figures/ServiceExtensionAbility-lifecycle.png) - **onCreate** - - This callback is triggered when a service is created for the first time. You can perform initialization operations, for example, registering a common event listener. + + This callback is triggered when a ServiceExtensionAbility is created for the first time. You can perform initialization operations, for example, registering a common event listener. > **NOTE** > - > If a service has been created, starting it again does not trigger the **onCreate()** callback. + > If a ServiceExtensionAbility has been created, starting it again does not trigger the **onCreate()** callback. - **onRequest** - - This callback is triggered when another component calls the **startServiceExtensionAbility()** method to start the service. After being started, the service runs in the background. + + This callback is triggered when another component calls the [startServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartserviceextensionability) method to start a ServiceExtensionAbility. After being started, the ServiceExtensionAbility runs in the background. This callback is triggered each time the [startServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartserviceextensionability) method is called. - **onConnect** - - This callback is triggered when another component calls the **connectServiceExtensionAbility()** method to connect to the service. In this method, a remote proxy object (IRemoteObject) is returned, through which the client communicates with the server by means of RPC. + + This callback is triggered when another component calls the [connectServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectserviceextensionability) method to connect to a ServiceExtensionAbility. In this method, a remote proxy object (IRemoteObject) is returned, through which the client communicates with the server by means of RPC. At the same time, the system stores the remote proxy object (IRemoteObject). If another component calls the [connectServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectserviceextensionability) method to connect to this ServiceExtensionAbility, the system directly returns the saved remote proxy object (IRemoteObject) and does not trigger the callback. - **onDisconnect** - - This callback is triggered when a component calls the **disconnectServiceExtensionAbility()** method to disconnect from the service. + + This callback is triggered when the last connection is disconnected. A connection is disconnected when the client exits or the [disconnectServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextdisconnectserviceextensionability) method is called. - **onDestroy** - This callback is triggered when the service is no longer used and the instance is ready for destruction. You can clear resources in this callback, for example, deregister the listener. + This callback is triggered when ServiceExtensionAbility is no longer used and the instance is ready for destruction. You can clear resources in this callback, for example, deregister the listener. +## Implementing a Background Service (for System Applications Only) -## How to Develop +### Preparations -To implement a background service, manually create a ServiceExtensionAbility component in DevEco Studio. The procedure is as follows: +Only system applications can implement ServiceExtensionAbility. You must make the following preparations before development: -1. In the **ets** directory of the **Module** project, right-click and choose **New > Directory** to create a directory named **serviceextability**. +- **Switching to the full SDK**: All APIs related to ServiceExtensionAbility are marked as system APIs and hidden by default. Therefore, you must manually obtain the full SDK from the mirror and switch to it in DevEco Studio. For details, see [Guide to Switching to Full SDK](../quick-start/full-sdk-switch-guide.md). -2. In the **serviceextability** directory, right-click and choose **New > TypeScript File** to create a file named **ServiceExtAbility.ts**. +- **Requesting the AllowAppUsePrivilegeExtension privilege**: Only applications with the **AllowAppUsePrivilegeExtension** privilege can develop ServiceExtensionAbility. For details about how to request the privilege, see [Application Privilege Configuration Guide](../../device-dev/subsystems/subsys-app-privilege-config-guide.md). -3. Open the **ServiceExtAbility.ts** file, import the [RPC module](../reference/apis/js-apis-rpc.md), and reload the **onRemoteMessageRequest()** method to receive messages from the client and return the processing result to the client. **REQUEST_VALUE** is used to verify the service request code sent by the client. - - ```ts - import rpc from '@ohos.rpc'; - - const REQUEST_CODE = 99; - - class StubTest extends rpc.RemoteObject { - constructor(des) { - super(des); - } - - // Receive a message from the client and return the processing result to the client. - onRemoteMessageRequest(code, data, reply, option) { - if (code === REQUEST_CODE) { - // Receive data from the client. - // If the client calls data.writeInt() multiple times to write multiple pieces of data, the server can call data.readInt() multiple times to receive all the data. - let optFir = data.readInt(); - let optSec = data.readInt(); - // The server returns the data processing result to the client. - // In the example, the server receives two pieces of data and returns the sum of the two pieces of data to the client. - reply.writeInt(optFir + optSec); - } - return true; - } - - // Send messages to the client in synchronous or asynchronous mode. - sendRequest(code, data, reply, options) { - return null; - } - } - ``` +### Defining IDL Interfaces + +As a background service, ServiceExtensionAbility needs to provide interfaces that can be called by external systems. You can define the interfaces in IDL files and use the [IDL tool](../IDL/idl-guidelines.md) to generate proxy and stub files. The following demonstrates how to define a file named **IIdlServiceExt.idl**: + +```cpp +interface OHOS.IIdlServiceExt { + int ProcessData([in] int data); + void InsertDataToMap([in] String key, [in] int val); +} +``` + +Create the **IdlServiceExt** directory in the **ets** directory corresponding to the module of the DevEco Studio project, and copy the files generated by the [IDL tool](../IDL/idl-guidelines.md) to this directory. Then create a file named **idl_service_ext_impl.ts** to implement the IDL interfaces. + +``` +├── ets +│ ├── IdlServiceExt +│ │ ├── i_idl_service_ext.ts # File generated. +│ │ ├── idl_service_ext_proxy.ts # File generated. +│ │ ├── idl_service_ext_stub.ts # File generated. +│ │ ├── idl_service_ext_impl.ts # Custom file used to implement IDL interfaces. +│ └ +└ +``` + +An example of **idl_service_ext_impl.ts** is as follows: + +```ts +import {processDataCallback} from './i_idl_service_ext'; +import {insertDataToMapCallback} from './i_idl_service_ext'; +import IdlServiceExtStub from './idl_service_ext_stub'; + +const ERR_OK = 0; +const TAG: string = "[IdlServiceExtImpl]"; + +// You need to implement interfaces in this type. +export default class ServiceExtImpl extends IdlServiceExtStub { + processData(data: number, callback: processDataCallback): void { + // Implement service logic. + console.info(TAG, `processData: ${data}`); + callback(ERR_OK, data + 1); + } + + insertDataToMap(key: string, val: number, callback: insertDataToMapCallback): void { + // Implement service logic. + console.log(TAG, `insertDataToMap, key: ${key} val: ${val}`); + callback(ERR_OK); + } +} +``` + +### Creating a ServiceExtensionAbility + +To manually create a ServiceExtensionAbility in the DevEco Studio project, perform the following steps: + +1. In the **ets** directory of the **Module** project, right-click and choose **New > Directory** to create a directory named **ServiceExtAbility**. + +2. In the **ServiceExtAbility** directory, right-click and choose **New > TypeScript File** to create a file named **ServiceExtAbility.ts**. + + ``` + ├── ets + │ ├── IdlServiceExt + │ │ ├── i_idl_service_ext.ts # File generated. + │ │ ├── idl_service_ext_proxy.ts # File generated. + │ │ ├── idl_service_ext_stub.ts # File generated. + │ │ ├── idl_service_ext_impl.ts # Custom file used to implement IDL interfaces. + │ ├── ServiceExtAbility + │ │ ├── ServiceExtAbility.ts + └ + ``` + +3. In the **ServiceExtAbility.ts** file, add the dependency package for importing ServiceExtensionAbility. Customize a class that inherits from ServiceExtensionAbility and implement the lifecycle callbacks, and return the previously defined **ServiceExtImpl** object in the **onConnect** lifecycle callback. -4. In the **ServiceExtAbility.ts** file, add the dependency package for importing ServiceExtensionAbility. Customize a class that inherits from ServiceExtensionAbility and add the required lifecycle callbacks. - ```ts import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility'; - import rpc from '@ohos.rpc'; - - const TAG: string = "[Example].[Entry].[ServiceExtAbility]"; - const REQUEST_CODE = 99; + import ServiceExtImpl from '../IdlServiceExt/idl_service_ext_impl'; - class StubTest extends rpc.RemoteObject { - // ... - } + const TAG: string = "[ServiceExtAbility]"; export default class ServiceExtAbility extends ServiceExtensionAbility { + serviceExtImpl = new ServiceExtImpl("ExtImpl"); + onCreate(want) { console.info(TAG, `onCreate, want: ${want.abilityName}`); } @@ -130,7 +156,8 @@ To implement a background service, manually create a ServiceExtensionAbility com onConnect(want) { console.info(TAG, `onConnect, want: ${want.abilityName}`); - return new StubTest("test"); + // Return the ServiceExtImpl object, through which the client can communicate with the ServiceExtensionAbility. + return this.serviceExtImpl; } onDisconnect(want) { @@ -143,8 +170,8 @@ To implement a background service, manually create a ServiceExtensionAbility com } ``` -5. Register ServiceExtensionAbility in the [module.json5 file](../quick-start/module-configuration-file.md) corresponding to the **Module** project. Set **type** to **"service"** and **srcEntrance** to the code path of the ExtensionAbility component. - +4. Register ServiceExtensionAbility in the [module.json5 file](../quick-start/module-configuration-file.md) corresponding to the **Module** project. Set **type** to **"service"** and **srcEntry** to the code path of the ServiceExtensionAbility component. + ```json { "module": { @@ -155,15 +182,14 @@ To implement a background service, manually create a ServiceExtensionAbility com "icon": "$media:icon", "description": "service", "type": "service", - "visible": true, - "srcEntrance": "./ets/serviceextability/ServiceExtAbility.ts" + "exported": true, + "srcEntry": "./ets/ServiceExtAbility/ServiceExtAbility.ts" } ] } } ``` - ## Starting a Background Service (for System Applications Only) A system application uses the [startServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#abilitycontextstartserviceextensionability) method to start a background service. The [onRequest()](../reference/apis/js-apis-app-ability-serviceExtensionAbility.md#serviceextensionabilityonrequest) callback is invoked, and the **Want** object passed by the caller is received through the callback. After the background service is started, its lifecycle is independent of that of the client. In other words, even if the client is destroyed, the background service can still run. Therefore, the background service must be stopped by calling [terminateSelf()](../reference/apis/js-apis-inner-application-serviceExtensionContext.md#serviceextensioncontextterminateself) when its work is complete. Alternatively, another component can call [stopServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#abilitycontextstopserviceextensionability) to stop the background service. @@ -173,7 +199,7 @@ A system application uses the [startServiceExtensionAbility()](../reference/apis > [startServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#abilitycontextstartserviceextensionability), [stopServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#abilitycontextstopserviceextensionability), and [terminateSelf()](../reference/apis/js-apis-inner-application-serviceExtensionContext.md#serviceextensioncontextterminateself) of ServiceExtensionContext are system APIs and cannot be called by third-party applications. 1. Start a new ServiceExtensionAbility in a system application. For details about how to obtain the context, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability). - + ```ts let want = { "deviceId": "", @@ -188,7 +214,7 @@ A system application uses the [startServiceExtensionAbility()](../reference/apis ``` 2. Stop ServiceExtensionAbility in the system application. - + ```ts let want = { "deviceId": "", @@ -203,7 +229,7 @@ A system application uses the [startServiceExtensionAbility()](../reference/apis ``` 3. ServiceExtensionAbility stops itself. - + ```ts // this is the current ServiceExtensionAbility component. this.context.terminateSelf().then(() => { @@ -213,35 +239,71 @@ A system application uses the [startServiceExtensionAbility()](../reference/apis }) ``` - > **NOTE** > > Background services can run in the background for a long time. To minimize resource usage, destroy it in time when a background service finishes the task of the requester. A background service can be stopped in either of the following ways: > > - The background service calls the [terminateSelf()](../reference/apis/js-apis-inner-application-serviceExtensionContext.md#serviceextensioncontextterminateself) method to automatically stop itself. -> > - Another component calls the [stopServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#abilitycontextstopserviceextensionability) method to stop the background service. -> > After either method is called, the system destroys the background service. - ## Connecting to a Background Service -Either a system application or a third-party application can connect to a service (service specified in the **Want** object) through [connectServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#abilitycontextconnectserviceextensionability). The [onConnect()](../reference/apis/js-apis-app-ability-serviceExtensionAbility.md#serviceextensionabilityonconnect) callback is invoked, and the **Want** object passed by the caller is received through the callback. In this way, a persistent connection is established. +Either a system application or a third-party application can connect to a ServiceExtensionAbility (specified in the **Want** object) through [connectServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#abilitycontextconnectserviceextensionability). The [onConnect()](../reference/apis/js-apis-app-ability-serviceExtensionAbility.md#serviceextensionabilityonconnect) callback is invoked, and the **Want** object passed by the caller is received through the callback. In this way, a persistent connection is established. The ServiceExtensionAbility component returns an IRemoteObject in the **onConnect()** callback. Through this IRemoteObject, you can define communication interfaces for RPC interaction between the client and server. Multiple clients can connect to the same background service at the same time. After a client finishes the interaction, it must call [disconnectServiceExtensionAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#abilitycontextdisconnectserviceextensionability) to disconnect from the service. If all clients connected to a background service are disconnected, the system destroys the service. - Call **connectServiceExtensionAbility()** to establish a connection to a background service. For details about how to obtain the context, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability). ```ts - import rpc from '@ohos.rpc'; - - const REQUEST_CODE = 99; let want = { "deviceId": "", "bundleName": "com.example.myapplication", "abilityName": "ServiceExtAbility" }; + let options = { + onConnect(elementName, remote) { + /* The input parameter remote is the object returned by ServiceExtensionAbility in the onConnect lifecycle callback. + * This object is used for communication with ServiceExtensionAbility. For details, see the section below. + */ + console.info('onConnect callback'); + if (remote === null) { + console.info(`onConnect remote is null`); + return; + } + }, + onDisconnect(elementName) { + console.info('onDisconnect callback') + }, + onFailed(code) { + console.info('onFailed callback') + } + } + // The ID returned after the connection is set up must be saved. The ID will be passed for service disconnection. + let connectionId = this.context.connectServiceExtensionAbility(want, options); + ``` + +- Use **disconnectServiceExtensionAbility()** to disconnect from the background service. + + ```ts + // connectionId is returned when connectServiceExtensionAbility is called and needs to be manually maintained. + this.context.disconnectServiceExtensionAbility(connectionId).then((data) => { + console.info('disconnectServiceExtensionAbility success'); + }).catch((error) => { + console.error('disconnectServiceExtensionAbility failed'); + }) + ``` + +## Communication Between the Client and Server + +After obtaining the [rpc.RemoteObject](../reference/apis/js-apis-rpc.md#iremoteobject) object from the **onConnect()** callback, the client can communicate with ServiceExtensionAbility in either of the following ways: + +- Using the IDL interface provided by the server for communication (recommended) + + ```ts + // The client needs to import idl_service_ext_proxy.ts provided by the server for external systems to the local project. + import IdlServiceExtProxy from '../IdlServiceExt/idl_service_ext_proxy'; + let options = { onConnect(elementName, remote) { console.info('onConnect callback'); @@ -249,23 +311,54 @@ The ServiceExtensionAbility component returns an IRemoteObject in the **onConnec console.info(`onConnect remote is null`); return; } + let serviceExtProxy = new IdlServiceExtProxy(remote); + // Communication is carried out by interface calling, without exposing RPC details. + serviceExtProxy.processData(1, (errorCode, retVal) => { + console.log(`processData, errorCode: ${errorCode}, retVal: ${retVal}`); + }); + serviceExtProxy.insertDataToMap('theKey', 1, (errorCode) => { + console.log(`insertDataToMap, errorCode: ${errorCode}`); + }) + }, + onDisconnect(elementName) { + console.info('onDisconnect callback') + }, + onFailed(code) { + console.info('onFailed callback') + } + } + ``` + +- Calling [sendMessageRequest](../reference/apis/js-apis-rpc.md#sendmessagerequest9) to send messages to the server (not recommended) + + ```ts + import rpc from '@ohos.rpc'; + + const REQUEST_CODE = 1; + let options = { + onConnect(elementName, remote) { + console.info('onConnect callback'); + if (remote === null) { + console.info(`onConnect remote is null`); + return; + } + // Directly call the RPC interface to send messages to the server. The client needs to serialize the input parameters and deserialize the return values. The process is complex. let option = new rpc.MessageOption(); - let data = new rpc.MessageParcel(); - let reply = new rpc.MessageParcel(); + let data = new rpc.MessageSequence(); + let reply = new rpc.MessageSequence(); data.writeInt(100); - data.writeInt(200); - + // @param code Indicates the service request code sent by the client. - // @param data Indicates the {@link MessageParcel} object sent by the client. + // @param data Indicates the {@link MessageSequence} object sent by the client. // @param reply Indicates the response message object sent by the remote service. // @param options Specifies whether the operation is synchronous or asynchronous. // // @return Returns {@code true} if the operation is successful; returns {@code false} otherwise. - remote.sendRequest(REQUEST_CODE, data, reply, option).then((ret) => { + remote.sendMessageRequest(REQUEST_CODE, data, reply, option).then((ret) => { let msg = reply.readInt(); - console.info(`sendRequest ret:${ret} msg:${msg}`); + console.info(`sendMessageRequest ret:${ret} msg:${msg}`); }).catch((error) => { - console.info('sendRequest failed'); + console.info('sendMessageRequest failed'); }); }, onDisconnect(elementName) { @@ -275,18 +368,90 @@ The ServiceExtensionAbility component returns an IRemoteObject in the **onConnec console.info('onFailed callback') } } - // The ID returned after the connection is set up must be saved. The ID will be passed for service disconnection. - let connectionId = this.context.connectServiceExtensionAbility(want, options); ``` -- Use **disconnectServiceExtensionAbility()** to disconnect from the background service. - +## Client Identity Verification by the Server + +When ServiceExtensionAbility is used to provide sensitive services, the client identity must be verified. You can implement the verification on the stub of the IDL interface. For details about the IDL interface implementation, see [Defining IDL Interfaces](#defining-idl-interfaces). Two verification modes are recommended: + +- **Verifying the client identity based on callerUid** + + Call the [getCallingUid()](../reference/apis/js-apis-rpc.md#getcallinguid) method to obtain the UID of the client, and then call the [getBundleNameByUid()](../reference/apis/js-apis-bundleManager.md#bundlemanagergetbundlenamebyuid) method to obtain the corresponding bundle name. In this way, the client identify is verified. Note that [getBundleNameByUid()](../reference/apis/js-apis-bundleManager.md#bundlemanagergetbundlenamebyuid) is asynchronous, and therefore the server cannot return the verification result to the client. This verification mode applies when the client sends an asynchronous task execution request to the server. The sample code is as follows: + ```ts - let connectionId = 1 // ID returned when the service is connected through connectServiceExtensionAbility. - this.context.disconnectServiceExtensionAbility(connectionId).then((data) => { - console.info('disconnectServiceExtensionAbility success'); - }).catch((error) => { - console.error('disconnectServiceExtensionAbility failed'); - }) + import rpc from '@ohos.rpc'; + import bundleManager from '@ohos.bundle.bundleManager'; + import {processDataCallback} from './i_idl_service_ext'; + import {insertDataToMapCallback} from './i_idl_service_ext'; + import IdlServiceExtStub from './idl_service_ext_stub'; + + const ERR_OK = 0; + const ERR_DENY = -1; + const TAG: string = "[IdlServiceExtImpl]"; + + export default class ServiceExtImpl extends IdlServiceExtStub { + processData(data: number, callback: processDataCallback): void { + console.info(TAG, `processData: ${data}`); + + let callerUid = rpc.IPCSkeleton.getCallingUid(); + bundleManager.getBundleNameByUid(callerUid).then((callerBundleName) => { + console.info(TAG, 'getBundleNameByUid: ' + callerBundleName); + // Identify the bundle name of the client. + if (callerBundleName != 'com.example.connectextapp') { // The verification fails. + console.info(TAG, 'The caller bundle is not in whitelist, reject'); + return; + } + // The verification is successful, and service logic is executed normally. + }).catch(err => { + console.info(TAG, 'getBundleNameByUid failed: ' + err.message); + }); + } + + insertDataToMap(key: string, val: number, callback: insertDataToMapCallback): void { + // Implement service logic. + console.log(TAG, `insertDataToMap, key: ${key} val: ${val}`); + callback(ERR_OK); + } + } + ``` + +- **Verifying the client identity based on callerTokenId** + + Call the [getCallingTokenId()](../reference/apis/js-apis-rpc.md#getcallingtokenid) method to obtain the token ID of the client, and then call the [verifyAccessTokenSync()](../reference/apis/js-apis-abilityAccessCtrl.md#verifyaccesstokensync) method to check whether the client has a specific permission. Currently, OpenHarmony does not support permission customization. Therefore, only [system-defined permissions](../security/permission-list.md) can be verified. The sample code is as follows: + + ```ts + import rpc from '@ohos.rpc'; + import abilityAccessCtrl from '@ohos.abilityAccessCtrl'; + import {processDataCallback} from './i_idl_service_ext'; + import {insertDataToMapCallback} from './i_idl_service_ext'; + import IdlServiceExtStub from './idl_service_ext_stub'; + + const ERR_OK = 0; + const ERR_DENY = -1; + const TAG: string = "[IdlServiceExtImpl]"; + + export default class ServiceExtImpl extends IdlServiceExtStub { + processData(data: number, callback: processDataCallback): void { + console.info(TAG, `processData: ${data}`); + + let callerTokenId = rpc.IPCSkeleton.getCallingTokenId(); + let accessManger = abilityAccessCtrl.createAtManager(); + // The permission to be verified varies depending on the service requirements. ohos.permission.SET_WALLPAPER is only an example. + let grantStatus = + accessManger.verifyAccessTokenSync(callerTokenId, "ohos.permission.SET_WALLPAPER"); + if (grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_DENIED) { + console.info(TAG, `PERMISSION_DENIED`); + callback(ERR_DENY, data); // The verification fails and an error is returned. + return; + } + callback(ERR_OK, data + 1); // The verification is successful, and service logic is executed normally. + } + + insertDataToMap(key: string, val: number, callback: insertDataToMapCallback): void { + // Implement service logic. + console.log(TAG, `insertDataToMap, key: ${key} val: ${val}`); + callback(ERR_OK); + } + } ``` diff --git a/en/application-dev/application-models/start-page.md b/en/application-dev/application-models/start-page.md index 58966d93cba037eaad141caaed0feaaaa672cde1..5831ea0c6f6b6fa9d954134ef723f70e925e3ed7 100644 --- a/en/application-dev/application-models/start-page.md +++ b/en/application-dev/application-models/start-page.md @@ -70,7 +70,7 @@ struct Index { ``` -When the launch type of a PageAbility is set to **standard** or when the PageAbility with the launch type set to **singleton** is started for the first time, you can use the **parameters** parameter in **want** to transfer the pages information and use the **startAbility()** method to start the PageAbility. For details about the launch type, see [PageAbility Launch Type](pageability-launch-type.md). The target PageAbility can use the **featureAbility.getWant()** method in **onCreate** to obtain the **want** parameter, and then call **router.push** to start a specified page. +When a PageAbility in multiton mode is started or when the PageAbility in singleton mode is started for the first time, you can use the **parameters** parameter in **want** to transfer the pages information and use the **startAbility()** method to start the PageAbility. For details about the launch type, see [PageAbility Launch Type](pageability-launch-type.md). The target PageAbility can use the **featureAbility.getWant()** method in **onCreate** to obtain the **want** parameter, and then call **router.push** to start a specified page. When a user touches the button on the page of the caller PageAbility, the **startAbility()** method is called to start the target PageAbility. The **want** parameter in **startAbility()** carries the specified page information. diff --git a/en/application-dev/application-models/thread-model-stage.md b/en/application-dev/application-models/thread-model-stage.md index deaab60b7bd7549dcb96bc00d7896d5c67e5c5d2..4ca9fb3ed369f78cf12054c7b6da085b8640b1db 100644 --- a/en/application-dev/application-models/thread-model-stage.md +++ b/en/application-dev/application-models/thread-model-stage.md @@ -2,19 +2,14 @@ For an OpenHarmony application, each process has a main thread to provide the following functionalities: -- Manage other threads. - -- Enable multiple UIAbility components of the same application to share the same main thread. - -- Distribute input events. - - Draw the UI. - -- Invoke application code callbacks (event processing and lifecycle callbacks). - +- Manage the ArkTS engine instance of the main thread so that multiple UIAbility components can run on it. +- Manage ArkTS engine instances of other threads (such as the worker thread), for example, starting and terminating other threads. +- Distribute interaction events. +- Process application code callbacks (event processing and lifecycle management). - Receive messages sent by the worker thread. -In addition to the main thread, there is an independent thread, named worker. The worker thread is mainly used to perform time-consuming operations. It cannot directly operate the UI. The worker thread is created in the main thread and is independent of the main thread. A maximum of seven worker threads can be created. +In addition to the main thread, there is an independent thread, named worker. The worker thread is mainly used to perform time-consuming operations. The worker thread is created in the main thread and is independent from the main thread. It cannot directly operate the UI. A maximum of seven worker threads can be created. ![thread-model-stage](figures/thread-model-stage.png) @@ -22,4 +17,5 @@ Based on the OpenHarmony thread model, different services run on different threa > **NOTE** > -> The stage model provides only the main thread and worker thread. Emitter is mainly used for event synchronization within the main thread or between the main thread and worker thread. +> - The stage model provides only the main thread and worker thread. Emitter is mainly used for event synchronization within the main thread or between the main thread and worker thread. +> - To view thread information about an application process, run the **hdc shell** command to enter the shell CLI of the device, and then run the **ps -p ** -T command**, where ** indicates the ID of the application process. diff --git a/en/application-dev/application-models/uiability-data-sync-with-ui.md b/en/application-dev/application-models/uiability-data-sync-with-ui.md index e5e5b7b54f2ad8e98048a08599360806e3ea578d..52967c25c86966710853378c95c74d5e6e13e432 100644 --- a/en/application-dev/application-models/uiability-data-sync-with-ui.md +++ b/en/application-dev/application-models/uiability-data-sync-with-ui.md @@ -124,14 +124,14 @@ By binding attributes or methods to **globalThis**, you can implement data synch ```ts let entryAbilityWant; - + @Entry @Component struct Index { aboutToAppear() { entryAbilityWant = globalThis.entryAbilityWant; } - + // Page display. build() { // ... @@ -161,7 +161,7 @@ To implement data synchronization between two UIAbility components in the same a ```ts import UIAbility from '@ohos.app.ability.UIAbility' - + export default class UIAbilityB extends UIAbility { onCreate(want, launch) { // UIAbilityB reads name from globalThis and outputs it. @@ -194,7 +194,7 @@ To implement data synchronization between the UIAbility and ExtensionAbility com ```ts import Extension from '@ohos.app.ability.ServiceExtensionAbility' - + export default class ServiceExtAbility extends Extension { onCreate(want) { / / ServiceExtAbility reads name from globalThis and outputs it. @@ -247,7 +247,7 @@ The following provides an example to describe the object overwritten problem in } } ``` - + 3. In the UIAbilityB file, [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md) is stored in **globalThis** and has the same name as that in the UIAbilityA file. ```ts @@ -277,7 +277,7 @@ The following provides an example to describe the object overwritten problem in } } ``` - + 5. Switch the UIAbilityB instance to the background and switch the UIAbilityA instance to the foreground. In this case, UIAbilityA will not enter the **onCreate()** lifecycle again. ```ts @@ -309,4 +309,6 @@ The following provides an example to describe the object overwritten problem in ## Using AppStorage or LocalStorage for Data Synchronization -ArkUI provides AppStorage and LocalStorage to implement application- and UIAbility-level data synchronization, respectively. Both solutions can be used to manage the application state, enhance application performance, and improve user experience. The AppStorage is a global state manager and is applicable when multiple UIAbilities share the same state data. The LocalStorage is a local state manager that manages state data used inside a single UIAbility. They help you control the application state more flexibly and improve the maintainability and scalability of applications. For details, see [State Management of Application-Level Variables](../quick-start/arkts-state-mgmt-application-level.md). +ArkUI provides AppStorage and LocalStorage to implement application- and UIAbility-level data synchronization, respectively. Both solutions can be used to manage the application state, enhance application performance, and improve user experience. The AppStorage is a global state manager and is applicable when multiple UIAbilities share the same state data. The LocalStorage is a local state manager that manages state data used inside a single UIAbility. They help you control the application state more flexibly and improve the maintainability and scalability of applications. For details, see [State Management of Application-Level Variables](../quick-start/arkts-application-state-management-overview.md). + + \ No newline at end of file diff --git a/en/application-dev/application-models/uiability-intra-device-interaction.md b/en/application-dev/application-models/uiability-intra-device-interaction.md index c8ba4ec50fa9b67805685468f0b3ab5cdada2377..9dbbc2be90107d2131a1cdae21e576cb4771966e 100644 --- a/en/application-dev/application-models/uiability-intra-device-interaction.md +++ b/en/application-dev/application-models/uiability-intra-device-interaction.md @@ -222,7 +222,7 @@ This section describes how to start the UIAbility of another application through ```ts let context = ...; // UIAbilityContext - // context is the AbilityContext of the UIAbility instance to stop. + // context is the UIAbilityContext of the UIAbility instance to stop. context.terminateSelf((err) => { // ... }); @@ -487,7 +487,7 @@ In summary, when a UIAbility instance of application A has been created and the > **NOTE** > -> When the [launch type of the target UIAbility](uiability-launch-type.md) is set to **standard**, a new instance is created each time the target UIAbility is started. In this case, the [onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant) callback will not be invoked. +> When the [launch type of the target UIAbility](uiability-launch-type.md) is set to **multiton**, a new instance is created each time the target UIAbility is started. In this case, the [onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant) callback will not be invoked. ## Using Call to Implement UIAbility Interaction (for System Applications Only) diff --git a/en/application-dev/application-models/uiability-launch-type.md b/en/application-dev/application-models/uiability-launch-type.md index 6442ffc4359254bbed7d7da85ec4b753f0f3eea4..8f5762fcde0a766f454a2540708368048e1b01aa 100644 --- a/en/application-dev/application-models/uiability-launch-type.md +++ b/en/application-dev/application-models/uiability-launch-type.md @@ -6,7 +6,7 @@ The launch type of the UIAbility component refers to the state of the UIAbility - [Singleton](#singleton) -- [Standard](#standard) +- [Multiton](#multiton) - [Specified](#specified) @@ -18,8 +18,7 @@ The launch type of the UIAbility component refers to the state of the UIAbility Each time [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called, if a UIAbility instance of this type already exists in the application process, the instance is reused. Therefore, only one UIAbility instance of this type exists in the system, that is, displayed in **Recents**. **Figure 1** Demonstration effect in singleton mode - -![uiability-launch-type1](figures/uiability-launch-type1.png) +![uiability-launch-type1](figures/uiability-launch-type1.gif) > **NOTE** > @@ -43,15 +42,15 @@ To use the singleton mode, set **launchType** in the [module.json5 configuration ``` -## Standard +## Multiton -In standard mode, each time [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called, a new UIAbility instance of this type is created in the application process. Multiple UIAbility instances of this type are displayed in **Recents**. +In multiton mode, each time [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called, a new UIAbility instance of this type is created in the application process. Multiple UIAbility instances of this type are displayed in **Recents**. -**Figure 2** Demonstration effect in standard mode +**Figure 2** Demonstration effect in multiton mode -![standard-mode](figures/standard-mode.png) +![uiability-launch-type2](figures/uiability-launch-type2.gif) -To use the standard mode, set **launchType** in the [module.json5 configuration file](../quick-start/module-configuration-file.md) to **standard**. +To use the multiton mode, set **launchType** in the [module.json5 file](../quick-start/module-configuration-file.md) to **multiton**. ```json @@ -60,7 +59,7 @@ To use the standard mode, set **launchType** in the [module.json5 configuration // ... "abilities": [ { - "launchType": "standard", + "launchType": "multiton", // ... } ] @@ -73,9 +72,8 @@ To use the standard mode, set **launchType** in the [module.json5 configuration The **specified** mode is used in some special scenarios. For example, in a document application, you want a document instance to be created each time you create a document, but you want to use the same document instance when you repeatedly open an existing document. -**Figure 3** Demonstration effect in specified mode - -![uiability-launch-type2](figures/uiability-launch-type2.png) +**Figure 3** Demonstration effect in specified mode +![uiability-launch-type3](figures/uiability-launch-type3.gif) For example, there are two UIAbility components: EntryAbility and SpecifiedAbility (with the launch type **specified**). You are required to start SpecifiedAbility from EntryAbility. @@ -155,3 +153,5 @@ For example, there are two UIAbility components: EntryAbility and SpecifiedAbili 2. Close the process of file A in **Recents**. UIAbility instance 1 is destroyed. Return to the home screen and open file A again. A new UIAbility instance is started, for example, UIAbility instance 2. 3. Return to the home screen and open file B. A new UIAbility instance is started, for example, UIAbility instance 3. 4. Return to the home screen and open file A again. UIAbility instance 2 is started. This is because the system automatically matches the key of the UIAbility instance and starts the UIAbility instance that has a matching key. In this example, UIAbility instance 2 has the same key as file A. Therefore, the system pulls back UIAbility instance 2 and focuses it without creating a new instance. + + \ No newline at end of file diff --git a/en/application-dev/application-models/uiability-overview.md b/en/application-dev/application-models/uiability-overview.md index cd059b9555bfd80c02c9bce66f4c50cd58fff568..e9a904e060e30e2523902aa4014664f6f0100e3a 100644 --- a/en/application-dev/application-models/uiability-overview.md +++ b/en/application-dev/application-models/uiability-overview.md @@ -11,7 +11,7 @@ The following design philosophy is behind UIAbility: 2. Support for multiple device types and window forms -For details, see [Interpretation of the Application Model](application-model-description.md). +For details, see [Interpretation of the Application Model] (application-model-description.md). The UIAbility division principles and suggestions are as follows: @@ -37,7 +37,7 @@ To enable an application to properly use a UIAbility component, declare the UIAb "abilities": [ { "name": "EntryAbility", // Name of the UIAbility component. - "srcEntrance": "./ets/entryability/EntryAbility.ts", // Code path of the UIAbility component. + "srcEntry": "./ets/entryability/EntryAbility.ts", // Code path of the UIAbility component. "description": "$string:EntryAbility_desc", // Description of the UIAbility component. "icon": "$media:icon", // Icon of the UIAbility component. "label": "$string:EntryAbility_label", // Label of the UIAbility component. diff --git a/en/application-dev/application-models/widget-development-fa.md b/en/application-dev/application-models/widget-development-fa.md index 17f9ee7234865b5d01e2a5f68e52cf7928739db7..b766c3420f56a7406bc345911a09bbf91bb6a187 100644 --- a/en/application-dev/application-models/widget-development-fa.md +++ b/en/application-dev/application-models/widget-development-fa.md @@ -323,7 +323,7 @@ async function deleteFormInfo(formId: string) { // ... ``` -For details about how to implement persistent data storage, see [Lightweight Data Store Development](../database/database-preference-guidelines.md). +For details about how to implement persistent data storage, see [Application Data Persistence Overview](../database/app-data-persistence-overview.md). The **Want** object passed in by the widget host to the widget provider contains a flag that specifies whether the requested widget is normal or temporary. @@ -364,7 +364,7 @@ You can use the web-like paradigm (HML+CSS+JSON) to develop JS widget pages. Thi > **NOTE** > -> Only the JavaScript-based web-like development paradigm is supported when developing the widget UI. +> In the FA model, only the JavaScript-based web-like development paradigm is supported when developing the widget UI. - HML: uses web-like paradigm components to describe the widget page information. diff --git a/en/application-dev/application-models/widget-development-stage.md b/en/application-dev/application-models/widget-development-stage.md index 73635fbc05c5e11cc0cc72857ccbcc7648bfa451..5003015d4109cdedbb3c1603a9f31a5d7ce4038d 100644 --- a/en/application-dev/application-models/widget-development-stage.md +++ b/en/application-dev/application-models/widget-development-stage.md @@ -332,7 +332,7 @@ export default class EntryFormAbility extends FormExtension { } ``` -For details about how to implement persistent data storage, see [Lightweight Data Store Development](../database/database-preference-guidelines.md). +For details about how to implement persistent data storage, see [Persisting Preferences Data](../database/data-persistence-by-preferences.md). The **Want** object passed in by the widget host to the widget provider contains a flag that specifies whether the requested widget is normal or temporary. diff --git a/en/application-dev/application-models/widget-switch.md b/en/application-dev/application-models/widget-switch.md index 8d9823385a8a05f71c742327dc966054427a6718..2f8a0a41b2e1b20824a19d08c98f67e39cd05df6 100644 --- a/en/application-dev/application-models/widget-switch.md +++ b/en/application-dev/application-models/widget-switch.md @@ -11,7 +11,7 @@ Widget switching involves the following parts: | Configuration Item | FA Model | Stage Model | | ---------------- | ------------------------------------------- | ------------------------------------------------------------ | | Configuration item location | **formAbility** and **forms** are in the **config.json** file.| **extensionAbilities** (configuration for **formExtensionAbility**) is in the **module.json5** file in the level-1 directory, and **forms** (configuration for **forms** contained in **formExtensionAbility**) is in the **form_config.json** file in the level-2 directory.| -| Widget code path | Specified by **srcPath**, without the file name. | Specified by **srcEntrance**, with the file name. | +| Widget code path | Specified by **srcPath**, without the file name. | Specified by **srcEntry**, with the file name. | | Programming language | **srcLanguage** can be set to **js** or **ets**. | This configuration item is unavailable. Only ets is supported. | | Whether to enable widgets | formsEnabled | This configuration item is unavailable. The setting of **type** set to **form** means that the widgets are enabled. | | Ability type | type: service | type: form | @@ -32,7 +32,7 @@ Figure 2 Widget configuration differences | Item| FA Model| Stage Model| | -------- | -------- | -------- | -| Entry file| **form.ts** in the directory pointed to by **srcPath**| File pointed to by **srcEntrance**| +| Entry file| **form.ts** in the directory pointed to by **srcPath**| File pointed to by **srcEntry**| | Lifecycle| export default| import FormExtension from '\@ohos.app.form.FormExtensionAbility';
export default class FormAbility extends FormExtension| diff --git a/en/application-dev/application-models/windowextensionability.md b/en/application-dev/application-models/windowextensionability.md index 069897ad02435070ac470f5d2d3d528c76b417e8..0f6e28b89790cfa1dd7dc471ed3a450280f19a4a 100644 --- a/en/application-dev/application-models/windowextensionability.md +++ b/en/application-dev/application-models/windowextensionability.md @@ -1,12 +1,13 @@ # WindowExtensionAbility + [WindowExtensionAbility](../reference/apis/js-apis-application-windowExtensionAbility.md) is a type of ExtensionAbility component that allows a system application to be embedded in and displayed over another application. The WindowExtensionAbility component must be used together with the [AbilityComponent](../reference/arkui-ts/ts-container-ability-component.md) to process services of the started application. WindowExtensionAbility is run in connection mode. A system application must use the AbilityComponent to start the WindowExtensionAbility component. Each ExtensionAbility has its own context. For WindowExtensionAbility, -the context is [WindowExtensionContext](../reference/apis/js-apis-inner-application-windowExtensionContext.md). +the context is [WindowExtensionContext](../reference/apis/js-apis-inner-application-windowExtensionContext.md). > **NOTE** > @@ -14,7 +15,7 @@ the context is [WindowExtensionContext](../reference/apis/js-apis-inner-applicat > -## Setting an Embedded Ability (for System Applications Only) +## Setting an Embedded UIAbility (for System Applications Only) The **WindowExtensionAbility** class provides **onConnect()**, **onDisconnect()**, and **onWindowReady()** lifecycle callbacks, which can be overridden. @@ -58,7 +59,7 @@ To implement an embedded application, manually create a WindowExtensionAbility i } ``` -4. Register the WindowExtensionAbility in the [module.json5 file](../quick-start/module-configuration-file.md) corresponding to the **Module** project. Set **type** to **"window"** and **srcEntrance** to the code path of the ExtensionAbility component. +4. Register the WindowExtensionAbility in the [module.json5 file](../quick-start/module-configuration-file.md) corresponding to the **Module** project. Set **type** to **"window"** and **srcEntry** to the code path of the ExtensionAbility component. ```json { @@ -66,11 +67,11 @@ To implement an embedded application, manually create a WindowExtensionAbility i "extensionAbilities": [ { "name": "WindowExtAbility", - "srcEntrance": "./ets/WindowExtAbility/WindowExtAbility.ts", + "srcEntry": "./ets/WindowExtAbility/WindowExtAbility.ts", "icon": "$media:icon", "description": "WindowExtension", "type": "window", - "visible": true, + "exported": true, } ], } @@ -78,7 +79,7 @@ To implement an embedded application, manually create a WindowExtensionAbility i ``` -## Starting an Embedded Ability (for System Applications Only) +## Starting an Embedded UIAbility (for System Applications Only) System applications can load the created WindowExtensionAbility through the AbilityComponent. @@ -90,23 +91,23 @@ System applications can load the created WindowExtensionAbility through the Abil 3. Set the width and height. The sample code is as follows: -```ts -@Entry -@Component -struct Index { - @State message: string = 'Hello World' - - build() { - Row() { - Column() { - AbilityComponent({ abilityName: "WindowExtAbility", bundleName: "com.example.WindowExtAbility"}) - .width(500) - .height(500) - } - .width('100%') - } - .height('100%') - .backgroundColor(0x64BB5c) - } -} -``` + ```ts + @Entry + @Component + struct Index { + @State message: string = 'Hello World' + + build() { + Row() { + Column() { + AbilityComponent({ abilityName: "WindowExtAbility", bundleName: "com.example.WindowExtAbility"}) + .width(500) + .height(500) + } + .width('100%') + } + .height('100%') + .backgroundColor(0x64BB5c) + } + } + ``` \ 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/database/share-device-data-across-apps-overview.md b/en/application-dev/database/share-device-data-across-apps-overview.md index 38aead4c3c77553daab497ab3436291a409a227f..6392e579a8e078e4ff41751aa2ebcc1481ac58a0 100644 --- a/en/application-dev/database/share-device-data-across-apps-overview.md +++ b/en/application-dev/database/share-device-data-across-apps-overview.md @@ -1,46 +1,47 @@ -# DataShare Overview - +# Cross-Application Data Sharing Overview ## Function -The **DataShare** module allows an application to share its data with other applications. Currently, data can be shared only between applications on the same device. +The application data on a device, such as the Contacts, short message service (SMS), and Gallery data, always needs to be shared with other applications. However, certain data, such as the accounts and passwords, cannot be shared. Certain data, such as SMS messages, can be accessed but not modified by other applications. The **DataShare** module provides a secure and easy-to-use mechanism for sharing data of an application with other applications on the same device. -Data needs to be shared in a wealth of scenarios. For example, the Contacts, short message service (SMS), and Gallery data always needs to be shared with other applications. However, certain data, such as accounts and passwords, cannot be shared. Some data, such as SMS messages, can be queried but not modified by other applications. **DataShare** provides a secure and convenient sharing mechanism for application data. +## Basic Concepts -The data provider can directly use **DataShare** to share data with other applications without complex encapsulation. The data consumer only needs to use a set of APIs because the DataShare access mode does not vary with the data provision mode. This greatly reduces the learning time and development difficulty. +Before developing cross-application data sharing on a device, understand the following concepts: -Data can be shared across applications in either of the following ways: +- Data provider: an application that provides data and implements related services. It is also called the data producer or server. -- Using **DataShareExtensionAbility** - An extension ability is implemented in the HAP to invoke a callback. When the data consumer calls an API, the extension ability of the data provider will be automatically started to invoke the registered callback. +- Data consumer: an application that accesses the data or services provided by the data provider. It is also called the client. - You can use **DataShareExtensionAbility** when the cross-application data access involves service operations other than mere addition, deletion, modification, and query of data in databases. +- **ValuesBucket**: a set of data to be inserted. It can be one or more data records in KV pairs. In each KV pair, the key must be of the string type, and the value can be a number, a string, a Boolean value, or an unsigned integer array. -- Using Silent Access - Database access rules are configured in the HAP. When the data consumer calls an API, the system ability automatically obtains the access rules in the HAP and returns data without starting the data provider. +- **ResultSet**: a set of query results. It provides flexible modes for obtaining various data. - You can use the silent access feature when the cross-application data access involves only the operations for adding, deleting, modifying, and querying data in databases. +- **Predicates**: an object that specifies the conditions for updating, deleting, or querying data in a database. -## Basic Concepts +## Implementation -Before developing cross-application data sharing on a device, understand the following concepts: +The data provider can directly use **DataShare** to share data with other applications without complex encapsulation. The data consumer only needs to use a set of APIs to access the data, because the **DataShare** access mode does not vary with the data provisioning mode. This greatly reduces the learning time and development difficulty. -- Data provider: an application that provides data and implements related services. It is also called the producer or server. +The cross-application data sharing can be implemented in either of the following ways: -- Data consumer: an application that accesses the data or services provided by the data provider. It is also called the client. +- **DataShareExtensionAbility** -- **ValuesBucket**: a set of data to be inserted. It can be one or more data records in KV pairs. In each KV pair, the key must be of the string type, and the value can be a number, a string, a Boolean value, or an unsigned integer array. + You can implement an ExtensionAbility with a callback in the HAP. When the data consumer calls an API, the ExtensionAbility of the data provider will be automatically started to invoke the registered callback. -- **ResultSet**: a set of query results. It provides flexible modes for users to obtain various data. + This method is recommended when the cross-application data access involves service operations other than mere addition, deletion, modification, and query of data in databases. -- **Predicates**: an object that specifies the conditions for updating, deleting, or querying data in a database. +- Silent access + + You can configure database access rules in the HAP. When the data consumer calls an API, the system ability automatically obtains the access rules in the HAP and returns data without starting the data provider. + + This method is recommended when the cross-application data access involves only the operations for adding, deleting, modifying, and querying data in databases. ## Constraints -- **DataShare** is subject to the limitations on the database used by the data provider. For example, the supported data models, length of the keys and values, and maximum number of databases that can be accessed at a time by each application vary with the database in use. +- **DataShare** is subject to the limitations on the database used by the data provider. The supported data models, length of the keys and values, and maximum number of databases that can be accessed at a time by each application vary with the database in use. -- The payloads of **ValuesBucket**, **Predicates**, and **ResultSet** are restricted by IPC. +- The payloads of **ValuesBucket**, **Predicates**, and **ResultSet** are restricted by inter-process communication (IPC). - Currently, **dataShare** supports development based on the stage model only. 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/dev-user-file-manager.md b/en/application-dev/file-management/dev-user-file-manager.md index 3eb26df8665594978e171b2a95b25f4a709631da..e048ad7fefa3cf5ddf26ad3764403231cc3045dd 100644 --- a/en/application-dev/file-management/dev-user-file-manager.md +++ b/en/application-dev/file-management/dev-user-file-manager.md @@ -128,7 +128,7 @@ For details about the APIs, see [User File Access and Management](../reference/a // Create a file. // sourceUri is the URI in fileinfo of the Download directory. // You need to use the obtained URI for development. - let sourceUri = "datashare:///media/file/6"; + let sourceUri = "file://media/file/6"; let displayName = "file1"; let fileUri = null; try { 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-ability-ability.md b/en/application-dev/reference/apis/js-apis-ability-ability.md index fe5b7cfde18961802383469c3d2558f8c8381f67..80610df7f925ac5a5d29744b48179488e8efc7f6 100644 --- a/en/application-dev/reference/apis/js-apis-ability-ability.md +++ b/en/application-dev/reference/apis/js-apis-ability-ability.md @@ -15,15 +15,15 @@ import ability from '@ohos.ability.ability'; **System capability**: SystemCapability.Ability.AbilityBase -| Name | Type | Mandatory| Description | -| ----------- | -------------------- | ---- | ------------------------------------------------------------ | -| DataAbilityHelper | [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | No | Level-2 module **DataAbilityHelper**. | -| PacMap | [PacMap](js-apis-inner-ability-dataAbilityHelper.md#PacMap) | No | Level-2 module **PacMap**.| -| DataAbilityOperation | [DataAbilityOperation](js-apis-inner-ability-dataAbilityOperation.md) | No | Level-2 module **DataAbilityOperation**.| -| DataAbilityResult | [DataAbilityResult](js-apis-inner-ability-dataAbilityResult.md) | No | Level-2 module **DataAbilityResult**.| -| AbilityResult | [AbilityResult](js-apis-inner-ability-abilityResult.md) | No | Level-2 module **AbilityResult**.| -| ConnectOptions | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | No | Level-2 module **ConnectOptions**.| -| StartAbilityParameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | No | Level-2 module **StartAbilityParameter**.| +| Name | Type | Description | +| ----------- | -------------------- | ------------------------------------------------------------ | +| DataAbilityHelper | [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | Level-2 module **DataAbilityHelper**. | +| PacMap | [PacMap](js-apis-inner-application-pacMap.md) | Level-2 module **PacMap**.| +| DataAbilityOperation | [DataAbilityOperation](js-apis-inner-ability-dataAbilityOperation.md) | Level-2 module **DataAbilityOperation**.| +| DataAbilityResult | [DataAbilityResult](js-apis-inner-ability-dataAbilityResult.md) | Level-2 module **DataAbilityResult**.| +| AbilityResult | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Level-2 module **AbilityResult**.| +| ConnectOptions | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | Level-2 module **ConnectOptions**.| +| StartAbilityParameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | Level-2 module **StartAbilityParameter**.| **Example** ```ts 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-app-ability-common.md b/en/application-dev/reference/apis/js-apis-app-ability-common.md index 497867de9df35f93bc04b818a305e32b3a5dee3a..e18bc26fecc0695b771769df0abee199c4254ed9 100644 --- a/en/application-dev/reference/apis/js-apis-app-ability-common.md +++ b/en/application-dev/reference/apis/js-apis-app-ability-common.md @@ -26,7 +26,7 @@ import common from '@ohos.app.ability.common'; | FormExtensionContext | [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) | Level-2 module **FormExtensionContext**.| | ServiceExtensionContext | [ServiceExtensionContext](js-apis-inner-application-serviceExtensionContext.md) | Level-2 module **ServiceExtensionContext**.| | EventHub | [EventHub](js-apis-inner-application-eventHub.md) | Level-2 module **EventHub**.| -| PacMap | [PacMap](js-apis-inner-ability-dataAbilityHelper.md#PacMap) | Level-2 module **PacMap**.| +| PacMap | [PacMap](js-apis-inner-application-pacMap.md) | Level-2 module **PacMap**.| | AbilityResult | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Level-2 module **AbilityResult**.| | ConnectOptions | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | Level-2 module **ConnectOptions**.| diff --git a/en/application-dev/reference/apis/js-apis-bundle-ApplicationInfo.md b/en/application-dev/reference/apis/js-apis-bundle-ApplicationInfo.md index 89444bc41bf2f3d55bf71c18b4c59c497dc37c20..99bede315abe0b033c4e5e1bedf127b807245585 100644 --- a/en/application-dev/reference/apis/js-apis-bundle-ApplicationInfo.md +++ b/en/application-dev/reference/apis/js-apis-bundle-ApplicationInfo.md @@ -12,26 +12,25 @@ The **ApplicationInfo** module provides application information. Unless otherwis **System capability**: SystemCapability.BundleManager.BundleFramework -| Name | Type | Readable | Writable | Description | -|----------------------------|------------------------------------------------------------------------|-----|-----|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| name | string | Yes | No | Application name. | -| description | string | Yes | No | Application description. | -| descriptionId | number | Yes | No | ID of the application description. | -| systemApp | boolean | Yes | No | Whether the application is a system application. The default value is **false**. | -| enabled | boolean | Yes | No | Whether the application is enabled. The default value is **true**. | -| label | string | Yes | No | Application label. | -| labelId | string | Yes | No | ID of the application label. | -| icon | string | Yes | No | Application icon. | -| iconId | string | Yes | No | ID of the application icon. | -| process | string | Yes | No | Process in which the application runs. If this parameter is not set, the bundle name is used. | -| supportedModes | number | Yes | No | Modes supported by the application. Currently, only the **drive** mode is defined. This attribute applies only to telematics devices. | -| moduleSourceDirs | Array\ | Yes | No | Relative paths for storing application resources. | -| permissions | Array\ | Yes | No | Permissions required for accessing the application.
The value is obtained by passing in GET_APPLICATION_INFO_WITH_PERMISSION to [bundle.getApplicationInfo](js-apis-Bundle.md#bundlegetapplicationinfodeprecated). | -| moduleInfos | Array\<[ModuleInfo](js-apis-bundle-ModuleInfo.md)> | Yes | No | Application module information. | -| entryDir | string | Yes | No | Path for storing application files. | -| codePath8+ | string | Yes | No | Installation directory of the application. | -| metaData8+ | Map\> | Yes | No | Custom metadata of the application.
The value is obtained by passing in GET_APPLICATION_INFO_WITH_METADATA to [bundle.getApplicationInfo](js-apis-Bundle.md#bundlegetapplicationinfodeprecated). | -| removable8+ | boolean | Yes | No | Whether the application is removable. | -| accessTokenId8+ | number | Yes | No | Access token ID of the application. | -| uid8+ | number | Yes | No | UID of the application. | -| entityType8+ | string | Yes | No | Category of the application, which can be **game**, **media**, **communication**, **news**, **travel**, **utility**, **shopping**, **education**, **kids**, **business**, and **photography**.| +| Name | Type | Readable| Writable| Description | +| -------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | +| name | string | Yes | No | Application name. | +| description | string | Yes | No | Application description. | +| descriptionId | number | Yes | No | ID of the application description. | +| systemApp | boolean | Yes | No | Whether the application is a system application. The default value is **false**. | +| enabled | boolean | Yes | No | Whether the application is enabled. The default value is **true**. | +| label | string | Yes | No | Application label. | +| labelId | string | Yes | No | ID of the application label. | +| icon | string | Yes | No | Application icon. | +| iconId | string | Yes | No | ID of the application icon. | +| process | string | Yes | No | Process in which the application runs. If this parameter is not set, the bundle name is used. | +| supportedModes | number | Yes | No | Modes supported by the application. Currently, only the **drive** mode is defined. This attribute applies only to telematics devices.| +| moduleSourceDirs | Array\ | Yes | No | Relative paths for storing application resources. Do not access resource files by concatenating paths. Use the [resourceManager API](js-apis-resource-manager.md) instead. | +| permissions | Array\ | Yes | No | Permissions required for accessing the application.
The value is obtained by passing in GET_APPLICATION_INFO_WITH_PERMISSION to [bundle.getApplicationInfo](js-apis-Bundle.md#bundlegetapplicationinfodeprecated).| +| moduleInfos | Array\<[ModuleInfo](js-apis-bundle-ModuleInfo.md)> | Yes | No | Application module information. | +| entryDir | string | Yes | No | Path for storing application files. Do not access resource files by concatenating paths. Use the [resourceManager API](js-apis-resource-manager.md) instead. | +| codePath8+ | string | Yes | No | Installation directory of the application. Do not access resource files by concatenating paths. Use the [resourceManager API](js-apis-resource-manager.md) instead. | +| metaData8+ | Map\> | Yes | No | Custom metadata of the application.
The value is obtained by passing in GET_APPLICATION_INFO_WITH_METADATA to [bundle.getApplicationInfo](js-apis-Bundle.md#bundlegetapplicationinfodeprecated).| +| removable8+ | boolean | Yes | No | Whether the application is removable. | +| accessTokenId8+ | number | Yes | No | Access token ID of the application. | +| uid8+ | number | Yes | No | UID of the application. | 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-fileAccess.md b/en/application-dev/reference/apis/js-apis-fileAccess.md index 41c76565f967a2ea057f9c81ca3328a1cc047a07..09dfaa48285b7229fcae30e22469f3332c25bacf 100644 --- a/en/application-dev/reference/apis/js-apis-fileAccess.md +++ b/en/application-dev/reference/apis/js-apis-fileAccess.md @@ -1,12 +1,11 @@ # @ohos.file.fileAccess (User File Access and Management) -The **fileAccess** module is a framework for accessing and operating user files based on the ExtensionAbility mechanism. This module interacts with diverse file management services, such as the media library and external storage management service, and provides a set of file access and management APIs for system applications. The media library service allows access to user files on local devices and distributed devices. The external storage management service allows access to the user files stored on devices such as shared disks, USB flash drives, and SD cards. +The **fileAccess** module provides a framework for accessing and operating user files based on the ExtensionAbility mechanism. This module interacts with file management services, such as the media library and external storage management service, and provides a set of unified interfaces for system applications to access and manage files. The media library service allows access to user files on local and distributed devices. The external storage management service allows access to the user files stored on devices, such as shared disks, USB flash drives, and SD cards. >**NOTE** > ->- The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. ->- The APIs provided by this module are system APIs and cannot be called by third-party applications. Currently, the APIs can be called only by **picker** and **fs**. ->- The APIs of this module support processing of error codes. For details, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). +> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> - The APIs provided by this module are system APIs and cannot be called by third-party applications. Currently, the APIs can be called only by **FilePicker** and **FileManager**. ## Modules to Import @@ -16,9 +15,11 @@ import fileAccess from '@ohos.file.fileAccess'; ## fileAccess.getFileAccessAbilityInfo -getFileAccessAbilityInfo( ) : Promise<Array<Want>> +getFileAccessAbilityInfo() : Promise<Array<Want>> -Obtains information about all wants with **extension** set to **fileAccess** in the system. A want is a basic communication component used to start services. This API uses a promise to return the result. +Obtains information about all Wants with **extension** set to **fileAccess** in the system. A Want contains information for starting an ability. This API uses a promise to return the result. + +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.FileManagement.UserFileService @@ -26,9 +27,13 @@ Obtains information about all wants with **extension** set to **fileAccess** in **Return value** -| Type| Description| -| --- | -- | -| Promise<Array<Want>> | Promise used to return the **want** information obtained.| + | Type| Description| + | --- | -- | + | Promise<Array<[Want](js-apis-app-ability-want.md)>> | Promise used to return the Want information obtained.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -46,9 +51,11 @@ Obtains information about all wants with **extension** set to **fileAccess** in ## fileAccess.getFileAccessAbilityInfo -getFileAccessAbilityInfo(callback: AsyncCallback<Array<Want>>): void; +getFileAccessAbilityInfo(callback: AsyncCallback<Array<Want>>): void + +Obtains information about all Wants with **extension** set to **fileAccess** in the system. A Want contains information for starting an ability. This API uses an asynchronous callback to return the result. -Obtains information about all wants with **extension** set to **fileAccess** in the system. A want is a basic communication component used to start services. This API uses an asynchronous callback to return the result. +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.FileManagement.UserFileService @@ -56,9 +63,13 @@ Obtains information about all wants with **extension** set to **fileAccess** in **Parameters** -| Name| Type| Mandatory| Description| -| --- | --- | --- | -- | -| callback | AsyncCallback<Array<Want>> | Yes| Promise used to return the **want** information obtained.| + | Name| Type| Mandatory| Description| + | --- | --- | --- | -- | + | callback | AsyncCallback<Array<[Want](js-apis-app-ability-want.md)>> | Yes| Promise used to return the Want information obtained.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -82,7 +93,9 @@ Obtains information about all wants with **extension** set to **fileAccess** in createFileAccessHelper(context: Context, wants: Array<Want>) : FileAccessHelper -Synchronously creates a **Helper** object to connect to the specified wants. The **Helper** object provides file access and management capabilities. +Synchronously creates a **Helper** object to connect to the specified Wants. The **Helper** object provides file access and management capabilities. + +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.FileManagement.UserFileService @@ -90,16 +103,20 @@ Synchronously creates a **Helper** object to connect to the specified wants. The **Parameters** -| Name| Type| Mandatory| Description| -| --- | --- | --- | -- | -| context | Context | Yes| Context of the ability.| -| wants | Array<Want> | Yes| Wants to connect.| + | Name| Type| Mandatory| Description| + | --- | --- | --- | -- | + | context | [Context](js-apis-inner-application-context.md) | Yes| Context of the ability.| + | wants | Array<[Want](js-apis-app-ability-want.md)> | Yes| Wants to connect.| **Return value** -| Type| Description| -| --- | -- | -| FileAccessHelper | **Helper** object created.| + | Type| Description| + | --- | -- | + | [FileAccessHelper](#fileaccesshelper) | **Helper** object created.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -131,21 +148,27 @@ createFileAccessHelper(context: Context) : FileAccessHelper Synchronously creates a **Helper** object to connect to all file management services in the system. +**Model restriction**: This API can be used only in the stage model. + **System capability**: SystemCapability.FileManagement.UserFileService **Required permissions**: ohos.permission.FILE_ACCESS_MANAGER and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED **Parameters** -| Name| Type| Mandatory| Description| -| --- | --- | --- | -- | -| context | Context | Yes| Context of the ability.| + | Name| Type| Mandatory| Description| + | --- | --- | --- | -- | + | context | [Context](js-apis-inner-application-context.md) | Yes| Context of the ability.| **Return value** -| Type| Description| -| --- | -- | -| FileAccessHelper | **Helper** object created.| + | Type| Description| + | --- | -- | + | [FileAccessHelper](#fileaccesshelper) | **Helper** object created.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -164,55 +187,91 @@ Synchronously creates a **Helper** object to connect to all file management serv } ``` -## FileAccessHelper.getRoots +## FileInfo + +Provides the file or directory attribute information and APIs. + +**Model restriction**: This API can be used only in the stage model. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Required permissions**: ohos.permission.FILE_ACCESS_MANAGER -getRoots( ) : Promise<RootIterator> +### Attributes -Obtains information about the device root nodes of the file management service type connected to the **Helper** object. This API uses a promise to return a **RootIterator** object, which returns [RootInfo](#rootinfo) by using [next()](#rootiteratornext). +| Name| Type | Readable| Writable| Description | +| ------ | ------ | -------- | ------ | -------- | +| uri | string | Yes| No| URI of the file or directory.| +| relativePath10+ | string | Yes| No| Relative path of the file or directory.| +| fileName | string | Yes| No| Name of the file or directory.| +| mode | number | Yes| No| Permissions on the file or directory.| +| size | number | Yes| No| Size of the file or directory.| +| mtime | number | Yes| No| Time when the file or directory was last modified.| +| mimeType | string | Yes| No| Multipurpose Internet Mail Extensions (MIME) type of the file or directory.| + +### listFile + +listFile(filter?: Filter) : FileIterator + +Synchronously obtains a **FileIterator** object that lists the next-level files (directories) matching the conditions of the filter from a directory and returns [FileInfo](#fileinfo) using [next()](#next). Currently, only built-in storage devices support the file filter. + +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.FileManagement.UserFileService **Required permissions**: ohos.permission.FILE_ACCESS_MANAGER +**Parameters** + + | Name| Type| Mandatory| Description| + | --- | --- | -- | -- | + | filter | [Filter](js-apis-file-fs.md#filter) | No| **Filter** object. | + **Return value** -| Type| Description| -| --- | -- | -| Promise<RootIterator> | Promise used to return the **RootIterator** object obtained.| + | Type| Description| + | --- | -- | + | [FileIterator](#fileiterator) | **FileIterator** object obtained.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** ```js - async getRoots() { - let rootIterator = null; - let rootinfos = []; - let isDone = false; - try { - // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. - rootIterator = await fileAccessHelper.getRoots(); - if (!rootIterator) { - console.error("getRoots interface returns an undefined object"); - return; - } - while (!isDone) { - let result = rootIterator.next(); - console.log("next result = " + JSON.stringify(result)); - isDone = result.done; - if (!isDone) - rootinfos.push(result.value); - } - } catch (error) { - console.error("getRoots failed, errCode:" + error.code + ", errMessage:" + error.message); + // fileInfoDir indicates information about a directory. + // let filter = { suffix : [".txt", ".jpg", ".xlsx"] }; + let fileInfoDir = fileInfos[0]; + let subfileInfos = []; + let isDone = false; + try { + let fileIterator = fileInfoDir.listFile(); + // listFile() with the filter implementation. + // let fileIterator = rootInfo.listFile(filter); + if (!fileIterator) { + console.error("listFile interface returns an undefined object"); + return; + } + while (!isDone) { + let result = fileIterator.next(); + console.log("next result = " + JSON.stringify(result)); + isDone = result.done; + if (!isDone) + subfileInfos.push(result.value); } + } catch (error) { + console.error("listFile failed, errCode:" + error.code + ", errMessage:" + error.message); } ``` -## FileAccessHelper.getRoots +### scanFile + +scanFile(filter?: Filter) : FileIterator; -getRoots(callback:AsyncCallback<RootIterator>) : void; +Synchronously obtains a **FileIterator** object that recursively retrieves the files matching the conditions of the filter from a directory and returns [FileInfo](#fileinfo) using [next()](#next). Currently, this API supports only built-in storage devices. -Obtains information about the device root nodes of the file management service type connected to the **Helper** object. This API uses an asynchronous callback to return the result. -The callback has a **RootIterator** object, which returns [RootInfo](#rootinfo) through [next()](#rootiteratornext). +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.FileManagement.UserFileService @@ -220,59 +279,127 @@ The callback has a **RootIterator** object, which returns [RootInfo](#rootinfo) **Parameters** -| Name| Type| Mandatory| Description| -| --- | --- | --- | -- | -| callback | AsyncCallback<RootIterator> | Yes| Promise used to return the **RootIterator** object obtained.| + | Name| Type| Mandatory| Description| + | --- | --- | -- | -- | + | filter | [Filter](js-apis-file-fs.md#filter) | No| **Filter** object. | + +**Return value** + + | Type| Description| + | --- | -- | + | [FileIterator](#fileiterator) | **FileIterator** object obtained.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** ```js - async getRoots() { - let rootinfos = []; - let isDone = false; - try { - // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. - fileAccessHelper.getRoots(function (err, rootIterator) { - if (err) { - console.error("Failed to getRoots in async, errCode:" + err.code + ", errMessage:" + err.message); - return; - } - while (!isDone) { - let result = rootIterator.next(); - console.log("next result = " + JSON.stringify(result)); - isDone = result.done; - if (!isDone) - rootinfos.push(result.value); - } - }); - } catch (error) { - console.error("getRoots failed, errCode:" + error.code + ", errMessage:" + error.message); + // fileInfoDir indicates information about a directory. + // let filter = {suffix : [".txt", ".jpg", ".xlsx"]}; + let fileInfoDir = fileInfos[0]; + let subfileInfos = []; + let isDone = false; + try { + let fileIterator = fileInfoDir.scanFile(); + // scanFile() with the filter implementation. + // let fileIterator = rootInfo.scanFile(filter); + if (!fileIterator) { + console.error("scanFile interface returns an undefined object"); + return; } + while (!isDone) { + let result = fileIterator.next(); + console.log("next result = " + JSON.stringify(result)); + isDone = result.done; + if (!isDone) + subfileInfos.push(result.value); + } + } catch (error) { + console.error("scanFile failed, errCode:" + error.code + ", errMessage:" + error.message); } ``` -## RootInfo.listfile +## FileIterator -listFile(filter?: Filter) : FileIterator +Provides the **FileIterator** object. -Synchronously obtains the **FileIterator** object of the first-level files (directory) matching the conditions of the filter from the device root node. The **FileIterator** object then returns [FileInfo](#fileinfo) by using [next()](#fileiteratornext). +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.FileManagement.UserFileService **Required permissions**: ohos.permission.FILE_ACCESS_MANAGER -**Parameters** +### next -| Name| Type| Mandatory| Description| -| --- | --- | -- | -- | -| filter | Filter | No| **Filter** object. | +next() : { value: FileInfo, done: boolean } + +Obtains information about the next-level files or directories. + +**Model restriction**: This API can be used only in the stage model. + +**System capability**: SystemCapability.FileManagement.UserFileService +**Required permissions**: ohos.permission.FILE_ACCESS_MANAGER **Return value** | Type| Description| | --- | -- | -| FileIterator | **FileIterator** object obtained.| +| {value: [FileInfo](#fileinfo), done: boolean} | File or directory information obtained. This method traverses the specified directory until **true** is returned. The **value** field contains the file or directory information obtained.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + +## RootInfo + +Provides the device's root attribute information and APIs. + +**Model restriction**: This API can be used only in the stage model. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Required permissions**: ohos.permission.FILE_ACCESS_MANAGER + +### Attributes + +| Name| Type | Readable| Writable| Description | +| ------ | ------ | -------- | ------ | -------- | +| deviceType | number | Yes| No|Type of the device.| +| uri | string | Yes| No| Root directory URI of the device.| +| relativePath10+ | string | Yes| No| Relative path of the root directory.| +| displayName | string | Yes| No| Device name.| +| deviceFlags | number | Yes| No| Capabilities supported by the device.| + +### listFile + +listFile(filter?: Filter) : FileIterator + +Synchronously obtains a **FileIterator** object that lists the first-level files (directories) matching the conditions of the filter from the device root directory and returns [FileInfo](#fileinfo) using [next()](#next). Currently, only built-in storage devices support the file filter. + +**Model restriction**: This API can be used only in the stage model. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Required permissions**: ohos.permission.FILE_ACCESS_MANAGER + +**Parameters** + + | Name| Type| Mandatory| Description| + | --- | --- | -- | -- | + | filter | [Filter](js-apis-file-fs.md#filter) | No| **Filter** object. | + +**Return value** + + | Type| Description| + | --- | -- | + | [FileIterator](#fileiterator) | **FileIterator** object obtained.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -284,7 +411,7 @@ Synchronously obtains the **FileIterator** object of the first-level files (dire let isDone = false; try { let fileIterator = rootInfo.listFile(); - // listFile contains the filter implementation. + // listFile() with the filter implementation. // let fileIterator = rootInfo.listFile(filter); if (!fileIterator) { console.error("listFile interface returns an undefined object"); @@ -302,11 +429,13 @@ Synchronously obtains the **FileIterator** object of the first-level files (dire } ``` -## RootInfo.scanFile +### scanFile scanFile(filter?: Filter) : FileIterator -Recursively obtains the **FileIterator** object of the files matching the conditions of the filter from the device root node synchronously. The **FileIterator** object then returns [FileInfo](#fileinfo) by using [next()](#fileiteratornext). +Synchronously obtains a **FileIterator** object that recursively retrieves the files matching the conditions of the filter from the device root directory and returns [FileInfo](#fileinfo)using [next()](#next). Currently, this API supports only built-in storage devices. + +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.FileManagement.UserFileService @@ -314,15 +443,19 @@ Recursively obtains the **FileIterator** object of the files matching the condit **Parameters** -| Name| Type| Mandatory| Description| -| --- | --- | -- | -- | -| filter | Filter | No| **Filter** object. | + | Name| Type| Mandatory| Description| + | --- | --- | -- | -- | + | filter | [Filter](js-apis-file-fs.md#filter) | No| **Filter** object. | **Return value** -| Type| Description| -| --- | -- | -| FileIterator | **FileIterator** object obtained.| + | Type| Description| + | --- | -- | + | [FileIterator](#fileiterator) | **FileIterator** object obtained.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -334,7 +467,7 @@ Recursively obtains the **FileIterator** object of the files matching the condit let isDone = false; try { let fileIterator = rootInfo.scanFile(); - // scanFile contains the filter implementation. + // scanFile with the filter implementation. // let fileIterator = rootInfo.scanFile(filter); if (!fileIterator) { console.error("scanFile interface returns undefined object"); @@ -352,61 +485,100 @@ Recursively obtains the **FileIterator** object of the files matching the condit } ``` -## FileInfo.listfile +## RootIterator -listFile(filter?: Filter) : FileIterator +Provides an iterator object of the device root directory. -Synchronously obtains the **FileIterator** object of the next-level files (directories) matching the conditions of the filter from a directory. The **FileIterator** object then returns [FileInfo](#fileinfo) by using [next()](#fileiteratornext). +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.FileManagement.UserFileService **Required permissions**: ohos.permission.FILE_ACCESS_MANAGER -**Parameters** +### next -| Name| Type| Mandatory| Description| -| --- | --- | -- | -- | -| filter | Filter | No| **Filter** object. | +next() : { value: RootInfo, done: boolean } + +Obtains the root directory of the next-level device. + +**Model restriction**: This API can be used only in the stage model. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Required permissions**: ohos.permission.FILE_ACCESS_MANAGER **Return value** | Type| Description| | --- | -- | -| FileIterator | **FileIterator** object obtained.| +| {value: [RootInfo](#rootinfo), done: boolean} | Root directory information obtained. This method traverses the directory until **true** is returned. The **value** field contains the root directory information.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + +## FileAccessHelper + +Provides a **FileAccessHelper** object. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Required permissions**: ohos.permission.FILE_ACCESS_MANAGER + +### getRoots + +getRoots() : Promise<RootIterator> + +Obtains information about the device root nodes of the file management service connected to the **Helper** object. This API uses a promise to return a **RootIterator** object, +which returns [RootInfo](#rootinfo) by using [next](#next-1). + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Required permissions**: ohos.permission.FILE_ACCESS_MANAGER + +**Return value** + +| Type| Description| +| --- | -- | +| Promise<[RootIterator](#rootiterator)> | Promise used to return the **RootIterator** object obtained.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** ```js - // fileInfoDir specifies the target directory. - // let filter = { suffix : [".txt", ".jpg", ".xlsx"] }; - let fileInfoDir = fileInfos[0]; - let subfileInfos = []; - let isDone = false; - try { - let fileIterator = fileInfoDir.listFile(); - // listFile contains the filter implementation. - // let fileIterator = rootInfo.listFile(filter); - if (!fileIterator) { - console.error("listFile interface returns an undefined object"); - return; - } - while (!isDone) { - let result = fileIterator.next(); - console.log("next result = " + JSON.stringify(result)); - isDone = result.done; - if (!isDone) - subfileInfos.push(result.value); + async getRoots() { + let rootIterator = null; + let rootinfos = []; + let isDone = false; + try { + // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. + rootIterator = await fileAccessHelper.getRoots(); + if (!rootIterator) { + console.error("getRoots interface returns an undefined object"); + return; + } + while (!isDone) { + let result = rootIterator.next(); + console.log("next result = " + JSON.stringify(result)); + isDone = result.done; + if (!isDone) + rootinfos.push(result.value); + } + } catch (error) { + console.error("getRoots failed, errCode:" + error.code + ", errMessage:" + error.message); } - } catch (error) { - console.error("listFile failed, errCode:" + error.code + ", errMessage:" + error.message); } ``` -## FileInfo.scanfile +### getRoots -scanFile(filter?: Filter) : FileIterator; +getRoots(callback:AsyncCallback<RootIterator>) : void -Recursively obtains the **FileIterator** object of the files matching the conditions of the filter from a directory synchronously. The **FileIterator** object then returns [FileInfo](#fileinfo) by using [next()](#fileiteratornext). +Obtains information about the device root nodes of the file management service connected to the **Helper** object. This API uses an asynchronous callback to return a **RootIterator** object, +which returns [RootInfo](#rootinfo) by using [next](#next-1). **System capability**: SystemCapability.FileManagement.UserFileService @@ -415,45 +587,41 @@ Recursively obtains the **FileIterator** object of the files matching the condit **Parameters** | Name| Type| Mandatory| Description| -| --- | --- | -- | -- | -| filter | Filter | No| **Filter** object. | - +| --- | --- | --- | -- | +| callback | AsyncCallback<[RootIterator](#rootiterator)> | Yes| Callback invoked to return the **RootIterator** object obtained.| -**Return value** +**Error codes** -| Type| Description| -| --- | -- | -| FileIterator | **FileIterator** object obtained.| +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** ```js - // fileInfoDir specifies the target directory. - // let filter = {suffix : [".txt", ".jpg", ".xlsx"]}; - let fileInfoDir = fileInfos[0]; - let subfileInfos = []; - let isDone = false; - try { - let fileIterator = fileInfoDir.scanFile(); - // scanFile contains the filter implementation. - // let fileIterator = rootInfo.scanFile(filter); - if (!fileIterator) { - console.error("scanFile interface returns an undefined object"); - return; - } - while (!isDone) { - let result = fileIterator.next(); - console.log("next result = " + JSON.stringify(result)); - isDone = result.done; - if (!isDone) - subfileInfos.push(result.value); + async getRoots() { + let rootinfos = []; + let isDone = false; + try { + // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. + fileAccessHelper.getRoots(function (err, rootIterator) { + if (err) { + console.error("Failed to getRoots in async, errCode:" + err.code + ", errMessage:" + err.message); + return; + } + while (!isDone) { + let result = rootIterator.next(); + console.log("next result = " + JSON.stringify(result)); + isDone = result.done; + if (!isDone) + rootinfos.push(result.value); + } + }); + } catch (error) { + console.error("getRoots failed, errCode:" + error.code + ", errMessage:" + error.message); } - } catch (error) { - console.error("scanFile failed, errCode:" + error.code + ", errMessage:" + error.message); } ``` -## FileAccessHelper.createFile +### createFile createFile(uri: string, displayName: string) : Promise<string> @@ -467,7 +635,7 @@ Creates a file in a directory. This API uses a promise to return the result. | Name| Type| Mandatory| Description| | --- | --- | --- | -- | -| uri | string | Yes| URI of the parent directory for the file to create.| +| uri | string | Yes| URI of the destination directory for the file to create.| | displayName | string | Yes| Name of the file to create. By default, the name of a local file must contain the file name extension.| **Return value** @@ -476,13 +644,17 @@ Creates a file in a directory. This API uses a promise to return the result. | --- | -- | | Promise<string> | Promise used to return the URI of the file created.| +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js // The media library URI is used as an example. // In the sample code, sourceUri indicates the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let sourceUri = "datashare:///media/file/6"; + let sourceUri = "file://media/file/6"; let displayName = "file1" let fileUri = null; try { @@ -498,9 +670,9 @@ Creates a file in a directory. This API uses a promise to return the result. }; ``` -## FileAccessHelper.createFile +### createFile -createFile(uri: string, displayName: string, callback: AsyncCallback<string>) : void; +createFile(uri: string, displayName: string, callback: AsyncCallback<string>) : void Creates a file in a directory. This API uses an asynchronous callback to return the result. @@ -512,9 +684,13 @@ Creates a file in a directory. This API uses an asynchronous callback to return | Name| Type| Mandatory| Description| | --- | --- | --- | -- | -| uri | string | Yes| URI of the parent directory for the file to create.| +| uri | string | Yes| URI of the destination directory for the file to create.| | displayName | string | Yes| Name of the file to create. By default, the name of a local file must contain the file name extension.| -| callback | AsyncCallback<string> | Yes| Promise used to return the URI of the file created.| +| callback | AsyncCallback<string> | Yes| Callback invoked to return the URI of the file created.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -522,7 +698,7 @@ Creates a file in a directory. This API uses an asynchronous callback to return // The media library URI is used as an example. // In the sample code, sourceUri indicates the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let sourceUri = "datashare:///media/file/6"; + let sourceUri = "file://media/file/6"; let displayName = "file1" try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. @@ -538,7 +714,7 @@ Creates a file in a directory. This API uses an asynchronous callback to return }; ``` -## FileAccessHelper.mkDir +### mkDir mkDir(parentUri: string, displayName: string) : Promise<string> @@ -552,7 +728,7 @@ Creates a directory. This API uses a promise to return the result. | Name| Type| Mandatory| Description| | --- | --- | --- | -- | -| parentUri | string | Yes| URI of the parent directory for the directory to create.| +| parentUri | string | Yes| URI of the destination directory for the directory to create.| | displayName | string | Yes| Name of the directory to create.| **Return value** @@ -561,13 +737,17 @@ Creates a directory. This API uses a promise to return the result. | --- | -- | | Promise<string> | Promise used to return the URI of the directory created.| +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js // The media library URI is used as an example. // In the sample code, sourceUri indicates the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let sourceUri = "datashare:///media/file/6"; + let sourceUri = "file://media/file/6"; let dirName = "dirTest" let dirUri = null; try { @@ -583,9 +763,9 @@ Creates a directory. This API uses a promise to return the result. }; ``` -## FileAccessHelper.mkDir +### mkDir -mkDir(parentUri: string, displayName: string, callback: AsyncCallback<string>) : void; +mkDir(parentUri: string, displayName: string, callback: AsyncCallback<string>) : void Creates a directory. This API uses an asynchronous callback to return the result. @@ -597,9 +777,13 @@ Creates a directory. This API uses an asynchronous callback to return the result | Name| Type| Mandatory| Description| | --- | --- | --- | -- | -| parentUri | string | Yes| URI of the parent directory for the directory to create.| +| parentUri | string | Yes| URI of the destination directory for the directory to create.| | displayName | string | Yes| Name of the directory to create.| -| callback | AsyncCallback<string> | Yes| Promise used to return the URI of the directory created.| +| callback | AsyncCallback<string> | Yes| Callback invoked to return the URI of the directory created.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -607,7 +791,7 @@ Creates a directory. This API uses an asynchronous callback to return the result // The media library URI is used as an example. // In the sample code, sourceUri indicates the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let sourceUri = "datashare:///media/file/6"; + let sourceUri = "file://media/file/6"; let dirName = "dirTest" try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. @@ -623,7 +807,7 @@ Creates a directory. This API uses an asynchronous callback to return the result }; ``` -## FileAccessHelper.openFile +### openFile openFile(uri: string, flags: OPENFLAGS) : Promise<number> @@ -644,15 +828,19 @@ Opens a file. This API uses a promise to return the result. | Type| Description| | --- | -- | -| Promise<number> | Promise used to return the file descriptor of the file opened.| +| Promise<number> | Promise used to return the file descriptor (FD) of the file opened.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** ```js // The media library URI is used as an example. - //In the sample code, targetUri indicates a file in the Download directory. The URI is the URI in fileInfo. + // In the sample code, targetUri indicates a file in the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let targetUri = "datashare:///media/file/100"; + let targetUri = "file://media/file/100"; try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. let fd = await fileAccessHelper.openFile(targetUri, fileAccess.OPENFLAGS.READ); @@ -661,9 +849,9 @@ Opens a file. This API uses a promise to return the result. }; ``` -## FileAccessHelper.openFile +### openFile -openFile(uri: string, flags: OPENFLAGS, callback: AsyncCallback<number>) : void; +openFile(uri: string, flags: OPENFLAGS, callback: AsyncCallback<number>) : void Opens a file. This API uses an asynchronous callback to return the result. @@ -677,15 +865,19 @@ Opens a file. This API uses an asynchronous callback to return the result. | --- | --- | --- | -- | | uri | string | Yes| URI of the file to open.| | flags | [OPENFLAGS](#openflags) | Yes| File open mode.| -| callback | AsyncCallback<number> | Yes| Callback invoked to return the file descriptor of the file opened.| +| callback | AsyncCallback<number> | Yes| Callback invoked to return the FD of the file opened.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** ```js // The media library URI is used as an example. - //In the sample code, targetUri indicates a file in the Download directory. The URI is the URI in fileInfo. + // In the sample code, targetUri indicates a file in the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let targetUri = "datashare:///media/file/100"; + let targetUri = "file://media/file/100"; try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. fileAccessHelper.openFile(targetUri, fileAccess.OPENFLAGS.READ, function (err, fd) { @@ -700,7 +892,7 @@ Opens a file. This API uses an asynchronous callback to return the result. }; ``` -## FileAccessHelper.delete +### delete delete(uri: string) : Promise<number> @@ -722,13 +914,17 @@ Deletes a file or directory. This API uses a promise to return the result. | --- | -- | | Promise<number> | Promise used to return the result.| +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js // The media library URI is used as an example. - //In the sample code, targetUri indicates a file in the Download directory. The URI is the URI in fileInfo. + // In the sample code, targetUri indicates a file in the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let targetUri = "datashare:///media/file/100"; + let targetUri = "file://media/file/100"; try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. let code = await fileAccessHelper.delete(targetUri); @@ -739,9 +935,9 @@ Deletes a file or directory. This API uses a promise to return the result. }; ``` -## FileAccessHelper.delete +### delete -delete(uri: string, callback: AsyncCallback<number>) : void; +delete(uri: string, callback: AsyncCallback<number>) : void Deletes a file or directory. This API uses an asynchronous callback to return the result. @@ -754,15 +950,19 @@ Deletes a file or directory. This API uses an asynchronous callback to return th | Name| Type| Mandatory| Description| | --- | --- | --- | -- | | uri | string | Yes| URI of the file or directory to delete.| -| callback | AsyncCallback<number> | Yes| Promise used to return the result.| +| callback | AsyncCallback<number> | Yes| Callback invoked to return the result.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** ```js // The media library URI is used as an example. - //In the sample code, targetUri indicates a file in the Download directory. The URI is the URI in fileInfo. + // In the sample code, targetUri indicates a file in the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let targetUri = "datashare:///media/file/100"; + let targetUri = "file://media/file/100"; try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. fileAccessHelper.delete(targetUri, function (err, code) { @@ -777,11 +977,11 @@ Deletes a file or directory. This API uses an asynchronous callback to return th }; ``` -## FileAccessHelper.move +### move move(sourceFile: string, destFile: string) : Promise<string> -Moves a file or directory. This API uses a promise to return the result. +Moves a file or directory. This API uses a promise to return the result. Currently, this API does not support move of files or directories across devices. **System capability**: SystemCapability.FileManagement.UserFileService @@ -792,7 +992,7 @@ Moves a file or directory. This API uses a promise to return the result. | Name| Type| Mandatory| Description| | --- | --- | --- | -- | | sourceFile | string | Yes| URI of the file or directory to move.| -| destFile | string | Yes| URI of the directory, to which the file or directory will be moved.| +| destFile | string | Yes| URI of the destination directory, to which the file or directory will be moved.| **Return value** @@ -800,14 +1000,18 @@ Moves a file or directory. This API uses a promise to return the result. | ----- | ------ | | Promise<string> | Promise used to return the URI of the file or directory in the destination directory.| +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js // The media library URI is used as an example. - //In the sample code, sourceFile destFile indicates the file or directory in the Download directory. The URI is the URI in fileInfo. + // In the sample code, sourceFile destFile indicates the file or directory in the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let sourceFile = "datashare:///media/file/102"; - let destFile = "datashare:///media/file/101"; + let sourceFile = "file://media/file/102"; + let destFile = "file://media/file/101"; try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. let fileUri = await fileAccessHelper.move(sourceFile, destFile); @@ -817,11 +1021,11 @@ Moves a file or directory. This API uses a promise to return the result. }; ``` -## FileAccessHelper.move +### move -move(sourceFile: string, destFile: string, callback: AsyncCallback<string>) : void; +move(sourceFile: string, destFile: string, callback: AsyncCallback<string>) : void -Moves a file or directory. This API uses an asynchronous callback to return the result. +Moves a file or directory. This API uses an asynchronous callback to return the result. Currently, this API does not support move of files or directories across devices. **System capability**: SystemCapability.FileManagement.UserFileService @@ -832,17 +1036,21 @@ Moves a file or directory. This API uses an asynchronous callback to return the | Name| Type| Mandatory| Description| | --- | --- | --- | -- | | sourceFile | string | Yes| URI of the file or directory to move.| -| destFile | string | Yes| URI of the directory, to which the file or directory will be moved.| -| callback | AsyncCallback<string> | Yes| Promise used to return the URI of the file or directory in the destination directory.| +| destFile | string | Yes| URI of the destination directory, to which the file or directory will be moved.| +| callback | AsyncCallback<string> | Yes| Callback invoked to return the URI of the file or directory in the destination directory.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** ```js // The media library URI is used as an example. - //In the sample code, sourceFile destFile indicates the file or directory in the Download directory. The URI is the URI in fileInfo. + // In the sample code, sourceFile destFile indicates the file or directory in the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let sourceFile = "datashare:///media/file/102"; - let destFile = "datashare:///media/file/101"; + let sourceFile = "file://media/file/102"; + let destFile = "file://media/file/101"; try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. fileAccessHelper.move(sourceFile, destFile, function (err, fileUri) { @@ -857,7 +1065,7 @@ Moves a file or directory. This API uses an asynchronous callback to return the }; ``` -## FileAccessHelper.rename +### rename rename(uri: string, displayName: string) : Promise<string> @@ -880,13 +1088,17 @@ Renames a file or directory. This API uses a promise to return the result. | --- | -- | | Promise<string> | Promise used to return the URI of the renamed file or directory.| +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js // The media library URI is used as an example. // In the sample code, sourceDir indicates a file in the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let sourceDir = "datashare:///media/file/100"; + let sourceDir = "file://media/file/100"; try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. let DestDir = await fileAccessHelper.rename(sourceDir, "testDir"); @@ -896,9 +1108,9 @@ Renames a file or directory. This API uses a promise to return the result. }; ``` -## FileAccessHelper.rename +### rename -rename(uri: string, displayName: string, callback: AsyncCallback<string>) : void; +rename(uri: string, displayName: string, callback: AsyncCallback<string>) : void Renames a file or directory. This API uses an asynchronous callback to return the result. @@ -912,7 +1124,11 @@ Renames a file or directory. This API uses an asynchronous callback to return th | --- | --- | --- | -- | | uri | string | Yes| URI of the file or directory to rename.| | displayName | string | Yes| New name of the file or directory, which can contain the file name extension.| -| callback | AsyncCallback<string> | Yes| Promise used to return the URI of the renamed file or directory.| +| callback | AsyncCallback<string> | Yes| Callback invoked to return the URI of the renamed file or directory.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -920,7 +1136,7 @@ Renames a file or directory. This API uses an asynchronous callback to return th // The media library URI is used as an example. // In the sample code, sourceDir indicates a file in the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let sourceDir = "datashare:///media/file/100"; + let sourceDir = "file://media/file/100"; try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. fileAccessHelper.rename(sourceDir, "testDir", function (err, DestDir) { @@ -935,7 +1151,7 @@ Renames a file or directory. This API uses an asynchronous callback to return th }; ``` -## FileAccessHelper.access +### access access(sourceFileUri: string) : Promise<boolean> @@ -949,7 +1165,7 @@ Checks whether a file or directory exists. This API uses a promise to return the | Name| Type| Mandatory| Description| | --- | --- | --- | -- | -| sourceFileUri | string | Yes| URI of the file or directory.| +| sourceFileUri | string | Yes| URI of the file or directory to check.| **Return value** @@ -957,13 +1173,17 @@ Checks whether a file or directory exists. This API uses a promise to return the | --- | -- | | Promise<boolean> | Promise used to return the result.| +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). + **Example** ```js // The media library URI is used as an example. // In the sample code, sourceDir indicates a file in the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let sourceDir = "datashare:///media/file/100"; + let sourceDir = "file://media/file/100"; try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. let existJudgment = await fileAccessHelper.access(sourceDir); @@ -976,9 +1196,9 @@ Checks whether a file or directory exists. This API uses a promise to return the }; ``` -## FileAccessHelper.access +### access -access(sourceFileUri: string, callback: AsyncCallback<boolean>) : void; +access(sourceFileUri: string, callback: AsyncCallback<boolean>) : void Checks whether a file or directory exists. This API uses an asynchronous callback to return the result. @@ -990,8 +1210,12 @@ Checks whether a file or directory exists. This API uses an asynchronous callbac | Name| Type| Mandatory| Description| | --- | --- | --- | -- | -| sourceFileUri | string | Yes| URI of the file or directory.| -| callback | AsyncCallback<boolean> | Yes| Promise used to return the result.| +| sourceFileUri | string | Yes| URI of the file or directory to check.| +| callback | AsyncCallback<boolean> | Yes| Callback invoked to return the result.| + +**Error codes** + +For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md). **Example** @@ -999,7 +1223,7 @@ Checks whether a file or directory exists. This API uses an asynchronous callbac // The media library URI is used as an example. // In the sample code, sourceDir indicates a file in the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let sourceDir = "datashare:///media/file/100"; + let sourceDir = "file://media/file/100"; try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. fileAccessHelper.access(sourceDir, function (err, existJudgment) { @@ -1017,11 +1241,11 @@ Checks whether a file or directory exists. This API uses an asynchronous callbac }; ``` -## FileAccessHelper.getFileInfoFromUri10+ +### getFileInfoFromUri10+ -getFileInfoFromUri(uri: string) : Promise; +getFileInfoFromUri(uri: string) : Promise\ -Obtains a [FileInfo](#fileinfo) object based on the specified URI. This API uses a promise to return the result. +Obtains a **FileInfo** object based on the specified URI. This API uses a promise to return the result. **System capability**: SystemCapability.FileManagement.UserFileService @@ -1037,7 +1261,7 @@ Obtains a [FileInfo](#fileinfo) object based on the specified URI. This API uses | Type| Description| | --- | -- | -| [FileInfo](#fileinfo) | Promise used to return the **FileInfo** object obtained.| +| Promise\<[FileInfo](#fileinfo)> | Promise used to return the **FileInfo** object obtained.| **Example** @@ -1045,7 +1269,7 @@ Obtains a [FileInfo](#fileinfo) object based on the specified URI. This API uses // The media library URI is used as an example. // In the sample code, sourceUri indicates the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let sourceUri = "datashare:///media/file/6"; + let sourceUri = "file://media/file/6"; try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. let fileInfo = await fileAccessHelper.getFileInfoFromUri(sourceUri); @@ -1054,11 +1278,11 @@ Obtains a [FileInfo](#fileinfo) object based on the specified URI. This API uses }; ``` -## FileAccessHelper.getFileInfoFromUri10+ +### getFileInfoFromUri10+ -getFileInfoFromUri(uri: string, callback: AsyncCallback) : void; +getFileInfoFromUri(uri: string, callback: AsyncCallback\) : void -Obtains a [FileInfo](#fileinfo) object based on the specified URI. This API uses an asynchronous callback to return the result. +Obtains a **FileInfo** object based on the specified URI. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.FileManagement.UserFileService @@ -1066,10 +1290,10 @@ Obtains a [FileInfo](#fileinfo) object based on the specified URI. This API uses **Parameters** -| Name| Type| Mandatory| Description| -| --- | --- | --- | -- | -| uri | string | Yes| URI of a file or directory.| -| callback | AsyncCallback<string> | Yes| Callback invoked to return the **FileInfo** object obtained.| + | Name| Type| Mandatory| Description| + | --- | --- | --- | -- | + | uri | string | Yes| URI of the file or directory.| + | callback | AsyncCallback<[FileInfo](#fileinfo)> | Yes| Callback invoked to return the **FileInfo** object obtained.| **Example** @@ -1077,7 +1301,7 @@ Obtains a [FileInfo](#fileinfo) object based on the specified URI. This API uses // The media library URI is used as an example. // In the sample code, sourceUri indicates the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. - let sourceUri = "datashare:///media/file/6"; + let sourceUri = "file://media/file/6"; try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. fileAccessHelper.getFileInfoFromUri(sourceUri, function (err, fileInfo) { @@ -1093,11 +1317,11 @@ Obtains a [FileInfo](#fileinfo) object based on the specified URI. This API uses ``` -## FileAccessHelper.getFileInfoFromRelativePath10+ +### getFileInfoFromRelativePath10+ -getFileInfoFromRelativePath(relativePath: string) : Promise; +getFileInfoFromRelativePath(relativePath: string) : Promise\ -Obtains a [FileInfo](#fileinfo) object based on the specified relative path. This API uses a promise to return the result. +Obtains a **FileInfo** object based on the **relativePath**. This API uses a promise to return the result. **System capability**: SystemCapability.FileManagement.UserFileService @@ -1107,19 +1331,19 @@ Obtains a [FileInfo](#fileinfo) object based on the specified relative path. Thi | Name| Type| Mandatory| Description| | --- | --- | --- | -- | -| relativePath | string | Yes| Relative path of a file or directory.| +| relativePath | string | Yes| Relative path of the file or directory.| **Return value** | Type| Description| | --- | -- | -| [FileInfo](#fileinfo) | Promise used to return the **FileInfo** object obtained.| +| Promise\<[FileInfo](#fileinfo)> | Promise used to return the **FileInfo** object obtained.| **Example** ```js - // The relative path of the media library is used as an example. - // In the sample code, relativePath indicates the download directory, which is the relativePath in fileInfo. + // The relative path of the Media Library is used as an example. + // In the sample code, relativePath indicates the Download directory, which is the relativePath in fileInfo. // You can use the relativePath obtained. let relativePath = "Download/"; try { @@ -1130,11 +1354,11 @@ Obtains a [FileInfo](#fileinfo) object based on the specified relative path. Thi }; ``` -## FileAccessHelper.getFileInfoFromRelativePath10+ +### getFileInfoFromRelativePath10+ -getFileInfoFromRelativePath(relativePath: string, callback: AsyncCallback) : void; +getFileInfoFromRelativePath(relativePath: string, callback: AsyncCallback\) : void -Obtains a [FileInfo](#fileinfo) object based on the specified relative path. This API uses an asynchronous callback to return the result. +Obtains a **FileInfo** object based on the **relativePath**. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.FileManagement.UserFileService @@ -1144,14 +1368,14 @@ Obtains a [FileInfo](#fileinfo) object based on the specified relative path. Thi | Name| Type| Mandatory| Description| | --- | --- | --- | -- | -| relativePath | string | Yes| Relative path of a file or directory.| -| callback | AsyncCallback<string> | Yes| Callback invoked to return the **FileInfo** object obtained.| +| relativePath | string | Yes| Relative path of the file or directory.| +| callback | AsyncCallback<[FileInfo](#fileinfo)> | Yes| Callback invoked to return the **FileInfo** object obtained.| **Example** ```js - // The relative path of the media library is used as an example. - // In the sample code, relativePath indicates the download directory, which is the relativePath in fileInfo. + // The relative path of the Media Library is used as an example. + // In the sample code, relativePath indicates the Download directory, which is the relativePath in fileInfo. // You can use the relativePath obtained. let relativePath = "Download/"; try { @@ -1168,7 +1392,7 @@ Obtains a [FileInfo](#fileinfo) object based on the specified relative path. Thi }; ``` -## FileAccessHelper.getThumbnail10+ +### getThumbnail10+ getThumbnail(uri: string, size: image.Size) : Promise<image.PixelMap> @@ -1189,7 +1413,7 @@ Obtains the **Pixelmap** object of a media file based on the specified URI and s | Type | Description | | :---------------------------- | :----------------- | -| Promise<image.PixelMap> | Promise used to return the **Pixelmap** object obtained.| +| Promise<[image.PixelMap](js-apis-image.md#pixelmap7)> | Promise used to return the **Pixelmap** object obtained.| **Example** @@ -1197,7 +1421,7 @@ Obtains the **Pixelmap** object of a media file based on the specified URI and s // The media library URI is used as an example. // In the sample code, targetUri indicates a media file (image, audio, or video) in the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. -let targetUri = "datashare:///media/image/100"; +let targetUri = "file://media/image/100"; let size = { width: 128, height: 128 }; try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. @@ -1210,7 +1434,7 @@ try { }; ``` -## FileAccessHelper.getThumbnail10+ +### getThumbnail10+ getThumbnail(uri: string, size: image.Size, callback: AsyncCallback<image.PixelMap>) : void @@ -1226,7 +1450,7 @@ Obtains the **Pixelmap** object of a media file based on the specified URI and s | -------- | ----------------------------------- | ---- | ------------------ | | uri | string | Yes | URI of the media file. | | size | [image.Size](js-apis-image.md#size) | Yes | Size of the thumbnail. | -| callback | AsyncCallback<image.PixelMap> | Yes | Callback invoked to return the **Pixelmap** object obtained.| +| callback | AsyncCallback<[image.PixelMap](js-apis-image.md#pixelmap7)> | Yes | Callback invoked to return the **Pixelmap** object obtained.| **Example** @@ -1234,7 +1458,7 @@ Obtains the **Pixelmap** object of a media file based on the specified URI and s // The media library URI is used as an example. // In the sample code, targetUri indicates a media file (image, audio, or video) in the Download directory. The URI is the URI in fileInfo. // You can use the URI obtained. -let targetUri = "datashare:///media/image/100"; +let targetUri = "file://media/image/100"; let size = { width: 128, height: 128 }; try { // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. @@ -1252,79 +1476,277 @@ try { }; ``` -## RootIterator.next +### query10+ -next( ) : { value: RootInfo, done: boolean } +query(uri:string, metaJson: string) : Promise<string> -Obtains the next-level device root directory. **RootIterator** is an iterator object of the device root directory. +Queries the attribute information about a file or directory based on the URI. This API uses a promise to return the result. **System capability**: SystemCapability.FileManagement.UserFileService **Required permissions**: ohos.permission.FILE_ACCESS_MANAGER +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ---------------------------------------------------- | +| uri | string | Yes | URI of the file or directory (obtained from [FileInfo](#fileinfo)).| +| metaJson | string | Yes | Attribute [FILEKEY](#filekey10) to query. | + **Return value** -| Type| Description| -| --- | -- | -| {value: RootInfo, done: boolean} | Root directory information obtained. This API traverses the directory until **done** returns **true**. The **value** field contains the root directory information.| +| Type | Description | +| :-------------------- | :------------------------------- | +| Promise<string> | Promised used to return the attribute queried and the value obtained.| + +**Example** -## FileIterator.next +```js +var imageFileRelativePath = "Download/queryTest/image/01.jpg"; +var jsonStrSingleRelativepath = JSON.stringify({ [fileAccess.FileKey.RELATIVE_PATH]: "" }); +try { + // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. + var fileInfo = await fileAccessHelper.getFileInfoFromRelativePath(imageFileRelativePath); + let queryResult = await fileAccessHelper.query(fileInfo.uri, jsonStrSingleRelativepath); + console.log("query_file_single faf query, queryResult.relative_path: " + JSON.parse(queryResult).relative_path); +} catch (error) { + console.error("query_file_single faf query failed, error.code :" + error.code + ", errorMessage :" + error.message); +}; +``` -next( ) : { value: FileInfo, done: boolean } +### query10+ -Obtains the information about the next-level file or directory. **FileIterator** is an iterator object of a directory. +query(uri:string, metaJson: string, callback: AsyncCallback<string>) : void + +Queries the attribute information about a file or directory based on the URI. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.FileManagement.UserFileService **Required permissions**: ohos.permission.FILE_ACCESS_MANAGER +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------------- | ---- | ---------------------------------------------------- | +| uri | string | Yes | URI of the file or directory (obtained from [FileInfo](#fileinfo)).| +| metaJson | string | Yes | Attribute [FILEKEY](#filekey10) to query. | +| callback | AsyncCallback<string> | Yes | Callback invoked to return the attribute queried and the value obtained. | + +**Example** + +```js +var imageFileRelativePath = "Download/queryTest/image/01.jpg"; +var jsonStrSingleRelativepath = JSON.stringify({ [fileAccess.FileKey.RELATIVE_PATH]: "" }); +try { + // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. + var fileInfo = await fileAccessHelper.getFileInfoFromRelativePath(imageFileRelativePath); + fileAccessHelper.query(fileInfo.uri, jsonStrSingleRelativepath, (err, queryResult)=>{ + if (err) { + console.log("query_file_single faf query Failed, errCode:" + err.code + ", errMessage:" + err.message); + return; + } + console.log("query_file_single faf query, queryResult.relative_path: " + JSON.parse(queryResult).relative_path); + }) +} catch (error) { + console.error("query_file_single faf query failed, error.code :" + error.code + ", errorMessage :" + error.message); +}; +``` + +### copy10+ + +copy(sourceUri: string, destUri: string, force?: boolean) : Promise<Array<CopyResult>> + +Copies a file or directory. This API uses a promise to return the result. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Required permissions**: ohos.permission.FILE_ACCESS_MANAGER + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | ------- | ---- | ------------------------------------------------------------ | +| sourceUri | string | Yes | URI of the file or directory to copy, for example, **file://media/file/102**. | +| destUri | string | Yes | URI of the destination directory, for example, **file://media/file/101**. | +| force | boolean | No | Whether to forcibly overwrite the file with the same name.
If **force** is **true**, the file with the same name will be overwritten. If **force** is **false** or not specified, the file with the same name will not be overwritten.| + **Return value** -| Type| Description| -| --- | -- | -| {value: FileInfo, done: boolean} | File or directory information obtained. This API traverses the specified directory until **done** returns **true**. The **value** field contains the file or directory information obtained.| +| Type | Description | +| :------------------------------------------------------ | :----------------------------------------------------------- | +| Promise<Array<[CopyResult](#copyresult10)>> | Promise used to return the result. If the file or directory is copied successfully, no information is returned. If the file copy fails, **copyResult** is returned.| -## RootInfo +Example 1: Copy a file with **force** unspecified. -Represents the root attribute information and interface capabilities of a device. +```js +// The media library URI is used as an example. +// In the sample code, sourceFile indicates the file (directory) in the Download directory to copy, destFile indicates the destination directory in the Download directory, and uri is to URI in fileInfo. +// You can use the URI obtained. +let sourceFile = "file://media/file/102"; +let destFile = "file://media/file/101"; +try { + // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. + let copyResult = await fileAccessHelper.copy(sourceFile, destFile); + if (copyResult.length === 0) { + console.log("copy success"); + } else { + for (let i = 0; i < copyResult.length; i++) { + console.error("errCode" + copyResult[i].errCode); + console.error("errMsg" + copyResult[i].errMsg); + console.error("sourceUri" + copyResult[i].sourceUri); + console.error("destUri" + copyResult[i].destUri); + } + } +} catch (error) { + console.error("copy failed, errCode:" + error.code + ", errMessage:" + error.message); +} +``` + +Example 2: Copy a file or directory when **force** set to **true**. + +```js +// The media library URI is used as an example. +// In the sample code, sourceFile indicates the file (directory) in the Download directory to copy, destFile indicates the destination directory in the Download directory, and uri is to URI in fileInfo. +// You can use the URI obtained. +let sourceFile = "file://media/file/102"; +let destFile = "file://media/file/101"; +try { + // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. + let copyResult = await fileAccessHelper.copy(sourceFile, destFile, true); + if (copyResult.length === 0) { + console.log("copy success"); + } else { + for (let i = 0; i < copyResult.length; i++) { + console.error("errCode" + copyResult[i].errCode); + console.error("errMsg" + copyResult[i].errMsg); + console.error("sourceUri" + copyResult[i].sourceUri); + console.error("destUri" + copyResult[i].destUri); + } + } +} catch (error) { + console.error("copy failed, errCode:" + error.code + ", errMessage:" + error.message); +} +``` + +### copy10+ + +copy(sourceUri: string, destUri: string, callback: AsyncCallback<Array<CopyResult>>) : void + +Copies a file or directory. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.FileManagement.UserFileService **Required permissions**: ohos.permission.FILE_ACCESS_MANAGER -### Attributes +**Parameters** -| Name| Type | Readable| Writable| Description | -| ------ | ------ | -------- | ------ | -------- | -| deviceType | number | Yes| No|Device type.| -| uri | string | Yes| No| Root directory URI of the device.| -| relativePath10+ | string | Yes| No| Relative path of the root directory.| -| displayName | string | Yes| No| Device name.| -| deviceFlags | number | Yes| No| Capabilities supported by the device.| +| Name | Type | Mandatory| Description | +| --------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | +| sourceUri | string | Yes | URI of the file or directory to copy, for example, **file://media/file/102**. | +| destUri | string | Yes | URI of the destination directory, for example, **file://media/file/101**. | +| callback | AsyncCallback<Array<[CopyResult](#copyresult10)>> | Yes | Callback invoked to return the result. If the file or directory is copied successfully, no information is returned. If the file copy fails, **copyResult** is returned.| -## FileInfo +**Example** -Represents the file or directory attribute information and interface capabilities. +```js +// The media library URI is used as an example. +// In the sample code, sourceFile indicates the file (directory) in the Download directory to copy, destFile indicates the destination directory in the Download directory, and uri is to URI in fileInfo. +// You can use the URI obtained. +let sourceFile = "file://media/file/102"; +let destFile = "file://media/file/101"; +try { + // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. + fileAccessHelper.copy(sourceFile, destFile, async (err, copyResult) => { + if (err) { + console.error("copy failed, errCode:" + err.code + ", errMessage:" + err.message); + return; + } + if (copyResult.length === 0) { + console.log("copy success"); + } else { + for (let i = 0; i < copyResult.length; i++) { + console.error("errCode" + copyResult[i].errCode); + console.error("errMsg" + copyResult[i].errMsg); + console.error("sourceUri" + copyResult[i].sourceUri); + console.error("destUri" + copyResult[i].destUri); + } + } + }); +} catch (error) { + console.error("copy failed, errCode:" + error.code + ", errMessage:" + error.message); +} +``` + +### copy10+ + +copy(sourceUri: string, destUri: string, force: boolean, callback: AsyncCallback<Array<CopyResult>>) : void + +Copies a file or directory. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.FileManagement.UserFileService **Required permissions**: ohos.permission.FILE_ACCESS_MANAGER -### Attributes +**Parameters** -| Name| Type | Readable| Writable| Description | -| ------ | ------ | -------- | ------ | -------- | -| uri | string | Yes| No| URI of the file or directory.| -| relativePath10+ | string | Yes| No| Relative path of a file or directory.| -| fileName | string | Yes| No| Name of a file or directory.| -| mode | number | Yes| No| Permissions on the file or directory.| -| size | number | Yes| No| Size of the file or directory.| -| mtime | number | Yes| No| Time when the file or directory was last modified.| -| mimeType | string | Yes| No| MIME type of the file or directory.| +| Name | Type | Mandatory| Description | +| --------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | +| sourceUri | string | Yes | URI of the file or directory to copy, for example, **file://media/file/102**. | +| destUri | string | Yes | URI of the destination directory, for example, **file://media/file/101**. | +| force | boolean | Yes | Whether to forcibly overwrite the file with the same name.
If **force** is **true**, the file with the same name will be overwritten. If **force** is **false** or not specified, the file with the same name will not be overwritten.| +| callback | AsyncCallback<Array<[CopyResult](#copyresult10)>> | Yes | Callback invoked to return the result. If the file or directory is copied successfully, no information is returned. If the file copy fails, **copyResult** is returned.| + +**Example** + +```js +// The media library URI is used as an example. +// In the sample code, sourceFile indicates the file (directory) in the Download directory to copy, destFile indicates the destination directory in the Download directory, and uri is to URI in fileInfo. +// You can use the URI obtained. +let sourceFile = "file://media/file/102"; +let destFile = "file://media/file/101"; +try { + // Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper. + fileAccessHelper.copy(sourceFile, destFile, true, async (err, copyResult) => { + if (err) { + console.error("copy failed, errCode:" + err.code + ", errMessage:" + err.message); + return; + } + if (copyResult.length === 0) { + console.log("copy success"); + } else { + for (let i = 0; i < copyResult.length; i++) { + console.error("errCode" + copyResult[i].errCode); + console.error("errMsg" + copyResult[i].errMsg); + console.error("sourceUri" + copyResult[i].sourceUri); + console.error("destUri" + copyResult[i].destUri); + } + } + }); +} catch (error) { + console.error("copy failed, errCode:" + error.code + ", errMessage:" + error.message); +} +``` + +## CopyResult10+ + +Defines the information returned when the file copy operation fails. If the copy operation is successful, no information is returned. + +**System capability**: SystemCapability.FileManagement.UserFileService + +**Required permissions**: ohos.permission.FILE_ACCESS_MANAGER + +| Name | Type | Readable| Writable| Description | +| --------- | ------ | ---- | ---- | ----------------- | +| sourceUri | string | Yes | No | URI of the source file or directory. | +| destUri | string | Yes | No | URI of the conflict file. If the error is not caused by a conflict, **destUri** is empty.| +| errCode | number | Yes | No | Error code. | +| errMsg | string | Yes | No | Error information. | ## OPENFLAGS -Enumerates the modes for opening a file. +Enumerates the file open modes. + +**Model restriction**: This API can be used only in the stage model. **System capability**: SystemCapability.FileManagement.UserFileService @@ -1333,3 +1755,22 @@ Enumerates the modes for opening a file. | READ | 0o0 | Read mode.| | WRITE | 0o1 | Write mode.| | WRITE_READ | 0o2 | Read/Write mode.| + +## FILEKEY10+ + +Enumerates the keys of the file attributes to query. + +**Model restriction**: This API can be used only in the stage model. + +**System capability**: SystemCapability.FileManagement.UserFileService + +| Name | Value | Description | +| ------------- | ------------- | ----------------------------------- | +| DISPLAY_NAME | 'display_name' | Name of the file. | +| DATE_ADDED | 'date_added' | Date when the file was created, for example, **1501925454**. | +| DATE_MODIFIED | 'date_modified' | Date when a file was modified, for example, **1665310670**. | +| RELATIVE_PATH | 'relative_path' | Relative path of the file, for example, **Pictures/Screenshots/**.| +| FILE_SIZE | 'size' | Size of a file, in bytes. | +| WIDTH | 'width' | Width of the image file, in pixels. | +| HEIGHT | 'height' | Height of the image file, in pixels. | +| DURATION | 'duration' | Duration of the audio or video file, in milliseconds. | diff --git a/en/application-dev/reference/apis/js-apis-fileShare.md b/en/application-dev/reference/apis/js-apis-fileShare.md index b9d9fb65f7c532d3ffd43ffdb195615b4c07b1aa..9acb27eb8ea457fd47a9a1677d8d4dd2fa9941ab 100644 --- a/en/application-dev/reference/apis/js-apis-fileShare.md +++ b/en/application-dev/reference/apis/js-apis-fileShare.md @@ -51,7 +51,7 @@ For details about the error codes, see [File Management Error Codes](../errorcod import wantConstant from '@ohos.app.ability.wantConstant'; -let uri = 'datashare:///media/image/8'; +let uri = 'file://media/image/8'; let bundleName = 'com.demo.test'; try { fileShare.grantUriPermission(uri, bundleName, wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION | wantConstant.Flags.FLAG_AUTH_WRITE_URI_PERMISSION, (err) => { @@ -111,7 +111,7 @@ For details about the error codes, see [File Management Error Codes](../errorcod ```js import wantConstant from '@ohos.app.ability.wantConstant'; -let uri = 'datashare:///media/image/8'; +let uri = 'file://media/image/8'; let bundleName = 'com.demo.test'; try { fileShare.grantUriPermission(uri, bundleName, wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION | 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-ability-dataAbilityHelper.md b/en/application-dev/reference/apis/js-apis-inner-ability-dataAbilityHelper.md index 6001a514c8b5f07874460271d0ebce3cf96c0987..17f012a1af194cfbb0ebb93dc319a5691c3b5913 100644 --- a/en/application-dev/reference/apis/js-apis-inner-ability-dataAbilityHelper.md +++ b/en/application-dev/reference/apis/js-apis-inner-ability-dataAbilityHelper.md @@ -7,6 +7,12 @@ The **DataAbilityHelper** object is obtained through [acquireDataAbilityHelper]( > The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The APIs of this module can be used only in the FA model. +## Modules to Import + +```ts +import ability from '@ohos.ability.ability'; +``` + ## Usage Import the following modules based on the actual situation before using the current module: @@ -35,7 +41,7 @@ Opens a file with a specified URI. This API uses an asynchronous callback to ret ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); let mode = 'rw'; @@ -73,7 +79,7 @@ Opens a file with a specified URI. This API uses a promise to return a file desc ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); let mode = 'rw'; @@ -102,7 +108,7 @@ Registers an observer to listen for changes in the data specified by a given URI ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); function onChangeNotify() { @@ -135,7 +141,7 @@ Deregisters the observer that listens for changes in the data specified by a giv ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); function onChangeNotify() { @@ -171,7 +177,7 @@ Obtains the media resource type of the data specified by a given URI. This API u ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); DAHelper.getType('dataability:///com.example.DataAbility', (error, data) => { @@ -207,7 +213,7 @@ Obtains the media resource type of the data specified by a given URI. This API u ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); DAHelper.getType('dataability:///com.example.DataAbility').then((data) => { @@ -235,7 +241,7 @@ Obtains the supported media resource types of a specified file. This API uses an ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); DAHelper.getFileTypes( 'dataability:///com.example.DataAbility', 'image/*', (error, data) => { @@ -272,7 +278,7 @@ Obtains the supported media resource types of a specified file. This API uses a ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); DAHelper.getFileTypes('dataability:///com.example.DataAbility', 'image/*').then((data) => { @@ -299,7 +305,7 @@ Converts the URI that refers to a Data ability into a normalized URI. This API u ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); DAHelper.normalizeUri('dataability:///com.example.DataAbility', (error, data) => { @@ -335,7 +341,7 @@ Converts the URI that refers to a Data ability into a normalized URI. This API u ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); DAHelper.normalizeUri('dataability:///com.example.DataAbility',).then((data) => { @@ -362,7 +368,7 @@ Converts a normalized URI generated by **DataAbilityHelper.normalizeUri(uri: str ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); DAHelper.denormalizeUri('dataability:///com.example.DataAbility', (error, data) => { @@ -398,7 +404,7 @@ Converts a normalized URI generated by **DataAbilityHelper.normalizeUri(uri: str ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); DAHelper.denormalizeUri('dataability:///com.example.DataAbility',).then((data) => { @@ -425,7 +431,7 @@ Notifies the registered observer of a change to the data specified by the URI. T ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); DAHelper.notifyChange('dataability:///com.example.DataAbility', (error) => { @@ -461,7 +467,7 @@ Notifies the registered observer of a change to the data specified by the URI. T ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); DAHelper.notifyChange('dataability:///com.example.DataAbility').then(() => { @@ -489,7 +495,7 @@ Inserts a single data record into the database. This API uses an asynchronous ca ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); const valueBucket = { @@ -532,7 +538,7 @@ Inserts a single data record into the database. This API uses a promise to retur ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); const valueBucket = { @@ -566,7 +572,7 @@ Inserts multiple data records into the database. This API uses an asynchronous c ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); let cars = new Array({'name': 'roe11', 'age': 21, 'salary': 20.5, 'blobType': 'u8',}, @@ -606,7 +612,7 @@ Inserts multiple data records into the database. This API uses a promise to retu ```ts import featureAbility from '@ohos.ability.featureAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); let cars = new Array({'name': 'roe11', 'age': 21, 'salary': 20.5, 'blobType': 'u8',}, @@ -638,7 +644,7 @@ Deletes one or more data records from the database. This API uses an asynchronou ```ts import featureAbility from '@ohos.ability.featureAbility'; import ohos_data_ability from '@ohos.data.dataAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); let da = new ohos_data_ability.DataAbilityPredicates(); @@ -677,7 +683,7 @@ Deletes one or more data records from the database. This API uses a promise to r ```ts import featureAbility from '@ohos.ability.featureAbility'; import ohos_data_ability from '@ohos.data.dataAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); let da = new ohos_data_ability.DataAbilityPredicates(); @@ -708,7 +714,7 @@ Updates data records in the database. This API uses an asynchronous callback to ```ts import featureAbility from '@ohos.ability.featureAbility'; import ohos_data_ability from '@ohos.data.dataAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); const va = { @@ -754,7 +760,7 @@ Updates data records in the database. This API uses a promise to return the resu ```ts import featureAbility from '@ohos.ability.featureAbility'; import ohos_data_ability from '@ohos.data.dataAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); const va = { @@ -791,7 +797,7 @@ Queries data in the database. This API uses an asynchronous callback to return t ```ts import featureAbility from '@ohos.ability.featureAbility'; import ohos_data_ability from '@ohos.data.dataAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); let cars=new Array('value1', 'value2', 'value3', 'value4'); @@ -834,7 +840,7 @@ Queries data in the database. This API uses a promise to return the result. ```ts import featureAbility from '@ohos.ability.featureAbility'; import ohos_data_ability from '@ohos.data.dataAbility'; -let DAHelper = featureAbility.acquireDataAbilityHelper( +let DAHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.DataAbility' ); let cars = new Array('value1', 'value2', 'value3', 'value4'); @@ -859,15 +865,15 @@ Calls an extended API of the DataAbility. This API uses an asynchronous callback | uri | string | Yes | URI of the DataAbility. Example: 'dataability:///com.example.xxx.xxxx'. | | method | string | Yes | Name of the API to call. | | arg | string | Yes | Parameter to pass in. | -| extras | [PacMap](#pacmap) | Yes | Key-value pair parameter. | -| callback | AsyncCallback\<[PacMap](#pacmap)> | Yes| Callback used to return the result. | +| extras | [PacMap](js-apis-inner-application-pacMap.md) | Yes | Key-value pair parameter. | +| callback | AsyncCallback\<[PacMap](js-apis-inner-application-pacMap.md)> | Yes| Callback used to return the result. | **Example** ```ts import featureAbility from '@ohos.ability.featureAbility'; -let dataAbilityHelper = featureAbility.acquireDataAbilityHelper( +let dataAbilityHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.jsapidemo.UserDataAbility' ); dataAbilityHelper.call('dataability:///com.example.jsapidemo.UserDataAbility', @@ -895,20 +901,20 @@ Calls an extended API of the DataAbility. This API uses a promise to return the | uri | string | Yes | URI of the DataAbility. Example: 'dataability:///com.example.xxx.xxxx'. | | method | string | Yes | Name of the API to call. | | arg | string | Yes | Parameter to pass in. | -| extras | [PacMap](#pacmap) | Yes | Key-value pair parameter. | +| extras | [PacMap](js-apis-inner-application-pacMap.md) | Yes | Key-value pair parameter. | **Return value** | Type| Description| |------ | ------- | -|Promise\<[PacMap](#pacmap)> | Promise used to return the result.| +|Promise\<[PacMap](js-apis-inner-application-pacMap.md)> | Promise used to return the result.| **Example** ```ts import featureAbility from '@ohos.ability.featureAbility'; -let dataAbilityHelper = featureAbility.acquireDataAbilityHelper( +let dataAbilityHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.jsapidemo.UserDataAbility' ); dataAbilityHelper.call('dataability:///com.example.jsapidemo.UserDataAbility', @@ -942,7 +948,7 @@ import featureAbility from '@ohos.ability.featureAbility'; // Select the operations to be performed on the database according to the DataAbilityOperation array. let op=new Array(); -let dataAbilityHelper = featureAbility.acquireDataAbilityHelper( +let dataAbilityHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.jsapidemo.UserDataAbility' ); dataAbilityHelper.executeBatch('dataability:///com.example.jsapidemo.UserDataAbility', op, (error, data) => { @@ -982,7 +988,7 @@ import featureAbility from '@ohos.ability.featureAbility'; // Select the operations to be performed on the database according to the DataAbilityOperation array. let op=new Array(); -let dataAbilityHelper = featureAbility.acquireDataAbilityHelper( +let dataAbilityHelper: ability.DataAbilityHelper = featureAbility.acquireDataAbilityHelper( 'dataability:///com.example.jsapidemo.UserDataAbility' ); dataAbilityHelper.executeBatch('dataability:///com.example.jsapidemo.UserDataAbility', op).then((data) => { @@ -992,13 +998,3 @@ dataAbilityHelper.executeBatch('dataability:///com.example.jsapidemo.UserDataAbi }); ``` - -## PacMap - -[key: string]: number | string | boolean | Array\ | null; - -**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel - -| Name| Type| Mandatory| Description| -| ------ | ------ | ------ | ------ | -| [key: string] | number \| string \| boolean \| Array\ \| null | Yes| Data stored in key-value pairs.| 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-pacMap.md b/en/application-dev/reference/apis/js-apis-inner-application-pacMap.md new file mode 100644 index 0000000000000000000000000000000000000000..afdf5e6c84413edfcb7303ea1069fca74898bd7c --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-pacMap.md @@ -0,0 +1,9 @@ +## PacMap + +[key: string]: number | string | boolean | Array\ | null; + +**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel + +| Name| Type| Mandatory| Description| +| ------ | ------ | ------ | ------ | +| [key: string] | number \| string \| boolean \| Array\ \| null | Yes| Data stored in key-value pairs.| 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-medialibrary.md b/en/application-dev/reference/apis/js-apis-medialibrary.md index 240108ae1849dfb2fd04d927728c653cdb4627f7..c90acd7d15a4fa31f489f952569a1f4511eb77c7 100644 --- a/en/application-dev/reference/apis/js-apis-medialibrary.md +++ b/en/application-dev/reference/apis/js-apis-medialibrary.md @@ -713,8 +713,8 @@ Starts image preview, with the first image to preview specified. This API can be ```js let images = [ - 'datashare:///media/xxxx/2', - 'datashare:///media/xxxx/3' + 'file://media/xxxx/2', + 'file://media/xxxx/3' ]; /* Preview online images. let images = [ @@ -756,8 +756,8 @@ Starts image preview. This API can be used to preview local images whose URIs st ```js let images = [ - 'datashare:///media/xxxx/2', - 'datashare:///media/xxxx/3' + 'file://media/xxxx/2', + 'file://media/xxxx/3' ]; /* Preview online images. let images = [ @@ -804,8 +804,8 @@ Starts image preview, with the first image to preview specified. This API can be ```js let images = [ - 'datashare:///media/xxxx/2', - 'datashare:///media/xxxx/3' + 'file://media/xxxx/2', + 'file://media/xxxx/3' ]; /* Preview online images. let images = [ @@ -1046,7 +1046,7 @@ Provides APIs for encapsulating file asset attributes. | Name | Type | Readable| Writable| Description | | ------------------------- | ------------------------ | ---- | ---- | ------------------------------------------------------ | | id | number | Yes | No | File asset ID. | -| uri | string | Yes | No | File asset URI, for example, **datashare:///media/image/2**. | +| uri | string | Yes | No | File asset URI, for example, **file://media/image/2**. | | mimeType | string | Yes | No | Extended file attributes. | | mediaType8+ | [MediaType](#mediatype8) | Yes | No | Media type. | | displayName | string | Yes | Yes | Display file name, including the file name extension. | diff --git a/en/application-dev/reference/apis/js-apis-mediaquery.md b/en/application-dev/reference/apis/js-apis-mediaquery.md index eb17dcdd6d568a442bae781edbd20bf9c8554c91..e5e74dc82b8abbcb15e48308484df7f587daf379 100644 --- a/en/application-dev/reference/apis/js-apis-mediaquery.md +++ b/en/application-dev/reference/apis/js-apis-mediaquery.md @@ -26,7 +26,7 @@ Sets the media query condition. This API returns the corresponding media query l | Name | Type | Mandatory | Description | | --------- | ------ | ---- | ---------------------------------------- | -| condition | string | Yes | Media query condition. For details, see [Syntax of Media Query Conditions](../../ui/ui-ts-layout-mediaquery.md#syntax-of-media-query-conditions).| +| condition | string | Yes | Media query condition. For details, see [Syntax of Media Query Conditions](../../ui/arkts-layout-development-media-query.md#syntax-of-media-query-conditions).| **Return value** @@ -158,3 +158,5 @@ struct MediaQueryExample { } } ``` + + \ No newline at end of file diff --git a/en/application-dev/reference/apis/js-apis-nfcTag.md b/en/application-dev/reference/apis/js-apis-nfcTag.md index f7f5b2b9362ed875d776c645be7d596de2755bfd..1075dd58f8f78bd7597903806a51d0c6ca5c2955 100644 --- a/en/application-dev/reference/apis/js-apis-nfcTag.md +++ b/en/application-dev/reference/apis/js-apis-nfcTag.md @@ -767,7 +767,7 @@ Defines the **TagInfo** object, which provides information about the tag technol | uid9+ | number[] | Yes| No| Tag unique identifier (UID), which consists of hexadecimal numbers ranging from **0x00** to **0xFF**.| | technology9+ | number[] | Yes| No| Supported technologies. Each number is a constant indicating the supported technology.| | supportedProfiles | number[] | Yes| No| Supported profiles. This parameter is not supported since API version 9. Use [technology](#taginfo).| -| extrasData9+ | [PacMap](js-apis-inner-ability-dataAbilityHelper.md#pacmap)[] | Yes| No| Extended attribute value of the tag technology.
**System API**: This is a system API.| +| extrasData9+ | [PacMap](js-apis-inner-application-pacMap.md)[] | Yes| No| Extended attribute value of the tag technology.
**System API**: This is a system API.| | tagRfDiscId9+ | number | Yes| No| ID allocated when the tag is discovered.
**System API**: This is a system API.| | remoteTagService9+ | [rpc.RemoteObject](js-apis-rpc.md#remoteobject) | Yes| No| Remote object of the NFC service process used for interface communication between the client and the service.
**System API**: This is a system API.| diff --git a/en/application-dev/reference/apis/js-apis-reminderAgentManager.md b/en/application-dev/reference/apis/js-apis-reminderAgentManager.md index 7d56973be54adf176ce6c22519cb125079f19df3..4380dd084573117be6f2ea5db284969884cad0a3 100644 --- a/en/application-dev/reference/apis/js-apis-reminderAgentManager.md +++ b/en/application-dev/reference/apis/js-apis-reminderAgentManager.md @@ -570,6 +570,7 @@ Enumerates button types. | -------- | -------- | -------- | | ACTION_BUTTON_TYPE_CLOSE | 0 | Button for closing the reminder.| | ACTION_BUTTON_TYPE_SNOOZE | 1 | Button for snoozing the reminder.| +| ACTION_BUTTON_TYPE_CUSTOM10+ | 2 | Custom button. (This is a system API.)| ## ReminderType @@ -587,7 +588,7 @@ Enumerates reminder types. ## ActionButton -Defines a button displayed in the reminder notification. +Defines a button displayed for the reminder in the notification panel. **System capability**: SystemCapability.Notification.ReminderAgent @@ -595,18 +596,19 @@ Defines a button displayed in the reminder notification. | -------- | -------- | -------- | -------- | | title | string | Yes| Text on the button.| | type | [ActionButtonType](#actionbuttontype) | Yes| Button type.| +| wantAgent10+ | [WantAgent](#wantagent) | No| Ability information that is displayed after the button is clicked. (This is a system API.)| ## WantAgent -Sets the package and ability that are redirected to when the reminder notification is clicked. +Defines the information about the redirected-to ability. **System capability**: SystemCapability.Notification.ReminderAgent | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| pkgName | string | Yes| Name of the HAP that is redirected to when the reminder notification is clicked.| -| abilityName | string | Yes| Name of the ability that is redirected to when the reminder notification is clicked.| +| pkgName | string | Yes| Name of the target package.| +| abilityName | string | Yes| Name of the target ability.| ## MaxScreenWantAgent @@ -617,7 +619,7 @@ Provides the information about the target package and ability to start automatic | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| pkgName | string | Yes| Name of the HAP that is automatically started when the reminder arrives and the device is not in use.| +| pkgName | string | Yes| Name of the package that is automatically started when the reminder arrives and the device is not in use.| | abilityName | string | Yes| Name of the ability that is automatically started when the reminder arrives and the device is not in use.| @@ -630,18 +632,20 @@ Defines the reminder to publish. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | reminderType | [ReminderType](#remindertype) | Yes| Type of the reminder.| -| actionButton | [ActionButton](#actionbutton) | No| Button displayed in the reminder notification. (The parameter is optional. Up to two buttons are supported.)| -| wantAgent | [WantAgent](#wantagent) | No| Information about the ability that is redirected to when the notification is clicked.| +| actionButton | [ActionButton](#actionbutton) | No| Button displayed for the reminder in the notification panel. For common applications, a maximum of two buttons are supported. For system applications, a maximum of two buttons are supported in API version 9, and a maximum of three buttons are supported in API version 10 and later versions. | +| wantAgent | [WantAgent](#wantagent) | No| Information about the ability that is redirected to when the reminder is clicked.| | maxScreenWantAgent | [MaxScreenWantAgent](#maxscreenwantagent) | No| Information about the ability that is automatically started when the reminder arrives. If the device is in use, a notification will be displayed.| | ringDuration | number | No| Ringing duration, in seconds. The default value is **1**.| | snoozeTimes | number | No| Number of reminder snooze times. The default value is **0**.| -| timeInterval | number | No| Reminder snooze interval, in seconds. The default value is **0**.| +| timeInterval | number | No| Reminder snooze interval, in seconds. The minimum value is 5 minutes.| | title | string | No| Reminder title.| | content | string | No| Reminder content.| | expiredContent | string | No| Content to be displayed after the reminder expires.| | snoozeContent | string | No| Content to be displayed when the reminder is snoozing.| | notificationId | number | No| Notification ID used by the reminder. If there are reminders with the same notification ID, the later one will overwrite the earlier one.| -| slotType | [notification.SlotType](js-apis-notification.md#slottype) | No| Type of the slot used by the reminder.| +| slotType | [notification.SlotType](js-apis-notificationManager.md#slottype) | No| Type of the slot used by the reminder.| +| tapDismissed10+ | boolean | No| Whether the notification is automatically cleared. The value is the same as that of [NotificationRequest.tapDismissed](js-apis-inner-notification-notificationRequest.md#notificationrequest).| +| autoDeletedTime10+ | number | No| Time when the notification is automatically cleared. The value is the same as that of [NotificationRequest.autoDeletedTime](js-apis-inner-notification-notificationRequest.md#notificationrequest).| ## ReminderRequestCalendar 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-resourceschedule-workScheduler.md b/en/application-dev/reference/apis/js-apis-resourceschedule-workScheduler.md index 5ba1e47b2f1d702e226ec3359044309b44a7dacb..ab02ed0f2c5bf6bf553f6a36f6a94442db2bb378 100644 --- a/en/application-dev/reference/apis/js-apis-resourceschedule-workScheduler.md +++ b/en/application-dev/reference/apis/js-apis-resourceschedule-workScheduler.md @@ -130,7 +130,7 @@ Obtains the latest task status. This API uses an asynchronous callback to return | Name | Type | Mandatory | Description | | -------- | ------------------------------------- | ---- | ---------------------------------------- | | workId | number | Yes | Task ID. | -| callback | AsyncCallback\<[WorkInfo](#workinfo)> | Yes | Callback used to return the result. Returns the task status obtained from the **WorkSchedulerService** if the specified task ID is valid; returns **null** otherwise.| +| callback | AsyncCallback\<[WorkInfo](#workinfo)> | Yes | Callback used to return the result. Returns the task status obtained from the **WorkSchedulerService** if the specified task ID is valid; throws an exception otherwise.| **Error codes** @@ -178,7 +178,7 @@ Obtains the latest task status. This API uses a promise to return the result. | Type | Description | | ------------------------------- | ---------------------------------------- | -| Promise\<[WorkInfo](#workinfo)> | Promise used to return the result. Returns the task status obtained from the **WorkSchedulerService** if the specified task ID is valid; returns **null** otherwise.| +| Promise\<[WorkInfo](#workinfo)> | Promise used to return the result. Returns the task status obtained from the **WorkSchedulerService** if the specified task ID is valid; throws an exception otherwise.| **Error codes** diff --git a/en/application-dev/reference/apis/js-apis-rpc.md b/en/application-dev/reference/apis/js-apis-rpc.md index 3b12ce374b7adcebeb45323fe3eda08efb0c9245..c4688c804e2ea21de453a25cf2ad543193f9d2ed 100644 --- a/en/application-dev/reference/apis/js-apis-rpc.md +++ b/en/application-dev/reference/apis/js-apis-rpc.md @@ -41,7 +41,6 @@ The APIs of this module return exceptions since API version 9. The following tab ## MessageSequence9+ Provides APIs for reading and writing data in specific format. - During RPC or IPC, the sender can use the **write()** method provided by **MessageSequence** to write data in specific format to a **MessageSequence** object. The receiver can use the **read()** method provided by **MessageSequence** to read data in specific format from a **MessageSequence** object. The data formats include basic data types and arrays, IPC objects, interface tokens, and custom sequenceable objects. ### create @@ -99,9 +98,9 @@ Serializes a remote object and writes it to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | -------- | ------- | - | 1900008 | proxy or remote object is invalid | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900008 | proxy or remote object is invalid | + | 1900009 | write data to message sequence failed | **Example** @@ -140,9 +139,9 @@ Reads the remote object from **MessageSequence**. You can use this API to deseri For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900008 | proxy or remote object is invalid | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900008 | proxy or remote object is invalid | + | 1900010 | read data from message sequence failed | **Example** @@ -182,8 +181,8 @@ Writes an interface token to this **MessageSequence** object. The remote object For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -216,8 +215,8 @@ Reads the interface token from this **MessageSequence** object. The interface to For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | ----- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -268,7 +267,7 @@ Obtains the capacity of this **MessageSequence** object. **Return value** - | Type | Description| + | Type | Description | | ------ | ----- | | number | **MessageSequence** capacity obtained, in bytes.| @@ -290,7 +289,7 @@ Sets the size of the data contained in this **MessageSequence** object. **Parameters** - | Name| Type | Mandatory| Description| + | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------ | | size | number | Yes | Data size to set, in bytes.| @@ -326,8 +325,8 @@ Sets the storage capacity of this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | -------- | ------ | - | 1900011 | parcel memory alloc failed | + | -------- | -------- | + | 1900011 | parcel memory alloc failed | **Example** @@ -352,7 +351,7 @@ Obtains the writable capacity (in bytes) of this **MessageSequence** object. **Return value** - | Type| Description| + | Type | Description | | ------ | ------ | | number | Writable capacity of the **MessageSequence** instance, in bytes.| @@ -378,7 +377,7 @@ Obtains the readable capacity of this **MessageSequence** object. **Return value** - | Type| Description| + | Type | Description | | ------ | ------- | | number | Readable capacity of the **MessageSequence** instance, in bytes.| @@ -404,7 +403,7 @@ Obtains the read position of this **MessageSequence** object. **Return value** - | Type| Description| + | Type | Description | | ------ | ------ | | number | Read position obtained.| @@ -426,7 +425,7 @@ Obtains the write position of this **MessageSequence** object. **Return value** - | Type| Description| + | Type | Description | | ------ | ----- | | number | Write position obtained.| @@ -449,7 +448,7 @@ Moves the read pointer to the specified position. **Parameters** - | Name| Type| Mandatory| Description| + | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------- | | pos | number | Yes | Position from which data is to read.| @@ -481,7 +480,7 @@ Moves the write pointer to the specified position. **Parameters** - | Name| Type| Mandatory| Description| + | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ----- | | pos | number | Yes | Position from which data is to write.| @@ -511,17 +510,17 @@ Writes a byte value to this **MessageSequence** object. **Parameters** - | Name| Type | Mandatory| Description| - | ----- | ------ | ---- | ----- | - | val | number | Yes| Byte value to write.| + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ----- | + | val | number | Yes | Byte value to write.| **Error codes** For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | -------- | ------- | - | 1900009 | write data to message sequence failed | + | -------- | ------- | + | 1900009 | write data to message sequence failed | **Example** @@ -545,7 +544,7 @@ Reads the byte value from this **MessageSequence** object. **Return value** - | Type | Description| + | Type | Description | | ------ | ----- | | number | Byte value read.| @@ -587,16 +586,16 @@ Writes a short integer to this **MessageSequence** object. **Parameters** | Name| Type | Mandatory| Description| - | ------ | ------ | --- | --- | - | val | number | Yes| Short integer to write.| + | ------ | ------ | --- | --- | + | val | number | Yes | Short integer to write.| **Error codes** For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | ------ | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -629,8 +628,8 @@ Reads the short integer from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -670,8 +669,8 @@ Writes an integer to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | -------- | ------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -704,8 +703,8 @@ Reads the integer from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | ------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -745,8 +744,8 @@ Writes a long integer to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | ------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -779,8 +778,8 @@ Reads the long integer from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -811,17 +810,17 @@ Writes a floating-point number to this **MessageSequence** object. **Parameters** - | Name| Type| Mandatory| Description| - | ----- | ---- | ---- | ----- | - | val | number | Yes| Floating-point number to write.| + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ----- | + | val | number | Yes | Floating-point number to write.| **Error codes** For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | ------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -854,8 +853,8 @@ Reads the floating-pointer number from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -895,8 +894,8 @@ Writes a double-precision floating-point number to this **MessageSequence** obje For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -929,8 +928,8 @@ Reads the double-precision floating-point number from this **MessageSequence** o For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -970,8 +969,8 @@ Writes a Boolean value to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | ------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -1004,8 +1003,8 @@ Reads the Boolean value from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | -------- | ------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -1045,8 +1044,8 @@ Writes a character to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -1079,8 +1078,8 @@ Reads the character from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------ | --------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -1120,8 +1119,8 @@ Writes a string to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -1154,8 +1153,8 @@ Reads the string from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -1195,8 +1194,8 @@ Writes a **Parcelable** object to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -1241,16 +1240,16 @@ Reads a **Parcelable** object from this **MessageSequence** object to the specif | Name| Type | Mandatory| Description | | ------ | ------------------------- | ---- | ----------------------------------------- | - | dataIn | Parcelable | Yes | **Parcelable** object to read.| + | dataIn | Parcelable | Yes | **Parcelable** object to read.| **Error codes** For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | -------- | ------- | - | 1900010 | read data from message sequence failed | - | 1900012 | call js callback function failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | + | 1900012 | call js callback function failed | **Example** @@ -1304,8 +1303,8 @@ Writes a byte array to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -1339,8 +1338,8 @@ Reads a byte array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -1381,8 +1380,8 @@ Reads the byte array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | -------- | ------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -1423,8 +1422,8 @@ Writes a short array to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ----- | ----- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -1457,8 +1456,8 @@ Reads a short array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------ | ------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -1498,8 +1497,8 @@ Reads the short array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | -------- | ------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -1539,8 +1538,8 @@ Writes an integer array to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ----- | --------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -1573,8 +1572,8 @@ Reads an integer array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -1614,8 +1613,8 @@ Reads the integer array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ----- | ------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -1655,8 +1654,8 @@ Writes a long array to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | ----- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -1689,8 +1688,8 @@ Reads a long array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | ------ | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -1730,8 +1729,8 @@ Reads the long array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -1771,8 +1770,8 @@ Writes a floating-point array to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -1805,8 +1804,8 @@ Reads a floating-point array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -1846,8 +1845,8 @@ Reads the floating-point array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -1887,8 +1886,8 @@ Writes a double-precision floating-point array to this **MessageSequence** objec For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -1921,8 +1920,8 @@ Reads a double-precision floating-point array from this **MessageSequence** obje For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -1962,8 +1961,8 @@ Reads the double-precision floating-point array from this **MessageSequence** ob For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -2003,8 +2002,8 @@ Writes a Boolean array to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -2037,8 +2036,8 @@ Reads a Boolean array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -2078,8 +2077,8 @@ Reads the Boolean array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -2119,8 +2118,8 @@ Writes a character array to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | -------- | ------ | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -2153,8 +2152,8 @@ Reads a character array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -2194,8 +2193,8 @@ Reads the character array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -2236,8 +2235,8 @@ Writes a string array to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -2270,8 +2269,8 @@ Reads a string array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -2311,8 +2310,8 @@ Reads the string array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -2346,8 +2345,8 @@ Writes information to this **MessageSequence** object indicating that no excepti For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -2388,15 +2387,17 @@ Reads the exception information from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** - Obtain the service. + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { @@ -2414,7 +2415,11 @@ For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.EntryAbility", }; - FA.connectAbility(want, connect); + + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + + globalThis.context.connectServiceExtensionAbility(want, connect); ``` The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **sendMessageRequest()** of the proxy object is called to send a message. @@ -2468,8 +2473,8 @@ Writes a **Parcelable** array to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -2524,9 +2529,9 @@ Reads a **Parcelable** array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | - | 1900012 | call js callback function failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | + | 1900012 | call js callback function failed | **Example** @@ -2585,8 +2590,8 @@ Writes an array of **IRemoteObject** objects to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | ------- | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -2632,8 +2637,8 @@ Reads an array of **IRemoteObject** objects from this **MessageSequence** object For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -2685,8 +2690,8 @@ Reads the **IRemoteObject** object array from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -2731,11 +2736,11 @@ Closes a file descriptor. This API is a static method. **Example** ```ts - import fileio from '@ohos.fileio'; + import fs from '@ohos.file.fs'; let filePath = "path/to/file"; - let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); try { - rpc.MessageSequence.closeFileDescriptor(fd); + rpc.MessageSequence.closeFileDescriptor(file.fd); } catch(error) { console.info("rpc close file descriptor fail, errorCode " + error.code); console.info("rpc close file descriptor fail, errorMessage" + error.message); @@ -2767,17 +2772,17 @@ Duplicates a file descriptor. This API is a static method. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | ------- | - | 1900013 | call os dup function failed | + | -------- | -------- | + | 1900013 | call os dup function failed | **Example** ```ts - import fileio from '@ohos.fileio'; + import fs from '@ohos.file.fs'; let filePath = "path/to/file"; - let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); try { - let newFd = rpc.MessageSequence.dupFileDescriptor(fd); + let newFd = rpc.MessageSequence.dupFileDescriptor(file.fd); } catch(error) { console.info("rpc dup file descriptor fail, errorCode " + error.code); console.info("rpc dup file descriptor fail, errorMessage" + error.message); @@ -2802,13 +2807,13 @@ Checks whether this **MessageSequence** object contains file descriptors. ```ts - import fileio from '@ohos.fileio'; + import fs from '@ohos.file.fs'; let sequence = new rpc.MessageSequence(); let filePath = "path/to/file"; let r1 = sequence.containFileDescriptors(); - let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); try { - sequence.writeFileDescriptor(fd); + sequence.writeFileDescriptor(file.fd); } catch(error) { console.info("rpc write file descriptor fail, errorCode " + error.code); console.info("rpc write file descriptor fail, errorMessage" + error.message); @@ -2841,18 +2846,18 @@ Writes a file descriptor to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | -------- | ------ | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** ```ts - import fileio from '@ohos.fileio'; + import fs from '@ohos.file.fs'; let sequence = new rpc.MessageSequence(); let filePath = "path/to/file"; - let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); try { - sequence.writeFileDescriptor(fd); + sequence.writeFileDescriptor(file.fd); } catch(error) { console.info("rpc write file descriptor fail, errorCode " + error.code); console.info("rpc write file descriptor fail, errorMessage" + error.message); @@ -2878,18 +2883,18 @@ Reads the file descriptor from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** ```ts - import fileio from '@ohos.fileio'; + import fs from '@ohos.file.fs'; let sequence = new rpc.MessageSequence(); let filePath = "path/to/file"; - let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); try { - sequence.writeFileDescriptor(fd); + sequence.writeFileDescriptor(file.fd); } catch(error) { console.info("rpc write file descriptor fail, errorCode " + error.code); console.info("rpc write file descriptor fail, errorMessage" + error.message); @@ -2921,8 +2926,8 @@ Writes an anonymous shared object to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | ------- | - | 1900003 | write to ashmem failed | + | -------- | ------- | + | 1900003 | write to ashmem failed | **Example** @@ -2963,8 +2968,8 @@ Reads the anonymous shared object from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900004 | read from ashmem failed | + | -------- | -------- | + | 1900004 | read from ashmem failed | **Example** @@ -3034,8 +3039,8 @@ Writes raw data to this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | ------ | - | 1900009 | write data to message sequence failed | + | -------- | -------- | + | 1900009 | write data to message sequence failed | **Example** @@ -3075,8 +3080,8 @@ Reads raw data from this **MessageSequence** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900010 | read data from message sequence failed | + | -------- | -------- | + | 1900010 | read data from message sequence failed | **Example** @@ -3103,7 +3108,6 @@ For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode >This class is no longer maintained since API version 9. You are advised to use [MessageSequence](#messagesequence9). Provides APIs for reading and writing data in specific format. - During RPC, the sender can use the **write()** method provided by **MessageParcel** to write data in specific format to a **MessageParcel** object. The receiver can use the **read()** method provided by **MessageParcel** to read data in specific format from a **MessageParcel** object. The data formats include basic data types and arrays, IPC objects, interface tokens, and custom sequenceable objects. ### create @@ -4031,8 +4035,8 @@ Writes a sequenceable object to this **MessageParcel** object. **Return value** - | Type | Description | - | ------- | --------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the data is written successfully; returns **false** otherwise.| **Example** @@ -4072,14 +4076,14 @@ Reads member variables from this **MessageParcel** object. **Parameters** - | Name| Type | Mandatory| Description | - | ------ | ----------------------------- | ---- | --------------------------------------- | + | Name| Type | Mandatory | Description | + | ------ | ----------------------------- | ------- | ---------------------------------------------- | | dataIn | [Sequenceable](#sequenceabledeprecated) | Yes | Object that reads member variables from the **MessageParcel** object.| **Return value** - | Type | Description | - | ------- | ------------------------------------------- | + | Type | Description | + | ------- | ---------------------------------------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| **Example** @@ -4128,8 +4132,8 @@ Writes a byte array to this **MessageParcel** object. **Return value** - | Type | Description | - | ------- | --------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the data is written successfully; returns **false** otherwise.| **Example** @@ -4207,8 +4211,8 @@ Writes a short array to this **MessageParcel** object. **Return value** - | Type | Description | - | ------- | ----------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the data is written successfully; returns **false** otherwise.| **Example** @@ -4283,8 +4287,8 @@ Writes an integer array to this **MessageParcel** object. **Return value** - | Type | Description | - | ------- | ----------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the data is written successfully; returns **false** otherwise.| **Example** @@ -4429,14 +4433,14 @@ Writes a FloatArray to this **MessageParcel** object. **Parameters** - | Name| Type| Mandatory| Description| + | Name| Type| Mandatory| Description | | ---------- | -------- | ---- | --- | | floatArray | number[] | Yes | Floating-point array to write. The system processes Float data as that of the Double type. Therefore, the total number of bytes occupied by a FloatArray must be calculated as the Double type.| **Return value** - | Type | Description | - | ------- | ----------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the data is written successfully; returns **false** otherwise.| **Example** @@ -4457,7 +4461,7 @@ Reads a FloatArray from this **MessageParcel** object. **Parameters** - | Name| Type| Mandatory| Description| + | Name| Type | Mandatory| Description | | ------ | -------- | ---- | ------ | | dataIn | number[] | Yes | Floating-point array to read. The system processes Float data as that of the Double type. Therefore, the total number of bytes occupied by a FloatArray must be calculated as the Double type.| @@ -4511,8 +4515,8 @@ Writes a DoubleArray to this **MessageParcel** object. **Return value** - | Type | Description | - | ------- | ----------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the data is written successfully; returns **false** otherwise.| **Example** @@ -4587,8 +4591,8 @@ Writes a Boolean array to this **MessageParcel** object. **Return value** - | Type | Description | - | ------- | --------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the data is written successfully; returns **false** otherwise.| **Example** @@ -4663,8 +4667,8 @@ Writes a character array to this **MessageParcel** object. **Return value** - | Type | Description | - | ------- | --------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the data is written successfully; returns **false** otherwise.| **Example** @@ -4733,14 +4737,14 @@ Writes a string array to this **MessageParcel** object. **Parameters** - | Name | Type | Mandatory| Description| + | Name | Type | Mandatory| Description | | ----------- | -------- | ---- | ---------------- | | stringArray | string[] | Yes | String array to write. The length of a single element in the array must be less than 40960 bytes.| **Return value** | Type | Description| - | ------- | --------------------------------- | + | ------- | -------------------------------- | | boolean | Returns **true** if the data is written successfully; returns **false** otherwise.| **Example** @@ -4850,11 +4854,13 @@ Reads the exception information from this **MessageParcel** object. **System capability**: SystemCapability.Communication.IPC.Core **Example** - - Obtain the service. + + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { @@ -4872,7 +4878,11 @@ Reads the exception information from this **MessageParcel** object. "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.EntryAbility", }; - FA.connectAbility(want, connect); + + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + + globalThis.context.connectServiceExtensionAbility(want, connect); ``` The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **sendMessageRequest()** of the proxy object is called to send a message. @@ -4918,8 +4928,8 @@ Writes a sequenceable array to this **MessageParcel** object. **Return value** - | Type | Description | - | ------- | --------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the data is written successfully; returns **false** otherwise.| **Example** @@ -5008,14 +5018,14 @@ Writes an array of **IRemoteObject** objects to this **MessageParcel** object. **Parameters** - | Name | Type | Mandatory| Description| + | Name | Type | Mandatory| Description | | ----------- | --------------- | ---- | ----- | | objectArray | IRemoteObject[] | Yes | Array of **IRemoteObject** objects to write.| **Return value** | Type | Description | - | ------- | -------------------------------------------------------------------------------------------------------------------- | + | ------- | -------------------------------- | | boolean | Returns **true** if the data is written successfully; returns **false** otherwise.| **Example** @@ -5060,7 +5070,7 @@ Reads an **IRemoteObject** array from this **MessageParcel** object. **Parameters** - | Name | Type | Mandatory| Description| + | Name | Type | Mandatory| Description | | ------- | --------------- | ---- | --------- | | objects | IRemoteObject[] | Yes | **IRemoteObject** array to read.| @@ -5107,8 +5117,8 @@ Reads the **IRemoteObject** array from this **MessageParcel** object. **Return value** - | Type| Description| - | --------------- | -------- | + | Type | Description | + | --------------- | --------------------------- | | IRemoteObject[] | **IRemoteObject** object array obtained.| **Example** @@ -5162,10 +5172,10 @@ Closes a file descriptor. This API is a static method. **Example** ```ts - import fileio from '@ohos.fileio'; + import fs from '@ohos.file.fs'; let filePath = "path/to/file"; - let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); - rpc.MessageParcel.closeFileDescriptor(fd); + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + rpc.MessageParcel.closeFileDescriptor(file.fd); ``` ### dupFileDescriptor8+ @@ -5191,10 +5201,10 @@ Duplicates a file descriptor. This API is a static method. **Example** ```ts - import fileio from '@ohos.fileio'; + import fs from '@ohos.file.fs'; let filePath = "path/to/file"; - let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); - let newFd = rpc.MessageParcel.dupFileDescriptor(fd); + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + let newFd = rpc.MessageParcel.dupFileDescriptor(file.fd); ``` ### containFileDescriptors8+ @@ -5207,19 +5217,19 @@ Checks whether this **MessageParcel** object contains file descriptors. **Return value** - | Type | Description | - | ------- | ------------------------------------------------------------------ | + | Type | Description | + | ------- | --------------------------------------------- | | boolean |Returns **true** if the **MessageParcel** object contains file descriptors; returns **false** otherwise.| **Example** ```ts - import fileio from '@ohos.fileio'; + import fs from '@ohos.file.fs'; let parcel = new rpc.MessageParcel(); let filePath = "path/to/file"; let r1 = parcel.containFileDescriptors(); - let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); - let writeResult = parcel.writeFileDescriptor(fd); + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + let writeResult = parcel.writeFileDescriptor(file.fd); console.log("RpcTest: parcel writeFd result is : " + writeResult); let containFD = parcel.containFileDescriptors(); console.log("RpcTest: parcel after write fd containFd result is : " + containFD); @@ -5241,18 +5251,18 @@ Writes a file descriptor to this **MessageParcel** object. **Return value** - | Type | Description | - | ------- | ----------------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| **Example** ```ts - import fileio from '@ohos.fileio'; + import fs from '@ohos.file.fs'; let parcel = new rpc.MessageParcel(); let filePath = "path/to/file"; - let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); - let writeResult = parcel.writeFileDescriptor(fd); + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + let writeResult = parcel.writeFileDescriptor(file.fd); console.log("RpcTest: parcel writeFd result is : " + writeResult); ``` @@ -5273,11 +5283,11 @@ Reads the file descriptor from this **MessageParcel** object. **Example** ```ts - import fileio from '@ohos.fileio'; + import fs from '@ohos.file.fs'; let parcel = new rpc.MessageParcel(); let filePath = "path/to/file"; - let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); - let writeResult = parcel.writeFileDescriptor(fd); + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + let writeResult = parcel.writeFileDescriptor(file.fd); let readFD = parcel.readFileDescriptor(); console.log("RpcTest: parcel read fd is : " + readFD); ``` @@ -5298,8 +5308,8 @@ Writes an anonymous shared object to this **MessageParcel** object. **Return value** - | Type | Description | - | ------- | -------------------------------------------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the data is written successfully; returns **false** otherwise.| **Example** @@ -5375,8 +5385,8 @@ Writes raw data to this **MessageParcel** object. **Return value** - | Type | Description | - | ------- | ----------------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the data is written successfully; returns **false** otherwise.| **Example** @@ -5439,8 +5449,8 @@ Marshals this **Parcelable** object into a **MessageSequence** object. **Return value** - | Type | Description | - | ------- | ----------------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| **Example** @@ -5488,8 +5498,8 @@ Unmarshals this **Parcelable** object from a **MessageSequence** object. **Return value** - | Type | Description | - | ------- | --------------------------------------------- | + | Type | Description | + | ------- | ---------------------------------------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| **Example** @@ -5538,14 +5548,14 @@ Marshals the sequenceable object into a **MessageParcel** object. **Parameters** - | Name | Type | Mandatory| Description | - | ------- | ------------------------------- | ---- | ----------------------------------------- | + | Name | Type | Mandatory| Description | + | ------- | ----------------------------------------- | ---- | ----------------------------------------- | | dataOut | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object to which the sequenceable object is to be marshaled.| **Return value** - | Type | Description | - | ------- | ----------------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| **Example** @@ -5587,14 +5597,14 @@ Unmarshals this sequenceable object from a **MessageParcel** object. **Parameters** - | Name| Type | Mandatory| Description | - | ------ | ------------------------------- | ---- | --------------------------------------------- | + | Name| Type | Mandatory| Description | + | ------ | ----------------------------------------- | ---- | --------------------------------------------- | | dataIn | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object in which the sequenceable object is to be unmarshaled.| **Return value** - | Type | Description | - | ------- | --------------------------------------------- | + | Type | Description | + | ------- | ---------------------------------------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| **Example** @@ -5641,8 +5651,8 @@ Obtains a proxy or remote object. This API must be implemented by its derived cl **Return value** - | Type | Description| - | ---- | ----- | + | Type | Description | + | ----- | ----- | | [IRemoteObject](#iremoteobject) | Returns the **RemoteObject** if it is the caller; returns the [IRemoteObject](#iremoteobject), the holder of this **RemoteProxy** object, if the caller is a [RemoteProxy](#remoteproxy) object.| **Example** @@ -5658,20 +5668,22 @@ Obtains a proxy or remote object. This API must be implemented by its derived cl **Example** - Obtain the service. + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { - onConnect: function (elementName, remoteProxy) { + onConnect: function(elementName, remoteProxy) { console.log("RpcClient: js onConnect called."); proxy = remoteProxy; }, - onDisconnect: function (elementName) { + onDisconnect: function(elementName) { console.log("RpcClient: onDisconnect"); }, - onFailed: function () { + onFailed: function() { console.log("RpcClient: onFailed"); } }; @@ -5679,11 +5691,15 @@ Obtains a proxy or remote object. This API must be implemented by its derived cl "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.EntryAbility", }; - FA.connectAbility(want, connect); - ``` - The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **asObject()** of the proxy object is called to obtain the proxy or remote object. + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + globalThis.context.connectServiceExtensionAbility(want, connect); + ``` + + The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **asObject()** of the proxy object is called to obtain the proxy or remote object. + ```ts class TestProxy { remote: rpc.RemoteObject; @@ -5695,7 +5711,6 @@ Obtains a proxy or remote object. This API must be implemented by its derived cl } } let iRemoteObject = new TestProxy(proxy).asObject(); - ``` ## DeathRecipient @@ -5806,17 +5821,17 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch **Parameters** - | Name | Type| Mandatory| Description | - | ------- | ------------------------------- | ---- | ---- | - | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| + | Name | Type | Mandatory| Description | + | ------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| | data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. | | reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. | - | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | + | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | **Return value** - | Type | Description | - | ------- | --------------------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the message is sent successfully; returns **false** otherwise.| @@ -5832,12 +5847,12 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch **Parameters** - | Name | Type | Mandatory| Description | - | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | - | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| + | Name | Type | Mandatory| Description | + | ------- | ---------------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| | data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. | | reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. | - | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | + | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | **Return value** @@ -5856,12 +5871,12 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn **Parameters** - | Name | Type | Mandatory| Description | - | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | - | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| + | Name | Type | Mandatory| Description | + | ------- | ------------------------------------ | ---- | -------------------------------------------------------------------------------------- | + | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| | data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. | | reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. | - | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | + | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | **Return value** @@ -5880,13 +5895,13 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn **Parameters** - | Name | Type | Mandatory| Description | - | -------- | ---------------------------------- | ---- | -------------------------------------------------------------------------------------- | - | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| + | Name | Type | Mandatory| Description | + | -------- | ------------------------------------ | ---- | -------------------------------------------------------------------------------------- | + | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| | data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. | | reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. | - | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | - | callback | AsyncCallback<RequestResult> | Yes | Callback for receiving the sending result. | + | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | + | callback | AsyncCallback<RequestResult> | Yes | Callback for receiving the sending result. | ### sendRequest8+(deprecated) @@ -5900,13 +5915,13 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch **Parameters** - | Name | Type | Mandatory| Description | - | -------- | -------------------------------------- | ---- | -------------------------------------------------------------------------------------- | - | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| - | data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. | - | reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. | - | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | - | callback | AsyncCallback<SendRequestResult> | Yes | Callback for receiving the sending result. | + | Name | Type | Mandatory| Description | + | -------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| + | data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. | + | reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. | + | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | + | callback | AsyncCallback<SendRequestResult> | Yes | Callback for receiving the sending result. | ### registerDeathRecipient9+ @@ -5928,8 +5943,8 @@ Registers a callback for receiving death notifications of the remote object. The For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900008 | proxy or remote object is invalid | + | -------- | -------- | + | 1900008 | proxy or remote object is invalid | ### addDeathrecipient(deprecated) @@ -5950,8 +5965,8 @@ Adds a callback for receiving death notifications of the remote object. This met **Return value** - | Type | Description | - | ------- | --------------------------------------------- | + | Type | Description | + | ------- | ---------------------------------------- | | boolean | Returns **true** if the callback is added successfully; returns **false** otherwise.| @@ -5975,8 +5990,8 @@ Unregisters the callback used to receive death notifications of the remote objec For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900008 | proxy or remote object is invalid | + | -------- | -------- | + | 1900008 | proxy or remote object is invalid | ### removeDeathRecipient(deprecated) @@ -5997,8 +6012,8 @@ Removes the callback used to receive death notifications of the remote object. **Return value** - | Type | Description | - | ------- | --------------------------------------------- | + | Type | Description | + | ------- | -----------------------------------------| | boolean | Returns **true** if the callback is removed; returns **false** otherwise.| ### getDescriptor9+ @@ -6020,8 +6035,8 @@ Obtains the interface descriptor (which is a string) of this object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900008 | proxy or remote object is invalid | + | -------- | -------- | + | 1900008 | proxy or remote object is invalid | ### getInterfaceDescriptor(deprecated) @@ -6051,8 +6066,8 @@ Checks whether this object is dead. **Return value** - | Type | Description | - | ------- | ------------------------------------------- | + | Type | Description | + | ------- | ---------------------------------- | | boolean | Returns **true** if the object is dead; returns **false** otherwise.| @@ -6082,25 +6097,27 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch **Parameters** - | Name | Type | Mandatory| Description | - | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | - | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| + | Name | Type | Mandatory| Description | + | ------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| | data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. | | reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. | - | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | + | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | **Return value** - | Type | Description | - | ------- | --------------------------------------------- | + | Type | Description | + | ------- | ---------------------------------| | boolean | Returns **true** if the message is sent successfully; returns **false** otherwise.| **Example** - Obtain the service. + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { @@ -6118,11 +6135,15 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.EntryAbility", }; - FA.connectAbility(want, connect); - ``` - The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **sendMessageRequest()** of the proxy object is called to send a message. + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + globalThis.context.connectServiceExtensionAbility(want, connect); + ``` + + The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **sendMessageRequest()** of the proxy object is called to send a message. + ```ts let option = new rpc.MessageOption(); let data = rpc.MessageParcel.create(); @@ -6152,12 +6173,12 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn **Parameters** - | Name | Type | Mandatory| Description | - | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | - | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| + | Name | Type | Mandatory| Description | + | ------- | ------------------------------------ | ---- | -------------------------------------------------------------------------------------- | + | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| | data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. | - | reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. | - | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | + | reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. | + | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | **Return value** @@ -6167,10 +6188,12 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn **Example** - Obtain the service. + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { @@ -6188,9 +6211,13 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.EntryAbility", }; - FA.connectAbility(want, connect); - ``` + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + + globalThis.context.connectServiceExtensionAbility(want, connect); + ``` + The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **sendMessageRequest()** of the proxy object is called to send a message. ```ts @@ -6230,12 +6257,12 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch **Parameters** - | Name | Type | Mandatory| Description | - | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | - | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| + | Name | Type | Mandatory| Description | + | ------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| | data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. | | reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. | - | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | + | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | **Return value** @@ -6245,10 +6272,12 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch **Example** - Obtain the service. + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { @@ -6266,7 +6295,11 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.EntryAbility", }; - FA.connectAbility(want, connect); + + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + + globalThis.context.connectServiceExtensionAbility(want, connect); ``` The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **sendMessageRequest()** of the proxy object is called to send a message. @@ -6306,20 +6339,22 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn **Parameters** - | Name | Type | Mandatory| Description | - | -------- | ---------------------------------- | ---- | -------------------------------------------------------------------------------------- | - | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| + | Name | Type | Mandatory| Description | + | -------- | ------------------------------------ | ---- | -------------------------------------------------------------------------------------- | + | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| | data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. | | reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. | - | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | - | callback | AsyncCallback<RequestResult> | Yes | Callback for receiving the sending result. | + | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | + | callback | AsyncCallback<RequestResult> | Yes | Callback for receiving the sending result. | **Example** - - Obtain the service. + + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { @@ -6350,7 +6385,11 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn result.data.reclaim(); result.reply.reclaim(); } - FA.connectAbility(want, connect); + + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + + globalThis.context.connectServiceExtensionAbility(want, connect); ``` The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **sendMessageRequest()** of the proxy object is called to send a message. @@ -6362,7 +6401,7 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn data.writeInt(1); data.writeString("hello"); try { - proxy.sendRequest(1, data, reply, option, sendRequestCallback); + proxy.sendMessageRequest(1, data, reply, option, sendRequestCallback); } catch(error) { console.info("rpc send sequence request fail, errorCode " + error.code); console.info("rpc send sequence request fail, errorMessage " + error.message); @@ -6381,20 +6420,22 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch **Parameters** - | Name | Type | Mandatory| Description | - | -------- | -------------------------------------- | ---- | -------------------------------------------------------------------------------------- | - | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| - | data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. | - | reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. | - | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | - | callback | AsyncCallback<SendRequestResult> | Yes | Callback for receiving the sending result. | + | Name | Type | Mandatory| Description | + | -------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| + | data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. | + | reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. | + | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | + | callback | AsyncCallback<SendRequestResult> | Yes | Callback for receiving the sending result. | **Example** - Obtain the service. + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { @@ -6412,7 +6453,7 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.EntryAbility", }; - function sendRequestCallback(result) { + function sendRequestCallback(result) { if (result.errCode === 0) { console.log("sendRequest got result"); result.reply.readException(); @@ -6425,7 +6466,11 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch result.data.reclaim(); result.reply.reclaim(); } - FA.connectAbility(want, connect); + + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + + globalThis.context.connectServiceExtensionAbility(want, connect); ``` The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **sendMessageRequest()** of the proxy object is called to send a message. @@ -6464,22 +6509,24 @@ Obtains the **LocalInterface** object of an interface token. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900006 | only remote object permitted | + | -------- | -------- | + | 1900006 | only remote object permitted | **Example** - Obtain the service. + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { console.log("RpcClient: js onConnect called."); proxy = remoteProxy; }, - onDisconnect: function (elementName) { + onDisconnect: function(elementName) { console.log("RpcClient: onDisconnect"); }, onFailed: function() { @@ -6487,10 +6534,14 @@ For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode } }; let want = { - "bundleName":"com.ohos.server", - "abilityName":"com.ohos.server.EntryAbility", + "bundleName": "com.ohos.server", + "abilityName": "com.ohos.server.EntryAbility", }; - FA.connectAbility(want, connect); + + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + + globalThis.context.connectServiceExtensionAbility(want, connect); ``` The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **getLocalInterface()** of the proxy object is called to obtain the interface descriptor. @@ -6529,17 +6580,19 @@ Obtains the **LocalInterface** object of an interface token. **Example** - Obtain the service. + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { console.log("RpcClient: js onConnect called."); proxy = remoteProxy; }, - onDisconnect: function (elementName) { + onDisconnect: function(elementName) { console.log("RpcClient: onDisconnect"); }, onFailed: function() { @@ -6547,12 +6600,16 @@ Obtains the **LocalInterface** object of an interface token. } }; let want = { - "bundleName":"com.ohos.server", - "abilityName":"com.ohos.server.EntryAbility", + "bundleName": "com.ohos.server", + "abilityName": "com.ohos.server.EntryAbility", }; - FA.connectAbility(want, connect); - ``` + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + + globalThis.context.connectServiceExtensionAbility(want, connect); + ``` + The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **queryLocalInterface()** of the proxy object is called to obtain the interface descriptor. ```ts @@ -6580,15 +6637,17 @@ Registers a callback for receiving death notifications of the remote object. The For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900008 | proxy or remote object is invalid | + | -------- | -------- | + | 1900008 | proxy or remote object is invalid | **Example** - Obtain the service. + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { @@ -6606,11 +6665,15 @@ For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.EntryAbility", }; - FA.connectAbility(want, connect); + + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + + globalThis.context.connectServiceExtensionAbility(want, connect); ``` The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **registerDeathRecipient()** of the proxy object is called to register a callback for receiving the death notification of the remote object. - + ```ts class MyDeathRecipient { onRemoteDied() { @@ -6645,16 +6708,18 @@ Adds a callback for receiving the death notifications of the remote object, incl **Return value** - | Type | Description | - | ------- | --------------------------------------------- | + | Type | Description | + | ------- | ---------------------------------------- | | boolean | Returns **true** if the callback is added successfully; returns **false** otherwise.| **Example** - Obtain the service. + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { @@ -6672,9 +6737,13 @@ Adds a callback for receiving the death notifications of the remote object, incl "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.EntryAbility", }; - FA.connectAbility(want, connect); - ``` + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + + globalThis.context.connectServiceExtensionAbility(want, connect); + ``` + The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **addDeathRecippient()** of the proxy object is called to add a callback for receiving the death notification of the remove object. ```ts @@ -6707,15 +6776,17 @@ Unregisters the callback used to receive death notifications of the remote objec For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900008 | proxy or remote object is invalid | + | -------- | -------- | + | 1900008 | proxy or remote object is invalid | **Example** - Obtain the service. + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { @@ -6733,9 +6804,13 @@ For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.EntryAbility", }; - FA.connectAbility(want, connect); - ``` + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + + globalThis.context.connectServiceExtensionAbility(want, connect); + ``` + The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **unregisterDeathRecipient()** of the proxy object is called to unregister the callback for receiving the death notification of the remote object. ```ts @@ -6773,16 +6848,18 @@ Removes the callback used to receive death notifications of the remote object. **Return value** - | Type | Description | - | ------- | --------------------------------------------- | + | Type | Description | + | ------- | ---------------------------------------- | | boolean | Returns **true** if the callback is removed; returns **false** otherwise.| **Example** - Obtain the service. + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { @@ -6800,9 +6877,13 @@ Removes the callback used to receive death notifications of the remote object. "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.EntryAbility", }; - FA.connectAbility(want, connect); - ``` + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + + globalThis.context.connectServiceExtensionAbility(want, connect); + ``` + The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **removeDeathRecipient()** of the proxy object is called to remove the callback used to receive the death notification of the remote object. ```ts @@ -6835,16 +6916,18 @@ Obtains the interface descriptor (which is a string) of this proxy object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | -------- | ------- | - | 1900008 | proxy or remote object is invalid | - | 1900007 | communication failed | + | -------- | -------- | + | 1900008 | proxy or remote object is invalid | + | 1900007 | communication failed | **Example** - Obtain the service. + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { @@ -6862,7 +6945,11 @@ For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.EntryAbility", }; - FA.connectAbility(want, connect); + + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + + globalThis.context.connectServiceExtensionAbility(want, connect); ``` The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **getDescriptor()** of the proxy object is called to obtain the interface descriptor of the object. @@ -6894,10 +6981,12 @@ Obtains the interface descriptor of this proxy object. **Example** - Obtain the service. + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { @@ -6915,9 +7004,13 @@ Obtains the interface descriptor of this proxy object. "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.EntryAbility", }; - FA.connectAbility(want, connect); - ``` + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + + globalThis.context.connectServiceExtensionAbility(want, connect); + ``` + The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **getInterfaceDescriptor()** of the proxy object is called to obtain the interface descriptor of the current proxy object. ```ts @@ -6935,16 +7028,18 @@ Checks whether the **RemoteObject** is dead. **Return value** - | Type | Description | - | ------- | --------------------------------------------------------- | + | Type | Description | + | ------- | ------------------------------------------------- | | boolean | Returns **true** if the **RemoteObject** is dead; returns **false** otherwise.| **Example** - Obtain the service. + Before obtaining the ability for the application developed based on the stage model, obtain the context. For details, see [Obtaining the Context](#obtaining-the-context). ```ts - import FA from "@ohos.ability.featureAbility"; + // Import @ohos.ability.featureAbility only for the application developed based on the FA model. + // import FA from "@ohos.ability.featureAbility"; + let proxy; let connect = { onConnect: function(elementName, remoteProxy) { @@ -6962,7 +7057,11 @@ Checks whether the **RemoteObject** is dead. "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.EntryAbility", }; - FA.connectAbility(want, connect); + + // Use this method to connect to the ability for the FA model. + // FA.connectAbility(want,connect); + + globalThis.context.connectServiceExtensionAbility(want, connect); ``` The proxy object in the **onConnect** callback can be assigned a value only after the ability is connected asynchronously. Then, **isObjectDead()** of the proxy object is called to check whether this object is dead. @@ -6980,10 +7079,10 @@ Provides common message options (flag and wait time). Use the specified flag to | Name | Value | Description | | ------------- | ---- | ----------------------------------------------------------- | - | TF_SYNC | 0 | Synchronous call. | - | TF_ASYNC | 1 | Asynchronous call. | + | TF_SYNC | 0 | Synchronous call. | + | TF_ASYNC | 1 | Asynchronous call. | | TF_ACCEPT_FDS | 0x10 | Indication to **sendMessageRequest9+** for returning the file descriptor.| - | TF_WAIT_TIME | 8 | Default waiting time, in seconds. | + | TF_WAIT_TIME | 8 | Default waiting time, in seconds. | ### constructor9+ @@ -7045,8 +7144,8 @@ Checks whether **SendMessageRequest** is called synchronously or asynchronously. **Return value** - | Type | Description | - | ------- | ------------------------------------ | + | Type | Description | + | ------- | ---------------------------------------- | | boolean | Returns **true** if **SendMessageRequest** is called synchronously; returns **false** if **SendMessageRequest** is called asynchronously.| **Example** @@ -7353,8 +7452,8 @@ Checks whether the remote process is a process of the local device. This API is **Return value** - | Type | Description | - | ------- | --------------------------------------------------------- | + | Type | Description | + | ------- | -------------------------------------------------- | | boolean | Returns **true** if the local and remote processes are on the same device; returns **false** otherwise.| **Example** @@ -7526,8 +7625,8 @@ Sets the UID and PID of the remote user. This API is a static method. It is usua **Return value** - | Type | Description | - | ------- | ----------------------------------------- | + | Type | Description | + | ------- | ---------------------------------| | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| **Example** @@ -7579,17 +7678,17 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch **Parameters** - | Name | Type | Mandatory| Description | - | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | - | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| + | Name | Type | Mandatory| Description | + | ------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| | data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. | | reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. | - | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | + | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | **Return value** - | Type | Description | - | ------- | --------------------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the message is sent successfully; returns **false** otherwise.| **Example** @@ -7645,12 +7744,12 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch **Parameters** - | Name | Type | Mandatory| Description | - | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | - | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| + | Name | Type | Mandatory| Description | + | ------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| | data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. | | reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. | - | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | + | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | **Return value** @@ -7715,12 +7814,12 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn **Parameters** - | Name | Type | Mandatory| Description | - | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | - | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| + | Name | Type | Mandatory| Description | + | ------- | ------------------------------------ | ---- | -------------------------------------------------------------------------------------- | + | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| | data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. | | reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. | - | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | + | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | **Return value** @@ -7771,13 +7870,13 @@ Sends a **MessageSequence** message to the remote process in synchronous or asyn **Parameters** - | Name | Type | Mandatory| Description | - | ------------- | ---------------------------------- | ---- | -------------------------------------------------------------------------------------- | - | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| + | Name | Type | Mandatory| Description | + | ------------- | ------------------------------------ | ---- | -------------------------------------------------------------------------------------- | + | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| | data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object holding the data to send. | | reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that receives the response. | - | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | - | AsyncCallback | AsyncCallback<RequestResult> | Yes | Callback for receiving the sending result. | + | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | + | AsyncCallback | AsyncCallback<RequestResult> | Yes | Callback for receiving the sending result. | **Example** @@ -7821,13 +7920,13 @@ Sends a **MessageParcel** message to the remote process in synchronous or asynch **Parameters** - | Name | Type | Mandatory| Description | - | ------------- | -------------------------------------- | ---- | -------------------------------------------------------------------------------------- | - | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| - | data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. | - | reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. | - | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | - | AsyncCallback | AsyncCallback<SendRequestResult> | Yes | Callback for receiving the sending result. | + | Name | Type | Mandatory| Description | + | ------------- | ----------------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | Yes | Message code called by the request, which is determined by the client and server. If the method is generated by an IDL tool, the message code is automatically generated by the IDL tool.| + | data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object holding the data to send. | + | reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that receives the response. | + | options | [MessageOption](#messageoption) | Yes | Request sending mode, which can be synchronous (default) or asynchronous. | + | AsyncCallback | AsyncCallback<SendRequestResult> | Yes | Callback for receiving the sending result. | **Example** @@ -7885,17 +7984,17 @@ Provides a response to **sendMessageRequest()**. The server processes the reques **Parameters** - | Name| Type | Mandatory| Description | - | ------ | ------------------------------- | ---- | --------------------------------------- | - | code | number | Yes | Service request code sent by the remote end. | + | Name| Type | Mandatory| Description | + | ------ | ----------------------------------------- | ---- | --------------------------------------- | + | code | number | Yes | Service request code sent by the remote end. | | data | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object that holds the parameters called by the client.| | reply | [MessageParcel](#messageparceldeprecated) | Yes | **MessageParcel** object carrying the result. | - | option | [MessageOption](#messageoption) | Yes | Whether the operation is synchronous or asynchronous. | + | option | [MessageOption](#messageoption) | Yes | Whether the operation is synchronous or asynchronous. | **Return value** - | Type | Description | - | ------- | ----------------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| **Example** @@ -7946,17 +8045,17 @@ Provides a response to **sendMessageRequest()**. The server processes the reques **Parameters** - | Name| Type | Mandatory| Description | - | ------ | ------------------------------- | ---- | ----------------------------------------- | - | code | number | Yes | Service request code sent by the remote end. | + | Name| Type | Mandatory| Description | + | ------ | ------------------------------------ | ---- | ----------------------------------------- | + | code | number | Yes | Service request code sent by the remote end. | | data | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object that holds the parameters called by the client.| | reply | [MessageSequence](#messagesequence9) | Yes | **MessageSequence** object to which the result is written. | - | option | [MessageOption](#messageoption) | Yes | Whether the operation is synchronous or asynchronous. | + | option | [MessageOption](#messageoption) | Yes | Whether the operation is synchronous or asynchronous. | **Return value** - | Type | Description | - | ----------------- | ---------------------------------------------------------------------------------------------- | + | Type | Description | + | ----------------- | ----------------------------------------------------------------------------------------------- | | boolean | Returns a Boolean value if the request is processed synchronously in **onRemoteMessageRequest**. The value **true** means the operation is successful; the value **false** means the opposite.| | Promise\ | Returns a promise object if the request is processed asynchronously in **onRemoteMessageRequest**. | @@ -8237,8 +8336,8 @@ Obtains the interface descriptor of this object. The interface descriptor is a s For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900008 | proxy or remote object is invalid | + | -------- | -------- | + | 1900008 | proxy or remote object is invalid | **Example** @@ -8629,8 +8728,8 @@ Creates the shared file mapping on the virtual address space of this process. Th For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | ------ | - | 1900001 | call mmap function failed | + | -------- | -------- | + | 1900001 | call mmap function failed | **Example** @@ -8662,8 +8761,8 @@ Creates the shared file mapping on the virtual address space of this process. Th **Return value** - | Type | Description | - | ------- | ----------------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the mapping is created; returns **false** otherwise.| **Example** @@ -8687,8 +8786,8 @@ Maps the shared file to the readable and writable virtual address space of the p For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900001 | call mmap function failed | + | -------- | -------- | + | 1900001 | call mmap function failed | **Example** @@ -8714,8 +8813,8 @@ Maps the shared file to the readable and writable virtual address space of the p **Return value** - | Type | Description | - | ------- | ----------------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the mapping is created; returns **false** otherwise.| **Example** @@ -8739,8 +8838,8 @@ Maps the shared file to the read-only virtual address space of the process. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900001 | call mmap function failed | + | -------- | -------- | + | 1900001 | call mmap function failed | **Example** @@ -8766,8 +8865,8 @@ Maps the shared file to the read-only virtual address space of the process. **Return value** - | Type | Description | - | ------- | ----------------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the mapping is created; returns **false** otherwise.| **Example** @@ -8797,8 +8896,8 @@ Sets the protection level of the memory region to which the shared file is mappe For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | -------- | ------- | - | 1900002 | call os ioctl function failed | + | -------- | -------- | + | 1900002 | call os ioctl function failed | **Example** @@ -8830,8 +8929,8 @@ Sets the protection level of the memory region to which the shared file is mappe **Return value** - | Type | Description | - | ------- | ----------------------------------------- | + | Type | Description | + | ------- | -------------------------------- | | boolean | Returns **true** if the operation is successful; returns **false** otherwise.| **Example** @@ -8863,8 +8962,8 @@ Writes data to the shared file associated with this **Ashmem** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). | ID| Error Message| - | ------- | -------- | - | 1900003 | write to ashmem failed | + | -------- | -------- | + | 1900003 | write to ashmem failed | **Example** @@ -8900,8 +8999,8 @@ Writes data to the shared file associated with this **Ashmem** object. **Return value** - | Type | Description | - | ------- | ----------------------------------------------------------------------------------------- | + | Type | Description | + | ------- | ----------------------------------------------------------------------------- | | boolean | Returns **true** if the data is written successfully; returns **false** otherwise.| **Example** @@ -8940,9 +9039,9 @@ Reads data from the shared file associated with this **Ashmem** object. For details about the error codes, see [RPC Error Codes](../errorcodes/errorcode-rpc.md). - | ID | Error Message| + | ID| Error Message| | -------- | -------- | - | 1900004 | read from ashmem failed | + | 1900004 | read from ashmem failed | **Example** @@ -8985,7 +9084,7 @@ Reads data from the shared file associated with this **Ashmem** object. **Example** - ```ts + ``` ts let ashmem = rpc.Ashmem.createAshmem("ashmem", 1024*1024); let mapResult = ashmem.mapReadAndWriteAshmem(); console.info("RpcTest map ashmem result is " + mapResult); @@ -8995,3 +9094,36 @@ Reads data from the shared file associated with this **Ashmem** object. let readResult = ashmem.readFromAshmem(5, 0); console.log("RpcTest: read to Ashmem result is : " + readResult); ``` + +## Obtaining the Context + +**Example** + + ```ts + import Ability from '@ohos.app.ability.UIAbility'; + export default class MainAbility extends Ability { + onCreate(want, launchParam) { + console.log("[Demo] MainAbility onCreate"); + globalThis.context = this.context; + } + onDestroy() { + console.log("[Demo] MainAbility onDestroy"); + } + onWindowStageCreate(windowStage) { + // Main window is created, set main page for this ability + console.log("[Demo] MainAbility onWindowStageCreate"); + } + onWindowStageDestroy() { + // Main window is destroyed, release UI related resources + console.log("[Demo] MainAbility onWindowStageDestroy"); + } + onForeground() { + // Ability has brought to foreground + console.log("[Demo] MainAbility onForeground"); + } + onBackground() { + // Ability has back to background + console.log("[Demo] MainAbility onBackground"); + } + }; + ``` 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/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/reference/errorcodes/errorcode-reminderAgentManager.md b/en/application-dev/reference/errorcodes/errorcode-reminderAgentManager.md index b74df9ec5663370f4d47e27eea0f71f100087479..9b166e1ca38d5022c9f6bbb6522b1b8ca7a098b2 100644 --- a/en/application-dev/reference/errorcodes/errorcode-reminderAgentManager.md +++ b/en/application-dev/reference/errorcodes/errorcode-reminderAgentManager.md @@ -36,8 +36,8 @@ The number of reminders exceeds the limit when **publishReminder()** is called. **Possible Causes** -1. There are already 2000 reminders for the entire system. -2. There are already 30 reminders for the application. +1. The number of reminders generated for the entire system exceeds 2000 in API version 9 or 12000 in API version 10 or later. +2. The number of reminders generated for the application exceeds 30 in API version 9 or 30 (for a common application) or 10000 (for a system application) in API version 10 or later. **Solution** 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/task-management/reminder-agent-development.md b/en/application-dev/task-management/reminder-agent-development.md index 2362e39c3a4f34213f19687d0377eed140a446a1..dd6d26f25a507adbd9168e647210e069b611acdb 100644 --- a/en/application-dev/task-management/reminder-agent-development.md +++ b/en/application-dev/task-management/reminder-agent-development.md @@ -7,14 +7,14 @@ The agent-powered reminder feature provides APIs for publishing background remin **Table 1** Major APIs in reminderAgentManager -| API | Description | -| ------------------------------------------------------------ | ------------------------------------------------------------ | -| publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void
publishReminder(reminderReq: ReminderRequest): Promise<number> | Publishes a scheduled reminder.
The maximum number of valid notifications (excluding expired ones that will not pop up again) is 30 for one application and 2000 for the entire system. | -| cancelReminder(reminderId: number, callback: AsyncCallback<void>): void
cancelReminder(reminderId: number): Promise<void> | Cancels a specified reminder. (The value of **reminderId** is obtained from the return value of **publishReminder**.) | -| getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void
getValidReminders(): Promise<Array<ReminderRequest>> | Obtains all valid reminders set by the current application. | -| cancelAllReminders(callback: AsyncCallback<void>): void
cancelAllReminders(): Promise<void> | Cancels all reminders set by the current application. | -| addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void
addNotificationSlot(slot: NotificationSlot): Promise<void> | Registers a **NotificationSlot** instance to be used by the reminder. | -| removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void
removeNotificationSlot(slotType: notification.SlotType): Promise<void> | Removes a **NotificationSlot** instance of a specified type. | +| API | Description | +| ---------------------------------------- | ---------------------------------------- | +| publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void
publishReminder(reminderReq: ReminderRequest): Promise<number> | Publishes a scheduled reminder.
The maximum number of valid notifications (excluding expired ones that will not pop up again) is 30 for one application
and 2000 for the entire system.| +| cancelReminder(reminderId: number, callback: AsyncCallback<void>): void
cancelReminder(reminderId: number): Promise<void> | Cancels a specified reminder. (The value of **reminderId** is obtained from the return value of **publishReminder**.)| +| getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void
getValidReminders(): Promise<Array<ReminderRequest>> | Obtains all valid reminders set by the current application. | +| cancelAllReminders(callback: AsyncCallback<void>): void
cancelAllReminders(): Promise<void> | Cancels all reminders set by the current application. | +| addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void
addNotificationSlot(slot: NotificationSlot): Promise<void> | Registers a **NotificationSlot** instance to be used by the reminder. | +| removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void
removeNotificationSlot(slotType: notification.SlotType): Promise<void> | Removes a **NotificationSlot** instance of a specified type. | ## How to Develop @@ -37,7 +37,7 @@ The agent-powered reminder feature provides APIs for publishing background remin let targetReminderAgent: reminderAgentManager.ReminderRequestTimer = { reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER, // The reminder type is countdown timer. triggerTimeInSeconds: 10, - actionButton: [ // Set the button type and title displayed in the reminder notification. The Close and Snooze types are supported, and the Snooze type must be used together with the snoozeTimes and timeInterval parameters. + actionButton: [ // Set the button type and title displayed for the reminder in the notification panel. { title: 'close', type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE @@ -73,7 +73,7 @@ The agent-powered reminder feature provides APIs for publishing background remin }, repeatMonths: [1], // Month in which the reminder repeats. repeatDays: [1], // Date on which the reminder repeats. - actionButton: [ // Set the button type and title displayed in the reminder notification. The Close and Snooze types are supported, and the Snooze type must be used together with the snoozeTimes and timeInterval parameters. + actionButton: [ // Set the button type and title displayed for the reminder in the notification panel. { title: 'close', type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE @@ -93,7 +93,7 @@ The agent-powered reminder feature provides APIs for publishing background remin }, ringDuration: 5, // Ringing duration, in seconds. snoozeTimes: 2, // Number of reminder snooze times. - timeInterval: 5, // Reminder snooze interval, in seconds. + timeInterval: 300, // Reminder snooze interval, in seconds. title: 'this is title', // Reminder title. content: 'this is content', // Reminder content. expiredContent: 'this reminder has expired', // Content to be displayed after the reminder expires. @@ -110,7 +110,7 @@ The agent-powered reminder feature provides APIs for publishing background remin hour: 23, // Hour portion of the reminder time. minute: 9, // Minute portion of the reminder time. daysOfWeek: [2], // Days of a week when the reminder repeats.. - actionButton: [ // Set the button type and title displayed in the reminder notification. The Close and Snooze types are supported, and the Snooze type must be used together with the snoozeTimes and timeInterval parameters. + actionButton: [ // Set the button type and title displayed for the reminder in the notification panel. { title: 'close', type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE @@ -130,7 +130,7 @@ The agent-powered reminder feature provides APIs for publishing background remin }, ringDuration: 5, // Ringing duration, in seconds. snoozeTimes: 2, // Number of reminder snooze times. - timeInterval: 5, // Reminder snooze interval, in seconds. + timeInterval: 300, // Reminder snooze interval, in seconds. title: 'this is title', // Reminder title. content: 'this is content', // Reminder content. expiredContent: 'this reminder has expired', // Content to be displayed after the reminder expires. diff --git a/en/application-dev/tools/aa-tool.md b/en/application-dev/tools/aa-tool.md index eb1e5955656595b6bf9529154a0f124c4e454da0..dd3e87862eac8d9c85ccb0cff2a250aef631965d 100644 --- a/en/application-dev/tools/aa-tool.md +++ b/en/application-dev/tools/aa-tool.md @@ -26,7 +26,7 @@ The ability assistant enables you to start applications and test cases. It provi - start - Starts an application component. The target component can be the PageAbility and ServiceAbility components of the FA model or the UIAbility and ServiceExtensionAbility components of the Stage model. The **visible** tag in the configuration file of the target component cannot be set to **false**. + Starts an application component. The target component can be the PageAbility and ServiceAbility components of the FA model or the UIAbility and ServiceExtensionAbility components of the Stage model. The **exported** tag in the configuration file of the target component cannot be set to **false**. | Name| Description| | -------- | -------- | @@ -77,7 +77,7 @@ The ability assistant enables you to start applications and test cases. It provi | -------- | -------- | -------- | | -h/--help | - | Help information.| | -a/--all | - | Application component information in all missions.| - | -l/--mission-list | type (All logs are printed if this parameter is left unspecified.)| For better management, the service side maintains four types of MissionLists, as described below:
- **NORMAL**: MissionList that is started normally. For example, if A starts B and C, the corresponding MissionList is A->B->C.
- **DEFAULT_STANDARD**: If a MissionList is damaged, missions with the launch type set to **standard** are removed to this MissionList. The Missions in it are not associated with each other.
- **DEFAULT_SINGLE**: If a MissionList is damaged, missions with the launch type set to **singleton** are removed to this MissionList. The Missions in it are not associated with each other.
- **LAUNCHER**: MissionList for launcher abilities. | + | -l/--mission-list | type (All logs are printed if this parameter is left unspecified.)| For better management, the service side maintains four types of MissionLists, as described below:
- **NORMAL**: MissionList that is started normally. For example, if A starts B and C, the corresponding MissionList is A->B->C.
- **DEFAULT_STANDARD**: If a MissionList is damaged, missions with the launch type set to **multiton** are removed to this MissionList. The Missions in it are not associated with each other.
- **DEFAULT_SINGLE**: If a MissionList is damaged, missions with the launch type set to **singleton** are removed to this MissionList. The Missions in it are not associated with each other.
- **LAUNCHER**: MissionList for launcher abilities.| | -e/--extension | elementName | Extended component information.| | -u/--userId | UserId | Mission stack information of a specified user ID. This parameter must be used together with other parameters. Example commands: **aa dump -a -u 100** and **aa dump -d -u 100**.| | -d/--data | - | DataAbility information.| 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/porting/porting-bes2600w-on-minisystem-display-demo.md b/en/device-dev/porting/porting-bes2600w-on-minisystem-display-demo.md index fdf4be08997d2ed8083d77b6ba75d2e8007343e0..c92f86c100993cbd0fc346562a5c4558f6206c2f 100644 --- a/en/device-dev/porting/porting-bes2600w-on-minisystem-display-demo.md +++ b/en/device-dev/porting/porting-bes2600w-on-minisystem-display-demo.md @@ -1,6 +1,6 @@ # Mini-System Devices with Screens – Bestechnic SoC Porting Case -This document exemplifies the porting procedure for a development board on a mini-system device with a screen – an intelligent switch panel. It uses the BES multi-modal V200Z-R development board powered by the Bestechnic BES2600W SoC as an example. Components such as `ace_engine_lite`, `graphic_ui`, `aafwk_lite`, `appexecfwk_lite`, and `HDF` are adapted based on the OpenHarmony LiteOS-M kernel. This example uses the board-SoC separation solution as the porting architecture, the Newlib C or Musl C library as the toolchain, and GN and Kconfig graphical configuration for LiteOS-M kernel compilation. +This document exemplifies the porting procedure for a development board on a mini-system device with a screen – an intelligent switch panel. It uses the BES multi-modal V200Z-R development board powered by the Bestechnic BES2600W SoC as an example. Components such as `ace_engine_lite`, `arkui_ui_lite`, `aafwk_lite`, `appexecfwk_lite`, and `HDF` are adapted based on the OpenHarmony LiteOS-M kernel. This example uses the board-SoC separation solution as the porting architecture, the Newlib C or Musl C library as the toolchain, and GN and Kconfig graphical configuration for LiteOS-M kernel compilation. ## Compilation and Building @@ -1311,7 +1311,7 @@ aafwk_lite + appexecfwk_lite (AAFWK + APPEXECFWK) | ace_engine_lite + jerryscript + i18n_lite + resmgr_lite + utils/native/lite/... (ACE and JS engines and their dependencies) | -graphic_ui + graphic_utils (Graphic framework) +arkui_lite + graphic_graphic_utils_lite (Graphic framework) | giflib + libjpeg + libpng + qrcodegen + freetype... (Third-party graphics library) ``` diff --git a/en/device-dev/porting/porting-stm32mp15xx-on-smallsystem.md b/en/device-dev/porting/porting-stm32mp15xx-on-smallsystem.md index 0bb8a5f39c772167420b88639299f066088f1457..91684e5a06777efb344dfbce35d1bc88ff60c94f 100644 --- a/en/device-dev/porting/porting-stm32mp15xx-on-smallsystem.md +++ b/en/device-dev/porting/porting-stm32mp15xx-on-smallsystem.md @@ -1,6 +1,6 @@ # Small System STM32MP1 SoC Porting Case -This document describes how to port small development boards with screens based on the [BearPi-HM Micro development board](https://gitee.com/openharmony/device_board_bearpi) of the `STM32MP157` SoC from STMicroelectronics, so as to adapt components such as `ace_engine_lite`, `graphic_ui`, `aafwk_lite`, `appexecfwk_lite`, and `HDF` to the `OpenHarmony LiteOS-A` kernel. The porting architecture uses the solution where `Board` and `SoC` are separated. +This document describes how to port small development boards with screens based on the [BearPi-HM Micro development board](https://gitee.com/openharmony/device_board_bearpi) of the `STM32MP157` SoC from STMicroelectronics, so as to adapt components such as `ace_engine_lite`, `arkui_ui_lite`, `aafwk_lite`, `appexecfwk_lite`, and `HDF` to the `OpenHarmony LiteOS-A` kernel. The porting architecture uses the solution where `Board` and `SoC` are separated. ## Compilation and Building 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/readme/common-event-notification.md b/en/readme/common-event-notification.md index a4daa5486470def4bf309b363b7b66725656903b..745ea06735002601ca57b2fe7ab620ae0162a2af 100644 --- a/en/readme/common-event-notification.md +++ b/en/readme/common-event-notification.md @@ -36,10 +36,10 @@ Each application can subscribe to common events as required. After your applicat ## How to Use -For details, see [Common Event Development](../application-dev/notification/common-event.md). +For details, see [Common Event Development](../application-dev/application-models/common-event-overview.md). ## Repositories Involved Common Event and Notification -[**notification_ces_standard**](https://gitee.com/openharmony/notification_ces_standard) \ No newline at end of file +**notification_ces_standard** \ No newline at end of file diff --git a/en/readme/graphics.md b/en/readme/graphics.md index 117da8cf1bf456c8771290357080f5cae00ffff6..209d5c23210085a7c947946f53182f93359344bd 100644 --- a/en/readme/graphics.md +++ b/en/readme/graphics.md @@ -28,11 +28,15 @@ The related modules are described as follows: ### Directory Structure ``` +/foundation/arkui +├── ui_lite # UI module, including UI components, animations, and fonts + /foundation/graphic -├── surface # Shared memory -├── ui # UI module, including UI components, animations, and fonts -├── utils # Basic graphics library and hardware adaptation layer -└── wms # Window and input event management +├── surface_lite # Shared memory +├── graphic_utils_lite # Basic graphics library and hardware adaptation layer + +/foundation/window +└── window_manager_lite # Window and input event management ``` ### Constraints @@ -48,13 +52,13 @@ For details, see the README and **test** directory of each repository. **Graphics subsystem** -[graphic\_surface](https://gitee.com/openharmony/graphic_surface) +[graphic\_surface_lite](https://gitee.com/openharmony/graphic_surface_lite) -[graphic\_ui](https://gitee.com/openharmony/graphic_ui) +[arkui\_ui_lite](https://gitee.com/openharmony/arkui_ui_lite) -[graphic\_wms](https://gitee.com/openharmony/graphic_wms) +[window\_window_manager_lite](https://gitee.com/openharmony/window_window_manager_lite) -[graphic\_utils](https://gitee.com/openharmony/graphic_utils) +[graphic\_graphic_utils_lite](https://gitee.com/openharmony/graphic_graphic_utils_lite) ## Standard System diff --git a/en/release-notes/OpenHarmony-1-1-0-LTS.md b/en/release-notes/OpenHarmony-1-1-0-LTS.md index 5c80392132f61db0f9a4869e36a9f128042e0dc2..7a74b95a9f7d2fec011a2aafd6d1cce98f19e968 100644 --- a/en/release-notes/OpenHarmony-1-1-0-LTS.md +++ b/en/release-notes/OpenHarmony-1-1-0-LTS.md @@ -139,10 +139,10 @@ The following table describes the optimization of repositories. | startup_frameworks_syspara_lite | startup_syspara_lite | Repository renamed | | startup_hals_syspara_lite | N/A | Read-only archiving | | startup_interfaces_kits_syspara_lite | N/A | Read-only archiving | -| graphic_lite | graphic_surface | Repository renamed | -| N/A | graphic_ui | New module | -| N/A | graphic_utils | New module | -| N/A | graphic_wms | New module | +| graphic_lite | graphic_surface_lite | Repository renamed | +| N/A | arkui_ui_lite | Repository renamed module | +| N/A | graphic_graphic_utils_lite | Repository renamed module | +| N/A | window_manager_lite | Repository renamed module | | N/A | third_party_giflib | New module | | N/A | third_party_qrcodegen | New module | | N/A | drivers_adapter_khdf_linux | New module | 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 **\