1# System Time and Time Zone 2 3The **systemTime** 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 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```js 12import systemTime from '@ohos.systemTime'; 13``` 14 15## systemTime.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**Required permissions**: ohos.permission.SET_TIME 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; 37systemTime.setTime(time, (error) => { 38 if (error) { 39 console.error(`Failed to set systemTime. Cause:` + JSON.stringify(error)); 40 return; 41 } 42 console.log('Succeeded in setting systemTime.'); 43}); 44``` 45 46## systemTime.setTime 47 48setTime(time : number) : Promise<void> 49 50Sets the system time. This API uses a promise to return the result. 51 52**Required permissions**: ohos.permission.SET_TIME 53 54**System capability**: SystemCapability.MiscServices.Time 55 56**Parameters** 57 58| Name| Type | Mandatory| Description | 59| ------ | ------ | ---- | ------------------ | 60| time | number | Yes | Timestamp to set, in milliseconds.| 61 62**Return value** 63 64| Type | Description | 65| ------------------- | ------------------------- | 66| Promise<void> | Promise that returns no value.| 67 68**Example** 69 70```js 71// Set the system time to 2021-01-20 02:36:25. 72let time = 1611081385000; 73systemTime.setTime(time).then(() => { 74 console.log('Succeeded in setting systemTime.'); 75}).catch((error) => { 76 console.error(`Failed to set systemTime. Cause:` + JSON.stringify(error)); 77}); 78``` 79 80## systemTime.getCurrentTime<sup>8+</sup> 81 82getCurrentTime(isNano?: boolean, callback: AsyncCallback<number>): void 83 84Obtains the time elapsed since the Unix epoch. This API uses an asynchronous callback to return the result. 85 86**System capability**: SystemCapability.MiscServices.Time 87 88**Parameters** 89 90| Name | Type | Mandatory| Description | 91| -------- | -------------- | ---- | ------------------ | 92| isNano | boolean | No | Whether the time to return is in nanoseconds.<br>- **true**: in nanoseconds (ns).<br>- **false**: in milliseconds (ms).| 93| callback | AsyncCallback<number> | Yes | Callback used to return the time elapsed since the Unix epoch. | 94 95**Example** 96 97```js 98systemTime.getCurrentTime(true, (error, data) => { 99 if (error) { 100 console.error(`Failed to get systemTime. Cause:` + JSON.stringify(error)); 101 return; 102 } 103 console.log(`Succeeded in getting systemTime.Data: ` + JSON.stringify(data)); 104}); 105``` 106 107## systemTime.getCurrentTime<sup>8+</sup> 108 109getCurrentTime(isNano?: boolean): Promise<number> 110 111Obtains the time elapsed since the Unix epoch. This API uses a promise to return the result. 112 113**System capability**: SystemCapability.MiscServices.Time 114 115**Parameters** 116 117| Name| Type | Mandatory| Description | 118| ------ | ------- | ---- | ------------------------- | 119| isNano | boolean | No | Whether the time to return is in nanoseconds.<br>- **true**: in nanoseconds (ns).<br>- **false**: in milliseconds (ms).| 120 121**Return value** 122 123| Type | Description | 124| --------------------- | --------------------------- | 125| Promise<number> | Promise used to return the time elapsed since the Unix epoch.| 126 127**Example** 128 129```js 130systemTime.getCurrentTime().then((data) => { 131 console.log(`Succeeded in getting systemTime.Data: ` + JSON.stringify(data)); 132}).catch((error) => { 133 console.error(`Failed to get systemTime. Cause:` + JSON.stringify(error)); 134}); 135``` 136 137## systemTime.getRealActiveTime<sup>8+</sup> 138 139getRealActiveTime(isNano?: boolean, callback: AsyncCallback<number>): void 140 141Obtains the time elapsed since system startup, excluding the deep sleep time. This API uses an asynchronous callback to return the result. 142 143**System capability**: SystemCapability.MiscServices.Time 144 145**Parameters** 146 147| Name | Type | Mandatory| Description | 148| -------- | ---------- | ---- | -------------------------- | 149| isNano | boolean | No | Whether the time to return is in nanoseconds.<br>- **true**: in nanoseconds (ns).<br>- **false**: in milliseconds (ms).| 150| callback | AsyncCallback<number> | Yes | Callback used to return the time.| 151 152**Example** 153 154```js 155systemTime.getRealActiveTime(true, (error, data) => { 156 if (error) { 157 console.error(`Failed to get real active systemTime. Cause:` + JSON.stringify(error)); 158 return; 159 } 160 console.log(`Succeeded in getting real active systemTime. Data: ` + JSON.stringify(data)); 161}); 162``` 163 164## systemTime.getRealActiveTime<sup>8+</sup> 165 166getRealActiveTime(isNano?: boolean): Promise<number> 167 168Obtains the time elapsed since system startup, excluding the deep sleep time. This API uses a promise to return the result. 169 170**System capability**: SystemCapability.MiscServices.Time 171 172**Parameters** 173 174| Name| Type | Mandatory| Description | 175| ------ | ------- | ---- | ----------------------------------- | 176| isNano | boolean | No | Whether the time to return is in nanoseconds.<br>- **true**: in nanoseconds (ns).<br>- **false**: in milliseconds (ms).| 177 178**Return value** 179 180| Type | Description | 181| -------------- | -------------------------------- | 182| Promise<number> | Promise used to return the time elapsed since system startup, excluding the deep sleep time.| 183 184**Example** 185 186```js 187systemTime.getRealActiveTime().then((data) => { 188 console.log(`Succeeded in getting real active systemTime. Data: ` + JSON.stringify(data)); 189}).catch((error) => { 190 console.error(`Failed to get real active systemTime. Cause:` + JSON.stringify(error)); 191}); 192``` 193 194## systemTime.getRealTime<sup>8+</sup> 195 196getRealTime(isNano?: boolean, callback: AsyncCallback<number>): void 197 198Obtains the time elapsed since system startup, including the deep sleep time. This API uses an asynchronous callback to return the result. 199 200**System capability**: SystemCapability.MiscServices.Time 201 202**Parameters** 203 204| Name | Type | Mandatory| Description | 205| -------- | --------------- | ---- | ------------------------------- | 206| isNano | boolean | No | Whether the time to return is in nanoseconds.<br>- **true**: in nanoseconds (ns).<br>- **false**: in milliseconds (ms).| 207| callback | AsyncCallback<number> | Yes | Callback used to return the time. | 208 209**Example** 210 211```js 212systemTime.getRealTime(true, (error, data) => { 213 if (error) { 214 console.error(`Failed to get real systemTime. Cause:` + JSON.stringify(error)); 215 return; 216 } 217 console.log(`Succeeded in getting real active systemTime. Data: ` + JSON.stringify(data)); 218}); 219``` 220 221## systemTime.getRealTime<sup>8+</sup> 222 223getRealTime(isNano?: boolean): Promise<number> 224 225Obtains the time elapsed since system startup, including the deep sleep time. This API uses a promise to return the result. 226 227**System capability**: SystemCapability.MiscServices.Time 228 229**Parameters** 230 231| Name| Type | Mandatory| Description | 232| ------ | ------- | ---- | ------------------------------- | 233| isNano | boolean | No | Whether the time to return is in nanoseconds.<<br>- **true**: in nanoseconds (ns).<br>- **false**: in milliseconds (ms).| 234 235**Return value** 236 237| Type | Description | 238| --------------------- | ------------------------------- | 239| Promise<number> | Promise used to return the time elapsed since system startup, including the deep sleep time.| 240 241**Example** 242 243```js 244systemTime.getRealTime().then((data) => { 245 console.log(`Succeeded in getting real active systemTime. Data: ` + JSON.stringify(data)); 246}).catch((error) => { 247 console.error(`Failed to get real systemTime. Cause:` + JSON.stringify(error)); 248}); 249``` 250 251## systemTime.setDate 252 253setDate(date: Date, callback: AsyncCallback<void>): void 254 255Sets the system date. This API uses an asynchronous callback to return the result. 256 257**Required permissions**: ohos.permission.SET_TIME 258 259**System capability**: SystemCapability.MiscServices.Time 260 261**Parameters** 262 263| Name | Type | Mandatory| Description | 264| -------- | ------------- | ---- | --------------------- | 265| date | Date | Yes | Target date to set. | 266| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 267 268**Example** 269 270```js 271let data = new Date("October 13, 2020 11:13:00"); 272systemTime.setDate(data,(error) => { 273 if (error) { 274 console.error('Failed to set systemDate. Cause: ' + JSON.stringify(error)); 275 return; 276} 277 console.info('Succeeded in setting systemDate.'); 278}); 279``` 280 281## systemTime.setDate 282 283setDate(date: Date): Promise<void> 284 285Sets the system date. This API uses a promise to return the result. 286 287**Required permissions**: ohos.permission.SET_TIME 288 289**System capability**: SystemCapability.MiscServices.Time 290 291**Parameters** 292 293| Name| Type| Mandatory| Description | 294| ------ | ---- | ---- | ---------- | 295| date | Date | Yes | Target date to set.| 296 297**Return value** 298 299| Type | Description | 300| ------------------- | -------------------- | 301| Promise<void> | Promise that returns no value.| 302 303**Example** 304 305```js 306let data = new Date("October 13, 2020 11:13:00"); 307systemTime.setDate(data).then(() => { 308 console.log('Succeeded in setting systemDate.'); 309}).catch((error) => { 310 console.error(`Failed to set systemDate. Cause: ` + JSON.stringify(error)); 311}); 312``` 313 314## systemTime.getDate<sup>8+</sup> 315 316getDate(callback: AsyncCallback<Date>): void 317 318Obtains the current system date. This API uses an asynchronous callback to return the result. 319 320**System capability**: SystemCapability.MiscServices.Time 321 322**Parameters** 323 324| Name | Type | Mandatory| Description | 325| -------- | -------------- | ---- | --------------------- | 326| callback | AsyncCallback<Date> | Yes | Callback used to return the current system date.| 327 328**Example** 329 330```js 331systemTime.getDate((error, data) => { 332 if (error) { 333 console.error(`Failed to get systemDate. Cause: ` + JSON.stringify(error)); 334 return; 335 } 336 console.log(`Succeeded in getting systemDate. Data: ` + JSON.stringify(data)); 337}); 338``` 339 340## systemTime.getDate<sup>8+</sup> 341 342getDate(): Promise<Date> 343 344Obtains the current system date. This API uses a promise to return the result. 345 346**System capability**: SystemCapability.MiscServices.Time 347 348**Return value** 349 350| Type | Description | 351| ------------------- | ----------------------------------------- | 352| Promise<Date> | Promise used to return the current system date.| 353 354**Example** 355 356```js 357systemTime.getDate().then((data) => { 358 console.log(`Succeeded in getting systemDate. Data: ` + JSON.stringify(data)); 359}).catch((error) => { 360 console.error(`Failed to get systemDate. Cause: ` + JSON.stringify(error)); 361}); 362``` 363 364## systemTime.setTimezone 365 366setTimezone(timezone: string, callback: AsyncCallback<void>): void 367 368Sets the system time zone. This API uses an asynchronous callback to return the result. 369 370**Required permissions**: ohos.permission.SET_TIME_ZONE 371 372**System capability**: SystemCapability.MiscServices.Time 373 374**Parameters** 375 376| Name | Type | Mandatory| Description | 377| -------- | ------------- | ---- | -------------------------- | 378| timezone | string | Yes | System time zone to set. | 379| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 380 381**Example** 382 383```js 384systemTime.setTimezone('Asia/Shanghai', (error) => { 385 if (error) { 386 console.error('Failed to set systemTimeZone. Cause: ' + JSON.stringify(error)); 387 return; 388 } 389 console.info('Succeeded in setting systemTimeZone.'); 390}); 391``` 392 393## systemTime.setTimezone 394 395setTimezone(timezone: string): Promise<void> 396 397Sets the system time zone. This API uses a promise to return the result. 398 399**Required permissions**: ohos.permission.SET_TIME_ZONE 400 401**System capability**: SystemCapability.MiscServices.Time 402 403**Parameters** 404 405| Name | Type | Mandatory| Description | 406| -------- | ------ | ---- | ---------- | 407| timezone | string | Yes | System time zone to set.| 408 409**Return value** 410 411| Type | Description | 412| ------------------- | -------------------- | 413| Promise<void> | Promise that returns no value.| 414 415**Example** 416 417```js 418systemTime.setTimezone('Asia/Shanghai').then(() => { 419 console.log('Succeeded in setting systemTimeZone.'); 420}).catch((error) => { 421 console.error(`Failed to set systemTimeZone. Cause: ` + JSON.stringify(error)); 422}); 423``` 424 425## systemTime.getTimezone<sup>8+</sup> 426 427getTimezone(callback: AsyncCallback<string>): void 428 429Obtains the system time zone. This API uses an asynchronous callback to return the result. 430 431**System capability**: SystemCapability.MiscServices.Time 432 433**Parameters** 434 435| Name | Type | Mandatory| Description | 436| -------- | --------- | ---- | ------------------------ | 437| callback | AsyncCallback<string> | Yes | Callback used to return the system time zone.| 438 439**Example** 440 441```js 442systemTime.getTimezone((error, data) => { 443 if (error) { 444 console.error(`Failed to get systemTimeZone. Cause: ` + JSON.stringify(error)); 445 return; 446 } 447 console.log(`Succeeded in getting systemTimeZone. Data: ` + JSON.stringify(data)); 448}); 449``` 450 451## systemTime.getTimezone<sup>8+</sup> 452 453getTimezone(): Promise<string> 454 455Obtains the system time zone. This API uses a promise to return the result. 456 457**System capability**: SystemCapability.MiscServices.Time 458 459**Return value** 460 461| Type | Description | 462| --------------------- | ------------------------------------- | 463| Promise<string> | Promise used to return the system time zone.| 464 465**Example** 466 467```js 468systemTime.getTimezone().then((data) => { 469 console.log(`Succeeded in getting systemTimeZone. Data: ` + JSON.stringify(data)); 470}).catch((error) => { 471 console.error(`Failed to get systemTimeZone. Cause: ` + JSON.stringify(error)); 472}); 473``` 474