1# @ohos.systemTimer (系统定时器) 2 3本模块主要由系统定时器功能组成。开发者可以使用定时功能实现定时服务，如闹钟等。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - 本模块接口为系统接口。 9 10## 导入模块 11 12 13```js 14import systemTimer from '@ohos.systemTimer'; 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 | 精准定时器。 | 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，表示为精准定时器；<br>取值为8，表示为IDLE模式定时器（暂不支持）。 | 39| repeat | boolean | 是 | true为循环定时器，false为单次定时器。 | 40| interval | number | 否 | 如果是循环定时器，repeat值应大于5000毫秒，非重复定时器置为0。 | 41| wantAgent | [WantAgent](js-apis-app-ability-wantAgent.md) | 否 | 设置通知的WantAgent，定时器到期后通知。（支持拉起应用MainAbility，暂不支持拉起ServiceAbility。） | 42| callback | number | 是 | 以回调函数的形式返回定时器的ID。 | 43 44 45## systemTimer.createTimer 46 47createTimer(options: TimerOptions, callback: AsyncCallback<number>): void 48 49创建定时器，使用callback异步回调。 50 51**系统能力：** SystemCapability.MiscServices.Time 52 53**参数：** 54 55| 参数名 | 类型 | 必填 | 说明 | 56| -------- | ----------------------------- | ---- | ------------------------------------------------------------ | 57| options | [TimerOptions](#timeroptions) | 是 | 创建系统定时器的初始化选项，包括定时器类型、是否循环触发、间隔时间、WantAgent通知机制等。 | 58| callback | AsyncCallback<number> | 是 | 回调函数，返回定时器的ID。 | 59 60**示例：** 61 62```js 63export default { 64 systemTimer () { 65 let options = { 66 type: systemTimer.TIMER_TYPE_REALTIME, 67 repeat: false 68 }; 69 try { 70 systemTimer.createTimer(options, (error, timerId) => { 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 console.info(`Failed to create timer. message: ${e.message}, code: ${e.code}`); 79 } 80 } 81} 82``` 83 84## systemTimer.createTimer 85 86createTimer(options: TimerOptions): Promise<number> 87 88创建定时器，使用Promise异步回调。 89 90**系统能力：** SystemCapability.MiscServices.Time 91 92**参数：** 93 94| 参数名 | 类型 | 必填 | 说明 | 95| ------- | ----------------------------- | ---- | ------------------------------------------------------------ | 96| options | [TimerOptions](#timeroptions) | 是 | 创建系统定时器的初始化选项，包括定时器类型、是否循环触发、间隔时间、WantAgent通知机制等。 | 97 98**返回值：** 99 100| 类型 | 说明 | 101| --------------------- | ----------------------------- | 102| Promise<number> | Promise对象，返回定时器的ID。 | 103 104**示例：** 105 106```js 107export default { 108 systemTimer () { 109 let options = { 110 type: systemTimer.TIMER_TYPE_REALTIME, 111 repeat:false 112 }; 113 try { 114 systemTimer.createTimer(options).then((timerId) => { 115 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 116 }).catch((error) => { 117 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 118 }); 119 } catch(e) { 120 console.info(`Failed to create timer. message: ${e.message}, code: ${e.code}`); 121 } 122 } 123} 124``` 125 126## systemTimer.startTimer 127 128startTimer(timer: number, triggerTime: number, callback: AsyncCallback<void>): void 129 130开始定时器，使用callback异步回调。 131 132**系统能力：** SystemCapability.MiscServices.Time 133 134**参数：** 135 136| 参数名 | 类型 | 必填 | 说明 | 137| ----------- | ---------------------- | ---- | ------------------------------ | 138| timer | number | 是 | 定时器的ID。 | 139| triggerTime | number | 是 | 定时器的触发时间，单位：毫秒。 | 140| callback | AsyncCallback<void> | 是 | 回调函数。 | 141 142**示例：** 143 144```js 145export default { 146 async systemTimer () { 147 let options = { 148 type: systemTimer.TIMER_TYPE_REALTIME, 149 repeat:false 150 } 151 let timerId = await systemTimer.createTimer(options); 152 let triggerTime = new Date().getTime(); 153 triggerTime += 3000; 154 try { 155 systemTimer.startTimer(timerId, triggerTime, (error) => { 156 if (error) { 157 console.info(`Failed to start timer. message: ${error.message}, code: ${error.code}`); 158 return; 159 } 160 console.info(`Succeeded in starting timer.`); 161 }); 162 } catch(e) { 163 console.info(`Failed to start timer. message: ${e.message}, code: ${e.code}`); 164 } 165 } 166} 167``` 168 169## systemTimer.startTimer 170 171startTimer(timer: number, triggerTime: number): Promise<void> 172 173开始定时器，使用Promise异步回调。 174 175**系统能力：** SystemCapability.MiscServices.Time 176 177**参数：** 178 179| 参数名 | 类型 | 必填 | 说明 | 180| ----------- | ------ | ---- | ------------------------------ | 181| timer | number | 是 | 定时器的ID。 | 182| triggerTime | number | 是 | 定时器的触发时间，单位：毫秒。 | 183 184**返回值：** 185 186| 类型 | 说明 | 187| -------------- | ------------------------- | 188| Promise\<void> | 无返回结果的Promise对象。 | 189 190**示例：** 191 192```js 193export default { 194 async systemTimer (){ 195 let options = { 196 type: systemTimer.TIMER_TYPE_REALTIME, 197 repeat:false 198 } 199 let timerId = await systemTimer.createTimer(options); 200 let triggerTime = new Date().getTime(); 201 triggerTime += 3000; 202 try { 203 systemTimer.startTimer(timerId, triggerTime).then(() => { 204 console.info(`Succeeded in starting timer.`); 205 }).catch((error) => { 206 console.info(`Failed to start timer. message: ${error.message}, code: ${error.code}`); 207 }); 208 } catch(e) { 209 console.info(`Failed to start timer. message: ${e.message}, code: ${e.code}`); 210 } 211 } 212} 213``` 214 215## systemTimer.stopTimer 216 217stopTimer(timer: number, callback: AsyncCallback<void>): void 218 219停止定时器，使用callback异步回调。 220 221**系统能力：** SystemCapability.MiscServices.Time 222 223**参数：** 224 225| 参数名 | 类型 | 必填 | 说明 | 226| -------- | ---------------------- | ---- | ------------ | 227| timer | number | 是 | 定时器的ID。 | 228| callback | AsyncCallback<void> | 是 | 回调函数。 | 229 230**示例：** 231 232```js 233export default { 234 async systemTimer () { 235 let options = { 236 type: systemTimer.TIMER_TYPE_REALTIME, 237 repeat:false 238 } 239 let timerId = await systemTimer.createTimer(options); 240 let triggerTime = new Date().getTime(); 241 triggerTime += 3000; 242 systemTimer.startTimer(timerId, triggerTime); 243 try { 244 systemTimer.stopTimer(timerId, (error) => { 245 if (error) { 246 console.info(`Failed to stop timer. message: ${error.message}, code: ${error.code}`); 247 return; 248 } 249 console.info(`Succeeded in stopping timer.`); 250 }); 251 } catch(e) { 252 console.info(`Failed to stop timer. message: ${e.message}, code: ${e.code}`); 253 } 254 } 255} 256``` 257 258## systemTimer.stopTimer 259 260stopTimer(timer: number): Promise<void> 261 262停止定时器，使用Promise异步回调。 263 264**系统能力：** SystemCapability.MiscServices.Time 265 266**参数：** 267 268| 参数名 | 类型 | 必填 | 说明 | 269| ------ | ------ | ---- | ------------ | 270| timer | number | 是 | 定时器的ID。 | 271 272**返回值：** 273 274| 类型 | 说明 | 275| -------------- | ------------------------- | 276| Promise\<void> | 无返回结果的Promise对象。 | 277 278**示例：** 279 280```js 281export default { 282 async systemTimer (){ 283 let options = { 284 type: systemTimer.TIMER_TYPE_REALTIME, 285 repeat:false 286 } 287 let timerId = await systemTimer.createTimer(options); 288 let triggerTime = new Date().getTime(); 289 triggerTime += 3000; 290 systemTimer.startTimer(timerId, triggerTime); 291 try { 292 systemTimer.stopTimer(timerId).then(() => { 293 console.info(`Succeeded in stopping timer.`); 294 }).catch((error) => { 295 console.info(`Failed to stop timer. message: ${error.message}, code: ${error.code}`); 296 }); 297 } catch(e) { 298 console.info(`Failed to stop timer. message: ${e.message}, code: ${e.code}`); 299 } 300 } 301} 302``` 303 304## systemTimer.destroyTimer 305 306destroyTimer(timer: number, callback: AsyncCallback<void>): void 307 308销毁定时器，使用callback异步回调。 309 310**系统能力：** SystemCapability.MiscServices.Time 311 312**参数：** 313 314| 参数名 | 类型 | 必填 | 说明 | 315| -------- | ---------------------- | ---- | ------------ | 316| timer | number | 是 | 定时器的ID。 | 317| callback | AsyncCallback<void> | 是 | 回调函数。 | 318 319**示例：** 320 321```js 322export default { 323 async systemTimer () { 324 let options = { 325 type: systemTimer.TIMER_TYPE_REALTIME, 326 repeat:false 327 } 328 let timerId = await systemTimer.createTimer(options); 329 let triggerTime = new Date().getTime(); 330 triggerTime += 3000; 331 systemTimer.startTimer(timerId, triggerTime); 332 systemTimer.stopTimer(timerId); 333 try { 334 systemTimer.destroyTimer(timerId, (error) => { 335 if (error) { 336 console.info(`Failed to destroy timer. message: ${error.message}, code: ${error.code}`); 337 return; 338 } 339 console.info(`Succeeded in destroying timer.`); 340 }); 341 } catch(e) { 342 console.info(`Failed to destroying timer. message: ${e.message}, code: ${e.code}`); 343 } 344 } 345} 346``` 347 348## systemTimer.destroyTimer 349 350destroyTimer(timer: number): Promise<void> 351 352销毁定时器，使用Promise异步回调。 353 354**系统能力：** SystemCapability.MiscServices.Time 355 356**参数：** 357 358| 参数名 | 类型 | 必填 | 说明 | 359| ------ | ------ | ---- | ------------ | 360| timer | number | 是 | 定时器的ID。 | 361 362**返回值：** 363 364| 类型 | 说明 | 365| -------------- | ------------------------- | 366| Promise\<void> | 无返回结果的Promise对象。 | 367 368**示例：** 369 370```js 371export default { 372 async systemTimer (){ 373 let options = { 374 type: systemTimer.TIMER_TYPE_REALTIME, 375 repeat:false 376 } 377 let timerId = await systemTimer.createTimer(options); 378 let triggerTime = new Date().getTime(); 379 triggerTime += 3000; 380 systemTimer.startTimer(timerId, triggerTime); 381 systemTimer.stopTimer(timerId); 382 try { 383 systemTimer.destroyTimer(timerId).then(() => { 384 console.info(`Succeeded in destroying timer.`); 385 }).catch((error) => { 386 console.info(`Failed to destroy timer. message: ${error.message}, code: ${error.code}`); 387 }); 388 } catch(e) { 389 console.info(`Failed to destroying timer. message: ${e.message}, code: ${e.code}`); 390 } 391 } 392} 393```