1# @ohos.systemDateTime (系统时间、时区) 2 3本模块主要由系统时间和系统时区功能组成。开发者可以设置、获取系统时间及系统时区。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```js 12import systemDateTime from '@ohos.systemDateTime'; 13``` 14 15## systemDateTime.setTime 16 17setTime(time : number, callback : AsyncCallback<void>) : void 18 19设置系统时间，使用callback异步回调。 20 21**系统接口：** 此接口为系统接口 22 23**系统能力：** SystemCapability.MiscServices.Time 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| -------- | ----------- | ---- | ---------------- | 29| time | number | 是 | 目标时间戳（ms）。 | 30| callback | AsyncCallback<void> | 是 | 回调函数。 | 31 32**示例：** 33 34```js 35// time对应的时间为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 54设置系统时间，使用Promise异步回调。 55 56**系统接口：** 此接口为系统接口 57 58**系统能力：** SystemCapability.MiscServices.Time 59 60**参数：** 61 62| 参数名 | 类型 | 必填 | 说明 | 63| ------ | ------ | ---- | ------------------ | 64| time | number | 是 | 目标时间戳（ms）。 | 65 66**返回值：** 67 68| 类型 | 说明 | 69| ------------------- | ------------------------- | 70| Promise<void> | 无返回结果的Promise对象。 | 71 72**示例：** 73 74```js 75// time对应的时间为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 92获取自Unix纪元以来经过的时间，使用callback异步回调。 93 94**系统能力：** SystemCapability.MiscServices.Time 95 96**参数：** 97 98| 参数名 | 类型 | 必填 | 说明 | 99| -------- | -------------- | ---- | ------------------ | 100| isNano | boolean | 是 | 返回结果是否为纳秒数。<br>- true：表示返回结果为纳秒数（ns）。 <br>- false：表示返回结果为毫秒数（ms）。 | 101| callback | AsyncCallback<number> | 是 | 回调函数，返回自Unix纪元以来经过的时间。 | 102 103**示例：** 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 123获取自Unix纪元以来经过的时间，使用callback异步回调。 124 125**系统能力：** SystemCapability.MiscServices.Time 126 127**参数：** 128 129| 参数名 | 类型 | 必填 | 说明 | 130| -------- | ----------- | ---- | ---------------------------------- | 131| callback | AsyncCallback<number> | 是 | 回调函数，返回自Unix纪元以来经过的时间。 | 132 133**示例：** 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 153获取自Unix纪元以来经过的时间，使用Promise异步回调。 154 155**系统能力：** SystemCapability.MiscServices.Time 156 157**参数：** 158 159| 参数名 | 类型 | 必填 | 说明 | 160| ------ | ------- | ---- | ------------------------- | 161| isNano | boolean | 否 | 返回结果是否为纳秒数。<br/>- true：表示返回结果为纳秒数（ns）。 <br/>- false：表示返回结果为毫秒数（ms）。 | 162 163**返回值：** 164 165| 类型 | 说明 | 166| --------------------- | --------------------------- | 167| Promise<number> | Promise对象，返回自Unix纪元以来经过的时间。 | 168 169**示例：** 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 187获取自系统启动以来经过的时间，不包括深度睡眠时间，使用callback异步回调。 188 189**系统能力：** SystemCapability.MiscServices.Time 190 191**参数：** 192 193| 参数名 | 类型 | 必填 | 说明 | 194| -------- | ---------- | ---- | -------------------------- | 195| isNano | boolean | 是 | 返回结果是否为纳秒数。<br/>- true：表示返回结果为纳秒数（ns）。 <br/>- false：表示返回结果为毫秒数（ms）。 | 196| callback | AsyncCallback<number> | 是 | 回调函数，返回自系统启动以来经过的时间，但不包括深度睡眠时间。 | 197 198**示例：** 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 218获取自系统启动以来经过的时间，不包括深度睡眠时间，使用callback异步回调。 219 220**系统能力：** SystemCapability.MiscServices.Time 221 222**参数：** 223 224| 参数名 | 类型 | 必填 | 说明 | 225| -------- | -------------- | ---- | --------------------- | 226| callback | AsyncCallback<number> | 是 | 回调函数，返回自系统启动以来经过的时间，但不包括度睡眠时间。 | 227 228**示例：** 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 248获取自系统启动以来经过的时间，不包括深度睡眠时间，使用Promise异步回调。 249 250**系统能力：** SystemCapability.MiscServices.Time 251 252**参数：** 253 254| 参数名 | 类型 | 必填 | 说明 | 255| ------ | ------- | ---- | ----------------------------------- | 256| isNano | boolean | 否 | 返回结果是否为纳秒数。<br/>- true：表示返回结果为纳秒数（ns）。 <br/>- false：表示返回结果为毫秒数（ms）。 | 257 258**返回值：** 259 260| 类型 | 说明 | 261| -------------- | -------------------------------- | 262| Promise<number> | Promise对象，返回自系统启动以来经过的时间，但不包括深度睡眠时间。 | 263 264**示例：** 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 282获取自系统启动以来经过的时间，包括深度睡眠时间，使用callback异步回调。 283 284**系统能力：** SystemCapability.MiscServices.Time 285 286**参数：** 287 288| 参数名 | 类型 | 必填 | 说明 | 289| -------- | --------------- | ---- | ------------------------------- | 290| isNano | boolean | 是 | 返回结果是否为纳秒数。<br/>- true：表示返回结果为纳秒数（ns）。 <br/>- false：表示返回结果为毫秒数（ms）。 | 291| callback | AsyncCallback<number> | 是 | 回调函数，返回自系统启动以来经过的时间，包括深度睡眠时间。 | 292 293**示例：** 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 313获取自系统启动以来经过的时间，包括深度睡眠时间，使用callback异步回调。 314 315**系统能力：** SystemCapability.MiscServices.Time 316 317**参数：** 318 319| 参数名 | 类型 | 必填 | 说明 | 320| -------- | --------- | ---- | --------------------------- | 321| callback | AsyncCallback<number> | 是 | 回调函数，返回自系统启动以来经过的时间，包括深度睡眠时间。 | 322 323**示例：** 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 343获取自系统启动以来经过的时间，包括深度睡眠时间，使用Promise异步回调。 344 345**系统能力：** SystemCapability.MiscServices.Time 346 347**参数：** 348 349| 参数名 | 类型 | 必填 | 说明 | 350| ------ | ------- | ---- | ------------------------------- | 351| isNano | boolean | 否 | 返回结果是否为纳秒数。<br/>- true：表示返回结果为纳秒数（ns）。 <br/>- false：表示返回结果为毫秒数（ms）。 | 352 353**返回值：** 354 355| 类型 | 说明 | 356| --------------------- | ------------------------------- | 357| Promise<number> | Promise对象，返回自系统启动以来经过的时间，包括深度睡眠时间。 | 358 359**示例：** 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 377设置系统日期，使用callback异步回调。 378 379**系统接口：** 此接口为系统接口 380 381**系统能力：** SystemCapability.MiscServices.Time 382 383**参数：** 384 385| 参数名 | 类型 | 必填 | 说明 | 386| -------- | ------------- | ---- | --------------------- | 387| date | Date | 是 | 目标日期。 | 388| callback | AsyncCallback<void> | 是 | 回调函数。 | 389 390**示例：** 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 411设置系统日期，使用Promise异步回调。 412 413**系统接口：** 此接口为系统接口 414 415**系统能力：** SystemCapability.MiscServices.Time 416 417**参数：** 418 419| 参数名 | 类型 | 必填 | 说明 | 420| ------ | ---- | ---- | ---------- | 421| date | Date | 是 | 目标日期。 | 422 423**返回值：** 424 425| 类型 | 说明 | 426| ------------------- | -------------------- | 427| Promise<void> | 无返回结果的Promise对象。 | 428 429**示例：** 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 448获取当前系统日期，使用callback异步回调。 449 450**系统能力：** SystemCapability.MiscServices.Time 451 452**参数：** 453 454| 参数名 | 类型 | 必填 | 说明 | 455| -------- | -------------- | ---- | --------------------- | 456| callback | AsyncCallback<Date> | 是 | 回调函数，返回当前系统日期。 | 457 458**示例：** 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 478获取当前系统日期，使用Promise异步回调。 479 480**系统能力：** SystemCapability.MiscServices.Time 481 482**返回值：** 483 484| 类型 | 说明 | 485| ------------------- | ----------------------------------------- | 486| Promise<Date> | Promise对象，返回当前系统日期。 | 487 488**示例：** 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 506设置系统时区，使用callback异步回调。 507 508**系统接口：** 此接口为系统接口 509 510**系统能力：** SystemCapability.MiscServices.Time 511 512**参数：** 513 514| 参数名 | 类型 | 必填 | 说明 | 515| -------- | ------------- | ---- | -------------------------- | 516| timezone | string | 是 | 系统时区。 具体可见[支持的系统时区](#支持的系统时区) 。 | 517| callback | AsyncCallback<void> | 是 | 回调函数。 | 518 519**示例：** 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 539设置系统时区，使用Promise异步回调。 540 541**系统接口：** 此接口为系统接口 542 543**系统能力：** SystemCapability.MiscServices.Time 544 545**参数：** 546 547| 参数名 | 类型 | 必填 | 说明 | 548| -------- | ------ | ---- | ---------- | 549| timezone | string | 是 | 系统时区。具体可见[支持的系统时区](#支持的系统时区) 。 | 550 551**返回值：** 552 553| 类型 | 说明 | 554| ------------------- | -------------------- | 555| Promise<void> | 无返回结果的Promise对象。 | 556 557**示例：** 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 575获取系统时区，使用callback异步回调。 576 577**系统能力：** SystemCapability.MiscServices.Time 578 579**参数：** 580 581| 参数名 | 类型 | 必填 | 说明 | 582| -------- | --------- | ---- | ------------------------ | 583| callback | AsyncCallback<string> | 是 | 回调函数，返回系统时区。具体可见[支持的系统时区](#支持的系统时区) 。 | 584 585**示例：** 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 605获取系统时区，使用Promise异步回调。 606 607**系统能力：** SystemCapability.MiscServices.Time 608 609**返回值：** 610 611| 类型 | 说明 | 612| --------------------- | ------------------------------------- | 613| Promise<string> | Promise对象，返回系统时区。具体可见[支持的系统时区](#支持的系统时区) 。 | 614 615**示例：** 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## 支持的系统时区 630 631支持的系统时区及各时区与0时区相比的偏移量（单位：h）可见下表。 632 633| 时区 | 偏移量 | 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 |