1# @ohos.systemTimer (系统定时器)(系统接口) 2 3本模块主要由系统定时器功能组成。开发者可以使用定时功能实现定时服务，如闹钟等。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - 本模块接口为系统接口。 9 10## 导入模块 11 12 13```ts 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 | 是 | 是否为循环定时器。<br>true为循环定时器，false为单次定时器。 | 40| interval | number | 否 | 定时器时间间隔。<br>如果是循环定时器，interval值应大于5000毫秒；单次定时器interval值为0。 | 41| wantAgent | WantAgent | 否 | 设置通知的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```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 87创建定时器，使用Promise异步回调。 88 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```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 129开启定时器，使用callback异步回调。 130 131**系统能力：** SystemCapability.MiscServices.Time 132 133**参数：** 134 135| 参数名 | 类型 | 必填 | 说明 | 136| ----------- | ---------------------- | ---- | ------------------------------ | 137| timer | number | 是 | 定时器的ID。 | 138| triggerTime | number | 是 | 定时器的触发时间，单位：毫秒。 | 139| callback | AsyncCallback<void> | 是 | 回调函数。 | 140 141**示例：** 142 143```ts 144import { BusinessError } from '@ohos.base'; 145 146let options: systemTimer.TimerOptions = { 147 type: systemTimer.TIMER_TYPE_REALTIME, 148 repeat:false 149} 150let triggerTime = new Date().getTime(); 151triggerTime += 3000; 152 153try { 154 systemTimer.createTimer(options).then((timerId: number) => { 155 systemTimer.startTimer(timerId, triggerTime, (error: BusinessError) => { 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 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 163 }).catch((error: BusinessError) => { 164 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 165 }); 166} catch(e) { 167 let error = e as BusinessError; 168 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 169} 170``` 171 172## systemTimer.startTimer 173 174startTimer(timer: number, triggerTime: number): Promise<void> 175 176开启定时器，使用Promise异步回调。 177 178**系统能力：** SystemCapability.MiscServices.Time 179 180**参数：** 181 182| 参数名 | 类型 | 必填 | 说明 | 183| ----------- | ------ | ---- | ------------------------------ | 184| timer | number | 是 | 定时器的ID。 | 185| triggerTime | number | 是 | 定时器的触发时间，单位：毫秒。 | 186 187**返回值：** 188 189| 类型 | 说明 | 190| -------------- | ------------------------- | 191| Promise\<void> | 无返回结果的Promise对象。 | 192 193**示例：** 194 195```ts 196import { BusinessError } from '@ohos.base'; 197 198let options: systemTimer.TimerOptions = { 199 type: systemTimer.TIMER_TYPE_REALTIME, 200 repeat:false 201} 202let triggerTime = new Date().getTime(); 203triggerTime += 3000; 204 205try { 206 systemTimer.createTimer(options).then((timerId: number) => { 207 systemTimer.startTimer(timerId, triggerTime).then(() => { 208 console.info(`Succeeded in starting timer.`); 209 }).catch((error: BusinessError) => { 210 console.info(`Failed to start timer. message: ${error.message}, code: ${error.code}`); 211 }); 212 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 213 }).catch((error: BusinessError) => { 214 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 215 }); 216} catch(e) { 217 let error = e as BusinessError; 218 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 219} 220``` 221 222## systemTimer.stopTimer 223 224stopTimer(timer: number, callback: AsyncCallback<void>): void 225 226停止定时器，使用callback异步回调。 227 228**系统能力：** SystemCapability.MiscServices.Time 229 230**参数：** 231 232| 参数名 | 类型 | 必填 | 说明 | 233| -------- | ---------------------- | ---- | ------------ | 234| timer | number | 是 | 定时器的ID。 | 235| callback | AsyncCallback<void> | 是 | 回调函数。 | 236 237**示例：** 238 239```ts 240import { BusinessError } from '@ohos.base'; 241 242let options: systemTimer.TimerOptions = { 243 type: systemTimer.TIMER_TYPE_REALTIME, 244 repeat:false 245} 246let triggerTime = new Date().getTime(); 247triggerTime += 3000; 248 249try { 250 systemTimer.createTimer(options).then((timerId: number) => { 251 systemTimer.startTimer(timerId, triggerTime); 252 systemTimer.stopTimer(timerId, (error: BusinessError) => { 253 if (error) { 254 console.info(`Failed to stop timer. message: ${error.message}, code: ${error.code}`); 255 return; 256 } 257 console.info(`Succeeded in stopping timer.`); 258 }); 259 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 260 }).catch((error: BusinessError) => { 261 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 262 }); 263} catch(e) { 264 let error = e as BusinessError; 265 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 266} 267``` 268 269## systemTimer.stopTimer 270 271stopTimer(timer: number): Promise<void> 272 273停止定时器，使用Promise异步回调。 274 275**系统能力：** SystemCapability.MiscServices.Time 276 277**参数：** 278 279| 参数名 | 类型 | 必填 | 说明 | 280| ------ | ------ | ---- | ------------ | 281| timer | number | 是 | 定时器的ID。 | 282 283**返回值：** 284 285| 类型 | 说明 | 286| -------------- | ------------------------- | 287| Promise\<void> | 无返回结果的Promise对象。 | 288 289**示例：** 290 291```ts 292import { BusinessError } from '@ohos.base'; 293 294let options: systemTimer.TimerOptions = { 295 type: systemTimer.TIMER_TYPE_REALTIME, 296 repeat:false 297} 298let triggerTime = new Date().getTime(); 299triggerTime += 3000; 300 301try { 302 systemTimer.createTimer(options).then((timerId: number) => { 303 systemTimer.startTimer(timerId, triggerTime); 304 systemTimer.stopTimer(timerId).then(() => { 305 console.info(`Succeeded in stopping timer.`); 306 }).catch((error: BusinessError) => { 307 console.info(`Failed to stop timer. message: ${error.message}, code: ${error.code}`); 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.destroyTimer 320 321destroyTimer(timer: number, callback: AsyncCallback<void>): void 322 323销毁定时器，使用callback异步回调。 324 325**系统能力：** SystemCapability.MiscServices.Time 326 327**参数：** 328 329| 参数名 | 类型 | 必填 | 说明 | 330| -------- | ---------------------- | ---- | ------------ | 331| timer | number | 是 | 定时器的ID。 | 332| callback | AsyncCallback<void> | 是 | 回调函数。 | 333 334**示例：** 335 336```ts 337import { BusinessError } from '@ohos.base'; 338 339let options: systemTimer.TimerOptions = { 340 type: systemTimer.TIMER_TYPE_REALTIME, 341 repeat:false 342} 343let triggerTime = new Date().getTime(); 344triggerTime += 3000; 345 346try { 347 systemTimer.createTimer(options).then((timerId: number) => { 348 systemTimer.startTimer(timerId, triggerTime); 349 systemTimer.stopTimer(timerId); 350 systemTimer.destroyTimer(timerId, (error: BusinessError) => { 351 if (error) { 352 console.info(`Failed to destroy timer. message: ${error.message}, code: ${error.code}`); 353 return; 354 } 355 console.info(`Succeeded in destroying timer.`); 356 }); 357 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 358 }).catch((error: BusinessError) => { 359 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 360 }); 361} catch(e) { 362 let error = e as BusinessError; 363 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 364} 365``` 366 367## systemTimer.destroyTimer 368 369destroyTimer(timer: number): Promise<void> 370 371销毁定时器，使用Promise异步回调。 372 373**系统能力：** SystemCapability.MiscServices.Time 374 375**参数：** 376 377| 参数名 | 类型 | 必填 | 说明 | 378| ------ | ------ | ---- | ------------ | 379| timer | number | 是 | 定时器的ID。 | 380 381**返回值：** 382 383| 类型 | 说明 | 384| -------------- | ------------------------- | 385| Promise\<void> | 无返回结果的Promise对象。 | 386 387**示例：** 388 389```ts 390import { BusinessError } from '@ohos.base'; 391 392let options: systemTimer.TimerOptions = { 393 type: systemTimer.TIMER_TYPE_REALTIME, 394 repeat:false 395} 396let triggerTime = new Date().getTime(); 397triggerTime += 3000; 398 399try { 400 systemTimer.createTimer(options).then((timerId: number) => { 401 systemTimer.startTimer(timerId, triggerTime); 402 systemTimer.stopTimer(timerId); 403 systemTimer.destroyTimer(timerId).then(() => { 404 console.info(`Succeeded in destroying timer.`); 405 }).catch((error: BusinessError) => { 406 console.info(`Failed to destroy timer. message: ${error.message}, code: ${error.code}`); 407 }); 408 console.info(`Succeeded in creating timer. timerId: ${timerId}`); 409 }).catch((error: BusinessError) => { 410 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 411 }); 412} catch(e) { 413 let error = e as BusinessError; 414 console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`); 415} 416```