1# @ohos.systemDateTime (系统时间、时区)(系统接口) 2<!--Kit: Basic Services Kit--> 3<!--Subsystem: Time--> 4<!--Owner: @huaxin05--> 5<!--Designer: @hu-kai45--> 6<!--Tester: @murphy1984--> 7<!--Adviser: @zhang_yixin13--> 8 9本模块主要由系统时间和系统时区功能组成。开发者可以设置、获取系统时间及系统时区。 10 11> **说明：** 12> 13> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15## 导入模块 16 17```ts 18import { systemDateTime } from '@kit.BasicServicesKit'; 19``` 20 21## TimeType<sup>10+</sup> 22 23定义获取时间的枚举类型。 24 25**系统能力**: SystemCapability.MiscServices.Time 26 27| 名称 | 值 | 说明 | 28| ------- | ---- | ------------------------------------------------ | 29| STARTUP | 0 | 自系统启动以来经过的毫秒数，包括深度睡眠时间。 | 30| ACTIVE | 1 | 自系统启动以来经过的毫秒数，不包括深度睡眠时间。 | 31 32## systemDateTime.setTime 33 34setTime(time : number, callback : AsyncCallback<void>) : void 35 36设置系统时间，使用callback异步回调。 37 38**系统接口：** 此接口为系统接口。 39 40**系统能力：** SystemCapability.MiscServices.Time 41 42**需要权限：** ohos.permission.SET_TIME 43 44**参数：** 45 46| 参数名 | 类型 | 必填 | 说明 | 47| -------- | ----------- | ---- | ---------------- | 48| time | number | 是 | 目标时间戳(ms)。 | 49| callback | AsyncCallback<void> | 是 | 回调函数。 | 50 51**错误码：** 52 53以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 54 55| 错误码ID | 错误信息 | 56| -------- |-------------------------------------------------------------------------------------------------------------| 57| 201 | Permission denied. | 58| 202 | Permission verification failed. A non-system application calls a system API. | 59| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 60 61**示例：** 62 63```ts 64import { BusinessError } from '@kit.BasicServicesKit'; 65 66// time对应的时间为2021-01-20 02:36:25。 67let time = 1611081385000; 68try { 69 systemDateTime.setTime(time, (error: BusinessError) => { 70 if (error) { 71 console.info(`Failed to set time. message: ${error.message}, code: ${error.code}`); 72 return; 73 } 74 console.info(`Succeeded in setting time`); 75 }); 76} catch(e) { 77 let error = e as BusinessError; 78 console.info(`Failed to set time. message: ${error.message}, code: ${error.code}`); 79} 80``` 81 82## systemDateTime.setTime 83 84setTime(time : number) : Promise<void> 85 86设置系统时间，使用Promise异步回调。 87 88**系统接口：** 此接口为系统接口。 89 90**系统能力：** SystemCapability.MiscServices.Time 91 92**需要权限：** ohos.permission.SET_TIME 93 94**参数：** 95 96| 参数名 | 类型 | 必填 | 说明 | 97| ------ | ------ | ---- | ------------------ | 98| time | number | 是 | 目标时间戳(ms)。 | 99 100**返回值：** 101 102| 类型 | 说明 | 103| ------------------- | ------------------------- | 104| Promise<void> | 无返回结果的Promise对象。 | 105 106**错误码：** 107 108以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 109 110| 错误码ID | 错误信息 | 111| -------- |-------------------------------------------------------------------------------------------------------------| 112| 201 | Permission denied. | 113| 202 | Permission verification failed. A non-system application calls a system API. | 114| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 115 116**示例：** 117 118```ts 119import { BusinessError } from '@kit.BasicServicesKit'; 120 121// time对应的时间为2021-01-20 02:36:25。 122let time = 1611081385000; 123try { 124 systemDateTime.setTime(time).then(() => { 125 console.info(`Succeeded in setting time.`); 126 }).catch((error: BusinessError) => { 127 console.info(`Failed to set time. message: ${error.message}, code: ${error.code}`); 128 }); 129} catch(e) { 130 let error = e as BusinessError; 131 console.info(`Failed to set time. message: ${error.message}, code: ${error.code}`); 132} 133``` 134 135## systemDateTime.setDate<sup>(deprecated)</sup> 136 137setDate(date: Date, callback: AsyncCallback<void>): void 138 139设置系统日期，使用callback异步回调。 140 141> **说明：** 142> 143> 从API version 9开始支持，从API 10开始废弃，建议使用[systemDateTime.setTime](#systemdatetimesettime)替代。 144 145**系统接口：** 此接口为系统接口。 146 147**系统能力：** SystemCapability.MiscServices.Time 148 149**需要权限：** ohos.permission.SET_TIME 150 151**参数：** 152 153| 参数名 | 类型 | 必填 | 说明 | 154| -------- | ------------- | ---- |-------------| 155| date | Date | 是 | 目标日期，且必须>0。 | 156| callback | AsyncCallback<void> | 是 | 回调函数。 | 157 158**错误码：** 159 160以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 161 162| 错误码ID | 错误信息 | 163| -------- |----------------------------------------------------------------------------------------------------------------------------------------------| 164| 201 | Permission denied. | 165| 202 | Permission verification failed. A non-system application calls a system API. | 166| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 167 168**示例：** 169 170```ts 171import { BusinessError } from '@kit.BasicServicesKit'; 172 173let date = new Date(); 174try { 175 systemDateTime.setDate(date, (error: BusinessError) => { 176 if (error) { 177 console.info(`Failed to set date. message: ${error.message}, code: ${error.code}`); 178 return; 179 } 180 console.info(`Succeeded in setting date.`); 181 }); 182} catch(e) { 183 let error = e as BusinessError; 184 console.info(`Failed to set date. message: ${error.message}, code: ${error.code}`); 185} 186``` 187 188## systemDateTime.setDate<sup>(deprecated)</sup> 189 190setDate(date: Date): Promise<void> 191 192设置系统日期，使用Promise异步回调。 193 194> **说明：** 195> 196> 从API version 9开始支持，从API 10开始废弃，建议使用[systemDateTime.setTime](#systemdatetimesettime)替代。 197 198**系统接口：** 此接口为系统接口。 199 200**系统能力：** SystemCapability.MiscServices.Time 201 202**需要权限：** ohos.permission.SET_TIME 203 204**参数：** 205 206| 参数名 | 类型 | 必填 | 说明 | 207| ------ | ---- | ---- | ---------- | 208| date | Date | 是 | 目标日期，且必须>0。 | 209 210**返回值：** 211 212| 类型 | 说明 | 213| ------------------- | -------------------- | 214| Promise<void> | 无返回结果的Promise对象。 | 215 216**错误码：** 217 218以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 219 220| 错误码ID | 错误信息 | 221| -------- |----------------------------------------------------------------------------------------------------------------------------------------------| 222| 201 | Permission denied. | 223| 202 | Permission verification failed. A non-system application calls a system API. | 224| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 225 226**示例：** 227 228```ts 229import { BusinessError } from '@kit.BasicServicesKit'; 230 231let date = new Date(); 232try { 233 systemDateTime.setDate(date).then(() => { 234 console.info(`Succeeded in setting date.`); 235 }).catch((error: BusinessError) => { 236 console.info(`Failed to set date. message: ${error.message}, code: ${error.code}`); 237 }); 238} catch(e) { 239 let error = e as BusinessError; 240 console.info(`Failed to set date. message: ${error.message}, code: ${error.code}`); 241} 242``` 243 244## systemDateTime.setTimezone 245 246setTimezone(timezone: string, callback: AsyncCallback<void>): void 247 248设置系统时区，使用callback异步回调。 249 250**系统接口：** 此接口为系统接口。 251 252**系统能力：** SystemCapability.MiscServices.Time 253 254**需要权限：** ohos.permission.SET_TIME_ZONE 255 256**参数：** 257 258| 参数名 | 类型 | 必填 | 说明 | 259| -------- | ------------- | ---- | -------------------------- | 260| timezone | string | 是 | 系统时区。 具体可见[支持的系统时区](#支持的系统时区) 。 | 261| callback | AsyncCallback<void> | 是 | 回调函数。 | 262 263**错误码：** 264 265以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 266 267| 错误码ID | 错误信息 | 268| -------- |-------------------------------------------------------------------------------------------------------------| 269| 201 | Permission denied. | 270| 202 | Permission verification failed. A non-system application calls a system API. | 271| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 272 273**示例：** 274 275```ts 276import { BusinessError } from '@kit.BasicServicesKit'; 277 278try { 279 systemDateTime.setTimezone('Asia/Shanghai', (error: BusinessError) => { 280 if (error) { 281 console.info(`Failed to set timezone. message: ${error.message}, code: ${error.code}`); 282 return; 283 } 284 console.info(`Succeeded in setting timezone.`); 285 }); 286} catch(e) { 287 let error = e as BusinessError; 288 console.info(`Failed to set timezone. message: ${error.message}, code: ${error.code}`); 289} 290``` 291 292## systemDateTime.setTimezone 293 294setTimezone(timezone: string): Promise<void> 295 296设置系统时区，使用Promise异步回调。 297 298**系统接口：** 此接口为系统接口。 299 300**系统能力：** SystemCapability.MiscServices.Time 301 302**需要权限：** ohos.permission.SET_TIME_ZONE 303 304**参数：** 305 306| 参数名 | 类型 | 必填 | 说明 | 307| -------- | ------ | ---- | ---------- | 308| timezone | string | 是 | 系统时区。具体可见[支持的系统时区](#支持的系统时区) 。 | 309 310**返回值：** 311 312| 类型 | 说明 | 313| ------------------- | -------------------- | 314| Promise<void> | 无返回结果的Promise对象。 | 315 316**错误码：** 317 318以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 319 320| 错误码ID | 错误信息 | 321| -------- |-------------------------------------------------------------------------------------------------------------| 322| 201 | Permission denied. | 323| 202 | Permission verification failed. A non-system application calls a system API. | 324| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 325 326**示例：** 327 328```ts 329import { BusinessError } from '@kit.BasicServicesKit'; 330 331try { 332 systemDateTime.setTimezone('Asia/Shanghai').then(() => { 333 console.info(`Succeeded in setting timezone.`); 334 }).catch((error: BusinessError) => { 335 console.info(`Failed to set timezone. message: ${error.message}, code: ${error.code}`); 336 }); 337} catch(e) { 338 let error = e as BusinessError; 339 console.info(`Failed to set timezone. message: ${error.message}, code: ${error.code}`); 340} 341``` 342 343## systemDateTime.updateNtpTime<sup>14+</sup> 344 345updateNtpTime(): Promise<void> 346 347使用异步方式从NTP服务器更新NTP时间。该方法一小时内只会从NTP服务器更新一次NTP时间。 348 349**系统接口：** 此接口为系统接口。 350 351**系统能力：** SystemCapability.MiscServices.Time 352 353**返回值：** 354 355| 类型 | 说明 | 356| ------------------- | -------------------- | 357| Promise<void> | 无返回结果的Promise对象。 | 358 359**错误码：** 360 361以下错误码的详细介绍请参见[时间时区错误码](./errorcode-time.md)和[通用错误码说明文档](../errorcode-universal.md)。 362 363| 错误码ID | 错误信息 | 364|-------|-------------------------------------------------------------------------------------------------------------| 365| 13000001 | Network connection error or OS error. | 366| 202 | Permission verification failed. A non-system application calls a system API. | 367 368**示例：** 369 370```ts 371import { BusinessError } from '@kit.BasicServicesKit'; 372 373try { 374 systemDateTime.updateNtpTime().then(() => { 375 console.info(`Succeeded in update ntp time.`); 376 }).catch((error: BusinessError) => { 377 console.error(`Failed to update ntp time. message: ${error.message}, code: ${error.code}`); 378 }); 379} catch(e) { 380 let error = e as BusinessError; 381 console.error(`Failed to update ntp time. message: ${error.message}, code: ${error.code}`); 382} 383``` 384 385## systemDateTime.getNtpTime<sup>14+</sup> 386 387getNtpTime(): number 388 389使用同步方式获取基于上次更新的NTP时间所计算出的真实时间。 390 391**系统接口：** 此接口为系统接口。 392 393**系统能力：** SystemCapability.MiscServices.Time 394 395**返回值**： 396 397| 类型 | 说明 | 398| ------ |--------------------------------| 399| number | 基于上次更新的NTP时间所计算出的Unix纪元时间(ms)。 | 400 401**错误码：** 402 403以下错误码的详细介绍请参见[时间时区错误码](./errorcode-time.md)和[通用错误码说明文档](../errorcode-universal.md)。 404 405| 错误码ID | 错误信息 | 406|-------|-------------------------------------------------------------------------------------------------------------| 407| 13000002 | Location NTP time of the system is invalid. | 408| 202 | Permission verification failed. A non-system application calls a system API. | 409 410**示例：** 411 412```ts 413import { BusinessError } from '@kit.BasicServicesKit'; 414 415try { 416 let time = systemDateTime.getNtpTime(); 417} catch(e) { 418 let error = e as BusinessError; 419 console.error(`Failed to get ntp time. message: ${error.message}, code: ${error.code}`); 420} 421``` 422 423## 支持的系统时区 424 425支持的系统时区参考接口[I18n.SystemLocaleManager.getTimeZoneCityItemArray()](../apis-localization-kit/js-apis-i18n-sys.md#gettimezonecityitemarray10)。 426