1# @ohos.request (上传下载) 2 3request部件主要给应用提供上传下载文件、后台传输代理的基础能力。 4 5>  **说明：** 6> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7 8 9## 导入模块 10 11 12```js 13import request from '@ohos.request'; 14``` 15 16## 常量 17 18**需要权限**：ohos.permission.INTERNET 19 20**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。 21 22### 网络类型 23下载支持自定义网络类型，可以在[DownloadConfig](#downloadconfig)中通过networkType配置成以下网络类型。 24 25| 名称 | 参数类型 | 数值 | 说明 | 26| -------- | -------- | -------- | -------- | 27| NETWORK_MOBILE | number | 0x00000001 | 使用蜂窝网络时允许下载的位标志。 | 28| NETWORK_WIFI | number | 0x00010000 | 使用WLAN时允许下载的位标志。 | 29 30### 下载任务的错误码 31下载[on('fail')<sup>7+</sup>](#onfail7)事件callback的错误参数、[getTaskInfo<sup>9+</sup>](#gettaskinfo9)返回值的failedReason字段取值。 32 33| 名称 | 参数类型 | 数值 | 说明 | 34| -------- | -------- | -------- | -------- | 35| ERROR_CANNOT_RESUME<sup>7+</sup> | number | 0 | 网络原因导致恢复下载失败。 | 36| ERROR_DEVICE_NOT_FOUND<sup>7+</sup> | number | 1 | 找不到SD卡等存储设备。 | 37| ERROR_FILE_ALREADY_EXISTS<sup>7+</sup> | number | 2 | 要下载的文件已存在，下载会话不能覆盖现有文件。 | 38| ERROR_FILE_ERROR<sup>7+</sup> | number | 3 | 文件操作失败。 | 39| ERROR_HTTP_DATA_ERROR<sup>7+</sup> | number | 4 | HTTP传输失败。 | 40| ERROR_INSUFFICIENT_SPACE<sup>7+</sup> | number | 5 | 存储空间不足。 | 41| ERROR_TOO_MANY_REDIRECTS<sup>7+</sup> | number | 6 | 网络重定向过多导致的错误。 | 42| ERROR_UNHANDLED_HTTP_CODE<sup>7+</sup> | number | 7 | 无法识别的HTTP代码。 | 43| ERROR_UNKNOWN<sup>7+</sup> | number | 8 | 未知错误。 | 44| ERROR_OFFLINE<sup>9+</sup> | number | 9 | 网络未连接。 | 45| ERROR_UNSUPPORTED_NETWORK_TYPE<sup>9+</sup> | number | 10 | 网络类型不匹配。 | 46 47 48### 下载任务暂停原因 49下载相关[getTaskInfo<sup>9+</sup>](#gettaskinfo9)返回值的pausedReason字段取值。 50 51| 名称 | 参数类型 | 数值 | 说明 | 52| -------- | -------- | -------- | -------- | 53| PAUSED_QUEUED_FOR_WIFI<sup>7+</sup> | number | 0 | 下载被暂停并等待WLAN连接，因为文件大小超过了使用蜂窝网络的会话允许的最大值。 | 54| PAUSED_WAITING_FOR_NETWORK<sup>7+</sup> | number | 1 | 由于网络问题（例如网络断开）而暂停下载。 | 55| PAUSED_WAITING_TO_RETRY<sup>7+</sup> | number | 2 | 发生网络错误，将重试下载会话。 | 56| PAUSED_BY_USER<sup>9+</sup> | number | 3 | 用户暂停会话。 | 57| PAUSED_UNKNOWN<sup>7+</sup> | number | 4 | 未知原因导致暂停下载。 | 58 59### 下载任务状态码 60下载相关[getTaskInfo<sup>9+</sup>](#gettaskinfo9)返回值的status字段取值。 61 62| 名称 | 参数类型 | 数值 | 说明 | 63| -------- | -------- | -------- | -------- | 64| SESSION_SUCCESSFUL<sup>7+</sup> | number | 0 | 下载会话已完成。 | 65| SESSION_RUNNING<sup>7+</sup> | number | 1 | 下载会话正在进行中。 | 66| SESSION_PENDING<sup>7+</sup> | number | 2 | 正在调度下载会话。 | 67| SESSION_PAUSED<sup>7+</sup> | number | 3 | 下载会话已暂停。 | 68| SESSION_FAILED<sup>7+</sup> | number | 4 | 下载会话已失败，将不会重试。 | 69 70 71## request.uploadFile<sup>9+</sup> 72 73uploadFile(context: BaseContext, config: UploadConfig): Promise<UploadTask> 74 75上传，异步方法，使用promise形式返回结果。通过[on('complete'|'fail')<sup>9+</sup>](#oncomplete--fail9)可获取任务上传时的错误信息。 76 77**需要权限**：ohos.permission.INTERNET 78 79**系统能力**: SystemCapability.MiscServices.Upload 80 81**参数：** 82 83 | 参数名 | 类型 | 必填 | 说明 | 84 | -------- | -------- | -------- | -------- | 85 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 86 | config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 | 87 88 89**返回值：** 90 91 | 类型 | 说明 | 92 | -------- | -------- | 93 | Promise<[UploadTask](#uploadtask)> | 返回上传任务。 | 94 95**错误码：** 96以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 97 98 | 错误码ID | 错误信息 | 99 | -------- | -------- | 100 | 13400002 | Bad file path. | 101 102**示例：** 103 104 ```js 105 let uploadTask; 106 let uploadConfig = { 107 url: 'https://patch', 108 header: { key1: "value1", key2: "value2" }, 109 method: "POST", 110 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 111 data: [{ name: "name123", value: "123" }], 112 }; 113 try { 114 request.uploadFile(globalThis.abilityContext, uploadConfig).then((data) => { 115 uploadTask = data; 116 }).catch((err) => { 117 console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); 118 }); 119 } catch (err) { 120 console.error('err.code : ' + err.code + ', err.message : ' + err.message); 121 } 122 ``` 123 124 125## request.uploadFile<sup>9+</sup> 126 127uploadFile(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void 128 129上传，异步方法，使用callback形式返回结果。通过[on('complete'|'fail')<sup>9+</sup>](#oncomplete--fail9)可获取任务上传时的错误信息。 130 131**需要权限**：ohos.permission.INTERNET 132 133**系统能力**: SystemCapability.MiscServices.Upload 134 135**参数：** 136 137 | 参数名 | 类型 | 必填 | 说明 | 138 | -------- | -------- | -------- | -------- | 139 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 140 | config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 | 141 | callback | AsyncCallback<[UploadTask](#uploadtask)> | 是 | 回调函数，异步返回UploadTask对象。 | 142 143**错误码：** 144以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 145 146 | 错误码ID | 错误信息 | 147 | -------- | -------- | 148 | 13400002 | Bad file path. | 149 150**示例：** 151 152 ```js 153 let uploadTask; 154 let uploadConfig = { 155 url: 'https://patch', 156 header: { key1: "value1", key2: "value2" }, 157 method: "POST", 158 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 159 data: [{ name: "name123", value: "123" }], 160 }; 161 try { 162 request.uploadFile(globalThis.abilityContext, uploadConfig, (err, data) => { 163 if (err) { 164 console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); 165 return; 166 } 167 uploadTask = data; 168 }); 169 } catch (err) { 170 console.error('err.code : ' + err.code + ', err.message : ' + err.message); 171 } 172 ``` 173 174## request.upload<sup>(deprecated)</sup> 175 176upload(config: UploadConfig): Promise<UploadTask> 177 178上传，异步方法，使用promise形式返回结果。 179 180**模型约束**：此接口仅可在FA模型下使用 181 182> **说明：** 从API Version 9开始不再维护，建议使用[request.uploadFile<sup>9+</sup>](#requestuploadfile9)替代。 183 184**需要权限**：ohos.permission.INTERNET 185 186**系统能力**: SystemCapability.MiscServices.Upload 187 188**参数：** 189 190 | 参数名 | 类型 | 必填 | 说明 | 191 | -------- | -------- | -------- | -------- | 192 | config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 | 193 194**返回值：** 195 196 | 类型 | 说明 | 197 | -------- | -------- | 198 | Promise<[UploadTask](#uploadtask)> | 返回上传任务。 | 199 200**示例：** 201 202 ```js 203 let uploadTask; 204 let uploadConfig = { 205 url: 'https://patch', 206 header: { key1: "value1", key2: "value2" }, 207 method: "POST", 208 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 209 data: [{ name: "name123", value: "123" }], 210 }; 211 request.upload(uploadConfig).then((data) => { 212 uploadTask = data; 213 }).catch((err) => { 214 console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); 215 }) 216 ``` 217 218 219## request.upload<sup>(deprecated)</sup> 220 221upload(config: UploadConfig, callback: AsyncCallback<UploadTask>): void 222 223上传，异步方法，使用callback形式返回结果。 224 225**模型约束**：此接口仅可在FA模型下使用 226 227> **说明：** 从API Version 9开始不再维护，建议使用[request.uploadFile<sup>9+</sup>](#requestuploadfile9-1)替代。 228 229**需要权限**：ohos.permission.INTERNET 230 231**系统能力**: SystemCapability.MiscServices.Upload 232 233**参数：** 234 235 | 参数名 | 类型 | 必填 | 说明 | 236 | -------- | -------- | -------- | -------- | 237 | config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 | 238 | callback | AsyncCallback<[UploadTask](#uploadtask)> | 是 | 回调函数，异步返回UploadTask对象。 | 239 240**示例：** 241 242 ```js 243 let uploadTask; 244 let uploadConfig = { 245 url: 'https://patch', 246 header: { key1: "value1", key2: "value2" }, 247 method: "POST", 248 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 249 data: [{ name: "name123", value: "123" }], 250 }; 251 request.upload(uploadConfig, (err, data) => { 252 if (err) { 253 console.error('Failed to request the upload. Cause: ' + JSON.stringify(err)); 254 return; 255 } 256 uploadTask = data; 257 }); 258 ``` 259 260## UploadTask 261 262上传任务，使用下列方法前，需要先获取UploadTask对象。 263 264 265### on('progress') 266 267on(type: 'progress', callback:(uploadedSize: number, totalSize: number) => void): void 268 269订阅上传任务进度监听，同步方法，使用callback形式返回结果。 270 271**需要权限**：ohos.permission.INTERNET 272 273**系统能力**: SystemCapability.MiscServices.Upload 274 275**参数：** 276 277 | 参数名 | 类型 | 必填 | 说明 | 278 | -------- | -------- | -------- | -------- | 279 | type | string | 是 | 订阅的事件类型，取值为'progress'（上传的进度信息）。 | 280 | callback | function | 是 | 上传进度的回调函数。 | 281 282 回调函数的参数 283 284| 参数名 | 类型 | 必填 | 说明 | 285| -------- | -------- | -------- | -------- | 286| uploadedSize | number | 是 | 当前已上传文件大小，单位为bit。 | 287| totalSize | number | 是 | 上传文件的总大小，单位为bit。 | 288 289**示例：** 290 291 ```js 292 let upProgressCallback = (uploadedSize, totalSize) => { 293 console.info("upload totalSize:" + totalSize + " uploadedSize:" + uploadedSize); 294 }; 295 uploadTask.on('progress', upProgressCallback); 296 ``` 297 298 299### on('headerReceive')<sup>7+</sup> 300 301on(type: 'headerReceive', callback: (header: object) => void): void 302 303订阅上传任务HTTP标头监听，同步方法，使用callback形式返回结果。 304 305**需要权限**：ohos.permission.INTERNET 306 307**系统能力**: SystemCapability.MiscServices.Upload 308 309**参数：** 310 311 | 参数名 | 类型 | 必填 | 说明 | 312 | -------- | -------- | -------- | -------- | 313 | type | string | 是 | 订阅的事件类型，取值为'headerReceive'（接收响应头）。 | 314 | callback | function | 是 | HTTP Response Header事件的回调函数。 | 315 316 回调函数的参数： 317 318| 参数名 | 类型 | 必填 | 说明 | 319| -------- | -------- | -------- | -------- | 320| header | object | 是 | HTTP Response Header。 | 321 322**示例：** 323 324 ```js 325 let headerCallback = (headers) => { 326 console.info("upOnHeader headers:" + JSON.stringify(headers)); 327 }; 328 uploadTask.on('headerReceive', headerCallback); 329 ``` 330 331 332### on('complete' | 'fail')<sup>9+</sup> 333 334 on(type:'complete' | 'fail', callback: Callback<Array<TaskState>>): void; 335 336订阅上传任务完成或失败监听，同步方法，使用callback形式返回结果。 337 338**需要权限**：ohos.permission.INTERNET 339 340**系统能力**: SystemCapability.MiscServices.Upload 341 342**参数：** 343 344 | 参数名 | 类型 | 必填 | 说明 | 345 | -------- | -------- | -------- | -------- | 346 | type | string | 是 | 订阅的事件类型，取值为'complete'，表示上传任务完成；取值为'fail'，表示上传任务失败。| 347 | callback | Callback<Array<TaskState>> | 是 | 上传任务完成或失败的回调函数。 | 348 349 回调函数的参数 350 351| 参数名 | 类型 | 必填 | 说明 | 352| -------- | -------- | -------- | -------- | 353| taskstates | Array<[TaskState](#taskstate9)> | 是 | 上传任务返回结果 | 354 355**示例：** 356 357 ```js 358 let upCompleteCallback = (taskStates) => { 359 for (let i = 0; i < taskStates.length; i++ ) { 360 console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i])); 361 } 362 }; 363 uploadTask.on('complete', upComplete); 364 365 let upFailCallback = (taskStates) => { 366 for (let i = 0; i < taskStates.length; i++ ) { 367 console.info("upOnFail taskState:" + JSON.stringify(taskStates[i])); 368 } 369 }; 370 uploadTask.on('fail', upFailCallback); 371 ``` 372 373 374### off('progress') 375 376off(type: 'progress', callback?: (uploadedSize: number, totalSize: number) => void): void 377 378删除上传任务进度监听，同步方法。 379 380**需要权限**：ohos.permission.INTERNET 381 382**系统能力**: SystemCapability.MiscServices.Upload 383 384**参数：** 385 386 | 参数名 | 类型 | 必填 | 说明 | 387 | -------- | -------- | -------- | -------- | 388 | type | string | 是 | 取消订阅的事件类型，取值为'progress'（上传的进度信息）。 | 389 | callback | function | 否 | 需要删除的上传任务进度的回调函数。<br/>uploadedSize：当前已上传文件的大小，单位为B。<br/>totalSize：上传文件的总大小，单位为B。 | 390 391**示例：** 392 393 ```js 394 uploadTask.off('progress', upProgressCallback); 395 ``` 396 397 398### off('headerReceive')<sup>7+</sup> 399 400off(type: 'headerReceive', callback?: (header: object) => void): void 401 402删除上传任务HTTP标头监听，同步方法。 403 404**需要权限**：ohos.permission.INTERNET 405 406**系统能力**: SystemCapability.MiscServices.Upload 407 408**参数：** 409 410 | 参数名 | 类型 | 必填 | 说明 | 411 | -------- | -------- | -------- | -------- | 412 | type | string | 是 | 取消订阅的事件类型，取值为'headerReceive'（接收响应头）。 | 413 | callback | function | 否 | HTTP Response 需要删除的Header事件的回调函数。<br/>header：HTTP Response Header。 | 414 415**示例：** 416 417 ```js 418 uploadTask.off('headerReceive', headerCallback); 419 ``` 420 421### off('complete' | 'fail')<sup>9+</sup> 422 423 off(type:'complete' | 'fail', callback?: Callback<Array<TaskState>>): void; 424 425删除上传任务完成或失败监听，同步方法。 426 427**需要权限**：ohos.permission.INTERNET 428 429**系统能力**: SystemCapability.MiscServices.Upload 430 431**参数：** 432 433 | 参数名 | 类型 | 必填 | 说明 | 434 | -------- | -------- | -------- | -------- | 435 | type | string | 是 | 订阅的事件类型，取值为'complete'，表示上传任务完成；取值为'fail'，表示上传任务失败。| 436 | callback | Callback<Array<TaskState>> | 否 | 需要删除的上传任务完成或失败的回调函数。<br/>taskstates：上传任务返回结果 | 437 438**示例：** 439 440 ```js 441 uploadTask.off('complete', upCompleteCallback); 442 443 uploadTask.off('fail', upFailCallback); 444 ``` 445 446### delete<sup>9+</sup> 447delete(): Promise<boolean> 448 449移除上传的任务，异步方法，使用promise形式返回结果。 450 451**需要权限**：ohos.permission.INTERNET 452 453**系统能力**: SystemCapability.MiscServices.Upload 454 455**返回值：** 456 457 | 类型 | 说明 | 458 | -------- | -------- | 459 | Promise<boolean> | 移除任务是否成功。true：成功，false：不成功。 | 460 461**示例：** 462 463 ```js 464 uploadTask.delete().then((result) => { 465 if (result) { 466 console.info('Upload task removed successfully. '); 467 } else { 468 console.error('Failed to remove the upload task. '); 469 } 470 }).catch((err) => { 471 console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); 472 }); 473 ``` 474 475 476### delete<sup>9+</sup> 477 478delete(callback: AsyncCallback<boolean>): void 479 480移除上传的任务，异步方法，使用callback形式返回结果。 481 482**需要权限**：ohos.permission.INTERNET 483 484**系统能力**: SystemCapability.MiscServices.Upload 485 486**参数：** 487 488 | 参数名 | 类型 | 必填 | 说明 | 489 | -------- | -------- | -------- | -------- | 490 | callback | AsyncCallback<boolean> | 是 | 移除任务的回调函数。 | 491 492**示例：** 493 494 ```js 495 uploadTask.delete((err, result) => { 496 if (err) { 497 console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); 498 return; 499 } 500 if (result) { 501 console.info('Upload task removed successfully.'); 502 } else { 503 console.error('Failed to remove the upload task.'); 504 } 505 }); 506 ``` 507 508 509### remove<sup>(deprecated)</sup> 510 511remove(): Promise<boolean> 512 513移除上传的任务，异步方法，使用promise形式返回结果。 514 515> **说明：** 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9)替代。 516 517**需要权限**：ohos.permission.INTERNET 518 519**系统能力**: SystemCapability.MiscServices.Upload 520 521**返回值：** 522 523 | 类型 | 说明 | 524 | -------- | -------- | 525 | Promise<boolean> | 移除任务是否成功。true：成功，false：不成功。 | 526 527**示例：** 528 529 ```js 530 uploadTask.remove().then((result) => { 531 if (result) { 532 console.info('Upload task removed successfully. '); 533 } else { 534 console.error('Failed to remove the upload task. '); 535 } 536 }).catch((err) => { 537 console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); 538 }); 539 ``` 540 541 542### remove<sup>(deprecated)</sup> 543 544remove(callback: AsyncCallback<boolean>): void 545 546移除上传的任务，异步方法，使用callback形式返回结果。 547 548> **说明：** 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9-1)替代。 549 550**需要权限**：ohos.permission.INTERNET 551 552**系统能力**: SystemCapability.MiscServices.Upload 553 554**参数：** 555 556 | 参数名 | 类型 | 必填 | 说明 | 557 | -------- | -------- | -------- | -------- | 558 | callback | AsyncCallback<boolean> | 是 | 移除任务的回调函数。 | 559 560**示例：** 561 562 ```js 563 uploadTask.remove((err, result) => { 564 if (err) { 565 console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); 566 return; 567 } 568 if (result) { 569 console.info('Upload task removed successfully.'); 570 } else { 571 console.error('Failed to remove the upload task.'); 572 } 573 }); 574 ``` 575 576## UploadConfig 577上传任务的配置信息。 578 579**需要权限**：ohos.permission.INTERNET 580 581**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。 582 583| 名称 | 类型 | 必填 | 说明 | 584| -------- | -------- | -------- | -------- | 585| url | string | 是 | 资源地址。 | 586| header | Object | 是 | 添加要包含在上传请求中的HTTP或HTTPS标志头。 | 587| method | string | 是 | 请求方法：POST、PUT。缺省为POST。 | 588| files | Array<[File](#file)> | 是 | 要上传的文件列表。请使用 multipart/form-data提交。 | 589| data | Array<[RequestData](#requestdata)> | 是 | 请求的表单数据。 | 590 591## TaskState<sup>9+</sup> 592 593上传任务信息，[on('complete' | 'fail')<sup>9+</sup>](#oncomplete--fail9)和[off('complete' | 'fail')<sup>9+</sup>](#offcomplete--fail9)接口的回调参数。 594 595**需要权限**：ohos.permission.INTERNET 596 597**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。 598 599| 名称 | 类型 | 必填 | 说明 | 600| -------- | -------- | -------- | -------- | 601| path | string | 是 | 文件路径 | 602| responseCode | number | 是 | 上传任务返回值 | 603| message | string | 是 | 上传任务结果描述信息 | 604 605## File 606[UploadConfig](#uploadconfig)中的文件列表。 607 608**需要权限**：ohos.permission.INTERNET 609 610**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。 611 612| 名称 | 类型 | 必填 | 说明 | 613| -------- | -------- | -------- | -------- | 614| filename | string | 是 | multipart提交时，请求头中的文件名。 | 615| name | string | 是 | multipart提交时，表单项目的名称，缺省为file。 | 616| uri | string | 是 | 文件的本地存储路径。<br/>仅支持“internal”协议类型，“internal://cache/”为必填字段，示例：<br/>internal://cache/path/to/file.txt | 617| type | string | 是 | 文件的内容类型，默认根据文件名或路径的后缀获取。 | 618 619 620## RequestData 621[UploadConfig](#uploadconfig)中的表单数据。 622 623**需要权限**：ohos.permission.INTERNET 624 625**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。 626 627| 名称 | 类型 | 必填 | 说明 | 628| -------- | -------- | -------- | -------- | 629| name | string | 是 | 表示表单元素的名称。 | 630| value | string | 是 | 表示表单元素的值。 | 631 632## request.downloadFile<sup>9+</sup> 633 634downloadFile(context: BaseContext, config: DownloadConfig): Promise<DownloadTask> 635 636下载，异步方法，使用promise形式返回结果。通过[on('complete'|'pause'|'remove')<sup>7+</sup>](#oncompletepauseremove7)可获取任务下载时的状态信息，包括任务完成、暂停或移除。通过[on('fail')<sup>7+</sup>](#onfail7)可获取任务下载时的错误信息。 637 638**需要权限**：ohos.permission.INTERNET 639 640**系统能力**: SystemCapability.MiscServices.Download 641 642**参数：** 643 644 | 参数名 | 类型 | 必填 | 说明 | 645 | -------- | -------- | -------- | -------- | 646 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 647 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 648 649**返回值：** 650 651 | 类型 | 说明 | 652 | -------- | -------- | 653 | Promise<[DownloadTask](#downloadtask)> | 返回下载任务。 | 654 655**错误码：** 656以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 657 658 | 错误码ID | 错误信息 | 659 | -------- | -------- | 660 | 13400001 | File operation error. | 661 | 13400002 | Bad file path. | 662 | 13400003 | Task manager service error. | 663 664**示例：** 665 666 ```js 667 let downloadTask; 668 try { 669 request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxx.hap' }).then((data) => { 670 downloadTask = data; 671 }).catch((err) => { 672 console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); 673 }) 674 } catch (err) { 675 console.error('err.code : ' + err.code + ', err.message : ' + err.message); 676 } 677 ``` 678 679 680## request.downloadFile<sup>9+</sup> 681 682downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void; 683 684下载，异步方法，使用callback形式返回结果。通过[on('complete'|'pause'|'remove')<sup>7+</sup>](#oncompletepauseremove7)可获取任务下载时的状态信息，包括任务完成、暂停或移除。通过[on('fail')<sup>7+</sup>](#onfail7)可获取任务下载时的错误信息。 685 686**需要权限**：ohos.permission.INTERNET 687 688**系统能力**: SystemCapability.MiscServices.Download 689 690**参数：** 691 692 | 参数名 | 类型 | 必填 | 说明 | 693 | -------- | -------- | -------- | -------- | 694 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 695 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 696 | callback | AsyncCallback<[DownloadTask](#downloadtask)> | 是 | 下载接口的回调函数。 | 697 698**错误码：** 699以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 700 701 | 错误码ID | 错误信息 | 702 | -------- | -------- | 703 | 13400001 | File operation error. | 704 | 13400002 | Bad file path. | 705 | 13400003 | Task manager service error. | 706 707**示例：** 708 709 ```js 710 let downloadTask; 711 try { 712 request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxxx.hap', 713 filePath: 'xxx/xxxxx.hap'}, (err, data) => { 714 if (err) { 715 console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); 716 return; 717 } 718 downloadTask = data; 719 }); 720 } catch (err) { 721 console.error('err.code : ' + err.code + ', err.message : ' + err.message); 722 } 723 ``` 724 725## request.download<sup>(deprecated)</sup> 726 727download(config: DownloadConfig): Promise<DownloadTask> 728 729下载，异步方法，使用promise形式返回结果。 730 731> **说明：** 从API Version 9开始不再维护，建议使用[request.downloadFile<sup>9+</sup>](#requestdownloadfile9)替代。 732 733**模型约束**：此接口仅可在FA模型下使用 734 735**需要权限**：ohos.permission.INTERNET 736 737**系统能力**: SystemCapability.MiscServices.Download 738 739**参数：** 740 741 | 参数名 | 类型 | 必填 | 说明 | 742 | -------- | -------- | -------- | -------- | 743 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 744 745**返回值：** 746 747 | 类型 | 说明 | 748 | -------- | -------- | 749 | Promise<[DownloadTask](#downloadtask)> | 返回下载任务。 | 750 751**示例：** 752 753 ```js 754 let downloadTask; 755 request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => { 756 downloadTask = data; 757 }).catch((err) => { 758 console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); 759 }) 760 ``` 761 762 763## request.download<sup>(deprecated)</sup> 764 765download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void 766 767下载，异步方法，使用callback形式返回结果。 768 769> **说明：** 从API Version 9开始不再维护，建议使用[request.downloadFile<sup>9+</sup>](#requestdownloadfile9-1)替代。 770 771**模型约束**：此接口仅可在FA模型下使用 772 773**需要权限**：ohos.permission.INTERNET 774 775**系统能力**: SystemCapability.MiscServices.Download 776 777**参数：** 778 779 | 参数名 | 类型 | 必填 | 说明 | 780 | -------- | -------- | -------- | -------- | 781 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 782 | callback | AsyncCallback<[DownloadTask](#downloadtask)> | 是 | 下载接口的回调函数。 | 783 784**示例：** 785 786 ```js 787 let downloadTask; 788 request.download({ url: 'https://xxxx/xxxxx.hap', 789 filePath: 'xxx/xxxxx.hap'}, (err, data) => { 790 if (err) { 791 console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); 792 return; 793 } 794 downloadTask = data; 795 }); 796 ``` 797 798## DownloadTask 799 800下载任务。 801 802 803### on('progress') 804 805on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void 806 807订阅下载任务进度监听，同步方法，使用callback形式返回结果。 808 809**需要权限**：ohos.permission.INTERNET 810 811**系统能力**: SystemCapability.MiscServices.Download 812 813**参数：** 814 815 | 参数名 | 类型 | 必填 | 说明 | 816 | -------- | -------- | -------- | -------- | 817 | type | string | 是 | 订阅的事件类型，取值为'progress'（下载的进度信息）。 | 818 | callback | function | 是 | 下载任务进度的回调函数。 | 819 820 回调函数的参数： 821 822| 参数名 | 类型 | 必填 | 说明 | 823| -------- | -------- | -------- | -------- | 824| receivedSize | number | 是 | 当前下载的进度，单位为bit。 | 825| totalSize | number | 是 | 下载文件的总大小，单位为bit。 | 826 827**示例：** 828 829 ```js 830 let progresCallbanck = (receivedSize, totalSize) => { 831 console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); 832 }; 833 downloadTask.on('progress', progresCallbanck); 834 ``` 835 836 837### off('progress') 838 839off(type: 'progress', callback?: (receivedSize: number, totalSize: number) => void): void 840 841删除下载任务进度监听，同步方法。 842 843**需要权限**：ohos.permission.INTERNET 844 845**系统能力**: SystemCapability.MiscServices.Download 846 847**参数：** 848 849 | 参数名 | 类型 | 必填 | 说明 | 850 | -------- | -------- | -------- | -------- | 851 | type | string | 是 | 取消订阅的事件类型，取值为'progress'（下载的进度信息）。 | 852 | callback | function | 否 | 需要删除的下载任务进度的回调。 <br/>receivedSize：当前下载任务的进度；<br/>totalSize：下载文件的总大小。 | 853 854**示例：** 855 856 ```js 857 downloadTask .off('progress',progresCallbanck); 858 ``` 859 860 861### on('complete'|'pause'|'remove')<sup>7+</sup> 862 863on(type: 'complete'|'pause'|'remove', callback:() => void): void 864 865订阅下载任务相关的监听，异步方法，使用callback形式返回。 866 867**需要权限**：ohos.permission.INTERNET 868 869**系统能力**: SystemCapability.MiscServices.Download 870 871**参数：** 872 873 | 参数名 | 类型 | 必填 | 说明 | 874 | -------- | -------- | -------- | -------- | 875 | type | string | 是 | 订阅的事件类型。<br>- 取值为'complete'，表示下载任务完成；<br/>- 取值为'pause'，表示下载任务暂停；<br/>- 取值为'remove'，表示下载任务移除。 | 876 | callback | function | 是 | 下载任务相关的回调函数。| 877 878**示例：** 879 880 ```js 881 let completeCallback = () => { 882 console.info('Download task completed.'); 883 }; 884 downloadTask.on('complete', completeCallback); 885 ``` 886 887 888### off('complete'|'pause'|'remove')<sup>7+</sup> 889 890off(type: 'complete'|'pause'|'remove', callback?:() => void): void 891 892删除下载任务相关的监听，同步方法。 893 894**需要权限**：ohos.permission.INTERNET 895 896**系统能力**: SystemCapability.MiscServices.Download 897 898**参数：** 899 900 | 参数名 | 类型 | 必填 | 说明 | 901 | -------- | -------- | -------- | -------- | 902 | type | string | 是 | 取消订阅的事件类型。<br/>- 取值为'complete'，表示下载任务完成；<br/>- 取值为'pause'，表示下载任务暂停；<br/>- 取值为'remove'，表示下载任务移除。 | 903 | callback | function | 否 | 需要删除的下载任务相关的回调。 | 904 905**示例：** 906 907 ```js 908 downloadTask.off('complete', completeCallback); 909 ``` 910 911 912### on('fail')<sup>7+</sup> 913 914on(type: 'fail', callback: (err: number) => void): void 915 916订阅下载任务失败监听，同步方法，使用callback形式返回结果。 917 918**需要权限**：ohos.permission.INTERNET 919 920**系统能力**: SystemCapability.MiscServices.Download 921 922**参数：** 923 924 | 参数名 | 类型 | 必填 | 说明 | 925 | -------- | -------- | -------- | -------- | 926 | type | string | 是 | 订阅的事件类型，取值为'fail'（下载失败）。 | 927 | callback | function | 是 | 下载失败的回调函数。 | 928 929 回调函数的参数： 930 931| 参数名 | 类型 | 必填 | 说明 | 932| -------- | -------- | -------- | -------- | 933| err | number | 是 | 下载失败的错误码，错误原因见[下载任务的错误码](#下载任务的错误码)。 | 934 935**示例：** 936 937 ```js 938 let failCallback = (err) => { 939 console.info('Download task failed. Cause:' + err); 940 }; 941 downloadTask.on('fail', failCallback); 942 ``` 943 944 945### off('fail')<sup>7+</sup> 946 947off(type: 'fail', callback?: (err: number) => void): void 948 949删除下载任务失败监听，同步方法。 950 951**需要权限**：ohos.permission.INTERNET 952 953**系统能力**: SystemCapability.MiscServices.Download 954 955**参数：** 956 957 | 参数名 | 类型 | 必填 | 说明 | 958 | -------- | -------- | -------- | -------- | 959 | type | string | 是 | 取消订阅的事件类型，取值为'fail'（下载失败）。 | 960 | callback | function | 否 | 需要删除的下载失败的回调函数。<br/>err：下载失败的错误码。 | 961 962**示例：** 963 964 ```js 965 downloadTask.off('fail', failCallback); 966 ``` 967 968### delete<sup>9+</sup> 969 970delete(): Promise<boolean> 971 972移除下载的任务，异步方法，使用promise形式返回结果。 973 974**需要权限**：ohos.permission.INTERNET 975 976**系统能力**: SystemCapability.MiscServices.Download 977 978**返回值：** 979 980 | 类型 | 说明 | 981 | -------- | -------- | 982 | Promise<boolean> | 移除任务是否成功。 | 983 984**示例：** 985 986 ```js 987 downloadTask.delete().then((result) => { 988 if (result) { 989 console.info('Download task removed.'); 990 } else { 991 console.error('Failed to remove the download task.'); 992 } 993 }).catch ((err) => { 994 console.error('Failed to remove the download task.'); 995 }); 996 ``` 997 998 999### delete<sup>9+</sup> 1000 1001delete(callback: AsyncCallback<boolean>): void 1002 1003移除下载的任务，异步方法，使用callback形式返回结果。 1004 1005**需要权限**：ohos.permission.INTERNET 1006 1007**系统能力**: SystemCapability.MiscServices.Download 1008 1009**参数：** 1010 1011 | 参数名 | 类型 | 必填 | 说明 | 1012 | -------- | -------- | -------- | -------- | 1013 | callback | AsyncCallback<boolean> | 是 | 移除任务是否成功。 | 1014 1015**示例：** 1016 1017 ```js 1018 downloadTask.delete((err, result)=>{ 1019 if(err) { 1020 console.error('Failed to remove the download task.'); 1021 return; 1022 } 1023 if (result) { 1024 console.info('Download task removed.'); 1025 } else { 1026 console.error('Failed to remove the download task.'); 1027 } 1028 }); 1029 ``` 1030 1031 1032### getTaskInfo<sup>9+</sup> 1033 1034getTaskInfo(): Promise<DownloadInfo> 1035 1036查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。 1037 1038**需要权限**：ohos.permission.INTERNET 1039 1040**系统能力**: SystemCapability.MiscServices.Download 1041 1042**返回值：** 1043 1044 | 类型 | 说明 | 1045 | -------- | -------- | 1046 | Promise<[DownloadInfo](#downloadinfo7)> | 查询下载任务信息。 | 1047 1048**示例：** 1049 1050 ```js 1051 downloadTask.getTaskInfo().then((downloadInfo) => { 1052 console.info('Download task queried. Data:' + JSON.stringify(downloadInfo)) 1053 }) .catch((err) => { 1054 console.error('Failed to query the download task. Cause:' + err) 1055 }); 1056 ``` 1057 1058 1059### getTaskInfo<sup>9+</sup> 1060 1061getTaskInfo(callback: AsyncCallback<DownloadInfo>): void 1062 1063查询下载的任务，异步方法，使用callback形式返回结果。 1064 1065**需要权限**：ohos.permission.INTERNET 1066 1067**系统能力**: SystemCapability.MiscServices.Download 1068 1069**参数：** 1070 1071 | 参数名 | 类型 | 必填 | 说明 | 1072 | -------- | -------- | -------- | -------- | 1073 | callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | 是 | 查询下载任务的回调函数。 | 1074 1075**示例：** 1076 1077 ```js 1078 downloadTask.getTaskInfo((err, downloadInfo)=>{ 1079 if(err) { 1080 console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); 1081 } else { 1082 console.info('download query success. data:'+ JSON.stringify(downloadInfo)); 1083 } 1084 }); 1085 ``` 1086 1087 1088### getTaskMimeType<sup>9+</sup> 1089 1090getTaskMimeType(): Promise<string> 1091 1092查询下载的任务的 MimeType，异步方法，使用promise形式返回结果。 1093 1094**需要权限**：ohos.permission.INTERNET 1095 1096**系统能力**: SystemCapability.MiscServices.Download 1097 1098**返回值：** 1099 1100 | 类型 | 说明 | 1101 | -------- | -------- | 1102 | Promise<string> | 查询下载任务的MimeType。 | 1103 1104**示例：** 1105 1106 ```js 1107 downloadTask.getTaskMimeType().then((data) => { 1108 console.info('Download task queried. Data:' + JSON.stringify(data)); 1109 }).catch((err) => { 1110 console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err)) 1111 }); 1112 ``` 1113 1114 1115### getTaskMimeType<sup>9+</sup> 1116 1117getTaskMimeType(callback: AsyncCallback<string>): void; 1118 1119查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。 1120 1121**需要权限**：ohos.permission.INTERNET 1122 1123**系统能力**: SystemCapability.MiscServices.Download 1124 1125**参数：** 1126 1127 | 参数名 | 类型 | 必填 | 说明 | 1128 | -------- | -------- | -------- | -------- | 1129 | callback | AsyncCallback<string> | 是 | 查询下载任务的MimeType的回调函数。 | 1130 1131**示例：** 1132 1133 ```js 1134 downloadTask.getTaskMimeType((err, data)=>{ 1135 if(err) { 1136 console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); 1137 } else { 1138 console.info('Download task queried. data:' + JSON.stringify(data)); 1139 } 1140 }); 1141 ``` 1142 1143 1144### suspend<sup>9+</sup> 1145 1146suspend(): Promise<boolean> 1147 1148暂停下载任务，异步方法，使用promise形式返回结果。 1149 1150**需要权限**：ohos.permission.INTERNET 1151 1152**系统能力**: SystemCapability.MiscServices.Download 1153 1154**返回值：** 1155 1156 | 类型 | 说明 | 1157 | -------- | -------- | 1158 | Promise<boolean> | 暂停下载任务是否成功。 | 1159 1160**示例：** 1161 1162 ```js 1163 downloadTask.suspend().then((result) => { 1164 if (result) { 1165 console.info('Download task paused. '); 1166 } else { 1167 console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); 1168 } 1169 }).catch((err) => { 1170 console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); 1171 }); 1172 ``` 1173 1174 1175### suspend<sup>9+</sup> 1176 1177suspend(callback: AsyncCallback<boolean>): void 1178 1179暂停下载任务，异步方法，使用callback形式返回结果。 1180 1181**需要权限**：ohos.permission.INTERNET 1182 1183**系统能力**: SystemCapability.MiscServices.Download 1184 1185**参数：** 1186 1187 | 参数名 | 类型 | 必填 | 说明 | 1188 | -------- | -------- | -------- | -------- | 1189 | callback | AsyncCallback<boolean> | 是 | 暂停下载任务的回调函数。 | 1190 1191**示例：** 1192 1193 ```js 1194 downloadTask.suspend((err, result)=>{ 1195 if(err) { 1196 console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); 1197 return; 1198 } 1199 if (result) { 1200 console.info('Download task paused. '); 1201 } else { 1202 console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); 1203 } 1204 }); 1205 ``` 1206 1207 1208### restore<sup>9+</sup> 1209 1210restore(): Promise<boolean> 1211 1212重新启动暂停的下载任务，异步方法，使用promise形式返回结果。 1213 1214**需要权限**：ohos.permission.INTERNET 1215 1216**系统能力**: SystemCapability.MiscServices.Download 1217 1218**返回值：** 1219 1220 | 类型 | 说明 | 1221 | -------- | -------- | 1222 | Promise<boolean> | 重新启动暂停的下载任务是否成功。 | 1223 1224**示例：** 1225 1226 ```js 1227 downloadTask.restore().then((result) => { 1228 if (result) { 1229 console.info('Download task resumed.') 1230 } else { 1231 console.error('Failed to resume the download task. '); 1232 } 1233 console.info('Download task resumed.') 1234 }).catch((err) => { 1235 console.error('Failed to resume the download task. Cause:' + err); 1236 }); 1237 ``` 1238 1239 1240### restore<sup>9+</sup> 1241 1242restore(callback: AsyncCallback<boolean>): void 1243 1244重新启动暂停的下载任务，异步方法，使用callback形式返回结果。 1245 1246**需要权限**：ohos.permission.INTERNET 1247 1248**系统能力**: SystemCapability.MiscServices.Download 1249 1250**参数：** 1251 1252 | 参数名 | 类型 | 必填 | 说明 | 1253 | -------- | -------- | -------- | -------- | 1254 | callback | AsyncCallback<boolean> | 是 | 重新启动暂停的下载任务的回调函数。 | 1255 1256**示例：** 1257 1258 ```js 1259 downloadTask.restore((err, result)=>{ 1260 if (err) { 1261 console.error('Failed to resume the download task. Cause:' + err); 1262 return; 1263 } 1264 if (result) { 1265 console.info('Download task resumed.'); 1266 } else { 1267 console.error('Failed to resume the download task.'); 1268 } 1269 }); 1270 ``` 1271 1272 1273 1274### remove<sup>(deprecated)</sup> 1275 1276remove(): Promise<boolean> 1277 1278移除下载的任务，异步方法，使用promise形式返回结果。 1279 1280> **说明：** 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9-2)替代。 1281 1282**需要权限**：ohos.permission.INTERNET 1283 1284**系统能力**: SystemCapability.MiscServices.Download 1285 1286**返回值：** 1287 1288 | 类型 | 说明 | 1289 | -------- | -------- | 1290 | Promise<boolean> | 移除任务是否成功。 | 1291 1292**示例：** 1293 1294 ```js 1295 downloadTask.remove().then((result) => { 1296 if (result) { 1297 console.info('Download task removed.'); 1298 } else { 1299 console.error('Failed to remove the download task.'); 1300 } 1301 }).catch ((err) => { 1302 console.error('Failed to remove the download task.'); 1303 }); 1304 ``` 1305 1306 1307### remove<sup>(deprecated)</sup> 1308 1309remove(callback: AsyncCallback<boolean>): void 1310 1311移除下载的任务，异步方法，使用callback形式返回结果。 1312 1313> **说明：** 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9-3)替代。 1314 1315**需要权限**：ohos.permission.INTERNET 1316 1317**系统能力**: SystemCapability.MiscServices.Download 1318 1319**参数：** 1320 1321 | 参数名 | 类型 | 必填 | 说明 | 1322 | -------- | -------- | -------- | -------- | 1323 | callback | AsyncCallback<boolean> | 是 | 移除任务是否成功。 | 1324 1325**示例：** 1326 1327 ```js 1328 downloadTask.remove((err, result)=>{ 1329 if(err) { 1330 console.error('Failed to remove the download task.'); 1331 return; 1332 } 1333 if (result) { 1334 console.info('Download task removed.'); 1335 } else { 1336 console.error('Failed to remove the download task.'); 1337 } 1338 }); 1339 ``` 1340 1341 1342### query<sup>(deprecated)</sup> 1343 1344query(): Promise<DownloadInfo> 1345 1346查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。 1347 1348> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskInfo<sup>9+</sup>](#gettaskinfo9)替代。 1349 1350**需要权限**：ohos.permission.INTERNET 1351 1352**系统能力**: SystemCapability.MiscServices.Download 1353 1354**返回值：** 1355 1356 | 类型 | 说明 | 1357 | -------- | -------- | 1358 | Promise<[DownloadInfo](#downloadinfo7)> | 查询下载任务信息。 | 1359 1360**示例：** 1361 1362 ```js 1363 downloadTask.query().then((downloadInfo) => { 1364 console.info('Download task queried. Data:' + JSON.stringify(downloadInfo)) 1365 }) .catch((err) => { 1366 console.error('Failed to query the download task. Cause:' + err) 1367 }); 1368 ``` 1369 1370 1371### query<sup>(deprecated)</sup> 1372 1373query(callback: AsyncCallback<DownloadInfo>): void 1374 1375查询下载的任务，异步方法，使用callback形式返回结果。 1376 1377> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskInfo<sup>9+</sup>](#gettaskinfo9-1)替代。 1378 1379**需要权限**：ohos.permission.INTERNET 1380 1381**系统能力**: SystemCapability.MiscServices.Download 1382 1383**参数：** 1384 1385 | 参数名 | 类型 | 必填 | 说明 | 1386 | -------- | -------- | -------- | -------- | 1387 | callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | 是 | 查询下载任务的回调函数。 | 1388 1389**示例：** 1390 1391 ```js 1392 downloadTask.query((err, downloadInfo)=>{ 1393 if(err) { 1394 console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); 1395 } else { 1396 console.info('download query success. data:'+ JSON.stringify(downloadInfo)); 1397 } 1398 }); 1399 ``` 1400 1401 1402### queryMimeType<sup>(deprecated)</sup> 1403 1404queryMimeType(): Promise<string> 1405 1406查询下载的任务的 MimeType，异步方法，使用promise形式返回结果。 1407 1408> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskMimeType<sup>9+</sup>](#gettaskmimetype9)替代。 1409 1410**需要权限**：ohos.permission.INTERNET 1411 1412**系统能力**: SystemCapability.MiscServices.Download 1413 1414**返回值：** 1415 1416 | 类型 | 说明 | 1417 | -------- | -------- | 1418 | Promise<string> | 查询下载任务的MimeType。 | 1419 1420**示例：** 1421 1422 ```js 1423 downloadTask.queryMimeType().then((data) => { 1424 console.info('Download task queried. Data:' + JSON.stringify(data)); 1425 }).catch((err) => { 1426 console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err)) 1427 }); 1428 ``` 1429 1430 1431### queryMimeType<sup>(deprecated)</sup> 1432 1433queryMimeType(callback: AsyncCallback<string>): void; 1434 1435查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。 1436 1437> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskMimeType<sup>9+</sup>](#gettaskmimetype9-1)替代。 1438 1439**需要权限**：ohos.permission.INTERNET 1440 1441**系统能力**: SystemCapability.MiscServices.Download 1442 1443**参数：** 1444 1445 | 参数名 | 类型 | 必填 | 说明 | 1446 | -------- | -------- | -------- | -------- | 1447 | callback | AsyncCallback<string> | 是 | 查询下载任务的MimeType的回调函数。 | 1448 1449**示例：** 1450 1451 ```js 1452 downloadTask.queryMimeType((err, data)=>{ 1453 if(err) { 1454 console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); 1455 } else { 1456 console.info('Download task queried. data:' + JSON.stringify(data)); 1457 } 1458 }); 1459 ``` 1460 1461 1462### pause<sup>(deprecated)</sup> 1463 1464pause(): Promise<void> 1465 1466暂停下载任务，异步方法，使用promise形式返回结果。 1467 1468> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[suspend<sup>9+</sup>](#suspend9)替代。 1469 1470**需要权限**：ohos.permission.INTERNET 1471 1472**系统能力**: SystemCapability.MiscServices.Download 1473 1474**返回值：** 1475 1476 | 类型 | 说明 | 1477 | -------- | -------- | 1478 | Promise<void> | 暂停下载任务是否成功。 | 1479 1480**示例：** 1481 1482 ```js 1483 downloadTask.pause().then((result) => { 1484 if (result) { 1485 console.info('Download task paused. '); 1486 } else { 1487 console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); 1488 } 1489 }).catch((err) => { 1490 console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); 1491 }); 1492 ``` 1493 1494 1495### pause<sup>(deprecated)</sup> 1496 1497pause(callback: AsyncCallback<void>): void 1498 1499> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[suspend<sup>9+</sup>](#suspend9-1)替代。 1500 1501暂停下载任务，异步方法，使用callback形式返回结果。 1502 1503**需要权限**：ohos.permission.INTERNET 1504 1505**系统能力**: SystemCapability.MiscServices.Download 1506 1507**参数：** 1508 1509 | 参数名 | 类型 | 必填 | 说明 | 1510 | -------- | -------- | -------- | -------- | 1511 | callback | AsyncCallback<void> | 是 | 暂停下载任务的回调函数。 | 1512 1513**示例：** 1514 1515 ```js 1516 downloadTask.pause((err, result)=>{ 1517 if(err) { 1518 console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); 1519 return; 1520 } 1521 if (result) { 1522 console.info('Download task paused. '); 1523 } else { 1524 console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); 1525 } 1526 }); 1527 ``` 1528 1529 1530### resume<sup>(deprecated)</sup> 1531 1532resume(): Promise<void> 1533 1534重新启动暂停的下载任务，异步方法，使用promise形式返回结果。 1535 1536> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[restore<sup>9+</sup>](#restore9)替代。 1537 1538**需要权限**：ohos.permission.INTERNET 1539 1540**系统能力**: SystemCapability.MiscServices.Download 1541 1542**返回值：** 1543 1544 | 类型 | 说明 | 1545 | -------- | -------- | 1546 | Promise<void> | 重新启动暂停的下载任务是否成功。 | 1547 1548**示例：** 1549 1550 ```js 1551 downloadTask.resume().then((result) => { 1552 if (result) { 1553 console.info('Download task resumed.') 1554 } else { 1555 console.error('Failed to resume the download task. '); 1556 } 1557 console.info('Download task resumed.') 1558 }).catch((err) => { 1559 console.error('Failed to resume the download task. Cause:' + err); 1560 }); 1561 ``` 1562 1563 1564### resume<sup>(deprecated)</sup> 1565 1566resume(callback: AsyncCallback<void>): void 1567 1568> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[restore<sup>9+</sup>](#restore9-1)替代。 1569 1570重新启动暂停的下载任务，异步方法，使用callback形式返回结果。 1571 1572**需要权限**：ohos.permission.INTERNET 1573 1574**系统能力**: SystemCapability.MiscServices.Download 1575 1576**参数：** 1577 1578 | 参数名 | 类型 | 必填 | 说明 | 1579 | -------- | -------- | -------- | -------- | 1580 | callback | AsyncCallback<void> | 是 | 重新启动暂停的下载任务的回调函数。 | 1581 1582**示例：** 1583 1584 ```js 1585 downloadTask.resume((err, result)=>{ 1586 if (err) { 1587 console.error('Failed to resume the download task. Cause:' + err); 1588 return; 1589 } 1590 if (result) { 1591 console.info('Download task resumed.'); 1592 } else { 1593 console.error('Failed to resume the download task.'); 1594 } 1595 }); 1596 ``` 1597 1598 1599## DownloadConfig 1600下载任务的配置信息。 1601 1602**需要权限**：ohos.permission.INTERNET 1603 1604**系统能力**: SystemCapability.MiscServices.Download 1605 1606| 名称 | 类型 | 必填 | 说明 | 1607| -------- | -------- | -------- | -------- | 1608| url | string | 是 | 资源地址。 | 1609| header | Object | 否 | 添加要包含在下载请求中的HTTPS标志头。<br/>开发者可以通过header的X-TLS-Version参数指定需要使用的TLS版本(如果不指定，则默认使用CURL_SSLVERSION_TLSv1_2版本，指定则使用指定版本。)<br/>CURL_SSLVERSION_TLSv1_0<br/>CURL_SSLVERSION_TLSv1_1<br/>CURL_SSLVERSION_TLSv1_2<br/>CURL_SSLVERSION_TLSv1_3<br/>通过header的X-Cipher-List参数指定需要使用的密码套件(如果不指定，则默认使用安全密码套件，指定则使用指定密码套件。)<br/>-1.2允许使用的密码套件白名单：<br/>TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,<br/>TLS_DHE_DSS_WITH_AES_128_GCM_SHA256,TLS_DSS_RSA_WITH_AES_256_GCM_SHA384,<br/>TLS_PSK_WITH_AES_256_GCM_SHA384,TLS_DHE_PSK_WITH_AES_128_GCM_SHA256,<br/>TLS_DHE_PSK_WITH_AES_256_GCM_SHA384,TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256,<br/>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,<br/>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,<br/>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256,<br/>TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256,TLS_ECDHE_PSK_WITH_AES_256_GCM_SHA384,<br/>TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_CCM,<br/>TLS_DHE_RSA_WITH_AES_256_CCM,TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256,<br/>TLS_PSK_WITH_AES_256_CCM,TLS_DHE_PSK_WITH_AES_128_CCM,<br/>TLS_DHE_PSK_WITH_AES_256_CCM,TLS_ECDHE_ECDSA_WITH_AES_128_CCM,<br/>TLS_ECDHE_ECDSA_WITH_AES_256_CCM,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256<br/>-1.3允许使用的密码套件白名单：<br/>TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_CCM_SHA256<br/>-1.3新增国密算法套：<br/>TLS_SM4_GCM_SM3,TLS_SM4_CCM_SM3 | 1610| enableMetered | boolean | 否 | 设置是否允许在按流量计费的连接下下载(默认使用false)。Wi-Fi为非计费网络，数据流量为计费网络。<br/>- true：是<br/>- false：否 | 1611| enableRoaming | boolean | 否 | 设置是否允许在漫游网络中下载(默认使用false)。 <br/>- true：是<br/>- false：否| 1612| description | string | 否 | 设置下载会话的描述。 | 1613| filePath<sup>7+</sup> | string | 否 | 设置下载路径。<br/>- FA模型下使用[context](js-apis-inner-app-context.md#contextgetcachedir) 获取应用存储路径，比如：\'${featureAbility.getContext().getFilesDir()}/test.txt\'，并将文件存储在此路径下。<br/>- Stage模型下使用[AbilityContext](js-apis-inner-application-context.md) 类获取文件路径，比如：\'${globalThis.abilityContext.tempDir}/test.txt\'并将文件存储在此路径下。 | 1614| networkType | number | 否 | 设置允许下载的网络类型(默认使用NETWORK_MOBILE&NETWORK_WIFI)。<br/>- NETWORK_MOBILE：0x00000001<br/>- NETWORK_WIFI：0x00010000| 1615| title | string | 否 | 设置下载任务名称。 | 1616| background<sup>9+</sup> | boolean | 否 | 后台任务通知开关，开启后可在通知中显示下载状态(默认使用false)。 | 1617 1618 1619## DownloadInfo<sup>7+</sup> 1620下载任务信息，[getTaskInfo<sup>9+</sup>](#gettaskinfo9)接口的回调参数。 1621 1622**需要权限**：ohos.permission.INTERNET 1623 1624**系统能力**: SystemCapability.MiscServices.Download 1625 1626| 名称 | 类型 | 说明 | 1627| -------- | ------ |---------------- | 1628| downloadId | number | 下载任务ID。 | 1629| failedReason | number | 下载失败原因，可以是任何[下载任务的错误码](#下载任务的错误码)常量。 | 1630| fileName | string | 下载的文件名。 | 1631| filePath | string | 存储文件的URI。 | 1632| pausedReason | number | 会话暂停的原因，可以是任何[下载任务暂停原因](#下载任务暂停原因)常量。 | 1633| status | number | 下载状态码，可以是任何[下载任务状态码](#下载任务状态码)常量。 | 1634| targetURI | string | 下载文件的URI。 | 1635| downloadTitle | string | 下载任务名称。 | 1636| downloadTotalBytes | number | 下载的文件的总大小（int bytes）。 | 1637| description | string | 待下载任务的描述信息。 | 1638| downloadedBytes | number | 实时下载大小（int bytes）。 | 1639<!--no_check-->
