1# @ohos.systemDateTime (System Time and Time Zone) 2 3The **systemDateTime** module provides system time and time zone features. You can use the APIs of this module to set and obtain the system time and time zone. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```js 12import systemDateTime from '@ohos.systemDateTime'; 13``` 14 15## systemDateTime.setTime 16 17setTime(time : number, callback : AsyncCallback<void>) : void 18 19Sets the system time. This API uses an asynchronous callback to return the result. 20 21**System API**: This is a system API. 22 23**System capability**: SystemCapability.MiscServices.Time 24 25**Parameters** 26 27| Name | Type | Mandatory| Description | 28| -------- | ----------- | ---- | ---------------- | 29| time | number | Yes | Timestamp to set, in milliseconds. | 30| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 31 32**Example** 33 34```js 35// Set the system time to 2021-01-20 02:36:25. 36let time = 1611081385000; 37try { 38 systemDateTime.setTime(time, (error) => { 39 if (error) { 40 console.info(`Failed to set time. message:${error.message}, code:${error.code}`); 41 return; 42 } 43 console.info(`Succeeded in setting time`); 44 }); 45} catch(e) { 46 console.info(`Failed to set time. message:${e.message}, code:${e.code}`); 47} 48``` 49 50## systemDateTime.setTime 51 52setTime(time : number) : Promise<void> 53 54Sets the system time. This API uses a promise to return the result. 55 56**System API**: This is a system API. 57 58**System capability**: SystemCapability.MiscServices.Time 59 60**Parameters** 61 62| Name| Type | Mandatory| Description | 63| ------ | ------ | ---- | ------------------ | 64| time | number | Yes | Timestamp to set, in milliseconds.| 65 66**Return value** 67 68| Type | Description | 69| ------------------- | ------------------------- | 70| Promise<void> | Promise that returns no value.| 71 72**Example** 73 74```js 75// Set the system time to 2021-01-20 02:36:25. 76let time = 1611081385000; 77try { 78 systemDateTime.setTime(time).then(() => { 79 console.info(`Succeeded in setting time.`); 80 }).catch((error) => { 81 console.info(`Failed to set time. message:${error.message}, code:${error.code}`); 82 }); 83} catch(e) { 84 console.info(`Failed to set time. message:${e.message}, code:${e.code}`); 85} 86``` 87 88## systemDateTime.getCurrentTime 89 90getCurrentTime(isNano: boolean, callback: AsyncCallback<number>): void 91 92Obtains the time elapsed since the Unix epoch. This API uses an asynchronous callback to return the result. 93 94**System capability**: SystemCapability.MiscServices.Time 95 96**Parameters** 97 98| Name | Type | Mandatory| Description | 99| -------- | -------------- | ---- | ------------------ | 100| isNano | boolean | Yes | Whether the time to return is in nanoseconds.<br>- **true**: The time to return is in nanoseconds.<br>- **false**: The time to return is in milliseconds.| 101| callback | AsyncCallback<number> | Yes | Callback used to return the time elapsed since the Unix epoch. | 102 103**Example** 104 105```js 106try { 107 systemDateTime.getCurrentTime(true, (error, time) => { 108 if (error) { 109 console.info(`Failed to get currentTime. message:${error.message}, code:${error.code}`); 110 return; 111 } 112 console.info(`Succeeded in getting currentTime : ${time}`); 113 }); 114} catch(e) { 115 console.info(`Failed to get currentTime. message:${e.message}, code:${e.code}`); 116} 117``` 118 119## systemDateTime.getCurrentTime 120 121getCurrentTime(callback: AsyncCallback<number>): void 122 123Obtains the time elapsed since the Unix epoch. This API uses an asynchronous callback to return the result. 124 125**System capability**: SystemCapability.MiscServices.Time 126 127**Parameters** 128 129| Name | Type | Mandatory| Description | 130| -------- | ----------- | ---- | ---------------------------------- | 131| callback | AsyncCallback<number> | Yes | Callback used to return the time elapsed since the Unix epoch. | 132 133**Example** 134 135```js 136try { 137 systemDateTime.getCurrentTime((error, time) => { 138 if (error) { 139 console.info(`Failed to get currentTime. message:${error.message}, code:${error.code}`); 140 return; 141 } 142 console.info(`Succeeded in getting currentTime : ${time}`); 143 }); 144} catch(e) { 145 console.info(`Failed to get currentTime. message:${e.message}, code:${e.code}`); 146} 147``` 148 149## systemDateTime.getCurrentTime 150 151getCurrentTime(isNano?: boolean): Promise<number> 152 153Obtains the time elapsed since the Unix epoch. This API uses a promise to return the result. 154 155**System capability**: SystemCapability.MiscServices.Time 156 157**Parameters** 158 159| Name| Type | Mandatory| Description | 160| ------ | ------- | ---- | ------------------------- | 161| isNano | boolean | No | Whether the time to return is in nanoseconds.<br>- **true**: The time to return is in nanoseconds.<br>- **false**: The time to return is in milliseconds.| 162 163**Return value** 164 165| Type | Description | 166| --------------------- | --------------------------- | 167| Promise<number> | Promise used to return the time elapsed since the Unix epoch.| 168 169**Example** 170 171```js 172try { 173 systemDateTime.getCurrentTime().then((time) => { 174 console.info(`Succeeded in getting currentTime : ${time}`); 175 }).catch((error) => { 176 console.info(`Failed to get currentTime. message:${error.message}, code:${error.code}`); 177 }); 178} catch(e) { 179 console.info(`Failed to get currentTime. message:${e.message}, code:${e.code}`); 180} 181``` 182 183## systemDateTime.getRealActiveTime 184 185getRealActiveTime(isNano: boolean, callback: AsyncCallback<number>): void 186 187Obtains the time elapsed since system startup, excluding the deep sleep time. This API uses an asynchronous callback to return the result. 188 189**System capability**: SystemCapability.MiscServices.Time 190 191**Parameters** 192 193| Name | Type | Mandatory| Description | 194| -------- | ---------- | ---- | -------------------------- | 195| isNano | boolean | Yes | Whether the time to return is in nanoseconds.<br>- **true**: The time to return is in nanoseconds.<br>- **false**: The time to return is in milliseconds.| 196| callback | AsyncCallback<number> | Yes | Callback used to return the time.| 197 198**Example** 199 200```js 201try { 202 systemDateTime.getRealActiveTime(true, (error, time) => { 203 if (error) { 204 console.info(`Failed to get real active time. message:${error.message}, code:${error.code}`); 205 return; 206 } 207 console.info(`Succeeded in getting real active time : ${time}`); 208 }); 209} catch(e) { 210 console.info(`Failed to get real active time. message:${e.message}, code:${e.code}`); 211} 212``` 213 214## systemDateTime.getRealActiveTime 215 216getRealActiveTime(callback: AsyncCallback<number>): void 217 218Obtains the time elapsed since system startup, excluding the deep sleep time. This API uses an asynchronous callback to return the result. 219 220**System capability**: SystemCapability.MiscServices.Time 221 222**Parameters** 223 224| Name | Type | Mandatory| Description | 225| -------- | -------------- | ---- | --------------------- | 226| callback | AsyncCallback<number> | Yes | Callback used to return the time.| 227 228**Example** 229 230```js 231try { 232 systemDateTime.getRealActiveTime((error, time) => { 233 if (error) { 234 console.info(`Failed to get real active time. message:${error.message}, code:${error.code}`); 235 return; 236 } 237 console.info(`Succeeded in getting real active time : ${time}`); 238 }); 239} catch(e) { 240 console.info(`Failed to get real active time. message:${e.message}, code:${e.code}`); 241} 242``` 243 244## systemDateTime.getRealActiveTime 245 246getRealActiveTime(isNano?: boolean): Promise<number> 247 248Obtains the time elapsed since system startup, excluding the deep sleep time. This API uses a promise to return the result. 249 250**System capability**: SystemCapability.MiscServices.Time 251 252**Parameters** 253 254| Name| Type | Mandatory| Description | 255| ------ | ------- | ---- | ----------------------------------- | 256| isNano | boolean | No | Whether the time to return is in nanoseconds.<br>- **true**: The time to return is in nanoseconds.<br>- **false**: The time to return is in milliseconds.| 257 258**Return value** 259 260| Type | Description | 261| -------------- | -------------------------------- | 262| Promise<number> | Promise used to return the time elapsed since system startup, excluding the deep sleep time.| 263 264**Example** 265 266```js 267try { 268 systemDateTime.getRealActiveTime().then((time) => { 269 console.info(`Succeeded in getting real active time : ${time}`); 270 }).catch((error) => { 271 console.info(`Failed to get real active time. message:${error.message}, code:${error.code}`); 272 }); 273} catch(e) { 274 console.info(`Failed to get real active time. message:${e.message}, code:${e.code}`); 275} 276``` 277 278## systemDateTime.getRealTime 279 280getRealTime(isNano: boolean, callback: AsyncCallback<number>): void 281 282Obtains the time elapsed since system startup, including the deep sleep time. This API uses an asynchronous callback to return the result. 283 284**System capability**: SystemCapability.MiscServices.Time 285 286**Parameters** 287 288| Name | Type | Mandatory| Description | 289| -------- | --------------- | ---- | ------------------------------- | 290| isNano | boolean | Yes | Whether the time to return is in nanoseconds.<br>- **true**: The time to return is in nanoseconds.<br>- **false**: The time to return is in milliseconds.| 291| callback | AsyncCallback<number> | Yes | Callback used to return the time. | 292 293**Example** 294 295```js 296try { 297 systemDateTime.getRealTime(true, (error, time) => { 298 if (error) { 299 console.info(`Failed to get real time. message:${error.message}, code:${error.code}`); 300 return; 301 } 302 console.info(`Succeeded in getting real time : ${time}`); 303 }); 304} catch(e) { 305 console.info(`Failed to get real time. message:${e.message}, code:${e.code}`); 306} 307``` 308 309## systemDateTime.getRealTime 310 311getRealTime(callback: AsyncCallback<number>): void 312 313Obtains the time elapsed since system startup, including the deep sleep time. This API uses an asynchronous callback to return the result. 314 315**System capability**: SystemCapability.MiscServices.Time 316 317**Parameters** 318 319| Name | Type | Mandatory| Description | 320| -------- | --------- | ---- | --------------------------- | 321| callback | AsyncCallback<number> | Yes | Callback used to return the time. | 322 323**Example** 324 325```js 326try { 327 systemDateTime.getRealTime((error, time) => { 328 if (error) { 329 console.info(`Failed to get real time. message:${error.message}, code:${error.code}`); 330 return; 331 } 332 console.info(`Succeeded in getting real time : ${time}`); 333 }); 334} catch(e) { 335 console.info(`Failed to get real time. message:${e.message}, code:${e.code}`); 336} 337``` 338 339## systemDateTime.getRealTime 340 341getRealTime(isNano?: boolean): Promise<number> 342 343Obtains the time elapsed since system startup, including the deep sleep time. This API uses a promise to return the result. 344 345**System capability**: SystemCapability.MiscServices.Time 346 347**Parameters** 348 349| Name| Type | Mandatory| Description | 350| ------ | ------- | ---- | ------------------------------- | 351| isNano | boolean | No | Whether the time to return is in nanoseconds.<br>- **true**: The time to return is in nanoseconds.<br>- **false**: The time to return is in milliseconds.| 352 353**Return value** 354 355| Type | Description | 356| --------------------- | ------------------------------- | 357| Promise<number> | Promise used to return the time elapsed since system startup, including the deep sleep time.| 358 359**Example** 360 361```js 362try { 363 systemDateTime.getRealTime().then((time) => { 364 console.info(`Succeeded in getting real time : ${time}`); 365 }).catch((error) => { 366 console.info(`Failed to get real time. message:${error.message}, code:${error.code}`); 367 }); 368} catch(e) { 369 console.info(`Failed to get real time. message:${e.message}, code:${e.code}`); 370} 371``` 372 373## systemDateTime.setDate 374 375setDate(date: Date, callback: AsyncCallback<void>): void 376 377Sets the system date. This API uses an asynchronous callback to return the result. 378 379**System API**: This is a system API. 380 381**System capability**: SystemCapability.MiscServices.Time 382 383**Parameters** 384 385| Name | Type | Mandatory| Description | 386| -------- | ------------- | ---- | --------------------- | 387| date | Date | Yes | Target date to set. | 388| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 389 390**Example** 391 392```js 393let date = new Date(); 394try { 395 systemDateTime.setDate(date, (error) => { 396 if (error) { 397 console.info(`Failed to set date. message:${error.message}, code:${error.code}`); 398 return; 399 } 400 console.info(`Succeeded in setting date.`); 401 }); 402} catch(e) { 403 console.info(`Failed to set date. message:${e.message}, code:${e.code}`); 404} 405``` 406 407## systemDateTime.setDate 408 409setDate(date: Date): Promise<void> 410 411Sets the system date. This API uses a promise to return the result. 412 413**System API**: This is a system API. 414 415**System capability**: SystemCapability.MiscServices.Time 416 417**Parameters** 418 419| Name| Type| Mandatory| Description | 420| ------ | ---- | ---- | ---------- | 421| date | Date | Yes | Target date to set.| 422 423**Return value** 424 425| Type | Description | 426| ------------------- | -------------------- | 427| Promise<void> | Promise that returns no value.| 428 429**Example** 430 431```js 432let date = new Date(); 433try { 434 systemDateTime.setDate(date).then(() => { 435 console.info(`Succeeded in setting date.`); 436 }).catch((error) => { 437 console.info(`Failed to set date. message:${error.message}, code:${error.code}`); 438 }); 439} catch(e) { 440 console.info(`Failed to set date. message:${e.message}, code:${e.code}`); 441} 442``` 443 444## systemDateTime.getDate 445 446getDate(callback: AsyncCallback<Date>): void 447 448Obtains the current system date. This API uses an asynchronous callback to return the result. 449 450**System capability**: SystemCapability.MiscServices.Time 451 452**Parameters** 453 454| Name | Type | Mandatory| Description | 455| -------- | -------------- | ---- | --------------------- | 456| callback | AsyncCallback<Date> | Yes | Callback used to return the current system date.| 457 458**Example** 459 460```js 461try { 462 systemDateTime.getDate((error, date) => { 463 if (error) { 464 console.info(`Failed to get date. message:${error.message}, code:${error.code}`); 465 return; 466 } 467 console.info(`Succeeded in getting date : ${date}`);; 468 }); 469} catch(e) { 470 console.info(`Failed to get date. message:${e.message}, code:${e.code}`); 471} 472``` 473 474## systemDateTime.getDate 475 476getDate(): Promise<Date> 477 478Obtains the current system date. This API uses a promise to return the result. 479 480**System capability**: SystemCapability.MiscServices.Time 481 482**Return value** 483 484| Type | Description | 485| ------------------- | ----------------------------------------- | 486| Promise<Date> | Promise used to return the current system date.| 487 488**Example** 489 490```js 491try { 492 systemDateTime.getDate().then((date) => { 493 console.info(`Succeeded in getting date : ${date}`); 494 }).catch((error) => { 495 console.info(`Failed to get date. message:${error.message}, code:${error.code}`); 496 }); 497} catch(e) { 498 console.info(`Failed to get date. message:${e.message}, code:${e.code}`); 499} 500``` 501 502## systemDateTime.setTimezone 503 504setTimezone(timezone: string, callback: AsyncCallback<void>): void 505 506Sets the system time zone. This API uses an asynchronous callback to return the result. 507 508**System API**: This is a system API. 509 510**System capability**: SystemCapability.MiscServices.Time 511 512**Parameters** 513 514| Name | Type | Mandatory| Description | 515| -------- | ------------- | ---- | -------------------------- | 516| timezone | string | Yes | System time zone to set. For details, see [Supported System Time Zones](#supported-system-time-zones). | 517| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 518 519**Example** 520 521```js 522try { 523 systemDateTime.setTimezone('Asia/Shanghai', (error) => { 524 if (error) { 525 console.info(`Failed to set timezone. message:${error.message}, code:${error.code}`); 526 return; 527 } 528 console.info(`Succeeded in setting timezone.`); 529 }); 530} catch(e) { 531 console.info(`Failed to set timezone. message:${e.message}, code:${e.code}`); 532} 533``` 534 535## systemDateTime.setTimezone 536 537setTimezone(timezone: string): Promise<void> 538 539Sets the system time zone. This API uses a promise to return the result. 540 541**System API**: This is a system API. 542 543**System capability**: SystemCapability.MiscServices.Time 544 545**Parameters** 546 547| Name | Type | Mandatory| Description | 548| -------- | ------ | ---- | ---------- | 549| timezone | string | Yes | System time zone to set. For details, see [Supported System Time Zones](#supported-system-time-zones).| 550 551**Return value** 552 553| Type | Description | 554| ------------------- | -------------------- | 555| Promise<void> | Promise that returns no value.| 556 557**Example** 558 559```js 560try { 561 systemDateTime.setTimezone('Asia/Shanghai').then(() => { 562 console.info(`Succeeded in setting timezone.`); 563 }).catch((error) => { 564 console.info(`Failed to set timezone. message:${error.message}, code:${error.code}`); 565 }); 566} catch(e) { 567 console.info(`Failed to set timezone. message:${e.message}, code:${e.code}`); 568} 569``` 570 571## systemDateTime.getTimezone 572 573getTimezone(callback: AsyncCallback<string>): void 574 575Obtains the system time zone. This API uses an asynchronous callback to return the result. 576 577**System capability**: SystemCapability.MiscServices.Time 578 579**Parameters** 580 581| Name | Type | Mandatory| Description | 582| -------- | --------- | ---- | ------------------------ | 583| callback | AsyncCallback<string> | Yes | Callback used to return the system time zone. For details, see [Supported System Time Zones](#supported-system-time-zones).| 584 585**Example** 586 587```js 588try { 589 systemDateTime.getTimezone((error, data) => { 590 if (error) { 591 console.info(`Failed to get timezone. message:${error.message}, code:${error.code}`); 592 return; 593 } 594 console.info(`Succeeded in get timezone : ${data}`);; 595 }); 596} catch(e) { 597 console.info(`Failed to get timezone. message:${e.message}, code:${e.code}`); 598} 599``` 600 601## systemDateTime.getTimezone 602 603getTimezone(): Promise<string> 604 605Obtains the system time zone. This API uses a promise to return the result. 606 607**System capability**: SystemCapability.MiscServices.Time 608 609**Return value** 610 611| Type | Description | 612| --------------------- | ------------------------------------- | 613| Promise<string> | Promise used to return the system time zone. For details, see [Supported System Time Zones](#supported-system-time-zones).| 614 615**Example** 616 617```js 618try { 619 systemDateTime.getTimezone().then((data) => { 620 console.info(`Succeeded in getting timezone: ${data}`); 621 }).catch((error) => { 622 console.info(`Failed to get timezone. message:${error.message}, code:${error.code}`); 623 }); 624} catch(e) { 625 console.info(`Failed to get timezone. message:${e.message}, code:${e.code}`); 626} 627``` 628 629## Supported System Time Zones 630 631The following table lists the supported system time zones and the respective offset (unit: h) between each time zone and time zone 0. 632 633| Time Zone | Offset | 634| ------------------------------ | --------------------- | 635| Antarctica/McMurdo | 12 | 636| America/Argentina/Buenos_Aires | -3 | 637| Australia/Sydney | 10 | 638| America/Noronha | -2 | 639| America/St_Johns | -3 | 640| Africa/Kinshasa | 1 | 641| America/Santiago | -3 | 642| Asia/Shanghai | 8 | 643| Asia/Nicosia | 3 | 644| Europe/Berlin | 2 | 645| America/Guayaquil | -5 | 646| Europe/Madrid | 2 | 647| Pacific/Pohnpei | 11 | 648| America/Godthab | -2 | 649| Asia/Jakarta | 7 | 650| Pacific/Tarawa | 12 | 651| Asia/Almaty | 6 | 652| Pacific/Majuro | 12 | 653| Asia/Ulaanbaatar | 8 | 654| America/Mexico_City | -5 | 655| Asia/Kuala_Lumpur | 8 | 656| Pacific/Auckland | 12 | 657| Pacific/Tahiti | -10 | 658| Pacific/Port_Moresby | 10 | 659| Asia/Gaza | 3 | 660| Europe/Lisbon | 1 | 661| Europe/Moscow | 3 | 662| Europe/Kiev | 3 | 663| Pacific/Wake | 12 | 664| America/New_York | -4 | 665| Asia/Tashkent | 5 | 666