已合并
update docs #156897
LexieLi创建于 7月22日
update docs #156897
已合并
共 6 个文件变更+2802-379
| @@ -2,18 +2,20 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Basic Services Kit--> | 3 | <!--Kit: Basic Services Kit--> |
| 4 | <!--Subsystem: Notification--> | 4 | <!--Subsystem: Notification--> |
| 5 | -<!--Owner: @peixu--> | 5 | +<!--Owner: @HuYueRong--> |
| 6 | -<!--Designer: @dongqingran; @wulong158--> | 6 | +<!--Designer: @dongqingran--> |
| 7 | <!--Tester: @wanghong1997--> | 7 | <!--Tester: @wanghong1997--> |
| 8 | <!--Adviser: @fang-jinxu--> | 8 | <!--Adviser: @fang-jinxu--> |
| 9 | +<!-- md-trans-meta sourceCommit=227499a15769ff89e238d0afb653f1633e59b877 translatedAt=2026-07-21T08:29:08.998Z pushedAt=2026-07-22T06:40:26.298Z --> | ||
| 9 | 10 | ||
| 10 | -This module provides common event capabilities to publish, subscribe to, and unsubscribe from common events. | 11 | +This module provides system APIs related to common events, including publishing common events to specified users, removing sticky common events, and enabling or disabling static subscription events. |
| 11 | 12 | ||
| 12 | > **NOTE** | 13 | > **NOTE** |
| 13 | > | 14 | > |
| 14 | -> 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. | 15 | +> - This module supports both ArkTS-Dyn and ArkTS-Sta. |
| 16 | +> - 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. | ||
| 15 | > | 17 | > |
| 16 | -> This topic describes only system APIs provided by the module. For details about its public APIs, see [CommonEventManager](./js-apis-commonEventManager.md). | 18 | +> - This topic describes only system APIs provided by the module. For details about its public APIs, see [CommonEventManager](./js-apis-commonEventManager.md). |
| 17 | 19 | ||
| 18 | ## Modules to Import | 20 | ## Modules to Import |
| 19 | 21 | ||
| @@ -25,24 +27,36 @@ import { commonEventManager } from '@kit.BasicServicesKit'; | |||
| 25 | 27 | ||
| 26 | A system common event is an event that is published by a system service or system application and requires specific permissions to subscribe to. To publish or subscribe to this type of event, you must follow the event-specific definitions. | 28 | A system common event is an event that is published by a system service or system application and requires specific permissions to subscribe to. To publish or subscribe to this type of event, you must follow the event-specific definitions. |
| 27 | 29 | ||
| 28 | -For details about the enum definitions of all system common events, see [System Common Events](./common_event/commonEventManager-definitions.md). | 30 | +For details about the enums of all system common events, see [System Common Events (System API)](./common_event/commonEventManager-definitions-sys.md). |
| 29 | 31 | ||
| 30 | -## commonEventManager.publishAsUser<sup> | 32 | +**System capability**: SystemCapability.Notification.CommonEvent |
| 31 | 33 | ||
| 32 | -publishAsUser(event: string, userId: number, callback: AsyncCallback\<void>): void | 34 | +**ArkTS-Dyn start version:** 9 |
| 35 | + | ||
| 36 | +**ArkTS-Sta start version:** 23 | ||
| 37 | + | ||
| 38 | +## commonEventManager.publishAsUser | ||
| 39 | + | ||
| 40 | +ArkTS-Dyn: publishAsUser(event: string, userId: number, callback: AsyncCallback\<void>): void | ||
| 41 | + | ||
| 42 | +ArkTS-Sta: publishAsUser(event: string, userId: int, callback: AsyncCallback\<void>): void | ||
| 33 | 43 | ||
| 34 | Publishes a common event to a specified user. This API uses an asynchronous callback to return the result. | 44 | Publishes a common event to a specified user. This API uses an asynchronous callback to return the result. |
| 35 | 45 | ||
| 36 | **System capability**: SystemCapability.Notification.CommonEvent | 46 | **System capability**: SystemCapability.Notification.CommonEvent |
| 37 | 47 | ||
| 38 | -**System API**: This is a system API and cannot be called by third-party applications. | 48 | +**System API**: This is a system API. |
| 49 | + | ||
| 50 | +**ArkTS-Dyn start version:** 9 | ||
| 51 | + | ||
| 52 | +**ArkTS-Sta start version:** 23 | ||
| 39 | 53 | ||
| 40 | **Parameters** | 54 | **Parameters** |
| 41 | 55 | ||
| 42 | | Name | Type | Mandatory| Description | | 56 | | Name | Type | Mandatory| Description | |
| 43 | | -------- | -------------------- | ---- | ---------------------------------- | | 57 | | -------- | -------------------- | ---- | ---------------------------------- | |
| 44 | -| event | string | Yes | Name of the common event to publish. For details, see [System Common Events](./common_event/commonEventManager-definitions.md). | | 58 | +| event | string | Yes | Name of the common event to publish. For details, see [System Common Events (System API)](./common_event/commonEventManager-definitions-sys.md). | |
| 45 | -| userId | number | Yes | User ID.| | 59 | +| userId | ArkTS-Dyn: number<br/>ArkTS-Sta: int | Yes | ID of the user who will receive the common event. | |
| 46 | | callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | | 60 | | callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | |
| 47 | 61 | ||
| 48 | **Error codes** | 62 | **Error codes** |
| @@ -51,15 +65,17 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 51 | 65 | ||
| 52 | | ID| Error Message | | 66 | | ID| Error Message | |
| 53 | | -------- | ----------------------------------- | | 67 | | -------- | ----------------------------------- | |
| 54 | -| 202 | not system app. | | 68 | +| 202 | Permission verification failed. A non-system application calls a system API. | |
| 55 | -| 1500003 | The common event sending frequency too high. | | 69 | +| 1500003 | The common event sending frequency too high.<br> Applicable versions: 20+ | |
| 56 | -| 1500006 | Invalid userId. | | 70 | +| 1500006 | Invalid userId.<br> Applicable versions: 21+ | |
| 57 | | 1500007 | Failed to send the message to the common event service. | | 71 | | 1500007 | Failed to send the message to the common event service. | |
| 58 | | 1500008 | Failed to initialize the common event service. | | 72 | | 1500008 | Failed to initialize the common event service. | |
| 59 | | 1500009 | Failed to obtain system parameters. | | 73 | | 1500009 | Failed to obtain system parameters. | |
| 60 | 74 | ||
| 61 | **Example** | 75 | **Example** |
| 62 | 76 | ||
| 77 | +**ArkTS-Dyn example:** | ||
| 78 | + | ||
| 63 | ```ts | 79 | ```ts |
| 64 | import { BusinessError } from '@kit.BasicServicesKit'; | 80 | import { BusinessError } from '@kit.BasicServicesKit'; |
| 65 | 81 | ||
| @@ -81,22 +97,51 @@ try { | |||
| 81 | } | 97 | } |
| 82 | ``` | 98 | ``` |
| 83 | 99 | ||
| 100 | +**ArkTS-Sta example:** | ||
| 101 | + | ||
| 102 | +```ts | ||
| 103 | +import { BusinessError } from '@kit.BasicServicesKit'; | ||
| 104 | + | ||
| 105 | +// Specify the target user. | ||
| 106 | +let userId = 1; | ||
| 107 | + | ||
| 108 | +// Publish the common event. | ||
| 109 | +try { | ||
| 110 | + commonEventManager.publishAsUser('event', userId, (err: BusinessError | null) => { | ||
| 111 | + if (err) { | ||
| 112 | + console.error(`publishAsUser failed, code is ${err.code}, message is ${err.message}`); | ||
| 113 | + return; | ||
| 114 | + } | ||
| 115 | + console.info('publishAsUser'); | ||
| 116 | + }); | ||
| 117 | +} catch (error) { | ||
| 118 | + let err: BusinessError = error as BusinessError; | ||
| 119 | + console.error(`publishAsUser failed, code is ${err.code}, message is ${err.message}`); | ||
| 120 | +} | ||
| 121 | +``` | ||
| 122 | + | ||
| 84 | ## commonEventManager.publishAsUser | 123 | ## commonEventManager.publishAsUser |
| 85 | 124 | ||
| 86 | -publishAsUser(event: string, userId: number, options: CommonEventPublishData, callback: AsyncCallback\<void>): void | 125 | +ArkTS-Dyn: publishAsUser(event: string, userId: number, options: CommonEventPublishData, callback: AsyncCallback\<void>): void |
| 126 | + | ||
| 127 | +ArkTS-Sta: publishAsUser(event: string, userId: int, options: CommonEventPublishData, callback: AsyncCallback\<void>): void | ||
| 87 | 128 | ||
| 88 | Publishes a common event to a specified user and specifies the information to be published. This API uses an asynchronous callback to return the result. | 129 | Publishes a common event to a specified user and specifies the information to be published. This API uses an asynchronous callback to return the result. |
| 89 | 130 | ||
| 90 | **System capability**: SystemCapability.Notification.CommonEvent | 131 | **System capability**: SystemCapability.Notification.CommonEvent |
| 91 | 132 | ||
| 92 | -**System API**: This is a system API and cannot be called by third-party applications. | 133 | +**System API**: This is a system API. |
| 134 | + | ||
| 135 | +**ArkTS-Dyn start version:** 9 | ||
| 136 | + | ||
| 137 | +**ArkTS-Sta start version:** 23 | ||
| 93 | 138 | ||
| 94 | **Parameters** | 139 | **Parameters** |
| 95 | 140 | ||
| 96 | | Name | Type | Mandatory| Description | | 141 | | Name | Type | Mandatory| Description | |
| 97 | | -------- | ---------------------- | ---- | ---------------------- | | 142 | | -------- | ---------------------- | ---- | ---------------------- | |
| 98 | -| event | string | Yes | Name of the common event to publish. For details, see [System Common Events](./common_event/commonEventManager-definitions.md). | | 143 | +| event | string | Yes | Name of the common event to publish. For details, see [System Common Events (System API)](./common_event/commonEventManager-definitions-sys.md). | |
| 99 | -| userId | number | Yes| User ID.| | 144 | +| userId | ArkTS-Dyn: number<br/>ArkTS-Sta: int | Yes | ID of the user who will receive the common event. | |
| 100 | | options | [CommonEventPublishData](./js-apis-inner-commonEvent-commonEventPublishData.md) | Yes | Properties of the common event to publish.| | 145 | | options | [CommonEventPublishData](./js-apis-inner-commonEvent-commonEventPublishData.md) | Yes | Properties of the common event to publish.| |
| 101 | | callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | | 146 | | callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | |
| 102 | 147 | ||
| @@ -106,22 +151,24 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 106 | 151 | ||
| 107 | | ID| Error Message | | 152 | | ID| Error Message | |
| 108 | | -------- | ----------------------------------- | | 153 | | -------- | ----------------------------------- | |
| 109 | -| 202 | not system app. | | 154 | +| 202 | Permission verification failed. A non-system application calls a system API. | |
| 110 | -| 1500003 | The common event sending frequency too high. | | 155 | +| 1500003 | The common event sending frequency too high.<br> Applicable versions: 20+ | |
| 111 | -| 1500006 | Invalid userId. | | 156 | +| 1500006 | Invalid userId.<br> Applicable versions: 21+ | |
| 112 | | 1500007 | Failed to send the message to the common event service. | | 157 | | 1500007 | Failed to send the message to the common event service. | |
| 113 | | 1500008 | Failed to initialize the common event service. | | 158 | | 1500008 | Failed to initialize the common event service. | |
| 114 | | 1500009 | Failed to obtain system parameters. | | 159 | | 1500009 | Failed to obtain system parameters. | |
| 115 | 160 | ||
| 116 | **Example** | 161 | **Example** |
| 117 | 162 | ||
| 163 | +**ArkTS-Dyn example:** | ||
| 164 | + | ||
| 118 | ```ts | 165 | ```ts |
| 119 | import { BusinessError } from '@kit.BasicServicesKit'; | 166 | import { BusinessError } from '@kit.BasicServicesKit'; |
| 120 | 167 | ||
| 121 | // Information of the common event. | 168 | // Information of the common event. |
| 122 | -let options:commonEventManager.CommonEventPublishData = { | 169 | +let options: commonEventManager.CommonEventPublishData = { |
| 123 | - code: 0, // Initial code of the common event. | 170 | + code: 0, // Initial code of the common event. |
| 124 | - data: 'initial data',// Initial data of the common event. | 171 | + data: 'initial data', // Initial data of the common event. |
| 125 | } | 172 | } |
| 126 | 173 | ||
| 127 | // Specify the user to whom the common event will be published. | 174 | // Specify the user to whom the common event will be published. |
| @@ -141,6 +188,34 @@ try { | |||
| 141 | } | 188 | } |
| 142 | ``` | 189 | ``` |
| 143 | 190 | ||
| 191 | +**ArkTS-Sta example:** | ||
| 192 | + | ||
| 193 | +```ts | ||
| 194 | +import { BusinessError } from '@kit.BasicServicesKit'; | ||
| 195 | + | ||
| 196 | +// Information about the common event. | ||
| 197 | +let options:commonEventManager.CommonEventPublishData = { | ||
| 198 | + code: 0,// Initial code of the common event. | ||
| 199 | + data: 'initial data',// Initial data of the common event. | ||
| 200 | +} | ||
| 201 | + | ||
| 202 | +// Specify the target user. | ||
| 203 | +let userId = 1; | ||
| 204 | +// Publish the common event. | ||
| 205 | +try { | ||
| 206 | + commonEventManager.publishAsUser('event', userId, options, (err: BusinessError | null) => { | ||
| 207 | + if (err) { | ||
| 208 | + console.error(`publishAsUser failed, code is ${err.code}, message is ${err.message}`); | ||
| 209 | + return; | ||
| 210 | + } | ||
| 211 | + console.info('publishAsUser'); | ||
| 212 | + }); | ||
| 213 | +} catch (error) { | ||
| 214 | + let err: BusinessError = error as BusinessError; | ||
| 215 | + console.error(`publishAsUser failed, code is ${err.code}, message is ${err.message}`); | ||
| 216 | +} | ||
| 217 | +``` | ||
| 218 | + | ||
| 144 | ## commonEventManager.removeStickyCommonEvent<sup>10+</sup> | 219 | ## commonEventManager.removeStickyCommonEvent<sup>10+</sup> |
| 145 | 220 | ||
| 146 | removeStickyCommonEvent(event: string, callback: AsyncCallback\<void>): void | 221 | removeStickyCommonEvent(event: string, callback: AsyncCallback\<void>): void |
| @@ -151,14 +226,18 @@ Removes a sticky common event. This API uses an asynchronous callback to return | |||
| 151 | 226 | ||
| 152 | **Required permissions**: ohos.permission.COMMONEVENT_STICKY | 227 | **Required permissions**: ohos.permission.COMMONEVENT_STICKY |
| 153 | 228 | ||
| 154 | -**System API**: This is a system API and cannot be called by third-party applications. | 229 | +**System API**: This is a system API. |
| 230 | + | ||
| 231 | +**ArkTS-Dyn start version:** 10 | ||
| 232 | + | ||
| 233 | +**ArkTS-Sta start version:** 23 | ||
| 155 | 234 | ||
| 156 | **Parameters** | 235 | **Parameters** |
| 157 | 236 | ||
| 158 | | Name | Type | Mandatory| Description | | 237 | | Name | Type | Mandatory| Description | |
| 159 | | -------- | -------------------- | ---- | -------------------------------- | | 238 | | -------- | -------------------- | ---- | -------------------------------- | |
| 160 | -| event | string | Yes | Sticky common event to remove. For details, see [System Common Events](./common_event/commonEventManager-definitions.md). | | 239 | +| event | string | Yes | Sticky common event to remove. For details, see [System Common Events (System API)](./common_event/commonEventManager-definitions-sys.md). | |
| 161 | -| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| | 240 | +| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the sticky common event is successfully removed, **err** is **undefined**; otherwise, **err** is an error object. | |
| 162 | 241 | ||
| 163 | **Error codes** | 242 | **Error codes** |
| 164 | 243 | ||
| @@ -166,15 +245,17 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 166 | 245 | ||
| 167 | | ID| Error Message | | 246 | | ID| Error Message | |
| 168 | | -------- | ----------------------------------- | | 247 | | -------- | ----------------------------------- | |
| 169 | -| 201 | The application does not have permission to call the interface. | | 248 | +| 201 | Permission verification failed. The application does not have the permission required to call the API. | |
| 170 | -| 202 | not system app. | | 249 | +| 202 | Permission verification failed. A non-system application calls a system API. | |
| 171 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 250 | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | |
| 172 | | 1500004 | A third-party application cannot send system common events. | | 251 | | 1500004 | A third-party application cannot send system common events. | |
| 173 | | 1500007 | Failed to send the message to the common event service. | | 252 | | 1500007 | Failed to send the message to the common event service. | |
| 174 | | 1500008 | Failed to initialize the common event service. | | 253 | | 1500008 | Failed to initialize the common event service. | |
| 175 | 254 | ||
| 176 | **Example** | 255 | **Example** |
| 177 | 256 | ||
| 257 | +**ArkTS-Dyn example:** | ||
| 258 | + | ||
| 178 | ```ts | 259 | ```ts |
| 179 | import { BusinessError } from '@kit.BasicServicesKit'; | 260 | import { BusinessError } from '@kit.BasicServicesKit'; |
| 180 | 261 | ||
| @@ -187,23 +268,41 @@ commonEventManager.removeStickyCommonEvent('sticky_event', (err: BusinessError) | |||
| 187 | }); | 268 | }); |
| 188 | ``` | 269 | ``` |
| 189 | 270 | ||
| 271 | +**ArkTS-Sta example:** | ||
| 272 | + | ||
| 273 | +```ts | ||
| 274 | +import { BusinessError } from '@kit.BasicServicesKit'; | ||
| 275 | + | ||
| 276 | +commonEventManager.removeStickyCommonEvent('sticky_event', (err: BusinessError | null) => { | ||
| 277 | + if (err) { | ||
| 278 | + console.error(`removeStickyCommonEvent failed, errCode: ${err.code}, errMes: ${err.message}`); | ||
| 279 | + return; | ||
| 280 | + } | ||
| 281 | + console.info(`removeStickyCommonEvent success`); | ||
| 282 | +}); | ||
| 283 | +``` | ||
| 284 | + | ||
| 190 | ## commonEventManager.removeStickyCommonEvent<sup>10+</sup> | 285 | ## commonEventManager.removeStickyCommonEvent<sup>10+</sup> |
| 191 | 286 | ||
| 192 | removeStickyCommonEvent(event: string): Promise\<void> | 287 | removeStickyCommonEvent(event: string): Promise\<void> |
| 193 | 288 | ||
| 194 | -Removes a sticky common event. This API uses a promise to return the result. | 289 | +Removes a sticky common event that has been published. This API uses a promise to return the result. |
| 195 | 290 | ||
| 196 | **System capability**: SystemCapability.Notification.CommonEvent | 291 | **System capability**: SystemCapability.Notification.CommonEvent |
| 197 | 292 | ||
| 198 | -**Required permissions**: ohos.permission.COMMONEVENT_STICKY | 293 | +**Required permissions:** ohos.permission.COMMONEVENT_STICKY |
| 199 | 294 | ||
| 200 | -**System API**: This is a system API and cannot be called by third-party applications. | 295 | +**System API**: This is a system API. |
| 296 | + | ||
| 297 | +**ArkTS-Dyn start version:** 10 | ||
| 298 | + | ||
| 299 | +**ArkTS-Sta start version:** 23 | ||
| 201 | 300 | ||
| 202 | **Parameters** | 301 | **Parameters** |
| 203 | 302 | ||
| 204 | | Name| Type | Mandatory| Description | | 303 | | Name| Type | Mandatory| Description | |
| 205 | | ------ | ------ | ---- | -------------------------- | | 304 | | ------ | ------ | ---- | -------------------------- | |
| 206 | -| event | string | Yes | Sticky common event to remove. For details, see [System Common Events](./common_event/commonEventManager-definitions.md).| | 305 | +| event | string | Yes | Sticky common event to remove. For details, see [System Common Events (System API)](./common_event/commonEventManager-definitions-sys.md). | |
| 207 | 306 | ||
| 208 | **Return value** | 307 | **Return value** |
| 209 | 308 | ||
| @@ -217,15 +316,17 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 217 | 316 | ||
| 218 | | ID| Error Message | | 317 | | ID| Error Message | |
| 219 | | -------- | ----------------------------------- | | 318 | | -------- | ----------------------------------- | |
| 220 | -| 201 | The application does not have permission to call the interface. | | 319 | +| 201 | Permission verification failed. The app does not have the permission required to call the API. | |
| 221 | -| 202 | not system app. | | 320 | +| 202 | Permission verification failed. A non-system app calls a system API. | |
| 222 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 321 | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | |
| 223 | | 1500004 | A third-party application cannot send system common events. | | 322 | | 1500004 | A third-party application cannot send system common events. | |
| 224 | | 1500007 | Failed to send the message to the common event service. | | 323 | | 1500007 | Failed to send the message to the common event service. | |
| 225 | | 1500008 | Failed to initialize the common event service. | | 324 | | 1500008 | Failed to initialize the common event service. | |
| 226 | 325 | ||
| 227 | **Example** | 326 | **Example** |
| 228 | 327 | ||
| 328 | +**ArkTS-Dyn example:** | ||
| 329 | + | ||
| 229 | ```ts | 330 | ```ts |
| 230 | import { BusinessError } from '@kit.BasicServicesKit'; | 331 | import { BusinessError } from '@kit.BasicServicesKit'; |
| 231 | 332 | ||
| @@ -236,6 +337,19 @@ commonEventManager.removeStickyCommonEvent('sticky_event').then(() => { | |||
| 236 | }); | 337 | }); |
| 237 | ``` | 338 | ``` |
| 238 | 339 | ||
| 340 | +**ArkTS-Sta example:** | ||
| 341 | + | ||
| 342 | +```ts | ||
| 343 | +import { BusinessError } from '@kit.BasicServicesKit'; | ||
| 344 | + | ||
| 345 | +commonEventManager.removeStickyCommonEvent('sticky_event').then(() => { | ||
| 346 | + console.info(`removeStickyCommonEvent success`); | ||
| 347 | +}).catch((err: Error): void => { | ||
| 348 | + let error: BusinessError = err as BusinessError; | ||
| 349 | + console.error(`removeStickyCommonEvent failed, errCode: ${error.code}, errMes: ${error.message}`); | ||
| 350 | +}); | ||
| 351 | +``` | ||
| 352 | + | ||
| 239 | ## commonEventManager.setStaticSubscriberState<sup>10+</sup> | 353 | ## commonEventManager.setStaticSubscriberState<sup>10+</sup> |
| 240 | 354 | ||
| 241 | setStaticSubscriberState(enable: boolean, callback: AsyncCallback\<void>): void | 355 | setStaticSubscriberState(enable: boolean, callback: AsyncCallback\<void>): void |
| @@ -246,13 +360,17 @@ Enables or disables static subscription for an application. This API uses an asy | |||
| 246 | 360 | ||
| 247 | **System capability**: SystemCapability.Notification.CommonEvent | 361 | **System capability**: SystemCapability.Notification.CommonEvent |
| 248 | 362 | ||
| 249 | -**System API**: This is a system API and cannot be called by third-party applications. | 363 | +**System API**: This is a system API. |
| 364 | + | ||
| 365 | +**ArkTS-Dyn start version:** 10 | ||
| 366 | + | ||
| 367 | +**ArkTS-Sta start version:** 23 | ||
| 250 | 368 | ||
| 251 | **Parameters** | 369 | **Parameters** |
| 252 | 370 | ||
| 253 | | Name| Type | Mandatory| Description | | 371 | | Name| Type | Mandatory| Description | |
| 254 | | ------ | ------ | ---- | -------------------------- | | 372 | | ------ | ------ | ---- | -------------------------- | |
| 255 | -| enable | boolean | Yes | Whether static subscription is enabled.<br> **true**: enabled.<br>**false**: disabled.| | 373 | +| enable | boolean | Yes | Whether static subscription is enabled.<br> **true**: enabled; **false**: disabled. | |
| 256 | | callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| | 374 | | callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| |
| 257 | 375 | ||
| 258 | **Error codes** | 376 | **Error codes** |
| @@ -261,13 +379,15 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 261 | 379 | ||
| 262 | | ID| Error Message | | 380 | | ID| Error Message | |
| 263 | | -------- | ----------------------------------- | | 381 | | -------- | ----------------------------------- | |
| 264 | -| 202 | not system app. | | 382 | +| 202 | Permission verification failed. A non-system application calls a system API. | |
| 265 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 383 | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | |
| 266 | | 1500007 | Failed to send the message to the common event service. | | 384 | | 1500007 | Failed to send the message to the common event service. | |
| 267 | | 1500008 | Failed to initialize the common event service. | | 385 | | 1500008 | Failed to initialize the common event service. | |
| 268 | 386 | ||
| 269 | **Example** | 387 | **Example** |
| 270 | 388 | ||
| 389 | +**ArkTS-Dyn example:** | ||
| 390 | + | ||
| 271 | ```ts | 391 | ```ts |
| 272 | import { BusinessError } from '@kit.BasicServicesKit'; | 392 | import { BusinessError } from '@kit.BasicServicesKit'; |
| 273 | 393 | ||
| @@ -280,6 +400,20 @@ commonEventManager.setStaticSubscriberState(true, (err: BusinessError) => { | |||
| 280 | }); | 400 | }); |
| 281 | ``` | 401 | ``` |
| 282 | 402 | ||
| 403 | +**ArkTS-Sta example:** | ||
| 404 | + | ||
| 405 | +```ts | ||
| 406 | +import { BusinessError } from '@kit.BasicServicesKit'; | ||
| 407 | + | ||
| 408 | +commonEventManager.setStaticSubscriberState(true, (err: BusinessError | null) => { | ||
| 409 | + if (err != null) { | ||
| 410 | + console.error(`setStaticSubscriberState failed, errCode: ${err.code}, errMes: ${err.message}`); | ||
| 411 | + return; | ||
| 412 | + } | ||
| 413 | + console.info(`setStaticSubscriberState success`); | ||
| 414 | +}); | ||
| 415 | +``` | ||
| 416 | + | ||
| 283 | ## commonEventManager.setStaticSubscriberState<sup>10+</sup> | 417 | ## commonEventManager.setStaticSubscriberState<sup>10+</sup> |
| 284 | 418 | ||
| 285 | setStaticSubscriberState(enable: boolean): Promise\<void> | 419 | setStaticSubscriberState(enable: boolean): Promise\<void> |
| @@ -290,13 +424,17 @@ Enables or disables static subscription for an application. This API uses a prom | |||
| 290 | 424 | ||
| 291 | **System capability**: SystemCapability.Notification.CommonEvent | 425 | **System capability**: SystemCapability.Notification.CommonEvent |
| 292 | 426 | ||
| 293 | -**System API**: This is a system API and cannot be called by third-party applications. | 427 | +**System API**: This is a system API. |
| 428 | + | ||
| 429 | +**ArkTS-Dyn start version:** 10 | ||
| 430 | + | ||
| 431 | +**ArkTS-Sta start version:** 23 | ||
| 294 | 432 | ||
| 295 | **Parameters** | 433 | **Parameters** |
| 296 | 434 | ||
| 297 | | Name| Type | Mandatory| Description | | 435 | | Name| Type | Mandatory| Description | |
| 298 | | ------ | ------ | ---- | -------------------------- | | 436 | | ------ | ------ | ---- | -------------------------- | |
| 299 | -| enable | boolean | Yes | Whether static subscription is enabled.<br> **true**: enabled.<br>**false**: disabled.| | 437 | +| enable | boolean | Yes | Whether static subscription is enabled.<br> **true**: enabled; **false**: disabled. | |
| 300 | 438 | ||
| 301 | **Return value** | 439 | **Return value** |
| 302 | 440 | ||
| @@ -310,13 +448,14 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 310 | 448 | ||
| 311 | | ID| Error Message | | 449 | | ID| Error Message | |
| 312 | | -------- | ----------------------------------- | | 450 | | -------- | ----------------------------------- | |
| 313 | -| 202 | not system app. | | 451 | +| 202 | Permission verification failed. A non-system app calls a system API. | |
| 314 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 452 | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | |
| 315 | | 1500007 | Failed to send the message to the common event service. | | 453 | | 1500007 | Failed to send the message to the common event service. | |
| 316 | | 1500008 | Failed to initialize the common event service. | | 454 | | 1500008 | Failed to initialize the common event service. | |
| 317 | 455 | ||
| 318 | **Example** | 456 | **Example** |
| 319 | 457 | ||
| 458 | +ArkTS-Dyn example: | ||
| 320 | 459 | ||
| 321 | ```ts | 460 | ```ts |
| 322 | import { BusinessError } from '@kit.BasicServicesKit'; | 461 | import { BusinessError } from '@kit.BasicServicesKit'; |
| @@ -328,10 +467,78 @@ commonEventManager.setStaticSubscriberState(false).then(() => { | |||
| 328 | }); | 467 | }); |
| 329 | ``` | 468 | ``` |
| 330 | 469 | ||
| 470 | +**ArkTS-Sta example:** | ||
| 471 | + | ||
| 472 | +```ts | ||
| 473 | +import { BusinessError } from '@kit.BasicServicesKit'; | ||
| 474 | + | ||
| 475 | +commonEventManager.setStaticSubscriberState(false).then(() => { | ||
| 476 | + console.info(`setStaticSubscriberState success`); | ||
| 477 | +}).catch((err: Error): void => { | ||
| 478 | + let error: BusinessError = err as BusinessError; | ||
| 479 | + console.error(`setStaticSubscriberState failed, errCode: ${error.code}, errMes: ${error.message}`); | ||
| 480 | +}); | ||
| 481 | +``` | ||
| 482 | + | ||
| 331 | ## commonEventManager.setStaticSubscriberState<sup>12+</sup> | 483 | ## commonEventManager.setStaticSubscriberState<sup>12+</sup> |
| 332 | 484 | ||
| 333 | setStaticSubscriberState(enable: boolean, events?: Array\<string>): Promise\<void> | 485 | setStaticSubscriberState(enable: boolean, events?: Array\<string>): Promise\<void> |
| 334 | 486 | ||
| 487 | +Enables or disables static subscription to a common event for the current application. This API uses a promise to return the result. | ||
| 488 | + | ||
| 489 | +**Model restriction**: This API can be used only in the stage model. | ||
| 490 | + | ||
| 491 | +**System capability**: SystemCapability.Notification.CommonEvent | ||
| 492 | + | ||
| 493 | +**System API**: This is a system API. | ||
| 494 | + | ||
| 495 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 496 | + | ||
| 497 | +**Related API:** The corresponding ArkTS-Sta API is [setStaticSubscriberState](#commoneventmanagersetstaticsubscriberstate). | ||
| 498 | + | ||
| 499 | +**ArkTS-Dyn start version:** 12 | ||
| 500 | + | ||
| 501 | +**Parameters** | ||
| 502 | + | ||
| 503 | +| Name | Type | Mandatory | Description | | ||
| 504 | +| ------ | ------------- | ---- | ---------------------------------------------------- | | ||
| 505 | +| enable | boolean | Yes | Whether the static subscription event is enabled. **true**: enable, **false**: disable. | | ||
| 506 | +| events | Array\<string> | No | Array of common event names to set. The array is empty by default, indicating that the status of all common events subscribed to in static mode by the current application is to be set. | | ||
| 507 | + | ||
| 508 | +**Return value** | ||
| 509 | + | ||
| 510 | +| Type | Description | | ||
| 511 | +| -------------- | ------------------------------------ | | ||
| 512 | +| Promise\<void> | Promise that returns no value. | | ||
| 513 | + | ||
| 514 | +**Error codes** | ||
| 515 | + | ||
| 516 | +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Event Error Codes](./errorcode-CommonEventService.md). | ||
| 517 | + | ||
| 518 | +| ID | Error Message | | ||
| 519 | +| -------- | ------------------------------------------------------ | | ||
| 520 | +| 202 | Permission verification failed. A non-system application calls a system API. | | ||
| 521 | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | | ||
| 522 | +| 1500007 | Failed to send the message to the common event service. | | ||
| 523 | +| 1500008 | Failed to initialize the common event service. | | ||
| 524 | + | ||
| 525 | +**Example** | ||
| 526 | + | ||
| 527 | +```ts | ||
| 528 | +import { BusinessError } from '@kit.BasicServicesKit'; | ||
| 529 | + | ||
| 530 | +let eventName: string[] = ['usual.event.SEND_DATA']; | ||
| 531 | +commonEventManager.setStaticSubscriberState(true, eventName).then(() => { | ||
| 532 | + console.info(`setStaticSubscriberState success, state is ${true}`); | ||
| 533 | +}).catch((err: BusinessError) => { | ||
| 534 | + console.error(`setStaticSubscriberState failed, errCode: ${err.code}, errMes: ${err.message}`); | ||
| 535 | +}); | ||
| 536 | +``` | ||
| 537 | + | ||
| 538 | +## commonEventManager.setStaticSubscriberState | ||
| 539 | + | ||
| 540 | +setStaticSubscriberState(enable: boolean, events: Array\<string>): Promise\<void> | ||
| 541 | + | ||
| 335 | Enables or disables the static subscription event for the current application and records the event name. This API uses a promise to return the result. | 542 | Enables or disables the static subscription event for the current application and records the event name. This API uses a promise to return the result. |
| 336 | 543 | ||
| 337 | **Model restriction**: This API can be used only in the stage model. | 544 | **Model restriction**: This API can be used only in the stage model. |
| @@ -340,12 +547,18 @@ Enables or disables the static subscription event for the current application an | |||
| 340 | 547 | ||
| 341 | **System API**: This is a system API. | 548 | **System API**: This is a system API. |
| 342 | 549 | ||
| 550 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 551 | + | ||
| 552 | +**Related API:** The corresponding ArkTS-Dyn API is [setStaticSubscriberState](#commoneventmanagersetstaticsubscriberstate12). | ||
| 553 | + | ||
| 554 | +**ArkTS-Sta start version:** 23 | ||
| 555 | + | ||
| 343 | **Parameters** | 556 | **Parameters** |
| 344 | 557 | ||
| 345 | | Name| Type | Mandatory| Description | | 558 | | Name| Type | Mandatory| Description | |
| 346 | | ------ | ------------- | ---- | ---------------------------------------------------- | | 559 | | ------ | ------------- | ---- | ---------------------------------------------------- | |
| 347 | -| enable | boolean | Yes | Whether static subscription is enabled.<br> **true**: enabled.<br>**false**: disabled.| | 560 | +| enable | boolean | Yes | Whether static subscription is enabled.<br> **true**: enabled; **false**: disabled.| |
| 348 | -| events | Array\<string> | No | Name of a recorded event. | | 561 | +| events | Array\<string> | Yes | Event names recorded. | |
| 349 | 562 | ||
| 350 | **Return value** | 563 | **Return value** |
| 351 | 564 | ||
| @@ -372,7 +585,8 @@ import { BusinessError } from '@kit.BasicServicesKit'; | |||
| 372 | let evenName: string[] = ['usual.event.SEND_DATA']; | 585 | let evenName: string[] = ['usual.event.SEND_DATA']; |
| 373 | commonEventManager.setStaticSubscriberState(true, evenName).then(() => { | 586 | commonEventManager.setStaticSubscriberState(true, evenName).then(() => { |
| 374 | console.info(`setStaticSubscriberState success, state is ${true}`); | 587 | console.info(`setStaticSubscriberState success, state is ${true}`); |
| 375 | -}).catch((err: BusinessError) => { | 588 | +}).catch((err: Error): void => { |
| 376 | - console.error(`setStaticSubscriberState failed, errCode: ${err.code}, errMes: ${err.message}`); | 589 | + let error: BusinessError = err as BusinessError; |
| 590 | + console.error(`setStaticSubscriberState failed, errCode: ${error.code}, errMes: ${error.message}`); | ||
| 377 | }); | 591 | }); |
| 378 | -``` | 592 | +``` |
| @@ -2,16 +2,54 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Basic Services Kit--> | 3 | <!--Kit: Basic Services Kit--> |
| 4 | <!--Subsystem: Notification--> | 4 | <!--Subsystem: Notification--> |
| 5 | -<!--Owner: @peixu--> | 5 | +<!--Owner: @HuYueRong--> |
| 6 | -<!--Designer: @dongqingran; @wulong158--> | 6 | +<!--Designer: @dongqingran--> |
| 7 | <!--Tester: @wanghong1997--> | 7 | <!--Tester: @wanghong1997--> |
| 8 | <!--Adviser: @fang-jinxu--> | 8 | <!--Adviser: @fang-jinxu--> |
| 9 | +<!-- md-trans-meta sourceCommit=227499a15769ff89e238d0afb653f1633e59b877 translatedAt=2026-07-21T08:29:24.994Z pushedAt=2026-07-22T06:40:29.156Z --> | ||
| 9 | 10 | ||
| 10 | -The **CommonEventManager** module provides common event capabilities to publish, subscribe to, and unsubscribe from common events. | 11 | +This module provides APIs to publish, subscribe to, and unsubscribe from common events. This module provides a system-level event notification mechanism that allows an app to send notifications to other apps that have subscribed to the event when the system status changes (such as power-on completion, battery level change, and screen on/off) or a custom service event occurs. This mechanism enables transferring information across components and apps. |
| 12 | + | ||
| 13 | +The key concepts involved in this module are as follows: | ||
| 14 | + | ||
| 15 | +- Unordered common events: common events that CES forwards regardless of whether subscribers receive the events and when they subscribe to the events. | ||
| 16 | + | ||
| 17 | +- Ordered common events: common events that CES forwards based on the subscriber priority. CES preferentially forwards an ordered common event to the subscriber with a higher priority, waits until the subscriber receives the event, and then forwards the event to the subscriber with a lower priority. Subscribers with the same priority receive common events in a random order. | ||
| 18 | + | ||
| 19 | +- Sticky common events: common events that can be sent to a subscriber before or after the subscriber initiates a subscription. Only system applications and system services can send sticky common events. | ||
| 20 | + | ||
| 21 | +**APIs used in combination** | ||
| 22 | + | ||
| 23 | +The event communication of this module involves three processes: subscription, publishing, and ordered event. The subscription process and publishing process are associated through the event name. The publisher and subscriber do not need to be aware of each other. | ||
| 24 | + | ||
| 25 | +**Subscription process: Create a subscriber, subscribe to an event, receive the event, and cancel the subscription.** | ||
| 26 | + | ||
| 27 | +1. Configure the subscriber information, declare the name of the event to be subscribed to, and set the subscription priority, publisher permission, and package name as required. | ||
| 28 | + | ||
| 29 | +2. Create a subscriber object using **commonEventManager.createSubscriberSync**. | ||
| 30 | + | ||
| 31 | +3. Subscribe to an event using **commonEventManager.subscribe**. When an event is published, use a callback to receive **CommonEventData**, and process the event data in the callback. | ||
| 32 | + | ||
| 33 | +4. Unsubscribe from the event using **commonEventManager.unsubscribe** when it is no longer needed. | ||
| 34 | + | ||
| 35 | +**Publishing process: Publish an event (carrying data and attributes as required).** | ||
| 36 | + | ||
| 37 | +1. Simple publishing: Publish an event by specifying only the event name using **commonEventManager.publish**. | ||
| 38 | + | ||
| 39 | +2. Publishing with data and attributes: Configure attributes such as code, data, parameters, and **isOrdered** using **CommonEventPublishData**, and then call **publish** to publish the event. | ||
| 40 | + | ||
| 41 | +**Ordered event process: Deliver the event by priority by collaborating with the subscriber.** | ||
| 42 | + | ||
| 43 | +1. Set **isOrdered** to **true** using **CommonEventPublishData** and call **publish** to publish ordered events. Events are delivered in sequence based on the subscriber priority. | ||
| 44 | + | ||
| 45 | +2. The subscriber with a higher priority receives the event first, who can modify the code and data in the callback using methods such as **setCodeAndData** for subsequent subscribers to receive. | ||
| 46 | + | ||
| 47 | +3. After the processing is complete, call **finishCommonEvent** to deliver the event to the subscriber with the next highest priority. To stop delivering the event, call **abortCommonEvent** to mark the event as aborted. | ||
| 11 | 48 | ||
| 12 | > **NOTE** | 49 | > **NOTE** |
| 13 | > | 50 | > |
| 14 | -> 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. | 51 | +> - This module supports both ArkTS-Dyn and ArkTS-Sta. |
| 52 | +> - 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. | ||
| 15 | 53 | ||
| 16 | ## Modules to Import | 54 | ## Modules to Import |
| 17 | 55 | ||
| @@ -21,7 +59,13 @@ import { commonEventManager } from '@kit.BasicServicesKit'; | |||
| 21 | 59 | ||
| 22 | ## Support | 60 | ## Support |
| 23 | 61 | ||
| 24 | -System common events refer to events released by system services or system applications. Subscribing to these common events requires specific permissions and values. For details, see [System Common Events](./common_event/commonEventManager-definitions.md). | 62 | +System common events refer to events released by system services or system apps. Subscribing to these common events requires specific permissions and event values. For details, see [System Common Events](./common_event/commonEventManager-definitions.md). |
| 63 | + | ||
| 64 | +**System capability**: SystemCapability.Notification.CommonEvent | ||
| 65 | + | ||
| 66 | +**ArkTS-Dyn start version:** 9 | ||
| 67 | + | ||
| 68 | +**ArkTS-Sta start version:** 23 | ||
| 25 | 69 | ||
| 26 | ## commonEventManager.publish | 70 | ## commonEventManager.publish |
| 27 | 71 | ||
| @@ -29,30 +73,36 @@ publish(event: string, callback: AsyncCallback\<void>): void | |||
| 29 | 73 | ||
| 30 | Publishes a common event. This API uses an asynchronous callback to return the result. | 74 | Publishes a common event. This API uses an asynchronous callback to return the result. |
| 31 | 75 | ||
| 32 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 76 | +**Atomic service API** (ArkTS-Dyn only): This API can be used in atomic services since API version 11. |
| 33 | 77 | ||
| 34 | **System capability**: SystemCapability.Notification.CommonEvent | 78 | **System capability**: SystemCapability.Notification.CommonEvent |
| 35 | 79 | ||
| 80 | +**ArkTS-Dyn start version:** 9 | ||
| 81 | + | ||
| 82 | +**ArkTS-Sta start version:** 23 | ||
| 83 | + | ||
| 36 | **Parameters** | 84 | **Parameters** |
| 37 | 85 | ||
| 38 | | Name | Type | Mandatory| Description | | 86 | | Name | Type | Mandatory| Description | |
| 39 | | -------- | -------------------- | ---- | ---------------------- | | 87 | | -------- | -------------------- | ---- | ---------------------- | |
| 40 | -| event | string | Yes | Name of the common event to publish. For details, see [System Common Events](./common_event/commonEventManager-definitions.md).| | 88 | +| event | string | Yes | Name of the common event to publish. For details, see [System Common Events](./common_event/commonEventManager-definitions.md). | |
| 41 | -| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| | 89 | +| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the common event is successfully published, **err** is **undefined**; otherwise, **err** is an error object. | |
| 42 | 90 | ||
| 43 | **Error codes** | 91 | **Error codes** |
| 44 | 92 | ||
| 45 | -For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Event Error Codes](./errorcode-CommonEventService.md). | 93 | +For details about the error codes, see [Event Error Codes](./errorcode-CommonEventService.md). |
| 46 | 94 | ||
| 47 | | ID| Error Message | | 95 | | ID| Error Message | |
| 48 | -| -------- | ----------------------------------- | | 96 | +| -------- | ----------------------------------- | |
| 49 | -| 1500003 | The common event sending frequency too high. | | 97 | +| 1500003 | The common event sending frequency too high.<br> Applicable versions: 20+ | |
| 50 | | 1500007 | Failed to send the message to the common event service. | | 98 | | 1500007 | Failed to send the message to the common event service. | |
| 51 | | 1500008 | Failed to initialize the common event service. | | 99 | | 1500008 | Failed to initialize the common event service. | |
| 52 | | 1500009 | Failed to obtain system parameters. | | 100 | | 1500009 | Failed to obtain system parameters. | |
| 53 | 101 | ||
| 54 | **Example** | 102 | **Example** |
| 55 | 103 | ||
| 104 | +ArkTS-Dyn example: | ||
| 105 | + | ||
| 56 | ```ts | 106 | ```ts |
| 57 | import { BusinessError } from '@kit.BasicServicesKit'; | 107 | import { BusinessError } from '@kit.BasicServicesKit'; |
| 58 | 108 | ||
| @@ -68,6 +118,26 @@ try { | |||
| 68 | } catch (error) { | 118 | } catch (error) { |
| 69 | let err: BusinessError = error as BusinessError; | 119 | let err: BusinessError = error as BusinessError; |
| 70 | console.error(`Failed to publish common event. Code is ${err.code}, message is ${err.message}`); | 120 | console.error(`Failed to publish common event. Code is ${err.code}, message is ${err.message}`); |
| 121 | +}; | ||
| 122 | +``` | ||
| 123 | + | ||
| 124 | +ArkTS-Sta example: | ||
| 125 | + | ||
| 126 | +```ts | ||
| 127 | +import { BusinessError } from '@kit.BasicServicesKit'; | ||
| 128 | + | ||
| 129 | +// Publish a common event. | ||
| 130 | +try { | ||
| 131 | + commonEventManager.publish('event', (err: BusinessError | null) => { | ||
| 132 | + if (err) { | ||
| 133 | + console.error(`Failed to publish common event. Code is ${err.code}, message is ${err.message}`); | ||
| 134 | + return; | ||
| 135 | + } | ||
| 136 | + console.info(`Succeeded in publishing common event.`); | ||
| 137 | + }); | ||
| 138 | +} catch (error) { | ||
| 139 | + let err: BusinessError = error as BusinessError; | ||
| 140 | + console.error(`Failed to publish common event. Code is ${err.code}, message is ${err.message}`); | ||
| 71 | } | 141 | } |
| 72 | ``` | 142 | ``` |
| 73 | 143 | ||
| @@ -77,31 +147,37 @@ publish(event: string, options: CommonEventPublishData, callback: AsyncCallback\ | |||
| 77 | 147 | ||
| 78 | Publishes a common event. This API uses an asynchronous callback to return the result. | 148 | Publishes a common event. This API uses an asynchronous callback to return the result. |
| 79 | 149 | ||
| 80 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 150 | +**Atomic service API** (ArkTS-Dyn only): This API can be used in atomic services since API version 11. |
| 81 | 151 | ||
| 82 | **System capability**: SystemCapability.Notification.CommonEvent | 152 | **System capability**: SystemCapability.Notification.CommonEvent |
| 83 | 153 | ||
| 154 | +**ArkTS-Dyn start version:** 9 | ||
| 155 | + | ||
| 156 | +**ArkTS-Sta start version:** 23 | ||
| 157 | + | ||
| 84 | **Parameters** | 158 | **Parameters** |
| 85 | 159 | ||
| 86 | | Name | Type | Mandatory| Description | | 160 | | Name | Type | Mandatory| Description | |
| 87 | | -------- | ---------------------- | ---- | ---------------------- | | 161 | | -------- | ---------------------- | ---- | ---------------------- | |
| 88 | -| event | string | Yes | Name of the common event to publish. For details, see [System Common Events](./common_event/commonEventManager-definitions.md). | | 162 | +| event | string | Yes | Name of the common event to publish. For details, see [System Common Events](./common_event/commonEventManager-definitions.md). | |
| 89 | | options | [CommonEventPublishData](./js-apis-inner-commonEvent-commonEventPublishData.md) | Yes | Properties of the common event to publish.| | 163 | | options | [CommonEventPublishData](./js-apis-inner-commonEvent-commonEventPublishData.md) | Yes | Properties of the common event to publish.| |
| 90 | -| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | | 164 | +| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the common event is successfully published, **err** is **undefined**; otherwise, **err** is an error object. | |
| 91 | 165 | ||
| 92 | **Error codes** | 166 | **Error codes** |
| 93 | 167 | ||
| 94 | -For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Event Error Codes](./errorcode-CommonEventService.md). | 168 | +For details about the error codes, see [Event Error Codes](./errorcode-CommonEventService.md). |
| 95 | 169 | ||
| 96 | | ID| Error Message | | 170 | | ID| Error Message | |
| 97 | | -------- | ----------------------------------- | | 171 | | -------- | ----------------------------------- | |
| 98 | -| 1500003 | The common event sending frequency too high. | | 172 | +| 1500003 | The common event sending frequency too high.<br> Applicable versions: 20+ | |
| 99 | | 1500007 | Failed to send the message to the common event service. | | 173 | | 1500007 | Failed to send the message to the common event service. | |
| 100 | | 1500008 | Failed to initialize the common event service. | | 174 | | 1500008 | Failed to initialize the common event service. | |
| 101 | | 1500009 | Failed to obtain system parameters. | | 175 | | 1500009 | Failed to obtain system parameters. | |
| 102 | 176 | ||
| 103 | **Example** | 177 | **Example** |
| 104 | 178 | ||
| 179 | +ArkTS-Dyn example: | ||
| 180 | + | ||
| 105 | ```ts | 181 | ```ts |
| 106 | import { BusinessError } from '@kit.BasicServicesKit'; | 182 | import { BusinessError } from '@kit.BasicServicesKit'; |
| 107 | 183 | ||
| @@ -127,22 +203,53 @@ try { | |||
| 127 | } | 203 | } |
| 128 | ``` | 204 | ``` |
| 129 | 205 | ||
| 206 | +ArkTS-Sta example: | ||
| 207 | + | ||
| 208 | +```ts | ||
| 209 | +import { BusinessError } from '@kit.BasicServicesKit'; | ||
| 210 | + | ||
| 211 | +// Common event information. The following uses an ordered common event as an example. | ||
| 212 | +let options: commonEventManager.CommonEventPublishData = { | ||
| 213 | + code: 0, | ||
| 214 | + data: 'initial data', | ||
| 215 | + isOrdered: true // The common event is an ordered one. | ||
| 216 | +} | ||
| 217 | + | ||
| 218 | +// Publish a common event. | ||
| 219 | +try { | ||
| 220 | + commonEventManager.publish('event', options, (err: BusinessError | null) => { | ||
| 221 | + if (err) { | ||
| 222 | + console.error(`Failed to publish common event. Code is ${err.code}, message is ${err.message}`); | ||
| 223 | + return; | ||
| 224 | + } | ||
| 225 | + console.info(`Succeeded in publishing common event.`); | ||
| 226 | + }); | ||
| 227 | +} catch (error) { | ||
| 228 | + let err: BusinessError = error as BusinessError; | ||
| 229 | + console.error(`Failed to publish common event. Code is ${err.code}, message is ${err.message}`); | ||
| 230 | +} | ||
| 231 | +``` | ||
| 232 | + | ||
| 130 | ## commonEventManager.createSubscriber | 233 | ## commonEventManager.createSubscriber |
| 131 | 234 | ||
| 132 | createSubscriber(subscribeInfo: CommonEventSubscribeInfo, callback: AsyncCallback\<CommonEventSubscriber>): void | 235 | createSubscriber(subscribeInfo: CommonEventSubscribeInfo, callback: AsyncCallback\<CommonEventSubscriber>): void |
| 133 | 236 | ||
| 134 | Creates a subscriber. This API uses an asynchronous callback to return the result. | 237 | Creates a subscriber. This API uses an asynchronous callback to return the result. |
| 135 | 238 | ||
| 136 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 239 | +**Atomic service API** (ArkTS-Dyn only): This API can be used in atomic services since API version 11. |
| 137 | 240 | ||
| 138 | **System capability**: SystemCapability.Notification.CommonEvent | 241 | **System capability**: SystemCapability.Notification.CommonEvent |
| 139 | 242 | ||
| 243 | +**ArkTS-Dyn start version:** 9 | ||
| 244 | + | ||
| 245 | +**ArkTS-Sta start version:** 23 | ||
| 246 | + | ||
| 140 | **Parameters** | 247 | **Parameters** |
| 141 | 248 | ||
| 142 | | Name | Type | Mandatory| Description | | 249 | | Name | Type | Mandatory| Description | |
| 143 | | ------------- | ------------------------------------------------------------ | ---- | -------------------------- | | 250 | | ------------- | ------------------------------------------------------------ | ---- | -------------------------- | |
| 144 | | subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | Yes | Subscriber information. | | 251 | | subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | Yes | Subscriber information. | |
| 145 | -| callback | AsyncCallback\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md#commoneventsubscriber-1)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| | 252 | +| callback | AsyncCallback\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md#commoneventsubscriber-1)> | Yes | Callback used to return the result. If the common event subscriber is created successfully, **err** is **undefined** and **data** is the created **CommonEventSubscriber** object; if the creation fails, **err** is an error object. | |
| 146 | 253 | ||
| 147 | **Error codes** | 254 | **Error codes** |
| 148 | 255 | ||
| @@ -150,10 +257,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 150 | 257 | ||
| 151 | | ID| Error Message | | 258 | | ID| Error Message | |
| 152 | | -------- | ----------------------------------- | | 259 | | -------- | ----------------------------------- | |
| 153 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 260 | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | |
| 154 | 261 | ||
| 155 | **Example** | 262 | **Example** |
| 156 | 263 | ||
| 264 | +ArkTS-Dyn example: | ||
| 265 | + | ||
| 157 | ```ts | 266 | ```ts |
| 158 | import { BusinessError } from '@kit.BasicServicesKit'; | 267 | import { BusinessError } from '@kit.BasicServicesKit'; |
| 159 | 268 | ||
| @@ -181,16 +290,58 @@ try { | |||
| 181 | } | 290 | } |
| 182 | ``` | 291 | ``` |
| 183 | 292 | ||
| 293 | +ArkTS-Sta example: | ||
| 294 | + | ||
| 295 | +```ts | ||
| 296 | +import { BusinessError } from '@kit.BasicServicesKit'; | ||
| 297 | + | ||
| 298 | +// Define a subscriber to save the created subscriber object for subsequent subscription and unsubscription. | ||
| 299 | +let subscriber: commonEventManager.CommonEventSubscriber | null = null; | ||
| 300 | + | ||
| 301 | +// Subscriber information. | ||
| 302 | +let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = { | ||
| 303 | + events: ['event'] | ||
| 304 | +}; | ||
| 305 | + | ||
| 306 | +// Create a subscriber. | ||
| 307 | +try { | ||
| 308 | + commonEventManager.createSubscriber( | ||
| 309 | + subscribeInfo, | ||
| 310 | + (err: BusinessError | null, | ||
| 311 | + commonEventSubscriber: commonEventManager.CommonEventSubscriber | undefined | null) => { | ||
| 312 | + if (!err && commonEventSubscriber) { | ||
| 313 | + console.info(`Succeeded in creating subscriber.`); | ||
| 314 | + subscriber = commonEventSubscriber; // Type matching. | ||
| 315 | + return; | ||
| 316 | + } | ||
| 317 | + | ||
| 318 | + if (err) { | ||
| 319 | + console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`); | ||
| 320 | + } else { | ||
| 321 | + console.error(`Failed to create subscriber: commonEventSubscriber is null or undefined`); | ||
| 322 | + } | ||
| 323 | + } | ||
| 324 | + ); | ||
| 325 | +} catch (error) { | ||
| 326 | + let err: BusinessError = error as BusinessError; | ||
| 327 | + console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`); | ||
| 328 | +} | ||
| 329 | +``` | ||
| 330 | + | ||
| 184 | ## commonEventManager.createSubscriber | 331 | ## commonEventManager.createSubscriber |
| 185 | 332 | ||
| 186 | createSubscriber(subscribeInfo: CommonEventSubscribeInfo): Promise\<CommonEventSubscriber> | 333 | createSubscriber(subscribeInfo: CommonEventSubscribeInfo): Promise\<CommonEventSubscriber> |
| 187 | 334 | ||
| 188 | Creates a subscriber. This API uses a promise to return the result. | 335 | Creates a subscriber. This API uses a promise to return the result. |
| 189 | 336 | ||
| 190 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 337 | +**Atomic service API** (ArkTS-Dyn only): This API can be used in atomic services since API version 11. |
| 191 | 338 | ||
| 192 | **System capability**: SystemCapability.Notification.CommonEvent | 339 | **System capability**: SystemCapability.Notification.CommonEvent |
| 193 | 340 | ||
| 341 | +**ArkTS-Dyn start version:** 9 | ||
| 342 | + | ||
| 343 | +**ArkTS-Sta start version:** 23 | ||
| 344 | + | ||
| 194 | **Parameters** | 345 | **Parameters** |
| 195 | 346 | ||
| 196 | | Name | Type | Mandatory| Description | | 347 | | Name | Type | Mandatory| Description | |
| @@ -198,6 +349,7 @@ Creates a subscriber. This API uses a promise to return the result. | |||
| 198 | | subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | Yes | Subscriber information.| | 349 | | subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | Yes | Subscriber information.| |
| 199 | 350 | ||
| 200 | **Return value** | 351 | **Return value** |
| 352 | + | ||
| 201 | | Type | Description | | 353 | | Type | Description | |
| 202 | | --------------------------------------------------------- | ---------------- | | 354 | | --------------------------------------------------------- | ---------------- | |
| 203 | | Promise\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md#commoneventsubscriber-1)> | Promise used to return the created subscriber object.| | 355 | | Promise\<[CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md#commoneventsubscriber-1)> | Promise used to return the created subscriber object.| |
| @@ -208,10 +360,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 208 | 360 | ||
| 209 | | ID| Error Message | | 361 | | ID| Error Message | |
| 210 | | -------- | ----------------------------------- | | 362 | | -------- | ----------------------------------- | |
| 211 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 363 | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | |
| 212 | 364 | ||
| 213 | **Example** | 365 | **Example** |
| 214 | 366 | ||
| 367 | +ArkTS-Dyn example: | ||
| 368 | + | ||
| 215 | ```ts | 369 | ```ts |
| 216 | import { BusinessError } from '@kit.BasicServicesKit'; | 370 | import { BusinessError } from '@kit.BasicServicesKit'; |
| 217 | 371 | ||
| @@ -230,16 +384,43 @@ commonEventManager.createSubscriber(subscribeInfo).then((commonEventSubscriber: | |||
| 230 | }); | 384 | }); |
| 231 | ``` | 385 | ``` |
| 232 | 386 | ||
| 387 | +ArkTS-Sta example: | ||
| 388 | + | ||
| 389 | +```ts | ||
| 390 | +import { BusinessError } from '@kit.BasicServicesKit'; | ||
| 391 | + | ||
| 392 | +// Define a subscriber to save the created subscriber object for subsequent subscription and unsubscription. | ||
| 393 | +let subscriber: commonEventManager.CommonEventSubscriber; | ||
| 394 | +// Subscriber information. | ||
| 395 | +let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = { | ||
| 396 | + events: ['event'] | ||
| 397 | +}; | ||
| 398 | +// Create a subscriber. | ||
| 399 | +commonEventManager.createSubscriber(subscribeInfo) | ||
| 400 | + .then((commonEventSubscriber: commonEventManager.CommonEventSubscriber) => { | ||
| 401 | + console.info(`Succeeded in creating subscriber.`); | ||
| 402 | + subscriber = commonEventSubscriber; | ||
| 403 | + }) | ||
| 404 | + .catch((err: Error): void => { | ||
| 405 | + let error: BusinessError = err as BusinessError; | ||
| 406 | + console.error(`Failed to create subscriber. Code is ${error.code}, message is ${error.message}`); | ||
| 407 | + }); | ||
| 408 | +``` | ||
| 409 | + | ||
| 233 | ## commonEventManager.createSubscriberSync<sup>10+</sup> | 410 | ## commonEventManager.createSubscriberSync<sup>10+</sup> |
| 234 | 411 | ||
| 235 | createSubscriberSync(subscribeInfo: CommonEventSubscribeInfo): CommonEventSubscriber | 412 | createSubscriberSync(subscribeInfo: CommonEventSubscribeInfo): CommonEventSubscriber |
| 236 | 413 | ||
| 237 | -Creates a subscriber. The API returns the result synchronously. | 414 | +Creates a subscriber synchronously. |
| 238 | 415 | ||
| 239 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 416 | +**Atomic service API** (ArkTS-Dyn only): This API can be used in atomic services since API version 11. |
| 240 | 417 | ||
| 241 | **System capability**: SystemCapability.Notification.CommonEvent | 418 | **System capability**: SystemCapability.Notification.CommonEvent |
| 242 | 419 | ||
| 420 | +**ArkTS-Dyn start version:** 10 | ||
| 421 | + | ||
| 422 | +**ArkTS-Sta start version:** 23 | ||
| 423 | + | ||
| 243 | **Parameters** | 424 | **Parameters** |
| 244 | 425 | ||
| 245 | | Name | Type | Mandatory| Description | | 426 | | Name | Type | Mandatory| Description | |
| @@ -247,9 +428,10 @@ Creates a subscriber. The API returns the result synchronously. | |||
| 247 | | subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | Yes | Subscriber information.| | 428 | | subscribeInfo | [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | Yes | Subscriber information.| |
| 248 | 429 | ||
| 249 | **Return value** | 430 | **Return value** |
| 431 | + | ||
| 250 | | Type | Description | | 432 | | Type | Description | |
| 251 | | --------------------------------------------------------- | ---------------- | | 433 | | --------------------------------------------------------- | ---------------- | |
| 252 | -| [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md#commoneventsubscriber-1) | Promise used to return the subscriber object.| | 434 | +| [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md#commoneventsubscriber-1) | Subscriber object.| |
| 253 | 435 | ||
| 254 | **Error codes** | 436 | **Error codes** |
| 255 | 437 | ||
| @@ -257,7 +439,7 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 257 | 439 | ||
| 258 | | ID| Error Message | | 440 | | ID| Error Message | |
| 259 | | -------- | ----------------------------------- | | 441 | | -------- | ----------------------------------- | |
| 260 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 442 | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | |
| 261 | 443 | ||
| 262 | **Example** | 444 | **Example** |
| 263 | 445 | ||
| @@ -285,16 +467,20 @@ subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback\<CommonEven | |||
| 285 | 467 | ||
| 286 | Subscribes to a common event. This API uses an asynchronous callback to return the result. | 468 | Subscribes to a common event. This API uses an asynchronous callback to return the result. |
| 287 | 469 | ||
| 288 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 470 | +**Atomic service API** (ArkTS-Dyn only): This API can be used in atomic services since API version 11. |
| 289 | 471 | ||
| 290 | **System capability**: SystemCapability.Notification.CommonEvent | 472 | **System capability**: SystemCapability.Notification.CommonEvent |
| 291 | 473 | ||
| 474 | +**ArkTS-Dyn start version:** 9 | ||
| 475 | + | ||
| 476 | +**ArkTS-Sta start version:** 23 | ||
| 477 | + | ||
| 292 | **Parameters** | 478 | **Parameters** |
| 293 | 479 | ||
| 294 | | Name | Type | Mandatory| Description | | 480 | | Name | Type | Mandatory| Description | |
| 295 | | ---------- | ---------------------------------------------------- | ---- | -------------------------------- | | 481 | | ---------- | ---------------------------------------------------- | ---- | -------------------------------- | |
| 296 | | subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md#commoneventsubscriber-1) | Yes | Subscriber object. | | 482 | | subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md#commoneventsubscriber-1) | Yes | Subscriber object. | |
| 297 | -| callback | AsyncCallback\<[CommonEventData](./js-apis-inner-commonEvent-commonEventData.md)> | Yes | Callback triggered if the operation is successful; otherwise, **err** is an error object.| | 483 | +| callback | AsyncCallback\<[CommonEventData](./js-apis-inner-commonEvent-commonEventData.md)> | Yes | Callback used to return the result. When a common event is successfully subscribed to, the common event data is returned by **data** when the event is triggered. If the subscription fails, **err** is an error object. | |
| 298 | 484 | ||
| 299 | **Error codes** | 485 | **Error codes** |
| 300 | 486 | ||
| @@ -302,17 +488,19 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 302 | 488 | ||
| 303 | | ID| Error Message | | 489 | | ID| Error Message | |
| 304 | | -------- | ----------------------------------- | | 490 | | -------- | ----------------------------------- | |
| 305 | -| 801 | capability not supported. | | 491 | +| 801 | Capability not supported. | |
| 306 | | 1500007 | Failed to send the message to the common event service. | | 492 | | 1500007 | Failed to send the message to the common event service. | |
| 307 | | 1500008 | Failed to initialize the common event service. | | 493 | | 1500008 | Failed to initialize the common event service. | |
| 308 | -| 1500010 | The count of subscriber exceed system specification. | | 494 | +| 1500010 | The count of subscriber exceeds system specification. <br> Applicable versions: 20+| |
| 309 | 495 | ||
| 310 | **Example** | 496 | **Example** |
| 311 | 497 | ||
| 498 | +ArkTS-Dyn example: | ||
| 499 | + | ||
| 312 | ```ts | 500 | ```ts |
| 313 | import { BusinessError } from '@kit.BasicServicesKit'; | 501 | import { BusinessError } from '@kit.BasicServicesKit'; |
| 314 | 502 | ||
| 315 | -// Define a subscriber to save the created subscriber object for subsequent subscription and unsubscription. | 503 | +// Define a subscriber to save the successfully created subscriber object, which will be used later for subscription and unsubscription. |
| 316 | let subscriber: commonEventManager.CommonEventSubscriber | null = null; | 504 | let subscriber: commonEventManager.CommonEventSubscriber | null = null; |
| 317 | // Subscriber information. | 505 | // Subscriber information. |
| 318 | let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = { | 506 | let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = { |
| @@ -349,22 +537,70 @@ try { | |||
| 349 | } | 537 | } |
| 350 | ``` | 538 | ``` |
| 351 | 539 | ||
| 540 | +ArkTS-Sta example: | ||
| 541 | + | ||
| 542 | +```ts | ||
| 543 | +import { BusinessError } from '@kit.BasicServicesKit'; | ||
| 544 | + | ||
| 545 | +// Define a subscriber to save the created subscriber object for subsequent subscription and unsubscription. | ||
| 546 | +let subscriber: commonEventManager.CommonEventSubscriber; | ||
| 547 | +// Subscriber information. | ||
| 548 | +let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = { | ||
| 549 | + events: ['event'] | ||
| 550 | +}; | ||
| 551 | + | ||
| 552 | +// Create a subscriber. | ||
| 553 | +try { | ||
| 554 | + commonEventManager.createSubscriber(subscribeInfo, | ||
| 555 | + (err: BusinessError | null, | ||
| 556 | + commonEventSubscriber: commonEventManager.CommonEventSubscriber | undefined | null) => { | ||
| 557 | + if (!err) { | ||
| 558 | + console.info(`Succeeded in creating subscriber.`); | ||
| 559 | + subscriber = commonEventSubscriber as commonEventManager.CommonEventSubscriber; | ||
| 560 | + // Subscribe to the common event. | ||
| 561 | + try { | ||
| 562 | + commonEventManager.subscribe(subscriber, | ||
| 563 | + (err: BusinessError | null, data: commonEventManager.CommonEventData | undefined | null) => { | ||
| 564 | + if (err) { | ||
| 565 | + console.error(`Failed to subscribe. Code is ${err.code}, message is ${err.message}`); | ||
| 566 | + return; | ||
| 567 | + } | ||
| 568 | + console.info(`Succeeded in subscribing, data is ${JSON.stringify(data)}`); | ||
| 569 | + }); | ||
| 570 | + } catch (error) { | ||
| 571 | + let err: BusinessError = error as BusinessError; | ||
| 572 | + console.error(`Failed to subscribe. Code is ${err.code}, message is ${err.message}`); | ||
| 573 | + } | ||
| 574 | + return; | ||
| 575 | + } | ||
| 576 | + console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`); | ||
| 577 | + }); | ||
| 578 | +} catch (error) { | ||
| 579 | + let err: BusinessError = error as BusinessError; | ||
| 580 | + console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`); | ||
| 581 | +} | ||
| 582 | +``` | ||
| 583 | + | ||
| 352 | ## commonEventManager.unsubscribe | 584 | ## commonEventManager.unsubscribe |
| 353 | 585 | ||
| 354 | unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback\<void>): void | 586 | unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback\<void>): void |
| 355 | 587 | ||
| 356 | Unsubscribes from a common event. This API uses an asynchronous callback to return the result. | 588 | Unsubscribes from a common event. This API uses an asynchronous callback to return the result. |
| 357 | 589 | ||
| 358 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 590 | +**Atomic service API** (ArkTS-Dyn only): This API can be used in atomic services since API version 11. |
| 359 | 591 | ||
| 360 | **System capability**: SystemCapability.Notification.CommonEvent | 592 | **System capability**: SystemCapability.Notification.CommonEvent |
| 361 | 593 | ||
| 594 | +**ArkTS-Dyn start version:** 9 | ||
| 595 | + | ||
| 596 | +**ArkTS-Sta start version:** 23 | ||
| 597 | + | ||
| 362 | **Parameters** | 598 | **Parameters** |
| 363 | 599 | ||
| 364 | | Name | Type | Mandatory| Description | | 600 | | Name | Type | Mandatory| Description | |
| 365 | | ---------- | ----------------------------------------------- | ---- | ------------------------ | | 601 | | ---------- | ----------------------------------------------- | ---- | ------------------------ | |
| 366 | | subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md#commoneventsubscriber-1) | Yes | Subscriber object. | | 602 | | subscriber | [CommonEventSubscriber](./js-apis-inner-commonEvent-commonEventSubscriber.md#commoneventsubscriber-1) | Yes | Subscriber object. | |
| 367 | -| callback | AsyncCallback\<void> | No | Callback to unregister. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| | 603 | +| callback | AsyncCallback\<void> | No | Callback used to return the result. If the unsubscription is successful, **err** is undefined; otherwise, **err** is an error object. If this parameter is not passed, the subscription is unsubscribed by default without returning a result. | |
| 368 | 604 | ||
| 369 | **Error codes** | 605 | **Error codes** |
| 370 | 606 | ||
| @@ -372,13 +608,15 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 372 | 608 | ||
| 373 | | ID| Error Message | | 609 | | ID| Error Message | |
| 374 | | -------- | ----------------------------------- | | 610 | | -------- | ----------------------------------- | |
| 375 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 611 | +| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | |
| 376 | -| 801 | capability not supported. | | 612 | +| 801 | Capability not supported. | |
| 377 | | 1500007 | Failed to send the message to the common event service. | | 613 | | 1500007 | Failed to send the message to the common event service. | |
| 378 | | 1500008 | Failed to initialize the common event service. | | 614 | | 1500008 | Failed to initialize the common event service. | |
| 379 | 615 | ||
| 380 | **Example** | 616 | **Example** |
| 381 | 617 | ||
| 618 | +ArkTS-Dyn example: | ||
| 619 | + | ||
| 382 | ```ts | 620 | ```ts |
| 383 | import { BusinessError } from '@kit.BasicServicesKit'; | 621 | import { BusinessError } from '@kit.BasicServicesKit'; |
| 384 | 622 | ||
| @@ -438,16 +676,99 @@ setTimeout(() => { | |||
| 438 | }, 500); | 676 | }, 500); |
| 439 | ``` | 677 | ``` |
| 440 | 678 | ||
| 679 | +ArkTS-Sta example: | ||
| 680 | + | ||
| 681 | +```ts | ||
| 682 | +import { BusinessError } from '@kit.BasicServicesKit'; | ||
| 683 | + | ||
| 684 | +// Define a subscriber, which can be null or undefined. | ||
| 685 | +let subscriber: commonEventManager.CommonEventSubscriber | null | undefined = null; | ||
| 686 | + | ||
| 687 | +// Subscriber information. | ||
| 688 | +let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = { | ||
| 689 | + events: ['event'] | ||
| 690 | +}; | ||
| 691 | + | ||
| 692 | + // Create the subscriber. | ||
| 693 | +try { | ||
| 694 | + commonEventManager.createSubscriber( | ||
| 695 | + subscribeInfo, | ||
| 696 | + (err: BusinessError | null, | ||
| 697 | + commonEventSubscriber: commonEventManager.CommonEventSubscriber | undefined | null) => { | ||
| 698 | + if (!err && commonEventSubscriber) { | ||
| 699 | + console.info(`Succeeded in creating subscriber.`); | ||
| 700 | + subscriber = commonEventSubscriber as commonEventManager.CommonEventSubscriber; | ||
| 701 | + // Subscribe to a common event. Use a non-null object. | ||
| 702 | + try { | ||
| 703 | + commonEventManager.subscribe( | ||
| 704 | + commonEventSubscriber, // Directly use the callback parameter, and ensure it is not null. | ||
| 705 | + (err: BusinessError | null, data: commonEventManager.CommonEventData | undefined | null) => { | ||
| 706 | + if (err) { | ||
| 707 | + console.error(`Failed to subscribe. Code is ${err.code}, message is ${err.message}`); | ||
| 708 | + return; | ||
| 709 | + } | ||
| 710 | + console.info(`Succeeded in subscribing, data is ${JSON.stringify(data)}`); | ||
| 711 | + } | ||
| 712 | + ); | ||
| 713 | + } catch (error) { | ||
| 714 | + const err = error as BusinessError; | ||
| 715 | + console.error(`Failed to subscribe. Code is ${err.code}, message is ${err.message}`); | ||
| 716 | + } | ||
| 717 | + return; | ||
| 718 | + } | ||
| 719 | + | ||
| 720 | + if (err) { | ||
| 721 | + console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`); | ||
| 722 | + } else { | ||
| 723 | + console.error(`Failed to create subscriber: commonEventSubscriber is null or undefined`); | ||
| 724 | + } | ||
| 725 | + } | ||
| 726 | + ); | ||
| 727 | +} catch (error) { | ||
| 728 | + const err = error as BusinessError; | ||
| 729 | + console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`); | ||
| 730 | +} | ||
| 731 | + | ||
| 732 | +// Unsubscribe from the common event. | ||
| 733 | +setTimeout(() => { | ||
| 734 | + if (subscriber) { | ||
| 735 | + const currentSubscriber = subscriber as commonEventManager.CommonEventSubscriber; | ||
| 736 | + try { | ||
| 737 | + commonEventManager.unsubscribe( | ||
| 738 | + currentSubscriber, | ||
| 739 | + (err: BusinessError | null) => { | ||
| 740 | + if (err) { | ||
| 741 | + console.error(`Failed to unsubscribe. Code is ${err.code}, message is ${err.message}`); | ||
| 742 | + return; | ||
| 743 | + } | ||
| 744 | + subscriber = undefined; | ||
| 745 | + console.info(`Succeeded in unsubscribing.`); | ||
| 746 | + } | ||
| 747 | + ); | ||
| 748 | + } catch (error) { | ||
| 749 | + const err = error as BusinessError; | ||
| 750 | + console.error(`Failed to unsubscribe. Code is ${err.code}, message is ${err.message}`); | ||
| 751 | + } | ||
| 752 | + } else { | ||
| 753 | + console.warn("Cannot unsubscribe: subscriber is null or undefined"); | ||
| 754 | + } | ||
| 755 | +}, 500); | ||
| 756 | +``` | ||
| 757 | + | ||
| 441 | ## commonEventManager.subscribeToEvent<sup>20+</sup> | 758 | ## commonEventManager.subscribeToEvent<sup>20+</sup> |
| 442 | 759 | ||
| 443 | subscribeToEvent(subscriber: CommonEventSubscriber, callback: Callback\<CommonEventData>): Promise\<void> | 760 | subscribeToEvent(subscriber: CommonEventSubscriber, callback: Callback\<CommonEventData>): Promise\<void> |
| 444 | 761 | ||
| 445 | Subscribes to a common event. This API uses a promise to return the result, indicating subscription success or failure. | 762 | Subscribes to a common event. This API uses a promise to return the result, indicating subscription success or failure. |
| 446 | 763 | ||
| 447 | -**Atomic service API**: This API can be used in atomic services since API version 20. | 764 | +**Atomic service API** (ArkTS-Dyn only): This API can be used in atomic services since API version 20. |
| 448 | 765 | ||
| 449 | **System capability**: SystemCapability.Notification.CommonEvent | 766 | **System capability**: SystemCapability.Notification.CommonEvent |
| 450 | 767 | ||
| 768 | +**ArkTS-Dyn start version:** 20 | ||
| 769 | + | ||
| 770 | +**ArkTS-Sta start version:** 23 | ||
| 771 | + | ||
| 451 | **Parameters** | 772 | **Parameters** |
| 452 | 773 | ||
| 453 | | Name | Type | Mandatory| Description | | 774 | | Name | Type | Mandatory| Description | |
| @@ -456,6 +777,7 @@ Subscribes to a common event. This API uses a promise to return the result, indi | |||
| 456 | | callback | Callback\<[CommonEventData](./js-apis-inner-commonEvent-commonEventData.md)> | Yes | Callback to be invoked when a common event is subscribed to.| | 777 | | callback | Callback\<[CommonEventData](./js-apis-inner-commonEvent-commonEventData.md)> | Yes | Callback to be invoked when a common event is subscribed to.| |
| 457 | 778 | ||
| 458 | **Return value** | 779 | **Return value** |
| 780 | + | ||
| 459 | | Type | Description | | 781 | | Type | Description | |
| 460 | | --------------------------------------------------------- | ---------------- | | 782 | | --------------------------------------------------------- | ---------------- | |
| 461 | | Promise\<void> | Promise that returns no value.| | 783 | | Promise\<void> | Promise that returns no value.| |
| @@ -469,10 +791,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 469 | | 801 | Capability not supported. | | 791 | | 801 | Capability not supported. | |
| 470 | | 1500007 | Failed to send the message to the common event service. | | 792 | | 1500007 | Failed to send the message to the common event service. | |
| 471 | | 1500008 | Failed to initialize the common event service. | | 793 | | 1500008 | Failed to initialize the common event service. | |
| 472 | -| 1500010 | The count of subscriber exceed system specification. | | 794 | +| 1500010 | The count of subscriber exceeds system specification. | |
| 473 | 795 | ||
| 474 | **Example** | 796 | **Example** |
| 475 | 797 | ||
| 798 | +ArkTS-Dyn example: | ||
| 799 | + | ||
| 476 | ```ts | 800 | ```ts |
| 477 | import { BusinessError } from '@kit.BasicServicesKit'; | 801 | import { BusinessError } from '@kit.BasicServicesKit'; |
| 478 | 802 | ||
| @@ -513,16 +837,74 @@ try { | |||
| 513 | } | 837 | } |
| 514 | ``` | 838 | ``` |
| 515 | 839 | ||
| 840 | +ArkTS-Sta example: | ||
| 841 | + | ||
| 842 | +```ts | ||
| 843 | +import { BusinessError } from '@kit.BasicServicesKit'; | ||
| 844 | + | ||
| 845 | +// Define a subscriber. | ||
| 846 | +let subscriber: commonEventManager.CommonEventSubscriber | undefined | null = null; | ||
| 847 | +// Subscriber information. | ||
| 848 | +let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = { | ||
| 849 | + events: ["event"] | ||
| 850 | +}; | ||
| 851 | + | ||
| 852 | +// Create a subscriber. | ||
| 853 | +try { | ||
| 854 | + commonEventManager.createSubscriber( | ||
| 855 | + subscribeInfo, | ||
| 856 | + (err: BusinessError | null, commonEventSubscriber: commonEventManager.CommonEventSubscriber | undefined) => { | ||
| 857 | + if (err) { | ||
| 858 | + console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`); | ||
| 859 | + return; | ||
| 860 | + } | ||
| 861 | + | ||
| 862 | + // Ensure the subscriber object is valid. | ||
| 863 | + if (!commonEventSubscriber) { | ||
| 864 | + console.error(`Failed to create subscriber: subscriber is undefined`); | ||
| 865 | + return; | ||
| 866 | + } | ||
| 867 | + | ||
| 868 | + console.info(`Succeeded in creating subscriber.`); | ||
| 869 | + subscriber = commonEventSubscriber; | ||
| 870 | + | ||
| 871 | + // Use type assertions to ensure the type is correct. | ||
| 872 | + const validSubscriber = commonEventSubscriber as commonEventManager.CommonEventSubscriber; | ||
| 873 | + | ||
| 874 | + // Subscribe to a common event. | ||
| 875 | + commonEventManager.subscribeToEvent( | ||
| 876 | + validSubscriber, | ||
| 877 | + (data: commonEventManager.CommonEventData) => { | ||
| 878 | + console.info(`Succeeded to receive common event, data is ${JSON.stringify(data)}`); | ||
| 879 | + } | ||
| 880 | + ).then(() => { | ||
| 881 | + console.info(`Succeeded to subscribe.`); | ||
| 882 | + }).catch((err: Error) => { | ||
| 883 | + const businessErr = err as BusinessError; | ||
| 884 | + console.error(`Failed to subscribe. Code is ${businessErr.code}, message is ${businessErr.message}`); | ||
| 885 | + }); | ||
| 886 | + } | ||
| 887 | + ); | ||
| 888 | +} catch (error) { | ||
| 889 | + const err = error as BusinessError; | ||
| 890 | + console.error(`Failed to create subscriber. Code is ${err.code}, message is ${err.message}`); | ||
| 891 | +} | ||
| 892 | +``` | ||
| 893 | + | ||
| 516 | ## CommonEventData<sup>10+</sup> | 894 | ## CommonEventData<sup>10+</sup> |
| 517 | 895 | ||
| 518 | type CommonEventData = _CommonEventData | 896 | type CommonEventData = _CommonEventData |
| 519 | 897 | ||
| 520 | -Describes the data of a common event. | 898 | +Describes information about a common event. |
| 521 | 899 | ||
| 522 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 900 | +**Atomic service API** (ArkTS-Dyn only): This API can be used in atomic services since API version 11. |
| 523 | 901 | ||
| 524 | **System capability**: SystemCapability.Notification.CommonEvent | 902 | **System capability**: SystemCapability.Notification.CommonEvent |
| 525 | 903 | ||
| 904 | +**ArkTS-Dyn start version:** 10 | ||
| 905 | + | ||
| 906 | +**ArkTS-Sta start version:** 23 | ||
| 907 | + | ||
| 526 | | Type| Description| | 908 | | Type| Description| |
| 527 | | --- | --- | | 909 | | --- | --- | |
| 528 | | [_CommonEventData](js-apis-inner-commonEvent-commonEventData.md) | Data of a common event.| | 910 | | [_CommonEventData](js-apis-inner-commonEvent-commonEventData.md) | Data of a common event.| |
| @@ -533,10 +915,14 @@ type CommonEventSubscriber = _CommonEventSubscriber | |||
| 533 | 915 | ||
| 534 | Describes the subscriber of a common event. | 916 | Describes the subscriber of a common event. |
| 535 | 917 | ||
| 536 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 918 | +**Atomic service API** (ArkTS-Dyn only): This API can be used in atomic services since API version 11. |
| 537 | 919 | ||
| 538 | **System capability**: SystemCapability.Notification.CommonEvent | 920 | **System capability**: SystemCapability.Notification.CommonEvent |
| 539 | 921 | ||
| 922 | +**ArkTS-Dyn start version:** 10 | ||
| 923 | + | ||
| 924 | +**ArkTS-Sta start version:** 23 | ||
| 925 | + | ||
| 540 | | Type| Description| | 926 | | Type| Description| |
| 541 | | --- | --- | | 927 | | --- | --- | |
| 542 | | [_CommonEventSubscriber](js-apis-inner-commonEvent-commonEventSubscriber.md#commoneventsubscriber-1) | Subscriber of a common event.| | 928 | | [_CommonEventSubscriber](js-apis-inner-commonEvent-commonEventSubscriber.md#commoneventsubscriber-1) | Subscriber of a common event.| |
| @@ -545,12 +931,16 @@ Describes the subscriber of a common event. | |||
| 545 | 931 | ||
| 546 | type CommonEventSubscribeInfo = _CommonEventSubscribeInfo | 932 | type CommonEventSubscribeInfo = _CommonEventSubscribeInfo |
| 547 | 933 | ||
| 548 | -Describes the information about a subscriber. | 934 | +Describes information about a common event subscriber. |
| 549 | 935 | ||
| 550 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 936 | +**Atomic service API** (ArkTS-Dyn only): This API can be used in atomic services since API version 11. |
| 551 | 937 | ||
| 552 | **System capability**: SystemCapability.Notification.CommonEvent | 938 | **System capability**: SystemCapability.Notification.CommonEvent |
| 553 | 939 | ||
| 940 | +**ArkTS-Dyn start version:** 10 | ||
| 941 | + | ||
| 942 | +**ArkTS-Sta start version:** 23 | ||
| 943 | + | ||
| 554 | | Type| Description| | 944 | | Type| Description| |
| 555 | | --- | --- | | 945 | | --- | --- | |
| 556 | | [_CommonEventSubscribeInfo](js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | Information about a subscriber.| | 946 | | [_CommonEventSubscribeInfo](js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | Information about a subscriber.| |
| @@ -561,10 +951,14 @@ type CommonEventPublishData = _CommonEventPublishData | |||
| 561 | 951 | ||
| 562 | Describes the content and properties of a common event. | 952 | Describes the content and properties of a common event. |
| 563 | 953 | ||
| 564 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 954 | +**Atomic service API** (ArkTS-Dyn only): This API can be used in atomic services since API version 11. |
| 565 | 955 | ||
| 566 | **System capability**: SystemCapability.Notification.CommonEvent | 956 | **System capability**: SystemCapability.Notification.CommonEvent |
| 567 | 957 | ||
| 958 | +**ArkTS-Dyn start version:** 10 | ||
| 959 | + | ||
| 960 | +**ArkTS-Sta start version:** 23 | ||
| 961 | + | ||
| 568 | | Type| Description| | 962 | | Type| Description| |
| 569 | | --- | --- | | 963 | | --- | --- | |
| 570 | -| [_CommonEventPublishData](js-apis-inner-commonEvent-commonEventPublishData.md) | Content and properties of a common event.| | 964 | +| [_CommonEventPublishData](js-apis-inner-commonEvent-commonEventPublishData.md) | Content and properties of a common event.| |
| @@ -2,16 +2,34 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Basic Services Kit--> | 3 | <!--Kit: Basic Services Kit--> |
| 4 | <!--Subsystem: Notification--> | 4 | <!--Subsystem: Notification--> |
| 5 | -<!--Owner: @peixu--> | 5 | +<!--Owner: @HuYueRong--> |
| 6 | -<!--Designer: @dongqingran; @wulong158--> | 6 | +<!--Designer: @dongqingran--> |
| 7 | <!--Tester: @wanghong1997--> | 7 | <!--Tester: @wanghong1997--> |
| 8 | <!--Adviser: @fang-jinxu--> | 8 | <!--Adviser: @fang-jinxu--> |
| 9 | +<!-- md-trans-meta sourceCommit=5bb683c74e19ca9ef1c5d6c3f44e52bc89ca5ff4 translatedAt=2026-07-22T06:54:12.932Z pushedAt=2026-07-22T08:08:43.889Z --> | ||
| 9 | 10 | ||
| 10 | -The **Emitter** module provides the capabilities of sending and processing inter- or intra-thread events in a process. You can use the APIs of this module to subscribe to an event in persistent or one-shot manner, unsubscribe from an event, or emit an event to the event queue. | 11 | +This module provides APIs for sending and processing events between threads in a process or within a thread. You can use the APIs of this module to subscribe to events (continuous subscription or one-shot subscription), cancel event subscription, send events to the event queue, and query the number of subscribed events. In this way, event communication between different threads in the same process and within the same thread can be implemented. It is applicable to scenarios such as cross-thread communication, module decoupling, and the event-driven mode, helping developers implement a lightweight publish-subscribe pattern, reduce coupling between components, and improve code maintainability and scalability. |
| 12 | + | ||
| 13 | +Two event processing entries are provided. You can select one based on the isolation requirements: | ||
| 14 | + | ||
| 15 | +- **Namespace APIs** (**on**, **once**, **off**, **emit**, and **getListenerCount** in the **emitter** namespace): provide global event subscription and publishing capabilities within a process. This entry works based on the global event queue. Any thread in the same process can subscribe to and publish events. These APIs are suitable for cross-thread event communication. | ||
| 16 | + | ||
| 17 | +- **Instance APIs** (**Emitter** class): provide the event subscription and publishing capabilities within the same **Emitter** instance. Different **Emitter** instances are isolated from each other. You can create multiple independent event communication channels when events need to be isolated or grouped by instance. | ||
| 18 | + | ||
| 19 | +**APIs used in combination** | ||
| 20 | + | ||
| 21 | +The event communication of this module follows the calling sequence of subscription, publishing, processing, and unsubscription. For both namespace and instance APIs, you need to subscribe to an event first, and then another thread or the same thread publishes the event. The callback is executed after the event is received. When the event is no longer needed, unsubscribe from the event to release resources. In addition, event subscription has a lifecycle. Pay attention to resource management: | ||
| 22 | + | ||
| 23 | +- **Continuous subscription** (**on**): The subscription remains valid until **off** is called to cancel subscription. If the subscription is not canceled, it will be retained. | ||
| 24 | + | ||
| 25 | +- **One-shot subscription** (**once**): The subscription is automatically canceled after the event is received for the first time and the callback is executed. You do not need to manually call **off**. | ||
| 26 | + | ||
| 27 | +- **Time for unsubscription**: After the subscription is canceled by calling **off**, the events that have been published through **emit** but have not been executed are also canceled and no callback is triggered. Note that when canceling a specified callback, you need to pass the corresponding callback function. If no callback is specified, all subscriptions to the event are canceled. | ||
| 11 | 28 | ||
| 12 | > **NOTE** | 29 | > **NOTE** |
| 13 | > | 30 | > |
| 14 | -> 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. | 31 | +> - This module supports both ArkTS-Dyn and ArkTS-Sta. |
| 32 | +> - 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. | ||
| 15 | 33 | ||
| 16 | ## Modules to Import | 34 | ## Modules to Import |
| 17 | 35 | ||
| @@ -19,25 +37,35 @@ The **Emitter** module provides the capabilities of sending and processing inter | |||
| 19 | import { emitter } from '@kit.BasicServicesKit'; | 37 | import { emitter } from '@kit.BasicServicesKit'; |
| 20 | ``` | 38 | ``` |
| 21 | 39 | ||
| 40 | +## Permission List | ||
| 41 | + | ||
| 42 | +No permission is required. | ||
| 43 | + | ||
| 22 | ## emitter.on | 44 | ## emitter.on |
| 23 | 45 | ||
| 24 | on(event: InnerEvent, callback: Callback\<EventData\>): void | 46 | on(event: InnerEvent, callback: Callback\<EventData\>): void |
| 25 | 47 | ||
| 26 | Subscribes to an event in persistent manner and executes a callback after the event is received. | 48 | Subscribes to an event in persistent manner and executes a callback after the event is received. |
| 27 | 49 | ||
| 28 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 50 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 29 | 51 | ||
| 30 | **System capability**: SystemCapability.Notification.Emitter | 52 | **System capability**: SystemCapability.Notification.Emitter |
| 31 | 53 | ||
| 54 | +**ArkTS-Dyn start version:** 7 | ||
| 55 | + | ||
| 56 | +**ArkTS-Sta start version:** 23 | ||
| 57 | + | ||
| 32 | **Parameters** | 58 | **Parameters** |
| 33 | 59 | ||
| 34 | | Name | Type | Mandatory| Description | | 60 | | Name | Type | Mandatory| Description | |
| 35 | | -------- | ----------------------------------- | ---- | ------------------------------------------------------------ | | 61 | | -------- | ----------------------------------- | ---- | ------------------------------------------------------------ | |
| 36 | -| event | [InnerEvent](#innerevent) | Yes | Event to subscribe to in persistent manner. The [EventPriority](#eventpriority) parameter is not required and does not take effect.| | 62 | +| event | [InnerEvent](#innerevent) | Yes | Event to subscribe to in persistent manner. The [EventPriority](#eventpriority) parameter is not required and does not take effect. | |
| 37 | | callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to be invoked when the event is received. | | 63 | | callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to be invoked when the event is received. | |
| 38 | 64 | ||
| 39 | **Example** | 65 | **Example** |
| 40 | 66 | ||
| 67 | +ArkTS-Dyn example: | ||
| 68 | + | ||
| 41 | ```ts | 69 | ```ts |
| 42 | import { Callback } from '@kit.BasicServicesKit'; | 70 | import { Callback } from '@kit.BasicServicesKit'; |
| 43 | 71 | ||
| @@ -49,20 +77,43 @@ let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { | |||
| 49 | console.info(`eventData: ${JSON.stringify(eventData)}`); | 77 | console.info(`eventData: ${JSON.stringify(eventData)}`); |
| 50 | } | 78 | } |
| 51 | 79 | ||
| 80 | +// Execute the callback after receiving the event whose ID is 1. | ||
| 81 | +emitter.on(innerEvent, callback); | ||
| 82 | +``` | ||
| 83 | + | ||
| 84 | +ArkTS-Sta example: | ||
| 85 | + | ||
| 86 | +```ts | ||
| 87 | +import { Callback } from '@kit.BasicServicesKit'; | ||
| 88 | + | ||
| 89 | +let innerEvent: emitter.InnerEvent = { | ||
| 90 | + eventId: 1 | ||
| 91 | +}; | ||
| 92 | + | ||
| 93 | +let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { | ||
| 94 | + console.info(`eventData: ${JSON.stringify(eventData?.data)}`); | ||
| 95 | +} | ||
| 96 | + | ||
| 52 | // Execute the callback after receiving the event whose eventId is 1. | 97 | // Execute the callback after receiving the event whose eventId is 1. |
| 53 | emitter.on(innerEvent, callback); | 98 | emitter.on(innerEvent, callback); |
| 54 | ``` | 99 | ``` |
| 55 | 100 | ||
| 56 | ## emitter.on<sup>11+</sup> | 101 | ## emitter.on<sup>11+</sup> |
| 57 | 102 | ||
| 58 | -on(eventId: string, callback: Callback\<EventData\>): void | 103 | +on(eventId: string, callback: Callback\<EventData\>): void |
| 59 | 104 | ||
| 60 | Subscribes to an event in persistent manner and executes a callback after the event is received. | 105 | Subscribes to an event in persistent manner and executes a callback after the event is received. |
| 61 | 106 | ||
| 62 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 107 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 63 | 108 | ||
| 64 | **System capability**: SystemCapability.Notification.Emitter | 109 | **System capability**: SystemCapability.Notification.Emitter |
| 65 | 110 | ||
| 111 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 112 | + | ||
| 113 | +**Related API**: The corresponding ArkTS-Sta API is [onEventData](#emitteroneventdata23) | ||
| 114 | + | ||
| 115 | +**ArkTS-Dyn start version:** 11 | ||
| 116 | + | ||
| 66 | **Parameters** | 117 | **Parameters** |
| 67 | 118 | ||
| 68 | | Name | Type | Mandatory| Description | | 119 | | Name | Type | Mandatory| Description | |
| @@ -82,21 +133,61 @@ let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { | |||
| 82 | emitter.on(`eventId`, callback); | 133 | emitter.on(`eventId`, callback); |
| 83 | ``` | 134 | ``` |
| 84 | 135 | ||
| 85 | -## emitter.on<sup>12+</sup> | 136 | +## emitter.onEventData<sup>23+</sup> |
| 86 | 137 | ||
| 87 | -on<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void | 138 | +onEventData(eventId: string, callback: Callback\<EventData\>): void |
| 88 | 139 | ||
| 89 | Subscribes to an event in persistent manner and executes a callback after the event is received. | 140 | Subscribes to an event in persistent manner and executes a callback after the event is received. |
| 90 | 141 | ||
| 91 | -**Atomic service API**: This API can be used in atomic services since API version 12. | ||
| 92 | - | ||
| 93 | **System capability**: SystemCapability.Notification.Emitter | 142 | **System capability**: SystemCapability.Notification.Emitter |
| 94 | 143 | ||
| 144 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 145 | + | ||
| 146 | +**Related API**: The corresponding ArkTS-Dyn API is [on](#emitteron11) | ||
| 147 | + | ||
| 148 | +**ArkTS-Sta start version:** 23 | ||
| 149 | + | ||
| 95 | **Parameters** | 150 | **Parameters** |
| 96 | 151 | ||
| 97 | | Name | Type | Mandatory| Description | | 152 | | Name | Type | Mandatory| Description | |
| 98 | | -------- | ----------------------------------- | ---- | -------------------------------------- | | 153 | | -------- | ----------------------------------- | ---- | -------------------------------------- | |
| 99 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 154 | +| eventId | string | Yes | ID of the event subscribed to in persistent manner.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated.| |
| 155 | +| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to be invoked when the event is received. | | ||
| 156 | + | ||
| 157 | +**Example** | ||
| 158 | + | ||
| 159 | +```ts | ||
| 160 | +import { Callback } from '@kit.BasicServicesKit'; | ||
| 161 | + | ||
| 162 | +let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { | ||
| 163 | + console.info(`eventData: ${JSON.stringify(eventData)}`); | ||
| 164 | +} | ||
| 165 | + | ||
| 166 | +// Execute the callback after receiving the event whose ID is eventId. | ||
| 167 | +emitter.onEventData(`eventId`, callback); | ||
| 168 | +``` | ||
| 169 | + | ||
| 170 | +## emitter.on<sup>12+</sup> | ||
| 171 | + | ||
| 172 | +on<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void | ||
| 173 | + | ||
| 174 | +Subscribes to an event in persistent manner and executes a callback after the event is received. | ||
| 175 | + | ||
| 176 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 12. | ||
| 177 | + | ||
| 178 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 179 | + | ||
| 180 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 181 | + | ||
| 182 | +**Related API**: The corresponding ArkTS-Sta API is [onGenericEventData](#emitterongenericeventdata23) | ||
| 183 | + | ||
| 184 | +**ArkTS-Dyn start version:** 12 | ||
| 185 | + | ||
| 186 | +**Parameters** | ||
| 187 | + | ||
| 188 | +| Name | Type | Mandatory| Description | | ||
| 189 | +| -------- | ----------------------------------- | ---- | -------------------------------------- | | ||
| 190 | +| eventId | string | Yes | ID of the event subscribed to in persistent manner.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | | ||
| 100 | | callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to be invoked when the event is received.| | 191 | | callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to be invoked when the event is received.| |
| 101 | 192 | ||
| 102 | **Example** | 193 | **Example** |
| @@ -125,16 +216,66 @@ let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.G | |||
| 125 | emitter.on("eventId", callback); | 216 | emitter.on("eventId", callback); |
| 126 | ``` | 217 | ``` |
| 127 | 218 | ||
| 219 | +## emitter.onGenericEventData<sup>23+</sup> | ||
| 220 | + | ||
| 221 | +onGenericEventData<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void | ||
| 222 | + | ||
| 223 | +Subscribes to an event in persistent manner and executes a callback after the event is received. | ||
| 224 | + | ||
| 225 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 226 | + | ||
| 227 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 228 | + | ||
| 229 | +**Related API**: The corresponding ArkTS-Dyn API is [on](#emitteron12) | ||
| 230 | + | ||
| 231 | +**ArkTS-Sta start version:** 23 | ||
| 232 | + | ||
| 233 | +**Parameters** | ||
| 234 | + | ||
| 235 | +| Name | Type | Mandatory| Description | | ||
| 236 | +| -------- | ----------------------------------- | ---- | -------------------------------------- | | ||
| 237 | +| eventId | string | Yes | ID of the event subscribed to in persistent manner.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated.| | ||
| 238 | +| callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to be invoked when the event is received. | | ||
| 239 | + | ||
| 240 | +**Example** | ||
| 241 | + | ||
| 242 | +```ts | ||
| 243 | +import { Callback } from '@kit.BasicServicesKit'; | ||
| 244 | + | ||
| 245 | +class Sample { | ||
| 246 | + constructor() { | ||
| 247 | + this.count = 100; | ||
| 248 | + } | ||
| 249 | + printCount() { | ||
| 250 | + console.info('Print count : ' + this.count); | ||
| 251 | + } | ||
| 252 | + count: number; | ||
| 253 | +} | ||
| 254 | + | ||
| 255 | +let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.GenericEventData<Sample>): void => { | ||
| 256 | + console.info(`eventData: ${JSON.stringify(eventData?.data)}`); | ||
| 257 | + let storage: Sample = eventData.data! as Sample; | ||
| 258 | + storage.printCount(); | ||
| 259 | +} | ||
| 260 | + | ||
| 261 | +// Execute the callback after receiving the event whose ID is eventId. | ||
| 262 | +emitter.onGenericEventData("eventId", callback); | ||
| 263 | +``` | ||
| 264 | + | ||
| 128 | ## emitter.once | 265 | ## emitter.once |
| 129 | 266 | ||
| 130 | once(event: InnerEvent, callback: Callback\<EventData\>): void | 267 | once(event: InnerEvent, callback: Callback\<EventData\>): void |
| 131 | 268 | ||
| 132 | Subscribes to an event in one-shot manner and unsubscribes from it after the event callback is executed. | 269 | Subscribes to an event in one-shot manner and unsubscribes from it after the event callback is executed. |
| 133 | 270 | ||
| 134 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 271 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 135 | 272 | ||
| 136 | **System capability**: SystemCapability.Notification.Emitter | 273 | **System capability**: SystemCapability.Notification.Emitter |
| 137 | 274 | ||
| 275 | +**ArkTS-Dyn start version:** 7 | ||
| 276 | + | ||
| 277 | +**ArkTS-Sta start version:** 23 | ||
| 278 | + | ||
| 138 | **Parameters** | 279 | **Parameters** |
| 139 | 280 | ||
| 140 | | Name | Type | Mandatory| Description | | 281 | | Name | Type | Mandatory| Description | |
| @@ -144,6 +285,8 @@ Subscribes to an event in one-shot manner and unsubscribes from it after the eve | |||
| 144 | 285 | ||
| 145 | **Example** | 286 | **Example** |
| 146 | 287 | ||
| 288 | +ArkTS-Dyn example: | ||
| 289 | + | ||
| 147 | ```ts | 290 | ```ts |
| 148 | import { Callback } from '@kit.BasicServicesKit'; | 291 | import { Callback } from '@kit.BasicServicesKit'; |
| 149 | 292 | ||
| @@ -158,21 +301,43 @@ let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { | |||
| 158 | emitter.once(innerEvent, callback); | 301 | emitter.once(innerEvent, callback); |
| 159 | ``` | 302 | ``` |
| 160 | 303 | ||
| 304 | +ArkTS-Sta example: | ||
| 305 | + | ||
| 306 | +```ts | ||
| 307 | +import { Callback } from '@kit.BasicServicesKit'; | ||
| 308 | + | ||
| 309 | +let innerEvent: emitter.InnerEvent = { | ||
| 310 | + eventId: 1 | ||
| 311 | +}; | ||
| 312 | + | ||
| 313 | +let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { | ||
| 314 | + console.info(`eventData: ${JSON.stringify(eventData?.data)}`); | ||
| 315 | +} | ||
| 316 | +// Execute the callback after receiving the event whose ID is 1. | ||
| 317 | +emitter.once(innerEvent, callback); | ||
| 318 | +``` | ||
| 319 | + | ||
| 161 | ## emitter.once<sup>11+</sup> | 320 | ## emitter.once<sup>11+</sup> |
| 162 | 321 | ||
| 163 | once(eventId: string, callback: Callback\<EventData\>): void | 322 | once(eventId: string, callback: Callback\<EventData\>): void |
| 164 | 323 | ||
| 165 | Subscribes to an event in one-shot manner and unsubscribes from it after the event callback is executed. | 324 | Subscribes to an event in one-shot manner and unsubscribes from it after the event callback is executed. |
| 166 | 325 | ||
| 167 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 326 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 168 | 327 | ||
| 169 | **System capability**: SystemCapability.Notification.Emitter | 328 | **System capability**: SystemCapability.Notification.Emitter |
| 170 | 329 | ||
| 330 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 331 | + | ||
| 332 | +**Related API**: The corresponding ArkTS-Sta API is [onceEventData](#emitteronceeventdata23) | ||
| 333 | + | ||
| 334 | +**ArkTS-Dyn start version:** 11 | ||
| 335 | + | ||
| 171 | **Parameters** | 336 | **Parameters** |
| 172 | 337 | ||
| 173 | | Name | Type | Mandatory| Description | | 338 | | Name | Type | Mandatory| Description | |
| 174 | | -------- | ----------------------------------- | ---- | -------------------------------------- | | 339 | | -------- | ----------------------------------- | ---- | -------------------------------------- | |
| 175 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 340 | +| eventId | string | Yes | ID of the event subscribed to in one-shot manner.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 176 | | callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to be invoked when the event is received.| | 341 | | callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to be invoked when the event is received.| |
| 177 | 342 | ||
| 178 | **Example** | 343 | **Example** |
| @@ -187,21 +352,60 @@ let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { | |||
| 187 | emitter.once("eventId", callback); | 352 | emitter.once("eventId", callback); |
| 188 | ``` | 353 | ``` |
| 189 | 354 | ||
| 355 | +## emitter.onceEventData<sup>23+</sup> | ||
| 356 | + | ||
| 357 | +onceEventData(eventId: string, callback: Callback\<EventData\>): void | ||
| 358 | + | ||
| 359 | +Subscribes to an event in one-shot manner and unsubscribes from it after the event callback is executed. | ||
| 360 | + | ||
| 361 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 362 | + | ||
| 363 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 364 | + | ||
| 365 | +**Related API**: The corresponding ArkTS-Dyn API is [once](#emitteronce11) | ||
| 366 | + | ||
| 367 | +**ArkTS-Sta start version:** 23 | ||
| 368 | + | ||
| 369 | +**Parameters** | ||
| 370 | + | ||
| 371 | +| Name | Type | Mandatory| Description | | ||
| 372 | +| -------- | ----------------------------------- | ---- | -------------------------------------- | | ||
| 373 | +| eventId | string | Yes | ID of the event subscribed to in one-shot manner.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated.| | ||
| 374 | +| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to be invoked when the event is received. | | ||
| 375 | + | ||
| 376 | +**Example** | ||
| 377 | + | ||
| 378 | +```ts | ||
| 379 | +import { Callback } from '@kit.BasicServicesKit'; | ||
| 380 | + | ||
| 381 | +let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { | ||
| 382 | + console.info(`eventData: ${JSON.stringify(eventData?.data)}`); | ||
| 383 | +} | ||
| 384 | +// Execute the callback after receiving the event whose ID is eventId. | ||
| 385 | +emitter.onceEventData("eventId", callback); | ||
| 386 | +``` | ||
| 387 | + | ||
| 190 | ## emitter.once<sup>12+</sup> | 388 | ## emitter.once<sup>12+</sup> |
| 191 | 389 | ||
| 192 | once<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void | 390 | once<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void |
| 193 | 391 | ||
| 194 | Subscribes to an event in one-shot manner and unsubscribes from it after the event callback is executed. | 392 | Subscribes to an event in one-shot manner and unsubscribes from it after the event callback is executed. |
| 195 | 393 | ||
| 196 | -**Atomic service API**: This API can be used in atomic services since API version 12. | 394 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 12. |
| 197 | 395 | ||
| 198 | **System capability**: SystemCapability.Notification.Emitter | 396 | **System capability**: SystemCapability.Notification.Emitter |
| 199 | 397 | ||
| 398 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 399 | + | ||
| 400 | +**Related API**: The corresponding ArkTS-Sta API is [onceGenericEventData](#emitteroncegenericeventdata23) | ||
| 401 | + | ||
| 402 | +**ArkTS-Dyn start version:** 12 | ||
| 403 | + | ||
| 200 | **Parameters** | 404 | **Parameters** |
| 201 | 405 | ||
| 202 | | Name | Type | Mandatory| Description | | 406 | | Name | Type | Mandatory| Description | |
| 203 | | -------- | ----------------------------------- | ---- | -------------------------------------- | | 407 | | -------- | ----------------------------------- | ---- | -------------------------------------- | |
| 204 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 408 | +| eventId | string | Yes | ID of the event subscribed to in one-shot manner.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 205 | | callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to be invoked when the event is received.| | 409 | | callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to be invoked when the event is received.| |
| 206 | 410 | ||
| 207 | **Example** | 411 | **Example** |
| @@ -230,28 +434,80 @@ let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.G | |||
| 230 | emitter.once("eventId", callback); | 434 | emitter.once("eventId", callback); |
| 231 | ``` | 435 | ``` |
| 232 | 436 | ||
| 437 | +## emitter.onceGenericEventData<sup>23+</sup> | ||
| 438 | + | ||
| 439 | +onceGenericEventData<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void | ||
| 440 | + | ||
| 441 | +Subscribes to an event in one-shot manner and unsubscribes from it after the event callback is executed. | ||
| 442 | + | ||
| 443 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 444 | + | ||
| 445 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 446 | + | ||
| 447 | +**Related API**: The corresponding ArkTS-Dyn API is [once](#emitteronce12) | ||
| 448 | + | ||
| 449 | +**ArkTS-Sta start version:** 23 | ||
| 450 | + | ||
| 451 | +**Parameters** | ||
| 452 | + | ||
| 453 | +| Name | Type | Mandatory| Description | | ||
| 454 | +| -------- | ----------------------------------- | ---- | -------------------------------------- | | ||
| 455 | +| eventId | string | Yes | ID of the event subscribed to in one-shot manner.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated.| | ||
| 456 | +| callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to be invoked when the event is received. | | ||
| 457 | + | ||
| 458 | +**Example** | ||
| 459 | + | ||
| 460 | +```ts | ||
| 461 | +import { Callback } from '@kit.BasicServicesKit'; | ||
| 462 | + | ||
| 463 | +class Sample { | ||
| 464 | + constructor() { | ||
| 465 | + this.count = 100; | ||
| 466 | + } | ||
| 467 | + printCount() { | ||
| 468 | + console.info('Print count : ' + this.count); | ||
| 469 | + } | ||
| 470 | + count: number; | ||
| 471 | +} | ||
| 472 | + | ||
| 473 | +let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.GenericEventData<Sample>): void => { | ||
| 474 | + console.info(`eventData: ${JSON.stringify(eventData?.data)}`); | ||
| 475 | + let storage: Sample = eventData.data! as Sample; | ||
| 476 | + storage.printCount(); | ||
| 477 | +} | ||
| 478 | + | ||
| 479 | +// Execute the callback after receiving the event whose ID is eventId. | ||
| 480 | +emitter.onceGenericEventData("eventId", callback); | ||
| 481 | +``` | ||
| 482 | + | ||
| 233 | ## emitter.off | 483 | ## emitter.off |
| 234 | 484 | ||
| 235 | -off(eventId: number): void | 485 | +ArkTS-Dyn: off(eventId: number): void |
| 486 | + | ||
| 487 | +ArkTS-Sta: off(eventId: long): void | ||
| 236 | 488 | ||
| 237 | Unsubscribes from all events with the specified event ID. | 489 | Unsubscribes from all events with the specified event ID. |
| 238 | 490 | ||
| 239 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emitteremit) API but has not been executed will be unsubscribed. | 491 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emitteremit) API but has not been executed will be unsubscribed. |
| 240 | 492 | ||
| 241 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 493 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 242 | 494 | ||
| 243 | **System capability**: SystemCapability.Notification.Emitter | 495 | **System capability**: SystemCapability.Notification.Emitter |
| 244 | 496 | ||
| 497 | +**ArkTS-Dyn start version:** 7 | ||
| 498 | + | ||
| 499 | +**ArkTS-Sta start version:** 23 | ||
| 500 | + | ||
| 245 | **Parameters** | 501 | **Parameters** |
| 246 | 502 | ||
| 247 | | Name | Type | Mandatory| Description | | 503 | | Name | Type | Mandatory| Description | |
| 248 | | ------- | ------ | ---- | -------- | | 504 | | ------- | ------ | ---- | -------- | |
| 249 | -| eventId | number | Yes | Event ID.| | 505 | +| eventId | ArkTS-Dyn: number<br/>ArkTS-Sta: long | Yes | Event ID, which is defined by the developer to identify the event. | |
| 250 | 506 | ||
| 251 | **Example** | 507 | **Example** |
| 252 | 508 | ||
| 253 | ```ts | 509 | ```ts |
| 254 | -// Unregister the callbacks of all events whose eventID is 1. | 510 | +// Unregister the callbacks of all events whose ID is 1. |
| 255 | emitter.off(1); | 511 | emitter.off(1); |
| 256 | ``` | 512 | ``` |
| 257 | 513 | ||
| @@ -263,55 +519,80 @@ Unsubscribes from all events with the specified event ID. | |||
| 263 | 519 | ||
| 264 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emitteremit11) API but has not been executed will be unsubscribed. | 520 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emitteremit11) API but has not been executed will be unsubscribed. |
| 265 | 521 | ||
| 266 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 522 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 267 | 523 | ||
| 268 | **System capability**: SystemCapability.Notification.Emitter | 524 | **System capability**: SystemCapability.Notification.Emitter |
| 269 | 525 | ||
| 526 | +**ArkTS-Dyn start version:** 11 | ||
| 527 | + | ||
| 528 | +**ArkTS-Sta start version:** 23 | ||
| 529 | + | ||
| 270 | **Parameters** | 530 | **Parameters** |
| 271 | 531 | ||
| 272 | | Name | Type | Mandatory| Description | | 532 | | Name | Type | Mandatory| Description | |
| 273 | | ------- | ------ | ---- | -------- | | 533 | | ------- | ------ | ---- | -------- | |
| 274 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty.| | 534 | +| eventId | string | Yes | Event ID.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 275 | 535 | ||
| 276 | **Example** | 536 | **Example** |
| 277 | 537 | ||
| 278 | ```ts | 538 | ```ts |
| 279 | -// Unregister the callbacks of all events whose event ID is eventId. | 539 | +// Unregister the callbacks of all events whose ID is eventId1. |
| 280 | -emitter.off("eventId"); | 540 | +emitter.off('eventId1'); |
| 281 | ``` | 541 | ``` |
| 282 | 542 | ||
| 283 | ## emitter.off<sup>10+</sup> | 543 | ## emitter.off<sup>10+</sup> |
| 284 | 544 | ||
| 285 | -off(eventId: number, callback: Callback\<EventData\>): void | 545 | +ArkTS-Dyn: off(eventId: number, callback: Callback\<EventData\>): void |
| 286 | 546 | ||
| 287 | -Unsubscribes from an event with the specified event ID and processed by the specified callback. This API takes effect only when **Callback\<EventData>** has been registered through the [on](#emitteron) or [once](#emitteronce) API. Otherwise, no processing is performed. | 547 | +ArkTS-Sta: off(eventId: long, callback: Callback\<EventData\>): void |
| 548 | + | ||
| 549 | +Unsubscribes from an event with the specified event ID and processed by the specified callback. This API takes effect only when **Callback\<EventData>** has been registered through the [on](#emitteron) or [once](#emitteronce) API. | ||
| 288 | 550 | ||
| 289 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emitteremit) API but has not been executed will be unsubscribed. | 551 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emitteremit) API but has not been executed will be unsubscribed. |
| 290 | 552 | ||
| 291 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 553 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 292 | 554 | ||
| 293 | **System capability**: SystemCapability.Notification.Emitter | 555 | **System capability**: SystemCapability.Notification.Emitter |
| 294 | 556 | ||
| 557 | +**ArkTS-Dyn start version:** 10 | ||
| 558 | + | ||
| 559 | +**ArkTS-Sta start version:** 23 | ||
| 560 | + | ||
| 295 | **Parameters** | 561 | **Parameters** |
| 296 | 562 | ||
| 297 | | Name | Type | Mandatory| Description | | 563 | | Name | Type | Mandatory| Description | |
| 298 | | ------- | ------ | ---- | ------ | | 564 | | ------- | ------ | ---- | ------ | |
| 299 | -| eventId | number | Yes | Event ID.| | 565 | +| eventId | ArkTS-Dyn: number<br/>ArkTS-Sta: long | Yes | Event ID, which is defined by the developer to identify the event. | |
| 300 | -| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to unregister. | | 566 | +| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to unregister, which must be the same as the callback used during registration. | |
| 301 | 567 | ||
| 302 | **Example** | 568 | **Example** |
| 303 | 569 | ||
| 570 | +ArkTS-Dyn example: | ||
| 571 | + | ||
| 304 | ```ts | 572 | ```ts |
| 305 | import { Callback } from '@kit.BasicServicesKit'; | 573 | import { Callback } from '@kit.BasicServicesKit'; |
| 306 | 574 | ||
| 307 | let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { | 575 | let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { |
| 308 | console.info(`eventData: ${JSON.stringify(eventData)}`); | 576 | console.info(`eventData: ${JSON.stringify(eventData)}`); |
| 309 | } | 577 | } |
| 310 | -// Unregister the callback of the event whose eventID is 1. The callback object must be the registered object. | 578 | +// Cancel the callback handler for the event with eventId 1. The callback object must be the same as the one used for subscription. |
| 311 | // If the callback has not been registered, no processing is performed. | 579 | // If the callback has not been registered, no processing is performed. |
| 312 | emitter.off(1, callback); | 580 | emitter.off(1, callback); |
| 313 | ``` | 581 | ``` |
| 314 | 582 | ||
| 583 | +ArkTS-Sta example: | ||
| 584 | + | ||
| 585 | +```ts | ||
| 586 | +import { Callback } from '@kit.BasicServicesKit'; | ||
| 587 | + | ||
| 588 | +let callback: Callback<emitter.EventData> = (eventData: emitter.EventData | undefined | null) => { | ||
| 589 | + console.info(`eventData: ${JSON.stringify(eventData?.data)}`); | ||
| 590 | +} | ||
| 591 | +// Unregister the callbacks for events whose ID is 1. The callback object must be the object used during registration. | ||
| 592 | +// If the callback handler has not been subscribed, no processing is performed. | ||
| 593 | +emitter.off(1, callback); | ||
| 594 | +``` | ||
| 595 | + | ||
| 315 | ## emitter.off<sup>11+</sup> | 596 | ## emitter.off<sup>11+</sup> |
| 316 | 597 | ||
| 317 | off(eventId: string, callback: Callback\<EventData\>): void | 598 | off(eventId: string, callback: Callback\<EventData\>): void |
| @@ -320,16 +601,22 @@ Unsubscribes from an event with the specified event ID and processed by the spec | |||
| 320 | 601 | ||
| 321 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emitteremit11) API but has not been executed will be unsubscribed. | 602 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emitteremit11) API but has not been executed will be unsubscribed. |
| 322 | 603 | ||
| 323 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 604 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 324 | 605 | ||
| 325 | **System capability**: SystemCapability.Notification.Emitter | 606 | **System capability**: SystemCapability.Notification.Emitter |
| 326 | 607 | ||
| 608 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 609 | + | ||
| 610 | +**Related API**: The corresponding ArkTS-Sta API is [offEventData](#emitteroffeventdata23) | ||
| 611 | + | ||
| 612 | +**ArkTS-Dyn start version:** 11 | ||
| 613 | + | ||
| 327 | **Parameters** | 614 | **Parameters** |
| 328 | 615 | ||
| 329 | | Name | Type | Mandatory| Description | | 616 | | Name | Type | Mandatory| Description | |
| 330 | | -------- | ----------------------------------- | ---- | -------------------------- | | 617 | | -------- | ----------------------------------- | ---- | -------------------------- | |
| 331 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 618 | +| eventId | string | Yes | Event ID.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 332 | -| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to unregister.| | 619 | +| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to unregister, which must be the same as the callback used during registration. | |
| 333 | 620 | ||
| 334 | **Example** | 621 | **Example** |
| 335 | 622 | ||
| @@ -339,28 +626,71 @@ import { Callback } from '@kit.BasicServicesKit'; | |||
| 339 | let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { | 626 | let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { |
| 340 | console.info(`eventData: ${JSON.stringify(eventData)}`); | 627 | console.info(`eventData: ${JSON.stringify(eventData)}`); |
| 341 | } | 628 | } |
| 342 | -// Unregister the callback of the event whose event ID is eventId. The callback object must be the registered object. | 629 | +// Unregister the callbacks for events whose ID is eventId1. The callback object must be the object used during registration. |
| 343 | // If the callback has not been registered, no processing is performed. | 630 | // If the callback has not been registered, no processing is performed. |
| 344 | -emitter.off("eventId", callback); | 631 | +emitter.off('eventId1', callback); |
| 632 | +``` | ||
| 633 | + | ||
| 634 | +## emitter.offEventData<sup>23+</sup> | ||
| 635 | + | ||
| 636 | +offEventData(eventId: string, callback: Callback\<EventData\>): void | ||
| 637 | + | ||
| 638 | +Unsubscribes from the event with the specified event ID and processed by the specified callback. This API takes effect only when the callback has been registered through the [onEventData](#emitteroneventdata23) or [onceEventData](#emitteronceeventdata23) API. This API uses an asynchronous callback to return the result. | ||
| 639 | + | ||
| 640 | +After this API is used to unsubscribe from an event, the event that has been published through the [emitter.emit<sup>23+</sup>](#emitteremit23-1) API but has not been executed will be unsubscribed from. | ||
| 641 | + | ||
| 642 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 643 | + | ||
| 644 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 645 | + | ||
| 646 | +**Related API**: The corresponding ArkTS-Dyn API is [off](#emitteroff11-1) | ||
| 647 | + | ||
| 648 | +**ArkTS-Sta start version:** 23 | ||
| 649 | + | ||
| 650 | +**Parameters** | ||
| 651 | + | ||
| 652 | +| Name | Type | Mandatory| Description | | ||
| 653 | +| -------- | ----------------------------------- | ---- | -------------------------- | | ||
| 654 | +| eventId | string | Yes | Event ID.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated.| | ||
| 655 | +| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to unregister, which must be the same as the callback used during registration. | | ||
| 656 | + | ||
| 657 | +**Example** | ||
| 658 | + | ||
| 659 | +```ts | ||
| 660 | +import { Callback } from '@kit.BasicServicesKit'; | ||
| 661 | + | ||
| 662 | +let callback: Callback<emitter.EventData> = (eventData: emitter.EventData | undefined | null) => { | ||
| 663 | + console.info(`eventData: ${JSON.stringify(eventData)}`); | ||
| 664 | +} | ||
| 665 | + | ||
| 666 | +// Unregister the callbacks for events whose ID is eventId. The callback object must be the object used during registration. | ||
| 667 | +// If the callback handler has not been subscribed, no processing is performed. | ||
| 668 | +emitter.offEventData("eventId", callback); | ||
| 345 | ``` | 669 | ``` |
| 346 | 670 | ||
| 347 | ## emitter.off<sup>12+</sup> | 671 | ## emitter.off<sup>12+</sup> |
| 348 | 672 | ||
| 349 | off<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void | 673 | off<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void |
| 350 | 674 | ||
| 351 | -Unsubscribes from an event with the specified event ID and processed by the specified callback. This API takes effect only when **Callback\<EventData>** has been registered through the [on](#emitteron12) or [once](#emitteronce12) API. Otherwise, no processing is performed. | 675 | +Unsubscribes from an event with the specified event ID and processed by the specified callback. This API takes effect only when **Callback\<EventData>** has been registered through the [on](#emitteron12) or [once](#emitteronce12) API. |
| 352 | 676 | ||
| 353 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emitteremit12) API but has not been executed will be unsubscribed. | 677 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emitteremit12) API but has not been executed will be unsubscribed. |
| 354 | 678 | ||
| 355 | -**Atomic service API**: This API can be used in atomic services since API version 12. | 679 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 12. |
| 356 | 680 | ||
| 357 | **System capability**: SystemCapability.Notification.Emitter | 681 | **System capability**: SystemCapability.Notification.Emitter |
| 358 | 682 | ||
| 683 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 684 | + | ||
| 685 | +**Related API**: The corresponding ArkTS-Sta API is [offGenericEventData](#emitteroffgenericeventdata23) | ||
| 686 | + | ||
| 687 | +**ArkTS-Dyn start version:** 12 | ||
| 688 | + | ||
| 359 | **Parameters** | 689 | **Parameters** |
| 360 | 690 | ||
| 361 | | Name | Type | Mandatory| Description | | 691 | | Name | Type | Mandatory| Description | |
| 362 | | -------- | ----------------------------------- | ---- | -------------------------- | | 692 | | -------- | ----------------------------------- | ---- | -------------------------- | |
| 363 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 693 | +| eventId | string | Yes | Event ID.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 364 | | callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to unregister.| | 694 | | callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to unregister.| |
| 365 | 695 | ||
| 366 | **Example** | 696 | **Example** |
| @@ -385,9 +715,57 @@ let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.G | |||
| 385 | eventData?.data?.printCount(); | 715 | eventData?.data?.printCount(); |
| 386 | } | 716 | } |
| 387 | } | 717 | } |
| 388 | -// Unregister the callback of the event whose event ID is eventId. The callback object must be the registered object. | 718 | +// Unregister the callbacks for events whose ID is eventId1. The callback object must be the object used during registration. |
| 389 | // If the callback has not been registered, no processing is performed. | 719 | // If the callback has not been registered, no processing is performed. |
| 390 | -emitter.off("eventId", callback); | 720 | +emitter.off('eventId1', callback); |
| 721 | +``` | ||
| 722 | + | ||
| 723 | +## emitter.offGenericEventData<sup>23+</sup> | ||
| 724 | + | ||
| 725 | +offGenericEventData<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void | ||
| 726 | + | ||
| 727 | +Unsubscribes from the event with the specified event ID and processed by the specified callback. This API takes effect only when the callback has been registered through the [onGenericEventData](#emitterongenericeventdata23) or [onceGenericEventData](#emitteroncegenericeventdata23) API. | ||
| 728 | + | ||
| 729 | +After this API is used to unsubscribe from an event, the event that has been published through the [emit<T\>(eventId: string, data: GenericEventData<T\>)](#emitteremit23-2) API but has not been executed will be unsubscribed. | ||
| 730 | + | ||
| 731 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 732 | + | ||
| 733 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 734 | + | ||
| 735 | +**Related API**: The corresponding ArkTS-Dyn API is [off](#emitteroff12) | ||
| 736 | + | ||
| 737 | +**ArkTS-Sta start version:** 23 | ||
| 738 | + | ||
| 739 | +**Parameters** | ||
| 740 | + | ||
| 741 | +| Name | Type | Mandatory| Description | | ||
| 742 | +| -------- | ----------------------------------- | ---- | -------------------------- | | ||
| 743 | +| eventId | string | Yes | Event ID.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | | ||
| 744 | +| callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to unregister. | | ||
| 745 | + | ||
| 746 | +**Example** | ||
| 747 | + | ||
| 748 | +```ts | ||
| 749 | +import { Callback } from '@kit.BasicServicesKit'; | ||
| 750 | + | ||
| 751 | +class Sample { | ||
| 752 | + constructor() { | ||
| 753 | + this.count = 100; | ||
| 754 | + } | ||
| 755 | + printCount() { | ||
| 756 | + console.info('Print count : ' + this.count); | ||
| 757 | + } | ||
| 758 | + count: number; | ||
| 759 | +} | ||
| 760 | + | ||
| 761 | +let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.GenericEventData<Sample>): void => { | ||
| 762 | + console.info(`eventData: ${JSON.stringify(eventData?.data)}`); | ||
| 763 | + let storage: Sample = eventData.data! as Sample; | ||
| 764 | + storage.printCount(); | ||
| 765 | +} | ||
| 766 | +// Unregister the callbacks for events whose ID is eventId. The callback object must be the object used during registration. | ||
| 767 | +// If the callback handler has not been subscribed, no processing is performed. | ||
| 768 | +emitter.offGenericEventData("eventId", callback); | ||
| 391 | ``` | 769 | ``` |
| 392 | 770 | ||
| 393 | ## emitter.emit | 771 | ## emitter.emit |
| @@ -400,10 +778,14 @@ This API can be used to emit data objects across threads. The data objects must | |||
| 400 | 778 | ||
| 401 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. | 779 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. |
| 402 | 780 | ||
| 403 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 781 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 404 | 782 | ||
| 405 | **System capability**: SystemCapability.Notification.Emitter | 783 | **System capability**: SystemCapability.Notification.Emitter |
| 406 | 784 | ||
| 785 | +**ArkTS-Dyn start version:** 7 | ||
| 786 | + | ||
| 787 | +**ArkTS-Sta start version:** 23 | ||
| 788 | + | ||
| 407 | **Parameters** | 789 | **Parameters** |
| 408 | 790 | ||
| 409 | | Name| Type | Mandatory| Description | | 791 | | Name| Type | Mandatory| Description | |
| @@ -413,6 +795,8 @@ After an event is published using this API, the event may not be executed immedi | |||
| 413 | 795 | ||
| 414 | **Example** | 796 | **Example** |
| 415 | 797 | ||
| 798 | +ArkTS-Dyn example: | ||
| 799 | + | ||
| 416 | ```ts | 800 | ```ts |
| 417 | let eventData: emitter.EventData = { | 801 | let eventData: emitter.EventData = { |
| 418 | data: { | 802 | data: { |
| @@ -429,6 +813,28 @@ let innerEvent: emitter.InnerEvent = { | |||
| 429 | emitter.emit(innerEvent, eventData); | 813 | emitter.emit(innerEvent, eventData); |
| 430 | ``` | 814 | ``` |
| 431 | 815 | ||
| 816 | +ArkTS-Sta example: | ||
| 817 | + | ||
| 818 | +```ts | ||
| 819 | +import { RecordData } from '@ohos.base'; | ||
| 820 | + | ||
| 821 | +let record: Record<string, RecordData> = { | ||
| 822 | + "content": "content", | ||
| 823 | + "id": 1, | ||
| 824 | +}; | ||
| 825 | + | ||
| 826 | +let eventData: emitter.EventData = { | ||
| 827 | + data: record // The types are now compatible. | ||
| 828 | +}; | ||
| 829 | + | ||
| 830 | +let innerEvent: emitter.InnerEvent = { | ||
| 831 | + eventId: 1, | ||
| 832 | + priority: emitter.EventPriority.HIGH | ||
| 833 | +}; | ||
| 834 | + | ||
| 835 | +emitter.emit(innerEvent, eventData); | ||
| 836 | +``` | ||
| 837 | + | ||
| 432 | ## emitter.emit<sup>11+</sup> | 838 | ## emitter.emit<sup>11+</sup> |
| 433 | 839 | ||
| 434 | emit(eventId: string, data?: EventData): void | 840 | emit(eventId: string, data?: EventData): void |
| @@ -439,15 +845,21 @@ This API can be used to emit data objects across threads. The data objects must | |||
| 439 | 845 | ||
| 440 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. | 846 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. |
| 441 | 847 | ||
| 442 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 848 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 443 | 849 | ||
| 444 | **System capability**: SystemCapability.Notification.Emitter | 850 | **System capability**: SystemCapability.Notification.Emitter |
| 445 | 851 | ||
| 852 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 853 | + | ||
| 854 | +**Related API**: The corresponding ArkTS-Sta APIs are [emitter.emit<sup>23+</sup>](#emitteremit23) and [emitter.emit<sup>23+</sup>](#emitteremit23-1) | ||
| 855 | + | ||
| 856 | +**ArkTS-Dyn start version:** 11 | ||
| 857 | + | ||
| 446 | **Parameters** | 858 | **Parameters** |
| 447 | 859 | ||
| 448 | | Name | Type | Mandatory| Description | | 860 | | Name | Type | Mandatory| Description | |
| 449 | | ------- | ----------------------- | ---- | ---------------- | | 861 | | ------- | ----------------------- | ---- | ---------------- | |
| 450 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 862 | +| eventId | string | Yes | Event ID.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 451 | | data | [EventData](#eventdata) | No | Data carried by the event. This parameter is left empty by default.| | 863 | | data | [EventData](#eventdata) | No | Data carried by the event. This parameter is left empty by default.| |
| 452 | 864 | ||
| 453 | **Example** | 865 | **Example** |
| @@ -463,6 +875,79 @@ let eventData: emitter.EventData = { | |||
| 463 | emitter.emit("eventId", eventData); | 875 | emitter.emit("eventId", eventData); |
| 464 | ``` | 876 | ``` |
| 465 | 877 | ||
| 878 | +## emitter.emit<sup>23+</sup> | ||
| 879 | + | ||
| 880 | +emit(eventId: string): void | ||
| 881 | + | ||
| 882 | +Emits a specified event. | ||
| 883 | + | ||
| 884 | +After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. | ||
| 885 | + | ||
| 886 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 23. | ||
| 887 | + | ||
| 888 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 889 | + | ||
| 890 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 891 | + | ||
| 892 | +**Related API**: The corresponding ArkTS-Dyn APIs are [emit(eventId: string, data?: EventData)](#emitteremit11) or [emit<T\>(eventId: string, data?: GenericEventData<T\>)](#emitteremit12) | ||
| 893 | + | ||
| 894 | +**ArkTS-Sta start version:** 23 | ||
| 895 | + | ||
| 896 | +**Parameters** | ||
| 897 | + | ||
| 898 | +| Name | Type | Mandatory| Description | | ||
| 899 | +| ------- | ----------------------- | ---- | ---------------- | | ||
| 900 | +| eventId | string | Yes | ID of the event to be emitted.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated.| | ||
| 901 | + | ||
| 902 | +**Example** | ||
| 903 | + | ||
| 904 | +```ts | ||
| 905 | +emitter.emit("eventId"); | ||
| 906 | +``` | ||
| 907 | + | ||
| 908 | +## emitter.emit<sup>23+</sup> | ||
| 909 | + | ||
| 910 | +emit(eventId: string, data: EventData): void | ||
| 911 | + | ||
| 912 | +Emits a specified event. | ||
| 913 | + | ||
| 914 | +After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. | ||
| 915 | + | ||
| 916 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 23. | ||
| 917 | + | ||
| 918 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 919 | + | ||
| 920 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 921 | + | ||
| 922 | +**Related API**: The corresponding ArkTS-Dyn API is [emit](#emitteremit11) | ||
| 923 | + | ||
| 924 | +**ArkTS-Sta start version:** 23 | ||
| 925 | + | ||
| 926 | +**Parameters** | ||
| 927 | + | ||
| 928 | +| Name | Type | Mandatory| Description | | ||
| 929 | +| ------- | ----------------------- | ---- | ---------------- | | ||
| 930 | +| eventId | string | Yes | ID of the event to be emitted.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated.| | ||
| 931 | +| data | [EventData](#eventdata) | Yes | Data carried by the event.| | ||
| 932 | + | ||
| 933 | +**Example** | ||
| 934 | + | ||
| 935 | +```ts | ||
| 936 | +import { RecordData } from '@ohos.base'; | ||
| 937 | + | ||
| 938 | +let record: Record<string, RecordData> = { | ||
| 939 | + "content": "content", | ||
| 940 | + "id": 1, | ||
| 941 | +}; | ||
| 942 | + | ||
| 943 | +let eventData: emitter.EventData = { | ||
| 944 | + data: record // The types are now compatible. | ||
| 945 | +}; | ||
| 946 | + | ||
| 947 | +emitter.emit("eventId", eventData); | ||
| 948 | + | ||
| 949 | +``` | ||
| 950 | + | ||
| 466 | ## emitter.emit<sup>12+</sup> | 951 | ## emitter.emit<sup>12+</sup> |
| 467 | 952 | ||
| 468 | emit<T\>(eventId: string, data?: GenericEventData<T\>): void | 953 | emit<T\>(eventId: string, data?: GenericEventData<T\>): void |
| @@ -473,15 +958,21 @@ This API can be used to emit data objects across threads. The data objects must | |||
| 473 | 958 | ||
| 474 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. | 959 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. |
| 475 | 960 | ||
| 476 | -**Atomic service API**: This API can be used in atomic services since API version 12. | 961 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 12. |
| 477 | 962 | ||
| 478 | **System capability**: SystemCapability.Notification.Emitter | 963 | **System capability**: SystemCapability.Notification.Emitter |
| 479 | 964 | ||
| 965 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 966 | + | ||
| 967 | +**Related API**: The corresponding ArkTS-Sta APIs are [emit<T\>(eventId: string, data: GenericEventData<T\>)](#emitteremit23-2) and [emit(eventId: string)](#emitteremit23) | ||
| 968 | + | ||
| 969 | +**ArkTS-Dyn start version:** 12 | ||
| 970 | + | ||
| 480 | **Parameters** | 971 | **Parameters** |
| 481 | 972 | ||
| 482 | | Name | Type | Mandatory| Description | | 973 | | Name | Type | Mandatory| Description | |
| 483 | | ------- | ----------------------- | ---- | ---------------- | | 974 | | ------- | ----------------------- | ---- | ---------------- | |
| 484 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 975 | +| eventId | string | Yes | ID of the event to be emitted.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 485 | | data | [GenericEventData<T\>](#genericeventdatat12) | No | Data carried by the event. This parameter is left empty by default.| | 976 | | data | [GenericEventData<T\>](#genericeventdatat12) | No | Data carried by the event. This parameter is left empty by default.| |
| 486 | 977 | ||
| 487 | **Example** | 978 | **Example** |
| @@ -504,6 +995,52 @@ let eventData: emitter.GenericEventData<Sample> = { | |||
| 504 | emitter.emit("eventId", eventData); | 995 | emitter.emit("eventId", eventData); |
| 505 | ``` | 996 | ``` |
| 506 | 997 | ||
| 998 | +## emitter.emit<sup>23+</sup> | ||
| 999 | + | ||
| 1000 | +emit<T\>(eventId: string, data: GenericEventData<T\>): void | ||
| 1001 | + | ||
| 1002 | +Emits a specified event. | ||
| 1003 | + | ||
| 1004 | +After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. | ||
| 1005 | + | ||
| 1006 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 23. | ||
| 1007 | + | ||
| 1008 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 1009 | + | ||
| 1010 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 1011 | + | ||
| 1012 | +**Related API**: The corresponding ArkTS-Dyn API is [emit](#emitteremit12) | ||
| 1013 | + | ||
| 1014 | +**ArkTS-Sta start version:** 23 | ||
| 1015 | + | ||
| 1016 | +**Parameters** | ||
| 1017 | + | ||
| 1018 | +| Name | Type | Mandatory| Description | | ||
| 1019 | +| ------- | ----------------------- | ---- | ---------------- | | ||
| 1020 | +| eventId | string | Yes | ID of the event to be emitted.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated.| | ||
| 1021 | +| data | [GenericEventData<T\>](#genericeventdatat12) | Yes | Data carried by the event.| | ||
| 1022 | + | ||
| 1023 | +**Example** | ||
| 1024 | +ArkTS-Sta example: | ||
| 1025 | + | ||
| 1026 | +```ts | ||
| 1027 | + | ||
| 1028 | +class Sample { | ||
| 1029 | + constructor() { | ||
| 1030 | + this.count = 100; | ||
| 1031 | + } | ||
| 1032 | + printCount() { | ||
| 1033 | + console.info('Print count : ' + this.count); | ||
| 1034 | + } | ||
| 1035 | + count: number; | ||
| 1036 | +} | ||
| 1037 | + | ||
| 1038 | +let eventData: emitter.GenericEventData<Sample> = { | ||
| 1039 | + data: new Sample() | ||
| 1040 | +}; | ||
| 1041 | +emitter.emit("eventId", eventData); | ||
| 1042 | +``` | ||
| 1043 | + | ||
| 507 | ## emitter.emit<sup>11+</sup> | 1044 | ## emitter.emit<sup>11+</sup> |
| 508 | 1045 | ||
| 509 | emit(eventId: string, options: Options, data?: EventData): void | 1046 | emit(eventId: string, options: Options, data?: EventData): void |
| @@ -514,20 +1051,28 @@ This API can be used to emit data objects across threads. The data objects must | |||
| 514 | 1051 | ||
| 515 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. | 1052 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. |
| 516 | 1053 | ||
| 517 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 1054 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 518 | 1055 | ||
| 519 | **System capability**: SystemCapability.Notification.Emitter | 1056 | **System capability**: SystemCapability.Notification.Emitter |
| 520 | 1057 | ||
| 1058 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 1059 | + | ||
| 1060 | +**Related API**: The corresponding ArkTS-Sta APIs are [emit(eventId: string, options: Options)](#emitteremit23-3) and [emit(eventId: string, options: Options, data: EventData)](#emitteremit23-4) | ||
| 1061 | + | ||
| 1062 | +**ArkTS-Dyn start version:** 11 | ||
| 1063 | + | ||
| 521 | **Parameters** | 1064 | **Parameters** |
| 522 | 1065 | ||
| 523 | | Name | Type | Mandatory| Description | | 1066 | | Name | Type | Mandatory| Description | |
| 524 | | ------- | ----------------------- | ---- | ---------------- | | 1067 | | ------- | ----------------------- | ---- | ---------------- | |
| 525 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 1068 | +| eventId | string | Yes | ID of the event to be emitted.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 526 | | options | [Options](#options11) | Yes | Event emit priority. | | 1069 | | options | [Options](#options11) | Yes | Event emit priority. | |
| 527 | | data | [EventData](#eventdata) | No | Data carried by the event. This parameter is left empty by default.| | 1070 | | data | [EventData](#eventdata) | No | Data carried by the event. This parameter is left empty by default.| |
| 528 | 1071 | ||
| 529 | **Example** | 1072 | **Example** |
| 530 | 1073 | ||
| 1074 | +ArkTS-Dyn example: | ||
| 1075 | + | ||
| 531 | ```ts | 1076 | ```ts |
| 532 | let eventData: emitter.EventData = { | 1077 | let eventData: emitter.EventData = { |
| 533 | data: { | 1078 | data: { |
| @@ -543,9 +1088,91 @@ let options: emitter.Options = { | |||
| 543 | emitter.emit("eventId", options, eventData); | 1088 | emitter.emit("eventId", options, eventData); |
| 544 | ``` | 1089 | ``` |
| 545 | 1090 | ||
| 1091 | +## emitter.emit<sup>23+</sup> | ||
| 1092 | + | ||
| 1093 | +emit(eventId: string, options: Options): void | ||
| 1094 | + | ||
| 1095 | +Emits an event of a specified priority. | ||
| 1096 | + | ||
| 1097 | +After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. | ||
| 1098 | + | ||
| 1099 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 23. | ||
| 1100 | + | ||
| 1101 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 1102 | + | ||
| 1103 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 1104 | + | ||
| 1105 | +**Related API**: The corresponding ArkTS-Dyn API is [emit](#emitteremit11-1) | ||
| 1106 | + | ||
| 1107 | +**ArkTS-Sta start version:** 23 | ||
| 1108 | + | ||
| 1109 | +**Parameters** | ||
| 1110 | + | ||
| 1111 | +| Name | Type | Mandatory| Description | | ||
| 1112 | +| ------- | ----------------------- | ---- | ---------------- | | ||
| 1113 | +| eventId | string | Yes | ID of the event to be emitted.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | | ||
| 1114 | +| options | [Options](#options11) | Yes | Event priority. | | ||
| 1115 | + | ||
| 1116 | +**Example** | ||
| 1117 | + | ||
| 1118 | +```ts | ||
| 1119 | +let options: emitter.Options = { | ||
| 1120 | + priority: emitter.EventPriority.HIGH | ||
| 1121 | +}; | ||
| 1122 | + | ||
| 1123 | +emitter.emit("eventId", options); | ||
| 1124 | +``` | ||
| 1125 | + | ||
| 1126 | +## emitter.emit<sup>23+</sup> | ||
| 1127 | + | ||
| 1128 | +emit(eventId: string, options: Options, data: EventData): void | ||
| 1129 | + | ||
| 1130 | +Emits an event of a specified priority. | ||
| 1131 | + | ||
| 1132 | +After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. | ||
| 1133 | + | ||
| 1134 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 23. | ||
| 1135 | + | ||
| 1136 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 1137 | + | ||
| 1138 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 1139 | + | ||
| 1140 | +**Related API**: The corresponding ArkTS-Dyn API is [emit](#emitteremit11-1) | ||
| 1141 | + | ||
| 1142 | +**ArkTS-Sta start version:** 23 | ||
| 1143 | + | ||
| 1144 | +**Parameters** | ||
| 1145 | + | ||
| 1146 | +| Name | Type | Mandatory| Description | | ||
| 1147 | +| ------- | ----------------------- | ---- | ---------------- | | ||
| 1148 | +| eventId | string | Yes | ID of the event to be emitted.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | | ||
| 1149 | +| options | [Options](#options11) | Yes | Event priority. | | ||
| 1150 | +| data | [EventData](#eventdata) | Yes | Data carried by the event. | | ||
| 1151 | + | ||
| 1152 | +**Example** | ||
| 1153 | + | ||
| 1154 | +```ts | ||
| 1155 | +let record: Record<string, RecordData> = { | ||
| 1156 | + "content": "content", | ||
| 1157 | + "id": 1, | ||
| 1158 | +}; | ||
| 1159 | + | ||
| 1160 | +let eventData: emitter.EventData = { | ||
| 1161 | + data: record // The types are now compatible. | ||
| 1162 | +}; | ||
| 1163 | + | ||
| 1164 | +let options: emitter.Options = { | ||
| 1165 | + priority: emitter.EventPriority.HIGH | ||
| 1166 | +}; | ||
| 1167 | + | ||
| 1168 | +emitter.emit("eventId", options, eventData); | ||
| 1169 | +``` | ||
| 1170 | + | ||
| 546 | ## emitter.emit<sup>12+</sup> | 1171 | ## emitter.emit<sup>12+</sup> |
| 547 | 1172 | ||
| 548 | -emit<T\>(eventId: string, options: Options, data?: GenericEventData<T\>): void | 1173 | +ArkTS-Dyn: emit<T\>(eventId: string, options: Options, data?: GenericEventData<T\>): void |
| 1174 | + | ||
| 1175 | +ArkTS-Sta: emit<T\>(eventId: string, options: Options, data: GenericEventData<T\>): void | ||
| 549 | 1176 | ||
| 550 | Emits an event of a specified priority. | 1177 | Emits an event of a specified priority. |
| 551 | 1178 | ||
| @@ -553,20 +1180,26 @@ This API can be used to emit data objects across threads. The data objects must | |||
| 553 | 1180 | ||
| 554 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. | 1181 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. |
| 555 | 1182 | ||
| 556 | -**Atomic service API**: This API can be used in atomic services since API version 12. | 1183 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 12. |
| 557 | 1184 | ||
| 558 | **System capability**: SystemCapability.Notification.Emitter | 1185 | **System capability**: SystemCapability.Notification.Emitter |
| 559 | 1186 | ||
| 1187 | +**ArkTS-Dyn start version:** 12 | ||
| 1188 | + | ||
| 1189 | +**ArkTS-Sta start version:** 23 | ||
| 1190 | + | ||
| 560 | **Parameters** | 1191 | **Parameters** |
| 561 | 1192 | ||
| 562 | | Name | Type | Mandatory| Description | | 1193 | | Name | Type | Mandatory| Description | |
| 563 | | ------- | ----------------------- | ---- | ---------------- | | 1194 | | ------- | ----------------------- | ---- | ---------------- | |
| 564 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 1195 | +| eventId | string | Yes | ID of the event to be emitted.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 565 | | options | [Options](#options11) | Yes | Event emit priority. | | 1196 | | options | [Options](#options11) | Yes | Event emit priority. | |
| 566 | -| data | [GenericEventData<T\>](#genericeventdatat12) | No | Data carried by the event. This parameter is left empty by default.| | 1197 | +| data | [GenericEventData<T\>](#genericeventdatat12) | ArkTS-Dyn: No<br/>ArkTS-Sta: Yes | Data carried by the event. The default value is empty. | |
| 567 | 1198 | ||
| 568 | **Example** | 1199 | **Example** |
| 569 | 1200 | ||
| 1201 | +ArkTS-Dyn example: | ||
| 1202 | + | ||
| 570 | ```ts | 1203 | ```ts |
| 571 | @Sendable | 1204 | @Sendable |
| 572 | class Sample { | 1205 | class Sample { |
| @@ -589,83 +1222,136 @@ let eventData: emitter.GenericEventData<Sample> = { | |||
| 589 | emitter.emit("eventId", options, eventData); | 1222 | emitter.emit("eventId", options, eventData); |
| 590 | ``` | 1223 | ``` |
| 591 | 1224 | ||
| 1225 | +ArkTS-Sta example: | ||
| 1226 | + | ||
| 1227 | +```ts | ||
| 1228 | + | ||
| 1229 | +class Sample { | ||
| 1230 | + constructor() { | ||
| 1231 | + this.count = 100; | ||
| 1232 | + } | ||
| 1233 | + printCount() { | ||
| 1234 | + console.info('Print count : ' + this.count); | ||
| 1235 | + } | ||
| 1236 | + count: number; | ||
| 1237 | +} | ||
| 1238 | + | ||
| 1239 | +let options: emitter.Options = { | ||
| 1240 | + priority: emitter.EventPriority.HIGH | ||
| 1241 | +}; | ||
| 1242 | +let eventData: emitter.GenericEventData<Sample> = { | ||
| 1243 | + data: new Sample() | ||
| 1244 | +}; | ||
| 1245 | + | ||
| 1246 | +emitter.emit("eventId", options, eventData); | ||
| 1247 | +``` | ||
| 1248 | + | ||
| 592 | ## emitter.getListenerCount<sup>11+</sup> | 1249 | ## emitter.getListenerCount<sup>11+</sup> |
| 593 | 1250 | ||
| 594 | -getListenerCount(eventId: number | string): number | 1251 | +ArkTS-Dyn: getListenerCount(eventId: number | string): number |
| 1252 | + | ||
| 1253 | +ArkTS-Sta: getListenerCount(eventId: long | string): long | ||
| 595 | 1254 | ||
| 596 | Obtains the number of subscriptions to a specified event. | 1255 | Obtains the number of subscriptions to a specified event. |
| 597 | 1256 | ||
| 598 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 1257 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 599 | 1258 | ||
| 600 | **System capability**: SystemCapability.Notification.Emitter | 1259 | **System capability**: SystemCapability.Notification.Emitter |
| 601 | 1260 | ||
| 1261 | +**ArkTS-Dyn start version:** 11 | ||
| 1262 | + | ||
| 1263 | +**ArkTS-Sta start version:** 23 | ||
| 1264 | + | ||
| 602 | **Parameters** | 1265 | **Parameters** |
| 603 | 1266 | ||
| 604 | | Name | Type | Mandatory| Description | | 1267 | | Name | Type | Mandatory| Description | |
| 605 | | ------- | -------------- | ---- | -------- | | 1268 | | ------- | -------------- | ---- | -------- | |
| 606 | -| eventId | number \| string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty.| | 1269 | +| eventId | ArkTS-Dyn: number\| string<br/>ArkTS-Sta: long \| string | Yes | Event ID, which is defined by the developer to identify events.<br>For the string type, the value must not be empty or exceed 10,240 bytes. The excess content will be truncated. | |
| 607 | 1270 | ||
| 608 | **Returns** | 1271 | **Returns** |
| 609 | 1272 | ||
| 610 | | Type | Description | | 1273 | | Type | Description | |
| 611 | | ------- |------------| | 1274 | | ------- |------------| |
| 612 | -| number | Number of subscriptions to a specified event.| | 1275 | +| ArkTS-Dyn: number<br/>ArkTS-Sta: long | Number of subscriptions to a specified event. | |
| 613 | - | ||
| 614 | 1276 | ||
| 615 | **Example** | 1277 | **Example** |
| 616 | 1278 | ||
| 1279 | +ArkTS-Dyn example: | ||
| 1280 | + | ||
| 617 | ```ts | 1281 | ```ts |
| 618 | let count: number = emitter.getListenerCount("eventId"); | 1282 | let count: number = emitter.getListenerCount("eventId"); |
| 619 | ``` | 1283 | ``` |
| 620 | 1284 | ||
| 1285 | +ArkTS-Sta example: | ||
| 1286 | + | ||
| 1287 | +```ts | ||
| 1288 | +let count: long = emitter.getListenerCount("eventId"); | ||
| 1289 | +``` | ||
| 1290 | + | ||
| 621 | ## EventPriority | 1291 | ## EventPriority |
| 622 | 1292 | ||
| 623 | Enumerates the event priorities. | 1293 | Enumerates the event priorities. |
| 624 | 1294 | ||
| 625 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 1295 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 626 | 1296 | ||
| 627 | **System capability**: SystemCapability.Notification.Emitter | 1297 | **System capability**: SystemCapability.Notification.Emitter |
| 628 | 1298 | ||
| 1299 | +**ArkTS-Dyn start version:** 7 | ||
| 1300 | + | ||
| 1301 | +**ArkTS-Sta start version:** 23 | ||
| 1302 | + | ||
| 629 | | Name | Value | Description | | 1303 | | Name | Value | Description | |
| 630 | | --------- | ---- | --------------------------------------------------- | | 1304 | | --------- | ---- | --------------------------------------------------- | |
| 631 | | IMMEDIATE | 0 | The event will be emitted before high-priority events. | | 1305 | | IMMEDIATE | 0 | The event will be emitted before high-priority events. | |
| 632 | | HIGH | 1 | The event will be emitted before low-priority events. | | 1306 | | HIGH | 1 | The event will be emitted before low-priority events. | |
| 633 | -| LOW | 2 | The event will be emitted before idle-priority events. By default, an event is in LOW priority. | | 1307 | +| LOW | 2 | The event will be emitted before idle-priority events. By default, an event is in LOW priority. | |
| 634 | | IDLE | 3 | The event will be emitted after all the other events. | | 1308 | | IDLE | 3 | The event will be emitted after all the other events. | |
| 635 | 1309 | ||
| 636 | ## InnerEvent | 1310 | ## InnerEvent |
| 637 | 1311 | ||
| 638 | Describes an event to subscribe to or emit. The **EventPriority** settings do not take effect under event subscription. | 1312 | Describes an event to subscribe to or emit. The **EventPriority** settings do not take effect under event subscription. |
| 639 | 1313 | ||
| 640 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 1314 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 641 | 1315 | ||
| 642 | **System capability**: SystemCapability.Notification.Emitter | 1316 | **System capability**: SystemCapability.Notification.Emitter |
| 643 | 1317 | ||
| 1318 | +**ArkTS-Dyn start version:** 7 | ||
| 1319 | + | ||
| 1320 | +**ArkTS-Sta start version:** 23 | ||
| 1321 | + | ||
| 644 | | Name | Type | Read Only| Optional| Description | | 1322 | | Name | Type | Read Only| Optional| Description | |
| 645 | | -------- | ------------------------------- | ---- | ---- | ------------------------------ | | 1323 | | -------- | ------------------------------- | ---- | ---- | ------------------------------ | |
| 646 | -| eventId | number | No | No | Event ID.| | 1324 | +| eventId | ArkTS-Dyn: number<br/>ArkTS-Sta: long | No | No | Event ID, which is defined by the developer to identify events. | |
| 647 | | priority | [EventPriority](#eventpriority) | No | Yes | Event priority. The default value is **EventPriority.LOW**. | | 1325 | | priority | [EventPriority](#eventpriority) | No | Yes | Event priority. The default value is **EventPriority.LOW**. | |
| 648 | 1326 | ||
| 649 | ## EventData | 1327 | ## EventData |
| 650 | 1328 | ||
| 651 | Describes the data carried by the emitted event. | 1329 | Describes the data carried by the emitted event. |
| 652 | 1330 | ||
| 653 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 1331 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 654 | 1332 | ||
| 655 | **System capability**: SystemCapability.Notification.Emitter | 1333 | **System capability**: SystemCapability.Notification.Emitter |
| 656 | 1334 | ||
| 1335 | +**ArkTS-Dyn start version:** 7 | ||
| 1336 | + | ||
| 1337 | +**ArkTS-Sta start version:** 23 | ||
| 1338 | + | ||
| 657 | | Name| Type | Read Only| Optional| Description | | 1339 | | Name| Type | Read Only| Optional| Description | |
| 658 | | ---- | ------------------ | ---- | ---- | -------------- | | 1340 | | ---- | ------------------ | ---- | ---- | -------------- | |
| 659 | -| data | { [key: string]: any } | No | Yes | Data carried by the emitted event. The value can be in any of the following types: Array, ArrayBuffer, Boolean, DataView, Date, Error, Map, Number, Object, Primitive (except symbol), RegExp, Set, String, and TypedArray. The maximum data size is 16 MB.| | 1341 | +| data | ArkTS-Dyn: { [key: string]: any }<br/>ArkTS-Sta: Record<string, RecordData> \| ESValue | No | Yes | Data carried by the emitted event. The value can be in any of the following types: Array, ArrayBuffer, Boolean, DataView, Date, Error, Map, Number, Object, Primitive (except symbol), RegExp, Set, String, and TypedArray. The maximum data size is 16 MB. If the data size exceeds the limit, the event fails to be emitted. | |
| 660 | 1342 | ||
| 661 | ## Options<sup>11+</sup> | 1343 | ## Options<sup>11+</sup> |
| 662 | 1344 | ||
| 663 | Describes the event emit priority. | 1345 | Describes the event emit priority. |
| 664 | 1346 | ||
| 665 | -**Atomic service API**: This API can be used in atomic services since API version 12. | 1347 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 12. |
| 666 | 1348 | ||
| 667 | **System capability**: SystemCapability.Notification.Emitter | 1349 | **System capability**: SystemCapability.Notification.Emitter |
| 668 | 1350 | ||
| 1351 | +**ArkTS-Dyn start version:** 11 | ||
| 1352 | + | ||
| 1353 | +**ArkTS-Sta start version:** 23 | ||
| 1354 | + | ||
| 669 | | Name | Type | Read Only| Optional| Description | | 1355 | | Name | Type | Read Only| Optional| Description | |
| 670 | | -------- | ------------------------------- | ---- | ---- | -------------- | | 1356 | | -------- | ------------------------------- | ---- | ---- | -------------- | |
| 671 | | priority | [EventPriority](#eventpriority) | No | Yes | Event priority. The default value is **EventPriority.LOW**.| | 1357 | | priority | [EventPriority](#eventpriority) | No | Yes | Event priority. The default value is **EventPriority.LOW**.| |
| @@ -674,55 +1360,71 @@ Describes the event emit priority. | |||
| 674 | 1360 | ||
| 675 | Describes the generic data carried by the emitted event. | 1361 | Describes the generic data carried by the emitted event. |
| 676 | 1362 | ||
| 677 | -**Atomic service API**: This API can be used in atomic services since API version 12. | 1363 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 12. |
| 678 | 1364 | ||
| 679 | **System capability**: SystemCapability.Notification.Emitter | 1365 | **System capability**: SystemCapability.Notification.Emitter |
| 680 | 1366 | ||
| 1367 | +**ArkTS-Dyn start version:** 12 | ||
| 1368 | + | ||
| 1369 | +**ArkTS-Sta start version:** 23 | ||
| 1370 | + | ||
| 681 | | Name | Type | Read Only| Optional| Description | | 1371 | | Name | Type | Read Only| Optional| Description | |
| 682 | | -------- | ------------------------------- | ---- | ---- | -------------- | | 1372 | | -------- | ------------------------------- | ---- | ---- | -------------- | |
| 683 | -| data | T | No | Yes | Data carried by the emitted event. **T**: generic type.| | 1373 | +| data | ArkTS-Dyn: T <br/>ArkTS-Sta: T \| ESValue | No | Yes | Data carried by the emitted event. **T** represents a generic type. | |
| 684 | - | ||
| 685 | 1374 | ||
| 686 | ## Emitter<sup>22+</sup> | 1375 | ## Emitter<sup>22+</sup> |
| 687 | 1376 | ||
| 688 | -This module provides the capabilities of sending and processing inter- or intra-thread events in a process of the same Emitter instance. You can use the following APIs to subscribe to an event in persistent or one-shot manner, unsubscribe from an event, or emit an event to the event queue. | 1377 | +This module provides the capabilities of sending and processing inter- or intra-thread events in a process of the same **Emitter** instance. You can use the following APIs to subscribe to an event in persistent or one-shot manner, cancel the subscription, or emit an event to the event queue. This module is applicable when inter-thread communication and event management are required based on independent instances. Different **Emitter** instances are isolated from each other. |
| 689 | 1378 | ||
| 690 | -**Atomic service API**: This API can be used in atomic services since API version 22. | 1379 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. |
| 691 | 1380 | ||
| 692 | **System capability**: SystemCapability.Notification.Emitter | 1381 | **System capability**: SystemCapability.Notification.Emitter |
| 693 | 1382 | ||
| 1383 | +**ArkTS-Dyn start version:** 22 | ||
| 1384 | + | ||
| 1385 | +**ArkTS-Sta start version:** 23 | ||
| 1386 | + | ||
| 694 | ### constructor<sup>22+</sup> | 1387 | ### constructor<sup>22+</sup> |
| 695 | 1388 | ||
| 696 | constructor() | 1389 | constructor() |
| 697 | 1390 | ||
| 698 | Defines a constructor. | 1391 | Defines a constructor. |
| 699 | 1392 | ||
| 700 | -**Atomic service API**: This API can be used in atomic services since API version 22. | 1393 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. |
| 701 | 1394 | ||
| 702 | **System capability**: SystemCapability.Notification.Emitter | 1395 | **System capability**: SystemCapability.Notification.Emitter |
| 703 | 1396 | ||
| 1397 | +**ArkTS-Dyn start version:** 22 | ||
| 1398 | + | ||
| 1399 | +**ArkTS-Sta start version:** 23 | ||
| 1400 | + | ||
| 704 | **Example** | 1401 | **Example** |
| 705 | 1402 | ||
| 706 | - | ||
| 707 | ```ts | 1403 | ```ts |
| 708 | -let emitter1: emitter.Emitter = new emitter.Emitter(); | 1404 | +let emitter1 = new emitter.Emitter(); |
| 709 | ``` | 1405 | ``` |
| 710 | 1406 | ||
| 711 | ### on<sup>22+</sup> | 1407 | ### on<sup>22+</sup> |
| 712 | 1408 | ||
| 713 | -on(eventId: string, callback: Callback\<EventData\>): void | 1409 | +on(eventId: string, callback: Callback\<EventData\>): void |
| 714 | 1410 | ||
| 715 | -Subscribes to an event specified by the Emitter instance in persistent manner and executes a callback after the event is received. | 1411 | +Subscribes to an event specified by the **Emitter** instance in persistent manner and executes a callback after the event is received. |
| 716 | 1412 | ||
| 717 | -**Atomic service API**: This API can be used in atomic services since API version 22. | 1413 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. |
| 718 | 1414 | ||
| 719 | **System capability**: SystemCapability.Notification.Emitter | 1415 | **System capability**: SystemCapability.Notification.Emitter |
| 720 | 1416 | ||
| 1417 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 1418 | + | ||
| 1419 | +**Related API**: The corresponding ArkTS-Sta API is [onEventData](#oneventdata22) | ||
| 1420 | + | ||
| 1421 | +**ArkTS-Dyn start version:** 22 | ||
| 1422 | + | ||
| 721 | **Parameters** | 1423 | **Parameters** |
| 722 | 1424 | ||
| 723 | | Name | Type | Mandatory| Description | | 1425 | | Name | Type | Mandatory| Description | |
| 724 | | -------- | ----------------------------------- | ---- | -------------------------------------- | | 1426 | | -------- | ----------------------------------- | ---- | -------------------------------------- | |
| 725 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 1427 | +| eventId | string | Yes | ID of the event subscribed to in persistent manner.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 726 | | callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to be invoked when the event is received.| | 1428 | | callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to be invoked when the event is received.| |
| 727 | 1429 | ||
| 728 | **Example** | 1430 | **Example** |
| @@ -741,19 +1443,25 @@ emitter1.on(`eventId`, callback); | |||
| 741 | 1443 | ||
| 742 | ### on<sup>22+</sup> | 1444 | ### on<sup>22+</sup> |
| 743 | 1445 | ||
| 744 | -on<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void | 1446 | +on<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void |
| 745 | 1447 | ||
| 746 | -Subscribes to an event specified by the Emitter instance in persistent manner and executes a callback after the event is received. | 1448 | +Subscribes to an event specified by the **Emitter** instance in persistent manner and executes a callback after the event is received. |
| 747 | 1449 | ||
| 748 | -**Atomic service API**: This API can be used in atomic services since API version 22. | 1450 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. |
| 749 | 1451 | ||
| 750 | **System capability**: SystemCapability.Notification.Emitter | 1452 | **System capability**: SystemCapability.Notification.Emitter |
| 751 | 1453 | ||
| 1454 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 1455 | + | ||
| 1456 | +**Related API**: The corresponding ArkTS-Sta API is [onGenericEventData](#ongenericeventdata22) | ||
| 1457 | + | ||
| 1458 | +**ArkTS-Dyn start version:** 22 | ||
| 1459 | + | ||
| 752 | **Parameters** | 1460 | **Parameters** |
| 753 | 1461 | ||
| 754 | | Name | Type | Mandatory| Description | | 1462 | | Name | Type | Mandatory| Description | |
| 755 | | -------- | ----------------------------------- | ---- | -------------------------------------- | | 1463 | | -------- | ----------------------------------- | ---- | -------------------------------------- | |
| 756 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 1464 | +| eventId | string | Yes | ID of the event subscribed to in persistent manner.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 757 | | callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to be invoked when the event is received.| | 1465 | | callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to be invoked when the event is received.| |
| 758 | 1466 | ||
| 759 | **Example** | 1467 | **Example** |
| @@ -784,21 +1492,115 @@ let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.G | |||
| 784 | emitter1.on("eventId", callback); | 1492 | emitter1.on("eventId", callback); |
| 785 | ``` | 1493 | ``` |
| 786 | 1494 | ||
| 787 | -### once<sup>22+</sup> | 1495 | +### onEventData<sup>22+</sup> |
| 788 | 1496 | ||
| 789 | -once(eventId: string, callback: Callback\<EventData\>): void | 1497 | +onEventData(eventId: string, callback: Callback\<EventData\>): void |
| 790 | 1498 | ||
| 791 | -Subscribes to an event specified by the Emitter instance in one-shot manner and unsubscribes from it after the event callback is executed. This API uses an asynchronous callback to return the result. | 1499 | +Subscribes to an event specified by the **Emitter** instance in persistent manner and executes a callback after the event is received. |
| 792 | 1500 | ||
| 793 | -**Atomic service API**: This API can be used in atomic services since API version 22. | 1501 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. |
| 794 | 1502 | ||
| 795 | **System capability**: SystemCapability.Notification.Emitter | 1503 | **System capability**: SystemCapability.Notification.Emitter |
| 796 | 1504 | ||
| 1505 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 1506 | + | ||
| 1507 | +**Related API**: The corresponding ArkTS-Dyn API is [on](#on22) | ||
| 1508 | + | ||
| 1509 | +**ArkTS-Sta start version:** 23 | ||
| 1510 | + | ||
| 797 | **Parameters** | 1511 | **Parameters** |
| 798 | 1512 | ||
| 799 | | Name | Type | Mandatory| Description | | 1513 | | Name | Type | Mandatory| Description | |
| 800 | | -------- | ----------------------------------- | ---- | -------------------------------------- | | 1514 | | -------- | ----------------------------------- | ---- | -------------------------------------- | |
| 801 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 1515 | +| eventId | string | Yes | ID of the event subscribed to in persistent manner.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 1516 | +| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback invoked when the event is received. | | ||
| 1517 | + | ||
| 1518 | +**Example** | ||
| 1519 | + | ||
| 1520 | +```ts | ||
| 1521 | +import { Callback } from '@kit.BasicServicesKit'; | ||
| 1522 | + | ||
| 1523 | +let emitter1 = new emitter.Emitter(); | ||
| 1524 | + | ||
| 1525 | +let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { | ||
| 1526 | + console.info(`eventData: ${JSON.stringify(eventData)}`); | ||
| 1527 | +} | ||
| 1528 | + | ||
| 1529 | +emitter1.onEventData(`eventId`, callback); | ||
| 1530 | +``` | ||
| 1531 | + | ||
| 1532 | +### onGenericEventData<sup>22+</sup> | ||
| 1533 | + | ||
| 1534 | +onGenericEventData<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void | ||
| 1535 | + | ||
| 1536 | +Subscribes to an event specified by the **Emitter** instance in persistent manner and executes a callback after the event is received. | ||
| 1537 | + | ||
| 1538 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. | ||
| 1539 | + | ||
| 1540 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 1541 | + | ||
| 1542 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 1543 | + | ||
| 1544 | +**Related API**: The corresponding ArkTS-Dyn API is [on](#on22) | ||
| 1545 | + | ||
| 1546 | +**ArkTS-Sta start version:** 23 | ||
| 1547 | + | ||
| 1548 | +**Parameters** | ||
| 1549 | + | ||
| 1550 | +| Name | Type | Mandatory| Description | | ||
| 1551 | +| -------- | ----------------------------------- | ---- | -------------------------------------- | | ||
| 1552 | +| eventId | string | Yes | ID of the event subscribed to in persistent manner.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | | ||
| 1553 | +| callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback invoked when the event is received. | | ||
| 1554 | + | ||
| 1555 | +**Example** | ||
| 1556 | + | ||
| 1557 | +```ts | ||
| 1558 | +import { Callback } from '@kit.BasicServicesKit'; | ||
| 1559 | + | ||
| 1560 | +let emitter1 = new emitter.Emitter(); | ||
| 1561 | + | ||
| 1562 | +class Sample { | ||
| 1563 | + constructor() { | ||
| 1564 | + this.count = 100; | ||
| 1565 | + } | ||
| 1566 | + printCount() { | ||
| 1567 | + console.info('Print count : ' + this.count); | ||
| 1568 | + } | ||
| 1569 | + count: number; | ||
| 1570 | +} | ||
| 1571 | + | ||
| 1572 | +let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.GenericEventData<Sample>): void => { | ||
| 1573 | + console.info(`eventData: ${JSON.stringify(eventData?.data)}`); | ||
| 1574 | + if (eventData?.data instanceof Sample) { | ||
| 1575 | + const sampleData = eventData.data as Sample; | ||
| 1576 | + sampleData.printCount(); | ||
| 1577 | + } | ||
| 1578 | +} | ||
| 1579 | + | ||
| 1580 | +emitter1.onGenericEventData("eventId", callback); | ||
| 1581 | +``` | ||
| 1582 | + | ||
| 1583 | +### once<sup>22+</sup> | ||
| 1584 | + | ||
| 1585 | +once(eventId: string, callback: Callback\<EventData\>): void | ||
| 1586 | + | ||
| 1587 | +Subscribes to an event specified by the **Emitter** instance in one-shot manner and unsubscribes from it after the event callback is executed. This API uses an asynchronous callback to return the result. | ||
| 1588 | + | ||
| 1589 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. | ||
| 1590 | + | ||
| 1591 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 1592 | + | ||
| 1593 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 1594 | + | ||
| 1595 | +**Related API**: The corresponding ArkTS-Sta API is [onceEventData](#onceeventdata22) | ||
| 1596 | + | ||
| 1597 | +**ArkTS-Dyn start version:** 22 | ||
| 1598 | + | ||
| 1599 | +**Parameters** | ||
| 1600 | + | ||
| 1601 | +| Name | Type | Mandatory| Description | | ||
| 1602 | +| -------- | ----------------------------------- | ---- | -------------------------------------- | | ||
| 1603 | +| eventId | string | Yes | ID of the event subscribed to in one-shot manner.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | | ||
| 802 | | callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to be invoked when the event is received.| | 1604 | | callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to be invoked when the event is received.| |
| 803 | 1605 | ||
| 804 | **Example** | 1606 | **Example** |
| @@ -819,17 +1621,23 @@ emitter1.once("eventId", callback); | |||
| 819 | 1621 | ||
| 820 | once<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void | 1622 | once<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void |
| 821 | 1623 | ||
| 822 | -Subscribes to an event specified by the Emitter instance in one-shot manner and unsubscribes from it after the event callback is executed. This API uses an asynchronous callback to return the result. | 1624 | +Subscribes to an event specified by the **Emitter** instance in one-shot manner and unsubscribes from it after the event callback is executed. This API uses an asynchronous callback to return the result. |
| 823 | 1625 | ||
| 824 | -**Atomic service API**: This API can be used in atomic services since API version 22. | 1626 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. |
| 825 | 1627 | ||
| 826 | **System capability**: SystemCapability.Notification.Emitter | 1628 | **System capability**: SystemCapability.Notification.Emitter |
| 827 | 1629 | ||
| 1630 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 1631 | + | ||
| 1632 | +**Related API**: The corresponding ArkTS-Sta API is [onceGenericEventData](#oncegenericeventdata22) | ||
| 1633 | + | ||
| 1634 | +**ArkTS-Dyn start version:** 22 | ||
| 1635 | + | ||
| 828 | **Parameters** | 1636 | **Parameters** |
| 829 | 1637 | ||
| 830 | | Name | Type | Mandatory| Description | | 1638 | | Name | Type | Mandatory| Description | |
| 831 | | -------- | ----------------------------------- | ---- | -------------------------------------- | | 1639 | | -------- | ----------------------------------- | ---- | -------------------------------------- | |
| 832 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 1640 | +| eventId | string | Yes | ID of the event subscribed to in one-shot manner.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 833 | | callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to be invoked when the event is received.| | 1641 | | callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to be invoked when the event is received.| |
| 834 | 1642 | ||
| 835 | **Example** | 1643 | **Example** |
| @@ -860,23 +1668,115 @@ let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.G | |||
| 860 | emitter1.once("eventId", callback); | 1668 | emitter1.once("eventId", callback); |
| 861 | ``` | 1669 | ``` |
| 862 | 1670 | ||
| 1671 | +### onceEventData<sup>22+</sup> | ||
| 1672 | + | ||
| 1673 | +onceEventData(eventId: string, callback: Callback\<EventData\>): void | ||
| 1674 | + | ||
| 1675 | +Subscribes to an event specified by the **Emitter** instance in one-shot manner and unsubscribes from it after the event callback is executed. This API uses an asynchronous callback to return the result. | ||
| 1676 | + | ||
| 1677 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. | ||
| 1678 | + | ||
| 1679 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 1680 | + | ||
| 1681 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 1682 | + | ||
| 1683 | +**Related API**: The corresponding ArkTS-Dyn API is [once](#once22) | ||
| 1684 | + | ||
| 1685 | +**ArkTS-Sta start version:** 23 | ||
| 1686 | + | ||
| 1687 | +**Parameters** | ||
| 1688 | + | ||
| 1689 | +| Name | Type | Mandatory| Description | | ||
| 1690 | +| -------- | ----------------------------------- | ---- | -------------------------------------- | | ||
| 1691 | +| eventId | string | Yes | ID of the event subscribed to in one-shot manner.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | | ||
| 1692 | +| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback used to return the [EventData](#eventdata). | | ||
| 1693 | + | ||
| 1694 | +**Example** | ||
| 1695 | + | ||
| 1696 | +```ts | ||
| 1697 | +import { Callback } from '@kit.BasicServicesKit'; | ||
| 1698 | + | ||
| 1699 | +let emitter1 = new emitter.Emitter(); | ||
| 1700 | + | ||
| 1701 | +let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { | ||
| 1702 | + console.info(`eventData: ${JSON.stringify(eventData)}`); | ||
| 1703 | +} | ||
| 1704 | + | ||
| 1705 | +emitter1.onceEventData("eventId", callback); | ||
| 1706 | +``` | ||
| 1707 | + | ||
| 1708 | +### onceGenericEventData<sup>22+</sup> | ||
| 1709 | + | ||
| 1710 | +onceGenericEventData<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void | ||
| 1711 | + | ||
| 1712 | +Subscribes to an event specified by the **Emitter** instance in one-shot manner and unsubscribes from it after the event callback is executed. This API uses an asynchronous callback to return the result. | ||
| 1713 | + | ||
| 1714 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. | ||
| 1715 | + | ||
| 1716 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 1717 | + | ||
| 1718 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 1719 | + | ||
| 1720 | +**Related API**: The corresponding ArkTS-Dyn API is [once](#once22) | ||
| 1721 | + | ||
| 1722 | +**ArkTS-Sta start version:** 23 | ||
| 1723 | + | ||
| 1724 | +**Parameters** | ||
| 1725 | + | ||
| 1726 | +| Name | Type | Mandatory| Description | | ||
| 1727 | +| -------- | ----------------------------------- | ---- | -------------------------------------- | | ||
| 1728 | +| eventId | string | Yes | ID of the event subscribed to in one-shot manner.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | | ||
| 1729 | +| callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback used to return the [GenericEventData<T\>](#genericeventdatat12). | | ||
| 1730 | + | ||
| 1731 | +**Example** | ||
| 1732 | + | ||
| 1733 | +```ts | ||
| 1734 | +import { Callback } from '@kit.BasicServicesKit'; | ||
| 1735 | + | ||
| 1736 | +let emitter1 = new emitter.Emitter(); | ||
| 1737 | + | ||
| 1738 | +class Sample { | ||
| 1739 | + constructor() { | ||
| 1740 | + this.count = 100; | ||
| 1741 | + } | ||
| 1742 | + printCount() { | ||
| 1743 | + console.info('Print count : ' + this.count); | ||
| 1744 | + } | ||
| 1745 | + count: number; | ||
| 1746 | +} | ||
| 1747 | + | ||
| 1748 | +let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.GenericEventData<Sample>): void => { | ||
| 1749 | + console.info(`eventData: ${JSON.stringify(eventData?.data)}`); | ||
| 1750 | + if (eventData?.data instanceof Sample) { | ||
| 1751 | + const sampleData = eventData.data as Sample; | ||
| 1752 | + sampleData.printCount(); | ||
| 1753 | + } | ||
| 1754 | +} | ||
| 1755 | + | ||
| 1756 | +emitter1.onceGenericEventData("eventId", callback); | ||
| 1757 | +``` | ||
| 1758 | + | ||
| 863 | ### off<sup>22+</sup> | 1759 | ### off<sup>22+</sup> |
| 864 | 1760 | ||
| 865 | off(eventId: string): void | 1761 | off(eventId: string): void |
| 866 | 1762 | ||
| 867 | -Unsubscribes from all events with the specified event ID of the Emitter instance. | 1763 | +Unsubscribes from all events with the specified event ID of the **Emitter** instance. |
| 868 | 1764 | ||
| 869 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emit22) API but has not been executed will be unsubscribed. | 1765 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emit22) API but has not been executed will be unsubscribed. |
| 870 | 1766 | ||
| 871 | -**Atomic service API**: This API can be used in atomic services since API version 22. | 1767 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. |
| 872 | 1768 | ||
| 873 | **System capability**: SystemCapability.Notification.Emitter | 1769 | **System capability**: SystemCapability.Notification.Emitter |
| 874 | 1770 | ||
| 1771 | +**ArkTS-Dyn start version:** 22 | ||
| 1772 | + | ||
| 1773 | +**ArkTS-Sta start version:** 23 | ||
| 1774 | + | ||
| 875 | **Parameters** | 1775 | **Parameters** |
| 876 | 1776 | ||
| 877 | | Name | Type | Mandatory| Description | | 1777 | | Name | Type | Mandatory| Description | |
| 878 | | ------- | ------ | ---- | -------- | | 1778 | | ------- | ------ | ---- | -------- | |
| 879 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty.| | 1779 | +| eventId | string | Yes | Event ID.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 880 | 1780 | ||
| 881 | **Example** | 1781 | **Example** |
| 882 | 1782 | ||
| @@ -890,19 +1790,25 @@ emitter1.off("eventId"); | |||
| 890 | 1790 | ||
| 891 | off(eventId: string, callback: Callback\<EventData\>): void | 1791 | off(eventId: string, callback: Callback\<EventData\>): void |
| 892 | 1792 | ||
| 893 | -Unsubscribes from an event of the Emitter instance. This API takes effect only when the [on](#on22) or [once](#once22) API is used to subscribe to the event with specified event ID and a callback is used to process the event. | 1793 | +Unsubscribes from an event of the **Emitter** instance. This API takes effect only when the [on](#on22) or [once](#once22) API is used to subscribe to the event with specified event ID and a callback is used to process the event. |
| 894 | 1794 | ||
| 895 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emit22) API but has not been executed will be unsubscribed. | 1795 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emit22) API but has not been executed will be unsubscribed. |
| 896 | 1796 | ||
| 897 | -**Atomic service API**: This API can be used in atomic services since API version 22. | 1797 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. |
| 898 | 1798 | ||
| 899 | **System capability**: SystemCapability.Notification.Emitter | 1799 | **System capability**: SystemCapability.Notification.Emitter |
| 900 | 1800 | ||
| 1801 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 1802 | + | ||
| 1803 | +**Related API**: The corresponding ArkTS-Sta API is [offEventData](#offeventdata22) | ||
| 1804 | + | ||
| 1805 | +**ArkTS-Dyn start version:** 22 | ||
| 1806 | + | ||
| 901 | **Parameters** | 1807 | **Parameters** |
| 902 | 1808 | ||
| 903 | | Name | Type | Mandatory| Description | | 1809 | | Name | Type | Mandatory| Description | |
| 904 | | -------- | ----------------------------------- | ---- | -------------------------- | | 1810 | | -------- | ----------------------------------- | ---- | -------------------------- | |
| 905 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 1811 | +| eventId | string | Yes | Event ID.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 906 | | callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to unregister.| | 1812 | | callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to unregister.| |
| 907 | 1813 | ||
| 908 | **Example** | 1814 | **Example** |
| @@ -923,19 +1829,25 @@ emitter1.off("eventId", callback); | |||
| 923 | 1829 | ||
| 924 | off<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void | 1830 | off<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void |
| 925 | 1831 | ||
| 926 | -Unsubscribes from an event of the Emitter instance. This API takes effect only when the [on](#on22-1) or [once](#once22-1) API is used to subscribe to the event with specified event ID and a callback is used to process the event. | 1832 | +Unsubscribes from an event of the **Emitter** instance. This API takes effect only when the [on](#on22-1) or [once](#once22-1) API is used to subscribe to the event with specified event ID and a callback is used to process the event. |
| 927 | 1833 | ||
| 928 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emit22-1) API but has not been executed will be unsubscribed. | 1834 | After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emit22-1) API but has not been executed will be unsubscribed. |
| 929 | 1835 | ||
| 930 | -**Atomic service API**: This API can be used in atomic services since API version 22. | 1836 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. |
| 931 | 1837 | ||
| 932 | **System capability**: SystemCapability.Notification.Emitter | 1838 | **System capability**: SystemCapability.Notification.Emitter |
| 933 | 1839 | ||
| 1840 | +**ArkTS mode:** This API is only applicable to ArkTS-Dyn. | ||
| 1841 | + | ||
| 1842 | +**Related API**: The corresponding ArkTS-Sta API is [offGenericEventData](#offgenericeventdata22) | ||
| 1843 | + | ||
| 1844 | +**ArkTS-Dyn start version:** 22 | ||
| 1845 | + | ||
| 934 | **Parameters** | 1846 | **Parameters** |
| 935 | 1847 | ||
| 936 | | Name | Type | Mandatory| Description | | 1848 | | Name | Type | Mandatory| Description | |
| 937 | | -------- | ----------------------------------- | ---- | -------------------------- | | 1849 | | -------- | ----------------------------------- | ---- | -------------------------- | |
| 938 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 1850 | +| eventId | string | Yes | Event ID.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 939 | | callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to unregister.| | 1851 | | callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to unregister.| |
| 940 | 1852 | ||
| 941 | **Example** | 1853 | **Example** |
| @@ -966,29 +1878,127 @@ let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.G | |||
| 966 | emitter1.off("eventId", callback); | 1878 | emitter1.off("eventId", callback); |
| 967 | ``` | 1879 | ``` |
| 968 | 1880 | ||
| 1881 | +### offEventData<sup>22+</sup> | ||
| 1882 | + | ||
| 1883 | +offEventData(eventId: string, callback: Callback\<EventData\>): void | ||
| 1884 | + | ||
| 1885 | +Unsubscribes from an event of the **Emitter** instance. This API takes effect only when the [onEventData](#oneventdata22) or [onceEventData](#onceeventdata22) API is used to subscribe to the event with the specified event ID and processed by the specified callback. | ||
| 1886 | + | ||
| 1887 | +After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emit22) API but has not been executed will be unsubscribed. | ||
| 1888 | + | ||
| 1889 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. | ||
| 1890 | + | ||
| 1891 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 1892 | + | ||
| 1893 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 1894 | + | ||
| 1895 | +**Related API**: The corresponding ArkTS-Dyn API is [off](#off22) | ||
| 1896 | + | ||
| 1897 | +**ArkTS-Sta start version:** 23 | ||
| 1898 | + | ||
| 1899 | +**Parameters** | ||
| 1900 | + | ||
| 1901 | +| Name | Type | Mandatory| Description | | ||
| 1902 | +| -------- | ----------------------------------- | ---- | -------------------------- | | ||
| 1903 | +| eventId | string | Yes | Event ID.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | | ||
| 1904 | +| callback | Callback\<[EventData](#eventdata)\> | Yes | Callback to unregister. | | ||
| 1905 | + | ||
| 1906 | +**Example** | ||
| 1907 | + | ||
| 1908 | +```ts | ||
| 1909 | +import { Callback } from '@kit.BasicServicesKit'; | ||
| 1910 | + | ||
| 1911 | +let emitter1 = new emitter.Emitter(); | ||
| 1912 | + | ||
| 1913 | +let callback: Callback<emitter.EventData> = (eventData: emitter.EventData) => { | ||
| 1914 | + console.info(`eventData: ${JSON.stringify(eventData)}`); | ||
| 1915 | +} | ||
| 1916 | + | ||
| 1917 | +emitter1.offEventData("eventId", callback); | ||
| 1918 | +``` | ||
| 1919 | + | ||
| 1920 | +### offGenericEventData<sup>22+</sup> | ||
| 1921 | + | ||
| 1922 | +offGenericEventData<T\>(eventId: string, callback: Callback\<GenericEventData<T\>\>): void | ||
| 1923 | + | ||
| 1924 | +Unsubscribes from an event of the **Emitter** instance. This API takes effect only when the [onGenericEventData](#ongenericeventdata22) or [onceGenericEventData](#oncegenericeventdata22) API is used to subscribe to the event with the specified event ID and processed by the specified callback. | ||
| 1925 | + | ||
| 1926 | +After this API is used to unsubscribe from an event, the event that has been published through the [emit](#emit22-1) API but has not been executed will be unsubscribed from. | ||
| 1927 | + | ||
| 1928 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. | ||
| 1929 | + | ||
| 1930 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 1931 | + | ||
| 1932 | +**ArkTS mode:** This API is only applicable to ArkTS-Sta. | ||
| 1933 | + | ||
| 1934 | +**Related API**: The corresponding ArkTS-Dyn API is [off](#off22) | ||
| 1935 | + | ||
| 1936 | +**ArkTS-Sta start version:** 23 | ||
| 1937 | + | ||
| 1938 | +**Parameters** | ||
| 1939 | + | ||
| 1940 | +| Name | Type | Mandatory| Description | | ||
| 1941 | +| -------- | ----------------------------------- | ---- | -------------------------- | | ||
| 1942 | +| eventId | string | Yes | Event ID.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | | ||
| 1943 | +| callback | Callback\<[GenericEventData<T\>](#genericeventdatat12)\> | Yes | Callback to unregister. | | ||
| 1944 | + | ||
| 1945 | +**Example** | ||
| 1946 | + | ||
| 1947 | +```ts | ||
| 1948 | +import { Callback } from '@kit.BasicServicesKit'; | ||
| 1949 | + | ||
| 1950 | +class Sample { | ||
| 1951 | + constructor() { | ||
| 1952 | + this.count = 100; | ||
| 1953 | + } | ||
| 1954 | + printCount() { | ||
| 1955 | + console.info('Print count : ' + this.count); | ||
| 1956 | + } | ||
| 1957 | + count: number; | ||
| 1958 | +} | ||
| 1959 | + | ||
| 1960 | +let emitter1 = new emitter.Emitter(); | ||
| 1961 | + | ||
| 1962 | +let callback: Callback<emitter.GenericEventData<Sample>> = (eventData: emitter.GenericEventData<Sample>): void => { | ||
| 1963 | + console.info(`eventData: ${JSON.stringify(eventData?.data)}`); | ||
| 1964 | + if (eventData?.data instanceof Sample) { | ||
| 1965 | + const sampleData = eventData.data as Sample; | ||
| 1966 | + sampleData.printCount(); | ||
| 1967 | + } | ||
| 1968 | +} | ||
| 1969 | + | ||
| 1970 | +emitter1.offGenericEventData("eventId", callback); | ||
| 1971 | +``` | ||
| 1972 | + | ||
| 969 | ### emit<sup>22+</sup> | 1973 | ### emit<sup>22+</sup> |
| 970 | 1974 | ||
| 971 | emit(eventId: string, data?: EventData): void | 1975 | emit(eventId: string, data?: EventData): void |
| 972 | 1976 | ||
| 973 | -Emits a specified event to the Emitter class instance. | 1977 | +Emits a specified event to the **Emitter** class instance. |
| 974 | 1978 | ||
| 975 | This API can be used to emit data objects across threads. The data objects must meet the specifications specified in [Overview of Inter-Thread Communication Objects](../../arkts-utils/serializable-overview.md). Currently, complex data decorated by decorators such as [@State](../../ui/state-management/arkts-state.md) and [@Observed](../../ui/state-management/arkts-observed-and-objectlink.md) is not supported. | 1979 | This API can be used to emit data objects across threads. The data objects must meet the specifications specified in [Overview of Inter-Thread Communication Objects](../../arkts-utils/serializable-overview.md). Currently, complex data decorated by decorators such as [@State](../../ui/state-management/arkts-state.md) and [@Observed](../../ui/state-management/arkts-observed-and-objectlink.md) is not supported. |
| 976 | 1980 | ||
| 977 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. | 1981 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. |
| 978 | 1982 | ||
| 979 | -**Atomic service API**: This API can be used in atomic services since API version 22. | 1983 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. |
| 980 | 1984 | ||
| 981 | **System capability**: SystemCapability.Notification.Emitter | 1985 | **System capability**: SystemCapability.Notification.Emitter |
| 982 | 1986 | ||
| 1987 | +**ArkTS-Dyn start version:** 22 | ||
| 1988 | + | ||
| 1989 | +**ArkTS-Sta start version:** 23 | ||
| 1990 | + | ||
| 983 | **Parameters** | 1991 | **Parameters** |
| 984 | 1992 | ||
| 985 | | Name | Type | Mandatory| Description | | 1993 | | Name | Type | Mandatory| Description | |
| 986 | | ------- | ----------------------- | ---- | ---------------- | | 1994 | | ------- | ----------------------- | ---- | ---------------- | |
| 987 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 1995 | +| eventId | string | Yes | Event ID.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 988 | | data | [EventData](#eventdata) | No | Data carried by the event. This parameter is left empty by default.| | 1996 | | data | [EventData](#eventdata) | No | Data carried by the event. This parameter is left empty by default.| |
| 989 | 1997 | ||
| 990 | **Example** | 1998 | **Example** |
| 991 | 1999 | ||
| 2000 | +ArkTS-Dyn example: | ||
| 2001 | + | ||
| 992 | ```ts | 2002 | ```ts |
| 993 | let emitter1: emitter.Emitter = new emitter.Emitter(); | 2003 | let emitter1: emitter.Emitter = new emitter.Emitter(); |
| 994 | let eventData: emitter.EventData = { | 2004 | let eventData: emitter.EventData = { |
| @@ -1001,25 +2011,47 @@ let eventData: emitter.EventData = { | |||
| 1001 | emitter1.emit("eventId", eventData); | 2011 | emitter1.emit("eventId", eventData); |
| 1002 | ``` | 2012 | ``` |
| 1003 | 2013 | ||
| 2014 | +ArkTS-Sta example: | ||
| 2015 | + | ||
| 2016 | +```ts | ||
| 2017 | +import { RecordData } from '@ohos.base'; | ||
| 2018 | + | ||
| 2019 | +let emitter1 = new emitter.Emitter(); | ||
| 2020 | +let record: Record<string, RecordData> = { | ||
| 2021 | + "content": "content", | ||
| 2022 | + "id": 1, | ||
| 2023 | +}; | ||
| 2024 | + | ||
| 2025 | +let eventData: emitter.EventData = { | ||
| 2026 | + data: record // The types are now compatible. | ||
| 2027 | +}; | ||
| 2028 | + | ||
| 2029 | +emitter1.emit("eventId", eventData); | ||
| 2030 | +``` | ||
| 2031 | + | ||
| 1004 | ### emit<sup>22+</sup> | 2032 | ### emit<sup>22+</sup> |
| 1005 | 2033 | ||
| 1006 | emit<T\>(eventId: string, data?: GenericEventData<T\>): void | 2034 | emit<T\>(eventId: string, data?: GenericEventData<T\>): void |
| 1007 | 2035 | ||
| 1008 | -Emits a specified event to the Emitter class instance. | 2036 | +Emits a specified event to the **Emitter** class instance. |
| 1009 | 2037 | ||
| 1010 | This API can be used to emit data objects across threads. The data objects must meet the specifications specified in [Overview of Inter-Thread Communication Objects](../../arkts-utils/serializable-overview.md). Currently, complex data decorated by decorators such as [@State](../../ui/state-management/arkts-state.md) and [@Observed](../../ui/state-management/arkts-observed-and-objectlink.md) is not supported. | 2038 | This API can be used to emit data objects across threads. The data objects must meet the specifications specified in [Overview of Inter-Thread Communication Objects](../../arkts-utils/serializable-overview.md). Currently, complex data decorated by decorators such as [@State](../../ui/state-management/arkts-state.md) and [@Observed](../../ui/state-management/arkts-observed-and-objectlink.md) is not supported. |
| 1011 | 2039 | ||
| 1012 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. | 2040 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. |
| 1013 | 2041 | ||
| 1014 | -**Atomic service API**: This API can be used in atomic services since API version 22. | 2042 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. |
| 1015 | 2043 | ||
| 1016 | **System capability**: SystemCapability.Notification.Emitter | 2044 | **System capability**: SystemCapability.Notification.Emitter |
| 1017 | 2045 | ||
| 2046 | +**ArkTS-Dyn start version:** 22 | ||
| 2047 | + | ||
| 2048 | +**ArkTS-Sta start version:** 23 | ||
| 2049 | + | ||
| 1018 | **Parameters** | 2050 | **Parameters** |
| 1019 | 2051 | ||
| 1020 | | Name | Type | Mandatory| Description | | 2052 | | Name | Type | Mandatory| Description | |
| 1021 | | ------- | ----------------------- | ---- | ---------------- | | 2053 | | ------- | ----------------------- | ---- | ---------------- | |
| 1022 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty.| | 2054 | +| eventId | string | Yes | Event ID.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 1023 | | data | [GenericEventData<T\>](#genericeventdatat12) | No | Data carried by the event. This parameter is left empty by default.| | 2055 | | data | [GenericEventData<T\>](#genericeventdatat12) | No | Data carried by the event. This parameter is left empty by default.| |
| 1024 | 2056 | ||
| 1025 | **Example** | 2057 | **Example** |
| @@ -1047,28 +2079,85 @@ emitter1.emit("eventId", eventData); | |||
| 1047 | 2079 | ||
| 1048 | ### emit<sup>22+</sup> | 2080 | ### emit<sup>22+</sup> |
| 1049 | 2081 | ||
| 1050 | -emit(eventId: string, options: Options, data?: EventData): void | 2082 | +emit<T\>(eventId: string, options: Options, data?: GenericEventData<T\>): void |
| 1051 | 2083 | ||
| 1052 | -Emits a specified event to the Emitter class instance. | 2084 | +Emits an event of a specified priority to the **Emitter** instance. |
| 1053 | 2085 | ||
| 1054 | This API can be used to emit data objects across threads. The data objects must meet the specifications specified in [Overview of Inter-Thread Communication Objects](../../arkts-utils/serializable-overview.md). Currently, complex data decorated by decorators such as [@State](../../ui/state-management/arkts-state.md) and [@Observed](../../ui/state-management/arkts-observed-and-objectlink.md) is not supported. | 2086 | This API can be used to emit data objects across threads. The data objects must meet the specifications specified in [Overview of Inter-Thread Communication Objects](../../arkts-utils/serializable-overview.md). Currently, complex data decorated by decorators such as [@State](../../ui/state-management/arkts-state.md) and [@Observed](../../ui/state-management/arkts-observed-and-objectlink.md) is not supported. |
| 1055 | 2087 | ||
| 1056 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. | 2088 | After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. |
| 1057 | 2089 | ||
| 1058 | -**Atomic service API**: This API can be used in atomic services since API version 22. | 2090 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. |
| 1059 | 2091 | ||
| 1060 | **System capability**: SystemCapability.Notification.Emitter | 2092 | **System capability**: SystemCapability.Notification.Emitter |
| 1061 | 2093 | ||
| 2094 | +**ArkTS-Dyn start version:** 22 | ||
| 2095 | + | ||
| 2096 | +**ArkTS-Sta start version:** 23 | ||
| 2097 | + | ||
| 1062 | **Parameters** | 2098 | **Parameters** |
| 1063 | 2099 | ||
| 1064 | | Name | Type | Mandatory| Description | | 2100 | | Name | Type | Mandatory| Description | |
| 1065 | | ------- | ----------------------- | ---- | ---------------- | | 2101 | | ------- | ----------------------- | ---- | ---------------- | |
| 1066 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | 2102 | +| eventId | string | Yes | Event ID.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 1067 | | options | [Options](#options11) | Yes | Event emit priority. | | 2103 | | options | [Options](#options11) | Yes | Event emit priority. | |
| 1068 | -| data | [EventData](#eventdata) | No | Data carried by the event. This parameter is left empty by default.| | 2104 | +| data | [GenericEventData<T\>](#genericeventdatat12) | No | Data carried by the event. | |
| 1069 | 2105 | ||
| 1070 | **Example** | 2106 | **Example** |
| 1071 | 2107 | ||
| 2108 | +```ts | ||
| 2109 | +class Sample { | ||
| 2110 | + constructor() { | ||
| 2111 | + this.count = 100; | ||
| 2112 | + } | ||
| 2113 | + printCount() { | ||
| 2114 | + console.info('Print count : ' + this.count); | ||
| 2115 | + } | ||
| 2116 | + count: number; | ||
| 2117 | +} | ||
| 2118 | + | ||
| 2119 | +let emitter1 = new emitter.Emitter(); | ||
| 2120 | + | ||
| 2121 | +let options: emitter.Options = { | ||
| 2122 | + priority: emitter.EventPriority.HIGH | ||
| 2123 | +}; | ||
| 2124 | +let eventData: emitter.GenericEventData<Sample> = { | ||
| 2125 | + data: new Sample() | ||
| 2126 | +}; | ||
| 2127 | + | ||
| 2128 | +emitter1.emit("eventId", options, eventData); | ||
| 2129 | +``` | ||
| 2130 | + | ||
| 2131 | +### emit<sup>22+</sup> | ||
| 2132 | + | ||
| 2133 | +emit(eventId: string, options: Options, data?: EventData): void | ||
| 2134 | + | ||
| 2135 | +Emits a specified event to the **Emitter** class instance. | ||
| 2136 | + | ||
| 2137 | +This API can be used to emit data objects across threads. The data objects must meet the specifications specified in [Overview of Inter-Thread Communication Objects](../../arkts-utils/serializable-overview.md). Currently, complex data decorated by decorators such as [@State](../../ui/state-management/arkts-state.md) and [@Observed](../../ui/state-management/arkts-observed-and-objectlink.md) is not supported. | ||
| 2138 | + | ||
| 2139 | +After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. | ||
| 2140 | + | ||
| 2141 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. | ||
| 2142 | + | ||
| 2143 | +**System capability**: SystemCapability.Notification.Emitter | ||
| 2144 | + | ||
| 2145 | +**ArkTS-Dyn start version:** 22 | ||
| 2146 | + | ||
| 2147 | +**ArkTS-Sta start version:** 23 | ||
| 2148 | + | ||
| 2149 | +**Parameters** | ||
| 2150 | + | ||
| 2151 | +| Name | Type | Mandatory| Description | | ||
| 2152 | +| ------- | ----------------------- | ---- | ---------------- | | ||
| 2153 | +| eventId | string | Yes | Event ID.<br>It cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | | ||
| 2154 | +| options | [Options](#options11) | Yes | Event emit priority. | | ||
| 2155 | +| data | [EventData](#eventdata) | No | Data carried by the event. This parameter is left empty by default. | | ||
| 2156 | + | ||
| 2157 | +**Example** | ||
| 2158 | + | ||
| 2159 | +ArkTS-Dyn example: | ||
| 2160 | + | ||
| 1072 | ```ts | 2161 | ```ts |
| 1073 | let emitter1: emitter.Emitter = new emitter.Emitter(); | 2162 | let emitter1: emitter.Emitter = new emitter.Emitter(); |
| 1074 | 2163 | ||
| @@ -1085,49 +2174,21 @@ let eventData: emitter.EventData = { | |||
| 1085 | emitter1.emit("eventId", options, eventData); | 2174 | emitter1.emit("eventId", options, eventData); |
| 1086 | ``` | 2175 | ``` |
| 1087 | 2176 | ||
| 1088 | -### emit<sup>22+</sup> | 2177 | +ArkTS-Sta example: |
| 1089 | - | ||
| 1090 | -emit<T\>(eventId: string, options: Options, data?: GenericEventData<T\>): void | ||
| 1091 | - | ||
| 1092 | -Emits an event of a specified priority to the Emitter instance. | ||
| 1093 | - | ||
| 1094 | -This API can be used to emit data objects across threads. The data objects must meet the specifications specified in [Overview of Inter-Thread Communication Objects](../../arkts-utils/serializable-overview.md). Currently, complex data decorated by decorators such as [@State](../../ui/state-management/arkts-state.md) and [@Observed](../../ui/state-management/arkts-observed-and-objectlink.md) is not supported. | ||
| 1095 | - | ||
| 1096 | -After an event is published using this API, the event may not be executed immediately. When the execution starts depends on the number of events in the event queue and the execution efficiency of each event. | ||
| 1097 | - | ||
| 1098 | -**Atomic service API**: This API can be used in atomic services since API version 22. | ||
| 1099 | - | ||
| 1100 | -**System capability**: SystemCapability.Notification.Emitter | ||
| 1101 | - | ||
| 1102 | -**Parameters** | ||
| 1103 | - | ||
| 1104 | -| Name | Type | Mandatory| Description | | ||
| 1105 | -| ------- | ----------------------- | ---- | ---------------- | | ||
| 1106 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty. | | ||
| 1107 | -| options | [Options](#options11) | Yes | Event emit priority. | | ||
| 1108 | -| data | [GenericEventData<T\>](#genericeventdatat12) | No | Data carried by the event. This parameter is left empty by default.| | ||
| 1109 | - | ||
| 1110 | -**Example** | ||
| 1111 | 2178 | ||
| 1112 | ```ts | 2179 | ```ts |
| 1113 | -@Sendable | 2180 | +import { RecordData } from '@ohos.base'; |
| 1114 | -class Sample { | ||
| 1115 | - constructor() { | ||
| 1116 | - this.count = 100; | ||
| 1117 | - } | ||
| 1118 | - printCount() { | ||
| 1119 | - console.info('Print count : ' + this.count); | ||
| 1120 | - } | ||
| 1121 | - count: number; | ||
| 1122 | -} | ||
| 1123 | - | ||
| 1124 | -let emitter1: emitter.Emitter = new emitter.Emitter(); | ||
| 1125 | 2181 | ||
| 2182 | +let emitter1 = new emitter.Emitter(); | ||
| 1126 | let options: emitter.Options = { | 2183 | let options: emitter.Options = { |
| 1127 | priority: emitter.EventPriority.HIGH | 2184 | priority: emitter.EventPriority.HIGH |
| 1128 | }; | 2185 | }; |
| 1129 | -let eventData: emitter.GenericEventData<Sample> = { | 2186 | +let record: Record<string, RecordData> = { |
| 1130 | - data: new Sample() | 2187 | + "content": "content", |
| 2188 | + "id": 1, | ||
| 2189 | +}; | ||
| 2190 | +let eventData: emitter.EventData = { | ||
| 2191 | + data: record | ||
| 1131 | }; | 2192 | }; |
| 1132 | 2193 | ||
| 1133 | emitter1.emit("eventId", options, eventData); | 2194 | emitter1.emit("eventId", options, eventData); |
| @@ -1135,30 +2196,35 @@ emitter1.emit("eventId", options, eventData); | |||
| 1135 | 2196 | ||
| 1136 | ### getListenerCount<sup>22+</sup> | 2197 | ### getListenerCount<sup>22+</sup> |
| 1137 | 2198 | ||
| 1138 | -getListenerCount(eventId: string): number | 2199 | +ArkTS-Dyn: getListenerCount(eventId: string): number |
| 1139 | 2200 | ||
| 1140 | -Obtains the number of subscriptions to a specified event of the Emitter instance. | 2201 | +ArkTS-Sta: getListenerCount(eventId: string): long |
| 1141 | 2202 | ||
| 1142 | -**Atomic service API**: This API can be used in atomic services since API version 22. | 2203 | +Obtains the number of subscriptions to a specified event of the **Emitter** instance. |
| 2204 | + | ||
| 2205 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 22. | ||
| 1143 | 2206 | ||
| 1144 | **System capability**: SystemCapability.Notification.Emitter | 2207 | **System capability**: SystemCapability.Notification.Emitter |
| 1145 | 2208 | ||
| 2209 | +**ArkTS-Dyn start version:** 22 | ||
| 2210 | + | ||
| 2211 | +**ArkTS-Sta start version:** 23 | ||
| 2212 | + | ||
| 1146 | **Parameters** | 2213 | **Parameters** |
| 1147 | 2214 | ||
| 1148 | | Name | Type | Mandatory| Description | | 2215 | | Name | Type | Mandatory| Description | |
| 1149 | | ------- | -------------- | ---- | -------- | | 2216 | | ------- | -------------- | ---- | -------- | |
| 1150 | -| eventId | string | Yes | Event ID, which is a custom string with a maximum of 10240 bytes. The value cannot be empty.| | 2217 | +| eventId | string | Yes | Event ID,<br>it cannot be empty or exceed 10,240 bytes. Excess content will be truncated. | |
| 1151 | 2218 | ||
| 1152 | **Returns** | 2219 | **Returns** |
| 1153 | 2220 | ||
| 1154 | | Type | Description | | 2221 | | Type | Description | |
| 1155 | | ----- | ----- | | 2222 | | ----- | ----- | |
| 1156 | -| number | Number of subscriptions to a specified event.| | 2223 | +| ArkTS-Dyn: number<br>ArkTS-Sta: long | Number of subscriptions for the specified event. | |
| 1157 | - | ||
| 1158 | 2224 | ||
| 1159 | **Example** | 2225 | **Example** |
| 1160 | 2226 | ||
| 1161 | ```ts | 2227 | ```ts |
| 1162 | let emitter1: emitter.Emitter = new emitter.Emitter(); | 2228 | let emitter1: emitter.Emitter = new emitter.Emitter(); |
| 1163 | let count = emitter1.getListenerCount("eventId"); | 2229 | let count = emitter1.getListenerCount("eventId"); |
| 1164 | -``` | 2230 | +``` |
Men/application-dev/reference/apis-basic-services-kit/js-apis-inner-commonEvent-commonEventPublishData.md+18-13
| @@ -1,30 +1,35 @@ | |||
| 1 | # CommonEventPublishData | 1 | # CommonEventPublishData |
| 2 | - | ||
| 3 | <!--Kit: Basic Services Kit--> | 2 | <!--Kit: Basic Services Kit--> |
| 4 | <!--Subsystem: Notification--> | 3 | <!--Subsystem: Notification--> |
| 5 | -<!--Owner: @peixu--> | 4 | +<!--Owner: @HuYueRong--> |
| 6 | -<!--Designer: @dongqingran; @wulong158--> | 5 | +<!--Designer: @dongqingran--> |
| 7 | <!--Tester: @wanghong1997--> | 6 | <!--Tester: @wanghong1997--> |
| 8 | <!--Adviser: @fang-jinxu--> | 7 | <!--Adviser: @fang-jinxu--> |
| 8 | +<!-- md-trans-meta sourceCommit=227499a15769ff89e238d0afb653f1633e59b877 translatedAt=2026-07-21T08:26:18.275Z pushedAt=2026-07-22T06:40:31.858Z --> | ||
| 9 | 9 | ||
| 10 | -The **CommonEventPublishData** module provides APIs for defining common event content and attributes. | 10 | +This module encapsulates the data and attributes carried when a common event is published, including the event data (code/data), subscriber permissions, subscriber bundle name, whether the event is ordered or sticky, and additional parameters. It allows the publisher to precisely control the common event recipients, event delivery sequence, and sticky feature. This module is applicable to scenarios where the recipients need to be specified, custom event data needs to be transferred, and ordered/sticky common events need to be implemented. |
| 11 | 11 | ||
| 12 | > **NOTE** | 12 | > **NOTE** |
| 13 | > | 13 | > |
| 14 | -> 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. | 14 | +> - This module supports both ArkTS-Dyn and ArkTS-Sta. |
| 15 | +> - 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. | ||
| 15 | > | 16 | > |
| 16 | -> If there is no restriction, any application can subscribe to common events and read related information. In this case, sensitive information should not be carried in common events. The **subscriberPermissions** and **bundleName** parameters of this module can be used to restrict the receiving scope of common events. | 17 | +> If there is no restriction, any app can subscribe to common events and read the information carried by the event. In this case, sensitive information should not be carried in common events. The **subscriberPermissions** and **bundleName** parameters of this module can be used to restrict the receiving scope of common events. |
| 17 | 18 | ||
| 18 | ## Properties | 19 | ## Properties |
| 19 | 20 | ||
| 20 | **System capability**: SystemCapability.Notification.CommonEvent | 21 | **System capability**: SystemCapability.Notification.CommonEvent |
| 21 | 22 | ||
| 23 | +**ArkTS-Dyn Since:** 7 | ||
| 24 | + | ||
| 25 | +**ArkTS-Sta Since:** 23 | ||
| 26 | + | ||
| 22 | | Name | Type | Read Only| Optional| Description | | 27 | | Name | Type | Read Only| Optional| Description | |
| 23 | | --------------------- | -------------------- | ---- | ---- | ---------------------------- | | 28 | | --------------------- | -------------------- | ---- | ---- | ---------------------------- | |
| 24 | -| bundleName | string | No | Yes | Bundle name of the subscriber that can receive the common event.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| | 29 | +| bundleName | string | No | Yes | Bundle name of the subscriber, which is used to specify the subscriber to whom the common event is published. This parameter is left empty by default. When this parameter is empty, the bundle name of the subscriber is not specified, and all subscribers can receive the common event.<br>**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. | |
| 25 | -| code | number | No | Yes | Common event data transferred by the publisher. The default value is **0**.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | | 30 | +| code | ArkTS-Dyn: number<br/>ArkTS-Sta: int | No | Yes | Common event data transferred by the publisher. The default value is **0**.<br>**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. | |
| 26 | -| data | string | No | Yes | Common event data transferred by the publisher. The data size cannot exceed 64 KB.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| | 31 | +| data | string | No | Yes | Common event data transferred by the publisher. The value is a string and cannot exceed 64 KB. If the value exceeds the limit, the event fails to be published. This parameter is left empty by default.<br>**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. | |
| 27 | -| subscriberPermissions | Array\<string> | No | Yes | Permissions required for subscribers to receive the common event.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | | 32 | +| subscriberPermissions | Array\<string> | No | Yes | Subscriber permissions. Only subscribers with the specified permissions can receive the common event. This parameter is left empty by default. When this parameter is empty, the subscriber permissions are not specified, and all subscribers can receive the common event.<br>**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. | |
| 28 | -| isOrdered | boolean | No | Yes | Whether the common event is an ordered one. The default value is **false**.<br> - **true**: This event is an ordered common event. Based on the priority set by the subscriber, the common event is preferentially sent to the subscriber with a higher priority. After the subscriber successfully receives the event, the public event is sent to the subscriber with a lower priority. Subscribers with the same priority receive common events in a random order.<br> - **false**: This event is an unordered common event. Whether subscribers receive the event is not considered, and the common event which subscribers receive may not comply with the subscription sequence. | | 33 | +| isOrdered | boolean | No | Yes | Whether the common event is an ordered one. The default value is **false**.<br/> - **true**: This event is an ordered common event. Based on the priority set by the subscriber, the common event is preferentially sent to the subscriber with a higher priority. After the subscriber successfully receives the event, the common event is sent to the subscriber with a lower priority. Subscribers with the same priority receive common events in a random order.<br/> - **false**: This event is an unordered common event. Whether subscribers receive the event is not considered, and the common event which subscribers receive may not comply with the subscription sequence. | |
| 29 | -| isSticky | boolean | No | Yes | Whether the common event is a sticky one. The default value is **false**.<br> - **true**: This event is a sticky common event, which allows subscribers to receive common events that have been sent before subscription.<br> - **false**: This event is not a sticky common event, which allows subscribers to receive common events sent after subscription.<br>Only system applications and system services are allowed to send sticky events.<br>**Required Permissions**: [ohos.permission.COMMONEVENT_STICKY](../../security/AccessToken/permissions-for-all.md#ohospermissioncommonevent_sticky)| | 34 | +| isSticky | boolean | No | Yes | Whether the common event is a sticky one. The default value is **false**.<br/> - **true**: This event is a sticky common event, which allows subscribers to receive common events that have been sent before subscription.<br/> - **false**: This event is not a sticky common event, which allows subscribers to receive common events sent after subscription.<br>Only system applications and system services are allowed to send sticky events.<br>**Required permissions:** [ohos.permission.COMMONEVENT_STICKY](../../security/AccessToken/permissions-for-all.md#ohospermissioncommonevent_sticky) | |
| 30 | -| parameters | {[key: string]: any} | No | Yes | Additional information about the common event transferred by the publisher.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | | 35 | +| parameters | ArkTS-Dyn: {[key: string]: any}<br/>ArkTS-Sta: Record\<string, RecordData\> | No | Yes | Additional information of the common event transferred by the publisher, which carries custom parameters in key-value pairs. This parameter is left empty by default.<br>**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. | |
Men/application-dev/reference/apis-basic-services-kit/js-apis-inner-commonEvent-commonEventSubscribeInfo.md+24-11
| @@ -1,24 +1,37 @@ | |||
| 1 | # CommonEventSubscribeInfo | 1 | # CommonEventSubscribeInfo |
| 2 | 2 | ||
| 3 | -The **CommonEventSubscribeInfo** module provides APIs for providing subscriber information. | 3 | +<!--Kit: Basic Services Kit--> |
| 4 | +<!--Subsystem: Notification--> | ||
| 5 | +<!--Owner: @HuYueRong--> | ||
| 6 | +<!--Designer: @dongqingran--> | ||
| 7 | +<!--Tester: @wanghong1997--> | ||
| 8 | +<!--Adviser: @fang-jinxu--> | ||
| 9 | +<!-- md-trans-meta sourceCommit=227499a15769ff89e238d0afb653f1633e59b877 translatedAt=2026-07-21T08:26:19.953Z pushedAt=2026-07-22T06:40:34.263Z --> | ||
| 10 | + | ||
| 11 | +This module provides APIs for providing subscriber information. It allows you to configure parameters such as the subscribed common event type, publisher permission, publisher device ID, user ID, and subscription priority. This module is applicable to scenarios where an app needs to subscribe to system common events or custom common events and requires refined control over event sources. | ||
| 4 | 12 | ||
| 5 | > **NOTE** | 13 | > **NOTE** |
| 6 | > | 14 | > |
| 7 | -> 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. | 15 | +> - This module supports both ArkTS-Dyn and ArkTS-Sta. |
| 16 | +> - 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. | ||
| 8 | > | 17 | > |
| 9 | -> After users subscribing to custom common events, any application can send potential malicious common events to subscribers. Use the **publisherPermission** and **publisherBundleName** parameters of this module to restrict the publishing scope of common events. | 18 | +> After users subscribe to custom common events, any app can send potential malicious common events to subscribers. The **publisherPermission** and **publisherBundleName** parameters of this module can be used to restrict the publisher scope of common events. |
| 10 | 19 | ||
| 11 | ## Attributes | 20 | ## Attributes |
| 12 | 21 | ||
| 13 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 22 | +**Atomic service API** (ArkTS-Dyn only): This API can be used in atomic services since API version 11. |
| 14 | 23 | ||
| 15 | **System capability**: SystemCapability.Notification.CommonEvent | 24 | **System capability**: SystemCapability.Notification.CommonEvent |
| 16 | 25 | ||
| 17 | -| Name | Type | Read Only| Optional| Description | | 26 | +**ArkTS-Dyn since:** 7 |
| 27 | + | ||
| 28 | +**ArkTS-Sta since:** 23 | ||
| 29 | + | ||
| 30 | +| Name | Type | Read-Only| Optional| Description | | ||
| 18 | | ------------------- | -------------- | ---- | ---- | ------------------------------------------------------------ | | 31 | | ------------------- | -------------- | ---- | ---- | ------------------------------------------------------------ | |
| 19 | -| events | Array\<string> | No | No | Common events to subscribe to. | | 32 | +| events | Array\<string> | No | No | Common events to subscribe to. | |
| 20 | -| publisherPermission | string | No | Yes | Permission of the publisher. The subscriber can receive only the events from the publisher with this permission. | | 33 | +| publisherPermission | string | No | Yes | Permission of the publisher. The value is an array of permission names defined by the system. This parameter specifies that the subscriber can only receive the common events from publishers with this permission. If this parameter is left empty, the subscriber can receive common events from all publishers. <br/>**ArkTS-Dyn start version**: 7<br/>**ArkTS-Sta start version**: 23 | |
| 21 | -| publisherDeviceId | string | No | Yes | Device ID. Use [@ohos.deviceInfo](js-apis-device-info.md) to obtain the UDID as the device ID of the subscriber. Not supported currently. | | 34 | +| publisherDeviceId | string | No | Yes | Device ID, which is used to specify that the subscriber receives only public events published by the specified device. Use [@ohos.deviceInfo](js-apis-device-info.md) to obtain the UDID as the device ID of the publisher. Not supported currently. <br/>**ArkTS-Dyn start version**: 7<br/>**ArkTS-Sta start version**: 23 | |
| 22 | -| userId | number | No | Yes | User ID. If this parameter is not specified, the default value, which is the ID of the current user, will be used. The value must be an existing user ID in the system. Use [getOsAccountLocalId](./js-apis-osAccount.md#getosaccountlocalid9) to obtain the system account ID and use it as the user ID of the subscriber.| | 35 | +| userId | ArkTS-Dyn: number<br/>ArkTS-Sta: int | No | Yes | User ID, which is used to specify that the subscriber receives only public events related to the specified user ID. This parameter is optional. 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. Use [getOsAccountLocalId](./js-apis-osAccount.md#getosaccountlocalid9) to obtain the system user ID and use it as the user ID of the publisher. <br/>**ArkTS-Dyn start version**: 7<br/>**ArkTS-Sta start version**: 23 | |
| 23 | -| priority | number | No | Yes | Subscriber priority. The value ranges from –100 to +1000. If the value exceeds the upper or lower limit, the upper or lower limit is used. | | 36 | +| priority | ArkTS-Dyn: number<br/>ArkTS-Sta: int | No | Yes | Subscriber priority. A larger value indicates a higher priority, and the subscriber with a higher priority receives ordered public events first. The value ranges from –100 to 1000. If the value exceeds the upper or lower limit, the upper or lower limit is used. The default value is **0**. <br/>**ArkTS-Dyn start version**: 7<br/>**ArkTS-Sta start version**: 23 | |
| 24 | -| publisherBundleName<sup>11+</sup> | string | No | Yes | Bundle name of the publisher to subscribe to. | | 37 | +| publisherBundleName<sup>11+</sup> | string | No | Yes | Bundle name of the publisher to be subscribed to. This parameter specifies that the subscribers receives only public events published by the publisher with the specified bundle name. If this parameter is not set, the subscriber can receive all public events published by the app. <br/>**ArkTS-Dyn start version**: 11<br/>**ArkTS-Sta start version**: 23 | |
Men/application-dev/reference/apis-basic-services-kit/js-apis-inner-commonEvent-commonEventSubscriber.md+840-109
| @@ -2,28 +2,35 @@ | |||
| 2 | 2 | ||
| 3 | <!--Kit: Basic Services Kit--> | 3 | <!--Kit: Basic Services Kit--> |
| 4 | <!--Subsystem: Notification--> | 4 | <!--Subsystem: Notification--> |
| 5 | -<!--Owner: @peixu--> | 5 | +<!--Owner: @HuYueRong--> |
| 6 | -<!--Designer: @dongqingran; @wulong158--> | 6 | +<!--Designer: @dongqingran--> |
| 7 | <!--Tester: @wanghong1997--> | 7 | <!--Tester: @wanghong1997--> |
| 8 | <!--Adviser: @fang-jinxu--> | 8 | <!--Adviser: @fang-jinxu--> |
| 9 | +<!-- md-trans-meta sourceCommit=227499a15769ff89e238d0afb653f1633e59b877 translatedAt=2026-07-21T08:36:10.955Z pushedAt=2026-07-22T09:00:29.164Z --> | ||
| 9 | 10 | ||
| 10 | > **NOTE** | 11 | > **NOTE** |
| 12 | +> - This module supports both ArkTS-Dyn and ArkTS-Sta. | ||
| 11 | > | 13 | > |
| 12 | -> 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. | 14 | +> - 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. |
| 13 | 15 | ||
| 14 | ## CommonEventSubscriber | 16 | ## CommonEventSubscriber |
| 15 | 17 | ||
| 16 | -The **CommonEventSubscriber** module provides APIs for describing the common event subscriber. | 18 | +Represents the subscriber of a common event. The **CommonEventSubscriber** module provides the capabilities for processing ordered common events, including obtaining and setting the data and code transferred by events, checking whether the current common event is an ordered or sticky event, terminating an ordered common event or clearing the termination status, ending the processing of the current ordered common event, and obtaining subscription information of a subscriber. This module is applicable to data processing and process control of the received common event by the subscriber. |
| 17 | 19 | ||
| 18 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 20 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 19 | 21 | ||
| 20 | **System capability**: SystemCapability.Notification.CommonEvent | 22 | **System capability**: SystemCapability.Notification.CommonEvent |
| 21 | 23 | ||
| 24 | +**ArkTS-Dyn start version:** 7 | ||
| 25 | + | ||
| 26 | +**ArkTS-Sta start version:** 23 | ||
| 27 | + | ||
| 22 | ### How to Use | 28 | ### How to Use |
| 23 | 29 | ||
| 24 | -Before using the **CommonEventSubscriber** module, you must obtain a **subscriber** object by calling **commonEventManager.createSubscriber**. | 30 | +Before using the **CommonEventSubscriber** module, you must obtain a **subscriber** object by calling [commonEventManager.createSubscriber](js-apis-commonEventManager.md#commoneventmanagercreatesubscriber-1). |
| 25 | 31 | ||
| 26 | <!--code_no_check--> | 32 | <!--code_no_check--> |
| 33 | + | ||
| 27 | ```ts | 34 | ```ts |
| 28 | import { commonEventManager } from '@kit.BasicServicesKit'; | 35 | import { commonEventManager } from '@kit.BasicServicesKit'; |
| 29 | import { BusinessError } from '@kit.BasicServicesKit'; | 36 | import { BusinessError } from '@kit.BasicServicesKit'; |
| @@ -32,7 +39,7 @@ import { BusinessError } from '@kit.BasicServicesKit'; | |||
| 32 | let subscriber: commonEventManager.CommonEventSubscriber | null = null; | 39 | let subscriber: commonEventManager.CommonEventSubscriber | null = null; |
| 33 | // Subscriber information. | 40 | // Subscriber information. |
| 34 | let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = { | 41 | let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = { |
| 35 | - events: ['event'] | 42 | + events: ['event'] |
| 36 | }; | 43 | }; |
| 37 | // Create a subscriber. | 44 | // Create a subscriber. |
| 38 | subscriber = commonEventManager.createSubscriberSync(subscribeInfo); | 45 | subscriber = commonEventManager.createSubscriberSync(subscribeInfo); |
| @@ -40,19 +47,27 @@ subscriber = commonEventManager.createSubscriberSync(subscribeInfo); | |||
| 40 | 47 | ||
| 41 | ### getCode | 48 | ### getCode |
| 42 | 49 | ||
| 43 | -getCode(callback: AsyncCallback\<number>): void | 50 | +ArkTS-Dyn: getCode(callback: AsyncCallback\<number>): void |
| 44 | 51 | ||
| 45 | -Obtains the result code (number type) of an ordered common event. This API uses an asynchronous callback to return the result. | 52 | +ArkTS-Sta: getCode(callback: AsyncCallback\<int>): void |
| 46 | 53 | ||
| 47 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 54 | +ArkTS-Dyn: Obtains the result code (number type) of an ordered common event. This API uses an asynchronous callback to return the result. |
| 55 | + | ||
| 56 | +ArkTS-Sta: Obtains the result code (int type) of an ordered common event. This API uses an asynchronous callback to return the result. | ||
| 57 | + | ||
| 58 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. | ||
| 48 | 59 | ||
| 49 | **System capability**: SystemCapability.Notification.CommonEvent | 60 | **System capability**: SystemCapability.Notification.CommonEvent |
| 50 | 61 | ||
| 62 | +**ArkTS-Dyn start version:** 7 | ||
| 63 | + | ||
| 64 | +**ArkTS-Sta start version:** 23 | ||
| 65 | + | ||
| 51 | **Parameters** | 66 | **Parameters** |
| 52 | 67 | ||
| 53 | -| Name | Type | Mandatory| Description | | 68 | +| Name | Type | Mandatory | Description | |
| 54 | | -------- | ---------------------- | ---- | ------------------ | | 69 | | -------- | ---------------------- | ---- | ------------------ | |
| 55 | -| callback | AsyncCallback\<number\> | Yes | Callback used to return the result.| | 70 | +| callback | ArkTS-Dyn: AsyncCallback\<number\><br/>ArkTS-Sta: AsyncCallback\<int\> | Yes | Callback used to return the result. If the result code of an ordered common event is successfully obtained, **err** is **undefined**, and data is the code obtained; otherwise, **err** is an error object. | |
| 56 | 71 | ||
| 57 | **Error codes** | 72 | **Error codes** |
| 58 | 73 | ||
| @@ -60,10 +75,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 60 | 75 | ||
| 61 | | ID| Error Message | | 76 | | ID| Error Message | |
| 62 | | -------- | ----------------------------------- | | 77 | | -------- | ----------------------------------- | |
| 63 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 78 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 64 | 79 | ||
| 65 | **Example** | 80 | **Example** |
| 66 | 81 | ||
| 82 | +ArkTS-Dyn example: | ||
| 83 | + | ||
| 67 | <!--code_no_check--> | 84 | <!--code_no_check--> |
| 68 | 85 | ||
| 69 | ```ts | 86 | ```ts |
| @@ -76,24 +93,48 @@ subscriber.getCode((err: BusinessError, code: number) => { | |||
| 76 | }); | 93 | }); |
| 77 | ``` | 94 | ``` |
| 78 | 95 | ||
| 96 | +ArkTS-Sta example: | ||
| 97 | + | ||
| 98 | +<!--code_no_check--> | ||
| 99 | + | ||
| 100 | +```ts | ||
| 101 | +subscriber.getCode((err: BusinessError | null, code: int | undefined | null) => { | ||
| 102 | + if (err) { | ||
| 103 | + console.error(`Failed to get code. Code is ${err.code}, message is ${err.message}`); | ||
| 104 | + return; | ||
| 105 | + } | ||
| 106 | + console.info(`Succeeded in getting code, code is ${JSON.stringify(code)}`); | ||
| 107 | +}); | ||
| 108 | +``` | ||
| 109 | + | ||
| 79 | ### getCode | 110 | ### getCode |
| 80 | 111 | ||
| 81 | -getCode(): Promise\<number> | 112 | +ArkTS-Dyn: getCode(): Promise\<number> |
| 82 | 113 | ||
| 83 | -Obtains the result code (number type) of an ordered common event. This API uses a promise to return the result. | 114 | +ArkTS-Sta: getCode(): Promise\<int> |
| 84 | 115 | ||
| 85 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 116 | +ArkTS-Dyn: Obtains the result code (number type) of an ordered common event. This API uses a promise to return the result. |
| 117 | + | ||
| 118 | +ArkTS-Sta: Obtains the result code (int type) of an ordered common event. This API uses a promise to return the result. | ||
| 119 | + | ||
| 120 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. | ||
| 86 | 121 | ||
| 87 | **System capability**: SystemCapability.Notification.CommonEvent | 122 | **System capability**: SystemCapability.Notification.CommonEvent |
| 88 | 123 | ||
| 124 | +**ArkTS-Dyn start version:** 7 | ||
| 125 | + | ||
| 126 | +**ArkTS-Sta start version:** 23 | ||
| 127 | + | ||
| 89 | **Return value** | 128 | **Return value** |
| 90 | 129 | ||
| 91 | | Type | Description | | 130 | | Type | Description | |
| 92 | | ---------------- | -------------------- | | 131 | | ---------------- | -------------------- | |
| 93 | -| Promise\<number> | Promise used to return the result.| | 132 | +| ArkTS-Dyn: Promise\<number><br/>ArkTS-Sta:Promise\<int> | Promise used to return the code delivered by the ordered common event. | |
| 94 | 133 | ||
| 95 | **Example** | 134 | **Example** |
| 96 | 135 | ||
| 136 | +ArkTS-Dyn example: | ||
| 137 | + | ||
| 97 | <!--code_no_check--> | 138 | <!--code_no_check--> |
| 98 | 139 | ||
| 99 | ```ts | 140 | ```ts |
| @@ -104,24 +145,47 @@ subscriber.getCode().then((code: number) => { | |||
| 104 | }); | 145 | }); |
| 105 | ``` | 146 | ``` |
| 106 | 147 | ||
| 148 | +ArkTS-Sta example: | ||
| 149 | + | ||
| 150 | +<!--code_no_check--> | ||
| 151 | + | ||
| 152 | +```ts | ||
| 153 | +subscriber.getCode().then((code: int) => { | ||
| 154 | + console.info(`Succeeded in getting code, code is ${JSON.stringify(code)}`); | ||
| 155 | +}).catch((err: Error): void => { | ||
| 156 | + let error: BusinessError = err as BusinessError; | ||
| 157 | + console.error(`Failed to get code. Code is ${error.code}, message is ${error.message}`); | ||
| 158 | +}); | ||
| 159 | +``` | ||
| 160 | + | ||
| 107 | ### getCodeSync<sup>10+</sup> | 161 | ### getCodeSync<sup>10+</sup> |
| 108 | 162 | ||
| 109 | -getCodeSync(): number | 163 | +ArkTS-Dyn: getCodeSync(): number |
| 110 | 164 | ||
| 111 | -Obtains the result code (number type) of an ordered common event. | 165 | +ArkTS-Sta: getCodeSync(): int |
| 112 | 166 | ||
| 113 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 167 | +ArkTS-Dyn: Obtains the result code (number type) of an ordered common event. This API returns the result synchronously. |
| 168 | + | ||
| 169 | +ArkTS-Sta: Obtains the result code (int type) of an ordered common event. This API returns the result synchronously. | ||
| 170 | + | ||
| 171 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. | ||
| 114 | 172 | ||
| 115 | **System capability**: SystemCapability.Notification.CommonEvent | 173 | **System capability**: SystemCapability.Notification.CommonEvent |
| 116 | 174 | ||
| 175 | +**ArkTS-Dyn start version:** 10 | ||
| 176 | + | ||
| 177 | +**ArkTS-Sta start version:** 23 | ||
| 178 | + | ||
| 117 | **Return value** | 179 | **Return value** |
| 118 | 180 | ||
| 119 | | Type | Description | | 181 | | Type | Description | |
| 120 | | ---------------- | -------------------- | | 182 | | ---------------- | -------------------- | |
| 121 | -| number | Result code of an ordered common event.| | 183 | +| ArkTS-Dyn: number<br/>ArkTS-Sta: int | Code delivered by the ordered common event. | |
| 122 | 184 | ||
| 123 | **Example** | 185 | **Example** |
| 124 | 186 | ||
| 187 | +ArkTS-Dyn example: | ||
| 188 | + | ||
| 125 | <!--code_no_check--> | 189 | <!--code_no_check--> |
| 126 | 190 | ||
| 127 | ```ts | 191 | ```ts |
| @@ -129,22 +193,39 @@ let code: number = subscriber.getCodeSync(); | |||
| 129 | console.info(`Succeeded in getting code, code is ${JSON.stringify(code)}`); | 193 | console.info(`Succeeded in getting code, code is ${JSON.stringify(code)}`); |
| 130 | ``` | 194 | ``` |
| 131 | 195 | ||
| 196 | +ArkTS-Sta example: | ||
| 197 | + | ||
| 198 | +<!--code_no_check--> | ||
| 199 | + | ||
| 200 | +```ts | ||
| 201 | +let code: int = subscriber.getCodeSync(); | ||
| 202 | +console.info(`Succeeded in getting code, code is ${JSON.stringify(code)}`); | ||
| 203 | +``` | ||
| 204 | + | ||
| 132 | ### setCode | 205 | ### setCode |
| 133 | 206 | ||
| 134 | -setCode(code: number, callback: AsyncCallback\<void>): void | 207 | +ArkTS-Dyn: setCode(code: number, callback: AsyncCallback\<void>): void |
| 135 | 208 | ||
| 136 | -Sets the result code (number type) of an ordered common event. This API uses an asynchronous callback to return the result. | 209 | +ArkTS-Sta: setCode(code: int, callback: AsyncCallback\<void>): void |
| 137 | 210 | ||
| 138 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 211 | +ArkTS-Dyn: Sets the result code (number type) of an ordered common event. This API uses an asynchronous callback to return the result. |
| 212 | + | ||
| 213 | +ArkTS-Sta: Sets the result code (int type) of an ordered common event. This API uses an asynchronous callback to return the result. | ||
| 214 | + | ||
| 215 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. | ||
| 139 | 216 | ||
| 140 | **System capability**: SystemCapability.Notification.CommonEvent | 217 | **System capability**: SystemCapability.Notification.CommonEvent |
| 141 | 218 | ||
| 219 | +**ArkTS-Dyn start version:** 7 | ||
| 220 | + | ||
| 221 | +**ArkTS-Sta start version:** 23 | ||
| 222 | + | ||
| 142 | **Parameters** | 223 | **Parameters** |
| 143 | 224 | ||
| 144 | | Name | Type | Mandatory| Description | | 225 | | Name | Type | Mandatory| Description | |
| 145 | | -------- | -------------------- | ---- | ---------------------- | | 226 | | -------- | -------------------- | ---- | ---------------------- | |
| 146 | -| code | number | Yes | Result code of an ordered common event. | | 227 | +| code | ArkTS-Dyn: number<br/>ArkTS-Sta: int | Yes | Code delivered by the ordered common event. | |
| 147 | -| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| | 228 | +| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | |
| 148 | 229 | ||
| 149 | **Error codes** | 230 | **Error codes** |
| 150 | 231 | ||
| @@ -152,10 +233,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 152 | 233 | ||
| 153 | | ID| Error Message | | 234 | | ID| Error Message | |
| 154 | | -------- | ----------------------------------- | | 235 | | -------- | ----------------------------------- | |
| 155 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 236 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 156 | 237 | ||
| 157 | **Example** | 238 | **Example** |
| 158 | 239 | ||
| 240 | +ArkTS-Dyn example: | ||
| 241 | + | ||
| 159 | <!--code_no_check--> | 242 | <!--code_no_check--> |
| 160 | 243 | ||
| 161 | ```ts | 244 | ```ts |
| @@ -168,21 +251,43 @@ subscriber.setCode(1, (err: BusinessError) => { | |||
| 168 | }); | 251 | }); |
| 169 | ``` | 252 | ``` |
| 170 | 253 | ||
| 254 | +ArkTS-Sta example: | ||
| 255 | + | ||
| 256 | +<!--code_no_check--> | ||
| 257 | + | ||
| 258 | +```ts | ||
| 259 | +subscriber.setCode(1, (err: BusinessError | null) => { | ||
| 260 | + if (err) { | ||
| 261 | + console.error(`Failed to set code. Code is ${err.code}, message is ${err.message}`); | ||
| 262 | + return; | ||
| 263 | + } | ||
| 264 | + console.info(`Succeeded in setting code.`); | ||
| 265 | +}); | ||
| 266 | +``` | ||
| 267 | + | ||
| 171 | ### setCode | 268 | ### setCode |
| 172 | 269 | ||
| 173 | -setCode(code: number): Promise\<void> | 270 | +ArkTS-Dyn: setCode(code: number): Promise\<void> |
| 174 | 271 | ||
| 175 | -Sets the result code (number type) of an ordered common event. This API uses a promise to return the result. | 272 | +ArkTS-Sta: setCode(code: int): Promise\<void> |
| 176 | 273 | ||
| 177 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 274 | +ArkTS-Dyn: Sets the result code (number type) of an ordered common event. This API uses a promise to return the result. |
| 275 | + | ||
| 276 | +ArkTS-Sta: Sets the result code (int type) of an ordered common event. This API uses a promise to return the result. | ||
| 277 | + | ||
| 278 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. | ||
| 178 | 279 | ||
| 179 | **System capability**: SystemCapability.Notification.CommonEvent | 280 | **System capability**: SystemCapability.Notification.CommonEvent |
| 180 | 281 | ||
| 282 | +**ArkTS-Dyn start version:** 7 | ||
| 283 | + | ||
| 284 | +**ArkTS-Sta start version:** 23 | ||
| 285 | + | ||
| 181 | **Parameters** | 286 | **Parameters** |
| 182 | 287 | ||
| 183 | | Name| Type | Mandatory| Description | | 288 | | Name| Type | Mandatory| Description | |
| 184 | | ------ | ------ | ---- | ------------------ | | 289 | | ------ | ------ | ---- | ------------------ | |
| 185 | -| code | number | Yes | Result code of an ordered common event.| | 290 | +| code | ArkTS-Dyn: number<br/>ArkTS-Sta: int | Yes | Code delivered by the ordered common event. | |
| 186 | 291 | ||
| 187 | **Return value** | 292 | **Return value** |
| 188 | 293 | ||
| @@ -196,10 +301,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 196 | 301 | ||
| 197 | | ID| Error Message | | 302 | | ID| Error Message | |
| 198 | | -------- | ----------------------------------- | | 303 | | -------- | ----------------------------------- | |
| 199 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 304 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 200 | 305 | ||
| 201 | **Example** | 306 | **Example** |
| 202 | 307 | ||
| 308 | +ArkTS-Dyn example: | ||
| 309 | + | ||
| 203 | <!--code_no_check--> | 310 | <!--code_no_check--> |
| 204 | 311 | ||
| 205 | ```ts | 312 | ```ts |
| @@ -210,21 +317,42 @@ subscriber.setCode(1).then(() => { | |||
| 210 | }); | 317 | }); |
| 211 | ``` | 318 | ``` |
| 212 | 319 | ||
| 320 | +ArkTS-Sta example: | ||
| 321 | + | ||
| 322 | +<!--code_no_check--> | ||
| 323 | + | ||
| 324 | +```ts | ||
| 325 | +subscriber.setCode(1).then(() => { | ||
| 326 | + console.info(`Succeeded in setting code.`); | ||
| 327 | +}).catch((err: Error): void => { | ||
| 328 | + let error: BusinessError = err as BusinessError; | ||
| 329 | + console.error(`Failed to set code. Code is ${error.code}, message is ${error.message}`); | ||
| 330 | +}); | ||
| 331 | +``` | ||
| 332 | + | ||
| 213 | ### setCodeSync<sup>10+</sup> | 333 | ### setCodeSync<sup>10+</sup> |
| 214 | 334 | ||
| 215 | -setCodeSync(code: number): void | 335 | +ArkTS-Dyn: setCodeSync(code: number): void |
| 216 | 336 | ||
| 217 | -Sets the result code (number type) of an ordered common event. | 337 | +ArkTS-Sta: setCodeSync(code: int): void |
| 218 | 338 | ||
| 219 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 339 | +ArkTS-Dyn: Sets the result code (number type) of an ordered common event. This API returns the result synchronously. |
| 340 | + | ||
| 341 | +ArkTS-Sta: Sets the result code (int type) of an ordered common event. This API returns the result synchronously. | ||
| 342 | + | ||
| 343 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. | ||
| 220 | 344 | ||
| 221 | **System capability**: SystemCapability.Notification.CommonEvent | 345 | **System capability**: SystemCapability.Notification.CommonEvent |
| 222 | 346 | ||
| 347 | +**ArkTS-Dyn start version:** 10 | ||
| 348 | + | ||
| 349 | +**ArkTS-Sta start version:** 23 | ||
| 350 | + | ||
| 223 | **Parameters** | 351 | **Parameters** |
| 224 | 352 | ||
| 225 | | Name| Type | Mandatory| Description | | 353 | | Name| Type | Mandatory| Description | |
| 226 | | ------ | ------ | ---- | ------------------ | | 354 | | ------ | ------ | ---- | ------------------ | |
| 227 | -| code | number | Yes | Result code of an ordered common event.| | 355 | +| code | ArkTS-Dyn: number<br/>ArkTS-Sta: int | Yes | Code delivered by the ordered common event. | |
| 228 | 356 | ||
| 229 | **Error codes** | 357 | **Error codes** |
| 230 | 358 | ||
| @@ -232,7 +360,7 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 232 | 360 | ||
| 233 | | ID| Error Message | | 361 | | ID| Error Message | |
| 234 | | -------- | ----------------------------------- | | 362 | | -------- | ----------------------------------- | |
| 235 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 363 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 236 | 364 | ||
| 237 | **Example** | 365 | **Example** |
| 238 | 366 | ||
| @@ -251,17 +379,21 @@ try { | |||
| 251 | 379 | ||
| 252 | getData(callback: AsyncCallback\<string>): void | 380 | getData(callback: AsyncCallback\<string>): void |
| 253 | 381 | ||
| 254 | -Obtains the result data (string type) of an ordered common event. This API uses an asynchronous callback to return the result. | 382 | +Obtains the result data of an ordered common event. This API uses an asynchronous callback to return the result. |
| 255 | 383 | ||
| 256 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 384 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 257 | 385 | ||
| 258 | **System capability**: SystemCapability.Notification.CommonEvent | 386 | **System capability**: SystemCapability.Notification.CommonEvent |
| 259 | 387 | ||
| 388 | +**ArkTS-Dyn start version:** 7 | ||
| 389 | + | ||
| 390 | +**ArkTS-Sta start version:** 23 | ||
| 391 | + | ||
| 260 | **Parameters** | 392 | **Parameters** |
| 261 | 393 | ||
| 262 | | Name | Type | Mandatory| Description | | 394 | | Name | Type | Mandatory| Description | |
| 263 | | -------- | ---------------------- | ---- | -------------------- | | 395 | | -------- | ---------------------- | ---- | -------------------- | |
| 264 | -| callback | AsyncCallback\<string> | Yes | Callback used to return the result.| | 396 | +| callback | AsyncCallback\<string> | Yes | Callback used to return the result. If the result data (string type) of an ordered common event is successfully obtained, **err** is **undefined**, and **data** is the data obtained; otherwise, **err** is an error object. | |
| 265 | 397 | ||
| 266 | **Error codes** | 398 | **Error codes** |
| 267 | 399 | ||
| @@ -269,10 +401,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 269 | 401 | ||
| 270 | | ID| Error Message | | 402 | | ID| Error Message | |
| 271 | | -------- | ----------------------------------- | | 403 | | -------- | ----------------------------------- | |
| 272 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 404 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 273 | 405 | ||
| 274 | **Example** | 406 | **Example** |
| 275 | 407 | ||
| 408 | +ArkTS-Dyn example: | ||
| 409 | + | ||
| 276 | <!--code_no_check--> | 410 | <!--code_no_check--> |
| 277 | 411 | ||
| 278 | ```ts | 412 | ```ts |
| @@ -286,24 +420,45 @@ subscriber.getData((err: BusinessError, data: string) => { | |||
| 286 | }); | 420 | }); |
| 287 | ``` | 421 | ``` |
| 288 | 422 | ||
| 423 | +ArkTS-Sta example: | ||
| 424 | + | ||
| 425 | +<!--code_no_check--> | ||
| 426 | + | ||
| 427 | +```ts | ||
| 428 | +// Obtain the result data (string type) of an ordered common event. | ||
| 429 | +subscriber.getData((err: BusinessError | null, data: string | undefined | null) => { | ||
| 430 | + if (err) { | ||
| 431 | + console.error(`Failed to get data. Code is ${err.code}, message is ${err.message}`); | ||
| 432 | + return; | ||
| 433 | + } | ||
| 434 | + console.info(`Succeeded in getting data, data is ${JSON.stringify(data)}`); | ||
| 435 | +}); | ||
| 436 | +``` | ||
| 437 | + | ||
| 289 | ### getData | 438 | ### getData |
| 290 | 439 | ||
| 291 | getData(): Promise\<string> | 440 | getData(): Promise\<string> |
| 292 | 441 | ||
| 293 | -Obtains the result data (string type) of an ordered common event. This API uses a promise to return the result. | 442 | +Obtains the result data of an ordered common event. This API uses a promise to return the result. |
| 294 | 443 | ||
| 295 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 444 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 296 | 445 | ||
| 297 | **System capability**: SystemCapability.Notification.CommonEvent | 446 | **System capability**: SystemCapability.Notification.CommonEvent |
| 298 | 447 | ||
| 448 | +**ArkTS-Dyn start version:** 7 | ||
| 449 | + | ||
| 450 | +**ArkTS-Sta start version:** 23 | ||
| 451 | + | ||
| 299 | **Return value** | 452 | **Return value** |
| 300 | 453 | ||
| 301 | | Type | Description | | 454 | | Type | Description | |
| 302 | | ---------------- | ------------------ | | 455 | | ---------------- | ------------------ | |
| 303 | -| Promise\<string> | Promise used to return the result.| | 456 | +| Promise\<string> | Promise used to return the result data (string type) of an ordered common event.| |
| 304 | 457 | ||
| 305 | **Example** | 458 | **Example** |
| 306 | 459 | ||
| 460 | +ArkTS-Dyn example: | ||
| 461 | + | ||
| 307 | <!--code_no_check--> | 462 | <!--code_no_check--> |
| 308 | 463 | ||
| 309 | ```ts | 464 | ```ts |
| @@ -314,21 +469,38 @@ subscriber.getData().then((data: string) => { | |||
| 314 | }); | 469 | }); |
| 315 | ``` | 470 | ``` |
| 316 | 471 | ||
| 472 | +ArkTS-Sta example: | ||
| 473 | + | ||
| 474 | +<!--code_no_check--> | ||
| 475 | + | ||
| 476 | +```ts | ||
| 477 | +subscriber.getData().then((data: string) => { | ||
| 478 | + console.info(`Succeeded in getting data, data is ${JSON.stringify(data)}`); | ||
| 479 | +}).catch((err: Error): void => { | ||
| 480 | + let error: BusinessError = err as BusinessError; | ||
| 481 | + console.error(`Failed to get data. Code is ${error.code}, message is ${error.message}`); | ||
| 482 | +}); | ||
| 483 | +``` | ||
| 484 | + | ||
| 317 | ### getDataSync<sup>10+</sup> | 485 | ### getDataSync<sup>10+</sup> |
| 318 | 486 | ||
| 319 | getDataSync(): string | 487 | getDataSync(): string |
| 320 | 488 | ||
| 321 | -Obtains the result data (string type) of an ordered common event. | 489 | +Obtains the result data of an ordered common event. This API returns the result synchronously. |
| 322 | 490 | ||
| 323 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 491 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 324 | 492 | ||
| 325 | **System capability**: SystemCapability.Notification.CommonEvent | 493 | **System capability**: SystemCapability.Notification.CommonEvent |
| 326 | 494 | ||
| 495 | +**ArkTS-Dyn start version:** 10 | ||
| 496 | + | ||
| 497 | +**ArkTS-Sta start version:** 23 | ||
| 498 | + | ||
| 327 | **Return value** | 499 | **Return value** |
| 328 | 500 | ||
| 329 | | Type | Description | | 501 | | Type | Description | |
| 330 | | ---------------- | ------------------ | | 502 | | ---------------- | ------------------ | |
| 331 | -| string | Result data of an ordered common event.| | 503 | +| string | Data delivered by the ordered common event. | |
| 332 | 504 | ||
| 333 | **Example** | 505 | **Example** |
| 334 | 506 | ||
| @@ -343,17 +515,21 @@ console.info(`Succeeded in getting data, data is ${data}`); | |||
| 343 | 515 | ||
| 344 | setData(data: string, callback: AsyncCallback\<void>): void | 516 | setData(data: string, callback: AsyncCallback\<void>): void |
| 345 | 517 | ||
| 346 | -Sets the result data (string type) of an ordered common event. This API uses an asynchronous callback to return the result. | 518 | +Sets the data of an ordered common event. This API uses an asynchronous callback to return the result. |
| 347 | 519 | ||
| 348 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 520 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 349 | 521 | ||
| 350 | **System capability**: SystemCapability.Notification.CommonEvent | 522 | **System capability**: SystemCapability.Notification.CommonEvent |
| 351 | 523 | ||
| 524 | +**ArkTS-Dyn start version:** 7 | ||
| 525 | + | ||
| 526 | +**ArkTS-Sta start version:** 23 | ||
| 527 | + | ||
| 352 | **Parameters** | 528 | **Parameters** |
| 353 | 529 | ||
| 354 | | Name | Type | Mandatory| Description | | 530 | | Name | Type | Mandatory| Description | |
| 355 | | -------- | -------------------- | ---- | -------------------- | | 531 | | -------- | -------------------- | ---- | -------------------- | |
| 356 | -| data | string | Yes | Result data of an ordered common event. | | 532 | +| data | string | Yes | Data delivered by the ordered common event. The value is a string containing a maximum of 65,536 characters. If the length exceeds the limit, the API setting becomes invalid. | |
| 357 | | callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| | 533 | | callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| |
| 358 | 534 | ||
| 359 | **Error codes** | 535 | **Error codes** |
| @@ -362,10 +538,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 362 | 538 | ||
| 363 | | ID| Error Message | | 539 | | ID| Error Message | |
| 364 | | -------- | ----------------------------------- | | 540 | | -------- | ----------------------------------- | |
| 365 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 541 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 366 | 542 | ||
| 367 | **Example** | 543 | **Example** |
| 368 | 544 | ||
| 545 | +ArkTS-Dyn example: | ||
| 546 | + | ||
| 369 | <!--code_no_check--> | 547 | <!--code_no_check--> |
| 370 | 548 | ||
| 371 | ```ts | 549 | ```ts |
| @@ -378,21 +556,39 @@ subscriber.setData('publish_data_changed', (err: BusinessError) => { | |||
| 378 | }); | 556 | }); |
| 379 | ``` | 557 | ``` |
| 380 | 558 | ||
| 559 | +ArkTS-Sta example: | ||
| 560 | + | ||
| 561 | +<!--code_no_check--> | ||
| 562 | + | ||
| 563 | +```ts | ||
| 564 | +subscriber.setData('publish_data_changed', (err: BusinessError | null) => { | ||
| 565 | + if (err) { | ||
| 566 | + console.error(`Failed to set data. Code is ${err.code}, message is ${err.message}`); | ||
| 567 | + return; | ||
| 568 | + } | ||
| 569 | + console.info(`Succeeded in setting data.`); | ||
| 570 | +}); | ||
| 571 | +``` | ||
| 572 | + | ||
| 381 | ### setData | 573 | ### setData |
| 382 | 574 | ||
| 383 | setData(data: string): Promise\<void> | 575 | setData(data: string): Promise\<void> |
| 384 | 576 | ||
| 385 | -Sets the result data (string type) of an ordered common event. This API uses a promise to return the result. | 577 | +Sets the result data of an ordered common event. This API uses a promise to return the result. |
| 386 | 578 | ||
| 387 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 579 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 388 | 580 | ||
| 389 | **System capability**: SystemCapability.Notification.CommonEvent | 581 | **System capability**: SystemCapability.Notification.CommonEvent |
| 390 | 582 | ||
| 583 | +**ArkTS-Dyn start version:** 7 | ||
| 584 | + | ||
| 585 | +**ArkTS-Sta start version:** 23 | ||
| 586 | + | ||
| 391 | **Parameters** | 587 | **Parameters** |
| 392 | 588 | ||
| 393 | | Name| Type | Mandatory| Description | | 589 | | Name| Type | Mandatory| Description | |
| 394 | | ------ | ------ | ---- | -------------------- | | 590 | | ------ | ------ | ---- | -------------------- | |
| 395 | -| data | string | Yes | Result data of an ordered common event.| | 591 | +| data | string | Yes | Data delivered by the ordered common event. The value is a string containing a maximum of 65,536 characters. If the length exceeds the limit, the API setting becomes invalid. | |
| 396 | 592 | ||
| 397 | **Return value** | 593 | **Return value** |
| 398 | 594 | ||
| @@ -406,10 +602,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 406 | 602 | ||
| 407 | | ID| Error Message | | 603 | | ID| Error Message | |
| 408 | | -------- | ----------------------------------- | | 604 | | -------- | ----------------------------------- | |
| 409 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 605 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 410 | 606 | ||
| 411 | **Example** | 607 | **Example** |
| 412 | 608 | ||
| 609 | +ArkTS-Dyn example: | ||
| 610 | + | ||
| 413 | <!--code_no_check--> | 611 | <!--code_no_check--> |
| 414 | 612 | ||
| 415 | ```ts | 613 | ```ts |
| @@ -420,21 +618,38 @@ subscriber.setData('publish_data_changed').then(() => { | |||
| 420 | }); | 618 | }); |
| 421 | ``` | 619 | ``` |
| 422 | 620 | ||
| 621 | +ArkTS-Sta example: | ||
| 622 | + | ||
| 623 | +<!--code_no_check--> | ||
| 624 | + | ||
| 625 | +```ts | ||
| 626 | +subscriber.setData('publish_data_changed').then(() => { | ||
| 627 | + console.info(`Succeeded in setting data.`); | ||
| 628 | +}).catch((err: Error): void => { | ||
| 629 | + let error: BusinessError = err as BusinessError; | ||
| 630 | + console.error(`Failed to set data. Code is ${error.code}, message is ${error.message}`); | ||
| 631 | +}); | ||
| 632 | +``` | ||
| 633 | + | ||
| 423 | ### setDataSync<sup>10+</sup> | 634 | ### setDataSync<sup>10+</sup> |
| 424 | 635 | ||
| 425 | setDataSync(data: string): void | 636 | setDataSync(data: string): void |
| 426 | 637 | ||
| 427 | -Sets the result data (string type) of an ordered common event. | 638 | +Sets the result data of an ordered common event. This API returns the result synchronously. |
| 428 | 639 | ||
| 429 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 640 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 430 | 641 | ||
| 431 | **System capability**: SystemCapability.Notification.CommonEvent | 642 | **System capability**: SystemCapability.Notification.CommonEvent |
| 432 | 643 | ||
| 644 | +**ArkTS-Dyn start version:** 10 | ||
| 645 | + | ||
| 646 | +**ArkTS-Sta start version:** 23 | ||
| 647 | + | ||
| 433 | **Parameters** | 648 | **Parameters** |
| 434 | 649 | ||
| 435 | | Name| Type | Mandatory| Description | | 650 | | Name| Type | Mandatory| Description | |
| 436 | | ------ | ------ | ---- | -------------------- | | 651 | | ------ | ------ | ---- | -------------------- | |
| 437 | -| data | string | Yes | Result data of an ordered common event.| | 652 | +| data | string | Yes | Data delivered by the ordered common event. The value is a string containing a maximum of 65,536 characters. If the length exceeds the limit, the API setting becomes invalid. | |
| 438 | 653 | ||
| 439 | **Error codes** | 654 | **Error codes** |
| 440 | 655 | ||
| @@ -442,7 +657,7 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 442 | 657 | ||
| 443 | | ID| Error Message | | 658 | | ID| Error Message | |
| 444 | | -------- | ----------------------------------- | | 659 | | -------- | ----------------------------------- | |
| 445 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 660 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 446 | 661 | ||
| 447 | **Example** | 662 | **Example** |
| 448 | 663 | ||
| @@ -459,20 +674,26 @@ try { | |||
| 459 | 674 | ||
| 460 | ### setCodeAndData | 675 | ### setCodeAndData |
| 461 | 676 | ||
| 462 | -setCodeAndData(code: number, data: string, callback:AsyncCallback\<void>): void | 677 | +ArkTS-Dyn: setCodeAndData(code: number, data: string, callback:AsyncCallback\<void>): void |
| 463 | 678 | ||
| 464 | -Sets the result code and data of an ordered common event. This API uses an asynchronous callback to return the result. | 679 | +ArkTS-Sta: setCodeAndData(code: int, data: string, callback:AsyncCallback\<void>): void |
| 465 | 680 | ||
| 466 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 681 | +Sets the code and data of an ordered common event. This API uses an asynchronous callback to return the result. |
| 682 | + | ||
| 683 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. | ||
| 467 | 684 | ||
| 468 | **System capability**: SystemCapability.Notification.CommonEvent | 685 | **System capability**: SystemCapability.Notification.CommonEvent |
| 469 | 686 | ||
| 687 | +**ArkTS-Dyn start version:** 7 | ||
| 688 | + | ||
| 689 | +**ArkTS-Sta start version:** 23 | ||
| 690 | + | ||
| 470 | **Parameters** | 691 | **Parameters** |
| 471 | 692 | ||
| 472 | | Name | Type | Mandatory| Description | | 693 | | Name | Type | Mandatory| Description | |
| 473 | | -------- | -------------------- | ---- | ---------------------- | | 694 | | -------- | -------------------- | ---- | ---------------------- | |
| 474 | -| code | number | Yes | Result code of an ordered common event. | | 695 | +| code | ArkTS-Dyn: number<br/>ArkTS-Sta: int | Yes | Code delivered by the ordered common event. | |
| 475 | -| data | string | Yes | Result data of an ordered common event. | | 696 | +| data | string | Yes | Data delivered by the ordered common event. The value is a string containing a maximum of 65,536 characters. If the length exceeds the limit, the API setting becomes invalid. | |
| 476 | | callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| | 697 | | callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| |
| 477 | 698 | ||
| 478 | **Error codes** | 699 | **Error codes** |
| @@ -481,10 +702,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 481 | 702 | ||
| 482 | | ID| Error Message | | 703 | | ID| Error Message | |
| 483 | | -------- | ----------------------------------- | | 704 | | -------- | ----------------------------------- | |
| 484 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 705 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 485 | 706 | ||
| 486 | **Example** | 707 | **Example** |
| 487 | 708 | ||
| 709 | +ArkTS-Dyn example: | ||
| 710 | + | ||
| 488 | <!--code_no_check--> | 711 | <!--code_no_check--> |
| 489 | 712 | ||
| 490 | ```ts | 713 | ```ts |
| @@ -497,22 +720,42 @@ subscriber.setCodeAndData(1, 'publish_data_changed', (err: BusinessError) => { | |||
| 497 | }); | 720 | }); |
| 498 | ``` | 721 | ``` |
| 499 | 722 | ||
| 723 | +ArkTS-Sta example: | ||
| 724 | + | ||
| 725 | +<!--code_no_check--> | ||
| 726 | + | ||
| 727 | +```ts | ||
| 728 | +subscriber.setCodeAndData(1, 'publish_data_changed', (err: BusinessError | null) => { | ||
| 729 | + if (err) { | ||
| 730 | + console.error(`Failed to set code and data. Code is ${err.code}, message is ${err.message}`); | ||
| 731 | + return; | ||
| 732 | + } | ||
| 733 | + console.info(`Succeeded in setting code and data.`); | ||
| 734 | +}); | ||
| 735 | +``` | ||
| 736 | + | ||
| 500 | ### setCodeAndData | 737 | ### setCodeAndData |
| 501 | 738 | ||
| 502 | -setCodeAndData(code: number, data: string): Promise\<void> | 739 | +ArkTS-Dyn: setCodeAndData(code: number, data: string): Promise\<void> |
| 740 | + | ||
| 741 | +ArkTS-Sta: setCodeAndData(code: int, data: string): Promise\<void> | ||
| 503 | 742 | ||
| 504 | Sets the result code and data of an ordered common event. This API uses a promise to return the result. | 743 | Sets the result code and data of an ordered common event. This API uses a promise to return the result. |
| 505 | 744 | ||
| 506 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 745 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 507 | 746 | ||
| 508 | **System capability**: SystemCapability.Notification.CommonEvent | 747 | **System capability**: SystemCapability.Notification.CommonEvent |
| 509 | 748 | ||
| 749 | +**ArkTS-Dyn start version:** 7 | ||
| 750 | + | ||
| 751 | +**ArkTS-Sta start version:** 23 | ||
| 752 | + | ||
| 510 | **Parameters** | 753 | **Parameters** |
| 511 | 754 | ||
| 512 | | Name| Type | Mandatory| Description | | 755 | | Name| Type | Mandatory| Description | |
| 513 | | ------ | ------ | ---- | -------------------- | | 756 | | ------ | ------ | ---- | -------------------- | |
| 514 | -| code | number | Yes | Result code of an ordered common event.| | 757 | +| code | ArkTS-Dyn: number<br/>ArkTS-Sta: int | Yes | Code delivered by the ordered common event. | |
| 515 | -| data | string | Yes | Result data of an ordered common event.| | 758 | +| data | string | Yes | Data delivered by the ordered common event. The value is a string containing a maximum of 65,536 characters. If the length exceeds the limit, the API setting becomes invalid. | |
| 516 | 759 | ||
| 517 | **Return value** | 760 | **Return value** |
| 518 | 761 | ||
| @@ -526,10 +769,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 526 | 769 | ||
| 527 | | ID| Error Message | | 770 | | ID| Error Message | |
| 528 | | -------- | ----------------------------------- | | 771 | | -------- | ----------------------------------- | |
| 529 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 772 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 530 | 773 | ||
| 531 | **Example** | 774 | **Example** |
| 532 | 775 | ||
| 776 | +ArkTS-Dyn example: | ||
| 777 | + | ||
| 533 | <!--code_no_check--> | 778 | <!--code_no_check--> |
| 534 | 779 | ||
| 535 | ```ts | 780 | ```ts |
| @@ -540,22 +785,39 @@ subscriber.setCodeAndData(1, 'publish_data_changed').then(() => { | |||
| 540 | }); | 785 | }); |
| 541 | ``` | 786 | ``` |
| 542 | 787 | ||
| 788 | +ArkTS-Sta example: | ||
| 789 | + | ||
| 790 | +```ts | ||
| 791 | +subscriber.setCodeAndData(1, 'publish_data_changed').then(() => { | ||
| 792 | + console.info(`Succeeded in setting code and data.`); | ||
| 793 | +}).catch((err: Error): void => { | ||
| 794 | + let error: BusinessError = err as BusinessError; | ||
| 795 | + console.error(`Failed to set code and data. Code is ${error.code}, message is ${error.message}`); | ||
| 796 | +}); | ||
| 797 | +``` | ||
| 798 | + | ||
| 543 | ### setCodeAndDataSync<sup>10+</sup> | 799 | ### setCodeAndDataSync<sup>10+</sup> |
| 544 | 800 | ||
| 545 | -setCodeAndDataSync(code: number, data: string): void | 801 | +ArkTS-Dyn: setCodeAndDataSync(code: number, data: string): void |
| 546 | 802 | ||
| 547 | -Sets the result code and data of an ordered common event. | 803 | +ArkTS-Sta: setCodeAndDataSync(code: int, data: string): void |
| 548 | 804 | ||
| 549 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 805 | +Sets the result code and data of an ordered common event. This API returns the result synchronously. |
| 806 | + | ||
| 807 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. | ||
| 550 | 808 | ||
| 551 | **System capability**: SystemCapability.Notification.CommonEvent | 809 | **System capability**: SystemCapability.Notification.CommonEvent |
| 552 | 810 | ||
| 811 | +**ArkTS-Dyn start version:** 10 | ||
| 812 | + | ||
| 813 | +**ArkTS-Sta start version:** 23 | ||
| 814 | + | ||
| 553 | **Parameters** | 815 | **Parameters** |
| 554 | 816 | ||
| 555 | | Name| Type | Mandatory| Description | | 817 | | Name| Type | Mandatory| Description | |
| 556 | | ------ | ------ | ---- | -------------------- | | 818 | | ------ | ------ | ---- | -------------------- | |
| 557 | -| code | number | Yes | Result code of an ordered common event.| | 819 | +| code | ArkTS-Dyn: number<br/>ArkTS-Sta: int | Yes | Code delivered by the ordered common event. | |
| 558 | -| data | string | Yes | Result data of an ordered common event.| | 820 | +| data | string | Yes | Data delivered by the ordered common event. The value is a string containing a maximum of 65,536 characters. If the length exceeds the limit, the API setting becomes invalid. | |
| 559 | 821 | ||
| 560 | **Error codes** | 822 | **Error codes** |
| 561 | 823 | ||
| @@ -563,7 +825,7 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 563 | 825 | ||
| 564 | | ID| Error Message | | 826 | | ID| Error Message | |
| 565 | | -------- | ----------------------------------- | | 827 | | -------- | ----------------------------------- | |
| 566 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 828 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 567 | 829 | ||
| 568 | **Example** | 830 | **Example** |
| 569 | 831 | ||
| @@ -587,11 +849,15 @@ Checks whether the current common event is an ordered common event. This API use | |||
| 587 | 849 | ||
| 588 | **System capability**: SystemCapability.Notification.CommonEvent | 850 | **System capability**: SystemCapability.Notification.CommonEvent |
| 589 | 851 | ||
| 852 | +**ArkTS-Dyn start version:** 7 | ||
| 853 | + | ||
| 854 | +**ArkTS-Sta start version:** 23 | ||
| 855 | + | ||
| 590 | **Parameters** | 856 | **Parameters** |
| 591 | 857 | ||
| 592 | | Name | Type | Mandatory| Description | | 858 | | Name | Type | Mandatory| Description | |
| 593 | | -------- | ----------------------- | ---- | ---------------------------------- | | 859 | | -------- | ----------------------- | ---- | ---------------------------------- | |
| 594 | -| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result. Returns **true** if the common event is an ordered one; returns **false** if the common event is an unordered one.| | 860 | +| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result. If the query is successful, **err** is **undefined**. If **data** is **true**, the common event is ordered; if **data** is **false**, the common event is not ordered. Otherwise, **err** is an error object. | |
| 595 | 861 | ||
| 596 | **Error codes** | 862 | **Error codes** |
| 597 | 863 | ||
| @@ -599,14 +865,30 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 599 | 865 | ||
| 600 | | ID| Error Message | | 866 | | ID| Error Message | |
| 601 | | -------- | ----------------------------------- | | 867 | | -------- | ----------------------------------- | |
| 602 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 868 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 603 | 869 | ||
| 604 | **Example** | 870 | **Example** |
| 605 | 871 | ||
| 872 | +ArkTS-Dyn example: | ||
| 873 | + | ||
| 606 | <!--code_no_check--> | 874 | <!--code_no_check--> |
| 607 | 875 | ||
| 608 | ```ts | 876 | ```ts |
| 609 | -subscriber.isOrderedCommonEvent((err: BusinessError, isOrdered:boolean) => { | 877 | +subscriber.isOrderedCommonEvent((err: BusinessError, isOrdered: boolean) => { |
| 878 | + if (err) { | ||
| 879 | + console.error(`isOrderedCommonEvent failed, code is ${err.code}, message is ${err.message}`); | ||
| 880 | + return; | ||
| 881 | + } | ||
| 882 | + console.info(`isOrderedCommonEvent ${JSON.stringify(isOrdered)}`); | ||
| 883 | +}); | ||
| 884 | +``` | ||
| 885 | + | ||
| 886 | +ArkTS-Sta example: | ||
| 887 | + | ||
| 888 | +<!--code_no_check--> | ||
| 889 | + | ||
| 890 | +```ts | ||
| 891 | +subscriber.isOrderedCommonEvent((err: BusinessError | null, isOrdered: boolean | undefined | null) => { | ||
| 610 | if (err) { | 892 | if (err) { |
| 611 | console.error(`isOrderedCommonEvent failed, code is ${err.code}, message is ${err.message}`); | 893 | console.error(`isOrderedCommonEvent failed, code is ${err.code}, message is ${err.message}`); |
| 612 | return; | 894 | return; |
| @@ -623,6 +905,10 @@ Checks whether the current common event is an ordered common event. This API use | |||
| 623 | 905 | ||
| 624 | **System capability**: SystemCapability.Notification.CommonEvent | 906 | **System capability**: SystemCapability.Notification.CommonEvent |
| 625 | 907 | ||
| 908 | +**ArkTS-Dyn start version:** 7 | ||
| 909 | + | ||
| 910 | +**ArkTS-Sta start version:** 23 | ||
| 911 | + | ||
| 626 | **Return value** | 912 | **Return value** |
| 627 | 913 | ||
| 628 | | Type | Description | | 914 | | Type | Description | |
| @@ -631,24 +917,43 @@ Checks whether the current common event is an ordered common event. This API use | |||
| 631 | 917 | ||
| 632 | **Example** | 918 | **Example** |
| 633 | 919 | ||
| 920 | +ArkTS-Dyn example: | ||
| 921 | + | ||
| 634 | <!--code_no_check--> | 922 | <!--code_no_check--> |
| 635 | 923 | ||
| 636 | ```ts | 924 | ```ts |
| 637 | -subscriber.isOrderedCommonEvent().then((isOrdered:boolean) => { | 925 | +subscriber.isOrderedCommonEvent().then((isOrdered: boolean) => { |
| 638 | console.info(`isOrderedCommonEvent ${JSON.stringify(isOrdered)}`); | 926 | console.info(`isOrderedCommonEvent ${JSON.stringify(isOrdered)}`); |
| 639 | }).catch((err: BusinessError) => { | 927 | }).catch((err: BusinessError) => { |
| 640 | console.error(`isOrderedCommonEvent failed, code is ${err.code}, message is ${err.message}`); | 928 | console.error(`isOrderedCommonEvent failed, code is ${err.code}, message is ${err.message}`); |
| 641 | }); | 929 | }); |
| 642 | ``` | 930 | ``` |
| 643 | 931 | ||
| 932 | +ArkTS-Sta example: | ||
| 933 | + | ||
| 934 | +<!--code_no_check--> | ||
| 935 | + | ||
| 936 | +```ts | ||
| 937 | +subscriber.isOrderedCommonEvent().then((isOrdered: boolean) => { | ||
| 938 | + console.info(`isOrderedCommonEvent ${JSON.stringify(isOrdered)}`); | ||
| 939 | +}).catch((err: Error): void => { | ||
| 940 | + let error: BusinessError = err as BusinessError; | ||
| 941 | + console.error(`isOrderedCommonEvent failed, code is ${error.code}, message is ${error.message}`); | ||
| 942 | +}); | ||
| 943 | +``` | ||
| 944 | + | ||
| 644 | ### isOrderedCommonEventSync<sup>10+</sup> | 945 | ### isOrderedCommonEventSync<sup>10+</sup> |
| 645 | 946 | ||
| 646 | isOrderedCommonEventSync(): boolean | 947 | isOrderedCommonEventSync(): boolean |
| 647 | 948 | ||
| 648 | -Checks whether the current common event is an ordered common event. | 949 | +Checks whether a common event is an ordered common event. This API returns the result synchronously. |
| 649 | 950 | ||
| 650 | **System capability**: SystemCapability.Notification.CommonEvent | 951 | **System capability**: SystemCapability.Notification.CommonEvent |
| 651 | 952 | ||
| 953 | +**ArkTS-Dyn start version:** 10 | ||
| 954 | + | ||
| 955 | +**ArkTS-Sta start version:** 23 | ||
| 956 | + | ||
| 652 | **Return value** | 957 | **Return value** |
| 653 | 958 | ||
| 654 | | Type | Description | | 959 | | Type | Description | |
| @@ -668,15 +973,19 @@ console.info(`isOrderedCommonEventSync ${JSON.stringify(isOrdered)}`); | |||
| 668 | 973 | ||
| 669 | isStickyCommonEvent(callback: AsyncCallback\<boolean>): void | 974 | isStickyCommonEvent(callback: AsyncCallback\<boolean>): void |
| 670 | 975 | ||
| 671 | -Checks whether a common event is a sticky one. This API uses an asynchronous callback to return the result. | 976 | +Checks whether the current common event is a sticky common event. This API uses an asynchronous callback to return the result. |
| 672 | 977 | ||
| 673 | **System capability**: SystemCapability.Notification.CommonEvent | 978 | **System capability**: SystemCapability.Notification.CommonEvent |
| 674 | 979 | ||
| 980 | +**ArkTS-Dyn start version:** 7 | ||
| 981 | + | ||
| 982 | +**ArkTS-Sta start version:** 23 | ||
| 983 | + | ||
| 675 | **Parameters** | 984 | **Parameters** |
| 676 | 985 | ||
| 677 | | Name | Type | Mandatory| Description | | 986 | | Name | Type | Mandatory| Description | |
| 678 | | -------- | ----------------------- | ---- | ---------------------------------- | | 987 | | -------- | ----------------------- | ---- | ---------------------------------- | |
| 679 | -| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result. Returns **true** if the common event is a sticky one; returns **false** otherwise.| | 988 | +| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result. If the query is successful, **err** is **undefined**. If **data** is **true**, the common event is sticky; if **data** is **false**, the common event is not sticky. Otherwise, **err** is an error object. | |
| 680 | 989 | ||
| 681 | **Error codes** | 990 | **Error codes** |
| 682 | 991 | ||
| @@ -684,14 +993,30 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 684 | 993 | ||
| 685 | | ID| Error Message | | 994 | | ID| Error Message | |
| 686 | | -------- | ----------------------------------- | | 995 | | -------- | ----------------------------------- | |
| 687 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 996 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 688 | 997 | ||
| 689 | **Example** | 998 | **Example** |
| 690 | 999 | ||
| 1000 | +ArkTS-Dyn example: | ||
| 1001 | + | ||
| 691 | <!--code_no_check--> | 1002 | <!--code_no_check--> |
| 692 | 1003 | ||
| 693 | ```ts | 1004 | ```ts |
| 694 | -subscriber.isStickyCommonEvent((err: BusinessError, isSticky:boolean) => { | 1005 | +subscriber.isStickyCommonEvent((err: BusinessError, isSticky: boolean) => { |
| 1006 | + if (err) { | ||
| 1007 | + console.error(`isStickyCommonEvent failed, code is ${err.code}, message is ${err.message}`); | ||
| 1008 | + return; | ||
| 1009 | + } | ||
| 1010 | + console.info(`isStickyCommonEvent ${JSON.stringify(isSticky)}`); | ||
| 1011 | +}); | ||
| 1012 | +``` | ||
| 1013 | + | ||
| 1014 | +ArkTS-Sta example: | ||
| 1015 | + | ||
| 1016 | +<!--code_no_check--> | ||
| 1017 | + | ||
| 1018 | +```ts | ||
| 1019 | +subscriber.isStickyCommonEvent((err: BusinessError | null, isSticky: boolean | undefined | null) => { | ||
| 695 | if (err) { | 1020 | if (err) { |
| 696 | console.error(`isStickyCommonEvent failed, code is ${err.code}, message is ${err.message}`); | 1021 | console.error(`isStickyCommonEvent failed, code is ${err.code}, message is ${err.message}`); |
| 697 | return; | 1022 | return; |
| @@ -704,10 +1029,14 @@ subscriber.isStickyCommonEvent((err: BusinessError, isSticky:boolean) => { | |||
| 704 | 1029 | ||
| 705 | isStickyCommonEvent(): Promise\<boolean> | 1030 | isStickyCommonEvent(): Promise\<boolean> |
| 706 | 1031 | ||
| 707 | -Checks whether a common event is a sticky one. This API uses a promise to return the result. | 1032 | +Checks whether the current common event is a sticky common event. This API uses a promise to return the result. |
| 708 | 1033 | ||
| 709 | **System capability**: SystemCapability.Notification.CommonEvent | 1034 | **System capability**: SystemCapability.Notification.CommonEvent |
| 710 | 1035 | ||
| 1036 | +**ArkTS-Dyn start version:** 7 | ||
| 1037 | + | ||
| 1038 | +**ArkTS-Sta start version:** 23 | ||
| 1039 | + | ||
| 711 | **Return value** | 1040 | **Return value** |
| 712 | 1041 | ||
| 713 | | Type | Description | | 1042 | | Type | Description | |
| @@ -716,24 +1045,43 @@ Checks whether a common event is a sticky one. This API uses a promise to return | |||
| 716 | 1045 | ||
| 717 | **Example** | 1046 | **Example** |
| 718 | 1047 | ||
| 1048 | +ArkTS-Dyn example: | ||
| 1049 | + | ||
| 719 | <!--code_no_check--> | 1050 | <!--code_no_check--> |
| 720 | 1051 | ||
| 721 | ```ts | 1052 | ```ts |
| 722 | -subscriber.isStickyCommonEvent().then((isSticky:boolean) => { | 1053 | +subscriber.isStickyCommonEvent().then((isSticky: boolean) => { |
| 723 | console.info(`isStickyCommonEvent ${JSON.stringify(isSticky)}`); | 1054 | console.info(`isStickyCommonEvent ${JSON.stringify(isSticky)}`); |
| 724 | }).catch((err: BusinessError) => { | 1055 | }).catch((err: BusinessError) => { |
| 725 | console.error(`isStickyCommonEvent failed, code is ${err.code}, message is ${err.message}`); | 1056 | console.error(`isStickyCommonEvent failed, code is ${err.code}, message is ${err.message}`); |
| 726 | }); | 1057 | }); |
| 727 | ``` | 1058 | ``` |
| 728 | 1059 | ||
| 1060 | +ArkTS-Sta example: | ||
| 1061 | + | ||
| 1062 | +<!--code_no_check--> | ||
| 1063 | + | ||
| 1064 | +```ts | ||
| 1065 | +subscriber.isStickyCommonEvent().then((isSticky: boolean) => { | ||
| 1066 | + console.info(`isStickyCommonEvent ${JSON.stringify(isSticky)}`); | ||
| 1067 | +}).catch((err: Error): void => { | ||
| 1068 | + let error: BusinessError = err as BusinessError; | ||
| 1069 | + console.error(`isStickyCommonEvent failed, code is ${error.code}, message is ${error.message}`); | ||
| 1070 | +}); | ||
| 1071 | +``` | ||
| 1072 | + | ||
| 729 | ### isStickyCommonEventSync<sup>10+</sup> | 1073 | ### isStickyCommonEventSync<sup>10+</sup> |
| 730 | 1074 | ||
| 731 | isStickyCommonEventSync(): boolean | 1075 | isStickyCommonEventSync(): boolean |
| 732 | 1076 | ||
| 733 | -Checks whether a common event is a sticky one. | 1077 | +Checks whether the current common event is a sticky common event. This API returns the result synchronously. |
| 734 | 1078 | ||
| 735 | **System capability**: SystemCapability.Notification.CommonEvent | 1079 | **System capability**: SystemCapability.Notification.CommonEvent |
| 736 | 1080 | ||
| 1081 | +**ArkTS-Dyn start version:** 10 | ||
| 1082 | + | ||
| 1083 | +**ArkTS-Sta start version:** 23 | ||
| 1084 | + | ||
| 737 | **Return value** | 1085 | **Return value** |
| 738 | 1086 | ||
| 739 | | Type | Description | | 1087 | | Type | Description | |
| @@ -757,6 +1105,10 @@ Aborts an ordered common event. This API is used with [finishCommonEvent](#finis | |||
| 757 | 1105 | ||
| 758 | **System capability**: SystemCapability.Notification.CommonEvent | 1106 | **System capability**: SystemCapability.Notification.CommonEvent |
| 759 | 1107 | ||
| 1108 | +**ArkTS-Dyn start version:** 7 | ||
| 1109 | + | ||
| 1110 | +**ArkTS-Sta start version:** 23 | ||
| 1111 | + | ||
| 760 | **Parameters** | 1112 | **Parameters** |
| 761 | 1113 | ||
| 762 | | Name | Type | Mandatory| Description | | 1114 | | Name | Type | Mandatory| Description | |
| @@ -769,10 +1121,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 769 | 1121 | ||
| 770 | | ID| Error Message | | 1122 | | ID| Error Message | |
| 771 | | -------- | ----------------------------------- | | 1123 | | -------- | ----------------------------------- | |
| 772 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 1124 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 773 | 1125 | ||
| 774 | **Example** | 1126 | **Example** |
| 775 | 1127 | ||
| 1128 | +ArkTS-Dyn example: | ||
| 1129 | + | ||
| 776 | <!--code_no_check--> | 1130 | <!--code_no_check--> |
| 777 | 1131 | ||
| 778 | ```ts | 1132 | ```ts |
| @@ -792,6 +1146,25 @@ subscriber.finishCommonEvent((err: BusinessError) => { | |||
| 792 | }); | 1146 | }); |
| 793 | ``` | 1147 | ``` |
| 794 | 1148 | ||
| 1149 | +ArkTS-Sta example: | ||
| 1150 | + | ||
| 1151 | +```ts | ||
| 1152 | +subscriber.abortCommonEvent((err: BusinessError | null) => { | ||
| 1153 | + if (err) { | ||
| 1154 | + console.error(`Failed to abort common event. Code is ${err.code}, message is ${err.message}`); | ||
| 1155 | + return; | ||
| 1156 | + } | ||
| 1157 | + console.info(`Succeeded in aborting common event.`); | ||
| 1158 | +}); | ||
| 1159 | +subscriber.finishCommonEvent((err: BusinessError | null) => { | ||
| 1160 | + if (err) { | ||
| 1161 | + console.error(`Failed to finish common event. Code is ${err.code}, message is ${err.message}`); | ||
| 1162 | + return; | ||
| 1163 | + } | ||
| 1164 | + console.info(`Succeeded in finishing common event.`); | ||
| 1165 | +}); | ||
| 1166 | +``` | ||
| 1167 | + | ||
| 795 | ### abortCommonEvent | 1168 | ### abortCommonEvent |
| 796 | 1169 | ||
| 797 | abortCommonEvent(): Promise\<void> | 1170 | abortCommonEvent(): Promise\<void> |
| @@ -800,6 +1173,10 @@ Aborts this ordered common event. This API is used with [finishCommonEvent](#fin | |||
| 800 | 1173 | ||
| 801 | **System capability**: SystemCapability.Notification.CommonEvent | 1174 | **System capability**: SystemCapability.Notification.CommonEvent |
| 802 | 1175 | ||
| 1176 | +**ArkTS-Dyn start version:** 7 | ||
| 1177 | + | ||
| 1178 | +**ArkTS-Sta start version:** 23 | ||
| 1179 | + | ||
| 803 | **Return value** | 1180 | **Return value** |
| 804 | 1181 | ||
| 805 | | Type | Description | | 1182 | | Type | Description | |
| @@ -808,6 +1185,8 @@ Aborts this ordered common event. This API is used with [finishCommonEvent](#fin | |||
| 808 | 1185 | ||
| 809 | **Example** | 1186 | **Example** |
| 810 | 1187 | ||
| 1188 | +ArkTS-Dyn example: | ||
| 1189 | + | ||
| 811 | <!--code_no_check--> | 1190 | <!--code_no_check--> |
| 812 | 1191 | ||
| 813 | ```ts | 1192 | ```ts |
| @@ -823,16 +1202,41 @@ subscriber.finishCommonEvent().then(() => { | |||
| 823 | }); | 1202 | }); |
| 824 | ``` | 1203 | ``` |
| 825 | 1204 | ||
| 1205 | +ArkTS-Sta example: | ||
| 1206 | + | ||
| 1207 | +<!--code_no_check--> | ||
| 1208 | + | ||
| 1209 | +```ts | ||
| 1210 | +subscriber.abortCommonEvent().then(() => { | ||
| 1211 | + console.info(`Succeeded in aborting common event.`); | ||
| 1212 | +}).catch((err: Error): void => { | ||
| 1213 | + let error: BusinessError = err as BusinessError; | ||
| 1214 | + console.error(`Failed to abort common event. Code is ${error.code}, message is ${error.message}`); | ||
| 1215 | +}); | ||
| 1216 | +subscriber.finishCommonEvent().then(() => { | ||
| 1217 | + console.info(`Succeeded in finishing common event.`); | ||
| 1218 | +}).catch((err: Error): void => { | ||
| 1219 | + let error: BusinessError = err as BusinessError; | ||
| 1220 | + console.error(`Failed to finish common event. Code is ${error.code}, message is ${error.message}`); | ||
| 1221 | +}); | ||
| 1222 | +``` | ||
| 1223 | + | ||
| 826 | ### abortCommonEventSync<sup>10+</sup> | 1224 | ### abortCommonEventSync<sup>10+</sup> |
| 827 | 1225 | ||
| 828 | abortCommonEventSync(): void | 1226 | abortCommonEventSync(): void |
| 829 | 1227 | ||
| 830 | -Aborts this ordered common event synchronously. This API is used with [finishCommonEvent](#finishcommonevent9). After the abort, the common event is not sent to the next subscriber. | 1228 | +Aborts an ordered common event when used with [finishCommonEvent](#finishcommonevent9). With the abort state, the common event is not sent to the next subscriber. This API returns the result synchronously. |
| 831 | 1229 | ||
| 832 | **System capability**: SystemCapability.Notification.CommonEvent | 1230 | **System capability**: SystemCapability.Notification.CommonEvent |
| 833 | 1231 | ||
| 1232 | +**ArkTS-Dyn start version:** 10 | ||
| 1233 | + | ||
| 1234 | +**ArkTS-Sta start version:** 23 | ||
| 1235 | + | ||
| 834 | **Example** | 1236 | **Example** |
| 835 | 1237 | ||
| 1238 | +ArkTS-Dyn example: | ||
| 1239 | + | ||
| 836 | <!--code_no_check--> | 1240 | <!--code_no_check--> |
| 837 | 1241 | ||
| 838 | ```ts | 1242 | ```ts |
| @@ -844,6 +1248,20 @@ subscriber.finishCommonEvent().then(() => { | |||
| 844 | }); | 1248 | }); |
| 845 | ``` | 1249 | ``` |
| 846 | 1250 | ||
| 1251 | +ArkTS-Sta example: | ||
| 1252 | + | ||
| 1253 | +<!--code_no_check--> | ||
| 1254 | + | ||
| 1255 | +```ts | ||
| 1256 | +subscriber.abortCommonEventSync(); | ||
| 1257 | +subscriber.finishCommonEvent().then(() => { | ||
| 1258 | + console.info(`Succeeded in finishing common event.`); | ||
| 1259 | +}).catch((err: Error): void => { | ||
| 1260 | + let error: BusinessError = err as BusinessError; | ||
| 1261 | + console.error(`Failed to finish common event. Code is ${error.code}, message is ${error.message}`); | ||
| 1262 | +}); | ||
| 1263 | +``` | ||
| 1264 | + | ||
| 847 | ### clearAbortCommonEvent | 1265 | ### clearAbortCommonEvent |
| 848 | 1266 | ||
| 849 | clearAbortCommonEvent(callback: AsyncCallback\<void>): void | 1267 | clearAbortCommonEvent(callback: AsyncCallback\<void>): void |
| @@ -852,6 +1270,10 @@ Clears the abort state of an ordered common event. Use this API together with [f | |||
| 852 | 1270 | ||
| 853 | **System capability**: SystemCapability.Notification.CommonEvent | 1271 | **System capability**: SystemCapability.Notification.CommonEvent |
| 854 | 1272 | ||
| 1273 | +**ArkTS-Dyn start version:** 7 | ||
| 1274 | + | ||
| 1275 | +**ArkTS-Sta start version:** 23 | ||
| 1276 | + | ||
| 855 | **Parameters** | 1277 | **Parameters** |
| 856 | 1278 | ||
| 857 | | Name | Type | Mandatory| Description | | 1279 | | Name | Type | Mandatory| Description | |
| @@ -864,10 +1286,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 864 | 1286 | ||
| 865 | | ID| Error Message | | 1287 | | ID| Error Message | |
| 866 | | -------- | ----------------------------------- | | 1288 | | -------- | ----------------------------------- | |
| 867 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 1289 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 868 | 1290 | ||
| 869 | **Example** | 1291 | **Example** |
| 870 | 1292 | ||
| 1293 | +ArkTS-Dyn example: | ||
| 1294 | + | ||
| 871 | <!--code_no_check--> | 1295 | <!--code_no_check--> |
| 872 | 1296 | ||
| 873 | ```ts | 1297 | ```ts |
| @@ -887,6 +1311,27 @@ subscriber.finishCommonEvent((err: BusinessError) => { | |||
| 887 | }); | 1311 | }); |
| 888 | ``` | 1312 | ``` |
| 889 | 1313 | ||
| 1314 | +ArkTS-Sta example: | ||
| 1315 | + | ||
| 1316 | +<!--code_no_check--> | ||
| 1317 | + | ||
| 1318 | +```ts | ||
| 1319 | +subscriber.clearAbortCommonEvent((err: BusinessError | null) => { | ||
| 1320 | + if (err) { | ||
| 1321 | + console.error(`Failed to clear abort common event. Code is ${err.code}, message is ${err.message}`); | ||
| 1322 | + return; | ||
| 1323 | + } | ||
| 1324 | + console.info(`Succeeded in clearing abort common event.`); | ||
| 1325 | +}); | ||
| 1326 | +subscriber.finishCommonEvent((err: BusinessError | null) => { | ||
| 1327 | + if (err) { | ||
| 1328 | + console.error(`Failed to finish common event. Code is ${err.code}, message is ${err.message}`); | ||
| 1329 | + return; | ||
| 1330 | + } | ||
| 1331 | + console.info(`Succeeded in finishing common event.`); | ||
| 1332 | +}); | ||
| 1333 | +``` | ||
| 1334 | + | ||
| 890 | ### clearAbortCommonEvent | 1335 | ### clearAbortCommonEvent |
| 891 | 1336 | ||
| 892 | clearAbortCommonEvent(): Promise\<void> | 1337 | clearAbortCommonEvent(): Promise\<void> |
| @@ -895,6 +1340,10 @@ Clears the abort state of this ordered common event. Use this API together with | |||
| 895 | 1340 | ||
| 896 | **System capability**: SystemCapability.Notification.CommonEvent | 1341 | **System capability**: SystemCapability.Notification.CommonEvent |
| 897 | 1342 | ||
| 1343 | +**ArkTS-Dyn start version:** 7 | ||
| 1344 | + | ||
| 1345 | +**ArkTS-Sta start version:** 23 | ||
| 1346 | + | ||
| 898 | **Return value** | 1347 | **Return value** |
| 899 | 1348 | ||
| 900 | | Type | Description | | 1349 | | Type | Description | |
| @@ -903,6 +1352,8 @@ Clears the abort state of this ordered common event. Use this API together with | |||
| 903 | 1352 | ||
| 904 | **Example** | 1353 | **Example** |
| 905 | 1354 | ||
| 1355 | +ArkTS-Dyn example: | ||
| 1356 | + | ||
| 906 | <!--code_no_check--> | 1357 | <!--code_no_check--> |
| 907 | 1358 | ||
| 908 | ```ts | 1359 | ```ts |
| @@ -918,16 +1369,41 @@ subscriber.finishCommonEvent().then(() => { | |||
| 918 | }); | 1369 | }); |
| 919 | ``` | 1370 | ``` |
| 920 | 1371 | ||
| 1372 | +ArkTS-Sta example: | ||
| 1373 | + | ||
| 1374 | +<!--code_no_check--> | ||
| 1375 | + | ||
| 1376 | +```ts | ||
| 1377 | +subscriber.clearAbortCommonEvent().then(() => { | ||
| 1378 | + console.info(`Succeeded in clearing abort common event.`); | ||
| 1379 | +}).catch((err: Error): void => { | ||
| 1380 | + let error: BusinessError = err as BusinessError; | ||
| 1381 | + console.error(`Failed to clear abort common event. Code is ${error.code}, message is ${error.message}`); | ||
| 1382 | +}); | ||
| 1383 | +subscriber.finishCommonEvent().then(() => { | ||
| 1384 | + console.info(`Succeeded in finishing common event.`); | ||
| 1385 | +}).catch((err: Error): void => { | ||
| 1386 | + let error: BusinessError = err as BusinessError; | ||
| 1387 | + console.error(`Failed to finish common event. Code is ${error.code}, message is ${error.message}`); | ||
| 1388 | +}); | ||
| 1389 | +``` | ||
| 1390 | + | ||
| 921 | ### clearAbortCommonEventSync<sup>10+</sup> | 1391 | ### clearAbortCommonEventSync<sup>10+</sup> |
| 922 | 1392 | ||
| 923 | clearAbortCommonEventSync(): void | 1393 | clearAbortCommonEventSync(): void |
| 924 | 1394 | ||
| 925 | -Clears the abort state of this ordered common event. Use this API together with [finishCommonEvent](#finishcommonevent9), and the common event can be passed to the next subscriber. | 1395 | +Clears the abort state of an ordered common event when used with [finishCommonEvent](#finishcommonevent9). After the clearance, the common event is sent to the next subscriber. This API returns the result synchronously. |
| 926 | 1396 | ||
| 927 | **System capability**: SystemCapability.Notification.CommonEvent | 1397 | **System capability**: SystemCapability.Notification.CommonEvent |
| 928 | 1398 | ||
| 1399 | +**ArkTS-Dyn start version:** 10 | ||
| 1400 | + | ||
| 1401 | +**ArkTS-Sta start version:** 23 | ||
| 1402 | + | ||
| 929 | **Example** | 1403 | **Example** |
| 930 | 1404 | ||
| 1405 | +ArkTS-Dyn example: | ||
| 1406 | + | ||
| 931 | <!--code_no_check--> | 1407 | <!--code_no_check--> |
| 932 | 1408 | ||
| 933 | ```ts | 1409 | ```ts |
| @@ -939,6 +1415,20 @@ subscriber.finishCommonEvent().then(() => { | |||
| 939 | }); | 1415 | }); |
| 940 | ``` | 1416 | ``` |
| 941 | 1417 | ||
| 1418 | +ArkTS-Sta example: | ||
| 1419 | + | ||
| 1420 | +<!--code_no_check--> | ||
| 1421 | + | ||
| 1422 | +```ts | ||
| 1423 | +subscriber.clearAbortCommonEventSync(); | ||
| 1424 | +subscriber.finishCommonEvent().then(() => { | ||
| 1425 | + console.info(`Succeeded in finishing common event.`); | ||
| 1426 | +}).catch((err: Error): void => { | ||
| 1427 | + let error: BusinessError = err as BusinessError; | ||
| 1428 | + console.error(`Failed to finish common event. Code is ${error.code}, message is ${error.message}`); | ||
| 1429 | +}); | ||
| 1430 | +``` | ||
| 1431 | + | ||
| 942 | ### getAbortCommonEvent | 1432 | ### getAbortCommonEvent |
| 943 | 1433 | ||
| 944 | getAbortCommonEvent(callback: AsyncCallback\<boolean>): void | 1434 | getAbortCommonEvent(callback: AsyncCallback\<boolean>): void |
| @@ -947,11 +1437,15 @@ Checks whether this ordered common event should be aborted. This API uses an asy | |||
| 947 | 1437 | ||
| 948 | **System capability**: SystemCapability.Notification.CommonEvent | 1438 | **System capability**: SystemCapability.Notification.CommonEvent |
| 949 | 1439 | ||
| 1440 | +**ArkTS-Dyn start version:** 7 | ||
| 1441 | + | ||
| 1442 | +**ArkTS-Sta start version:** 23 | ||
| 1443 | + | ||
| 950 | **Parameters** | 1444 | **Parameters** |
| 951 | 1445 | ||
| 952 | | Name | Type | Mandatory| Description | | 1446 | | Name | Type | Mandatory| Description | |
| 953 | | -------- | ----------------------- | ---- | ---------------------------------- | | 1447 | | -------- | ----------------------- | ---- | ---------------------------------- | |
| 954 | -| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result. Returns **true** if the ordered common event is in the abort state; returns **false** otherwise.| | 1448 | +| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result. If the query is successful, **err** is **undefined** and **data** is **true** if the current ordered common event is in the abort state, or **false** if the current ordered common event is not in the abort state. If the operation fails, **err** is an error object. | |
| 955 | 1449 | ||
| 956 | **Error codes** | 1450 | **Error codes** |
| 957 | 1451 | ||
| @@ -959,10 +1453,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 959 | 1453 | ||
| 960 | | ID| Error Message | | 1454 | | ID| Error Message | |
| 961 | | -------- | ----------------------------------- | | 1455 | | -------- | ----------------------------------- | |
| 962 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 1456 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 963 | 1457 | ||
| 964 | **Example** | 1458 | **Example** |
| 965 | 1459 | ||
| 1460 | +ArkTS-Dyn example: | ||
| 1461 | + | ||
| 966 | <!--code_no_check--> | 1462 | <!--code_no_check--> |
| 967 | 1463 | ||
| 968 | ```ts | 1464 | ```ts |
| @@ -975,6 +1471,20 @@ subscriber.getAbortCommonEvent((err: BusinessError, abortEvent: boolean) => { | |||
| 975 | }); | 1471 | }); |
| 976 | ``` | 1472 | ``` |
| 977 | 1473 | ||
| 1474 | +ArkTS-Sta example: | ||
| 1475 | + | ||
| 1476 | +<!--code_no_check--> | ||
| 1477 | + | ||
| 1478 | +```ts | ||
| 1479 | +subscriber.getAbortCommonEvent((err: BusinessError | null, abortEvent: boolean | undefined | null) => { | ||
| 1480 | + if (err) { | ||
| 1481 | + console.error(`Failed to get abort common event. Code is ${err.code}, message is ${err.message}`); | ||
| 1482 | + return; | ||
| 1483 | + } | ||
| 1484 | + console.info(`Succeeded in getting abort common event, abortEvent is ${JSON.stringify(abortEvent)}`); | ||
| 1485 | +}); | ||
| 1486 | +``` | ||
| 1487 | + | ||
| 978 | ### getAbortCommonEvent | 1488 | ### getAbortCommonEvent |
| 979 | 1489 | ||
| 980 | getAbortCommonEvent(): Promise\<boolean> | 1490 | getAbortCommonEvent(): Promise\<boolean> |
| @@ -983,14 +1493,20 @@ Checks whether this ordered common event should be aborted. This API uses a prom | |||
| 983 | 1493 | ||
| 984 | **System capability**: SystemCapability.Notification.CommonEvent | 1494 | **System capability**: SystemCapability.Notification.CommonEvent |
| 985 | 1495 | ||
| 1496 | +**ArkTS-Dyn start version:** 7 | ||
| 1497 | + | ||
| 1498 | +**ArkTS-Sta start version:** 23 | ||
| 1499 | + | ||
| 986 | **Return value** | 1500 | **Return value** |
| 987 | 1501 | ||
| 988 | | Type | Description | | 1502 | | Type | Description | |
| 989 | | ----------------- | ---------------------------------- | | 1503 | | ----------------- | ---------------------------------- | |
| 990 | -| Promise\<boolean> | Promise used to return the result. Returns **true** if the ordered common event is in the abort state; returns **false** otherwise.| | 1504 | +| Promise\<boolean> | Promise used to return the result. The **true** indicates that the ordered common event is in the abort state; the value **false** indicates otherwise. | |
| 991 | 1505 | ||
| 992 | **Example** | 1506 | **Example** |
| 993 | 1507 | ||
| 1508 | +ArkTS-Dyn example: | ||
| 1509 | + | ||
| 994 | <!--code_no_check--> | 1510 | <!--code_no_check--> |
| 995 | 1511 | ||
| 996 | ```ts | 1512 | ```ts |
| @@ -1001,19 +1517,36 @@ subscriber.getAbortCommonEvent().then((abortEvent: boolean) => { | |||
| 1001 | }); | 1517 | }); |
| 1002 | ``` | 1518 | ``` |
| 1003 | 1519 | ||
| 1520 | +ArkTS-Sta example: | ||
| 1521 | + | ||
| 1522 | +<!--code_no_check--> | ||
| 1523 | + | ||
| 1524 | +```ts | ||
| 1525 | +subscriber.getAbortCommonEvent().then((abortEvent: boolean) => { | ||
| 1526 | + console.info(`Succeeded in getting abort common event, abortEvent is ${JSON.stringify(abortEvent)}`); | ||
| 1527 | +}).catch((err: Error): void => { | ||
| 1528 | + let error: BusinessError = err as BusinessError; | ||
| 1529 | + console.error(`Failed to get abort common event. Code is ${error.code}, message is ${error.message}`); | ||
| 1530 | +}); | ||
| 1531 | +``` | ||
| 1532 | + | ||
| 1004 | ### getAbortCommonEventSync<sup>10+</sup> | 1533 | ### getAbortCommonEventSync<sup>10+</sup> |
| 1005 | 1534 | ||
| 1006 | getAbortCommonEventSync(): boolean | 1535 | getAbortCommonEventSync(): boolean |
| 1007 | 1536 | ||
| 1008 | -Checks whether this ordered common event should be aborted. | 1537 | +Checks whether an ordered common event is aborted. This API returns the result synchronously. |
| 1009 | 1538 | ||
| 1010 | **System capability**: SystemCapability.Notification.CommonEvent | 1539 | **System capability**: SystemCapability.Notification.CommonEvent |
| 1011 | 1540 | ||
| 1541 | +**ArkTS-Dyn start version:** 10 | ||
| 1542 | + | ||
| 1543 | +**ArkTS-Sta start version:** 23 | ||
| 1544 | + | ||
| 1012 | **Return value** | 1545 | **Return value** |
| 1013 | 1546 | ||
| 1014 | | Type | Description | | 1547 | | Type | Description | |
| 1015 | | ----------------- | ---------------------------------- | | 1548 | | ----------------- | ---------------------------------- | |
| 1016 | -| boolean |Returns **true** if the ordered common event is in the abort state; returns **false** otherwise.| | 1549 | +| boolean | The value **true** indicates that the ordered common event is in the abort state; the value **false** indicates otherwise. | |
| 1017 | 1550 | ||
| 1018 | **Example** | 1551 | **Example** |
| 1019 | 1552 | ||
| @@ -1030,15 +1563,19 @@ getSubscribeInfo(callback: AsyncCallback\<CommonEventSubscribeInfo>): void | |||
| 1030 | 1563 | ||
| 1031 | Obtains the subscriber information. This API uses an asynchronous callback to return the result. | 1564 | Obtains the subscriber information. This API uses an asynchronous callback to return the result. |
| 1032 | 1565 | ||
| 1033 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 1566 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 1034 | 1567 | ||
| 1035 | **System capability**: SystemCapability.Notification.CommonEvent | 1568 | **System capability**: SystemCapability.Notification.CommonEvent |
| 1036 | 1569 | ||
| 1570 | +**ArkTS-Dyn start version:** 7 | ||
| 1571 | + | ||
| 1572 | +**ArkTS-Sta start version:** 23 | ||
| 1573 | + | ||
| 1037 | **Parameters** | 1574 | **Parameters** |
| 1038 | 1575 | ||
| 1039 | | Name | Type | Mandatory| Description | | 1576 | | Name | Type | Mandatory| Description | |
| 1040 | | -------- | ------------------------------------------------------------ | ---- | ---------------------- | | 1577 | | -------- | ------------------------------------------------------------ | ---- | ---------------------- | |
| 1041 | -| callback | AsyncCallback\<[CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md)> | Yes | Callback used to return the result.| | 1578 | +| callback | AsyncCallback\<[CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md)> | Yes | Callback used to return the result. If the subscriber information is successfully obtained, **err** is **undefined** and **data** is the subscription information of the subscriber. Otherwise, **err** is an error object. | |
| 1042 | 1579 | ||
| 1043 | **Error codes** | 1580 | **Error codes** |
| 1044 | 1581 | ||
| @@ -1046,10 +1583,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 1046 | 1583 | ||
| 1047 | | ID| Error Message | | 1584 | | ID| Error Message | |
| 1048 | | -------- | ----------------------------------- | | 1585 | | -------- | ----------------------------------- | |
| 1049 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 1586 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 1050 | 1587 | ||
| 1051 | **Example** | 1588 | **Example** |
| 1052 | 1589 | ||
| 1590 | +ArkTS-Dyn example: | ||
| 1591 | + | ||
| 1053 | <!--code_no_check--> | 1592 | <!--code_no_check--> |
| 1054 | 1593 | ||
| 1055 | ```ts | 1594 | ```ts |
| @@ -1062,24 +1601,46 @@ subscriber.getSubscribeInfo((err: BusinessError, subscribeInfo: commonEventManag | |||
| 1062 | }); | 1601 | }); |
| 1063 | ``` | 1602 | ``` |
| 1064 | 1603 | ||
| 1604 | +ArkTS-Sta example: | ||
| 1605 | + | ||
| 1606 | +<!--code_no_check--> | ||
| 1607 | + | ||
| 1608 | +```ts | ||
| 1609 | +subscriber.getSubscribeInfo((err: BusinessError | null, subscribeInfo: commonEventManager.CommonEventSubscribeInfo | undefined | null) => { | ||
| 1610 | + if (err) { | ||
| 1611 | + console.error(`Failed to get subscribe info. Code is ${err.code}, message is ${err.message}`); | ||
| 1612 | + return; | ||
| 1613 | + } | ||
| 1614 | + console.info(`Succeeded in getting subscribe info, subscribe info is ${JSON.stringify(subscribeInfo)}`); | ||
| 1615 | +}); | ||
| 1616 | +``` | ||
| 1617 | + | ||
| 1065 | ### getSubscribeInfo | 1618 | ### getSubscribeInfo |
| 1066 | 1619 | ||
| 1067 | -getSubscribeInfo(): Promise\<CommonEventSubscribeInfo> | 1620 | +ArkTS-Dyn: getSubscribeInfo(): Promise\<CommonEventSubscribeInfo> |
| 1621 | + | ||
| 1622 | +ArkTS-Sta: getSubscribeInfo(): Promise\<CommonEventSubscribeInfo|null> | ||
| 1068 | 1623 | ||
| 1069 | Obtains the subscriber information. This API uses a promise to return the result. | 1624 | Obtains the subscriber information. This API uses a promise to return the result. |
| 1070 | 1625 | ||
| 1071 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 1626 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. |
| 1072 | 1627 | ||
| 1073 | **System capability**: SystemCapability.Notification.CommonEvent | 1628 | **System capability**: SystemCapability.Notification.CommonEvent |
| 1074 | 1629 | ||
| 1630 | +**ArkTS-Dyn start version:** 7 | ||
| 1631 | + | ||
| 1632 | +**ArkTS-Sta start version:** 23 | ||
| 1633 | + | ||
| 1075 | **Return value** | 1634 | **Return value** |
| 1076 | 1635 | ||
| 1077 | | Type | Description | | 1636 | | Type | Description | |
| 1078 | | ------------------------------------------------------------ | ---------------------- | | 1637 | | ------------------------------------------------------------ | ---------------------- | |
| 1079 | -| Promise\<[CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md)> | Promise used to return the result.| | 1638 | +| ArkTS-Dyn: Promise\<[CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md)> <br>ArkTS-Sta: Promise\<[CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md)\|null> | Promise used to return the subscriber's subscription information. | |
| 1080 | 1639 | ||
| 1081 | **Example** | 1640 | **Example** |
| 1082 | 1641 | ||
| 1642 | +ArkTS-Dyn example: | ||
| 1643 | + | ||
| 1083 | <!--code_no_check--> | 1644 | <!--code_no_check--> |
| 1084 | 1645 | ||
| 1085 | ```ts | 1646 | ```ts |
| @@ -1090,24 +1651,44 @@ subscriber.getSubscribeInfo().then((subscribeInfo: commonEventManager.CommonEven | |||
| 1090 | }); | 1651 | }); |
| 1091 | ``` | 1652 | ``` |
| 1092 | 1653 | ||
| 1654 | +ArkTS-Sta example: | ||
| 1655 | + | ||
| 1656 | +<!--code_no_check--> | ||
| 1657 | + | ||
| 1658 | +```ts | ||
| 1659 | +subscriber.getSubscribeInfo().then((subscribeInfo: commonEventManager.CommonEventSubscribeInfo | null) => { | ||
| 1660 | + console.info(`Succeeded in getting subscribe info, subscribe info is ${JSON.stringify(subscribeInfo)}`); | ||
| 1661 | +}).catch((err: BusinessError): void => { | ||
| 1662 | + console.error(`Failed to get subscribe info. Code is ${err.code}, message is ${err.message}`); | ||
| 1663 | +}); | ||
| 1664 | +``` | ||
| 1665 | + | ||
| 1093 | ### getSubscribeInfoSync<sup>10+</sup> | 1666 | ### getSubscribeInfoSync<sup>10+</sup> |
| 1094 | 1667 | ||
| 1095 | -getSubscribeInfoSync(): CommonEventSubscribeInfo | 1668 | +ArkTS-Dyn: getSubscribeInfoSync(): CommonEventSubscribeInfo |
| 1096 | 1669 | ||
| 1097 | -Obtains the subscriber information. | 1670 | +ArkTS-Sta: getSubscribeInfoSync(): CommonEventSubscribeInfo|null |
| 1098 | 1671 | ||
| 1099 | -**Atomic service API**: This API can be used in atomic services since API version 11. | 1672 | +Obtains the subscriber information. This API returns the result synchronously. |
| 1673 | + | ||
| 1674 | +**Atomic service API (ArkTS-Dyn only):** This API can be used in atomic services since API version 11. | ||
| 1100 | 1675 | ||
| 1101 | **System capability**: SystemCapability.Notification.CommonEvent | 1676 | **System capability**: SystemCapability.Notification.CommonEvent |
| 1102 | 1677 | ||
| 1678 | +**ArkTS-Dyn start version:** 10 | ||
| 1679 | + | ||
| 1680 | +**ArkTS-Sta start version:** 23 | ||
| 1681 | + | ||
| 1103 | **Return value** | 1682 | **Return value** |
| 1104 | 1683 | ||
| 1105 | | Type | Description | | 1684 | | Type | Description | |
| 1106 | | ------------------------------------------------------------ | ---------------------- | | 1685 | | ------------------------------------------------------------ | ---------------------- | |
| 1107 | -| [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) | Subscriber information.| | 1686 | +| ArkTS-Dyn: [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md) <br>ArkTS-Sta: [CommonEventSubscribeInfo](./js-apis-inner-commonEvent-commonEventSubscribeInfo.md)\|null | Subscriber information. | |
| 1108 | 1687 | ||
| 1109 | **Example** | 1688 | **Example** |
| 1110 | 1689 | ||
| 1690 | +ArkTS-Dyn example: | ||
| 1691 | + | ||
| 1111 | <!--code_no_check--> | 1692 | <!--code_no_check--> |
| 1112 | 1693 | ||
| 1113 | ```ts | 1694 | ```ts |
| @@ -1115,6 +1696,15 @@ let subscribeInfo1: commonEventManager.CommonEventSubscribeInfo = subscriber.get | |||
| 1115 | console.info(`Succeeded in getting subscribe info, subscribe info is ${JSON.stringify(subscribeInfo1)}`); | 1696 | console.info(`Succeeded in getting subscribe info, subscribe info is ${JSON.stringify(subscribeInfo1)}`); |
| 1116 | ``` | 1697 | ``` |
| 1117 | 1698 | ||
| 1699 | +ArkTS-Sta example: | ||
| 1700 | + | ||
| 1701 | +<!--code_no_check--> | ||
| 1702 | + | ||
| 1703 | +```ts | ||
| 1704 | +let getSubscribeInfo = subscriber.getSubscribeInfoSync(); | ||
| 1705 | +console.info(`Succeeded in getting subscribe info, subscribe info is ${JSON.stringify(getSubscribeInfo)}`); | ||
| 1706 | +``` | ||
| 1707 | + | ||
| 1118 | ### finishCommonEvent<sup>9+</sup> | 1708 | ### finishCommonEvent<sup>9+</sup> |
| 1119 | 1709 | ||
| 1120 | finishCommonEvent(callback: AsyncCallback\<void>): void | 1710 | finishCommonEvent(callback: AsyncCallback\<void>): void |
| @@ -1123,11 +1713,15 @@ Finishes this ordered common event. This API uses an asynchronous callback to re | |||
| 1123 | 1713 | ||
| 1124 | **System capability**: SystemCapability.Notification.CommonEvent | 1714 | **System capability**: SystemCapability.Notification.CommonEvent |
| 1125 | 1715 | ||
| 1716 | +**ArkTS-Dyn start version:** 9 | ||
| 1717 | + | ||
| 1718 | +**ArkTS-Sta start version:** 23 | ||
| 1719 | + | ||
| 1126 | **Parameters** | 1720 | **Parameters** |
| 1127 | 1721 | ||
| 1128 | | Name | Type | Mandatory| Description | | 1722 | | Name | Type | Mandatory| Description | |
| 1129 | | -------- | -------------------- | ---- | -------------------------------- | | 1723 | | -------- | -------------------- | ---- | -------------------------------- | |
| 1130 | -| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| | 1724 | +| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the subscriber successfully finishes this ordered common event, **err** is **undefined**; otherwise, **err** is an error object.| |
| 1131 | 1725 | ||
| 1132 | **Error codes** | 1726 | **Error codes** |
| 1133 | 1727 | ||
| @@ -1135,10 +1729,12 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | |||
| 1135 | 1729 | ||
| 1136 | | ID| Error Message | | 1730 | | ID| Error Message | |
| 1137 | | -------- | ----------------------------------- | | 1731 | | -------- | ----------------------------------- | |
| 1138 | -| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameter types.<br>3. Parameter verification failed. | | 1732 | +| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | |
| 1139 | 1733 | ||
| 1140 | **Example** | 1734 | **Example** |
| 1141 | 1735 | ||
| 1736 | +ArkTS-Dyn example: | ||
| 1737 | + | ||
| 1142 | <!--code_no_check--> | 1738 | <!--code_no_check--> |
| 1143 | 1739 | ||
| 1144 | ```ts | 1740 | ```ts |
| @@ -1151,6 +1747,20 @@ subscriber.finishCommonEvent((err: BusinessError) => { | |||
| 1151 | }); | 1747 | }); |
| 1152 | ``` | 1748 | ``` |
| 1153 | 1749 | ||
| 1750 | +ArkTS-Sta example: | ||
| 1751 | + | ||
| 1752 | +<!--code_no_check--> | ||
| 1753 | + | ||
| 1754 | +```ts | ||
| 1755 | +subscriber.finishCommonEvent((err: BusinessError | null) => { | ||
| 1756 | + if (err) { | ||
| 1757 | + console.error(`Failed to finish common event. Code is ${err.code}, message is ${err.message}`); | ||
| 1758 | + return; | ||
| 1759 | + } | ||
| 1760 | + console.info(`Succeeded in finishing common event.`); | ||
| 1761 | +}); | ||
| 1762 | +``` | ||
| 1763 | + | ||
| 1154 | ### finishCommonEvent<sup>9+</sup> | 1764 | ### finishCommonEvent<sup>9+</sup> |
| 1155 | 1765 | ||
| 1156 | finishCommonEvent(): Promise\<void> | 1766 | finishCommonEvent(): Promise\<void> |
| @@ -1159,6 +1769,10 @@ Finishes this ordered common event. This API uses a promise to return the result | |||
| 1159 | 1769 | ||
| 1160 | **System capability**: SystemCapability.Notification.CommonEvent | 1770 | **System capability**: SystemCapability.Notification.CommonEvent |
| 1161 | 1771 | ||
| 1772 | +**ArkTS-Dyn start version:** 9 | ||
| 1773 | + | ||
| 1774 | +**ArkTS-Sta start version:** 23 | ||
| 1775 | + | ||
| 1162 | **Return value** | 1776 | **Return value** |
| 1163 | 1777 | ||
| 1164 | | Type | Description | | 1778 | | Type | Description | |
| @@ -1167,6 +1781,8 @@ Finishes this ordered common event. This API uses a promise to return the result | |||
| 1167 | 1781 | ||
| 1168 | **Example** | 1782 | **Example** |
| 1169 | 1783 | ||
| 1784 | +ArkTS-Dyn example: | ||
| 1785 | + | ||
| 1170 | <!--code_no_check--> | 1786 | <!--code_no_check--> |
| 1171 | 1787 | ||
| 1172 | ```ts | 1788 | ```ts |
| @@ -1176,3 +1792,118 @@ subscriber.finishCommonEvent().then(() => { | |||
| 1176 | console.error(`Failed to finish common event. Code is ${err.code}, message is ${err.message}`); | 1792 | console.error(`Failed to finish common event. Code is ${err.code}, message is ${err.message}`); |
| 1177 | }); | 1793 | }); |
| 1178 | ``` | 1794 | ``` |
| 1795 | + | ||
| 1796 | +ArkTS-Sta example: | ||
| 1797 | + | ||
| 1798 | +<!--code_no_check--> | ||
| 1799 | + | ||
| 1800 | +```ts | ||
| 1801 | +subscriber.finishCommonEvent().then(() => { | ||
| 1802 | + console.info(`Succeeded in finishing common event.`); | ||
| 1803 | +}).catch((err: Error): void => { | ||
| 1804 | + let error: BusinessError = err as BusinessError; | ||
| 1805 | + console.error(`Failed to finish common event. Code is ${error.code}, message is ${error.message}`); | ||
| 1806 | +}); | ||
| 1807 | +``` | ||
| 1808 | + | ||
| 1809 | +## Converting CommonEventSubscriber Types Using @ohos.transfer | ||
| 1810 | + | ||
| 1811 | +Uses an ArkTS-Sta **CommonEventSubscriber** object in ArkTS-Dyn. | ||
| 1812 | + | ||
| 1813 | +**Example** | ||
| 1814 | + | ||
| 1815 | +- In the ArkTS-Sta module, convert the ArkTS-Sta **CommonEventSubscriber** to the ArkTS-Dyn **CommonEventSubscriber** and pass it to the ArkTS-Dyn submodule **library**. | ||
| 1816 | + | ||
| 1817 | + ArkTS-Sta example: | ||
| 1818 | + | ||
| 1819 | + ```TypeScript | ||
| 1820 | + 'use static' | ||
| 1821 | + import { transfer } from '@kit.ArkTS'; | ||
| 1822 | + import { CommonEventSubscriberStaticToDynamic } from 'library'; | ||
| 1823 | + import { commonEventManager, BusinessError } from '@kit.BasicServicesKit'; | ||
| 1824 | + | ||
| 1825 | + let subscriber: commonEventManager.CommonEventSubscriber; | ||
| 1826 | + let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = { | ||
| 1827 | + events: ['event'] | ||
| 1828 | + }; | ||
| 1829 | + try { | ||
| 1830 | + subscriber = commonEventManager.createSubscriberSync(subscribeInfo); | ||
| 1831 | + let dynamicHandler = transfer.transferDynamic(subscriber, 'CommonEventManager.CommonEventSubscriber'); | ||
| 1832 | + CommonEventSubscriberStaticToDynamic(dynamicHandler as commonEventManager.CommonEventSubscriber); | ||
| 1833 | + } catch (err) { | ||
| 1834 | + console.error('transferDynamic catch error:-----------' + err.message); | ||
| 1835 | + } | ||
| 1836 | + ``` | ||
| 1837 | + | ||
| 1838 | +- Export the dependency **CommonEventSubscriberStaticToDynamic** in the **library/src/index.ets** file. | ||
| 1839 | + | ||
| 1840 | + ```TypeScript | ||
| 1841 | + export { CommonEventSubscriberStaticToDynamic } from './src/main/ets/components/MainPage'; | ||
| 1842 | + ``` | ||
| 1843 | + | ||
| 1844 | +- Create an ArkTS-Dyn submodule **library**, and provide a method for receiving the ArkTS-Dyn **CommonEventSubscriber** in the **library/src/main/ets/components** directory. | ||
| 1845 | + | ||
| 1846 | + ArkTS-Dyn example: | ||
| 1847 | + | ||
| 1848 | + ```TypeScript | ||
| 1849 | + import { commonEventManager, BusinessError } from '@kit.BasicServicesKit'; | ||
| 1850 | + export function CommonEventSubscriberStaticToDynamic(subscriber_: commonEventManager.CommonEventSubscriber) { | ||
| 1851 | + try { | ||
| 1852 | + let subscriber: commonEventManager.CommonEventSubscriber = subscriber_ as commonEventManager.CommonEventSubscriber; | ||
| 1853 | + let subscribeInfo = subscriber.getSubscribeInfoSync(); | ||
| 1854 | + console.info(`Succeeded in getting subscribe info, subscribe info is ${JSON.stringify(subscribeInfo)}`); | ||
| 1855 | + } catch (err) { | ||
| 1856 | + console.error('CommonEventSubscriberStaticToDynamic catch Error: ' + err.message); | ||
| 1857 | + } | ||
| 1858 | + } | ||
| 1859 | + ``` | ||
| 1860 | + | ||
| 1861 | +Uses the ArkTS-Dyn **CommonEventSubscriber** object in ArkTS-Sta. | ||
| 1862 | + | ||
| 1863 | +**Example** | ||
| 1864 | + | ||
| 1865 | +- In the ArkTS-Dyn module, create an ArkTS-Dyn **CommonEventSubscriber** object and pass it to the ArkTS-Sta submodule **library**. | ||
| 1866 | + | ||
| 1867 | + ArkTS-Dyn example: | ||
| 1868 | + | ||
| 1869 | + ```TypeScript | ||
| 1870 | + import { CommonEventSubscriberDynamicToStatic } from 'library'; | ||
| 1871 | + import { commonEventManager, BusinessError } from '@kit.BasicServicesKit'; | ||
| 1872 | + | ||
| 1873 | + let dynamicSubscriber: commonEventManager.CommonEventSubscriber; | ||
| 1874 | + let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = { | ||
| 1875 | + events: ['event'] | ||
| 1876 | + }; | ||
| 1877 | + try { | ||
| 1878 | + dynamicSubscriber = commonEventManager.createSubscriberSync(subscribeInfo); | ||
| 1879 | + CommonEventSubscriberDynamicToStatic(dynamicSubscriber); | ||
| 1880 | + } catch (err) { | ||
| 1881 | + console.error('transferDynamic catch error:' + err.message); | ||
| 1882 | + } | ||
| 1883 | + ``` | ||
| 1884 | + | ||
| 1885 | +- Export the dependency **CommonEventSubscriberDynamicToStatic** in the **library/src/index.ets** file. | ||
| 1886 | + | ||
| 1887 | + ```TypeScript | ||
| 1888 | + export { CommonEventSubscriberDynamicToStatic } from './src/main/ets/components/MainPage'; | ||
| 1889 | + ``` | ||
| 1890 | + | ||
| 1891 | +- Create an ArkTS-Sta submodule **library**, and provide a method for receiving the ArkTS-Dyn **CommonEventSubscriber** in the **library/src/main/ets/components** directory. | ||
| 1892 | + | ||
| 1893 | + ArkTS-Sta example: | ||
| 1894 | + | ||
| 1895 | + ```TypeScript | ||
| 1896 | + 'use static' | ||
| 1897 | + import { transfer } from '@kit.ArkTS'; | ||
| 1898 | + import { commonEventManager, BusinessError } from '@kit.BasicServicesKit'; | ||
| 1899 | + | ||
| 1900 | + export function CommonEventSubscriberDynamicToStatic(dynObject: Object | undefined | null) :void { | ||
| 1901 | + try { | ||
| 1902 | + let staticSubscriber: commonEventManager.CommonEventSubscriber = transfer.transferStatic(dynObject, 'CommonEventManager.CommonEventSubscriber') as commonEventManager.CommonEventSubscriber; | ||
| 1903 | + let subscribeInfo = staticSubscriber.getSubscribeInfoSync(); | ||
| 1904 | + console.info(`Succeeded in getting subscribe info, subscribe info is ${JSON.stringify(subscribeInfo)}`); | ||
| 1905 | + } catch (err) { | ||
| 1906 | + console.error('CommonEventSubscriberDynamicToStatic catch error:' + err.message); | ||
| 1907 | + } | ||
| 1908 | + } | ||
| 1909 | + ``` | ||