js-apis-system-time.md 14.1 KB
Newer Older
W
wusongqing 已提交
1
# Setting the System Time
Z
zengyawen 已提交
2

E
ester.zhou 已提交
3 4 5
This module provides the time, time zone, and timing services. Use the time and time zone services to set and obtain the system time and time zone, and use the timing service to manage and use the system time and time zone to implement alarms or other timing functions.

> **NOTE**<br>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.
Z
zengyawen 已提交
6 7


W
wusongqing 已提交
8
## Modules to Import
Z
zengyawen 已提交
9

E
ester.zhou 已提交
10

Z
zengyawen 已提交
11 12 13 14 15
```
import systemTime from '@ohos.systemTime';
```


W
wusongqing 已提交
16
## systemTime.setTime
Z
zengyawen 已提交
17

W
wusongqing 已提交
18 19 20 21 22 23
setTime(time : number, callback : AsyncCallback&lt;void&gt;) : void

Sets the system time. This API uses an asynchronous callback to return the result.

**Required permissions**: ohos.permission.SET_TIME

E
ester.zhou 已提交
24
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
25

E
ester.zhou 已提交
26
**Parameters**
W
wusongqing 已提交
27

E
ester.zhou 已提交
28 29 30 31 32 33 34 35 36
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| time | number | Yes| Timestamp to set, in milliseconds.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to process the received return value.|

**Example**

  ```js
// Set the system time to 2021-01-20 02:36:25.
W
wusongqing 已提交
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
  var time = 1611081385000;
  systemTime.setTime(time, (error, data) => {
      if (error) {
          console.error(`failed to systemTime.setTime because ` + JSON.stringify(error));
          return;
      }
      console.log(`systemTime.setTime success data : ` + JSON.stringify(data));
  });
  ```


## systemTime.setTime

setTime(time : number) : Promise&lt;void&gt;

Sets the system time. This API uses a promise to return the result.

**Required permissions**: ohos.permission.SET_TIME

E
ester.zhou 已提交
56
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
57

E
ester.zhou 已提交
58
**Parameters**
W
wusongqing 已提交
59

E
ester.zhou 已提交
60 61 62
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| time | number | Yes| Timestamp to set, in milliseconds.|
W
wusongqing 已提交
63

E
ester.zhou 已提交
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79
**Return value**

| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|

**Example**

  ```js
// Set the system time to 2021-01-20 02:36:25.
var time = 1611081385000;
systemTime.setTime(time).then((data) => {
    console.log(`systemTime.setTime success data : ` + JSON.stringify(data));
}).catch((error) => {
    console.error(`failed to systemTime.setTime because ` + JSON.stringify(error));
});
W
wusongqing 已提交
80 81 82 83 84 85 86 87 88
  ```


## systemTime.getCurrentTime<sup>8+</sup>

getCurrentTime(isNano?: boolean, callback: AsyncCallback&lt;number&gt;): void

Obtains the time elapsed since the Unix epoch. This API uses an asynchronous callback to return the result.

E
ester.zhou 已提交
89
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
90

E
ester.zhou 已提交
91
**Parameters**
W
wusongqing 已提交
92

E
ester.zhou 已提交
93 94 95 96 97 98 99 100
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
| callback | AsyncCallback&lt;number&gt; | Yes| Callback used to return the time.|

**Example**

  ```js
W
wusongqing 已提交
101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
  systemTime.getCurrentTime(true, (error, data) => {
      if (error) {
          console.error(`failed to systemTime.getCurrentTime because ` + JSON.stringify(error));
          return;
      }
      console.log(`systemTime.getCurrentTime success data : ` + JSON.stringify(data));
  });
  ```


## systemTime.getCurrentTime<sup>8+</sup>

getCurrentTime(isNano?: boolean): Promise&lt;number&gt;

Obtains the time elapsed since the Unix epoch. This API uses a promise to return the result.

E
ester.zhou 已提交
117
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
118

E
ester.zhou 已提交
119
**Parameters**
W
wusongqing 已提交
120

E
ester.zhou 已提交
121 122 123
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
W
wusongqing 已提交
124

