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