1# @ohos.systemTime (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 APIs of this module are deprecated since API version 9. You are advised to use the APIs of the [@ohos.systemDateTime (System Time and Time Zone)](js-apis-system-date-time-sys.md) module. 8> - 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. 9 10## Modules to Import 11 12```ts 13import systemTime from '@ohos.systemTime'; 14``` 15 16## systemTime.setTime 17 18setTime(time : number, callback : AsyncCallback<void>) : void 19 20Sets the system time. This API uses an asynchronous callback to return the result. 21 22**Required permissions**: ohos.permission.SET_TIME 23 24**System capability**: SystemCapability.MiscServices.Time 25 26**Parameters** 27 28| Name | Type | Mandatory| Description | 29| -------- | ----------- | ---- | ---------------- | 30| time | number | Yes | Timestamp to set, in milliseconds. | 31| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 32 33**Error codes** 34 35For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md). 36 37| ID| Error Message | 38| -------- | ------------------------------------------------------------ | 39| -1 | The parameter check failed or permission denied or system error. | 40 41**Example** 42 43```ts 44import { BusinessError } from '@ohos.base'; 45 46// Set the system time to 2021-01-20 02:36:25. 47let time = 1611081385000; 48try { 49 systemTime.setTime(time, (error: BusinessError) => { 50 if (error) { 51 console.info(`Failed to setting time. message: ${error.message}, code: ${error.code}`); 52 return; 53 } 54 console.info(`Succeeded in setting time`); 55 }); 56} catch(e) { 57 let error = e as BusinessError; 58 console.info(`Failed to set time. message: ${error.message}, code: ${error.code}`); 59} 60``` 61 62## systemTime.setTime 63 64setTime(time : number) : Promise<void> 65 66Sets the system time. This API uses a promise to return the result. 67 68**Required permissions**: ohos.permission.SET_TIME 69 70**System capability**: SystemCapability.MiscServices.Time 71 72**Parameters** 73 74| Name| Type | Mandatory| Description | 75| ------ | ------ | ---- | ------------------ | 76| time | number | Yes | Timestamp to set, in milliseconds.| 77 78**Return value** 79 80| Type | Description | 81| ------------------- | ------------------------- | 82| Promise<void> | Promise that returns no value.| 83 84**Error codes** 85 86For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md). 87 88| ID| Error Message | 89| -------- | ------------------------------------------------------------ | 90| -1 | The parameter check failed or permission denied or system error. | 91 92**Example** 93 94```ts 95import { BusinessError } from '@ohos.base'; 96 97// Set the system time to 2021-01-20 02:36:25. 98let time = 1611081385000; 99try { 100 systemTime.setTime(time).then(() => { 101 console.info(`Succeeded in setting time.`); 102 }).catch((error: BusinessError) => { 103 console.info(`Failed to setting time. message: ${error.message}, code: ${error.code}`); 104 }); 105} catch(e) { 106 let error = e as BusinessError; 107 console.info(`Failed to set time. message: ${error.message}, code: ${error.code}`); 108} 109``` 110 111## systemTime.setDate 112 113setDate(date: Date, callback: AsyncCallback<void>): void 114 115Sets the system date. This API uses an asynchronous callback to return the result. 116 117**Required permissions**: ohos.permission.SET_TIME 118 119**System capability**: SystemCapability.MiscServices.Time 120 121**Parameters** 122 123| Name | Type | Mandatory| Description | 124| -------- | ------------- | ---- | --------------------- | 125| date | Date | Yes | Target date to set. | 126| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 127 128**Error codes** 129 130For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md). 131 132| ID| Error Message | 133| -------- | ------------------------------------------------------------ | 134| -1 | The parameter check failed or permission denied or system error. | 135 136**Example** 137 138```ts 139import { BusinessError } from '@ohos.base'; 140 141let date = new Date(); 142try { 143 systemTime.setDate(date, (error: BusinessError) => { 144 if (error) { 145 console.info(`Failed to setting date. message: ${error.message}, code: ${error.code}`); 146 return; 147 } 148 console.info(`Succeeded in setting date.`); 149 }); 150} catch(e) { 151 let error = e as BusinessError; 152 console.info(`Failed to set date. message: ${error.message}, code: ${error.code}`); 153} 154``` 155 156## systemTime.setDate 157 158setDate(date: Date): Promise<void> 159 160Sets the system date. This API uses a promise to return the result. 161 162**Required permissions**: ohos.permission.SET_TIME 163 164**System capability**: SystemCapability.MiscServices.Time 165 166**Parameters** 167 168| Name| Type| Mandatory| Description | 169| ------ | ---- | ---- | ---------- | 170| date | Date | Yes | Target date to set.| 171 172**Return value** 173 174| Type | Description | 175| ------------------- | -------------------- | 176| Promise<void> | Promise that returns no value.| 177 178**Error codes** 179 180For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md). 181 182| ID| Error Message | 183| -------- | ------------------------------------------------------------ | 184| -1 | The parameter check failed or permission denied or system error. | 185 186**Example** 187 188```ts 189import { BusinessError } from '@ohos.base'; 190 191let date = new Date(); 192try { 193 systemTime.setDate(date).then(() => { 194 console.info(`Succeeded in setting date.`); 195 }).catch((error: BusinessError) => { 196 console.info(`Failed to setting date. message: ${error.message}, code: ${error.code}`); 197 }); 198} catch(e) { 199 let error = e as BusinessError; 200 console.info(`Failed to set date. message: ${error.message}, code: ${error.code}`); 201} 202``` 203 204## systemTime.setTimezone 205 206setTimezone(timezone: string, callback: AsyncCallback<void>): void 207 208Sets the system time zone. This API uses an asynchronous callback to return the result. 209 210**Required permissions**: ohos.permission.SET_TIME_ZONE 211 212**System capability**: SystemCapability.MiscServices.Time 213 214**Parameters** 215 216| Name | Type | Mandatory| Description | 217| -------- | ------------- | ---- | -------------------------- | 218| timezone | string | Yes | System time zone to set. For details, see [Supported System Time Zones](#supported-system-time-zones). | 219| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 220 221**Error codes** 222 223For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md). 224 225| ID| Error Message | 226| -------- | ------------------------------------------------------------ | 227| -1 | The parameter check failed or permission denied or system error. | 228 229**Example** 230 231```ts 232import { BusinessError } from '@ohos.base'; 233 234try { 235 systemTime.setTimezone('Asia/Shanghai', (error: BusinessError) => { 236 if (error) { 237 console.info(`Failed to setting timezone. message: ${error.message}, code: ${error.code}`); 238 return; 239 } 240 console.info(`Succeeded in setting timezone.`); 241 }); 242} catch(e) { 243 let error = e as BusinessError; 244 console.info(`Failed to set timezone. message: ${error.message}, code: ${error.code}`); 245} 246``` 247 248## systemTime.setTimezon 249 250setTimezone(timezone: string): Promise<void> 251 252Sets the system time zone. This API uses a promise to return the result. 253 254**Required permissions**: ohos.permission.SET_TIME_ZONE 255 256**System capability**: SystemCapability.MiscServices.Time 257 258**Parameters** 259 260| Name | Type | Mandatory| Description | 261| -------- | ------ | ---- | ---------- | 262| timezone | string | Yes | System time zone to set. For details, see [Supported System Time Zones](#supported-system-time-zones).| 263 264**Return value** 265 266| Type | Description | 267| ------------------- | -------------------- | 268| Promise<void> | Promise that returns no value.| 269 270**Error codes** 271 272For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md). 273 274| ID| Error Message | 275| -------- | ------------------------------------------------------------ | 276| -1 | The parameter check failed or permission denied or system error. | 277 278**Example** 279 280```ts 281import { BusinessError } from '@ohos.base'; 282 283try { 284 systemTime.setTimezone('Asia/Shanghai').then(() => { 285 console.info(`Succeeded in setting timezone.`); 286 }).catch((error: BusinessError) => { 287 console.info(`Failed to setting timezone. message: ${error.message}, code: ${error.code}`); 288 }); 289} catch(e) { 290 let error = e as BusinessError; 291 console.info(`Failed to set timezone. message: ${error.message}, code: ${error.code}`); 292} 293``` 294 295## Supported System Time Zones 296 297The following table lists the supported system time zones and the respective offset (unit: h) between each time zone and time zone 0. 298 299| Time Zone | Offset | 300| ------------------------------ | --------------------- | 301| Antarctica/McMurdo | 12 | 302| America/Argentina/Buenos_Aires | -3 | 303| Australia/Sydney | 10 | 304| America/Noronha | -2 | 305| America/St_Johns | -3 | 306| Africa/Kinshasa | 1 | 307| America/Santiago | -3 | 308| Asia/Shanghai | 8 | 309| Asia/Nicosia | 3 | 310| Europe/Berlin | 2 | 311| America/Guayaquil | -5 | 312| Europe/Madrid | 2 | 313| Pacific/Pohnpei | 11 | 314| America/Godthab | -2 | 315| Asia/Jakarta | 7 | 316| Pacific/Tarawa | 12 | 317| Asia/Almaty | 6 | 318| Pacific/Majuro | 12 | 319| Asia/Ulaanbaatar | 8 | 320| America/Mexico_City | -5 | 321| Asia/Kuala_Lumpur | 8 | 322| Pacific/Auckland | 12 | 323| Pacific/Tahiti | -10 | 324| Pacific/Port_Moresby | 10 | 325| Asia/Gaza | 3 | 326| Europe/Lisbon | 1 | 327| Europe/Moscow | 3 | 328| Europe/Kiev | 3 | 329| Pacific/Wake | 12 | 330| America/New_York | -4 | 331| Asia/Tashkent | 5 | 332