E
ester.zhou 已提交
125 126 127 128 129 130 131 132 133
**Return value**

| Type| Description|
| -------- | -------- |
| Promise&lt;number&gt; | Promise used to return the time.|

**Example**

  ```js
W
wusongqing 已提交
134 135 136 137 138 139 140 141 142 143 144 145 146 147
  systemTime.getCurrentTime().then((data) => {
      console.log(`systemTime.getCurrentTime success data : ` + JSON.stringify(data));
  }).catch((error) => {
      console.error(`failed to systemTime.getCurrentTime because ` + JSON.stringify(error));
  });
  ```


## systemTime.getRealActiveTime<sup>8+</sup>

getRealActiveTime(isNano?: boolean, callback: AsyncCallback&lt;number&gt;): void

Obtains the time elapsed since system start, excluding the deep sleep time. This API uses an asynchronous callback to return the result.

E
ester.zhou 已提交
148
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
149

E
ester.zhou 已提交
150
**Parameters**
W
wusongqing 已提交
151

E
ester.zhou 已提交
152 153 154 155 156 157 158 159
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
| callback | AsyncCallback&lt;number&gt; | Yes| Callback used to return the time.|

**Example**

  ```js
W
wusongqing 已提交
160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175
  systemTime.getRealActiveTime(true, (error, data) => {
      if (error) {
          console.error(`failed to systemTime.getRealActiveTimebecause ` + JSON.stringify(error));
          return;
      }
      console.log(`systemTime.getRealActiveTime success data : ` + JSON.stringify(data));
  });
  ```


## systemTime.getRealActiveTime<sup>8+</sup>

getRealActiveTime(isNano?: boolean): Promise&lt;number&gt;

Obtains the time elapsed since system start, excluding the deep sleep time. This API uses a promise to return the result.

E
ester.zhou 已提交
176
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
177

E
ester.zhou 已提交
178
**Parameters**
W
wusongqing 已提交
179

E
ester.zhou 已提交
180 181 182
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
W
wusongqing 已提交
183

E
ester.zhou 已提交
184 185 186 187 188 189 190 191 192
**Return value**

| Type| Description|
| -------- | -------- |
| Promise&lt;number&gt; | Promise used to return the time.|

**Example**

  ```js
E
ester.zhou 已提交
193
  systemTime.getRealActiveTime().then((data) => {
W
wusongqing 已提交
194 195 196 197 198 199 200 201 202
      console.log(`systemTime.getRealActiveTime success data : ` + JSON.stringify(data));
  }).catch((error) => {
      console.error(`failed to systemTime.getRealActiveTime because ` + JSON.stringify(error));
  });
  ```


## systemTime.getRealTime<sup>8+</sup>

E
ester.zhou 已提交
203
getRealTime(isNano?: boolean, callback: AsyncCallback&lt;number&gt;): void
W
wusongqing 已提交
204 205 206

Obtains the time elapsed since system start, including the deep sleep time. This API uses an asynchronous callback to return the result.

E
ester.zhou 已提交
207
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
208

E
ester.zhou 已提交
209
**Parameters**
W
wusongqing 已提交
210

E
ester.zhou 已提交
211 212 213 214 215 216 217 218
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
| callback | AsyncCallback&lt;number&gt; | Yes| Callback used to return the time.|

**Example**

  ```js
W
wusongqing 已提交
219 220 221 222 223 224 225 226 227 228 229 230
  systemTime.getRealTime(true, (error, data) => {
      if (error) {
          console.error(`failed to systemTime.getRealTime because ` + JSON.stringify(error));
          return;
      }
      console.log(`systemTime.getRealTime success data: ` + JSON.stringify(data));
  });
  ```


## systemTime.getRealTime<sup>8+</sup>

E
ester.zhou 已提交
231
getRealTime(isNano?: boolean): Promise&lt;number&gt;
W
wusongqing 已提交
232 233 234

Obtains the time elapsed since system start, including the deep sleep time. This API uses a promise to return the result.

E
ester.zhou 已提交
235
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
236

