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