1# @ohos.systemDateTime (系统时间、时区) 2 3本模块主要由系统时间和系统时区功能组成。开发者可以设置、获取系统时间及系统时区。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import systemDateTime from '@ohos.systemDateTime'; 13``` 14 15## TimeType<sup>10+</sup> 16 17定义获取时间的枚举类型。 18 19**系统能力**: SystemCapability.MiscServices.Time 20 21| 名称 | 值 | 说明 | 22| ------- | ---- | ------------------------------------------------ | 23| STARTUP | 0 | 自系统启动以来经过的毫秒数，包括深度睡眠时间。 | 24| ACTIVE | 1 | 自系统启动以来经过的毫秒数，不包括深度睡眠时间。 | 25 26## systemDateTime.getCurrentTime 27 28getCurrentTime(isNano: boolean, callback: AsyncCallback<number>): void 29 30获取自Unix纪元以来经过的时间，使用callback异步回调。 31 32**系统能力：** SystemCapability.MiscServices.Time 33 34**参数：** 35 36| 参数名 | 类型 | 必填 | 说明 | 37| -------- | -------------- | ---- | ------------------ | 38| isNano | boolean | 是 | 返回结果是否为纳秒数。<br>- true：表示返回结果为纳秒数（ns）。 <br>- false：表示返回结果为毫秒数（ms）。 | 39| callback | AsyncCallback<number> | 是 | 回调函数，返回自Unix纪元以来经过的时间戳。 | 40 41**示例：** 42 43```ts 44import { BusinessError } from '@ohos.base'; 45 46try { 47 systemDateTime.getCurrentTime(true, (error: BusinessError, time: number) => { 48 if (error) { 49 console.info(`Failed to get currentTime. message: ${error.message}, code: ${error.code}`); 50 return; 51 } 52 console.info(`Succeeded in getting currentTime : ${time}`); 53 }); 54} catch(e) { 55 let error = e as BusinessError; 56 console.info(`Failed to get currentTime. message: ${error.message}, code: ${error.code}`); 57} 58``` 59 60## systemDateTime.getCurrentTime 61 62getCurrentTime(callback: AsyncCallback<number>): void 63 64获取自Unix纪元以来经过的时间，使用callback异步回调。 65 66**系统能力：** SystemCapability.MiscServices.Time 67 68**参数：** 69 70| 参数名 | 类型 | 必填 | 说明 | 71| -------- | ----------- | ---- | ---------------------------------- | 72| callback | AsyncCallback<number> | 是 | 回调函数，返回自Unix纪元以来经过的时间戳（ms）。 | 73 74**示例：** 75 76```ts 77import { BusinessError } from '@ohos.base'; 78 79try { 80 systemDateTime.getCurrentTime((error: BusinessError, time: number) => { 81 if (error) { 82 console.info(`Failed to get currentTime. message: ${error.message}, code: ${error.code}`); 83 return; 84 } 85 console.info(`Succeeded in getting currentTime : ${time}`); 86 }); 87} catch(e) { 88 let error = e as BusinessError; 89 console.info(`Failed to get currentTime. message: ${error.message}, code: ${error.code}`); 90} 91``` 92 93## systemDateTime.getCurrentTime 94 95getCurrentTime(isNano?: boolean): Promise<number> 96 97获取自Unix纪元以来经过的时间，使用Promise异步回调。 98 99**系统能力：** SystemCapability.MiscServices.Time 100 101**参数：** 102 103| 参数名 | 类型 | 必填 | 说明 | 104| ------ | ------- | ---- | ------------------------- | 105| isNano | boolean | 否 | 返回结果是否为纳秒数,默认值为false。<br/>- true：表示返回结果为纳秒数（ns）。 <br/>- false：表示返回结果为毫秒数（ms）。 | 106 107**返回值：** 108 109| 类型 | 说明 | 110| --------------------- | --------------------------- | 111| Promise<number> | Promise对象，返回自Unix纪元以来经过的时间戳。 | 112 113**示例：** 114 115```ts 116import { BusinessError } from '@ohos.base'; 117 118try { 119 systemDateTime.getCurrentTime().then((time: number) => { 120 console.info(`Succeeded in getting currentTime : ${time}`); 121 }).catch((error: BusinessError) => { 122 console.info(`Failed to get currentTime. message: ${error.message}, code: ${error.code}`); 123 }); 124} catch(e) { 125 let error = e as BusinessError; 126 console.info(`Failed to get currentTime. message: ${error.message}, code: ${error.code}`); 127} 128``` 129 130## systemDateTime.getRealActiveTime 131 132getRealActiveTime(isNano: boolean, callback: AsyncCallback<number>): void 133 134获取自系统启动以来经过的时间，不包括深度睡眠时间，使用callback异步回调。 135 136**系统能力：** SystemCapability.MiscServices.Time 137 138**参数：** 139 140| 参数名 | 类型 | 必填 | 说明 | 141| -------- | ---------- | ---- | -------------------------- | 142| isNano | boolean | 是 | 返回结果是否为纳秒数。<br/>- true：表示返回结果为纳秒数（ns）。 <br/>- false：表示返回结果为毫秒数（ms）。 | 143| callback | AsyncCallback<number> | 是 | 回调函数，返回自系统启动以来经过的时间，但不包括深度睡眠时间。 | 144 145**示例：** 146 147```ts 148import { BusinessError } from '@ohos.base'; 149 150try { 151 systemDateTime.getRealActiveTime(true, (error: BusinessError, time: number) => { 152 if (error) { 153 console.info(`Failed to get real active time. message: ${error.message}, code: ${error.code}`); 154 return; 155 } 156 console.info(`Succeeded in getting real active time : ${time}`); 157 }); 158} catch(e) { 159 let error = e as BusinessError; 160 console.info(`Failed to get real active time. message: ${error.message}, code: ${error.code}`); 161} 162``` 163 164## systemDateTime.getRealActiveTime 165 166getRealActiveTime(callback: AsyncCallback<number>): void 167 168获取自系统启动以来经过的时间，不包括深度睡眠时间，使用callback异步回调。 169 170**系统能力：** SystemCapability.MiscServices.Time 171 172**参数：** 173 174| 参数名 | 类型 | 必填 | 说明 | 175| -------- | -------------- | ---- | --------------------- | 176| callback | AsyncCallback<number> | 是 | 回调函数，返回自系统启动以来经过的时间，但不包括度睡眠时间。 | 177 178**示例：** 179 180```ts 181import { BusinessError } from '@ohos.base'; 182 183try { 184 systemDateTime.getRealActiveTime((error: BusinessError, time: number) => { 185 if (error) { 186 console.info(`Failed to get real active time. message: ${error.message}, code: ${error.code}`); 187 return; 188 } 189 console.info(`Succeeded in getting real active time : ${time}`); 190 }); 191} catch(e) { 192 let error = e as BusinessError; 193 console.info(`Failed to get real active time. message: ${error.message}, code: ${error.code}`); 194} 195``` 196 197## systemDateTime.getRealActiveTime 198 199getRealActiveTime(isNano?: boolean): Promise<number> 200 201获取自系统启动以来经过的时间，不包括深度睡眠时间，使用Promise异步回调。 202 203**系统能力：** SystemCapability.MiscServices.Time 204 205**参数：** 206 207| 参数名 | 类型 | 必填 | 说明 | 208| ------ | ------- | ---- | ----------------------------------- | 209| isNano | boolean | 否 | 返回结果是否为纳秒数,默认值为false。<br/>- true：表示返回结果为纳秒数（ns）。 <br/>- false：表示返回结果为毫秒数（ms）。 | 210 211**返回值：** 212 213| 类型 | 说明 | 214| -------------- | -------------------------------- | 215| Promise<number> | Promise对象，返回自系统启动以来经过的时间，但不包括深度睡眠时间。 | 216 217**示例：** 218 219```ts 220import { BusinessError } from '@ohos.base'; 221 222try { 223 systemDateTime.getRealActiveTime().then((time: number) => { 224 console.info(`Succeeded in getting real active time : ${time}`); 225 }).catch((error: BusinessError) => { 226 console.info(`Failed to get real active time. message: ${error.message}, code: ${error.code}`); 227 }); 228} catch(e) { 229 let error = e as BusinessError; 230 console.info(`Failed to get real active time. message: ${error.message}, code: ${error.code}`); 231} 232``` 233 234## systemDateTime.getRealTime 235 236getRealTime(isNano: boolean, callback: AsyncCallback<number>): void 237 238获取自系统启动以来经过的时间，包括深度睡眠时间，使用callback异步回调。 239 240**系统能力：** SystemCapability.MiscServices.Time 241 242**参数：** 243 244| 参数名 | 类型 | 必填 | 说明 | 245| -------- | --------------- | ---- | ------------------------------- | 246| isNano | boolean | 是 | 返回结果是否为纳秒数。<br/>- true：表示返回结果为纳秒数（ns）。 <br/>- false：表示返回结果为毫秒数（ms）。 | 247| callback | AsyncCallback<number> | 是 | 回调函数，返回自系统启动以来经过的时间，包括深度睡眠时间。 | 248 249**示例：** 250 251```ts 252import { BusinessError } from '@ohos.base'; 253 254try { 255 systemDateTime.getRealTime(true, (error: BusinessError, time: number) => { 256 if (error) { 257 console.info(`Failed to get real time. message: ${error.message}, code: ${error.code}`); 258 return; 259 } 260 console.info(`Succeeded in getting real time : ${time}`); 261 }); 262} catch(e) { 263 let error = e as BusinessError; 264 console.info(`Failed to get real time. message: ${error.message}, code: ${error.code}`); 265} 266``` 267 268## systemDateTime.getRealTime 269 270getRealTime(callback: AsyncCallback<number>): void 271 272获取自系统启动以来经过的时间，包括深度睡眠时间，使用callback异步回调。 273 274**系统能力：** SystemCapability.MiscServices.Time 275 276**参数：** 277 278| 参数名 | 类型 | 必填 | 说明 | 279| -------- | --------- | ---- | --------------------------- | 280| callback | AsyncCallback<number> | 是 | 回调函数，返回自系统启动以来经过的时间，包括深度睡眠时间。 | 281 282**示例：** 283 284```ts 285import { BusinessError } from '@ohos.base'; 286 287try { 288 systemDateTime.getRealTime((error: BusinessError, time: number) => { 289 if (error) { 290 console.info(`Failed to get real time. message: ${error.message}, code: ${error.code}`); 291 return; 292 } 293 console.info(`Succeeded in getting real time : ${time}`); 294 }); 295} catch(e) { 296 let error = e as BusinessError; 297 console.info(`Failed to get real time. message: ${error.message}, code: ${error.code}`); 298} 299``` 300 301## systemDateTime.getRealTime 302 303getRealTime(isNano?: boolean): Promise<number> 304 305获取自系统启动以来经过的时间，包括深度睡眠时间，使用Promise异步回调。 306 307**系统能力：** SystemCapability.MiscServices.Time 308 309**参数：** 310 311| 参数名 | 类型 | 必填 | 说明 | 312| ------ | ------- | ---- | ------------------------------- | 313| isNano | boolean | 否 | 返回结果是否为纳秒数,默认值为false。<br/>- true：表示返回结果为纳秒数（ns）。 <br/>- false：表示返回结果为毫秒数（ms）。 | 314 315**返回值：** 316 317| 类型 | 说明 | 318| --------------------- | ------------------------------- | 319| Promise<number> | Promise对象，返回自系统启动以来经过的时间，包括深度睡眠时间。 | 320 321**示例：** 322 323```ts 324import { BusinessError } from '@ohos.base'; 325 326try { 327 systemDateTime.getRealTime().then((time: number) => { 328 console.info(`Succeeded in getting real time : ${time}`); 329 }).catch((error: BusinessError) => { 330 console.info(`Failed to get real time. message: ${error.message}, code: ${error.code}`); 331 }); 332} catch(e) { 333 let error = e as BusinessError; 334 console.info(`Failed to get real time. message: ${error.message}, code: ${error.code}`); 335} 336``` 337 338## systemDateTime.getTime<sup>10+</sup> 339 340getTime(isNanoseconds?: boolean): number 341 342 使用同步方式获取自Unix纪元以来经过的时间。 343 344**系统能力：** SystemCapability.MiscServices.Time 345 346**参数：** 347 348| 参数名 | 类型 | 必填 | 说明 | 349| ------------- | ------- | ---- | ------------------------------------------------------------ | 350| isNanoseconds | boolean | 否 | 返回结果是否为纳秒数。<br>- true：表示返回结果为纳秒数（ns）。 <br>- false：表示返回结果为毫秒数（ms）。<br>默认值为false。 | 351 352**返回值**： 353 354| 类型 | 说明 | 355| ------ | -------------------------- | 356| number | 自Unix纪元以来经过的时间。 | 357 358**示例：** 359 360```ts 361try { 362 let time = systemDateTime.getTime(true) 363} catch(e) { 364 let error = e as BusinessError; 365 console.info(`Failed to get time. message: ${error.message}, code: ${error.code}`); 366} 367``` 368 369## systemDateTime.getUptime<sup>10+</sup> 370 371getUptime(timeType: TimeType, isNanoseconds?: boolean): number 372 373使用同步方式获取自系统启动以来经过的时间。 374 375**系统能力：** SystemCapability.MiscServices.Time 376 377**参数：** 378 379| 参数名 | 类型 | 必填 | 说明 | 380| ------------- | ----------------------- | ---- | ------------------------------------------------------------ | 381| timeType | [TimeType](#timetype10) | 是 | 获取时间的类型。 | 382| isNanoseconds | boolean | 否 | 返回结果是否为纳秒数。<br/>- true：表示返回结果为纳秒数（ns）。 <br/>- false：表示返回结果为毫秒数（ms）。<br>默认值为false。 | 383 384**返回值：** 385 386| 类型 | 说明 | 387| ------ | -------------------------- | 388| number | 自系统启动以来经过的时间。 | 389 390**示例：** 391 392```ts 393try { 394 let time = systemDateTime.getUptime(systemDateTime.TimeType.ACTIVE, false); 395} catch(e) { 396 let error = e as BusinessError; 397 console.info(`Failed to get uptime. message: ${error.message}, code: ${error.code}`); 398} 399``` 400 401## systemDateTime.getDate<sup>(deprecated)</sup> 402 403getDate(callback: AsyncCallback<Date>): void 404 405获取当前系统日期，使用callback异步回调。 406 407> **说明：** 408> 409> 从API version 9开始支持，从API 10开始废弃。建议使用new Date()替代，new Date()返回Date实例对象。 410 411**系统能力：** SystemCapability.MiscServices.Time 412 413**参数：** 414 415| 参数名 | 类型 | 必填 | 说明 | 416| -------- | -------------- | ---- | --------------------- | 417| callback | AsyncCallback<Date> | 是 | 回调函数，返回当前系统日期。 | 418 419**示例：** 420 421```ts 422import { BusinessError } from '@ohos.base'; 423 424try { 425 systemDateTime.getDate((error: BusinessError, date: Date) => { 426 if (error) { 427 console.info(`Failed to get date. message: ${error.message}, code: ${error.code}`); 428 return; 429 } 430 console.info(`Succeeded in getting date : ${date}`);; 431 }); 432} catch(e) { 433 let error = e as BusinessError; 434 console.info(`Failed to get date. message: ${error.message}, code: ${error.code}`); 435} 436``` 437 438## systemDateTime.getDate<sup>(deprecated)</sup> 439 440getDate(): Promise<Date> 441 442获取当前系统日期，使用Promise异步回调。 443 444> **说明：** 445> 446> 从API version 9开始支持，从API 10开始废弃。建议使用new Date()替代，new Date()返回Date实例对象。 447 448**系统能力：** SystemCapability.MiscServices.Time 449 450**返回值：** 451 452| 类型 | 说明 | 453| ------------------- | ----------------------------------------- | 454| Promise<Date> | Promise对象，返回当前系统日期。 | 455 456**示例：** 457 458```ts 459import { BusinessError } from '@ohos.base'; 460 461try { 462 systemDateTime.getDate().then((date: Date) => { 463 console.info(`Succeeded in getting date : ${date}`); 464 }).catch((error: BusinessError) => { 465 console.info(`Failed to get date. message: ${error.message}, code: ${error.code}`); 466 }); 467} catch(e) { 468 let error = e as BusinessError; 469 console.info(`Failed to get date. message: ${error.message}, code: ${error.code}`); 470} 471``` 472 473## systemDateTime.getTimezone 474 475getTimezone(callback: AsyncCallback<string>): void 476 477获取系统时区，使用callback异步回调。 478 479**系统能力：** SystemCapability.MiscServices.Time 480 481**参数：** 482 483| 参数名 | 类型 | 必填 | 说明 | 484| -------- | --------- | ---- | ------------------------ | 485| callback | AsyncCallback<string> | 是 | 回调函数，返回系统时区。具体可见[支持的系统时区](#支持的系统时区) 。 | 486 487**示例：** 488 489```ts 490import { BusinessError } from '@ohos.base'; 491 492try { 493 systemDateTime.getTimezone((error: BusinessError, data: string) => { 494 if (error) { 495 console.info(`Failed to get timezone. message: ${error.message}, code: ${error.code}`); 496 return; 497 } 498 console.info(`Succeeded in get timezone : ${data}`);; 499 }); 500} catch(e) { 501 let error = e as BusinessError; 502 console.info(`Failed to get timezone. message: ${error.message}, code: ${error.code}`); 503} 504``` 505 506## systemDateTime.getTimezone 507 508getTimezone(): Promise<string> 509 510获取系统时区，使用Promise异步回调。 511 512**系统能力：** SystemCapability.MiscServices.Time 513 514**返回值：** 515 516| 类型 | 说明 | 517| --------------------- | ------------------------------------- | 518| Promise<string> | Promise对象，返回系统时区。具体可见[支持的系统时区](#支持的系统时区) 。 | 519 520**示例：** 521 522```ts 523import { BusinessError } from '@ohos.base'; 524 525try { 526 systemDateTime.getTimezone().then((data: string) => { 527 console.info(`Succeeded in getting timezone: ${data}`); 528 }).catch((error: BusinessError) => { 529 console.info(`Failed to get timezone. message: ${error.message}, code: ${error.code}`); 530 }); 531} catch(e) { 532 let error = e as BusinessError; 533 console.info(`Failed to get timezone. message: ${error.message}, code: ${error.code}`); 534} 535``` 536 537## systemDateTime.getTimezoneSync<sup>10+</sup> 538 539getTimezoneSync(): string 540 541获取系统时区，使用同步方式。 542 543**系统能力：** SystemCapability.MiscServices.Time 544 545**返回值：** 546 547| 类型 | 说明 | 548| ------ | ---------------------------------------------------------- | 549| string | 返回系统时区。具体可见[支持的系统时区](#支持的系统时区) 。 | 550 551**示例：** 552 553```ts 554try { 555 let timezone = systemDateTime.getTimezoneSync(); 556} catch(e) { 557 let error = e as BusinessError; 558 console.info(`Failed to get timezone. message: ${error.message}, code: ${error.code}`); 559} 560``` 561 562## 支持的系统时区 563 564支持的系统时区及各时区与0时区相比的偏移量（单位：h）可见下表。 565 566| 时区 | 偏移量 | 567| ------------------------------ | --------------------- | 568| Antarctica/McMurdo | 12 | 569| America/Argentina/Buenos_Aires | -3 | 570| Australia/Sydney | 10 | 571| America/Noronha | -2 | 572| America/St_Johns | -3 | 573| Africa/Kinshasa | 1 | 574| America/Santiago | -3 | 575| Asia/Shanghai | 8 | 576| Asia/Nicosia | 3 | 577| Europe/Berlin | 2 | 578| America/Guayaquil | -5 | 579| Europe/Madrid | 2 | 580| Pacific/Pohnpei | 11 | 581| America/Godthab | -2 | 582| Asia/Jakarta | 7 | 583| Pacific/Tarawa | 12 | 584| Asia/Almaty | 6 | 585| Pacific/Majuro | 12 | 586| Asia/Ulaanbaatar | 8 | 587| America/Mexico_City | -5 | 588| Asia/Kuala_Lumpur | 8 | 589| Pacific/Auckland | 12 | 590| Pacific/Tahiti | -10 | 591| Pacific/Port_Moresby | 10 | 592| Asia/Gaza | 3 | 593| Europe/Lisbon | 1 | 594| Europe/Moscow | 3 | 595| Europe/Kiev | 3 | 596| Pacific/Wake | 12 | 597| America/New_York | -4 | 598| Asia/Tashkent | 5 |