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