E
ester.zhou 已提交
237
**Parameters**
W
wusongqing 已提交
238

E
ester.zhou 已提交
239 240 241
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| isNano | boolean | No| Whether nanoseconds or milliseconds will be returned. If the value is **true**, nanoseconds will be returned. Otherwise, milliseconds will be returned.|
W
wusongqing 已提交
242

E
ester.zhou 已提交
243 244 245 246 247 248 249 250 251
**Return value**

| Type| Description|
| -------- | -------- |
| Promise&lt;number&gt; | Promise used to return the time.|

**Example**

  ```js
W
wusongqing 已提交
252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267
  systemTime.getRealTime().then((data) => {
      console.log(`systemTime.getRealTime success data: ` + JSON.stringify(data));
  }).catch((error) => {
      console.error(`failed to systemTime.getRealTime because ` + JSON.stringify(error));
  });
  ```


## systemTime.setDate

setDate(date: Date, callback: AsyncCallback&lt;void&gt;): void

Sets the system date. This API uses an asynchronous callback to return the result.

**Required permissions**: ohos.permission.SET_TIME

E
ester.zhou 已提交
268
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
269

E
ester.zhou 已提交
270
**Parameters**
W
wusongqing 已提交
271

E
ester.zhou 已提交
272 273 274 275 276 277 278 279
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| date | Date | Yes| Target date to set.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to process the received return value.|

**Example**

  ```js
W
wusongqing 已提交
280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298
  var data = new Date("October 13, 2020 11:13:00");
  systemTime.setDate(data,(error, data) => {       
      if (error) {            
      console.error('failed to systemTime.setDate because ' + JSON.stringify(error));           
      return;       
  }        
      console.info('systemTime.setDate success data : ' + JSON.stringify(data));    
  });
  ```


## systemTime.setDate

setDate(date: Date): Promise&lt;void&gt;

Sets the system date. This API uses a promise to return the result.

**Required permissions**: ohos.permission.SET_TIME

E
ester.zhou 已提交
299
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
300

E
ester.zhou 已提交
301
**Parameters**
W
wusongqing 已提交
302

E
ester.zhou 已提交
303 304 305
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| date | Date | Yes| Target date to set.|
W
wusongqing 已提交
306

E
ester.zhou 已提交
307 308 309 310 311 312 313 314 315
**Return value**

| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|

**Example**

  ```js
W
wusongqing 已提交
316 317 318 319 320 321 322 323 324 325 326 327 328 329 330
  var data = new Date("October 13, 2020 11:13:00"); 
  systemTime.setDate(data).then((value) => {        
      console.log(`systemTime.setDate success data : ` + JSON.stringify(value));    
  }).catch((error) => {        
      console.error(`failed to systemTime.setDate because: ` + JSON.stringify(error));
  });
  ```


## systemTime.getDate<sup>8+</sup>

getDate(callback: AsyncCallback&lt;Date&gt;): void

Obtains the current system date. This API uses an asynchronous callback to return the result.

E
ester.zhou 已提交
331
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
332

E
ester.zhou 已提交
333
**Parameters**
W
wusongqing 已提交
334

E
ester.zhou 已提交
335 336 337 338 339 340 341
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;Date&gt; | Yes| Callback used to return the current system date.|

**Example**

  ```js
W
wusongqing 已提交
342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357
  systemTime.getDate((error, data) => {
      if (error) {
          console.error(`failed to systemTime.getDate because ` + JSON.stringify(error));
          return;
      }
      console.log(`systemTime.getDate success data : ` + JSON.stringify(data));
  });
  ```


## systemTime.getDate<sup>8+</sup>

getDate(): Promise&lt;Date&gt;

Obtains the current system date. This API uses a promise to return the result.

E
ester.zhou 已提交
358
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
359

E
ester.zhou 已提交
360
**Return value**
W
wusongqing 已提交
361

E
ester.zhou 已提交
362 363 364 365 366 367 368
| Type| Description|
| -------- | -------- |
| Promise&lt;Date&gt; | Promise used to return the current system date.|

