1# 升级 2 3升级范围：升级整个系统，包括内置的资源、预置应用；第三方的应用不在升级的范围。 4 5升级依赖：升级分为SD卡升级和在线升级两种。 6 7- SD卡升级依赖升级包和SD卡安装。 8- 在线升级依赖设备厂商部署的用于管理升级包的服务器。服务器由设备厂商部署，IP由调用者传入，请求的request接口是固定的，由设备厂商开发。 9 10> **说明：** 11> 12> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 13> 14> 本模块接口为系统接口。 15 16## 导入模块 17 18```js 19import update from '@ohos.update' 20``` 21 22## 权限列表 23 24无 25 26## update.getUpdater 27 28getUpdater(upgradeFile: string, updateType?: UpdateTypes): Updater 29 30获取本地升级Updater。 31 32**系统能力**：SystemCapability.Update.UpdateService 33 34**参数：** 35 36| 参数名 | 类型 | 必填 | 说明 | 37| ----------- | --------------------------- | ---- | ---- | 38| upgradeFile | string | 是 | 升级文件 | 39| updateType | [UpdateTypes](#updatetypes) | 是 | 升级类型 | 40 41**返回值：** 42 43| 类型 | 说明 | 44| ------------------- | ---- | 45| [Updater](#updater) | 升级对象 | 46 47**示例：** 48 49```js 50try { 51 let updater = update.getUpdater('/data/updater/updater.zip', 'OTA'); 52} catch(error) { 53 console.error(" Fail to get updater error: " + error); 54} 55``` 56 57## update.getUpdaterForOther 58 59getUpdaterForOther(upgradeFile: string, device: string, updateType?: UpdateTypes): Updater 60 61获取升级对象给待升级设备。 62 63**系统能力**：SystemCapability.Update.UpdateService 64 65**参数：** 66 67| 参数名 | 类型 | 必填 | 说明 | 68| ----------- | --------------------------- | ---- | ----- | 69| upgradeFile | string | 是 | 升级文件 | 70| device | string | 是 | 待升级设备 | 71| updateType | [UpdateTypes](#updatetypes) | 是 | 升级类型 | 72 73**返回值：** 74 75| 类型 | 说明 | 76| ------------------- | ---- | 77| [Updater](#updater) | 升级对象 | 78 79**示例：** 80 81```js 82try { 83 let updater = update.getUpdaterForOther('/data/updater/updater.zip', '1234567890', 'OTA'); 84} catch(error) { 85 console.error(" Fail to get updater error: " + error); 86} 87``` 88 89## update.getUpdaterFromOther 90 91getUpdaterFromOther(upgradeFile: string, device: string, updateType?: UpdateTypes): Updater 92 93获取其它设备为本设备升级的Updater。 94 95**系统能力**：SystemCapability.Update.UpdateService 96 97**参数：** 98 99| 参数名 | 类型 | 必填 | 说明 | 100| ----------- | --------------------------- | ---- | ----- | 101| upgradeFile | string | 是 | 升级文件 | 102| device | string | 是 | 待升级设备 | 103| updateType | [UpdateTypes](#updatetypes) | 是 | 升级类型 | 104 105**返回值：** 106 107| 类型 | 说明 | 108| ------------------- | ---- | 109| [Updater](#updater) | 升级对象 | 110 111**示例：** 112 113```js 114try { 115 let updater = update.getUpdaterFromOther('/data/updater/updater.zip', '1234567890', 'OTA'); 116} catch(error) { 117 console.error(" Fail to get updater error: " + error); 118} 119``` 120 121## Updater 122 123### getNewVersionInfo 124 125getNewVersionInfo(callback: AsyncCallback\<NewVersionInfo>): void 126 127获取新版本信息，使用callback方式作为异步方法。 128 129**系统能力**：SystemCapability.Update.UpdateService 130 131**参数：** 132 133| 参数名 | 类型 | 必填 | 说明 | 134| -------- | ---------------------------------------- | ---- | --------- | 135| callback | AsyncCallback<[NewVersionInfo](#newversioninfo)> | 否 | 回调返回新版本信息 | 136 137**示例：** 138 139```js 140updater.getNewVersionInfo((err, info) => { 141 console.log("getNewVersionInfo success " + info.status); 142 console.log(`info versionName = ` + info.checkResults[0].versionName); 143 console.log(`info versionCode = ` + info.checkResults[0].versionCode); 144 console.log(`info verifyInfo = ` + info.checkResults[0].verifyInfo); 145}); 146``` 147 148### getNewVersionInfo 149 150getNewVersionInfo(): Promise\<NewVersionInfo> 151 152获取新版本信息，使用promise方式作为异步方法。 153 154**系统能力**：SystemCapability.Update.UpdateService 155 156**返回值：** 157 158| 类型 | 说明 | 159| ---------------------------------------- | ---------------- | 160| Promise\<[NewVersionInfo](#newversioninfo)> | Promise，用于异步获取结果 | 161 162**示例：** 163 164```js 165updater.getNewVersionInfo().then(value => { 166 console.log(`info versionName = ` + value.checkResults[0].versionName); 167 console.log(`info versionCode = ` + value.checkResults[0].versionCode); 168 console.log(`info verifyInfo = ` + value.checkResults[0].verifyInfo); 169}).catch(err => { 170 console.log("getNewVersionInfo promise error: " + err.code); 171}); 172``` 173 174### checkNewVersion 175 176checkNewVersion(callback: AsyncCallback\<NewVersionInfo>): void 177 178检查新版本，使用callback方式作为异步方法。 179 180**系统能力**：SystemCapability.Update.UpdateService 181 182**参数：** 183 184| 参数名 | 类型 | 必填 | 说明 | 185| -------- | ---------------------------------------- | ---- | --------- | 186| callback | AsyncCallback\<[NewVersionInfo](#newversioninfo)> | 否 | 回调返回新版本信息 | 187 188**示例：** 189 190```js 191updater.checkNewVersion((err, info) => { 192 console.log("checkNewVersion success " + info.status); 193 console.log(`info versionName = ` + info.checkResults[0].versionName); 194 console.log(`info versionCode = ` + info.checkResults[0].versionCode); 195 console.log(`info verifyInfo = ` + info.checkResults[0].verifyInfo); 196}); 197``` 198 199### checkNewVersion 200 201checkNewVersion(): Promise\<NewVersionInfo> 202 203检查新版本，使用promise方式作为异步方法。 204 205**系统能力**：SystemCapability.Update.UpdateService 206 207**返回值:** 208 209| 类型 | 说明 | 210| ---------------------------------------- | ---------------- | 211| Promise\<[NewVersionInfo](#newversioninfo)> | Promise函数返回新版本信息 | 212 213**示例:** 214 215```js 216updater.checkNewVersion().then(value => { 217 console.log(`info versionName = ` + value.checkResults[0].versionName); 218 console.log(`info versionCode = ` + value.checkResults[0].versionCode); 219 console.log(`info verifyInfo = ` + value.checkResults[0].verifyInfo); 220}).catch(err => { 221 console.log("checkNewVersion promise error: " + err.code); 222}); 223``` 224 225### verifyUpdatePackage 226 227verifyUpdatePackage(upgradeFile: string, certsFile: string): void 228 229升级前检查升级包是否有效。 230 231**系统能力**：SystemCapability.Update.UpdateService 232 233**参数：** 234 235| 参数名 | 类型 | 必填 | 说明 | 236| ----------- | ------ | ---- | --------- | 237| upgradeFile | string | 是 | 待校验的升级包路径 | 238| certsFile | string | 是 | 证书路径 | 239 240**示例：** 241 242```js 243updater.on("verifyProgress", callback => { 244 console.info('on verifyProgress ' + callback.percent); 245}); 246update.verifyUpdatePackage("XXX", "XXX"); 247``` 248 249### rebootAndCleanUserData<sup>8+</sup> 250 251rebootAndCleanUserData(): Promise\<number> 252 253重启设备并清除用户分区数据。 254 255**系统能力**：SystemCapability.Update.UpdateService 256 257**返回值：** 258 259| 类型 | 说明 | 260| ---------------- | ------------------- | 261| Promise\<number> | Promise示例，用于异步获取结果。 | 262 263**示例：** 264 265```js 266updater.rebootAndCleanUserData().then(result => { 267 console.log("rebootAndCleanUserData " + result); 268}).catch(err => { 269 console.info("rebootAndCleanUserData promise error: " + err.code); 270}); 271``` 272 273### rebootAndCleanUserData<sup>8+</sup> 274 275rebootAndCleanUserData(callback: AsyncCallback\<number>): void 276 277重启设备并清除用户分区数据。 278 279**系统能力**：SystemCapability.Update.UpdateService 280 281**参数：** 282 283| 参数名 | 类型 | 必填 | 说明 | 284| -------- | -------- | ---- | ---------------------- | 285| callback | Function | 是 | AsyncCallback\<number> | 286 287**示例：** 288 289```js 290updater.rebootAndCleanUserData((err, result) => { 291 console.log("rebootAndCleanUserData ", result) 292}); 293``` 294 295### applyNewVersion 296 297applyNewVersion(): Promise\<number> 298 299重启设备后安装升级包。 300 301**系统能力**：SystemCapability.Update.UpdateService 302 303**返回值：** 304 305| 类型 | 说明 | 306| ---------------- | ------------------- | 307| Promise\<number> | Promise示例，用于异步获取结果。 | 308 309**示例：** 310 311```js 312updater.applyNewVersion().then(result => { 313 console.log("appVewVersion ", result) 314}).catch(err => { 315 console.info("applyNewVersion promise error: " + err.code); 316}); 317``` 318 319### applyNewVersion 320 321applyNewVersion(callback: AsyncCallback\<number>): void 322 323重启设备后安装升级包。 324 325**系统能力**：SystemCapability.Update.UpdateService 326 327**参数：** 328 329| 参数名 | 类型 | 必填 | 说明 | 330| -------- | -------- | ---- | ---------------------- | 331| callback | Function | 是 | AsyncCallback\<number> | 332 333**示例：** 334 335```js 336updater.applyNewVersion((err, result) => { 337 console.log("applyNewVersion ", result) 338}); 339``` 340 341### download 342 343download(): void 344 345下载新版本，并监听下载进程。 346 347**系统能力**：SystemCapability.Update.UpdateService 348 349**示例：** 350 351```js 352updater.on("downloadProgress", progress => { 353 console.log("downloadProgress on" + progress); 354 console.log(`downloadProgress status: ` + progress.status); 355 console.log(`downloadProgress percent: ` + progress.percent); 356}); 357updater.download(); 358``` 359 360### upgrade 361 362upgrade():void 363 364启动升级。 365 366**系统能力**：SystemCapability.Update.UpdateService 367 368**示例：** 369 370```js 371updater.on("upgradeProgress", progress => { 372 console.log("upgradeProgress on" + progress); 373 console.log(`upgradeProgress status: ` + progress.status); 374 console.log(`upgradeProgress percent: ` + progress.percent); 375}); 376updater.upgrade(); 377``` 378 379### setUpdatePolicy 380 381setUpdatePolicy(policy: UpdatePolicy, callback: AsyncCallback\<number>): void 382 383设置升级策略，使用callback方式作为异步方法。 384 385**系统能力**：SystemCapability.Update.UpdateService 386 387**参数：** 388 389| 参数名 | 类型 | 必填 | 说明 | 390| -------- | ----------------------------- | ---- | ------ | 391| policy | [UpdatePolicy](#updatepolicy) | 是 | 设置升级策略 | 392| callback | AsyncCallback\<number> | 是 | 回调返回结果 | 393 394**示例：** 395 396```js 397// 设置策略 398let policy = { 399 autoDownload: false, 400 autoDownloadNet: true, 401 mode: 2, 402 autoUpgradeInterval: [ 2, 3 ], 403 autoUpgradeCondition: 2 404} 405updater.setUpdatePolicy(policy, (err, result) => { 406 console.log("setUpdatePolicy ", result) 407}); 408``` 409 410### setUpdatePolicy 411 412setUpdatePolicy(policy: UpdatePolicy): Promise\<number> 413 414设置升级策略，使用promise方式作为异步方法。 415 416**系统能力**：SystemCapability.Update.UpdateService 417 418**参数：** 419 420| 参数名 | 类型 | 必填 | 说明 | 421| ------ | ----------------------------- | ---- | ------ | 422| policy | [UpdatePolicy](#updatepolicy) | 是 | 设置升级策略 | 423 424**返回值：** 425 426| 类型 | 说明 | 427| ---------------- | --------------- | 428| Promise\<number> | Promise函数返回设置结果 | 429 430**示例：** 431 432```js 433let policy = { 434 autoDownload: false, 435 autoDownloadNet: true, 436 mode: 2, 437 autoUpgradeInterval: [ 2, 3 ], 438 autoUpgradeCondition: 2 439} 440updater.setUpdatePolicy(policy).then(result => 441 console.log("setUpdatePolicy ", result) 442).catch(err => { 443 console.log("setUpdatePolicy promise error: " + err.code); 444}); 445``` 446 447### getUpdatePolicy 448 449getUpdatePolicy(callback: AsyncCallback\<UpdatePolicy>): void 450 451获取升级策略信息，使用callback方式作为异步方法。 452 453**系统能力**：SystemCapability.Update.UpdateService 454 455**参数：** 456 457| 参数名 | 类型 | 必填 | 说明 | 458| -------- | ---------------------------------------- | ---- | ---------- | 459| callback | AsyncCallback\<[UpdatePolicy](#updatepolicy)> | 否 | 回调返回升级策略信息 | 460 461**示例：** 462 463```js 464updater.getUpdatePolicy((err, policy) => { 465 console.log("getUpdatePolicy success"); 466 console.log(`policy autoDownload = ` + policy.autoDownload); 467 console.log(`policy autoDownloadNet = ` + policy.autoDownloadNet); 468 console.log(`policy mode = ` + policy.mode); 469}); 470``` 471 472### getUpdatePolicy 473 474getUpdatePolicy(): Promise\<UpdatePolicy> 475 476获取升级策略，通过promise方式作为异步方法。 477 478**系统能力**：SystemCapability.Update.UpdateService 479 480**返回值：** 481 482| 类型 | 说明 | 483| --------------------------------------- | ----------------- | 484| Promise\<[UpdatePolicy](#updatepolicy)> | Promise函数返回升级策略信息 | 485 486**示例：** 487 488```js 489updater.getUpdatePolicy().then(value => { 490 console.log(`info autoDownload = ` + value.autoDownload); 491 console.log(`info autoDownloadNet = ` + value.autoDownloadNet); 492 console.log(`info mode = ` + value.mode); 493}).catch(err => { 494 console.log("getUpdatePolicy promise error: " + err.code); 495}); 496``` 497 498## UpdateTypes 499 500升级类型。 501 502**系统能力**：SystemCapability.Update.UpdateService 503 504| 参数名 | 说明 | 505| ----- | ----- | 506| OTA | OTA升级 | 507| patch | 补丁升级 | 508 509## PackageTypes 510 511升级包类型。 512 513**系统能力**：SystemCapability.Update.UpdateService 514 515| 参数名 | 默认值 | 说明 | 516| -------------------- | ---- | ------- | 517| PACKAGE_TYPE_NORMAL | 1 | 通用升级包 | 518| PACKAGE_TYPE_BASE | 2 | 基础升级包 | 519| PACKAGE_TYPE_CUST | 3 | 定制升级包 | 520| PACKAGE_TYPE_PRELOAD | 4 | 预装升级包 | 521| PACKAGE_TYPE_COTA | 5 | 参数配置升级包 | 522| PACKAGE_TYPE_VERSION | 6 | 版本升级包 | 523| PACKAGE_TYPE_PATCH | 7 | 补丁包 | 524 525## InstallMode 526 527安装模式。 528 529**系统能力**：SystemCapability.Update.UpdateService 530 531| 参数名 | 默认值 | 说明 | 532| ------------------- | ---- | ---- | 533| INSTALL_MODE_NORMAL | 0 | 正常升级 | 534| INSTALL_MODE_NIGHT | 1 | 夜间升级 | 535| INSTALL_MODE_AUTO | 2 | 自动升级 | 536 537## NewVersionStatus 538 539新版本检测状态。 540 541**系统能力**：SystemCapability.Update.UpdateService 542 543| 参数名 | 默认值 | 说明 | 544| ------------------- | ---- | -------- | 545| VERSION_STATUS_ERR | -1 | 检测版本时出错 | 546| VERSION_STATUS_NEW | 0 | 检测到新版本 | 547| VERSION_STATUS_NONE | 1 | 没有检测到新版本 | 548| VERSION_STATUS_BUSY | 2 | 检测版本时忙 | 549 550## UpdatePolicy 551 552升级策略。 553 554**系统能力**：SystemCapability.Update.UpdateService 555 556| 名称 | 参数类型 | 必填 | 说明 | 557| ------------------- | --------------------------- | ---- | ------- | 558| autoDownload | bool | 是 | 自动升级开关 | 559| installMode | [InstallMode](#installmode) | 是 | 安装模式 | 560| autoUpgradeInterval | Array\<number> | 是 | 自动升级时间段 | 561 562## NewVersionInfo 563 564新版本信息。 565 566**系统能力**：SystemCapability.Update.UpdateService 567 568| 名称 | 参数类型 | 必填 | 说明 | 569| --------------- | ---------------------------------------- | ---- | ---- | 570| status | [NewVersionStatus](#newversionstatus) | 是 | 升级状态 | 571| errMsg | string | 是 | 错误信息 | 572| checkResults | Array<[CheckResult](#checkresult)> | 是 | 检测结果 | 573| descriptionInfo | Array\<[DescriptionInfo](#descriptioninfo)> | 是 | 描述信息 | 574 575## CheckResult 576 577检测结果。 578 579**系统能力**：SystemCapability.Update.UpdateService 580 581| 名称 | 参数类型 | 必填 | 说明 | 582| ------------- | ----------------------------- | ---- | ------ | 583| versionName | string | 是 | 版本名称 | 584| versionCode | number | 是 | 版本编码 | 585| size | number | 是 | 版本大小 | 586| verifyInfo | string | 是 | 版本校验信息 | 587| packageType | [PackageTypes](#packagetypes) | 是 | 版本类型 | 588| descriptionId | string | 是 | 版本描述信息 | 589 590## DescriptionInfo 591 592版本描述信息。 593 594**系统能力**：SystemCapability.Update.UpdateService 595 596| 名称 | 参数类型 | 必填 | 说明 | 597| ------------- | ------ | ---- | ------------- | 598| descriptionId | string | 是 | 版本versionId信息 | 599| content | string | 是 | 版本changelog信息 |