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