**Example**

  ```js
W
wusongqing 已提交
369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384
  systemTime.getDate().then((data) => {
      console.log(`systemTime.getDate success data : ` + JSON.stringify(data));
  }).catch((error) => {
      console.error(`failed to systemTime.getDate because ` + JSON.stringify(error));
  });
  ```


## systemTime.setTimezone

setTimezone(timezone: string, callback: AsyncCallback&lt;void&gt;): void

Sets the system time zone. This API uses an asynchronous callback to return the result.

**Required permissions**: ohos.permission.SET_TIME_ZONE

E
ester.zhou 已提交
385
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
386

E
ester.zhou 已提交
387
**Parameters**
W
wusongqing 已提交
388

E
ester.zhou 已提交
389 390 391 392 393 394 395 396
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| timezone | string | Yes| System time zone to set.|
| callback | AsyncCallback&lt;void&gt; | Yes| Callback used to process the received return value.|

**Example**

  ```js
W
wusongqing 已提交
397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414
  systemTime.setTimezone('Asia/Shanghai', (error, data) => {       
      if (error) {          
          console.error('failed to systemTime.setTimezone because ' + JSON.stringify(error));         
          return;       
      }       
      console.info('SystemTimePlugin systemTime.setTimezone success data : ' + JSON.stringify(data)); 
  });
  ```


## systemTime.setTimezone

setTimezone(timezone: string): Promise&lt;void&gt;

Sets the system time zone. This API uses a promise to return the result.

**Required permissions**: ohos.permission.SET_TIME_ZONE

E
ester.zhou 已提交
415
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
416

E
ester.zhou 已提交
417
**Parameters**
W
wusongqing 已提交
418

E
ester.zhou 已提交
419 420 421
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| timezone | string | Yes| System time zone to set.|
W
wusongqing 已提交
422

E
ester.zhou 已提交
423 424 425 426 427 428 429 430 431
**Return value**

| Type| Description|
| -------- | -------- |
| Promise&lt;void&gt; | Promise used to return the result.|

**Example**

  ```js
W
wusongqing 已提交
432 433 434 435 436 437 438 439 440 441 442 443 444 445
  systemTime.setTimezone('Asia/Shanghai').then((data) => {        
      console.log(`systemTime.setTimezone success data : ` + JSON.stringify(data));     
  }).catch((error) => {        
      console.error(`failed to systemTime.setTimezone because: ` + JSON.stringify(error));    
  });
  ```


## systemTime.getTimezone<sup>8+</sup>

getTimezone(callback: AsyncCallback&lt;string&gt;): void

Obtains the system time zone. This API uses an asynchronous callback to return the result.

E
ester.zhou 已提交
446
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
447

E
ester.zhou 已提交
448
**Parameters**
W
wusongqing 已提交
449

E
ester.zhou 已提交
450 451 452 453 454 455 456
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback&lt;string&gt; | Yes| Callback used to return the system time zone.|

**Example**

  ```js
W
wusongqing 已提交
457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472
  systemTime.getTimezone((error, data) => {
      if (error) {
          console.error(`failed to systemTime.getTimezone because ` + JSON.stringify(error));
          return;
      }
      console.log(`systemTime.getTimezone success data : ` + JSON.stringify(data));
  });
  ```


## systemTime.getTimezone<sup>8+</sup>

getTimezone(): Promise&lt;string&gt;

Obtains the system time zone. This API uses a promise to return the result.

E
ester.zhou 已提交
473
**System capability**: SystemCapability.MiscServices.Time
W
wusongqing 已提交
474

E
ester.zhou 已提交
475
**Return value**
W
wusongqing 已提交
476

E
ester.zhou 已提交
477 478 479 480 481 482 483
| Type| Description|
| -------- | -------- |
| Promise&lt;string&gt; | Promise used to return the system time zone.|

**Example**

  ```js
W
wusongqing 已提交
484 485 486 487 488 489
  systemTime.getTimezone().then((data) => {
      console.log(`systemTime.getTimezone success data : ` + JSON.stringify(data));
  }).catch((error) => {
      console.error(`failed to systemTime.getTimezone because ` + JSON.stringify(error));
  });
  ```