1# @ohos.systemTimer (系统定时器)(系统接口) 2 3本模块主要由系统定时器功能组成。开发者可以使用定时功能实现定时服务，如闹钟等。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - 本模块接口为系统接口。 9 10## 导入模块 11 12 13```ts 14import { systemTimer } from '@kit.BasicServicesKit'; 15``` 16 17## 常量 18 19支持创建的定时器类型。 20 21**系统能力：** SystemCapability.MiscServices.Time 22 23| 名称 | 类型 | 值 | 说明 | 24| ------------------- | ------ | ---- |---------------------------------------------| 25| TIMER_TYPE_REALTIME | number | 1 | 系统启动时间定时器（定时器启动时间不能晚于当前设置的系统时间）。| 26| TIMER_TYPE_WAKEUP | number | 2 | 唤醒定时器（如果未配置为唤醒定时器，则系统处于休眠状态下不会触发，直到退出休眠状态）。| 27| TIMER_TYPE_EXACT | number | 4 | 精准定时器（系统时间修改的情况下，可能会出现最多1s的前后偏移误差）。| 28| TIMER_TYPE_IDLE | number | 8 | IDLE模式定时器（仅支持系统服务配置，不支持应用配置）。| 29 30 ## TimerOptions 31 32创建系统定时器的初始化选项。 33 34**系统能力：** SystemCapability.MiscServices.Time 35 36| 名称 | 类型 | 必填 | 说明 | 37|-----------| --------------------------------------------- | ---- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 38| type | number | 是 | 定时器类型，可以使用 '\|' 多选。<br>取值为1，表示为系统启动时间定时器（定时器启动时间不能晚于当前设置的系统时间）；<br>取值为2，表示为唤醒定时器；<br>取值为4，表示为精准定时器（APP被冻结时，定时器也会被冻结，并且定时器受统一心跳管控，因此即使是精准定时器也不能确保在指定时间点触发）；<br>取值为8，表示为IDLE模式定时器（仅支持系统服务配置，不支持应用配置）。 | 39| repeat | boolean | 是 | 是否为循环定时器。<br>true为循环定时器，false为单次定时器。 | 40| autoRestore<sup>15+</sup> | boolean | 否 | 是否在设备重启后恢复。<br>true为重启后恢复，false为重启后不恢复。<br>仅支持非`TIMER_TYPE_REALTIME`类型且配置了wantAgent的定时器配置为true。 | | | | 41| name<sup>15+</sup> | string | 否 | 定时器名称，长度不超过64字节。<br>同一个UID中不可以同时存在两个同名定时器。如果创建了一个和之前已创建的定时器名字相同的定时器，先创建的定时器会被销毁。| 42| interval | number | 否 | 定时器时间间隔。<br>如果是循环定时器，interval值最小为1s，最大为365天，建议interval值不小于5000毫秒；<br>单次定时器interval值为0。 | 43| wantAgent | WantAgent | 否 | 设置通知的WantAgent，定时器到期后通知（支持拉起应用MainAbility，不支持拉起ServiceAbility）。 | 44| callback | void | 否 | 用户需要执行的回调函数。 | 45 46 47## systemTimer.createTimer 48 49createTimer(options: TimerOptions, callback: AsyncCallback<number>): void 50 51创建定时器，使用callback异步回调。 52 53**注意：需与[systemTimer.destroyTimer](#systemtimerdestroytimer)结合使用，否则会造成内存泄漏** 54 55**系统能力：** SystemCapability.MiscServices.Time 56 57**参数：** 58 59| 参数名 | 类型 | 必填 | 说明 | 60| -------- | ----------------------------- | ---- | ------------------------------------------------------------ | 61| options | [TimerOptions](#timeroptions) | 是 | 创建系统定时器的初始化选项，包括定时器类型、是否循环触发、间隔时间、WantAgent通知机制等。 | 62| callback | AsyncCallback<number> | 是 | 回调函数，返回定时器的ID。 | 63 64**错误码：** 65 66以下错误码的详细介绍请参见[时间时区错误码](./errorcode-time.md)。 67 68| 错误码ID | 错误信息 | 69|-------|----------------------------------------------------------------------------------------------------------------------------------------------| 70| 202 | Permission verification failed. A non-system application calls a system API. | 71| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 72 73**示例：** 74 75```ts 76import { BusinessError } from '@kit.BasicServicesKit'; 77 78let options: systemTimer.TimerOptions = { 79 type: systemTimer.TIMER_TYPE_REALTIME, 80 repeat: false 81}; 82try { 83 systemTimer.createTimer(options, (error: BusinessError, timerId: Number) => { 84 if (error) { 85 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 86 return; 87 } 88 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 89 }); 90} catch(e) { 91 let error = e as BusinessError; 92 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 93} 94``` 95 96## systemTimer.createTimer 97 98createTimer(options: TimerOptions): Promise<number> 99 100创建定时器，使用Promise异步回调。 101 102**注意：需与[systemTimer.destroyTimer](#systemtimerdestroytimer)结合使用，否则会造成内存泄漏** 103 104**系统能力：** SystemCapability.MiscServices.Time 105 106**参数：** 107 108| 参数名 | 类型 | 必填 | 说明 | 109| ------- | ----------------------------- | ---- | ------------------------------------------------------------ | 110| options | [TimerOptions](#timeroptions) | 是 | 创建系统定时器的初始化选项，包括定时器类型、是否循环触发、间隔时间、WantAgent通知机制等。 | 111 112**返回值：** 113 114| 类型 | 说明 | 115| --------------------- | ----------------------------- | 116| Promise<number> | Promise对象，返回定时器的ID。 | 117 118**错误码：** 119 120以下错误码的详细介绍请参见[时间时区错误码](./errorcode-time.md)。 121 122| 错误码ID | 错误信息 | 123|-------|-------------------------------------------------------------------------------------------------------------| 124| 202 | Permission verification failed. A non-system application calls a system API. | 125| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 126 127**示例：** 128 129```ts 130import { BusinessError } from '@kit.BasicServicesKit'; 131 132let options: systemTimer.TimerOptions = { 133 type: systemTimer.TIMER_TYPE_REALTIME, 134 repeat:false 135}; 136try { 137 systemTimer.createTimer(options).then((timerId: Number) => { 138 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 139 }).catch((error: BusinessError) => { 140 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 141 }); 142} catch(e) { 143 let error = e as BusinessError; 144 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 145} 146``` 147 148## systemTimer.startTimer 149 150startTimer(timer: number, triggerTime: number, callback: AsyncCallback<void>): void 151 152开启定时器，使用callback异步回调。 153 154**系统能力：** SystemCapability.MiscServices.Time 155 156**参数：** 157 158| 参数名 | 类型 | 必填 | 说明 | 159| ----------- | ---------------------- | ---- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 160| timer | number | 是 | 定时器的ID。 | 161| triggerTime | number | 是 | 定时器的触发时间，单位：毫秒。<br/>若定时器类型包含了TIMER_TYPE_REALTIME，该triggerTime应为系统启动时间，建议通过[systemDateTime.getUptime(STARTUP)](js-apis-date-time.md#systemdatetimegetuptime10)获取；<br/>若定时器类型不包含TIMER_TYPE_REALTIME，该triggerTime应为墙上时间，建议通过[systemDateTime.getTime()](js-apis-date-time.md#systemdatetimegettime10)获取。 | 162| callback | AsyncCallback<void> | 是 | 回调函数。 | 163 164**错误码：** 165 166以下错误码的详细介绍请参见[时间时区错误码](./errorcode-time.md)。 167 168| 错误码ID | 错误信息 | 169|-------|-------------------------------------------------------------------------------------------------------------| 170| 202 | Permission verification failed. A non-system application calls a system API. | 171| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 172 173**示例：** 174 175```ts 176import { BusinessError } from '@kit.BasicServicesKit'; 177 178let options: systemTimer.TimerOptions = { 179 type: systemTimer.TIMER_TYPE_REALTIME, 180 repeat:false 181} 182let triggerTime = new Date().getTime(); 183triggerTime += 3000; 184 185try { 186 systemTimer.createTimer(options).then((timerId: number) => { 187 systemTimer.startTimer(timerId, triggerTime, (error: BusinessError) => { 188 if (error) { 189 console.info(`Failed to start timer. message: ${error.message}, code: ${error.code}`); 190 return; 191 } 192 console.info(`Succeeded in starting timer.`); 193 }); 194 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 195 }).catch((error: BusinessError) => { 196 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 197 }); 198} catch(e) { 199 let error = e as BusinessError; 200 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 201} 202``` 203 204## systemTimer.startTimer 205 206startTimer(timer: number, triggerTime: number): Promise<void> 207 208开启定时器，使用Promise异步回调。 209 210**系统能力：** SystemCapability.MiscServices.Time 211 212**参数：** 213 214| 参数名 | 类型 | 必填 | 说明 | 215| ----------- | ------ | ---- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 216| timer | number | 是 | 定时器的ID。 | 217| triggerTime | number | 是 | 定时器的触发时间，单位：毫秒。<br/>若定时器类型包含了TIMER_TYPE_REALTIME，该triggerTime应为系统启动时间，建议通过[systemDateTime.getUptime(STARTUP)](js-apis-date-time.md#systemdatetimegetuptime10)获取；<br/>若定时器类型不包含TIMER_TYPE_REALTIME，该triggerTime应为墙上时间，建议通过[systemDateTime.getTime()](js-apis-date-time.md#systemdatetimegettime10)获取。 | 218 219**返回值：** 220 221| 类型 | 说明 | 222| -------------- | ------------------------- | 223| Promise\<void> | 无返回结果的Promise对象。 | 224 225**错误码：** 226 227以下错误码的详细介绍请参见[时间时区错误码](./errorcode-time.md)。 228 229| 错误码ID | 错误信息 | 230|-------|-------------------------------------------------------------------------------------------------------------| 231| 202 | Permission verification failed. A non-system application calls a system API. | 232| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 233 234**示例：** 235 236```ts 237import { BusinessError } from '@kit.BasicServicesKit'; 238 239let options: systemTimer.TimerOptions = { 240 type: systemTimer.TIMER_TYPE_REALTIME, 241 repeat:false 242} 243let triggerTime = new Date().getTime(); 244triggerTime += 3000; 245 246try { 247 systemTimer.createTimer(options).then((timerId: number) => { 248 systemTimer.startTimer(timerId, triggerTime).then(() => { 249 console.info(`Succeeded in starting timer.`); 250 }).catch((error: BusinessError) => { 251 console.info(`Failed to start timer. message: ${error.message}, code: ${error.code}`); 252 }); 253 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 254 }).catch((error: BusinessError) => { 255 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 256 }); 257} catch(e) { 258 let error = e as BusinessError; 259 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 260} 261``` 262 263## systemTimer.stopTimer 264 265stopTimer(timer: number, callback: AsyncCallback<void>): void 266 267停止定时器，使用callback异步回调。 268 269**系统能力：** SystemCapability.MiscServices.Time 270 271**参数：** 272 273| 参数名 | 类型 | 必填 | 说明 | 274| -------- | ---------------------- | ---- | ------------ | 275| timer | number | 是 | 定时器的ID。 | 276| callback | AsyncCallback<void> | 是 | 回调函数。 | 277 278**错误码：** 279 280以下错误码的详细介绍请参见[时间时区错误码](./errorcode-time.md)。 281 282| 错误码ID | 错误信息 | 283|-------|-------------------------------------------------------------------------------------------------------------| 284| 202 | Permission verification failed. A non-system application calls a system API. | 285| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 286 287**示例：** 288 289```ts 290import { BusinessError } from '@kit.BasicServicesKit'; 291 292let options: systemTimer.TimerOptions = { 293 type: systemTimer.TIMER_TYPE_REALTIME, 294 repeat:false 295} 296let triggerTime = new Date().getTime(); 297triggerTime += 3000; 298 299try { 300 systemTimer.createTimer(options).then((timerId: number) => { 301 systemTimer.startTimer(timerId, triggerTime); 302 systemTimer.stopTimer(timerId, (error: BusinessError) => { 303 if (error) { 304 console.info(`Failed to stop timer. message: ${error.message}, code: ${error.code}`); 305 return; 306 } 307 console.info(`Succeeded in stopping timer.`); 308 }); 309 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 310 }).catch((error: BusinessError) => { 311 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 312 }); 313} catch(e) { 314 let error = e as BusinessError; 315 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 316} 317``` 318 319## systemTimer.stopTimer 320 321stopTimer(timer: number): Promise<void> 322 323停止定时器，使用Promise异步回调。 324 325**系统能力：** SystemCapability.MiscServices.Time 326 327**参数：** 328 329| 参数名 | 类型 | 必填 | 说明 | 330| ------ | ------ | ---- | ------------ | 331| timer | number | 是 | 定时器的ID。 | 332 333**返回值：** 334 335| 类型 | 说明 | 336| -------------- | ------------------------- | 337| Promise\<void> | 无返回结果的Promise对象。 | 338 339**错误码：** 340 341以下错误码的详细介绍请参见[时间时区错误码](./errorcode-time.md)。 342 343| 错误码ID | 错误信息 | 344|-------|-------------------------------------------------------------------------------------------------------------| 345| 202 | Permission verification failed. A non-system application calls a system API. | 346| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 347 348**示例：** 349 350```ts 351import { BusinessError } from '@kit.BasicServicesKit'; 352 353let options: systemTimer.TimerOptions = { 354 type: systemTimer.TIMER_TYPE_REALTIME, 355 repeat:false 356} 357let triggerTime = new Date().getTime(); 358triggerTime += 3000; 359 360try { 361 systemTimer.createTimer(options).then((timerId: number) => { 362 systemTimer.startTimer(timerId, triggerTime); 363 systemTimer.stopTimer(timerId).then(() => { 364 console.info(`Succeeded in stopping timer.`); 365 }).catch((error: BusinessError) => { 366 console.info(`Failed to stop timer. message: ${error.message}, code: ${error.code}`); 367 }); 368 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 369 }).catch((error: BusinessError) => { 370 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 371 }); 372} catch(e) { 373 let error = e as BusinessError; 374 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 375} 376``` 377 378## systemTimer.destroyTimer 379 380destroyTimer(timer: number, callback: AsyncCallback<void>): void 381 382销毁定时器，使用callback异步回调。 383 384**系统能力：** SystemCapability.MiscServices.Time 385 386**参数：** 387 388| 参数名 | 类型 | 必填 | 说明 | 389| -------- | ---------------------- | ---- | ------------ | 390| timer | number | 是 | 定时器的ID。 | 391| callback | AsyncCallback<void> | 是 | 回调函数。 | 392 393**错误码：** 394 395以下错误码的详细介绍请参见[时间时区错误码](./errorcode-time.md)。 396 397| 错误码ID | 错误信息 | 398|-------|-------------------------------------------------------------------------------------------------------------| 399| 202 | Permission verification failed. A non-system application calls a system API. | 400| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 401 402**示例：** 403 404```ts 405import { BusinessError } from '@kit.BasicServicesKit'; 406 407let options: systemTimer.TimerOptions = { 408 type: systemTimer.TIMER_TYPE_REALTIME, 409 repeat:false 410} 411let triggerTime = new Date().getTime(); 412triggerTime += 3000; 413 414try { 415 systemTimer.createTimer(options).then((timerId: number) => { 416 systemTimer.startTimer(timerId, triggerTime); 417 systemTimer.stopTimer(timerId); 418 systemTimer.destroyTimer(timerId, (error: BusinessError) => { 419 if (error) { 420 console.info(`Failed to destroy timer. message: ${error.message}, code: ${error.code}`); 421 return; 422 } 423 console.info(`Succeeded in destroying timer.`); 424 }); 425 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 426 }).catch((error: BusinessError) => { 427 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 428 }); 429} catch(e) { 430 let error = e as BusinessError; 431 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 432} 433``` 434 435## systemTimer.destroyTimer 436 437destroyTimer(timer: number): Promise<void> 438 439销毁定时器，使用Promise异步回调。 440 441**系统能力：** SystemCapability.MiscServices.Time 442 443**参数：** 444 445| 参数名 | 类型 | 必填 | 说明 | 446| ------ | ------ | ---- | ------------ | 447| timer | number | 是 | 定时器的ID。 | 448 449**返回值：** 450 451| 类型 | 说明 | 452| -------------- | ------------------------- | 453| Promise\<void> | 无返回结果的Promise对象。 | 454 455**错误码：** 456 457以下错误码的详细介绍请参见[时间时区错误码](./errorcode-time.md)。 458 459| 错误码ID | 错误信息 | 460|-------|-------------------------------------------------------------------------------------------------------------| 461| 202 | Permission verification failed. A non-system application calls a system API. | 462| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 463 464**示例：** 465 466```ts 467import { BusinessError } from '@kit.BasicServicesKit'; 468 469let options: systemTimer.TimerOptions = { 470 type: systemTimer.TIMER_TYPE_REALTIME, 471 repeat:false 472} 473let triggerTime = new Date().getTime(); 474triggerTime += 3000; 475 476try { 477 systemTimer.createTimer(options).then((timerId: number) => { 478 systemTimer.startTimer(timerId, triggerTime); 479 systemTimer.stopTimer(timerId); 480 systemTimer.destroyTimer(timerId).then(() => { 481 console.info(`Succeeded in destroying timer.`); 482 }).catch((error: BusinessError) => { 483 console.info(`Failed to destroy timer. message: ${error.message}, code: ${error.code}`); 484 }); 485 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 486 }).catch((error: BusinessError) => { 487 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 488 }); 489} catch(e) { 490 let error = e as BusinessError; 491 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 492} 493```