From f0a2c4358d33a046601fba1115614ea66cf18837 Mon Sep 17 00:00:00 2001 From: "ester.zhou" Date: Wed, 11 Jan 2023 17:57:02 +0800 Subject: [PATCH] Update docs (12832) Signed-off-by: ester.zhou --- .../reference/apis/js-apis-commonEvent.md | 111 +- .../apis/js-apis-commonEventManager.md | 1353 ++++++++++++ .../reference/apis/js-apis-router.md | 2 +- .../arkui-ts/ts-basic-components-web.md | 1860 +++++------------ .../arkui-ts/ts-components-canvas-lottie.md | 83 +- 5 files changed, 1992 insertions(+), 1417 deletions(-) create mode 100644 en/application-dev/reference/apis/js-apis-commonEventManager.md diff --git a/en/application-dev/reference/apis/js-apis-commonEvent.md b/en/application-dev/reference/apis/js-apis-commonEvent.md index 5aaacbe7d1..fb94f3c30f 100644 --- a/en/application-dev/reference/apis/js-apis-commonEvent.md +++ b/en/application-dev/reference/apis/js-apis-commonEvent.md @@ -1,10 +1,11 @@ -# CommonEvent +# @ohos.commonEvent The **CommonEvent** module provides common event capabilities, including the capabilities to publish, subscribe to, and unsubscribe from common events, as well obtaining and setting the common event result code and result data. > **NOTE** > -> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> - The APIs provided by this module are no longer maintained since API version 9. You are advised to use [@ohos.commonEventManager](js-apis-commonEventManager.md). +> - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import @@ -14,7 +15,7 @@ import CommonEvent from '@ohos.commonEvent'; ## Support -Provides the event types supported by the **CommonEvent** module. The name and value indicate the macro and name of a common event, respectively. +The table below lists the event types supported by the **CommonEvent** module. The name and value indicate the macro and name of a common event, respectively. **System capability**: SystemCapability.Notification.CommonEvent @@ -167,8 +168,8 @@ Provides the event types supported by the **CommonEvent** module. The name and v | COMMON_EVENT_ACCOUNT_DELETED | usual.event.data.ACCOUNT_DELETED | ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS | Indicates the common event that the account was deleted. | | COMMON_EVENT_FOUNDATION_READY | usual.event.data.FOUNDATION_READY | ohos.permission.RECEIVER_STARTUP_COMPLETED | Indicates the common event that the foundation is ready. | | COMMON_EVENT_AIRPLANE_MODE_CHANGED | usual.event.AIRPLANE_MODE | - | Indicates the common event that the airplane mode of the device has changed. | -| COMMON_EVENT_SPLIT_SCREEN8+ | usual.event.SPLIT_SCREEN | - | Indicates the common event of screen splitting. | -| COMMON_EVENT_SLOT_CHANGE9+ | usual.event.SLOT_CHANGE | ohos.permission.NOTIFICATION_CONTROLLER | Indicates the common event that the notification slot has changed. | +| COMMON_EVENT_SPLIT_SCREEN8+ | usual.event.SPLIT_SCREEN | - | Indicates the common event of screen splitting. | +| COMMON_EVENT_SLOT_CHANGE9+ | usual.event.SLOT_CHANGE | ohos.permission.NOTIFICATION_CONTROLLER | Indicates the common event that the notification slot has been updated. | | COMMON_EVENT_SPN_INFO_CHANGED 9+ | usual.event.SPN_INFO_CHANGED | - | Indicates the common event that the SPN displayed has been updated. | | COMMON_EVENT_QUICK_FIX_APPLY_RESULT 9+ | usual.event.QUICK_FIX_APPLY_RESULT | - | Indicates the common event that a quick fix is applied to the application. | @@ -192,7 +193,7 @@ Publishes a common event. This API uses an asynchronous callback to return the r ```js // Callback for common event publication -function PublishCallBack(err) { +function publishCallBack(err) { if (err.code) { console.error("publish failed " + JSON.stringify(err)); } else { @@ -201,7 +202,7 @@ function PublishCallBack(err) { } // Publish a common event. -CommonEvent.publish("event", PublishCallBack); +CommonEvent.publish("event", publishCallBack); ``` @@ -229,12 +230,12 @@ Publishes a common event with given attributes. This API uses an asynchronous ca // Attributes of a common event. let options = { code: 0, // Result code of the common event. - data: "initial data";// Result data of the common event. + data: "initial data",// Result data of the common event. isOrdered: true // The common event is an ordered one. } // Callback for common event publication -function PublishCallBack(err) { +function publishCallBack(err) { if (err.code) { console.error("publish failed " + JSON.stringify(err)); } else { @@ -243,7 +244,7 @@ function PublishCallBack(err) { } // Publish a common event. -CommonEvent.publish("event", options, PublishCallBack); +CommonEvent.publish("event", options, publishCallBack); ``` @@ -270,7 +271,7 @@ Publishes a common event to a specific user. This API uses an asynchronous callb ```js // Callback for common event publication -function PublishAsUserCallBack(err) { +function publishAsUserCallBack(err) { if (err.code) { console.error("publishAsUser failed " + JSON.stringify(err)); } else { @@ -282,7 +283,7 @@ function PublishAsUserCallBack(err) { let userId = 100; // Publish a common event. -CommonEvent.publishAsUser("event", userId, PublishAsUserCallBack); +CommonEvent.publishAsUser("event", userId, publishAsUserCallBack); ``` @@ -313,11 +314,11 @@ Publishes a common event with given attributes to a specific user. This API uses // Attributes of a common event. let options = { code: 0, // Result code of the common event. - data: "initial data";// Result data of the common event. + data: "initial data",// Result data of the common event. } // Callback for common event publication -function PublishAsUserCallBack(err) { +function publishAsUserCallBack(err) { if (err.code) { console.error("publishAsUser failed " + JSON.stringify(err)); } else { @@ -329,7 +330,7 @@ function PublishAsUserCallBack(err) { let userId = 100; // Publish a common event. -CommonEvent.publishAsUser("event", userId, options, PublishAsUserCallBack); +CommonEvent.publishAsUser("event", userId, options, publishAsUserCallBack); ``` @@ -361,7 +362,7 @@ let subscribeInfo = { }; // Callback for subscriber creation. -function CreateSubscriberCallBack(err, commonEventSubscriber) { +function createSubscriberCallBack(err, commonEventSubscriber) { if (err.code) { console.error("createSubscriber failed " + JSON.stringify(err)); } else { @@ -371,7 +372,7 @@ function CreateSubscriberCallBack(err, commonEventSubscriber) { } // Create a subscriber. -CommonEvent.createSubscriber(subscribeInfo, CreateSubscriberCallBack); +CommonEvent.createSubscriber(subscribeInfo, createSubscriberCallBack); ``` @@ -442,7 +443,7 @@ let subscribeInfo = { }; // Callback for common event subscription. -function SubscribeCallBack(err, data) { +function subscribeCallBack(err, data) { if (err.code) { console.error("subscribe failed " + JSON.stringify(err)); } else { @@ -451,19 +452,19 @@ function SubscribeCallBack(err, data) { } // Callback for subscriber creation. -function CreateSubscriberCallBack(err, commonEventSubscriber) { +function createSubscriberCallBack(err, commonEventSubscriber) { if (err.code) { console.error("createSubscriber failed " + JSON.stringify(err)); } else { console.info("createSubscriber"); subscriber = commonEventSubscriber; // Subscribe to a common event. - CommonEvent.subscribe(subscriber, SubscribeCallBack); + CommonEvent.subscribe(subscriber, subscribeCallBack); } } // Create a subscriber. -CommonEvent.createSubscriber(subscribeInfo, CreateSubscriberCallBack); +CommonEvent.createSubscriber(subscribeInfo, createSubscriberCallBack); ``` @@ -494,7 +495,7 @@ let subscribeInfo = { }; // Callback for common event subscription. -function SubscribeCallBack(err, data) { +function subscribeCallBack(err, data) { if (err.code) { console.info("subscribe failed " + JSON.stringify(err)); } else { @@ -503,19 +504,19 @@ function SubscribeCallBack(err, data) { } // Callback for subscriber creation. -function CreateSubscriberCallBack(err, commonEventSubscriber) { +function createSubscriberCallBack(err, commonEventSubscriber) { if (err.code) { console.info("createSubscriber failed " + JSON.stringify(err)); } else { console.info("createSubscriber"); subscriber = commonEventSubscriber; // Subscribe to a common event. - CommonEvent.subscribe(subscriber, SubscribeCallBack); + CommonEvent.subscribe(subscriber, subscribeCallBack); } } // Callback for common event unsubscription. -function UnsubscribeCallBack(err) { +function unsubscribeCallBack(err) { if (err.code) { console.info("unsubscribe failed " + JSON.stringify(err)); } else { @@ -524,10 +525,10 @@ function UnsubscribeCallBack(err) { } // Create a subscriber. -CommonEvent.createSubscriber(subscribeInfo, CreateSubscriberCallBack); +CommonEvent.createSubscriber(subscribeInfo, createSubscriberCallBack); // Unsubscribe from the common event. -CommonEvent.unsubscribe(subscriber, UnsubscribeCallBack); +CommonEvent.unsubscribe(subscriber, unsubscribeCallBack); ``` ## CommonEventSubscriber @@ -841,7 +842,6 @@ isOrderedCommonEvent(callback: AsyncCallback\): void Checks whether this common event is an ordered one. This API uses an asynchronous callback to return the result. - **System capability**: SystemCapability.Notification.CommonEvent **Parameters** @@ -872,7 +872,6 @@ isOrderedCommonEvent(): Promise\ Checks whether this common event is an ordered one. This API uses a promise to return the result. - **System capability**: SystemCapability.Notification.CommonEvent **Return value** @@ -899,7 +898,6 @@ isStickyCommonEvent(callback: AsyncCallback\): void Checks whether this common event is a sticky one. This API uses an asynchronous callback to return the result. - **System capability**: SystemCapability.Notification.CommonEvent **Parameters** @@ -930,7 +928,6 @@ isStickyCommonEvent(): Promise\ Checks whether this common event is a sticky one. This API uses a promise to return the result. - **System capability**: SystemCapability.Notification.CommonEvent **Return value** @@ -1233,39 +1230,45 @@ subscriber.finishCommonEvent().then(() => { ## CommonEventData +Describes the common event data body. + **System capability**: SystemCapability.Notification.CommonEvent -| Name | Readable| Writable| Type | Description | -| ---------- | ---- | ---- | -------------------- | ------------------------------------------------------- | -| event | Yes | No | string | Name of the common event that is being received. | -| bundleName | Yes | No | string | Bundle name. | -| code | Yes | No | number | Result code of the common event, which is used to transfer data of the int type. | -| data | Yes | No | string | Custom result data of the common event, which is used to transfer data of the string type.| -| parameters | Yes | No | {[key: string]: any} | Additional information about the common event. | +| Name | Type | Readable| Writable| Description | +| ---------- |-------------------- | ---- | ---- | ------------------------------------------------------- | +| event | string | Yes | No | Name of the common event that is being received. | +| bundleName | string | Yes | No | Bundle name. | +| code | number | Yes | No | Result code of the common event, which is used to transfer data of the int type. | +| data | string | Yes | No | Custom result data of the common event, which is used to transfer data of the string type.| +| parameters | {[key: string]: any} | Yes | No | Additional information about the common event. | ## CommonEventPublishData +Describes the data body published by a common event, including the common event content and attributes. + **System capability**: SystemCapability.Notification.CommonEvent -| Name | Readable| Writable| Type | Description | -| --------------------- | ---- | ---- | -------------------- | ---------------------------- | -| bundleName | Yes | No | string | Bundle name. | -| code | Yes | No | number | Result code of the common event. | -| data | Yes | No | string | Custom result data of the common event.| -| subscriberPermissions | Yes | No | Array\ | Permissions required for subscribers to receive the common event. | -| isOrdered | Yes | No | boolean | Whether the common event is an ordered one. | -| isSticky | Yes | No | boolean | Whether the common event is a sticky one. | -| parameters | Yes | No | {[key: string]: any} | Additional information about the common event. | +| Name | Type | Readable| Writable| Description | +| --------------------- | -------------------- | ---- | ---- | ---------------------------- | +| bundleName | string | Yes | No | Bundle name. | +| code | number | Yes | No | Result code of the common event. | +| data | string | Yes | No | Custom result data of the common event.| +| subscriberPermissions | Array\ | Yes | No | Permissions required for subscribers to receive the common event. | +| isOrdered | boolean | Yes | No | Whether the common event is an ordered one. | +| isSticky | boolean | Yes | No | Whether the common event is a sticky one. Only system applications and system services are allowed to send sticky events.| +| parameters | {[key: string]: any} | Yes | No | Additional information about the common event. | ## CommonEventSubscribeInfo +Provides the subscriber information. + **System capability**: SystemCapability.Notification.CommonEvent -| Name | Readable| Writable| Type | Description | -| ------------------- | ---- | ---- | -------------- | ------------------------------------------------------------ | -| events | Yes | No | Array\ | Name of the common event to publish. | -| publisherPermission | Yes | No | string | Permissions required for publishers to publish the common event. | -| publisherDeviceId | Yes | No | string | Device ID. The value must be the ID of an existing device on the same network. | -| userId | Yes | No | number | User ID. The default value is the ID of the current user. If this parameter is specified, the value must be an existing user ID in the system.| -| priority | Yes | No | number | Subscriber priority. The value ranges from -100 to 1000. | +| Name | Type | Readable| Writable| Description | +| ------------------- | -------------- | ---- | ---- | ------------------------------------------------------------ | +| events | Array\ | Yes | No | Name of the common event to publish. | +| publisherPermission | string | Yes | No | Permissions required for publishers to publish the common event. | +| publisherDeviceId | string | Yes | No | Device ID. The value must be the ID of an existing device on the same network. | +| userId | number | Yes | No | User ID. The default value is the ID of the current user. If this parameter is specified, the value must be an existing user ID in the system.| +| priority | number | Yes | No | Subscriber priority. The value ranges from -100 to +1000. | diff --git a/en/application-dev/reference/apis/js-apis-commonEventManager.md b/en/application-dev/reference/apis/js-apis-commonEventManager.md new file mode 100644 index 0000000000..3489db4f58 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-commonEventManager.md @@ -0,0 +1,1353 @@ +# @ohos.commonEventManager + +The **CommonEventManager** module provides common event capabilities, including the capabilities to publish, subscribe to, and unsubscribe from common events, as well obtaining and setting the common event result code and result data. + +> **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 + +```ts +import CommonEventManager from '@ohos.commonEventManager'; +``` + +## Support + +The table below lists the event types supported by the **CommonEventManager** module. The name and value indicate the macro and name of a common event, respectively. + +**System capability**: SystemCapability.Notification.CommonEvent + +| Name | Value | Subscriber Permission | Description | +| ------------ | ------------------ | ---------------------- | -------------------- | +| COMMON_EVENT_BOOT_COMPLETED | usual.event.BOOT_COMPLETED | ohos.permission.RECEIVER_STARTUP_COMPLETED | Indicates the common event that the user has finished booting and the system has been loaded. | +| COMMON_EVENT_LOCKED_BOOT_COMPLETED | usual.event.LOCKED_BOOT_COMPLETED | ohos.permission.RECEIVER_STARTUP_COMPLETED | Indicates the common event that the user has finished booting and the system has been loaded but the screen is still locked. | +| COMMON_EVENT_SHUTDOWN | usual.event.SHUTDOWN | - | Indicates the common event that the device is being shut down and the final shutdown will proceed. | +| COMMON_EVENT_BATTERY_CHANGED | usual.event.BATTERY_CHANGED | - | Indicates the common event that the charging state, level, and other information about the battery have changed. | +| COMMON_EVENT_BATTERY_LOW | usual.event.BATTERY_LOW | - | Indicates the common event that the battery level is low. | +| COMMON_EVENT_BATTERY_OKAY | usual.event.BATTERY_OKAY | - | Indicates the common event that the battery exits the low state. | +| COMMON_EVENT_POWER_CONNECTED | usual.event.POWER_CONNECTED | - | Indicates the common event that the device is connected to an external power supply. | +| COMMON_EVENT_POWER_DISCONNECTED | usual.event.POWER_DISCONNECTED | - | Indicates the common event that the device is disconnected from the external power supply. | +| COMMON_EVENT_SCREEN_OFF | usual.event.SCREEN_OFF | - | Indicates the common event that the device screen is off and the device is sleeping. | +| COMMON_EVENT_SCREEN_ON | usual.event.SCREEN_ON | - | Indicates the common event that the device screen is on and the device is in interactive state. | +| COMMON_EVENT_THERMAL_LEVEL_CHANGED | usual.event.THERMAL_LEVEL_CHANGED | - | Indicates the common event that the device's thermal level has changed. | +| COMMON_EVENT_USER_PRESENT | usual.event.USER_PRESENT | - | Indicates the common event that the user unlocks the device. | +| COMMON_EVENT_TIME_TICK | usual.event.TIME_TICK | - | Indicates the common event that the system time has changed. | +| COMMON_EVENT_TIME_CHANGED | usual.event.TIME_CHANGED | - | Indicates the common event that the system time is set. | +| COMMON_EVENT_DATE_CHANGED | usual.event.DATE_CHANGED | - | Indicates the common event that the system time has changed. | +| COMMON_EVENT_TIMEZONE_CHANGED | usual.event.TIMEZONE_CHANGED | - | Indicates the common event that the system time zone has changed. | +| COMMON_EVENT_CLOSE_SYSTEM_DIALOGS | usual.event.CLOSE_SYSTEM_DIALOGS | - | Indicates the common event that a user closes a temporary system dialog box. | +| COMMON_EVENT_PACKAGE_ADDED | usual.event.PACKAGE_ADDED | - | Indicates the common event that a new application package has been installed on the device. | +| COMMON_EVENT_PACKAGE_REPLACED | usual.event.PACKAGE_REPLACED | - | Indicates the common event that a later version of an installed application package has replaced the previous one on the device. | +| COMMON_EVENT_MY_PACKAGE_REPLACED | usual.event.MY_PACKAGE_REPLACED | - | Indicates the common event that a later version of your application package has replaced the previous one. +| COMMON_EVENT_PACKAGE_REMOVED | usual.event.PACKAGE_REMOVED | - | Indicates the common event that an installed application has been uninstalled from the device with the application data retained. | +| COMMON_EVENT_BUNDLE_REMOVED | usual.event.BUNDLE_REMOVED | - | Indicates the common event that an installed bundle has been uninstalled from the device with the application data retained. | +| COMMON_EVENT_PACKAGE_FULLY_REMOVED | usual.event.PACKAGE_FULLY_REMOVED | - | Indicates the common event that an installed application, including both the application data and code, has been completely uninstalled from the device. | +| COMMON_EVENT_PACKAGE_CHANGED | usual.event.PACKAGE_CHANGED | - | Indicates the common event that an application package has been changed (for example, a component in the package has been enabled or disabled). | +| COMMON_EVENT_PACKAGE_RESTARTED | usual.event.PACKAGE_RESTARTED | - | Indicates the common event that the user has restarted the application package and killed all its processes. | +| COMMON_EVENT_PACKAGE_DATA_CLEARED | usual.event.PACKAGE_DATA_CLEARED | - | Indicates the common event that the user has cleared the application package data. | +| COMMON_EVENT_PACKAGE_CACHE_CLEARED9+ | usual.event.PACKAGE_CACHE_CLEARED | - | Indicates the common event that the user has cleared the application package data. | +| COMMON_EVENT_PACKAGES_SUSPENDED | usual.event.PACKAGES_SUSPENDED | - | Indicates the common event that application packages have been suspended. | +| COMMON_EVENT_PACKAGES_UNSUSPENDED | usual.event.PACKAGES_UNSUSPENDED | - | Indicates the common event that application package has not been suspended. | +| COMMON_EVENT_MY_PACKAGE_SUSPENDED | usual.event.MY_PACKAGE_SUSPENDED | - | Indicates the common event that an application package has been suspended. | +| COMMON_EVENT_MY_PACKAGE_UNSUSPENDED | usual.event.MY_PACKAGE_UNSUSPENDED | - | Indicates the common event that application package has not been suspended. | +| COMMON_EVENT_UID_REMOVED | usual.event.UID_REMOVED | - | Indicates the common event that a user ID has been removed from the system. | +| COMMON_EVENT_PACKAGE_FIRST_LAUNCH | usual.event.PACKAGE_FIRST_LAUNCH | - | Indicates the common event that an installed application is started for the first time. | +| COMMON_EVENT_PACKAGE_NEEDS_VERIFICATION | usual.event.PACKAGE_NEEDS_VERIFICATION | - | Indicates the common event that an application requires system verification. | +| COMMON_EVENT_PACKAGE_VERIFIED | usual.event.PACKAGE_VERIFIED | - | Indicates the common event that an application has been verified by the system. | +| COMMON_EVENT_EXTERNAL_APPLICATIONS_AVAILABLE | usual.event.EXTERNAL_APPLICATIONS_AVAILABLE | - | Indicates the common event that applications installed on the external storage become available for the system. | +| COMMON_EVENT_EXTERNAL_APPLICATIONS_UNAVAILABLE | usual.event.EXTERNAL_APPLICATIONS_UNAVAILABLE | - | Indicates the common event that applications installed on the external storage become unavailable for the system. | +| COMMON_EVENT_CONFIGURATION_CHANGED | usual.event.CONFIGURATION_CHANGED | - | Indicates the common event that the device state (for example, orientation and locale) has changed. | +| COMMON_EVENT_LOCALE_CHANGED | usual.event.LOCALE_CHANGED | - | Indicates the common event that the device locale has changed. | +| COMMON_EVENT_MANAGE_PACKAGE_STORAGE | usual.event.MANAGE_PACKAGE_STORAGE | - | Indicates the common event that the device storage is insufficient. | +| COMMON_EVENT_DRIVE_MODE | common.event.DRIVE_MODE | - | Indicates the common event that the system is in driving mode. | +| COMMON_EVENT_HOME_MODE | common.event.HOME_MODE | - | Indicates the common event that the system is in home mode. | +| COMMON_EVENT_OFFICE_MODE | common.event.OFFICE_MODE | - | Indicates the common event that the system is in office mode. | +| COMMON_EVENT_USER_STARTED | usual.event.USER_STARTED | - | Indicates the common event that the user has been started. | +| COMMON_EVENT_USER_BACKGROUND | usual.event.USER_BACKGROUND | - | Indicates the common event that the user has been brought to the background. | +| COMMON_EVENT_USER_FOREGROUND | usual.event.USER_FOREGROUND | - | Indicates the common event that the user has been brought to the foreground. | +| COMMON_EVENT_USER_SWITCHED | usual.event.USER_SWITCHED | ohos.permission.MANAGE_LOCAL_ACCOUNTS | Indicates the common event that user switching is happening. | +| COMMON_EVENT_USER_STARTING | usual.event.USER_STARTING | ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS | Indicates the common event that the user is going to be started. | +| COMMON_EVENT_USER_UNLOCKED | usual.event.USER_UNLOCKED | - | Indicates the common event that the credential-encrypted storage has been unlocked for the current user when the device is unlocked after being restarted. | +| COMMON_EVENT_USER_STOPPING | usual.event.USER_STOPPING | ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS | Indicates the common event that the user is going to be stopped. | +| COMMON_EVENT_USER_STOPPED | usual.event.USER_STOPPED | - | Indicates the common event that the user has been stopped. | +| COMMON_EVENT_DISTRIBUTED_ACCOUNT_LOGIN | usual.event.DISTRIBUTED_ACCOUNT_LOGIN | - | Indicates the action of successful login using a distributed account. | +| COMMON_EVENT_DISTRIBUTED_ACCOUNT_LOGOUT | usual.event.DISTRIBUTED_ACCOUNT_LOGOUT | - | Indicates the action of successful logout of a distributed account. | +| COMMON_EVENT_DISTRIBUTED_ACCOUNT_TOKEN_INVALID | usual.event.DISTRIBUTED_ACCOUNT_TOKEN_INVALID | - | Indicates the action when the token of a distributed account is invalid. | +| COMMON_EVENT_DISTRIBUTED_ACCOUNT_LOGOFF | usual.event.DISTRIBUTED_ACCOUNT_LOGOFF | - | Indicates the action of deregistering a distributed account. | +| COMMON_EVENT_WIFI_POWER_STATE | usual.event.wifi.POWER_STATE | - | Indicates the common event about the Wi-Fi network state, such as enabled and disabled. | +| COMMON_EVENT_WIFI_SCAN_FINISHED | usual.event.wifi.SCAN_FINISHED | ohos.permission.LOCATION | Indicates the common event that the Wi-Fi access point has been scanned and proven to be available. | +| COMMON_EVENT_WIFI_RSSI_VALUE | usual.event.wifi.RSSI_VALUE | ohos.permission.GET_WIFI_INFO | Indicates the common event that the Wi-Fi signal strength (RSSI) has changed. | +| COMMON_EVENT_WIFI_CONN_STATE | usual.event.wifi.CONN_STATE | - | Indicates the common event that the Wi-Fi connection state has changed. | +| COMMON_EVENT_WIFI_HOTSPOT_STATE | usual.event.wifi.HOTSPOT_STATE | - | Indicates the common event about the Wi-Fi hotspot state, such as enabled or disabled. | +| COMMON_EVENT_WIFI_AP_STA_JOIN | usual.event.wifi.WIFI_HS_STA_JOIN | ohos.permission.GET_WIFI_INFO | Indicates the common event that a client has joined the Wi-Fi hotspot of the current device. | +| COMMON_EVENT_WIFI_AP_STA_LEAVE | usual.event.wifi.WIFI_HS_STA_LEAVE | ohos.permission.GET_WIFI_INFO |Indicates the common event that a client has disconnected from the Wi-Fi hotspot of the current device. | +| COMMON_EVENT_WIFI_MPLINK_STATE_CHANGE | usual.event.wifi.mplink.STATE_CHANGE | ohos.permission.MPLINK_CHANGE_STATE | Indicates the common event that the state of MPLINK (an enhanced Wi-Fi feature) has changed. | +| COMMON_EVENT_WIFI_P2P_CONN_STATE | usual.event.wifi.p2p.CONN_STATE_CHANGE | ohos.permission.GET_WIFI_INFO and ohos.permission.LOCATION | Indicates the common event that the Wi-Fi P2P connection state has changed. | +| COMMON_EVENT_WIFI_P2P_STATE_CHANGED | usual.event.wifi.p2p.STATE_CHANGE | ohos.permission.GET_WIFI_INFO | Indicates the common event about the Wi-Fi P2P state, such as enabled and disabled. | +| COMMON_EVENT_WIFI_P2P_PEERS_STATE_CHANGED | usual.event.wifi.p2p.DEVICES_CHANGE | ohos.permission.GET_WIFI_INFO | Indicates the common event about the status change of Wi-Fi P2P peer devices. | +| COMMON_EVENT_WIFI_P2P_PEERS_DISCOVERY_STATE_CHANGED | usual.event.wifi.p2p.PEER_DISCOVERY_STATE_CHANGE | ohos.permission.GET_WIFI_INFO | Indicates the common event about the Wi-Fi P2P discovery status change. | +| COMMON_EVENT_WIFI_P2P_CURRENT_DEVICE_STATE_CHANGED | usual.event.wifi.p2p.CURRENT_DEVICE_CHANGE | ohos.permission.GET_WIFI_INFO | Indicates the common event about the status change of the Wi-Fi P2P local device. | +| COMMON_EVENT_WIFI_P2P_GROUP_STATE_CHANGED | usual.event.wifi.p2p.GROUP_STATE_CHANGED | ohos.permission.GET_WIFI_INFO | Indicates the common event that the Wi-Fi P2P group information has changed. | +| COMMON_EVENT_BLUETOOTH_HANDSFREE_AG_CONNECT_STATE_UPDATE | usual.event.bluetooth.handsfree.ag.CONNECT_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event about the connection state of Bluetooth handsfree communication. | +| COMMON_EVENT_BLUETOOTH_HANDSFREE_AG_CURRENT_DEVICE_UPDATE | usual.event.bluetooth.handsfree.ag.CURRENT_DEVICE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the device connected to the Bluetooth handsfree is active. | +| COMMON_EVENT_BLUETOOTH_HANDSFREE_AG_AUDIO_STATE_UPDATE | usual.event.bluetooth.handsfree.ag.AUDIO_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the connection state of Bluetooth A2DP has changed. | +| COMMON_EVENT_BLUETOOTH_A2DPSOURCE_CONNECT_STATE_UPDATE | usual.event.bluetooth.a2dpsource.CONNECT_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event about the connection state of Bluetooth A2DP. | +| COMMON_EVENT_BLUETOOTH_A2DPSOURCE_CURRENT_DEVICE_UPDATE | usual.event.bluetooth.a2dpsource.CURRENT_DEVICE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the device connected using Bluetooth A2DP is active. | +| COMMON_EVENT_BLUETOOTH_A2DPSOURCE_PLAYING_STATE_UPDATE | usual.event.bluetooth.a2dpsource.PLAYING_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the playing state of Bluetooth A2DP has changed. | +| COMMON_EVENT_BLUETOOTH_A2DPSOURCE_AVRCP_CONNECT_STATE_UPDATE | usual.event.bluetooth.a2dpsource.AVRCP_CONNECT_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the AVRCP connection state of Bluetooth A2DP has changed. | +| COMMON_EVENT_BLUETOOTH_A2DPSOURCE_CODEC_VALUE_UPDATE | usual.event.bluetooth.a2dpsource.CODEC_VALUE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the audio codec state of Bluetooth A2DP has changed. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_DISCOVERED | usual.event.bluetooth.remotedevice.DISCOVERED | ohos.permission.LOCATION and ohos.permission.USE_BLUETOOTH | Indicates the common event that a remote Bluetooth device is discovered. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_CLASS_VALUE_UPDATE | usual.event.bluetooth.remotedevice.CLASS_VALUE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the Bluetooth class of a remote Bluetooth device has changed. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_ACL_CONNECTED | usual.event.bluetooth.remotedevice.ACL_CONNECTED | ohos.permission.USE_BLUETOOTH | Indicates the common event that a low-ACL connection has been established with a remote Bluetooth device. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_ACL_DISCONNECTED | usual.event.bluetooth.remotedevice.ACL_DISCONNECTED | ohos.permission.USE_BLUETOOTH | Indicates the common event that a low-ACL connection has been disconnected from a remote Bluetooth device. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_NAME_UPDATE | usual.event.bluetooth.remotedevice.NAME_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the friendly name of a remote Bluetooth device is retrieved for the first time or is changed since the last retrieval. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_PAIR_STATE | usual.event.bluetooth.remotedevice.PAIR_STATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the connection state of a remote Bluetooth device has changed. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_BATTERY_VALUE_UPDATE | usual.event.bluetooth.remotedevice.BATTERY_VALUE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the battery level of a remote Bluetooth device is retrieved for the first time or is changed since the last retrieval. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_SDP_RESULT | usual.event.bluetooth.remotedevice.SDP_RESULT | - | Indicates the common event about the SDP state of a remote Bluetooth device. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_UUID_VALUE | usual.event.bluetooth.remotedevice.UUID_VALUE | ohos.permission.DISCOVER_BLUETOOTH | Indicates the common event about the UUID connection state of a remote Bluetooth device. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_PAIRING_REQ | usual.event.bluetooth.remotedevice.PAIRING_REQ | ohos.permission.DISCOVER_BLUETOOTH | Indicates the common event about the pairing request from a remote Bluetooth device. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_PAIRING_CANCEL | usual.event.bluetooth.remotedevice.PAIRING_CANCEL | - | Indicates the common event that Bluetooth pairing is canceled. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_CONNECT_REQ | usual.event.bluetooth.remotedevice.CONNECT_REQ | - | Indicates the common event about the connection request from a remote Bluetooth device. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_CONNECT_REPLY | usual.event.bluetooth.remotedevice.CONNECT_REPLY | - | Indicates the common event about the response to the connection request from a remote Bluetooth device. | +| COMMON_EVENT_BLUETOOTH_REMOTEDEVICE_CONNECT_CANCEL | usual.event.bluetooth.remotedevice.CONNECT_CANCEL | - | Indicates the common event that the connection to a remote Bluetooth device has been canceled. | +| COMMON_EVENT_BLUETOOTH_HANDSFREEUNIT_CONNECT_STATE_UPDATE | usual.event.bluetooth.handsfreeunit.CONNECT_STATE_UPDATE | - | Indicates the common event that the connection state of a Bluetooth handsfree has changed. | +| COMMON_EVENT_BLUETOOTH_HANDSFREEUNIT_AUDIO_STATE_UPDATE | usual.event.bluetooth.handsfreeunit.AUDIO_STATE_UPDATE | - | Indicates the common event that the audio state of a Bluetooth handsfree has changed. | +| COMMON_EVENT_BLUETOOTH_HANDSFREEUNIT_AG_COMMON_EVENT | usual.event.bluetooth.handsfreeunit.AG_COMMON_EVENT | - | Indicates the common event that the audio gateway state of a Bluetooth handsfree has changed. | +| COMMON_EVENT_BLUETOOTH_HANDSFREEUNIT_AG_CALL_STATE_UPDATE | usual.event.bluetooth.handsfreeunit.AG_CALL_STATE_UPDATE | - | Indicates the common event that the calling state of a Bluetooth handsfree has changed. | +| COMMON_EVENT_BLUETOOTH_HOST_STATE_UPDATE | usual.event.bluetooth.host.STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the state of a Bluetooth adapter has been changed, for example, Bluetooth has been enabled or disabled. | +| COMMON_EVENT_BLUETOOTH_HOST_REQ_DISCOVERABLE | usual.event.bluetooth.host.REQ_DISCOVERABLE | - | Indicates the common event about the request for the user to allow Bluetooth device scanning. | +| COMMON_EVENT_BLUETOOTH_HOST_REQ_ENABLE | usual.event.bluetooth.host.REQ_ENABLE | ohos.permission.USE_BLUETOOTH | Indicates the common event about the request for the user to enable Bluetooth. | +| COMMON_EVENT_BLUETOOTH_HOST_REQ_DISABLE | usual.event.bluetooth.host.REQ_DISABLE | ohos.permission.USE_BLUETOOTH | Indicates the common event about the request for the user to disable Bluetooth. | +| COMMON_EVENT_BLUETOOTH_HOST_SCAN_MODE_UPDATE | usual.event.bluetooth.host.SCAN_MODE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the Bluetooth scanning mode of a device has changed. | +| COMMON_EVENT_BLUETOOTH_HOST_DISCOVERY_STARTED | usual.event.bluetooth.host.DISCOVERY_STARTED | ohos.permission.USE_BLUETOOTH | Indicates the common event that the Bluetooth scanning has been started on the device. | +| COMMON_EVENT_BLUETOOTH_HOST_DISCOVERY_FINISHED | usual.event.bluetooth.host.DISCOVERY_FINISHED | ohos.permission.USE_BLUETOOTH | Indicates the common event that the Bluetooth scanning is finished on the device. | +| COMMON_EVENT_BLUETOOTH_HOST_NAME_UPDATE | usual.event.bluetooth.host.NAME_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the Bluetooth adapter name of the device has changed. | +| COMMON_EVENT_BLUETOOTH_A2DPSINK_CONNECT_STATE_UPDATE | usual.event.bluetooth.a2dpsink.CONNECT_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the connection state of Bluetooth A2DP Sink has changed. | +| COMMON_EVENT_BLUETOOTH_A2DPSINK_PLAYING_STATE_UPDATE | usual.event.bluetooth.a2dpsink.PLAYING_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the playing state of Bluetooth A2DP Sink has changed. | +| COMMON_EVENT_BLUETOOTH_A2DPSINK_AUDIO_STATE_UPDATE | usual.event.bluetooth.a2dpsink.AUDIO_STATE_UPDATE | ohos.permission.USE_BLUETOOTH | Indicates the common event that the audio state of Bluetooth A2DP Sink has changed. | +| COMMON_EVENT_NFC_ACTION_ADAPTER_STATE_CHANGED | usual.event.nfc.action.ADAPTER_STATE_CHANGED | - | Indicates the common event that the state of the device's NFC adapter has changed. | +| COMMON_EVENT_NFC_ACTION_RF_FIELD_ON_DETECTED | usual.event.nfc.action.RF_FIELD_ON_DETECTED | ohos.permission.MANAGE_SECURE_SETTINGS | Indicates the action of a common event that the NFC RF field is detected to be in the enabled state. | +| COMMON_EVENT_NFC_ACTION_RF_FIELD_OFF_DETECTED | usual.event.nfc.action.RF_FIELD_OFF_DETECTED | ohos.permission.MANAGE_SECURE_SETTINGS | Indicates the common event that the NFC RF field is detected to be in the disabled state. | +| COMMON_EVENT_DISCHARGING | usual.event.DISCHARGING | - | Indicates the common event that the system stops charging the battery. | +| COMMON_EVENT_CHARGING | usual.event.CHARGING | - | Indicates the common event that the system starts charging the battery. | +| COMMON_EVENT_DEVICE_IDLE_MODE_CHANGED | usual.event.DEVICE_IDLE_MODE_CHANGED | - | Indicates the common event that the system idle mode has changed. | +| COMMON_EVENT_POWER_SAVE_MODE_CHANGED | usual.event.POWER_SAVE_MODE_CHANGED | - | Indicates the common event that the power saving mode of the system has changed. | +| COMMON_EVENT_USER_ADDED | usual.event.USER_ADDED | ohos.permission.MANAGE_LOCAL_ACCOUNTS | Indicates the common event that a user has been added to the system. | +| COMMON_EVENT_USER_REMOVED | usual.event.USER_REMOVED | ohos.permission.MANAGE_LOCAL_ACCOUNTS | Indicates the common event that a user has been removed from the system. | +| COMMON_EVENT_ABILITY_ADDED | usual.event.ABILITY_ADDED | ohos.permission.LISTEN_BUNDLE_CHANGE | Indicates the common event that an ability has been added. | +| COMMON_EVENT_ABILITY_REMOVED | usual.event.ABILITY_REMOVED | ohos.permission.LISTEN_BUNDLE_CHANGE | Indicates the common event that an ability has been removed. | +| COMMON_EVENT_ABILITY_UPDATED | usual.event.ABILITY_UPDATED | ohos.permission.LISTEN_BUNDLE_CHANGE | Indicates the common event that an ability has been updated. | +| COMMON_EVENT_LOCATION_MODE_STATE_CHANGED | usual.event.location.MODE_STATE_CHANGED | - | Indicates the common event that the location mode of the system has changed. | +| COMMON_EVENT_IVI_SLEEP | common.event.IVI_SLEEP | - | Indicates the common event that the in-vehicle infotainment (IVI) system of a vehicle is sleeping. | +| COMMON_EVENT_IVI_PAUSE | common.event.IVI_PAUSE | - | Indicates the common event that the IVI system of a vehicle has entered sleep mode and the playing application is instructed to stop playback. | +| COMMON_EVENT_IVI_STANDBY | common.event.IVI_STANDBY | - | Indicates the common event that a third-party application is instructed to pause the current work. | +| COMMON_EVENT_IVI_LASTMODE_SAVE | common.event.IVI_LASTMODE_SAVE | - | Indicates the common event that a third-party application is instructed to save its last mode. | +| COMMON_EVENT_IVI_VOLTAGE_ABNORMAL | common.event.IVI_VOLTAGE_ABNORMAL | - | Indicates the common event that the voltage of the vehicle's power system is abnormal. | +| COMMON_EVENT_IVI_HIGH_TEMPERATURE | common.event.IVI_HIGH_TEMPERATURE | - | Indicates the common event that the temperature of the IVI system is high. | +| COMMON_EVENT_IVI_EXTREME_TEMPERATURE | common.event.IVI_EXTREME_TEMPERATURE | - | Indicates the common event that the temperature of the IVI system is extremely high. | +| COMMON_EVENT_IVI_TEMPERATURE_ABNORMAL | common.event.IVI_TEMPERATURE_ABNORMAL | - | Indicates the common event that the IVI system has an extreme temperature. | +| COMMON_EVENT_IVI_VOLTAGE_RECOVERY | common.event.IVI_VOLTAGE_RECOVERY | - | Indicates the common event that the voltage of the vehicle's power system is restored to normal. | +| COMMON_EVENT_IVI_TEMPERATURE_RECOVERY | common.event.IVI_TEMPERATURE_RECOVERY | - | Indicates the common event that the temperature of the IVI system is restored to normal. | +| COMMON_EVENT_IVI_ACTIVE | common.event.IVI_ACTIVE | - | Indicates the common event that the battery service is active. | +|COMMON_EVENT_USB_STATE9+ | usual.event.hardware.usb.action.USB_STATE | - | Indicates a common event indicating that the USB device status changes. | +|COMMON_EVENT_USB_PORT_CHANGED9+ | usual.event.hardware.usb.action.USB_PORT_CHANGED | - | Indicates the public event that the USB port status of the user device changes. | +| COMMON_EVENT_USB_DEVICE_ATTACHED | usual.event.hardware.usb.action.USB_DEVICE_ATTACHED | - | Indicates the common event that a USB device has been attached when the user device functions as a USB host. | +| COMMON_EVENT_USB_DEVICE_DETACHED | usual.event.hardware.usb.action.USB_DEVICE_DETACHED | - | Indicates the common event that a USB device has been detached when the user device functions as a USB host. | +| COMMON_EVENT_USB_ACCESSORY_ATTACHED | usual.event.hardware.usb.action.USB_ACCESSORY_ATTACHED | - | Indicates the common event that a USB accessory was attached. | +| COMMON_EVENT_USB_ACCESSORY_DETACHED | usual.event.hardware.usb.action.USB_ACCESSORY_DETACHED | - | Indicates the common event that a USB accessory was detached. | +| COMMON_EVENT_DISK_REMOVED | usual.event.data.DISK_REMOVED | ohos.permission.STORAGE_MANAGER | Indicates the common event that an external storage device was removed. | +| COMMON_EVENT_DISK_UNMOUNTED | usual.event.data.DISK_UNMOUNTED | ohos.permission.STORAGE_MANAGER | Indicates the common event that an external storage device was unmounted. | +| COMMON_EVENT_DISK_MOUNTED | usual.event.data.DISK_MOUNTED | ohos.permission.STORAGE_MANAGER | Indicates the common event that an external storage device was mounted. | +| COMMON_EVENT_DISK_BAD_REMOVAL | usual.event.data.DISK_BAD_REMOVAL | ohos.permission.STORAGE_MANAGER | Indicates the common event that an external storage device was removed without being unmounted. | +| COMMON_EVENT_DISK_UNMOUNTABLE | usual.event.data.DISK_UNMOUNTABLE | ohos.permission.STORAGE_MANAGER | Indicates the common event that an external storage device becomes unmountable. | +| COMMON_EVENT_DISK_EJECT | usual.event.data.DISK_EJECT | ohos.permission.STORAGE_MANAGER | Indicates the common event that an external storage device was ejected. | +| COMMON_EVENT_VOLUME_REMOVED9+ | usual.event.data.VOLUME_REMOVED | ohos.permission.STORAGE_MANAGER | Indicates the common event that an external storage device was removed. | +| COMMON_EVENT_VOLUME_UNMOUNTED9+ | usual.event.data.VOLUME_UNMOUNTED | ohos.permission.STORAGE_MANAGER | Indicates the common event that an external storage device was unmounted. | +| COMMON_EVENT_VOLUME_MOUNTED9+ | usual.event.data.VOLUME_MOUNTED | ohos.permission.STORAGE_MANAGER | Indicates the common event that an external storage device was mounted. | +| COMMON_EVENT_VOLUME_BAD_REMOVAL9+ | usual.event.data.VOLUME_BAD_REMOVAL | ohos.permission.STORAGE_MANAGER | Indicates the common event that an external storage device was removed without being unmounted. | +| COMMON_EVENT_VOLUME_EJECT9+ | usual.event.data.VOLUME_EJECT | ohos.permission.STORAGE_MANAGER | Indicates the common event that an external storage device was ejected. | +| COMMON_EVENT_VISIBLE_ACCOUNTS_UPDATED | usual.event.data.VISIBLE_ACCOUNTS_UPDATED | ohos.permission.GET_APP_ACCOUNTS | Indicates the common event that the account visibility changed. | +| COMMON_EVENT_ACCOUNT_DELETED | usual.event.data.ACCOUNT_DELETED | ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS | Indicates the common event that the account was deleted. | +| COMMON_EVENT_FOUNDATION_READY | usual.event.data.FOUNDATION_READY | ohos.permission.RECEIVER_STARTUP_COMPLETED | Indicates the common event that the foundation is ready. | +| COMMON_EVENT_AIRPLANE_MODE_CHANGED | usual.event.AIRPLANE_MODE | - | Indicates the common event that the airplane mode of the device has changed. | +| COMMON_EVENT_SPLIT_SCREEN | usual.event.SPLIT_SCREEN | ohos.permission.RECEIVER_SPLIT_SCREEN | Indicates the common event of screen splitting. | +| COMMON_EVENT_SLOT_CHANGE9+ | usual.event.SLOT_CHANGE | ohos.permission.NOTIFICATION_CONTROLLER | Indicates the common event that the notification slot has been updated. | +| COMMON_EVENT_SPN_INFO_CHANGED 9+ | usual.event.SPN_INFO_CHANGED | - | Indicates the common event that the SPN displayed has been updated. | +| COMMON_EVENT_QUICK_FIX_APPLY_RESULT 9+ | usual.event.QUICK_FIX_APPLY_RESULT | - | Indicates the common event that a quick fix is applied to the application. | + + +## CommonEventManager.publish + +publish(event: string, callback: AsyncCallback\): void + +Publishes a common event. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ---------------------- | +| event | string | Yes | Name of the common event to publish.| +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Error codes** +For details about the error codes, see [Event Error Codes](../errorcodes/errorcode-CommonEventService.md). + +|ID |Error Message | +|-----------|--------------------| +|1500004 |not System services or System app| +|1500007 |message send error| +|1500008 |CEMS error| +|1500009 |system error| + +**Example** + +```ts +// Callback for common event publication +function publishCallBack(err) { + if (err) { + console.error("publish failed " + JSON.stringify(err)); + } else { + console.info("publish"); + } +} + +// Publish a common event. +try { + CommonEventManager.publish("event", publishCallBack); +} catch(err) { + console.error('publish failed, catch error' + JSON.stringify(err)); +} +``` + +## CommonEventManager.publish + +publish(event: string, options: CommonEventPublishData, callback: AsyncCallback\): void + +Publishes a common event with given attributes. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | ---------------------- | +| event | string | Yes | Name of the common event to publish. | +| options | [CommonEventPublishData](#commoneventpublishdata) | Yes | Attributes of the common event to publish.| +| callback | syncCallback\ | Yes | Callback used to return the result. | + +**Error codes** +|ID |Error Message | +|-----------|--------------------| +|1500004 |not System services or System app| +|1500007 |message send error| +|1500008 |CEMS error| +|1500009 |system error| + + +**Example** + + +```ts +// Attributes of a common event. +var options = { + code: 0, // Result code of the common event. + data: "initial data",// Result data of the common event. + isOrdered: true // The common event is an ordered one. +} + +// Callback for common event publication +function publishCallBack(err) { + if (err) { + console.error("publish failed " + JSON.stringify(err)); + } else { + console.info("publish"); + } +} + +// Publish a common event. +try { + CommonEventManager.publish("event", options, publishCallBack); +} catch (err) { + console.error('publish failed, catch error' + JSON.stringify(err)); +} +``` + + + +## CommonEventManager.publishAsUser + +publishAsUser(event: string, userId: number, callback: AsyncCallback\): void + +Publishes a common event to a specific user. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ---------------------------------- | +| event | string | Yes | Name of the common event to publish. | +| userId | number | Yes | User ID.| +| callback | AsyncCallback\ | Yes | Callback used to return the result. | + +**Error codes** +|ID |Error Message | +|-----------|--------------------| +|1500004 |not System services or System app| +|1500007 |message send error| +|1500008 |CEMS error| +|1500009 |system error| + +**Example** + +```ts +// Callback for common event publication +function publishAsUserCallBack(err) { + if (err) { + console.error("publishAsUser failed " + JSON.stringify(err)); + } else { + console.info("publishAsUser"); + } +} + +// Specify the user to whom the common event will be published. +var userId = 100; + +// Publish a common event. +try { + CommonEventManager.publishAsUser("event", userId, publishAsUserCallBack); +} catch (err) { + console.error('publishAsUser failed, catch error' + JSON.stringify(err)); +} +``` + + + +## CommonEventManager.publishAsUser + +publishAsUser(event: string, userId: number, options: CommonEventPublishData, callback: AsyncCallback\): void + +Publishes a common event with given attributes to a specific user. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | ---------------------- | +| event | string | Yes | Name of the common event to publish. | +| userId | number | Yes| User ID.| +| options | [CommonEventPublishData](#commoneventpublishdata) | Yes | Attributes of the common event to publish.| +| callback | AsyncCallback\ | Yes | Callback used to return the result. | + +**Error codes** +|ID |Error Message | +|-----------|--------------------| +|1500004 |not System services or System app| +|1500007 |message send error| +|1500008 |CEMS error| +|1500009 |system error| + +**Example** + + +```ts +// Attributes of a common event. +var options = { + code: 0, // Result code of the common event. + data: "initial data",// Result data of the common event. +} + +// Callback for common event publication +function publishAsUserCallBack(err) { + if (err) { + console.error("publishAsUser failed " + JSON.stringify(err)); + } else { + console.info("publishAsUser"); + } +} + +// Specify the user to whom the common event will be published. +var userId = 100; + +// Publish a common event. +try { + CommonEventManager.publishAsUser("event", userId, options, publishAsUserCallBack); +} catch (err) { + console.error('publishAsUser failed, catch error' + JSON.stringify(err)); +} +``` + + + +## CommonEventManager.createSubscriber + +createSubscriber(subscribeInfo: CommonEventSubscribeInfo, callback: AsyncCallback\): void + +Creates a subscriber. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------- | ------------------------------------------------------------ | ---- | -------------------------- | +| subscribeInfo | [CommonEventSubscribeInfo](#commoneventsubscribeinfo) | Yes | Subscriber information. | +| callback | AsyncCallback\<[CommonEventSubscriber](#commoneventsubscriber)> | Yes | Callback used to return the result.| + +**Example** + + +```ts +var subscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription. + +// Subscriber information. +var subscribeInfo = { + events: ["event"] +}; + +// Callback for subscriber creation. +function createSubscriberCallBack(err, commonEventSubscriber) { + if(!err) { + console.info("createSubscriber"); + subscriber = commonEventSubscriber; + } else { + console.error("createSubscriber failed " + JSON.stringify(err)); + } +} + +// Create a subscriber. +try { + CommonEventManager.createSubscriber(subscribeInfo, createSubscriberCallBack); +} catch (err) { + console.error('createSubscriber failed, catch error' + JSON.stringify(err)); +} +``` + + + +## CommonEventManager.createSubscriber + +createSubscriber(subscribeInfo: CommonEventSubscribeInfo): Promise\ + +Creates a subscriber. This API uses a promise to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------- | ----------------------------------------------------- | ---- | -------------- | +| subscribeInfo | [CommonEventSubscribeInfo](#commoneventsubscribeinfo) | Yes | Subscriber information.| + +**Return value** +| Type | Description | +| --------------------------------------------------------- | ---------------- | +| Promise\<[CommonEventSubscriber](#commoneventsubscriber)> | Promise used to return the subscriber object.| + +**Example** + +```ts +var subscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription. + +// Subscriber information. +var subscribeInfo = { + events: ["event"] +}; + +// Create a subscriber. +try { + CommonEventManager.createSubscriber(subscribeInfo).then((commonEventSubscriber) => { + console.info("createSubscriber"); + subscriber = commonEventSubscriber; +}).catch((err) => { + console.error("createSubscriber failed " + JSON.stringify(err)); +}); +} catch(err) { + console.error('createSubscriber failed, catch error' + JSON.stringify(err)); +} + +``` + + + +## CommonEventManager.subscribe + +subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback\): void + +Subscribes to common events. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ---------------------------------------------------- | ---- | -------------------------------- | +| subscriber | [CommonEventSubscriber](#commoneventsubscriber) | Yes | Subscriber object. | +| callback | AsyncCallback\<[CommonEventData](#commoneventdata)> | Yes | Callback used to return the result.| + +**Example** + +```ts +// Subscriber information. +var subscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription. + +// Subscriber information. +var subscribeInfo = { + events: ["event"] +}; + +// Callback for common event subscription. +function SubscribeCallBack(err, data) { + if (err.code) { + console.error("subscribe failed " + JSON.stringify(err)); + } else { + console.info("subscribe "); + } +} + +// Callback for subscriber creation. +function createSubscriberCallBack(err, commonEventSubscriber) { + if(!err) { + console.info("createSubscriber"); + subscriber = commonEventSubscriber; + // Subscribe to a common event. + try { + CommonEventManager.subscribe(subscriber, SubscribeCallBack); + } catch (err) { + console.error("createSubscriber failed " + JSON.stringify(err)); + } + } else { + console.error("createSubscriber failed " + JSON.stringify(err)); + } +} + +// Create a subscriber. +try { + CommonEventManager.createSubscriber(subscribeInfo, createSubscriberCallBack); +} catch (err) { + console.error('createSubscriber failed, catch error' + JSON.stringify(err)); +} +``` + + + +## CommonEventManager.unsubscribe + +unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback\): void + +Unsubscribes from common events. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ----------------------------------------------- | ---- | ------------------------ | +| subscriber | [CommonEventSubscriber](#commoneventsubscriber) | Yes | Subscriber object. | +| callback | AsyncCallback\ | No | Callback used to return the result.| + +**Example** + +```ts +var subscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription. +// Subscriber information. +var subscribeInfo = { + events: ["event"] +}; +// Callback for common event subscription. +function subscribeCallBack(err, data) { + if (err) { + console.info("subscribe failed " + JSON.stringify(err)); + } else { + console.info("subscribe"); + } +} +// Callback for subscriber creation. +function createSubscriberCallBack(err, commonEventSubscriber) { + if (err) { + console.info("createSubscriber failed " + JSON.stringify(err)); + } else { + console.info("createSubscriber"); + subscriber = commonEventSubscriber; + // Subscribe to a common event. + try { + CommonEventManager.subscribe(subscriber, subscribeCallBack); + } catch(err) { + console.info("subscribe failed " + JSON.stringify(err)); + } + } +} +// Callback for common event unsubscription. +function unsubscribeCallBack(err) { + if (err) { + console.info("unsubscribe failed " + JSON.stringify(err)); + } else { + console.info("unsubscribe"); + } +} +// Create a subscriber. +try { + CommonEventManager.createSubscriber(subscribeInfo, createSubscriberCallBack); +} catch (err) { + console.info("createSubscriber failed " + JSON.stringify(err)); +} + +// Unsubscribe from the common event. +try { + CommonEventManager.unsubscribe(subscriber, unsubscribeCallBack); +} catch (err) { + console.info("unsubscribe failed " + JSON.stringify(err)); +} +``` + +## CommonEventSubscriber + +### getCode + +getCode(callback: AsyncCallback\): void + +Obtains the result code of this common event. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | ------------------ | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +// Callback for result code obtaining of an ordered common event. +function getCodeCallback(err, Code) { + if (err.code) { + console.error("getCode failed " + JSON.stringify(err)); + } else { + console.info("getCode " + JSON.stringify(Code)); + } +} +subscriber.getCode(getCodeCallback); +``` + +### getCode + +getCode(): Promise\ + +Obtains the result code of this common event. This API uses a promise to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Return value** + +| Type | Description | +| ---------------- | -------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +subscriber.getCode().then((Code) => { + console.info("getCode " + JSON.stringify(Code)); +}).catch((err) => { + console.error("getCode failed " + JSON.stringify(err)); +}); +``` + +### setCode + +setCode(code: number, callback: AsyncCallback\): void + +Sets the result code for this common event. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ---------------------- | +| code | number | Yes | Result code of the common event. | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +// Callback for result code setting of an ordered common event. +function setCodeCallback(err) { + if (err.code) { + console.error("setCode failed " + JSON.stringify(err)); + } else { + console.info("setCode"); + } +} +subscriber.setCode(1, setCodeCallback); +``` + +### setCode + +setCode(code: number): Promise\ + +Sets the result code for this common event. This API uses a promise to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------ | +| code | number | Yes | Result code of the common event.| + +**Return value** + +| Type | Description | +| ---------------- | -------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +subscriber.setCode(1).then(() => { + console.info("setCode"); +}).catch((err) => { + console.error("setCode failed " + JSON.stringify(err)); +}); +``` + +### getData + +getData(callback: AsyncCallback\): void + +Obtains the result data of this common event. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | -------------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result data.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +// Callback for result data obtaining of an ordered common event. +function getDataCallback(err, Data) { + if (err.code) { + console.error("getData failed " + JSON.stringify(err)); + } else { + console.info("getData " + JSON.stringify(Data)); + } +} +subscriber.getData(getDataCallback); +``` + +### getData + +getData(): Promise\ + +Obtains the result data of this common event. This API uses a promise to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Return value** + +| Type | Description | +| ---------------- | ------------------ | +| Promise\ | Promise used to return the result data.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +subscriber.getData().then((Data) => { + console.info("getData " + JSON.stringify(Data)); +}).catch((err) => { + console.error("getData failed " + JSON.stringify(err)); +}); +``` + +### setData + +setData(data: string, callback: AsyncCallback\): void + +Sets the result data for this common event. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | -------------------- | +| data | string | Yes | Result data of the common event. | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +// Callback for result data setting of an ordered common event +function setDataCallback(err) { + if (err.code) { + console.error("setData failed " + JSON.stringify(err)); + } else { + console.info("setData"); + } +} +subscriber.setData("publish_data_changed", setDataCallback); +``` + +### setData + +setData(data: string): Promise\ + +Sets the result data for this common event. This API uses a promise to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------- | +| data | string | Yes | Result data of the common event.| + +**Return value** + +| Type | Description | +| ---------------- | -------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +subscriber.setData("publish_data_changed").then(() => { + console.info("setData"); +}).catch((err) => { + console.error("setData failed " + JSON.stringify(err)); +}); +``` + +### setCodeAndData + +setCodeAndData(code: number, data: string, callback:AsyncCallback\): void + +Sets the result code and result data for this common event. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ---------------------- | +| code | number | Yes | Result code of the common event. | +| data | string | Yes | Result data of the common event. | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +// Callback for result code and result data setting of an ordered common event. +function setCodeDataCallback(err) { + if (err.code) { + console.error("setCodeAndData failed " + JSON.stringify(err)); + } else { + console.info("setCodeDataCallback"); + } +} +subscriber.setCodeAndData(1, "publish_data_changed", setCodeDataCallback); +``` + +### setCodeAndData + +setCodeAndData(code: number, data: string): Promise\ + +Sets the result code and result data for this common event. This API uses a promise to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------- | +| code | number | Yes | Result code of the common event.| +| data | string | Yes | Result data of the common event.| + +**Return value** + +| Type | Description | +| ---------------- | -------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +subscriber.setCodeAndData(1, "publish_data_changed").then(() => { + console.info("setCodeAndData"); +}).catch((err) => { + console.info("setCodeAndData failed " + JSON.stringify(err)); +}); +``` + +### isOrderedCommonEvent + +isOrderedCommonEvent(callback: AsyncCallback\): void + +Checks whether this common event is an ordered one. This API uses an asynchronous callback to return the result. + + + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | ---------------------------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result. The value **true** means that the common event is an ordered one; and **false** means the opposite.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +// Callback for checking whether the current common event is an ordered one. +function isOrderedCallback(err, isOrdered) { + if (err.code) { + console.error("isOrderedCommonEvent failed " + JSON.stringify(err)); + } else { + console.info("isOrdered " + JSON.stringify(isOrdered)); + } +} +subscriber.isOrderedCommonEvent(isOrderedCallback); +``` + +### isOrderedCommonEvent + +isOrderedCommonEvent(): Promise\ + +Checks whether this common event is an ordered one. This API uses a promise to return the result. + + + +**System capability**: SystemCapability.Notification.CommonEvent + +**Return value** + +| Type | Description | +| ----------------- | -------------------------------- | +| Promise\ | Promise used to return the result. The value **true** means that the common event is an ordered one; and **false** means the opposite.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +subscriber.isOrderedCommonEvent().then((isOrdered) => { + console.info("isOrdered " + JSON.stringify(isOrdered)); +}).catch((err) => { + console.error("isOrdered failed " + JSON.stringify(err)); +}); +``` + +### isStickyCommonEvent + +isStickyCommonEvent(callback: AsyncCallback\): void + +Checks whether this common event is a sticky one. This API uses an asynchronous callback to return the result. + + + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | ---------------------------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result. The value **true** means that the common event is a sticky one; and **false** means the opposite.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +// Callback for checking whether the current common event is a sticky one. +function isStickyCallback(err, isSticky) { + if (err.code) { + console.error("isStickyCommonEvent failed " + JSON.stringify(err)); + } else { + console.info("isSticky " + JSON.stringify(isSticky)); + } +} +subscriber.isStickyCommonEvent(isStickyCallback); +``` + +### isStickyCommonEvent + +isStickyCommonEvent(): Promise\ + +Checks whether this common event is a sticky one. This API uses a promise to return the result. + + + +**System capability**: SystemCapability.Notification.CommonEvent + +**Return value** + +| Type | Description | +| ----------------- | -------------------------------- | +| Promise\ | Promise used to return the result. The value **true** means that the common event is a sticky one; and **false** means the opposite.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +subscriber.isStickyCommonEvent().then((isSticky) => { + console.info("isSticky " + JSON.stringify(isSticky)); +}).catch((err) => { + console.error("isSticky failed " + JSON.stringify(err)); +}); +``` + +### abortCommonEvent + +abortCommonEvent(callback: AsyncCallback\): void + +Aborts this common event. After the abort, the common event is not sent to the next subscriber. This API takes effect only for ordered common events. It uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | -------------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +// Callback for common event aborting. +function abortCallback(err) { + if (err.code) { + console.error("abortCommonEvent failed " + JSON.stringify(err)); + } else { + console.info("abortCommonEvent"); + } +} +subscriber.abortCommonEvent(abortCallback); +``` + +### abortCommonEvent + +abortCommonEvent(): Promise\ + +Aborts this common event. After the abort, the common event is not sent to the next subscriber. This API takes effect only for ordered common events. It uses a promise to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Return value** + +| Type | Description | +| ---------------- | -------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +subscriber.abortCommonEvent().then(() => { + console.info("abortCommonEvent"); +}).catch((err) => { + console.error("abortCommonEvent failed " + JSON.stringify(err)); +}); +``` + +### clearAbortCommonEvent + +clearAbortCommonEvent(callback: AsyncCallback\): void + +Clears the aborted state of this common event. This API takes effect only for ordered common events. It uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | -------------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +// Callback for clearing the aborted state of the current common event. +function clearAbortCallback(err) { + if (err.code) { + console.error("clearAbortCommonEvent failed " + JSON.stringify(err)); + } else { + console.info("clearAbortCommonEvent"); + } +} +subscriber.clearAbortCommonEvent(clearAbortCallback); +``` + +### clearAbortCommonEvent + +clearAbortCommonEvent(): Promise\ + +Clears the aborted state of this common event. This API takes effect only for ordered common events. It uses a promise to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Return value** + +| Type | Description | +| ---------------- | -------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +subscriber.clearAbortCommonEvent().then(() => { + console.info("clearAbortCommonEvent"); +}).catch((err) => { + console.error("clearAbortCommonEvent failed " + JSON.stringify(err)); +}); +``` + +### getAbortCommonEvent + +getAbortCommonEvent(callback: AsyncCallback\): void + +Checks whether this common event is in the aborted state. This API takes effect only for ordered common events. It uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | ---------------------------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result. The value **true** means that the ordered common event is in the aborted state; and **false** means the opposite.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +// Callback for checking whether the current common event is in the aborted state. +function getAbortCallback(err, AbortCommonEvent) { + if (err.code) { + console.error("getAbortCommonEvent failed " + JSON.stringify(err)); + } else { + console.info("AbortCommonEvent " + AbortCommonEvent) + } +} +subscriber.getAbortCommonEvent(getAbortCallback); +``` + +### getAbortCommonEvent + +getAbortCommonEvent(): Promise\ + +Checks whether this common event is in the aborted state. This API takes effect only for ordered common events. It uses a promise to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Return value** + +| Type | Description | +| ----------------- | ---------------------------------- | +| Promise\ | Promise used to return the result. The value **true** means that the ordered common event is in the aborted state; and **false** means the opposite.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +subscriber.getAbortCommonEvent().then((AbortCommonEvent) => { + console.info("AbortCommonEvent " + JSON.stringify(AbortCommonEvent)); +}).catch((err) => { + console.error("getAbortCommonEvent failed " + JSON.stringify(err)); +}); +``` + +### getSubscribeInfo + +getSubscribeInfo(callback: AsyncCallback\): void + +Obtains the subscriber information. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ---------------------- | +| callback | AsyncCallback\<[CommonEventSubscribeInfo](#commoneventsubscribeinfo)> | Yes | Callback used to return the subscriber information.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +// Callback for subscriber information obtaining. +function getSubscribeInfoCallback(err, SubscribeInfo) { + if (err.code) { + console.error("getSubscribeInfo failed " + JSON.stringify(err)); + } else { + console.info("SubscribeInfo " + JSON.stringify(SubscribeInfo)); + } +} +subscriber.getSubscribeInfo(getSubscribeInfoCallback); +``` + +### getSubscribeInfo + +getSubscribeInfo(): Promise\ + +Obtains the subscriber information. This API uses a promise to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Return value** + +| Type | Description | +| ------------------------------------------------------------ | ---------------------- | +| Promise\<[CommonEventSubscribeInfo](#commoneventsubscribeinfo)> | Promise used to return the subscriber information.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +subscriber.getSubscribeInfo().then((SubscribeInfo) => { + console.info("SubscribeInfo " + JSON.stringify(SubscribeInfo)); +}).catch((err) => { + console.error("getSubscribeInfo failed " + JSON.stringify(err)); +}); +``` + +### finishCommonEvent9+ + +finishCommonEvent(callback: AsyncCallback\): void + +Finishes this ordered common event. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | -------------------------------- | +| callback | AsyncCallback\ | Yes | Callback returned after the ordered common event is finished.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +// Callback for ordered common event finishing. +function finishCommonEventCallback(err) { + if (err.code) { + console.error("finishCommonEvent failed " + JSON.stringify(err)); +} else { + console.info("FinishCommonEvent"); +} +} +subscriber.finishCommonEvent(finishCommonEventCallback); +``` + +### finishCommonEvent9+ + +finishCommonEvent(): Promise\ + +Finishes this ordered common event. This API uses a promise to return the result. + +**System capability**: SystemCapability.Notification.CommonEvent + +**Return value** + +| Type | Description | +| ---------------- | -------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```ts +var subscriber; // Subscriber object successfully created. + +subscriber.finishCommonEvent().then(() => { + console.info("FinishCommonEvent"); +}).catch((err) => { + console.error("finishCommonEvent failed " + JSON.stringify(err)); +}); +``` + +## CommonEventData + +**System capability**: SystemCapability.Notification.CommonEvent + +| Name | Type | Readable| Writable| Description | +| ---------- |-------------------- | ---- | ---- | ------------------------------------------------------- | +| event | string | Yes | No | Name of the common event that is being received. | +| bundleName | string | Yes | No | Bundle name. | +| code | number | Yes | No | Result code of the common event, which is used to transfer data of the int type. | +| data | string | Yes | No | Custom result data of the common event, which is used to transfer data of the string type.| +| parameters | {[key: string]: any} | Yes | No | Additional information about the common event. | + + +## CommonEventPublishData + +**System capability**: SystemCapability.Notification.CommonEvent + +| Name | Type | Readable| Writable| Description | +| --------------------- | -------------------- | ---- | ---- | ---------------------------- | +| bundleName | string | Yes | No | Bundle name. | +| code | number | Yes | No | Result code of the common event. | +| data | string | Yes | No | Custom result data of the common event.| +| subscriberPermissions | Array\ | Yes | No | Permissions required for subscribers to receive the common event. | +| isOrdered | boolean | Yes | No | Whether the common event is an ordered one. | +| isSticky | boolean | Yes | No | Whether the common event is a sticky one. Only system applications and system services are allowed to send sticky events.| +| parameters | {[key: string]: any} | Yes | No | Additional information about the common event. | + +## CommonEventSubscribeInfo + +**System capability**: SystemCapability.Notification.CommonEvent + +| Name | Type | Readable| Writable| Description | +| ------------------- | -------------- | ---- | ---- | ------------------------------------------------------------ | +| events | Array\ | Yes | No | Name of the common event to publish. | +| publisherPermission | string | Yes | No | Permissions required for publishers to publish the common event. | +| publisherDeviceId | string | Yes | No | Device ID. The value must be the ID of an existing device on the same network. | +| userId | number | Yes | No | User ID. The default value is the ID of the current user. If this parameter is specified, the value must be an existing user ID in the system.| +| priority | number | Yes | No | Subscriber priority. The value ranges from -100 to +1000. | diff --git a/en/application-dev/reference/apis/js-apis-router.md b/en/application-dev/reference/apis/js-apis-router.md index 75d75ddb09..11bb575b30 100644 --- a/en/application-dev/reference/apis/js-apis-router.md +++ b/en/application-dev/reference/apis/js-apis-router.md @@ -804,7 +804,7 @@ router.replace({ }); ``` - ## router.replace(deprecated) +## router.replace(deprecated) replace(options: RouterOptions, mode: RouterMode): void diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-web.md b/en/application-dev/reference/arkui-ts/ts-basic-components-web.md index ed5e7623b0..d6fba0b804 100644 --- a/en/application-dev/reference/arkui-ts/ts-basic-components-web.md +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-web.md @@ -1,12 +1,12 @@ # Web +The **** component can be used to display web pages. + > **NOTE** > > - This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. > - You can preview how this component looks on a real device. The preview is not yet available in the DevEco Studio Previewer. -The **** component can be used to display web pages. - ## Required Permissions To use online resources, the application must have the **ohos.permission.INTERNET** permission. For details about how to apply for a permission, see [Declaring Permissions](../../security/accesstoken-guidelines.md). @@ -24,10 +24,10 @@ Web(options: { src: ResourceStr, controller: WebController | WebviewController}) **Parameters** -| Name | Type | Mandatory | Description | -| ---------- | ------------------------------- | ---- | ------- | -| src | [ResourceStr](ts-types.md) | Yes | Address of a web page resource.| -| controller | [WebController](#webcontroller) or WebviewController |Yes | Controller. | +| Name | Type | Mandatory | Description | +| ---------- | ---------------------------------------- | ---- | ------- | +| src | [ResourceStr](ts-types.md) | Yes | Address of a web page resource.| +| controller | [WebController](#webcontroller) \| [WebviewController9+](../apis/js-apis-webview.md#webviewcontroller) | Yes | Controller. | **Example** @@ -88,7 +88,7 @@ Web(options: { src: ResourceStr, controller: WebController | WebviewController}) ## Attributes -The **\** component has network attributes. +Only the following universal attributes are supported: [width](ts-universal-attributes-size.md#Attributes), [height](ts-universal-attributes-size.md#attributes), [padding](ts-universal-attributes-size.md#Attributes), [margin](ts-universal-attributes-size.md#attributes), and [border](ts-universal-attributes-border.md#attributes). ### domStorageAccess @@ -98,8 +98,8 @@ Sets whether to enable the DOM Storage API. By default, this feature is disabled **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| ---------------- | ------- | ---- | ---- | ------------------------------------ | +| Name | Type | Mandatory | Default Value | Description | +| ---------------- | ------- | ---- | ----- | ------------------------------------ | | domStorageAccess | boolean | Yes | false | Whether to enable the DOM Storage API.| **Example** @@ -123,12 +123,12 @@ Sets whether to enable the DOM Storage API. By default, this feature is disabled fileAccess(fileAccess: boolean) -Sets whether to enable access to the file system in the application. Access to the files in **rawfile** specified through [$rawfile(filepath/filename)](../../quick-start/resource-categories-and-access.md) are not affected by the setting. +Sets whether to enable access to the file system in the application. This setting does not affect the access to the files specified through [$rawfile(filepath/filename)](../../quick-start/resource-categories-and-access.md). **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| ---------- | ------- | ---- | ---- | ---------------------------------------- | +| Name | Type | Mandatory | Default Value | Description | +| ---------- | ------- | ---- | ---- | ---------------------- | | fileAccess | boolean | Yes | true | Whether to enable access to the file system in the application. By default, this feature is enabled.| **Example** @@ -148,35 +148,6 @@ Sets whether to enable access to the file system in the application. Access to t } ``` -### fileFromUrlAccess9+ - -fileFromUrlAccess(fileFromUrlAccess: boolean) - -Sets whether to allow the use of JavaScript scripts on web pages for access to content in the application file system. By default, this feature is disabled. Access to the files in **rawfile** specified through [$rawfile(filepath/filename)](../../quick-start/resource-categories-and-access.md) are not affected by the setting. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ----------------- | ------- | ---- | ----- | ---------------------------------------- | -| fileFromUrlAccess | boolean | Yes | false | Whether to allow the use of JavaScript scripts on web pages for access to content in the application file system. By default, this feature is disabled.| - -**Example** - - ```ts - // xxx.ets - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - build() { - Column() { - Web({ src: 'www.example.com', controller: this.controller }) - .fileFromUrlAccess(true) - } - } - } - ``` - ### imageAccess imageAccess(imageAccess: boolean) @@ -187,7 +158,7 @@ Sets whether to enable automatic image loading. By default, this feature is enab | Name | Type | Mandatory | Default Value | Description | | ----------- | ------- | ---- | ---- | --------------- | -| imageAccess | boolean | Yes | true | Whether to enable automatic image loading. By default, this feature is enabled.| +| imageAccess | boolean | Yes | true | Whether to enable automatic image loading.| **Example** ```ts @@ -210,16 +181,16 @@ Sets whether to enable automatic image loading. By default, this feature is enab javaScriptProxy(javaScriptProxy: { object: object, name: string, methodList: Array\, controller: WebController | WebviewController}) -Injects a JavaScript object into the window. Methods of this object can be invoked in the window. The parameters cannot be updated. +Registers a JavaScript object with the window. APIs of this object can then be invoked in the window. The parameters cannot be updated. **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| ---------- | --------------- | ---- | ---- | ------------------------- | -| object | object | Yes | - | Object to be registered. Methods can be declared, but attributes cannot. | -| name | string | Yes | - | Name of the object to be registered, which is the same as that invoked in the window.| -| methodList | Array\ | Yes | - | Methods of the JavaScript object to be registered at the application side. | -| controller | [WebController](#webcontroller) or WebviewController | Yes | - | Controller. | +| Name | Type | Mandatory | Default Value | Description | +| ---------- | ---------------------------------------- | ---- | ---- | ------------------------- | +| object | object | Yes | - | Object to be registered. Methods can be declared, but attributes cannot. | +| name | string | Yes | - | Name of the object to be registered, which is the same as that invoked in the window.| +| methodList | Array\ | Yes | - | Methods of the JavaScript object to be registered at the application side. | +| controller | [WebController](#webcontroller) or [WebviewController](../apis/js-apis-webview.md#webviewcontroller) | Yes | - | Controller. | **Example** @@ -325,8 +296,8 @@ Sets whether to enable loading of HTTP and HTTPS hybrid content can be loaded. B **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| --------- | --------------------------- | ---- | ---- | --------- | +| Name | Type | Mandatory | Default Value | Description | +| --------- | --------------------------- | ---- | -------------- | --------- | | mixedMode | [MixedMode](#mixedmode)| Yes | MixedMode.None | Mixed content to load.| **Example** @@ -442,8 +413,8 @@ Sets whether to enable database access. By default, this feature is disabled. **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| -------------- | ------- | ---- | ---- | ----------------- | +| Name | Type | Mandatory | Default Value | Description | +| -------------- | ------- | ---- | ----- | ----------------- | | databaseAccess | boolean | Yes | false | Whether to enable database access.| **Example** @@ -471,9 +442,9 @@ Sets whether to enable geolocation access. By default, this feature is enabled. **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| -------------- | ------- | ---- | ---- | ----------------- | -| geolocationAccess | boolean | Yes | true | Whether to enable geolocation access.| +| Name | Type | Mandatory | Default Value | Description | +| ----------------- | ------- | ---- | ---- | --------------- | +| geolocationAccess | boolean | Yes | true | Whether to enable geolocation access.| **Example** @@ -496,13 +467,13 @@ Sets whether to enable geolocation access. By default, this feature is enabled. mediaPlayGestureAccess(access: boolean) -Sets whether a manual click is required for video playback. +Sets whether video playback must be started by user gestures. This API is not applicable to videos that do not have an audio track or whose audio track is muted. **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| --------- | ------ | ---- | ---- | --------- | -| access | boolean | Yes | true | Whether a manual click is required for video playback.| +| Name | Type | Mandatory | Default Value | Description | +| ------ | ------- | ---- | ---- | ----------------- | +| access | boolean | Yes | true | Whether video playback must be started by user gestures.| **Example** @@ -530,8 +501,8 @@ Sets whether to enable the multi-window permission. **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| -------------- | ------- | ---- | ---- | ----------------- | +| Name | Type | Mandatory | Default Value | Description | +| ----------- | ------- | ---- | ----- | ------------ | | multiWindow | boolean | Yes | false | Whether to enable the multi-window permission.| **Example** @@ -559,8 +530,8 @@ Sets the cache mode. **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| --------- | --------------------------- | ---- | ---- | --------- | +| Name | Type | Mandatory | Default Value | Description | +| --------- | --------------------------- | ---- | ----------------- | --------- | | cacheMode | [CacheMode](#cachemode)| Yes | CacheMode.Default | Cache mode to set.| **Example** @@ -589,9 +560,9 @@ Sets the text zoom ratio of the page. The default value is **100**, which indica **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| ------------ | ------ | ---- | ---- | --------------- | -| textZoomRatio | number | Yes | 100 | Text zoom ratio to set.| +| Name | Type | Mandatory | Default Value | Description | +| ------------- | ------ | ---- | ---- | --------------- | +| textZoomRatio | number | Yes | 100 | Text zoom ratio to set.| **Example** @@ -619,9 +590,9 @@ Sets the scale factor of the entire page. The default value is 100%. **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| ------------ | ------ | ---- | ---- | --------------- | -| percent | number | Yes | 100 | Scale factor of the entire page.| +| Name | Type | Mandatory | Default Value | Description | +| ------- | ------ | ---- | ---- | --------------- | +| percent | number | Yes | 100 | Scale factor of the entire page.| **Example** @@ -679,9 +650,9 @@ Sets whether to enable web debugging. **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| --------- | ------ | ---- | ---- | --------- | -| webDebuggingAccess | boolean | Yes | false | Whether to enable web debugging.| +| Name | Type | Mandatory | Default Value | Description | +| ------------------ | ------- | ---- | ----- | ------------- | +| webDebuggingAccess | boolean | Yes | false | Whether to enable web debugging.| **Example** @@ -701,10 +672,6 @@ Sets whether to enable web debugging. } ``` -> **NOTE**
-> -> Only the following universal attributes are supported: [width](ts-universal-attributes-size.md#Attributes), [height](ts-universal-attributes-size.md#attributes), [padding](ts-universal-attributes-size.md#Attributes), [margin](ts-universal-attributes-size.md#attributes), and [border](ts-universal-attributes-border.md#attributes). - ## Events The universal events are not supported. @@ -721,7 +688,7 @@ Triggered when **alert()** is invoked to display an alert dialog box on the web | ------- | --------------------- | --------------- | | url | string | URL of the web page where the dialog box is displayed.| | message | string | Message displayed in the dialog box. | -| result | [JsResult](#jsresult) | The user's operation. | +| result | [JsResult](#jsresult) | User operation. | **Return value** @@ -771,7 +738,7 @@ Triggered when **alert()** is invoked to display an alert dialog box on the web onBeforeUnload(callback: (event?: { url: string; message: string; result: JsResult }) => boolean) -Triggered when the current page is about to exit after the user refreshes or closes the page. If the user refreshes the page, this callback is invoked only when the page has obtained focus. +Triggered when this page is about to exit after the user refreshes or closes the page. This callback is triggered only when the page has obtained focus. **Parameters** @@ -779,7 +746,7 @@ Triggered when the current page is about to exit after the user refreshes or clo | ------- | --------------------- | --------------- | | url | string | URL of the web page where the dialog box is displayed.| | message | string | Message displayed in the dialog box. | -| result | [JsResult](#jsresult) | The user's operation. | +| result | [JsResult](#jsresult) | User operation. | **Return value** @@ -840,7 +807,7 @@ Triggered when **confirm()** is invoked by the web page. | ------- | --------------------- | --------------- | | url | string | URL of the web page where the dialog box is displayed.| | message | string | Message displayed in the dialog box. | -| result | [JsResult](#jsresult) | The user's operation. | +| result | [JsResult](#jsresult) | User operation. | **Return value** @@ -900,7 +867,7 @@ onPrompt(callback: (event?: { url: string; message: string; value: string; resul | ------- | --------------------- | --------------- | | url | string | URL of the web page where the dialog box is displayed.| | message | string | Message displayed in the dialog box. | -| result | [JsResult](#jsresult) | The user's operation. | +| result | [JsResult](#jsresult) | User operation. | **Return value** @@ -1084,7 +1051,7 @@ Triggered when an HTTP error (the response code is greater than or equal to 400) | Name | Type | Description | | ------- | ---------------------------------------- | --------------- | | request | [WebResourceRequest](#webresourcerequest) | Encapsulation of a web page request. | -| error | [WebResourceError](#webresourceerror) | Encapsulation of a web page resource loading error.| +| response | [WebResourceResponse](#webresourceresponse) | Encapsulation of a resource response.| **Example** @@ -1262,9 +1229,9 @@ Triggered when loading of the web page is complete. This API is used by an appli **Parameters** -| Name | Type | Description | -| ----------- | ------- | --------------------------------- | -| url | string | URL to be accessed. | +| Name | Type | Description | +| ----------- | ------- | ---------------------------------------- | +| url | string | URL to be accessed. | | isRefreshed | boolean | Whether the page is reloaded. The value **true** means that the page is reloaded by invoking the [refresh](#refresh) API, and **false** means the opposite.| **Example** @@ -1287,7 +1254,7 @@ Triggered when loading of the web page is complete. This API is used by an appli } ``` -### onRenderExited +### onRenderExited9+ onRenderExited(callback: (event?: { renderExitReason: RenderExitReason }) => void) @@ -1334,8 +1301,8 @@ Triggered to process an HTML form whose input type is **file**, in response to t **Return value** -| Type | Description | -| ------- | ----------------------------------- | +| Type | Description | +| ------- | ---------------------------------------- | | boolean | The value **true** means that the pop-up window provided by the system is displayed. The value **false** means that the default web pop-up window is displayed.| **Example** @@ -1383,9 +1350,9 @@ Invoked to notify the **\** component of the URL of the loaded resource fil **Parameters** -| Name | Type | Description | -| ---- | ---------------------------------------- | --------- | -| url | string | URL of the loaded resource file.| +| Name | Type | Description | +| ---- | ------ | -------------- | +| url | string | URL of the loaded resource file.| **Example** @@ -1415,8 +1382,8 @@ Invoked when the display ratio of this page changes. **Parameters** -| Name | Type | Description | -| ---- | ---------------------------------------- | --------- | +| Name | Type | Description | +| -------- | ------ | ------------ | | oldScale | number | Display ratio of the page before the change.| | newScale | number | Display ratio of the page after the change.| @@ -1493,8 +1460,8 @@ Invoked when the **\** component is about to access a URL. This API is used **Return value** -| Type | Description | -| ---------------------------------------- | --------------------------- | +| Type | Description | +| ---------------------------------------- | ---------------------------------------- | | [WebResourceResponse](#webresourceresponse) | If response data is returned, the data is loaded based on the response data. If no response data is returned, null is returned, indicating that the data is loaded in the original mode.| **Example** @@ -1554,7 +1521,7 @@ Invoked when an HTTP authentication request is received. | Name | Type | Description | | ------- | ------------------------------------ | ---------------- | -| handler | [HttpAuthHandler](#httpauthhandler9) | The user's operation. | +| handler | [HttpAuthHandler](#httpauthhandler9) | User operation. | | host | string | Host to which HTTP authentication credentials apply.| | realm | string | Realm to which HTTP authentication credentials apply. | @@ -1621,10 +1588,10 @@ Invoked when an SSL error occurs during resource loading. **Parameters** -| Name | Type | Description | -| ------- | ------------------------------------ | ---------------- | -| handler | [SslErrorHandler](#sslerrorhandler9) | The user's operation.| -| error | [SslError](#sslerror9) | Error code.| +| Name | Type | Description | +| ------- | ------------------------------------ | -------------- | +| handler | [SslErrorHandler](#sslerrorhandler9) | User operation.| +| error | [SslError](#sslerror9) | Error code. | **Example** @@ -1668,19 +1635,19 @@ Invoked when an SSL error occurs during resource loading. ### onClientAuthenticationRequest9+ -onClientAuthenticationRequest(callback: (event: {handler : ClientAuthenticationHandler, host : string, port : number, keyTypes : Array\, issuers : Array\}) => void) +onClientAuthenticationRequest(callback: (event: {handler : ClientAuthenticationHandler, host : string, port : number, keyTypes : Array, issuers : Array}) => void) Invoked when an SSL client certificate request is received. **Parameters** -| Name | Type | Description | -| ------- | ------------------------------------ | ---------------- | -| handler | [ClientAuthenticationHandler](#clientauthenticationhandler9) | The user's operation.| -| host | string | Host name of the server that requests a certificate.| -| port | number | Port number of the server that requests a certificate.| -| keyTypes| Array\ | Acceptable asymmetric private key types.| -| issuers | Array\ | Issuer of the certificate that matches the private key.| +| Name | Type | Description | +| -------- | ---------------------------------------- | --------------- | +| handler | [ClientAuthenticationHandler](#clientauthenticationhandler9) | User operation. | +| host | string | Host name of the server that requests a certificate. | +| port | number | Port number of the server that requests a certificate. | +| keyTypes | Array | Acceptable asymmetric private key types. | +| issuers | Array | Issuer of the certificate that matches the private key.| **Example** ```ts @@ -1729,9 +1696,9 @@ Invoked when a permission request is received. **Parameters** -| Name | Type | Description | -| ------- | ------------------------------------ | ---------------- | -| request | [PermissionRequest](#permissionrequest9) | The user's operation. | +| Name | Type | Description | +| ------- | ---------------------------------------- | -------------- | +| request | [PermissionRequest](#permissionrequest9) | User operation.| **Example** @@ -1774,19 +1741,19 @@ Invoked when a permission request is received. onContextMenuShow(callback: (event?: { param: WebContextMenuParam, result: WebContextMenuResult }) => boolean) -Invoked when a context menu is displayed upon a long press on a specific element (such as an image or link). +Shows a context menu after the user long presses a specific element, such as an image or a link. **Parameters** -| Name | Type | Description | -| ------- | ------------------------------------ | ---------------- | -| param | [WebContextMenuParam](#webcontextmenuparam9) | Parameters related to the context menu.| -| result | [WebContextMenuResult](#webcontextmenuresult9) | Result of the context menu.| +| Name | Type | Description | +| ------ | ---------------------------------------- | ----------- | +| param | [WebContextMenuParam](#webcontextmenuparam9) | Parameters related to the context menu. | +| result | [WebContextMenuResult](#webcontextmenuresult9) | Result of the context menu.| **Return value** -| Type | Description | -| ------ | -------------------- | +| Type | Description | +| ------- | ------------------------ | | boolean | The value **true** means a custom menu, and **false** means the default menu.| **Example** @@ -1818,10 +1785,10 @@ Invoked when the scrollbar of the page scrolls. **Parameters** -| Name | Type | Description | -| ------- | ------------------------------------ | ---------------- | -| xOffset | number | Position of the scrollbar on the x-axis.| -| yOffset | number | Position of the scrollbar on the y-axis.| +| Name | Type | Description | +| ------- | ------ | ------------ | +| xOffset | number | Position of the scrollbar on the x-axis.| +| yOffset | number | Position of the scrollbar on the y-axis.| **Example** @@ -1851,10 +1818,10 @@ Registers a callback for receiving a request to obtain the geolocation informati **Parameters** -| Name | Type | Description | -| ----------- | ------------------------------- | ---------------- | +| Name | Type | Description | +| ----------- | ------------------------------- | -------------- | | origin | string | Index of the origin. | -| geolocation | [JsGeolocation](#jsgeolocation) | The user's operation.| +| geolocation | [JsGeolocation](#jsgeolocation) | User operation.| **Example** @@ -1896,9 +1863,9 @@ Triggered to notify the user that the request for obtaining the geolocation info **Parameters** -| Name | Type | Description | -| ----------- | ------------------------------- | ---------------- | -| callback | () => void | Callback invoked when the request for obtaining geolocation information has been canceled. | +| Name | Type | Description | +| -------- | ---------- | -------------------- | +| callback | () => void | Callback invoked when the request for obtaining geolocation information has been canceled. | **Example** @@ -1928,9 +1895,9 @@ Registers a callback for the component's entering into full screen mode. **Parameters** -| Name | Type | Description | -| ----------- | ------------------------------- | ---------------- | -| handler | [FullScreenExitHandler](#fullscreenexithandler9) | Function handle for exiting full screen mode.| +| Name | Type | Description | +| ------- | ---------------------------------------- | -------------- | +| handler | [FullScreenExitHandler](#fullscreenexithandler9) | Function handle for exiting full screen mode.| **Example** @@ -1961,9 +1928,9 @@ Registers a callback for the component's exiting full screen mode. **Parameters** -| Name | Type | Description | -| ----------- | ------------------------------- | ---------------- | -| callback | () => void | Callback invoked when the component exits full screen mode.| +| Name | Type | Description | +| -------- | ---------- | ------------- | +| callback | () => void | Callback invoked when the component exits full screen mode.| **Example** @@ -1997,12 +1964,12 @@ Registers a callback for window creation. **Parameters** -| Name | Type | Description | -| ----------- | ------------------------------- | ---------------- | -| isAlert | boolean | Whether to open the target URL in a new window. The value **true** means to open the target URL in a new window, and **false** means to open the target URL in a new tab.| -| isUserTrigger | boolean | Whether the creation is triggered by the user. The value **true** means that the creation is triggered by the user, and **false** means the opposite.| -| targetUrl | string | Target URL.| -| handler | [ControllerHandler](#controllerhandler9) | **WebController** instance for setting the new window.| +| Name | Type | Description | +| ------------- | ---------------------------------------- | -------------------------- | +| isAlert | boolean | Whether to open the target URL in a new window. The value **true** means to open the target URL in a new window, and **false** means to open the target URL in a new tab.| +| isUserTrigger | boolean | Whether the creation is triggered by the user. The value **true** means that the creation is triggered by the user, and **false** means the opposite. | +| targetUrl | string | Target URL. | +| handler | [ControllerHandler](#controllerhandler9) | **WebController** instance for setting the new window. | **Example** @@ -2011,14 +1978,14 @@ Registers a callback for window creation. @Entry @Component struct WebComponent { - controller:WebController = new WebController() + controller: web_webview.WebviewController = new web_webview.WebviewController() build() { Column() { Web({ src:'www.example.com', controller: this.controller }) .multiWindowAccess(true) .onWindowNew((event) => { console.log("onWindowNew...") - var popController: WebController = new WebController() + var popController: web_webview.WebviewController = new web_webview.WebviewController() event.handler.setWebController(popController) }) } @@ -2034,9 +2001,9 @@ Registers a callback for window closure. **Parameters** -| Name | Type | Description | -| ----------- | ------------------------------- | ---------------- | -| callback | () => void | Callback invoked when the window closes.| +| Name | Type | Description | +| -------- | ---------- | ------------ | +| callback | () => void | Callback invoked when the window closes.| **Example** @@ -2057,9 +2024,44 @@ Registers a callback for window closure. } ``` +### onSearchResultReceive9+ + +onSearchResultReceive(callback: (event?: {activeMatchOrdinal: number, numberOfMatches: number, isDoneCounting: boolean}) => void): WebAttribute + +Invoked to notify the caller of the search result on the web page. + +**Parameters** + +| Name | Type | Description | +| ------------------ | ------- | ---------------------------------------- | +| activeMatchOrdinal | number | Sequence number of the current match, which starts from 0. | +| numberOfMatches | number | Total number of matches. | +| isDoneCounting | boolean | Whether the search operation on the current page is complete. This API may be called multiple times until **isDoneCounting** is **true**.| + +**Example** + + ```ts + // xxx.ets + @Entry + @Component + struct WebComponent { + controller: WebController = new WebController() + + build() { + Column() { + Web({ src: 'www.example.com', controller: this.controller }) + .onSearchResultReceive(ret => { + console.log("on search result receive:" + "[cur]" + ret.activeMatchOrdinal + + "[total]" + ret.numberOfMatches + "[isDone]"+ ret.isDoneCounting) + }) + } + } + } + ``` + ## ConsoleMessage -Implements the **ConsoleMessage** object. For details about the sample code, see [onConsole](#onconsole). +Implements the **ConsoleMessage** object. For the sample code, see [onConsole](#onconsole). ### getLineNumber @@ -2111,7 +2113,7 @@ Obtains the path and name of the web page source file. ## JsResult -Implements the **JsResult** object, which indicates the result returned to the **\** component to indicate the user operation performed in the dialog box. For details about the sample code, see [onAlert Event](#onalert). +Implements the **JsResult** object, which indicates the result returned to the **\** component to indicate the user operation performed in the dialog box. For the sample code, see [onAlert Event](#onalert). ### handleCancel @@ -2139,7 +2141,7 @@ Notifies the **\** component of the user's confirm operation in the dialog ## FullScreenExitHandler9+ -Defines a **FullScreenExitHandler** for listening for exiting full screen mode. For the sample code, see [onFullScreenEnter](#onfullscreenenter9). +Implements a **FullScreenExitHandler** object for listening for exiting full screen mode. For the sample code, see [onFullScreenEnter](#onfullscreenenter9). ### exitFullScreen9+ @@ -2149,23 +2151,23 @@ Exits full screen mode. ## ControllerHandler9+ -Defines a **WebController** for new web components. For the sample code, see [onWindowNew](#onwindownew9). +Implements a **WebviewController** object for new **\** components. For the sample code, see [onWindowNew](#onwindownew9). ### setWebController9+ -setWebController(controller: WebController): void +setWebController(controller: WebviewController): void -Sets a **WebController** object. +Sets a **WebviewController** object. **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| ------ | ------ | ---- | ---- | ----------- | -| controller | WebController | Yes | - | **WebController** object to set.| +| Name | Type | Mandatory | Default Value | Description | +| ---------- | ------------- | ---- | ---- | ------------------------- | +| controller | [WebviewController](../apis/js-apis-webview.md#webviewcontroller) | Yes | - | **WebviewController** object of the **\** component.| ## WebResourceError -Implements the **WebResourceError** object. For details about the sample code, see [onErrorReceive](#onerrorreceive). +Implements the **WebResourceError** object. For the sample code, see [onErrorReceive](#onerrorreceive). ### getErrorCode @@ -2193,7 +2195,7 @@ Obtains error information about resource loading. ## WebResourceRequest -Implements the **WebResourceRequest** object. For details about the sample code, see [onErrorReceive](#onerrorreceive). +Implements the **WebResourceRequest** object. For the sample code, see [onErrorReceive](#onerrorreceive). ### getRequestHeader @@ -2267,7 +2269,7 @@ Describes the request/response header returned by the **\** component. ## WebResourceResponse -Implements the **WebResourceResponse** object. For details about the sample code, see [onHttpErrorReceive](#onhttperrorreceive). +Implements the **WebResourceResponse** object. For the sample code, see [onHttpErrorReceive](#onhttperrorreceive). ### getReasonMessage @@ -2349,9 +2351,9 @@ Sets the data in the resource response. **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| ---- | ------ | ---- | ---- | ----------- | -| data | string | Yes | - | Resource response data to set.| +| Name| Type | Mandatory| Default Value| Description | +| ------ | ---------------- | ---- | ------ | ------------------------------------------------------------ | +| data | string | Yes | - | Resource response data to set. When set to a number, the value indicates a file handle.| ### setResponseEncoding9+ @@ -2415,7 +2417,7 @@ Sets the status code of the resource response. ## FileSelectorResult9+ -Notifies the **\** component of the file selection result. For details about the sample code, see [onShowFileSelector](#onshowfileselector9). +Notifies the **\** component of the file selection result. For the sample code, see [onShowFileSelector](#onshowfileselector9). ### handleFileList9+ @@ -2431,7 +2433,7 @@ Instructs the **\** component to select a file. ## FileSelectorParam9+ -Implements the **FileSelectorParam** object. For details about the sample code, see [onShowFileSelector](#onshowfileselector9). +Implements the **FileSelectorParam** object. For the sample code, see [onShowFileSelector](#onshowfileselector9). ### getTitle9+ @@ -2483,7 +2485,7 @@ Checks whether multimedia capabilities are invoked. ## HttpAuthHandler9+ -Implements the **HttpAuthHandler** object. For details about the sample code, see [onHttpAuthRequest](#onhttpauthrequest9). +Implements the **HttpAuthHandler** object. For the sample code, see [onHttpAuthRequest](#onhttpauthrequest9). ### cancel9+ @@ -2524,7 +2526,7 @@ Uses the password cached on the server for authentication. ## SslErrorHandler9+ -Implements an **SslErrorHandler** object. For details about the sample code, see [onSslErrorEventReceive Event](#onsslerroreventreceive9). +Implements an **SslErrorHandler** object. For the sample code, see [onSslErrorEventReceive Event](#onsslerroreventreceive9). ### handleCancel9+ @@ -2540,7 +2542,7 @@ Continues using the SSL certificate. ## ClientAuthenticationHandler9+ -Defines a **ClientAuthenticationHandler** object returned by the **\** component. For details about the sample code, see [onClientAuthenticationRequest](#onclientauthenticationrequest9). +Implements a **ClientAuthenticationHandler** object returned by the **\** component. For the sample code, see [onClientAuthenticationRequest](#onclientauthenticationrequest9). ### confirm9+ @@ -2550,10 +2552,10 @@ Uses the specified private key and client certificate chain. **Parameters** -| Name | Type| Mandatory | Description | -| -------- | ------ | ---- | ---------- | -| priKeyFile | string | Yes | File that stores the private key, which is a directory including the file name.| -| certChainFile | string | Yes | File that stores the certificate chain, which is a directory including the file name.| +| Name | Type | Mandatory | Description | +| ------------- | ------ | ---- | ------------------ | +| priKeyFile | string | Yes | File that stores the private key, which is a directory including the file name. | +| certChainFile | string | Yes | File that stores the certificate chain, which is a directory including the file name.| ### cancel9+ @@ -2569,7 +2571,7 @@ Ignores this request. ## PermissionRequest9+ -Implements the **PermissionRequest** object. For details about the sample code, see [onPermissionRequest](#onpermissionrequest9). +Implements the **PermissionRequest** object. For the sample code, see [onPermissionRequest](#onpermissionrequest9). ### deny9+ @@ -2585,9 +2587,9 @@ Obtains the origin of this web page. **Return value** -| Type | Description | -| ------- | --------------------- | -| string | Origin of the web page that requests the permission.| +| Type | Description | +| ------ | ------------ | +| string | Origin of the web page that requests the permission.| ### getAccessibleResource9+ @@ -2597,8 +2599,8 @@ Obtains the list of accessible resources requested for the web page. For details **Return value** -| Type | Description | -| --------------- | ----------------------- | +| Type | Description | +| --------------- | ------------- | | Array\ | List of accessible resources requested by the web page.| ### grant9+ @@ -2609,13 +2611,13 @@ Grants the permission for resources requested by the web page. **Parameters** -| Name | Type | Mandatory| Default Value| Description | -| --------- | --------------- | ---- | ----- | ---------------------- | -| resources | Array\ | Yes | - | List of accessible resources requested by the web page.| +| Name | Type | Mandatory | Default Value | Description | +| --------- | --------------- | ---- | ---- | ------------- | +| resources | Array\ | Yes | - | List of resources that can be requested by the web page with the permission to grant.| ## WebContextMenuParam9+ -Provides the information about the context menu that is displayed when a page element is long pressed. For details about the sample code, see [onContextMenuShow](#oncontextmenushow9). +Implements a context menu, which is displayed after the user long presses a specific element, such as an image or a link. For the sample code, see [onContextMenuShow](#oncontextmenushow9). ### x9+ @@ -2625,8 +2627,8 @@ Obtains the X coordinate of the context menu. **Return value** -| Type | Description | -| --------------- | ----------------------- | +| Type | Description | +| ------ | ------------------ | | number | If the display is normal, a non-negative integer is returned. Otherwise, **-1** is returned.| ### y9+ @@ -2637,8 +2639,8 @@ Obtains the Y coordinate of the context menu. **Return value** -| Type | Description | -| --------------- | ----------------------- | +| Type | Description | +| ------ | ------------------ | | number | If the display is normal, a non-negative integer is returned. Otherwise, **-1** is returned.| ### getLinkUrl9+ @@ -2649,20 +2651,20 @@ Obtains the URL of the destination link. **Return value** -| Type | Description | -| --------------- | ----------------------- | +| Type | Description | +| ------ | ------------------------- | | string | If it is a link that is being long pressed, the URL that has passed the security check is returned.| -### getUnfilterendLinkUrl9+ +### getUnfilteredLinkUrl9+ -getUnfilterendLinkUrl(): string +getUnfilteredLinkUrl(): string Obtains the URL of the destination link. **Return value** -| Type | Description | -| --------------- | ----------------------- | +| Type | Description | +| ------ | --------------------- | | string | If it is a link that is being long pressed, the original URL is returned.| ### getSourceUrl9+ @@ -2673,8 +2675,8 @@ Obtain the source URL. **Return value** -| Type | Description | -| --------------- | ----------------------- | +| Type | Description | +| ------ | ------------------------ | | string | If the selected element has the **src** attribute, the URL in the **src** is returned.| ### existsImageContents9+ @@ -2685,13 +2687,13 @@ Checks whether image content exists. **Return value** -| Type | Description | -| --------------- | ----------------------- | +| Type | Description | +| ------- | ------------------------- | | boolean | The value **true** means that there is image content in the element being long pressed, and **false** means the opposite.| ## WebContextMenuResult9+ -Defines the response event executed when a context menu is displayed. For details about the sample code, see [onContextMenuShow](#oncontextmenushow9). +Implements a **WebContextMenuResult** object. For the sample code, see [onContextMenuShow](#oncontextmenushow9). ### closeContextMenu9+ @@ -2707,7 +2709,7 @@ Copies the image specified in **WebContextMenuParam**. ## JsGeolocation -Implements the **PermissionRequest** object. For details about the sample code, see [onGeolocationShow Event](#ongeolocationshow). +Implements the **PermissionRequest** object. For the sample code, see [onGeolocationShow Event](#ongeolocationshow). ### invoke @@ -2717,15 +2719,17 @@ Sets the geolocation permission status of a web page. **Parameters** -| Name | Type| Mandatory| Default Value| Description | -| --------- | ------- | ---- | ----- | ---------------------- | -| origin | string | Yes | - | Index of the origin. | -| allow | boolean | Yes | - | Geolocation permission status.| -| retain | boolean | Yes | - | Whether the geolocation permission status can be saved to the system. The **[GeolocationPermissions](#geolocationpermissions9)** API can be used to manage the geolocation permission status saved to the system.| +| Name | Type | Mandatory | Default Value | Description | +| ------ | ------- | ---- | ---- | ---------------------------------------- | +| origin | string | Yes | - | Index of the origin. | +| allow | boolean | Yes | - | Geolocation permission status. | +| retain | boolean | Yes | - | Whether the geolocation permission status can be saved to the system. You can manage the geolocation permissions saved to the system through [GeolocationPermissions9+](../apis/js-apis-webview.md#geolocationpermissions).| ## WebController -Defines a **WebController** to control the behavior of the **\** component. A **WebController** can control only one **\** component, and the APIs in the **WebController** can be invoked only after it has been bound to the target **\** component. +Implements a **WebController** to control the behavior of the **\** component. A **WebController** can control only one **\** component, and the APIs in the **WebController** can be invoked only after it has been bound to the target **\** component. + +This API is deprecated since API version 9. You are advised to use [WebviewController9+](../apis/js-apis-webview.md#webviewcontroller). ### Creating an Object @@ -2733,12 +2737,14 @@ Defines a **WebController** to control the behavior of the **\** component. webController: WebController = new WebController() ``` -### requestFocus +### requestFocus(deprecated) requestFocus() Requests focus for this web page. +This API is deprecated since API version 9. You are advised to use [requestFocus9+](../apis/js-apis-webview.md#requestfocus). + **Example** ```ts @@ -2760,12 +2766,14 @@ Requests focus for this web page. } ``` -### accessBackward +### accessBackward(deprecated) accessBackward(): boolean Checks whether going to the previous page can be performed on the current page. +This API is deprecated since API version 9. You are advised to use [accessBackward9+](../apis/js-apis-webview.md#accessbackward). + **Return value** | Type | Description | @@ -2794,12 +2802,14 @@ Checks whether going to the previous page can be performed on the current page. } ``` -### accessForward +### accessForward(deprecated) accessForward(): boolean Checks whether going to the next page can be performed on the current page. +This API is deprecated since API version 9. You are advised to use [accessForward9+](../apis/js-apis-webview.md#accessforward). + **Return value** | Type | Description | @@ -2828,12 +2838,14 @@ Checks whether going to the next page can be performed on the current page. } ``` -### accessStep +### accessStep(deprecated) accessStep(step: number): boolean Performs a specific number of steps forward or backward from the current page. +This API is deprecated since API version 9. You are advised to use [accessStep9+](../apis/js-apis-webview.md#accessstep). + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -2869,12 +2881,14 @@ Performs a specific number of steps forward or backward from the current page. } ``` -### backward +### backward(deprecated) backward(): void Goes to the previous page based on the history stack. This API is generally used together with **accessBackward**. +This API is deprecated since API version 9. You are advised to use [backward9+](../apis/js-apis-webview.md#backward). + **Example** ```ts @@ -2896,12 +2910,14 @@ Goes to the previous page based on the history stack. This API is generally used } ``` -### forward +### forward(deprecated) forward(): void Goes to the next page based on the history stack. This API is generally used together with **accessForward**. +This API is deprecated since API version 9. You are advised to use [forward9+](../apis/js-apis-webview.md#forward). + **Example** ```ts @@ -2957,12 +2973,14 @@ Performs a specific number of steps forward or backward on the current page base } ``` -### deleteJavaScriptRegister +### deleteJavaScriptRegister(deprecated) deleteJavaScriptRegister(name: string) Deletes a specific application JavaScript object that is registered with the window through **registerJavaScriptProxy**. The deletion takes effect immediately, with no need for invoking the [refresh](#refresh) API. +This API is deprecated since API version 9. You are advised to use [deleteJavaScriptRegister9+](../apis/js-apis-webview.md#deletejavascriptregister). + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -2991,12 +3009,14 @@ Deletes a specific application JavaScript object that is registered with the win } ``` -### getHitTest +### getHitTest(deprecated) getHitTest(): HitTestType Obtains the element type of the area being clicked. +This API is deprecated since API version 9. You are advised to use [getHitTest9+](../apis/js-apis-webview.md#gethittest). + **Return value** | Type | Description | @@ -3191,7 +3211,7 @@ Obtains the default user agent of the current web page. } ``` -### loadData +### loadData(deprecated) loadData(options: { data: string, mimeType: string, encoding: string, baseUrl?: string, historyUrl?: string }) @@ -3201,6 +3221,8 @@ If **baseUrl** is set to a data URL, the encoded string will be loaded by the ** If **baseUrl** is set to an HTTP or HTTPS URL, the encoded string will be processed by the **\** component as a non-encoded string in a manner similar to **loadUrl**. +This API is deprecated since API version 9. You are advised to use [loadData9+](../apis/js-apis-webview.md#loaddata). + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -3236,7 +3258,7 @@ If **baseUrl** is set to an HTTP or HTTPS URL, the encoded string will be proces } ``` -### loadUrl +### loadUrl(deprecated) loadUrl(options: { url: string | Resource, headers?: Array\ }) @@ -3246,6 +3268,8 @@ The object injected through **loadUrl** is valid only in the current document. I The object injected through **registerJavaScriptProxy** is still valid on a new page redirected through **loadUrl**. +This API is deprecated since API version 9. You are advised to use [loadUrl9+](../apis/js-apis-webview.md#loadurl). + **Parameters** | Name | Type | Mandatory | Default Value | Description | @@ -3274,12 +3298,14 @@ The object injected through **registerJavaScriptProxy** is still valid on a new } ``` -### onActive +### onActive(deprecated) onActive(): void Invoked when the **\** component enters the active state. +This API is deprecated since API version 9. You are advised to use [onActive9+](../apis/js-apis-webview.md#onactive). + **Example** ```ts @@ -3301,12 +3327,14 @@ Invoked when the **\** component enters the active state. } ``` -### onInactive +### onInactive(deprecated) onInactive(): void Invoked when the **\** component enters the inactive state. +This API is deprecated since API version 9. You are advised to use [onInactive9+](../apis/js-apis-webview.md#oninactive). + **Example** ```ts @@ -3328,11 +3356,13 @@ Invoked when the **\** component enters the inactive state. } ``` -### zoom +### zoom(deprecated) zoom(factor: number): void Sets a zoom factor for the current web page. +This API is deprecated since API version 9. You are advised to use [zoom9+](../apis/js-apis-webview.md#zoom). + **Parameters** | Name | Type | Mandatory | Description | @@ -3364,7 +3394,7 @@ Sets a zoom factor for the current web page. ### zoomIn9+ zoomIn(): boolean -Zooms in on the current web page by 20%. +Zooms in on this web page by 20%. **Return value** @@ -3397,7 +3427,7 @@ Zooms in on the current web page by 20%. ### zoomOut9+ zoomOut(): boolean -Zooms out of the current web page by 20%. +Zooms out of this web page by 20%. **Return value** @@ -3427,12 +3457,14 @@ Zooms out of the current web page by 20%. } ``` -### refresh +### refresh(deprecated) refresh() Invoked when the **\** component refreshes the web page. +This API is deprecated since API version 9. You are advised to use [refresh9+](../apis/js-apis-webview.md#refresh). + **Example** ```ts @@ -3454,11 +3486,13 @@ Invoked when the **\** component refreshes the web page. } ``` -### registerJavaScriptProxy +### registerJavaScriptProxy(deprecated) registerJavaScriptProxy(options: { object: object, name: string, methodList: Array\ }) -Registers a JavaScript object and invokes the methods of the object in the window. You must invoke the [refresh](#refresh) API for the registration to take effect. +Registers a JavaScript object with the window. APIs of this object can then be invoked in the window. You must invoke the [refresh](#refresh) API for the registration to take effect. + +This API is deprecated since API version 9. You are advised to use [registerJavaScriptProxy9+](../apis/js-apis-webview.md#registerjavascriptproxy). **Parameters** @@ -3520,11 +3554,13 @@ Registers a JavaScript object and invokes the methods of the object in the windo ``` -### runJavaScript +### runJavaScript(deprecated) runJavaScript(options: { script: string, callback?: (result: string) => void }) -Asynchronously executes a JavaScript script. This API uses a callback to return the script execution result. **runJavaScript** can be invoked only after **loadUrl** is executed. For example, it can be executed in **onPageEnd**. +Executes a JavaScript script. This API uses an asynchronous callback to return the script execution result. **runJavaScript** can be invoked only after **loadUrl** is executed. For example, it can be invoked in **onPageEnd**. + +This API is deprecated since API version 9. You are advised to use [runJavaScript9+](../apis/js-apis-webview.md#runjavascript). **Parameters** @@ -3579,12 +3615,14 @@ Asynchronously executes a JavaScript script. This API uses a callback to return ``` -### stop +### stop(deprecated) stop() Stops page loading. +This API is deprecated since API version 9. You are advised to use [stop9+](../apis/js-apis-webview.md#stop). + **Example** ```ts @@ -3606,12 +3644,14 @@ Stops page loading. } ``` -### clearHistory +### clearHistory(deprecated) clearHistory(): void Clears the browsing history. +This API is deprecated since API version 9. You are advised to use [clearHistory9+](../apis/js-apis-webview.md#clearhistory). + **Example** ```ts @@ -3664,7 +3704,7 @@ Clears the user operation corresponding to the SSL certificate error event recor clearClientAuthenticationCache(): void -Clears the user operation corresponding to the client certificate request event recorded by the \ component. +Clears the user operation corresponding to the client certificate request event recorded by the **\** component. **Example** @@ -3729,8 +3769,8 @@ Creates web message ports. **Return value** -| Type | Description | -| ------------------------------- | ------------- | +| Type | Description | +| ---------------------------------------- | ---------- | | Array\<[WebMessagePort](#webmessageport9)\> | List of web message ports.| **Example** @@ -3763,10 +3803,10 @@ Sends a web message to an HTML5 window. **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| ---------- | --------------- | ---- | ---- | ------------------------- | -| message | [WebMessageEvent](#webmessageevent9) | Yes | - |Message to send, including the data and message port.| -| uri | string | Yes | - | URI for receiving the message.| +| Name | Type | Mandatory | Default Value | Description | +| ------- | ------------------------------------ | ---- | ---- | ----------------- | +| message | [WebMessageEvent](#webmessageevent9) | Yes | - | Message to send, including the data and message port.| +| uri | string | Yes | - | URI for receiving the message. | **Example** @@ -3870,12 +3910,12 @@ Sends a web message to an HTML5 window. getUrl(): string -Obtains the URL of the current page. +Obtains the URL of this page. **Return value** -| Type | Description | -| ------------------------------- | ------------- | +| Type | Description | +| ------ | ----------- | | string | URL of the current page.| **Example** @@ -3898,8 +3938,115 @@ Obtains the URL of the current page. } ``` +### searchAllAsync9+ + +searchAllAsync(searchString: string): void + +Searches the web page for content that matches the keyword specified by **'searchString'** and highlights the matches on the page. This API returns the result asynchronously through [onSearchResultReceive](#onsearchresultreceive9). + +**Parameters** + +| Name | Type | Mandatory | Default Value | Description | +| ------------ | ------ | ---- | ---- | ------- | +| searchString | string | Yes | - | Search keyword.| + +**Example** + + ```ts + // xxx.ets + @Entry + @Component + struct WebComponent { + controller: WebController = new WebController() + @State searchString: string = "xxx" + + build() { + Column() { + Button('searchString') + .onClick(() => { + this.controller.searchAllAsync(this.searchString) + }) + Button('clearMatches') + .onClick(() => { + this.controller.clearMatches() + }) + Button('searchNext') + .onClick(() => { + this.controller.searchNext(true) + }) + Web({ src: 'www.example.com', controller: this.controller }) + .onSearchResultReceive(ret => { + console.log("on search result receive:" + "[cur]" + ret.activeMatchOrdinal + + "[total]" + ret.numberOfMatches + "[isDone]"+ ret.isDoneCounting) + }) + } + } + } + ``` + +### clearMatches9+ + +clearMatches(): void + +Clears the matches found through [searchAllAsync](#searchallasync9). + +**Example** + + ```ts + // xxx.ets + @Entry + @Component + struct WebComponent { + controller: WebController = new WebController() + + build() { + Column() { + Button('clearMatches') + .onClick(() => { + this.controller.clearMatches() + }) + Web({ src: 'www.example.com', controller: this.controller }) + } + } + } + ``` + +### searchNext9+ + +searchNext(forward: boolean): void + +Searches for and highlights the next match. + +**Parameters** + +| Name | Type | Mandatory | Default Value | Description | +| ------- | ------- | ---- | ---- | ----------- | +| forward | boolean | Yes | - | Whether to search forward.| + + +**Example** + + ```ts + // xxx.ets + @Entry + @Component + struct WebComponent { + controller: WebController = new WebController() + + build() { + Column() { + Button('searchNext') + .onClick(() => { + this.controller.searchNext(true) + }) + Web({ src: 'www.example.com', controller: this.controller }) + } + } + } + ``` + ## HitTestValue9+ -Implements the **HitTestValue** object. For details about the sample code, see [getHitTestValue](#gethittestvalue9). +Implements the **HitTestValue** object. For the sample code, see [getHitTestValue](#gethittestvalue9). ### getType9+ getType(): HitTestType @@ -3968,21 +4115,28 @@ Sets the cookie. This API returns the result synchronously. Returns **true** if } ``` -### saveCookieSync9+ -saveCookieSync(): boolean +### getCookie9+ +getCookie(url: string): string -Saves the cookies in the memory to the drive. This API returns the result synchronously. +Obtains the cookie value corresponding to the specified URL. + +**Parameters** + +| Name | Type | Mandatory | Default Value | Description | +| ---- | ------ | ---- | ---- | ----------------- | +| url | string | Yes | - | URL of the cookie value to obtain.| **Return value** -| Type | Description | -| ------- | -------------------- | -| boolean | Operation result.| +| Type | Description | +| ------ | ----------------- | +| string | Cookie value corresponding to the specified URL.| **Example** ```ts // xxx.ets + import web_webview from '@ohos.web.webview' @Entry @Component struct WebComponent { @@ -3990,10 +4144,10 @@ Saves the cookies in the memory to the drive. This API returns the result synchr build() { Column() { - Button('saveCookieSync') + Button('getCookie') .onClick(() => { - let result = this.controller.getCookieManager().saveCookieSync() - console.log("result: " + result) + let value = web_webview.WebCookieManager.getCookie('www.example.com') + console.log("value: " + value) }) Web({ src: 'www.example.com', controller: this.controller }) } @@ -4001,809 +4155,23 @@ Saves the cookies in the memory to the drive. This API returns the result synchr } ``` -### getCookie9+ -getCookie(url: string): string +### setCookie9+ +setCookie(url: string, value: string): boolean -Obtains the cookie value corresponding to the specified URL. +Sets a cookie value for the specified URL. **Parameters** | Name | Type | Mandatory | Default Value | Description | | ----- | ------ | ---- | ---- | ----------------- | -| url | string | Yes | - | URL of the cookie value to obtain.| +| url | string | Yes | - | URL of the cookie to set.| +| value | string | Yes | - | Cookie value to set. | **Return value** -| Type | Description | -| ------- | -------------------- | -| string | Cookie value corresponding to the specified URL.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('getCookie') - .onClick(() => { - let value = webview.WebCookieManager.getCookie('www.example.com') - console.log("value: " + value) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### setCookie9+ -setCookie(url: string, value: string): boolean - -Sets a cookie value for the specified URL. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ----- | ------ | ---- | ---- | ----------------- | -| url | string | Yes | - | URL of the cookie to set.| -| value | string | Yes | - | Cookie value to set.| - -**Return value** - -| Type | Description | -| ------- | -------------------- | -| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('setCookie') - .onClick(() => { - let result = web_webview.WebCookieManager.setCookie('www.example.com', 'a=b') - console.log("result: " + result) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### saveCookieSync9+ -saveCookieSync(): boolean - -Saves the cookies in the memory to the drive. This API returns the result synchronously. - -**Return value** - -| Type | Description | -| ------- | -------------------- | -| boolean | Operation result.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('saveCookieSync') - .onClick(() => { - let result = web_webview.WebCookieManager.saveCookieSync() - console.log("result: " + result) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### saveCookieAsync9+ -saveCookieAsync(): Promise\ - -Saves cookies in the memory to the drive. This API uses a promise to return the value. - -**Return value** - -| Type | Description | -| ------- | -------------------- | -| Promise\ | Promise used to return the result.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('saveCookieAsync') - .onClick(() => { - web_webview.WebCookieManager.saveCookieAsync() - .then (function(result) { - console.log("result: " + result) - }) - .catch(function(error) { - console.error("error: " + error) - }) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### saveCookieAsync9+ -saveCookieAsync(callback: AsyncCallback\): void - -Saves cookies in the memory to the drive. This API uses an asynchronous callback to return the result. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ----- | ------ | ---- | ---- | ----------------- | -| callback | AsyncCallback\ | Yes | - | Callback used to return the operation result.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('saveCookieAsync') - .onClick(() => { - web_webview.WebCookieManager.saveCookieAsync(function(result) { - console.log("result: " + result) - }) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### isCookieAllowed9+ -isCookieAllowed(): boolean - -Checks whether the **WebCookieManager** instance has the permission to send and receive cookies. - -**Return value** - -| Type | Description | -| ------- | -------------------- | -| boolean | Whether the **WebCookieManager** instance has the permission to send and receive cookies.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('isCookieAllowed') - .onClick(() => { - let result = web_webview.WebCookieManager.isCookieAllowed() - console.log("result: " + result) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### putAcceptCookieEnabled9+ -putAcceptCookieEnabled(accept: boolean): void - -Sets whether the **WebCookieManager** instance has the permission to send and receive cookies. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ----- | ------ | ---- | ---- | ----------------- | -| accept | boolean | Yes | - | Whether the **WebCookieManager** instance has the permission to send and receive cookies.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('putAcceptCookieEnabled') - .onClick(() => { - web_webview.WebCookieManager.putAcceptCookieEnabled(false) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### isThirdPartyCookieAllowed9+ -isThirdCookieAllowed(): boolean - -Checks whether the **WebCookieManager** instance has the permission to send and receive third-party cookies. - -**Return value** - -| Type | Description | -| ------- | -------------------- | -| boolean | Whether the **WebCookieManager** instance has the permission to send and receive third-party cookies.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('isThirdPartyCookieAllowed') - .onClick(() => { - let result = web_webview.WebCookieManager.isThirdPartyCookieAllowed() - console.log("result: " + result) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### putAcceptThirdPartyCookieEnabled9+ -putAcceptThirdPartyCookieEnabled(accept: boolean): void - -Sets whether the **WebCookieManager** instance has the permission to send and receive third-party cookies. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ----- | ------ | ---- | ---- | ----------------- | -| accept | boolean | Yes | - | Whether the **WebCookieManager** instance has the permission to send and receive third-party cookies.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('putAcceptThirdPartyCookieEnabled') - .onClick(() => { - web_webview.WebCookieManager.putAcceptThirdPartyCookieEnabled(false) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### existCookie9+ -existCookie(): boolean - -Checks whether cookies exist. - -**Return value** - -| Type | Description | -| ------- | -------------------- | -| boolean | Whether cookies exist.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('existCookie') - .onClick(() => { - let result = web_webview.WebCookieManager.existCookie() - console.log("result: " + result) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### deleteEntireCookie9+ -deleteEntireCookie(): void - -Deletes all cookies. - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('deleteEntireCookie') - .onClick(() => { - web_webview.WebCookieManager.deleteEntireCookie() - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### deleteSessionCookie9+ -deleteSessionCookie(): void - -Deletes all session cookies. - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('deleteSessionCookie') - .onClick(() => { - webview.WebCookieManager.deleteSessionCookie() - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -## WebDataBase9+ -Implements the **WebDataBase** object. - -### existHttpAuthCredentials9+ - -static existHttpAuthCredentials(): boolean - -Checks whether any saved HTTP authentication credentials exist. This API is synchronous. - -**Return value** - -| Type | Description | -| ------- | ---------------------------------------- | -| boolean | Whether any saved HTTP authentication credentials exist. Returns **true** if any saved HTTP authentication credentials exist exists; returns **false** otherwise.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('existHttpAuthCredentials') - .onClick(() => { - let result = web_webview.WebDataBase.existHttpAuthCredentials() - console.log('result: ' + result) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### deleteHttpAuthCredentials9+ - -static deleteHttpAuthCredentials(): void - -Deletes all HTTP authentication credentials saved in the cache. This API returns the result synchronously. - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Button('deleteHttpAuthCredentials') - .onClick(() => { - web_webview.WebDataBase.deleteHttpAuthCredentials() - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### getHttpAuthCredentials9+ - -static getHttpAuthCredentials(host: string, realm: string): Array\ - -Retrieves HTTP authentication credentials for a given host and domain. This API is synchronous. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ----- | ------ | ---- | ---- | ---------------- | -| host | string | Yes | - | Host for which you want to obtain the HTTP authentication credentials.| -| realm | string | Yes | - | Realm for which you want to obtain the HTTP authentication credentials. | - -**Return value** - -| Type | Description | -| --------------- | ---------------------- | -| Array\ | Returns the array of the matching user names and passwords if the operation is successful; returns an empty array otherwise.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - host: string = "www.spincast.org" - realm: string = "protected example" - username_password: string[] - build() { - Column() { - Button('getHttpAuthCredentials') - .onClick(() => { - this.username_password = web_webview.WebDataBase.getHttpAuthCredentials(this.host, this.realm) - console.log('num: ' + this.username_password.length) - ForEach(this.username_password, (item) => { - console.log('username_password: ' + item) - }, item => item) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### saveHttpAuthCredentials9+ - -static saveHttpAuthCredentials(host: string, realm: string, username: string, password: string): void - -Saves HTTP authentication credentials for a given host and realm. This API returns the result synchronously. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| -------- | ------ | ---- | ---- | ---------------- | -| host | string | Yes | - | Host for which you want to obtain the HTTP authentication credentials.| -| realm | string | Yes | - | Realm to which HTTP authentication credentials apply. | -| username | string | Yes | - | User name. | -| password | string | Yes | - | Password. | - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - host: string = "www.spincast.org" - realm: string = "protected example" - build() { - Column() { - Button('saveHttpAuthCredentials') - .onClick(() => { - web_webview.WebDataBase.saveHttpAuthCredentials(this.host, this.realm, "Stromgol", "Laroche") - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -## GeolocationPermissions9+ - -Defines a **GeolocationPermissions** object. - -### allowGeolocation9+ - -static allowGeolocation(origin: string): void - -Allows the specified source to use the geolocation information. - -**Parameters** - -| Name | Type| Mandatory| Default Value| Description | -| -------- | -------- | ---- | ----- | ------------- | -| origin | string | Yes | - | Index of the origin.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - origin: string = "file:///" - build() { - Column() { - Button('allowGeolocation') - .onClick(() => { - web_webview.GeolocationPermissions.allowGeolocation(this.origin) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### deleteGeolocation9+ - -static deleteGeolocation(origin: string): void - -Clears the geolocation permission status of a specified source. - -**Parameters** - -| Name | Type| Mandatory| Default Value| Description | -| -------- | -------- | ---- | ----- | ------------- | -| origin | string | Yes | - | Index of the origin.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - origin: string = "file:///" - build() { - Column() { - Button('deleteGeolocation') - .onClick(() => { - web_webview.GeolocationPermissions.deleteGeolocation(this.origin) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### deleteAllGeolocation9+ - -static deleteAllGeolocation(): void - -Clears the geolocation permission status of all sources. - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - build() { - Column() { - Button('deleteAllGeolocation') - .onClick(() => { - web_webview.GeolocationPermissions.deleteAllGeolocation() - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### getAccessibleGeolocation9+ - -static getAccessibleGeolocation(origin: string, callback: AsyncCallback\): void - -Obtains the geolocation permission status of the specified source. This API uses an asynchronous callback to return the result. - -**Parameters** - -| Name | Type| Mandatory| Default Value| Description | -| -------- | -------- | ---- | ----- | ------------- | -| origin | string | Yes | - | Index of the origin.| -| callback | AsyncCallback\ | Yes| - | Callback used to return the geolocation permission status of the specified source. If the operation is successful, the value **true** means that the geolocation permission is granted, and **false** means the opposite. If the operation fails, the geolocation permission status of the specified source is not found.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - origin: string = "file:///" - build() { - Column() { - Button('getAccessibleGeolocationAsync') - .onClick(() => { - web_webview.GeolocationPermissions.getAccessibleGeolocation(this.origin, (error, result) => { - if (error) { - console.log('getAccessibleGeolocationAsync error: ' + JSON.stringify(error)) - return - } - console.log('getAccessibleGeolocationAsync result: ' + result) - }) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### getAccessibleGeolocation9+ - -static getAccessibleGeolocation(origin: string): Promise\ - -Obtains the geolocation permission status of the specified source. This API uses a promise to return the result. - -**Parameters** - -| Name | Type| Mandatory| Default Value| Description | -| -------- | -------- | ---- | ----- | ------------- | -| origin | string | Yes | - | Index of the origin.| - -**Return value** - -| Type | Description | -| ------------------ | ------------------------------------ | -| Promise\ | Promise used to return the geolocation permission status of the specified source. If the operation is successful, the value **true** means that the geolocation permission is granted, and **false** means the opposite. If the operation fails, the geolocation permission status of the specified source is not found.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - origin: string = "file:///" - build() { - Column() { - Button('getAccessibleGeolocationPromise') - .onClick(() => { - web_webview.GeolocationPermissions.getAccessibleGeolocation(this.origin).then(result => { - console.log('getAccessibleGeolocationPromise result: ' + result) - }).catch(error => { - console.log('getAccessibleGeolocationPromise error: ' + JSON.stringify(error)) - }) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### getStoredGeolocation9+ - -static getStoredGeolocation(callback: AsyncCallback\\>): void - -Obtains the geolocation permission status of all sources. This API uses an asynchronous callback to return the result. - -**Parameters** - -| Name | Type| Mandatory| Default Value| Description | -| -------- | -------- | ---- | ----- | ------------- | -| callback | AsyncCallback\\> | Yes| - | Callback used to return the geolocation permission status of all sources.| - -**Example** - - ```ts - // xxx.ets - import web_webview from '@ohos.web.webview' - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - build() { - Column() { - Button('getStoredGeolocationAsync') - .onClick(() => { - web_webview.GeolocationPermissions.getStoredGeolocation((error, origins) => { - if (error) { - console.log('getStoredGeolocationAsync error: ' + JSON.stringify(error)) - return - } - let origins_str: string = origins.join() - console.log('getStoredGeolocationAsync origins: ' + origins_str) - }) - }) - Web({ src: 'www.example.com', controller: this.controller }) - } - } - } - ``` - -### getStoredGeolocation9+ - -static getStoredGeolocation(): Promise\\> - -Obtains the geolocation permission status of all sources. This API uses a promise to return the result. - -**Parameters** - -| Name | Type| Mandatory| Default Value| Description | -| -------- | -------- | ---- | ----- | ------------- | -| callback | AsyncCallback\\> | Yes| - | Callback used to return the geolocation permission status of all sources.| - -**Return value** - -| Type | Description | -| -------------------------- | ------------------------------------ | -| Promise\\> | Promise used to return the geolocation permission status of all sources.| +| Type | Description | +| ------- | ------------- | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| **Example** @@ -4814,16 +4182,13 @@ Obtains the geolocation permission status of all sources. This API uses a promis @Component struct WebComponent { controller: WebController = new WebController() + build() { Column() { - Button('getStoredGeolocationPromise') + Button('setCookie') .onClick(() => { - web_webview.GeolocationPermissions.getStoredGeolocation().then(origins => { - let origins_str: string = origins.join() - console.log('getStoredGeolocationPromise origins: ' + origins_str) - }).catch(error => { - console.log('getStoredGeolocationPromise error: ' + JSON.stringify(error)) - }) + let result = web_webview.WebCookieManager.setCookie('www.example.com', 'a=b') + console.log("result: " + result) }) Web({ src: 'www.example.com', controller: this.controller }) } @@ -4831,12 +4196,16 @@ Obtains the geolocation permission status of all sources. This API uses a promis } ``` -## WebStorage9+ -Implements the **WebStorage** object, which can be used to manage the Web SQL and the HTML5 Web Storage API. All **\** components in an application share one **WebStorage**. -### deleteAllData9+ -static deleteAllData(): void +### saveCookieSync9+ +saveCookieSync(): boolean + +Saves the cookies in the memory to the drive. This API returns the result synchronously. + +**Return value** -Deletes all data in the Web SQL database. +| Type | Description | +| ------- | -------------------- | +| boolean | Operation result.| **Example** @@ -4847,29 +4216,30 @@ Deletes all data in the Web SQL database. @Component struct WebComponent { controller: WebController = new WebController() + build() { Column() { - Button('deleteAllData') + Button('saveCookieSync') .onClick(() => { - web_webview.WebStorage.deleteAllData() + let result = web_webview.WebCookieManager.saveCookieSync() + console.log("result: " + result) }) Web({ src: 'www.example.com', controller: this.controller }) - .databaseAccess(true) } } } ``` -### deleteOrigin9+ -static deleteOrigin(origin : string): void +### saveCookieAsync9+ +saveCookieAsync(): Promise\ -Deletes all data in the specified origin. +Saves the cookies in the memory to the drive. This API uses a promise to return the value. -**Parameters** +**Return value** -| Name | Type | Mandatory | Description | -| ------ | ------ | ---- | ---------- | -| origin | string | Yes | Index of the origin.| +| Type | Description | +| ----------------- | --------------------------- | +| Promise\ | Promise used to return the result.| **Example** @@ -4880,30 +4250,35 @@ Deletes all data in the specified origin. @Component struct WebComponent { controller: WebController = new WebController() - origin: string = "origin" + build() { Column() { - Button('getHttpAuthCredentials') + Button('saveCookieAsync') .onClick(() => { - web_webview.WebStorage.deleteOrigin(this.origin) + web_webview.WebCookieManager.saveCookieAsync() + .then (function(result) { + console.log("result: " + result) + }) + .catch(function(error) { + console.error("error: " + error) + }) }) Web({ src: 'www.example.com', controller: this.controller }) - .databaseAccess(true) } } } ``` -### getOrigins9+ -static getOrigins(callback: AsyncCallback\>) : void +### saveCookieAsync9+ +saveCookieAsync(callback: AsyncCallback\): void -Obtains information about all origins that are currently using the Web SQL database. This API uses an asynchronous callback to return the result. +Saves the cookies in the memory to the drive. This API uses an asynchronous callback to return the result. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------------------------- | ---- | ----------------------------------- | -| callback | AsyncCallback> | Yes | Callback used to return the information about the origins. For details, see **WebStorageOrigin**.| +| Name | Type | Mandatory | Default Value | Description | +| -------- | ----------------------- | ---- | ---- | ---------------------------- | +| callback | AsyncCallback\ | Yes | - | Callback used to return the operation result.| **Example** @@ -4914,40 +4289,31 @@ Obtains information about all origins that are currently using the Web SQL datab @Component struct WebComponent { controller: WebController = new WebController() - origin: string = "origin" + build() { Column() { - Button('getOrigins') + Button('saveCookieAsync') .onClick(() => { - web_webview.WebStorage.getOrigins((error, origins) => { - if (error) { - console.log('error: ' + error) - return - } - for (let i = 0; i < origins.length; i++) { - console.log('origin: ' + origins[i].origin) - console.log('usage: ' + origins[i].usage) - console.log('quota: ' + origins[i].quota) - } + web_webview.WebCookieManager.saveCookieAsync(function(result) { + console.log("result: " + result) }) }) Web({ src: 'www.example.com', controller: this.controller }) - .databaseAccess(true) } } } ``` -### getOrigins9+ -static getOrigins() : Promise\> +### isCookieAllowed9+ +isCookieAllowed(): boolean -Obtains information about all origins that are currently using the Web SQL database. This API uses a promise to return the result. +Checks whether the **WebCookieManager** instance has the permission to send and receive cookies. **Return value** -| Type | Description | -| ---------------------------------------- | ---------------------------------------- | -| Promise> | Promise used to return the information about the origins. For details, see **WebStorageOrigin**.| +| Type | Description | +| ------- | ------------------- | +| boolean | Whether the **WebCookieManager** instance has the permission to send and receive cookies.| **Example** @@ -4958,41 +4324,30 @@ Obtains information about all origins that are currently using the Web SQL datab @Component struct WebComponent { controller: WebController = new WebController() - origin: string = "origin" + build() { Column() { - Button('getOrigins') + Button('isCookieAllowed') .onClick(() => { - web_webview.WebStorage.getOrigins() - .then(origins => { - for (let i = 0; i < origins.length; i++) { - console.log('origin: ' + origins[i].origin) - console.log('usage: ' + origins[i].usage) - console.log('quota: ' + origins[i].quota) - } - }) - .catch(error => { - console.log('error: ' + error) - }) + let result = web_webview.WebCookieManager.isCookieAllowed() + console.log("result: " + result) }) Web({ src: 'www.example.com', controller: this.controller }) - .databaseAccess(true) } } } ``` -### getOriginQuota9+ -static getOriginQuota(origin : string, callback : AsyncCallback\) : void +### putAcceptCookieEnabled9+ +putAcceptCookieEnabled(accept: boolean): void -Obtains the storage quota of an origin in the Web SQL database, in bytes. This API uses an asynchronous callback to return the result. +Sets whether the **WebCookieManager** instance has the permission to send and receive cookies. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------- | ---- | --------- | -| origin | string | Yes | Index of the origin.| -| callback | AsyncCallback\ | Yes | Callback used to return the storage quota of the origin.| +| Name | Type | Mandatory | Default Value | Description | +| ------ | ------- | ---- | ---- | --------------------- | +| accept | boolean | Yes | - | Whether the **WebCookieManager** instance has the permission to send and receive cookies.| **Example** @@ -5003,42 +4358,29 @@ Obtains the storage quota of an origin in the Web SQL database, in bytes. This A @Component struct WebComponent { controller: WebController = new WebController() - origin: string = "origin" + build() { Column() { - Button('getOriginQuota') + Button('putAcceptCookieEnabled') .onClick(() => { - web_webview.WebStorage.getOriginQuota(this.origin, (error, quota) => { - if (error) { - console.log('error: ' + error) - return - } - console.log('quota: ' + quota) - }) + web_webview.WebCookieManager.putAcceptCookieEnabled(false) }) Web({ src: 'www.example.com', controller: this.controller }) - .databaseAccess(true) } } } ``` -### getOriginQuota9+ -static getOriginQuota(origin : string) : Promise\ - -Obtains the storage quota of an origin in the Web SQL database, in bytes. This API uses a promise to return the result. - -**Parameters** +### isThirdPartyCookieAllowed9+ +isThirdCookieAllowed(): boolean -| Name | Type | Mandatory | Description | -| ------ | ------ | ---- | ---------- | -| origin | string | Yes | Index of the origin.| +Checks whether the **WebCookieManager** instance has the permission to send and receive third-party cookies. **Return value** -| Type | Description | -| ---------------- | ----------------------- | -| Promise\ | Promise used to return the storage quota of the origin.| +| Type | Description | +| ------- | ---------------------- | +| boolean | Whether the **WebCookieManager** instance has the permission to send and receive third-party cookies.| **Example** @@ -5048,38 +4390,31 @@ Obtains the storage quota of an origin in the Web SQL database, in bytes. This A @Entry @Component struct WebComponent { - controller: WebController = new WebController(); - origin: string = "origin" + controller: WebController = new WebController() + build() { Column() { - Button('getOriginQuota') + Button('isThirdPartyCookieAllowed') .onClick(() => { - web_webview.WebStorage.getOriginQuota(this.origin) - .then(quota => { - console.log('quota: ' + quota) - }) - .catch(error => { - console.log('error: ' + error) - }) + let result = web_webview.WebCookieManager.isThirdPartyCookieAllowed() + console.log("result: " + result) }) Web({ src: 'www.example.com', controller: this.controller }) - .databaseAccess(true) } } } ``` -### getOriginUsage9+ -static getOriginUsage(origin : string, callback : AsyncCallback\) : void +### putAcceptThirdPartyCookieEnabled9+ +putAcceptThirdPartyCookieEnabled(accept: boolean): void -Obtains the storage usage of an origin in the Web SQL database, in bytes. This API uses an asynchronous callback to return the result. +Sets whether the **WebCookieManager** instance has the permission to send and receive third-party cookies. **Parameters** -| Name | Type | Mandatory | Description | -| -------- | ---------------------- | ---- | ---------- | -| origin | string | Yes | Index of the origin.| -| callback | AsyncCallback\ | Yes | Callback used to return the storage usage of the origin. | +| Name | Type | Mandatory | Default Value | Description | +| ------ | ------- | ---- | ---- | ------------------------ | +| accept | boolean | Yes | - | Whether the **WebCookieManager** instance has the permission to send and receive third-party cookies.| **Example** @@ -5089,43 +4424,30 @@ Obtains the storage usage of an origin in the Web SQL database, in bytes. This A @Entry @Component struct WebComponent { - controller: WebController = new WebController(); - origin: string = "origin" + controller: WebController = new WebController() + build() { Column() { - Button('getOriginUsage') + Button('putAcceptThirdPartyCookieEnabled') .onClick(() => { - web_webview.WebStorage.getOriginUsage(this.origin, (error, usage) => { - if (error) { - console.log('error: ' + error) - return - } - console.log('usage: ' + usage) - }) + web_webview.WebCookieManager.putAcceptThirdPartyCookieEnabled(false) }) Web({ src: 'www.example.com', controller: this.controller }) - .databaseAccess(true) } } } ``` -### getOriginUsage9+ -static getOriginUsage(origin : string) : Promise\ - -Obtains the storage usage of an origin in the Web SQL database, in bytes. This API uses a promise to return the result. - -**Parameters** +### existCookie9+ +existCookie(): boolean -| Name | Type | Mandatory | Description | -| ------ | ------ | ---- | ---------- | -| origin | string | Yes | Index of the origin.| +Checks whether cookies exist. **Return value** -| Type | Description | -| ---------------- | ---------------------- | -| Promise\ | Promise used to return the storage usage of the origin.| +| Type | Description | +| ------- | ----------- | +| boolean | Whether cookies exist.| **Example** @@ -5134,93 +4456,42 @@ Obtains the storage usage of an origin in the Web SQL database, in bytes. This A import web_webview from '@ohos.web.webview' @Entry @Component - struct WebComponent { - controller: WebController = new WebController(); - origin: string = "origin" - build() { - Column() { - Button('getOriginQuota') - .onClick(() => { - web_webview.WebStorage.getOriginUsage(this.origin) - .then(usage => { - console.log('usage: ' + usage) - }) - .catch(error => { - console.log('error: ' + error) - }) - }) - Web({ src: 'www.example.com', controller: this.controller }) - .databaseAccess(true) - } - } - } - ``` -### searchAllAsync9+ - -searchAllAsync(searchString: string): void - -Searches the web page for content that matches the keyword specified by **'searchString'** and highlights the matches on the page. This API returns the result asynchronously through [onSearchResultReceive](#onsearchresultreceive9). - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ---- | ------ | ---- | ---- | --------------------- | -| searchString | string | Yes | - | Search keyword.| - -**Example** - - ```ts - // xxx.ets - @Entry - @Component struct WebComponent { controller: WebController = new WebController() - @State searchString: string = "xxx" - + build() { Column() { - Button('searchString') - .onClick(() => { - this.controller.searchAllAsync(this.searchString) - }) - Button('clearMatches') - .onClick(() => { - this.controller.clearMatches() - }) - Button('searchNext') + Button('existCookie') .onClick(() => { - this.controller.searchNext(true) + let result = web_webview.WebCookieManager.existCookie() + console.log("result: " + result) }) Web({ src: 'www.example.com', controller: this.controller }) - .onSearchResultReceive(ret => { - console.log("on search result receive:" + "[cur]" + ret.activeMatchOrdinal + - "[total]" + ret.numberOfMatches + "[isDone]"+ ret.isDoneCounting) - }) } } } ``` -### clearMatches9+ - -clearMatches(): void +### deleteEntireCookie9+ +deleteEntireCookie(): void -Clears the matches found through [searchAllAsync](#searchallasync9). +Deletes all cookies. **Example** ```ts // xxx.ets + import web_webview from '@ohos.web.webview' @Entry @Component struct WebComponent { controller: WebController = new WebController() - + build() { Column() { - Button('clearMatches') + Button('deleteEntireCookie') .onClick(() => { - this.controller.clearMatches() + web_webview.WebCookieManager.deleteEntireCookie() }) Web({ src: 'www.example.com', controller: this.controller }) } @@ -5228,33 +4499,26 @@ Clears the matches found through [searchAllAsync](#searchallasync9). } ``` -### searchNext9+ - -searchNext(forward: boolean): void - -Searches for and highlights the next match. - -**Parameters** - -| Name | Type | Mandatory | Default Value | Description | -| ---- | ------ | ---- | ---- | --------------------- | -| forward | boolean | Yes | - | Whether to search forward.| +### deleteSessionCookie9+ +deleteSessionCookie(): void +Deletes all session cookies. **Example** ```ts // xxx.ets + import web_webview from '@ohos.web.webview' @Entry @Component struct WebComponent { controller: WebController = new WebController() - + build() { Column() { - Button('searchNext') + Button('deleteSessionCookie') .onClick(() => { - this.controller.searchNext(true) + web_webview.WebCookieManager.deleteSessionCookie() }) Web({ src: 'www.example.com', controller: this.controller }) } @@ -5262,53 +4526,6 @@ Searches for and highlights the next match. } ``` -### onSearchResultReceive9+ - -onSearchResultReceive(callback: (event?: {activeMatchOrdinal: number, numberOfMatches: number, isDoneCounting: boolean}) => void): WebAttribute - -Invoked to notify the caller of the search result on the web page. - -**Parameters** - -| Name | Type | Description | -| ------------------ | ------------- | ----------------------------------- | -| activeMatchOrdinal | number | Sequence number of the current match, which starts from 0.| -| numberOfMatches | number | Total number of matches.| -| isDoneCounting | boolean | Whether the search operation on the current page is complete. This API may be called multiple times until **isDoneCounting** is **true**.| - -**Example** - - ```ts - // xxx.ets - @Entry - @Component - struct WebComponent { - controller: WebController = new WebController() - - build() { - Column() { - Web({ src: 'www.example.com', controller: this.controller }) - .onSearchResultReceive(ret => { - console.log("on search result receive:" + "[cur]" + ret.activeMatchOrdinal + - "[total]" + ret.numberOfMatches + "[isDone]"+ ret.isDoneCounting) - }) - } - } - } - ``` - -## WebStorageOrigin9+ - -Provides usage information about the Web SQL database. - -**Parameters** - -| Name | Type | Mandatory | Description | -| ------ | ------ | ---- | ---------- | -| origin | string | Yes | Index of the origin.| -| usage | number | Yes | Storage usage of the origin. | -| quota | number | Yes | Storage quota of the origin. | - ## MessageLevel | Name | Description | @@ -5365,23 +4582,24 @@ Enumerates the reasons why the rendering process exits. | HttpAnchorImg | Image with a hyperlink, where **src** is **http**.| | Img | HTML::img tag. | | Map | Geographical address. | +| Phone | Phone number. | | Unknown | Unknown content. | ## SslError9+ Enumerates the error codes returned by **onSslErrorEventReceive** API. -| Name | Description | -| -------------- | ----------------- | -| Invalid | Minor error. | -| HostMismatch | The host name does not match. | -| DateInvalid | The certificate has an invalid date. | -| Untrusted | The certificate issuer is not trusted.| +| Name | Description | +| ------------ | ----------- | +| Invalid | Minor error. | +| HostMismatch | The host name does not match. | +| DateInvalid | The certificate has an invalid date. | +| Untrusted | The certificate issuer is not trusted.| ## ProtectedResourceType9+ -| Name | Description | Remarks | -| --------- | -------------- | -------------- | +| Name | Description | Remarks | +| --------- | ------------- | -------------------------- | | MidiSysex | MIDI SYSEX resource.| Currently, only permission events can be reported. MIDI devices are not yet supported.| ## WebAsyncController @@ -5483,7 +4701,7 @@ Stores this web page. This API uses a promise to return the result. ## WebMessagePort9+ -Defines a **WebMessagePort** instance, which can be used to send and receive messages. +Implements a **WebMessagePort** instance, which can be used to send and receive messages. ### close9+ close(): void @@ -5497,9 +4715,9 @@ Sends messages. For the complete sample code, see [postMessage](#postmessage9). **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| ----- | ------ | ---- | ---- | ----------------- | -| message | [WebMessageEvent](#webmessageevent9) | Yes | - | Message to send.| +| Name | Type | Mandatory | Default Value | Description | +| ------- | ------------------------------------ | ---- | ---- | ------- | +| message | [WebMessageEvent](#webmessageevent9) | Yes | - | Message to send.| **Example** @@ -5532,9 +4750,9 @@ Registers a callback to receive messages from an HTML5 page. For the complete sa **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| ----- | ------ | ---- | ---- | ----------------- | -| callback | function | Yes | - | Callback for receiving messages.| +| Name | Type | Mandatory | Default Value | Description | +| -------- | -------- | ---- | ---- | ---------- | +| callback | function | Yes | - | Callback for receiving messages.| **Example** @@ -5572,8 +4790,8 @@ Obtains the messages stored in this object. **Return value** -| Type | Description | -| ------------------------------- | ------------- | +| Type | Description | +| ------ | -------------- | | string | Message stored in the object of this type.| **Example** @@ -5604,9 +4822,9 @@ Sets the message in this object. For the complete sample code, see [postMessage] **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| ----- | ------ | ---- | ---- | ----------------- | -| data | string | Yes | - | Message to send.| +| Name | Type | Mandatory | Default Value | Description | +| ---- | ------ | ---- | ---- | ------- | +| data | string | Yes | - | Message to send.| **Example** @@ -5638,8 +4856,8 @@ Obtains the message port stored in this object. **Return value** -| Type | Description | -| ------------------------------- | ------------- | +| Type | Description | +| ---------------------------------------- | ---------------- | | Array\<[WebMessagePort](#webmessageport9)\> | Message port stored in the object of this type.| **Example** @@ -5672,9 +4890,9 @@ Sets the message port in this object. For the complete sample code, see [postMes **Parameters** -| Name | Type | Mandatory | Default Value | Description | -| ----- | ------ | ---- | ---- | ----------------- | -| ports | Array\<[WebMessagePort](#webmessageport9)\> | Yes | - | Message port.| +| Name | Type | Mandatory | Default Value | Description | +| ----- | ---------------------------------------- | ---- | ---- | --------- | +| ports | Array\<[WebMessagePort](#webmessageport9)\> | Yes | - | Message port.| **Example** diff --git a/en/application-dev/reference/arkui-ts/ts-components-canvas-lottie.md b/en/application-dev/reference/arkui-ts/ts-components-canvas-lottie.md index aacc4d7e66..6bb371dfa5 100644 --- a/en/application-dev/reference/arkui-ts/ts-components-canvas-lottie.md +++ b/en/application-dev/reference/arkui-ts/ts-components-canvas-lottie.md @@ -27,34 +27,35 @@ loadAnimation( path: string, container: object, render: string, loop: boolean, autoplay: boolean, name: string ): AnimationItem -Loads an animation. Before calling this method, declare the **Animator('\__lottie\_ets')** object and check that the canvas layout is complete. This method can be used together with a lifecycle callback of the **Canvas** component, for example, **onAppear()** and **onPageShow()**. +Loads an animation. Before calling this API, declare the **Animator('__lottie_ets')** object and make sure the canvas layout is complete. This API can be used together with the lifecycle callback **onReady()** of the **Canvas** component. **Parameters** -| Name | Type | Mandatory | Description | -| -------------- | --------------------------- | ---- | ---------------------------------------- | -| path | string | Yes | Path of the animation resource file in the HAP file. The resource file must be in JSON format. Example: **path: "common/lottie/data.json"**| -| container | object | Yes | Canvas drawing context. A **CanvasRenderingContext2D** object must be declared in advance.| -| render | string | Yes | Rendering type. The value can only be **"canvas"**. | -| loop | boolean \| number | No | If the value is of the Boolean type, this parameter indicates whether to repeat the animation cyclically after the animation ends; the default value is **true**. If the value is of the number type and is greater than or equal to 1, this parameter indicates the number of times the animation plays.| -| autoplay | boolean | No | Whether to automatically play the animation. The default value is **true**. | -| name | string | No | Custom animation name. In later versions, the name can be used to reference and control the animation. The default value is null. | -| initialSegment | [number, number] | No | Start frame and end frame of the animation, respectively. | +| Name | Type | Mandatory| Description | +| -------------- | --------------------------- | ---- | ------------------------------------------------------------ | +| path | string | Yes | Path of the animation resource file in the HAP file. The resource file must be in JSON format. Example: **path: "common/lottie/data.json"**| +| container | object | Yes | Canvas drawing context. A **CanvasRenderingContext2D** object must be declared in advance.| +| render | string | Yes | Rendering type. The value can only be **"canvas"**. | +| loop | boolean \| number | No | If the value is of the Boolean type, this parameter indicates whether to repeat the animation cyclically after the animation ends; the default value is **true**. If the value is of the number type and is greater than or equal to 1, this parameter indicates the number of times the animation plays.| +| autoplay | boolean | No | Whether to automatically play the animation.
Default value: **true** | +| name | string | No | Custom animation name. In later versions, the name can be used to reference and control the animation.
Default value: null | +| initialSegment | [number, number] | No | Start frame and end frame of the animation, respectively. | ## lottie.destroy destroy(name: string): void -Destroys the animation. This method must be called when a page exits. This method can be used together with a lifecycle callback of the **Canvas** component, for example, **onDisappear()** and **onPageHide()**. +Destroys the animation. This API must be called when a page exits. This API can be used together with a lifecycle callback of the **Canvas** component, for example, **onDisappear()** and **onPageHide()**. **Parameters** | Name | Type | Mandatory | Description | | ---- | ------ | ---- | ---------------------------------------- | -| name | string | Yes | Name of the animation to destroy, which is the same as the **name** in the **loadAnimation** interface. By default, all animations are destroyed.| +| name | string | Yes | Name of the animation to destroy, which is the same as the **name** in the **loadAnimation** API. By default, all animations are destroyed. | **Example** + ```ts // xxx.ets import lottie from '@ohos/lottieETS' @@ -78,7 +79,7 @@ Destroys the animation. This method must be called when a page exits. This metho .width('30%') .height('20%') .backgroundColor('#0D9FFB') - .onAppear(() => { + .onReady(() => { console.log('canvas onAppear'); this.animateItem = lottie.loadAnimation({ container: this.controller, @@ -133,7 +134,7 @@ Plays a specified animation. | Name | Type | Mandatory | Description | | ---- | ------ | ---- | ---------------------------------------- | -| name | string | Yes | Name of the animation to play, which is the same as the **name** in the **loadAnimation** interface. By default, all animations are played.| +| name | string | Yes | Name of the animation to play, which is the same as the **name** in the **loadAnimation** API. By default, all animations are played. | **Example** @@ -152,7 +153,7 @@ Pauses a specified animation. The next time **lottie.play()** is called, the ani | Name | Type | Mandatory | Description | | ---- | ------ | ---- | ---------------------------------------- | -| name | string | Yes | Name of the animation to pause, which is the same as the **name** in the **loadAnimation** interface. By default, all animations are paused.| +| name | string | Yes | Name of the animation to pause, which is the same as the **name** in the **loadAnimation** API. By default, all animations are paused. | **Example** @@ -165,13 +166,13 @@ Pauses a specified animation. The next time **lottie.play()** is called, the ani togglePause(name: string): void -Pauses or plays a specified animation. This method is equivalent to the switching between **lottie.play()** and **lottie.pause()**. +Pauses or plays a specified animation. This API is equivalent to the switching between **lottie.play()** and **lottie.pause()**. **Parameters** | Name | Type | Mandatory | Description | | ---- | ------ | ---- | ---------------------------------------- | -| name | string | Yes | Name of the target animation, which is the same as the **name** in the **loadAnimation** interface. By default, all animations are paused.| +| name | string | Yes | Name of the target animation, which is the same as the **name** in the **loadAnimation** API. By default, all animations are paused or played. | **Example** @@ -190,7 +191,7 @@ Stops the specified animation. The next time **lottie.play()** is called, the an | Name | Type | Mandatory | Description | | ---- | ------ | ---- | ---------------------------------------- | -| name | string | Yes | Name of the target animation, which is the same as the **name** in the **loadAnimation** interface. By default, all animations are paused.| +| name | string | Yes | Name of the target animation, which is the same as the **name** in the **loadAnimation** API. By default, all animations are stopped. | **Example** @@ -209,8 +210,8 @@ Sets the playback speed of the specified animation. | Name | Type | Mandatory | Description | | ----- | ------ | ---- | ---------------------------------------- | -| speed | number | Yes | Playback speed. The value is a floating-point number. If the value is greater than 0, the animation plays in forward direction. If the value is less than 0, the animation plays in reversed direction. If the value is 0, the animation is paused. If the value is 1.0 or -1.0, the animation plays at the normal speed.| -| name | string | Yes | Name of the target animation, which is the same as the **name** in the **loadAnimation** interface. By default, all animations are stopped.| +| speed | number | Yes | Playback speed. The value is a floating-point number. If the value is greater than 0, the animation plays in forward direction. If the value is less than 0, the animation plays in reversed direction. If the value is **0**, the animation is paused. If the value is **1.0** or **-1.0**, the animation plays at the normal speed. | +| name | string | Yes | Name of the target animation, which is the same as the **name** in the **loadAnimation** API. By default, all animations are set. | **Example** @@ -230,7 +231,7 @@ Sets the direction in which the specified animation plays. | Name | Type | Mandatory | Description | | --------- | ------------------ | ---- | ---------------------------------------- | | direction | AnimationDirection | Yes | Direction in which the animation plays. **1**: forwards; **-1**: backwards. When set to play backwards, the animation plays from the current playback progress to the first frame. When this setting is combined with **loop** being set to **true**, the animation plays backwards continuously. When the value of **speed** is less than 0, the animation also plays backwards.
AnimationDirection: 1 \| -1 | -| name | string | Yes | Name of the target animation, which is the same as the **name** in the **loadAnimation** interface. By default, all animations are set.| +| name | string | Yes | Name of the target animation, which is the same as the **name** in the **loadAnimation** API. By default, all animations are set. | **Example** @@ -241,7 +242,7 @@ Sets the direction in which the specified animation plays. ## AnimationItem -Defines an **AnimationItem** object, which is returned by the **loadAnimation** interface and has attributes and interfaces. The attributes are described as follows: +Defines an **AnimationItem** object, which is returned by the **loadAnimation** API and has attributes and APIs. The attributes are described as follows: | Name | Type | Description | | ----------------- | ---------------------------------------- | ---------------------------------------- | @@ -253,18 +254,18 @@ Defines an **AnimationItem** object, which is returned by the **loadAnimation** | totalFrames | number | Total number of frames in the animation segment that is being played. | | frameRate | number | Frame rate (frame/s). | | frameMult | number | Frame rate (frame/ms). | -| playSpeed | number | Playback speed. The value is a floating-point number. If the value is greater than 0, the animation plays forward. If the value is less than 0, the animation plays backward. If the value is 0, the animation is paused.|If the value is **1.0** or **-1.0**, the animation plays at the normal speed.| -| playDirection | number | Playback direction. The options are **1** (forward) and **-1** (backward). | +| playSpeed | number | Playback speed. The value is a floating-point number. If the value is greater than 0, the animation plays forward. If the value is less than 0, the animation plays backward. If the value is **0**, the animation is paused. If the value is **1.0** or **-1.0**, the animation plays at the normal speed. | +| playDirection | number | Playback direction.
**1**: forward.
**-1**: backward. | | playCount | number | Number of times the animation plays. | | isPaused | boolean | Whether the current animation is paused. The value **true** means that the animation is paused. | -| autoplay | boolean | Whether to automatically play the animation upon completion of the loading. The value **false** means that the **play()** interface needs to be called to start playing.| -| loop | boolean \| number | If the value is of the Boolean type, this parameter indicates whether to repeat the animation cyclically after the animation ends. If the value is of the number type and is greater than or equal to 1, this parameter indicates the number of times the animation plays. | +| autoplay | boolean | Whether to automatically play the animation upon completion of the loading. The value **false** means that the **play()** API needs to be called to start playing. | +| loop | boolean \| number | If the value is of the Boolean type, this parameter indicates whether to repeat the animation cyclically after the animation ends. If the value is of the number type and is greater than or equal to 1, this parameter indicates the number of times the animation plays. | | renderer | any | Animation rendering object, which depends on the rendering type. | | animationID | string | Animation ID. | | timeCompleted | number | Number of frames that are played for an animation sequence. The value is affected by the setting of **AnimationSegment** and is the same as the value of **totalFrames**.| | segmentPos | number | ID of the current animation segment. The value is a positive integer greater than or equal to 0. | | isSubframeEnabled | boolean | Whether the precision of **currentFrame** is a floating point number. | -| segments | AnimationSegment \| AnimationSegment[] | Current segment of the animation. | +| segments | AnimationSegment \| AnimationSegment[] | Current segment of the animation. | ## AnimationItem.play @@ -309,7 +310,7 @@ Destroys an animation. pause(name?: string): void -Pauses an animation. When the **play** interface is called next time, the animation is played from the current frame. +Pauses an animation. When the **play** API is called next time, the animation is played from the current frame. **Parameters** @@ -328,7 +329,7 @@ Pauses an animation. When the **play** interface is called next time, the animat togglePause(name?: string): void -Pauses or plays an animation. This method is equivalent to the switching between **play** and **pause**. +Pauses or plays an animation. This API is equivalent to the switching between **play** and **pause**. **Parameters** @@ -347,7 +348,7 @@ Pauses or plays an animation. This method is equivalent to the switching between stop(name?: string): void -Stops an animation. When the **play** interface is called next time, the animation is played from the first frame. +Stops an animation. When the **play** API is called next time, the animation is played from the first frame. **Parameters** @@ -372,7 +373,7 @@ Sets the playback speed of an animation. | Name | Type | Mandatory | Description | | ----- | ------ | ---- | ---------------------------------------- | -| speed | number | Yes | Playback speed. The value is a floating-point number. If the value is greater than 0, the animation plays forward. If the value is less than 0, the animation plays backward. If the value is 0, the animation is paused.|If the value is **1.0** or **-1.0**, the animation plays at the normal speed.| +| speed | number | Yes | Playback speed. The value is a floating-point number. If the value is greater than 0, the animation plays forward. If the value is less than 0, the animation plays backward. If the value is **0**, the animation is paused. If the value is **1.0** or **-1.0**, the animation plays at the normal speed. | **Example** @@ -411,8 +412,8 @@ Sets the animation to stop at the specified frame or time. | Name | Type | Mandatory | Description | | ------- | ------- | ---- | ---------------------------------------- | | value | number | Yes | Frame ID (greater than or equal to 0) or time progress (ms) at which the animation will stop. | -| isFrame | boolean | No | Whether to set the animation to stop at the specified frame. The value **true** means to set the animation to stop at the specified frame, and **false** means to set the animation to stop at the specified time progress. The default value is **false**.| -| name | string | No | Name of the target animation. By default, the value is null. | +| isFrame | boolean | No | Whether to set the animation to stop at the specified frame. The value **true** means to set the animation to stop at the specified frame, and **false** means to set the animation to stop at the specified time progress.
Default value: **false** | +| name | string | No | Name of the target animation. By default, the value is null. | **Example** @@ -435,8 +436,8 @@ Sets the animation to start from the specified frame or time progress. | Name | Type | Mandatory | Description | | ------- | ------- | ---- | ---------------------------------------- | | value | number | Yes | Frame ID (greater than or equal to 0) or time progress (ms) at which the animation will start. | -| isFrame | boolean | Yes | Whether to set the animation to start from the specified frame. The value **true** means to set the animation to start from the specified frame, and **false** means to set the animation to start from the specified time progress. The default value is **false**.| -| name | string | No | Name of the target animation. By default, the value is null. | +| isFrame | boolean | Yes | Whether to set the animation to start from the specified frame. The value **true** means to set the animation to start from the specified frame, and **false** means to set the animation to start from the specified time progress.
Default value: **false** | +| name | string | No | Name of the target animation.
Default value: null | **Example** @@ -459,7 +460,7 @@ Sets the animation to play only the specified segment. | Name | Type | Mandatory | Description | | --------- | ---------------------------------------- | ---- | ---------------------------------------- | | segments | AnimationSegment = [number, number] \| AnimationSegment[] | Yes | Segment or segment list.
If all segments in the segment list are played, only the last segment is played in the next cycle.| -| forceFlag | boolean | Yes | Whether the settings take effect immediately. The value **true** means the settings take effect immediately, and **false** means the settings take effect until the current cycle of playback is completed. | +| forceFlag | boolean | Yes | Whether the settings take effect immediately. The value **true** means the settings take effect immediately, and **false** means the settings take effect until the current cycle of playback is completed. | **Example** @@ -475,7 +476,7 @@ Sets the animation to play only the specified segment. resetSegments(forceFlag: boolean): void -Resets the settings configured by the **playSegments** method to play all the frames. +Resets the settings configured by the **playSegments** API to play all the frames. **Parameters** @@ -526,13 +527,13 @@ Sets the precision of the **currentFrame** attribute to display floating-point n getDuration(inFrames?: boolean): void -Obtains the duration (irrelevant to the playback speed) or number of frames for playing an animation sequence. The settings are related to the input parameter **initialSegment** of the **Lottie.loadAnimation** interface. +Obtains the duration (irrelevant to the playback speed) or number of frames for playing an animation sequence. The settings are related to the input parameter **initialSegment** of the **Lottie.loadAnimation** API. **Parameters** | Name | Type | Mandatory | Description | | -------- | ------- | ---- | ---------------------------------------- | -| inFrames | boolean | No | Whether to obtain the duration or number of frames.
**true**: number of frames.
**false**: duration, in ms.
Default value: **false**| +| inFrames | boolean | No | Whether to obtain the duration or number of frames.
**true**: number of frames.
**false**: duration, in ms.
Default value: **false** | **Example** @@ -545,7 +546,7 @@ Obtains the duration (irrelevant to the playback speed) or number of frames for addEventListener<T = any>(name: AnimationEventName, callback: AnimationEventCallback<T>): () => void -Adds an event listener. After the event is complete, the specified callback function is triggered. This method returns the function object that can delete the event listener. +Adds an event listener. After the event is complete, the specified callback is triggered. This API returns the function object that can delete the event listener. **Parameters** @@ -578,7 +579,7 @@ Removes an event listener. | Name | Type | Mandatory | Description | | -------- | ------------------------------- | ---- | ---------------------------------------- | | name | AnimationEventName | Yes | Animation event type. The available options are as follows:
'enterFrame', 'loopComplete', 'complete', 'segmentStart', 'destroy', 'config_ready', 'data_ready', 'DOMLoaded', 'error', 'data_failed', 'loaded_images'| -| callback | AnimationEventCallback<T> | No | Custom callback. By default, the value is null, meaning that all callbacks of the event will be removed. | +| callback | AnimationEventCallback<T> | No | Custom callback. By default, the value is null, meaning that all callbacks of the event will be removed. | **Example** -- GitLab