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