1# @ohos.systemTimer (System Timer) 2 3The **systemTimer** module provides system timer features. You can use the APIs of this module to implement the alarm clock and other timer services. 4 5> **NOTE** 6> 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. 8> - The APIs provided by this module are system APIs. 9 10## Modules to Import 11 12 13```ts 14import systemTimer from '@ohos.systemTimer'; 15``` 16 17## Constants 18 19Provides the constants that define the supported timer types. 20 21**System capability**: SystemCapability.MiscServices.Time 22 23| Name | Type | Value | Description | 24| ------------------- | ------ | ---- | ---------------------------- | 25| TIMER_TYPE_REALTIME | number | 1 | CPU time type. (The start time of the timer cannot be later than the current system time.) | 26| TIMER_TYPE_WAKEUP | number | 2 | Wakeup type. | 27| TIMER_TYPE_EXACT | number | 4 | Exact type. | 28| TIMER_TYPE_IDLE | number | 8 | Idle type (not supported currently).| 29 30 ## TimerOptions 31 32Defines the initialization options for **createTimer**. 33 34**System capability**: SystemCapability.MiscServices.Time 35 36| Name | Type | Mandatory| Description | 37| --------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 38| type | number | Yes | Timer type.<br>**1**: CPU time type. (The start time of the timer cannot be later than the current system time.)<br>**2**: wakeup type.<br>**4**: exact type.<br>**8**: idle type (not supported currently).| 39| repeat | boolean | Yes | Whether the timer is a repeating timer.<br>The value **true** means that the timer is a repeating timer, and **false** means that the timer is a one-shot timer. | 40| interval | number | No | Repeat interval.<br>For a repeating timer, the value must be greater than 5000 ms. For a one-shot timer, the value is **0**.| 41| wantAgent | [WantAgent](js-apis-app-ability-wantAgent.md) | No | **WantAgent** object of the notification to be sent when the timer expires. (An application MainAbility can be started, but not a Service ability.)| 42| callback | number | Yes | Callback used to return the timer ID. | 43 44 45## systemTimer.createTimer 46 47createTimer(options: TimerOptions, callback: AsyncCallback<number>): void 48 49Creates a timer. This API uses an asynchronous callback to return the result. 50 51**System capability**: SystemCapability.MiscServices.Time 52 53**Parameters** 54 55| Name | Type | Mandatory| Description | 56| -------- | ----------------------------- | ---- | ------------------------------------------------------------ | 57| options | [TimerOptions](#timeroptions) | Yes | Timer initialization options, including the timer type, whether the timer is a repeating timer, interval, and **WantAgent** options.| 58| callback | AsyncCallback<number> | Yes | Callback used to return the timer ID. | 59 60**Example** 61 62```ts 63import { BusinessError } from '@ohos.base'; 64 65let options: systemTimer.TimerOptions = { 66 type: systemTimer.TIMER_TYPE_REALTIME, 67 repeat: false 68}; 69try { 70 systemTimer.createTimer(options, (error: BusinessError, timerId: Number) => { 71 if (error) { 72 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 73 return; 74 } 75 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 76 }); 77} catch(e) { 78 let error = e as BusinessError; 79 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 80} 81``` 82 83## systemTimer.createTimer 84 85createTimer(options: TimerOptions): Promise<number> 86 87Creates a timer. This API uses a promise to return the result. 88 89 90**System capability**: SystemCapability.MiscServices.Time 91 92**Parameters** 93 94| Name | Type | Mandatory| Description | 95| ------- | ----------------------------- | ---- | ------------------------------------------------------------ | 96| options | [TimerOptions](#timeroptions) | Yes | Timer initialization options, including the timer type, whether the timer is a repeating timer, interval, and **WantAgent** options.| 97 98**Return value** 99 100| Type | Description | 101| --------------------- | ----------------------------- | 102| Promise<number> | Promise used to return the timer ID.| 103 104**Example** 105 106```ts 107import { BusinessError } from '@ohos.base'; 108 109let options: systemTimer.TimerOptions = { 110 type: systemTimer.TIMER_TYPE_REALTIME, 111 repeat:false 112}; 113try { 114 systemTimer.createTimer(options).then((timerId: Number) => { 115 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 116 }).catch((error: BusinessError) => { 117 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 118 }); 119} catch(e) { 120 let error = e as BusinessError; 121 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 122} 123``` 124 125## systemTimer.startTimer 126 127startTimer(timer: number, triggerTime: number, callback: AsyncCallback<void>): void 128 129Starts a timer. This API uses an asynchronous callback to return the result. 130 131**System capability**: SystemCapability.MiscServices.Time 132 133**Parameters** 134 135| Name | Type | Mandatory| Description | 136| ----------- | ---------------------- | ---- | ------------------------------ | 137| timer | number | Yes | ID of the timer. | 138| triggerTime | number | Yes | Time when the timer is triggered, in milliseconds.| 139| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 140 141**Example** 142 143```ts 144import { BusinessError } from '@ohos.base'; 145 146let options: systemTimer.TimerOptions = { 147 type: systemTimer.TIMER_TYPE_REALTIME, 148 repeat:false 149} 150let timerId = await systemTimer.createTimer(options); 151let triggerTime = new Date().getTime(); 152triggerTime += 3000; 153try { 154 systemTimer.startTimer(timerId, triggerTime, (error: BusinessError) => { 155 if (error) { 156 console.info(`Failed to start timer. message: ${error.message}, code: ${error.code}`); 157 return; 158 } 159 console.info(`Succeeded in starting timer.`); 160 }); 161} catch(e) { 162 let error = e as BusinessError; 163 console.info(`Failed to start timer. message: ${error.message}, code: ${error.code}`); 164} 165``` 166 167## systemTimer.startTimer 168 169startTimer(timer: number, triggerTime: number): Promise<void> 170 171Starts a timer. This API uses a promise to return the result. 172 173**System capability**: SystemCapability.MiscServices.Time 174 175**Parameters** 176 177| Name | Type | Mandatory| Description | 178| ----------- | ------ | ---- | ------------------------------ | 179| timer | number | Yes | ID of the timer. | 180| triggerTime | number | Yes | Time when the timer is triggered, in milliseconds.| 181 182**Return value** 183 184| Type | Description | 185| -------------- | ------------------------- | 186| Promise\<void> | Promise that returns no value.| 187 188**Example** 189 190```ts 191import { BusinessError } from '@ohos.base'; 192 193let options: systemTimer.TimerOptions = { 194 type: systemTimer.TIMER_TYPE_REALTIME, 195 repeat:false 196} 197let timerId = await systemTimer.createTimer(options); 198let triggerTime = new Date().getTime(); 199triggerTime += 3000; 200try { 201 systemTimer.startTimer(timerId, triggerTime).then(() => { 202 console.info(`Succeeded in starting timer.`); 203 }).catch((error: BusinessError) => { 204 console.info(`Failed to start timer. message: ${error.message}, code: ${error.code}`); 205 }); 206} catch(e) { 207 let error = e as BusinessError; 208 console.info(`Failed to start timer. message: ${error.message}, code: ${error.code}`); 209} 210``` 211 212## systemTimer.stopTimer 213 214stopTimer(timer: number, callback: AsyncCallback<void>): void 215 216Stops a timer. This API uses an asynchronous callback to return the result. 217 218**System capability**: SystemCapability.MiscServices.Time 219 220**Parameters** 221 222| Name | Type | Mandatory| Description | 223| -------- | ---------------------- | ---- | ------------ | 224| timer | number | Yes | ID of the timer.| 225| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 226 227**Example** 228 229```ts 230import { BusinessError } from '@ohos.base'; 231 232let options: systemTimer.TimerOptions = { 233 type: systemTimer.TIMER_TYPE_REALTIME, 234 repeat:false 235} 236let timerId = await systemTimer.createTimer(options); 237let triggerTime = new Date().getTime(); 238triggerTime += 3000; 239systemTimer.startTimer(timerId, triggerTime); 240try { 241 systemTimer.stopTimer(timerId, (error: BusinessError) => { 242 if (error) { 243 console.info(`Failed to stop timer. message: ${error.message}, code: ${error.code}`); 244 return; 245 } 246 console.info(`Succeeded in stopping timer.`); 247 }); 248} catch(e) { 249 let error = e as BusinessError; 250 console.info(`Failed to stop timer. message: ${error.message}, code: ${error.code}`); 251} 252``` 253 254## systemTimer.stopTimer 255 256stopTimer(timer: number): Promise<void> 257 258Stops a timer. This API uses a promise to return the result. 259 260**System capability**: SystemCapability.MiscServices.Time 261 262**Parameters** 263 264| Name| Type | Mandatory| Description | 265| ------ | ------ | ---- | ------------ | 266| timer | number | Yes | ID of the timer.| 267 268**Return value** 269 270| Type | Description | 271| -------------- | ------------------------- | 272| Promise\<void> | Promise that returns no value.| 273 274**Example** 275 276```ts 277import { BusinessError } from '@ohos.base'; 278 279let options: systemTimer.TimerOptions = { 280 type: systemTimer.TIMER_TYPE_REALTIME, 281 repeat:false 282} 283let timerId = await systemTimer.createTimer(options); 284let triggerTime = new Date().getTime(); 285triggerTime += 3000; 286systemTimer.startTimer(timerId, triggerTime); 287try { 288 systemTimer.stopTimer(timerId).then(() => { 289 console.info(`Succeeded in stopping timer.`); 290 }).catch((error: BusinessError) => { 291 console.info(`Failed to stop timer. message: ${error.message}, code: ${error.code}`); 292 }); 293} catch(e) { 294 let error = e as BusinessError; 295 console.info(`Failed to stop timer. message: ${error.message}, code: ${error.code}`); 296} 297``` 298 299## systemTimer.destroyTimer 300 301destroyTimer(timer: number, callback: AsyncCallback<void>): void 302 303Destroys a timer. This API uses an asynchronous callback to return the result. 304 305**System capability**: SystemCapability.MiscServices.Time 306 307**Parameters** 308 309| Name | Type | Mandatory| Description | 310| -------- | ---------------------- | ---- | ------------ | 311| timer | number | Yes | ID of the timer.| 312| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 313 314**Example** 315 316```ts 317import { BusinessError } from '@ohos.base'; 318 319let options: systemTimer.TimerOptions = { 320 type: systemTimer.TIMER_TYPE_REALTIME, 321 repeat:false 322} 323let timerId = await systemTimer.createTimer(options); 324let triggerTime = new Date().getTime(); 325triggerTime += 3000; 326systemTimer.startTimer(timerId, triggerTime); 327systemTimer.stopTimer(timerId); 328try { 329 systemTimer.destroyTimer(timerId, (error: BusinessError) => { 330 if (error) { 331 console.info(`Failed to destroy timer. message: ${error.message}, code: ${error.code}`); 332 return; 333 } 334 console.info(`Succeeded in destroying timer.`); 335 }); 336} catch(e) { 337 let error = e as BusinessError; 338 console.info(`Failed to destroying timer. message: ${error.message}, code: ${error.code}`); 339} 340``` 341 342## systemTimer.destroyTimer 343 344destroyTimer(timer: number): Promise<void> 345 346Destroys a timer. This API uses a promise to return the result. 347 348**System capability**: SystemCapability.MiscServices.Time 349 350**Parameters** 351 352| Name| Type | Mandatory| Description | 353| ------ | ------ | ---- | ------------ | 354| timer | number | Yes | ID of the timer.| 355 356**Return value** 357 358| Type | Description | 359| -------------- | ------------------------- | 360| Promise\<void> | Promise that returns no value.| 361 362**Example** 363 364```ts 365import { BusinessError } from '@ohos.base'; 366 367let options: systemTimer.TimerOptions = { 368 type: systemTimer.TIMER_TYPE_REALTIME, 369 repeat:false 370} 371let timerId = await systemTimer.createTimer(options); 372let triggerTime = new Date().getTime(); 373triggerTime += 3000; 374systemTimer.startTimer(timerId, triggerTime); 375systemTimer.stopTimer(timerId); 376try { 377 systemTimer.destroyTimer(timerId).then(() => { 378 console.info(`Succeeded in destroying timer.`); 379 }).catch((error: BusinessError) => { 380 console.info(`Failed to destroy timer. message: ${error.message}, code: ${error.code}`); 381 }); 382} catch(e) { 383 let error = e as BusinessError; 384 console.info(`Failed to destroying timer. message: ${error.message}, code: ${error.code}`); 385} 386``` 387