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', upCompleteCallback); 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 let upProgressCallback = (uploadedSize, totalSize) => { 395 console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize); 396 }; 397 uploadTask.off('progress', upProgressCallback); 398 ``` 399 400 401### off('headerReceive')<sup>7+</sup> 402 403off(type: 'headerReceive', callback?: (header: object) => void): void 404 405删除上传任务HTTP标头监听，同步方法。 406 407**需要权限**：ohos.permission.INTERNET 408 409**系统能力**: SystemCapability.MiscServices.Upload 410 411**参数：** 412 413 | 参数名 | 类型 | 必填 | 说明 | 414 | -------- | -------- | -------- | -------- | 415 | type | string | 是 | 取消订阅的事件类型，取值为'headerReceive'（接收响应头）。 | 416 | callback | function | 否 | HTTP Response 需要删除的Header事件的回调函数。<br/>header：HTTP Response Header。 | 417 418**示例：** 419 420 ```js 421 let headerCallback = (header) => { 422 console.info(`Upload delete headerReceive notification. header: ${JSON.stringify(header)}`); 423 }; 424 uploadTask.off('headerReceive', headerCallback); 425 ``` 426 427### off('complete' | 'fail')<sup>9+</sup> 428 429 off(type:'complete' | 'fail', callback?: Callback<Array<TaskState>>): void; 430 431删除上传任务完成或失败监听，同步方法。 432 433**需要权限**：ohos.permission.INTERNET 434 435**系统能力**: SystemCapability.MiscServices.Upload 436 437**参数：** 438 439 | 参数名 | 类型 | 必填 | 说明 | 440 | -------- | -------- | -------- | -------- | 441 | type | string | 是 | 订阅的事件类型，取值为'complete'，表示上传任务完成；取值为'fail'，表示上传任务失败。| 442 | callback | Callback<Array<TaskState>> | 否 | 需要删除的上传任务完成或失败的回调函数。<br/>taskstates：上传任务返回结果 | 443 444**示例：** 445 446 ```js 447 let upCompleteCallback = (taskStates) => { 448 console.info('Upload delete complete notification.'); 449 for (let i = 0; i < taskStates.length; i++ ) { 450 console.info('taskState:' + JSON.stringify(taskStates[i])); 451 } 452 }; 453 uploadTask.off('complete', upCompleteCallback); 454 455 let upFailCallback = (taskStates) => { 456 console.info('Upload delete fail notification.'); 457 for (let i = 0; i < taskStates.length; i++ ) { 458 console.info('taskState:' + JSON.stringify(taskStates[i])); 459 } 460 }; 461 uploadTask.off('fail', upFailCallback); 462 ``` 463 464### delete<sup>9+</sup> 465delete(): Promise<boolean> 466 467移除上传的任务，异步方法，使用promise形式返回结果。 468 469**需要权限**：ohos.permission.INTERNET 470 471**系统能力**: SystemCapability.MiscServices.Upload 472 473**返回值：** 474 475 | 类型 | 说明 | 476 | -------- | -------- | 477 | Promise<boolean> | 移除任务是否成功。true：成功，false：不成功。 | 478 479**示例：** 480 481 ```js 482 uploadTask.delete().then((result) => { 483 if (result) { 484 console.info('Upload task removed successfully. '); 485 } else { 486 console.error('Failed to remove the upload task. '); 487 } 488 }).catch((err) => { 489 console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); 490 }); 491 ``` 492 493 494### delete<sup>9+</sup> 495 496delete(callback: AsyncCallback<boolean>): void 497 498移除上传的任务，异步方法，使用callback形式返回结果。 499 500**需要权限**：ohos.permission.INTERNET 501 502**系统能力**: SystemCapability.MiscServices.Upload 503 504**参数：** 505 506 | 参数名 | 类型 | 必填 | 说明 | 507 | -------- | -------- | -------- | -------- | 508 | callback | AsyncCallback<boolean> | 是 | 移除任务的回调函数。 | 509 510**示例：** 511 512 ```js 513 uploadTask.delete((err, result) => { 514 if (err) { 515 console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); 516 return; 517 } 518 if (result) { 519 console.info('Upload task removed successfully.'); 520 } else { 521 console.error('Failed to remove the upload task.'); 522 } 523 }); 524 ``` 525 526 527### remove<sup>(deprecated)</sup> 528 529remove(): Promise<boolean> 530 531移除上传的任务，异步方法，使用promise形式返回结果。 532 533> **说明：** 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9)替代。 534 535**需要权限**：ohos.permission.INTERNET 536 537**系统能力**: SystemCapability.MiscServices.Upload 538 539**返回值：** 540 541 | 类型 | 说明 | 542 | -------- | -------- | 543 | Promise<boolean> | 移除任务是否成功。true：成功，false：不成功。 | 544 545**示例：** 546 547 ```js 548 uploadTask.remove().then((result) => { 549 if (result) { 550 console.info('Upload task removed successfully. '); 551 } else { 552 console.error('Failed to remove the upload task. '); 553 } 554 }).catch((err) => { 555 console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); 556 }); 557 ``` 558 559 560### remove<sup>(deprecated)</sup> 561 562remove(callback: AsyncCallback<boolean>): void 563 564移除上传的任务，异步方法，使用callback形式返回结果。 565 566> **说明：** 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9-1)替代。 567 568**需要权限**：ohos.permission.INTERNET 569 570**系统能力**: SystemCapability.MiscServices.Upload 571 572**参数：** 573 574 | 参数名 | 类型 | 必填 | 说明 | 575 | -------- | -------- | -------- | -------- | 576 | callback | AsyncCallback<boolean> | 是 | 移除任务的回调函数。 | 577 578**示例：** 579 580 ```js 581 uploadTask.remove((err, result) => { 582 if (err) { 583 console.error('Failed to remove the upload task. Cause: ' + JSON.stringify(err)); 584 return; 585 } 586 if (result) { 587 console.info('Upload task removed successfully.'); 588 } else { 589 console.error('Failed to remove the upload task.'); 590 } 591 }); 592 ``` 593 594## UploadConfig 595上传任务的配置信息。 596 597**需要权限**：ohos.permission.INTERNET 598 599**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。 600 601| 名称 | 类型 | 必填 | 说明 | 602| -------- | -------- | -------- | -------- | 603| url | string | 是 | 资源地址。 | 604| header | Object | 是 | 添加要包含在上传请求中的HTTP或HTTPS标志头。 | 605| method | string | 是 | 请求方法：POST、PUT。缺省为POST。 | 606| files | Array<[File](#file)> | 是 | 要上传的文件列表。请使用 multipart/form-data提交。 | 607| data | Array<[RequestData](#requestdata)> | 是 | 请求的表单数据。 | 608 609## TaskState<sup>9+</sup> 610 611上传任务信息，[on('complete' | 'fail')<sup>9+</sup>](#oncomplete--fail9)和[off('complete' | 'fail')<sup>9+</sup>](#offcomplete--fail9)接口的回调参数。 612 613**需要权限**：ohos.permission.INTERNET 614 615**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。 616 617| 名称 | 类型 | 必填 | 说明 | 618| -------- | -------- | -------- | -------- | 619| path | string | 是 | 文件路径 | 620| responseCode | number | 是 | 上传任务返回值 | 621| message | string | 是 | 上传任务结果描述信息 | 622 623## File 624[UploadConfig](#uploadconfig)中的文件列表。 625 626**需要权限**：ohos.permission.INTERNET 627 628**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。 629 630| 名称 | 类型 | 必填 | 说明 | 631| -------- | -------- | -------- | -------- | 632| filename | string | 是 | multipart提交时，请求头中的文件名。 | 633| name | string | 是 | multipart提交时，表单项目的名称，缺省为file。 | 634| uri | string | 是 | 文件的本地存储路径。<br/>仅支持“internal”协议类型，“internal://cache/”为必填字段，示例：<br/>internal://cache/path/to/file.txt | 635| type | string | 是 | 文件的内容类型，默认根据文件名或路径的后缀获取。 | 636 637 638## RequestData 639[UploadConfig](#uploadconfig)中的表单数据。 640 641**需要权限**：ohos.permission.INTERNET 642 643**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。 644 645| 名称 | 类型 | 必填 | 说明 | 646| -------- | -------- | -------- | -------- | 647| name | string | 是 | 表示表单元素的名称。 | 648| value | string | 是 | 表示表单元素的值。 | 649 650## request.downloadFile<sup>9+</sup> 651 652downloadFile(context: BaseContext, config: DownloadConfig): Promise<DownloadTask> 653 654下载，异步方法，使用promise形式返回结果。通过[on('complete'|'pause'|'remove')<sup>7+</sup>](#oncompletepauseremove7)可获取任务下载时的状态信息，包括任务完成、暂停或移除。通过[on('fail')<sup>7+</sup>](#onfail7)可获取任务下载时的错误信息。 655 656**需要权限**：ohos.permission.INTERNET 657 658**系统能力**: SystemCapability.MiscServices.Download 659 660**参数：** 661 662 | 参数名 | 类型 | 必填 | 说明 | 663 | -------- | -------- | -------- | -------- | 664 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 665 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 666 667**返回值：** 668 669 | 类型 | 说明 | 670 | -------- | -------- | 671 | Promise<[DownloadTask](#downloadtask)> | 返回下载任务。 | 672 673**错误码：** 674以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 675 676 | 错误码ID | 错误信息 | 677 | -------- | -------- | 678 | 13400001 | file operation error. | 679 | 13400002 | bad file path. | 680 | 13400003 | task manager service error. | 681 682**示例：** 683 684 ```js 685 let downloadTask; 686 try { 687 request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxx.hap' }).then((data) => { 688 downloadTask = data; 689 }).catch((err) => { 690 console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); 691 }) 692 } catch (err) { 693 console.error('err.code : ' + err.code + ', err.message : ' + err.message); 694 } 695 ``` 696 697 698## request.downloadFile<sup>9+</sup> 699 700downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void; 701 702下载，异步方法，使用callback形式返回结果。通过[on('complete'|'pause'|'remove')<sup>7+</sup>](#oncompletepauseremove7)可获取任务下载时的状态信息，包括任务完成、暂停或移除。通过[on('fail')<sup>7+</sup>](#onfail7)可获取任务下载时的错误信息。 703 704**需要权限**：ohos.permission.INTERNET 705 706**系统能力**: SystemCapability.MiscServices.Download 707 708**参数：** 709 710 | 参数名 | 类型 | 必填 | 说明 | 711 | -------- | -------- | -------- | -------- | 712 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 713 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 714 | callback | AsyncCallback<[DownloadTask](#downloadtask)> | 是 | 下载接口的回调函数。 | 715 716**错误码：** 717以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 718 719 | 错误码ID | 错误信息 | 720 | -------- | -------- | 721 | 13400001 | file operation error. | 722 | 13400002 | bad file path. | 723 | 13400003 | task manager service error. | 724 725**示例：** 726 727 ```js 728 let downloadTask; 729 try { 730 request.downloadFile(globalThis.abilityContext, { url: 'https://xxxx/xxxxx.hap', 731 filePath: 'xxx/xxxxx.hap'}, (err, data) => { 732 if (err) { 733 console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); 734 return; 735 } 736 downloadTask = data; 737 }); 738 } catch (err) { 739 console.error('err.code : ' + err.code + ', err.message : ' + err.message); 740 } 741 ``` 742 743## request.download<sup>(deprecated)</sup> 744 745download(config: DownloadConfig): Promise<DownloadTask> 746 747下载，异步方法，使用promise形式返回结果。 748 749> **说明：** 从API Version 9开始不再维护，建议使用[request.downloadFile<sup>9+</sup>](#requestdownloadfile9)替代。 750 751**模型约束**：此接口仅可在FA模型下使用 752 753**需要权限**：ohos.permission.INTERNET 754 755**系统能力**: SystemCapability.MiscServices.Download 756 757**参数：** 758 759 | 参数名 | 类型 | 必填 | 说明 | 760 | -------- | -------- | -------- | -------- | 761 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 762 763**返回值：** 764 765 | 类型 | 说明 | 766 | -------- | -------- | 767 | Promise<[DownloadTask](#downloadtask)> | 返回下载任务。 | 768 769**示例：** 770 771 ```js 772 let downloadTask; 773 request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => { 774 downloadTask = data; 775 }).catch((err) => { 776 console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); 777 }) 778 ``` 779 780 781## request.download<sup>(deprecated)</sup> 782 783download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void 784 785下载，异步方法，使用callback形式返回结果。 786 787> **说明：** 从API Version 9开始不再维护，建议使用[request.downloadFile<sup>9+</sup>](#requestdownloadfile9-1)替代。 788 789**模型约束**：此接口仅可在FA模型下使用 790 791**需要权限**：ohos.permission.INTERNET 792 793**系统能力**: SystemCapability.MiscServices.Download 794 795**参数：** 796 797 | 参数名 | 类型 | 必填 | 说明 | 798 | -------- | -------- | -------- | -------- | 799 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 800 | callback | AsyncCallback<[DownloadTask](#downloadtask)> | 是 | 下载接口的回调函数。 | 801 802**示例：** 803 804 ```js 805 let downloadTask; 806 request.download({ url: 'https://xxxx/xxxxx.hap', 807 filePath: 'xxx/xxxxx.hap'}, (err, data) => { 808 if (err) { 809 console.error('Failed to request the download. Cause: ' + JSON.stringify(err)); 810 return; 811 } 812 downloadTask = data; 813 }); 814 ``` 815 816## DownloadTask 817 818下载任务。 819 820 821### on('progress') 822 823on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void 824 825订阅下载任务进度监听，同步方法，使用callback形式返回结果。 826 827**需要权限**：ohos.permission.INTERNET 828 829**系统能力**: SystemCapability.MiscServices.Download 830 831**参数：** 832 833 | 参数名 | 类型 | 必填 | 说明 | 834 | -------- | -------- | -------- | -------- | 835 | type | string | 是 | 订阅的事件类型，取值为'progress'（下载的进度信息）。 | 836 | callback | function | 是 | 下载任务进度的回调函数。 | 837 838 回调函数的参数： 839 840| 参数名 | 类型 | 必填 | 说明 | 841| -------- | -------- | -------- | -------- | 842| receivedSize | number | 是 | 当前下载的进度，单位为bit。 | 843| totalSize | number | 是 | 下载文件的总大小，单位为bit。 | 844 845**示例：** 846 847 ```js 848 let progresCallback = (receivedSize, totalSize) => { 849 console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); 850 }; 851 downloadTask.on('progress', progresCallback); 852 ``` 853 854 855### off('progress') 856 857off(type: 'progress', callback?: (receivedSize: number, totalSize: number) => void): void 858 859删除下载任务进度监听，同步方法。 860 861**需要权限**：ohos.permission.INTERNET 862 863**系统能力**: SystemCapability.MiscServices.Download 864 865**参数：** 866 867 | 参数名 | 类型 | 必填 | 说明 | 868 | -------- | -------- | -------- | -------- | 869 | type | string | 是 | 取消订阅的事件类型，取值为'progress'（下载的进度信息）。 | 870 | callback | function | 否 | 需要删除的下载任务进度的回调。 <br/>receivedSize：当前下载任务的进度；<br/>totalSize：下载文件的总大小。 | 871 872**示例：** 873 874 ```js 875 let progresCallback = (receivedSize, totalSize) => { 876 console.info('Download delete progress notification.' + 'receivedSize:' + receivedSize + 'totalSize:' + totalSize); 877 }; 878 downloadTask.off('progress', progresCallback); 879 ``` 880 881 882### on('complete'|'pause'|'remove')<sup>7+</sup> 883 884on(type: 'complete'|'pause'|'remove', callback:() => void): void 885 886订阅下载任务相关的监听，异步方法，使用callback形式返回。 887 888**需要权限**：ohos.permission.INTERNET 889 890**系统能力**: SystemCapability.MiscServices.Download 891 892**参数：** 893 894 | 参数名 | 类型 | 必填 | 说明 | 895 | -------- | -------- | -------- | -------- | 896 | type | string | 是 | 订阅的事件类型。<br>- 取值为'complete'，表示下载任务完成；<br/>- 取值为'pause'，表示下载任务暂停；<br/>- 取值为'remove'，表示下载任务移除。 | 897 | callback | function | 是 | 下载任务相关的回调函数。| 898 899**示例：** 900 901 ```js 902 let completeCallback = () => { 903 console.info('Download task completed.'); 904 }; 905 downloadTask.on('complete', completeCallback); 906 907 let pauseCallback = () => { 908 console.info('Download task pause.'); 909 }; 910 downloadTask.on('pause', pauseCallback); 911 912 let removeCallback = () => { 913 console.info('Download task remove.'); 914 }; 915 downloadTask.on('remove', removeCallback); 916 ``` 917 918 919### off('complete'|'pause'|'remove')<sup>7+</sup> 920 921off(type: 'complete'|'pause'|'remove', callback?:() => void): void 922 923删除下载任务相关的监听，同步方法。 924 925**需要权限**：ohos.permission.INTERNET 926 927**系统能力**: SystemCapability.MiscServices.Download 928 929**参数：** 930 931 | 参数名 | 类型 | 必填 | 说明 | 932 | -------- | -------- | -------- | -------- | 933 | type | string | 是 | 取消订阅的事件类型。<br/>- 取值为'complete'，表示下载任务完成；<br/>- 取值为'pause'，表示下载任务暂停；<br/>- 取值为'remove'，表示下载任务移除。 | 934 | callback | function | 否 | 需要删除的下载任务相关的回调。 | 935 936**示例：** 937 938 ```js 939 let completeCallback = () => { 940 console.info('Download delete complete notification.'); 941 }; 942 downloadTask.off('complete', completeCallback); 943 944 let pauseCallback = () => { 945 console.info('Download delete pause notification.'); 946 }; 947 downloadTask.off('pause', pauseCallback); 948 949 let removeCallback = () => { 950 console.info('Download delete remove notification.'); 951 }; 952 downloadTask.off('remove', removeCallback); 953 ``` 954 955 956### on('fail')<sup>7+</sup> 957 958on(type: 'fail', callback: (err: number) => void): void 959 960订阅下载任务失败监听，同步方法，使用callback形式返回结果。 961 962**需要权限**：ohos.permission.INTERNET 963 964**系统能力**: SystemCapability.MiscServices.Download 965 966**参数：** 967 968 | 参数名 | 类型 | 必填 | 说明 | 969 | -------- | -------- | -------- | -------- | 970 | type | string | 是 | 订阅的事件类型，取值为'fail'（下载失败）。 | 971 | callback | function | 是 | 下载失败的回调函数。 | 972 973 回调函数的参数： 974 975| 参数名 | 类型 | 必填 | 说明 | 976| -------- | -------- | -------- | -------- | 977| err | number | 是 | 下载失败的错误码，错误原因见[下载任务的错误码](#下载任务的错误码)。 | 978 979**示例：** 980 981 ```js 982 let failCallback = (err) => { 983 console.info('Download task failed. Cause:' + err); 984 }; 985 downloadTask.on('fail', failCallback); 986 ``` 987 988 989### off('fail')<sup>7+</sup> 990 991off(type: 'fail', callback?: (err: number) => void): void 992 993删除下载任务失败监听，同步方法。 994 995**需要权限**：ohos.permission.INTERNET 996 997**系统能力**: SystemCapability.MiscServices.Download 998 999**参数：** 1000 1001 | 参数名 | 类型 | 必填 | 说明 | 1002 | -------- | -------- | -------- | -------- | 1003 | type | string | 是 | 取消订阅的事件类型，取值为'fail'（下载失败）。 | 1004 | callback | function | 否 | 需要删除的下载失败的回调函数。<br/>err：下载失败的错误码。 | 1005 1006**示例：** 1007 1008 ```js 1009 let failCallback = (err) => { 1010 console.info(`Download delete fail notification. err: ${err.message}`); 1011 }; 1012 downloadTask.off('fail', failCallback); 1013 ``` 1014 1015### delete<sup>9+</sup> 1016 1017delete(): Promise<boolean> 1018 1019移除下载的任务，异步方法，使用promise形式返回结果。 1020 1021**需要权限**：ohos.permission.INTERNET 1022 1023**系统能力**: SystemCapability.MiscServices.Download 1024 1025**返回值：** 1026 1027 | 类型 | 说明 | 1028 | -------- | -------- | 1029 | Promise<boolean> | 移除任务是否成功。 | 1030 1031**示例：** 1032 1033 ```js 1034 downloadTask.delete().then((result) => { 1035 if (result) { 1036 console.info('Download task removed.'); 1037 } else { 1038 console.error('Failed to remove the download task.'); 1039 } 1040 }).catch ((err) => { 1041 console.error('Failed to remove the download task.'); 1042 }); 1043 ``` 1044 1045 1046### delete<sup>9+</sup> 1047 1048delete(callback: AsyncCallback<boolean>): void 1049 1050移除下载的任务，异步方法，使用callback形式返回结果。 1051 1052**需要权限**：ohos.permission.INTERNET 1053 1054**系统能力**: SystemCapability.MiscServices.Download 1055 1056**参数：** 1057 1058 | 参数名 | 类型 | 必填 | 说明 | 1059 | -------- | -------- | -------- | -------- | 1060 | callback | AsyncCallback<boolean> | 是 | 移除任务是否成功。 | 1061 1062**示例：** 1063 1064 ```js 1065 downloadTask.delete((err, result)=>{ 1066 if(err) { 1067 console.error('Failed to remove the download task.'); 1068 return; 1069 } 1070 if (result) { 1071 console.info('Download task removed.'); 1072 } else { 1073 console.error('Failed to remove the download task.'); 1074 } 1075 }); 1076 ``` 1077 1078 1079### getTaskInfo<sup>9+</sup> 1080 1081getTaskInfo(): Promise<DownloadInfo> 1082 1083查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。 1084 1085**需要权限**：ohos.permission.INTERNET 1086 1087**系统能力**: SystemCapability.MiscServices.Download 1088 1089**返回值：** 1090 1091 | 类型 | 说明 | 1092 | -------- | -------- | 1093 | Promise<[DownloadInfo](#downloadinfo7)> | 查询下载任务信息。 | 1094 1095**示例：** 1096 1097 ```js 1098 downloadTask.getTaskInfo().then((downloadInfo) => { 1099 console.info('Download task queried. Data:' + JSON.stringify(downloadInfo)) 1100 }) .catch((err) => { 1101 console.error('Failed to query the download task. Cause:' + err) 1102 }); 1103 ``` 1104 1105 1106### getTaskInfo<sup>9+</sup> 1107 1108getTaskInfo(callback: AsyncCallback<DownloadInfo>): void 1109 1110查询下载的任务，异步方法，使用callback形式返回结果。 1111 1112**需要权限**：ohos.permission.INTERNET 1113 1114**系统能力**: SystemCapability.MiscServices.Download 1115 1116**参数：** 1117 1118 | 参数名 | 类型 | 必填 | 说明 | 1119 | -------- | -------- | -------- | -------- | 1120 | callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | 是 | 查询下载任务的回调函数。 | 1121 1122**示例：** 1123 1124 ```js 1125 downloadTask.getTaskInfo((err, downloadInfo)=>{ 1126 if(err) { 1127 console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); 1128 } else { 1129 console.info('download query success. data:'+ JSON.stringify(downloadInfo)); 1130 } 1131 }); 1132 ``` 1133 1134 1135### getTaskMimeType<sup>9+</sup> 1136 1137getTaskMimeType(): Promise<string> 1138 1139查询下载的任务的 MimeType，异步方法，使用promise形式返回结果。 1140 1141**需要权限**：ohos.permission.INTERNET 1142 1143**系统能力**: SystemCapability.MiscServices.Download 1144 1145**返回值：** 1146 1147 | 类型 | 说明 | 1148 | -------- | -------- | 1149 | Promise<string> | 查询下载任务的MimeType。 | 1150 1151**示例：** 1152 1153 ```js 1154 downloadTask.getTaskMimeType().then((data) => { 1155 console.info('Download task queried. Data:' + JSON.stringify(data)); 1156 }).catch((err) => { 1157 console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err)) 1158 }); 1159 ``` 1160 1161 1162### getTaskMimeType<sup>9+</sup> 1163 1164getTaskMimeType(callback: AsyncCallback<string>): void; 1165 1166查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。 1167 1168**需要权限**：ohos.permission.INTERNET 1169 1170**系统能力**: SystemCapability.MiscServices.Download 1171 1172**参数：** 1173 1174 | 参数名 | 类型 | 必填 | 说明 | 1175 | -------- | -------- | -------- | -------- | 1176 | callback | AsyncCallback<string> | 是 | 查询下载任务的MimeType的回调函数。 | 1177 1178**示例：** 1179 1180 ```js 1181 downloadTask.getTaskMimeType((err, data)=>{ 1182 if(err) { 1183 console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); 1184 } else { 1185 console.info('Download task queried. data:' + JSON.stringify(data)); 1186 } 1187 }); 1188 ``` 1189 1190 1191### suspend<sup>9+</sup> 1192 1193suspend(): Promise<boolean> 1194 1195暂停下载任务，异步方法，使用promise形式返回结果。 1196 1197**需要权限**：ohos.permission.INTERNET 1198 1199**系统能力**: SystemCapability.MiscServices.Download 1200 1201**返回值：** 1202 1203 | 类型 | 说明 | 1204 | -------- | -------- | 1205 | Promise<boolean> | 暂停下载任务是否成功。 | 1206 1207**示例：** 1208 1209 ```js 1210 downloadTask.suspend().then((result) => { 1211 if (result) { 1212 console.info('Download task paused. '); 1213 } else { 1214 console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); 1215 } 1216 }).catch((err) => { 1217 console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); 1218 }); 1219 ``` 1220 1221 1222### suspend<sup>9+</sup> 1223 1224suspend(callback: AsyncCallback<boolean>): void 1225 1226暂停下载任务，异步方法，使用callback形式返回结果。 1227 1228**需要权限**：ohos.permission.INTERNET 1229 1230**系统能力**: SystemCapability.MiscServices.Download 1231 1232**参数：** 1233 1234 | 参数名 | 类型 | 必填 | 说明 | 1235 | -------- | -------- | -------- | -------- | 1236 | callback | AsyncCallback<boolean> | 是 | 暂停下载任务的回调函数。 | 1237 1238**示例：** 1239 1240 ```js 1241 downloadTask.suspend((err, result)=>{ 1242 if(err) { 1243 console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); 1244 return; 1245 } 1246 if (result) { 1247 console.info('Download task paused. '); 1248 } else { 1249 console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); 1250 } 1251 }); 1252 ``` 1253 1254 1255### restore<sup>9+</sup> 1256 1257restore(): Promise<boolean> 1258 1259重新启动暂停的下载任务，异步方法，使用promise形式返回结果。 1260 1261**需要权限**：ohos.permission.INTERNET 1262 1263**系统能力**: SystemCapability.MiscServices.Download 1264 1265**返回值：** 1266 1267 | 类型 | 说明 | 1268 | -------- | -------- | 1269 | Promise<boolean> | 重新启动暂停的下载任务是否成功。 | 1270 1271**示例：** 1272 1273 ```js 1274 downloadTask.restore().then((result) => { 1275 if (result) { 1276 console.info('Download task resumed.') 1277 } else { 1278 console.error('Failed to resume the download task. '); 1279 } 1280 console.info('Download task resumed.') 1281 }).catch((err) => { 1282 console.error('Failed to resume the download task. Cause:' + err); 1283 }); 1284 ``` 1285 1286 1287### restore<sup>9+</sup> 1288 1289restore(callback: AsyncCallback<boolean>): void 1290 1291重新启动暂停的下载任务，异步方法，使用callback形式返回结果。 1292 1293**需要权限**：ohos.permission.INTERNET 1294 1295**系统能力**: SystemCapability.MiscServices.Download 1296 1297**参数：** 1298 1299 | 参数名 | 类型 | 必填 | 说明 | 1300 | -------- | -------- | -------- | -------- | 1301 | callback | AsyncCallback<boolean> | 是 | 重新启动暂停的下载任务的回调函数。 | 1302 1303**示例：** 1304 1305 ```js 1306 downloadTask.restore((err, result)=>{ 1307 if (err) { 1308 console.error('Failed to resume the download task. Cause:' + err); 1309 return; 1310 } 1311 if (result) { 1312 console.info('Download task resumed.'); 1313 } else { 1314 console.error('Failed to resume the download task.'); 1315 } 1316 }); 1317 ``` 1318 1319 1320 1321### remove<sup>(deprecated)</sup> 1322 1323remove(): Promise<boolean> 1324 1325移除下载的任务，异步方法，使用promise形式返回结果。 1326 1327> **说明：** 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9-2)替代。 1328 1329**需要权限**：ohos.permission.INTERNET 1330 1331**系统能力**: SystemCapability.MiscServices.Download 1332 1333**返回值：** 1334 1335 | 类型 | 说明 | 1336 | -------- | -------- | 1337 | Promise<boolean> | 移除任务是否成功。 | 1338 1339**示例：** 1340 1341 ```js 1342 downloadTask.remove().then((result) => { 1343 if (result) { 1344 console.info('Download task removed.'); 1345 } else { 1346 console.error('Failed to remove the download task.'); 1347 } 1348 }).catch ((err) => { 1349 console.error('Failed to remove the download task.'); 1350 }); 1351 ``` 1352 1353 1354### remove<sup>(deprecated)</sup> 1355 1356remove(callback: AsyncCallback<boolean>): void 1357 1358移除下载的任务，异步方法，使用callback形式返回结果。 1359 1360> **说明：** 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9-3)替代。 1361 1362**需要权限**：ohos.permission.INTERNET 1363 1364**系统能力**: SystemCapability.MiscServices.Download 1365 1366**参数：** 1367 1368 | 参数名 | 类型 | 必填 | 说明 | 1369 | -------- | -------- | -------- | -------- | 1370 | callback | AsyncCallback<boolean> | 是 | 移除任务是否成功。 | 1371 1372**示例：** 1373 1374 ```js 1375 downloadTask.remove((err, result)=>{ 1376 if(err) { 1377 console.error('Failed to remove the download task.'); 1378 return; 1379 } 1380 if (result) { 1381 console.info('Download task removed.'); 1382 } else { 1383 console.error('Failed to remove the download task.'); 1384 } 1385 }); 1386 ``` 1387 1388 1389### query<sup>(deprecated)</sup> 1390 1391query(): Promise<DownloadInfo> 1392 1393查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。 1394 1395> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskInfo<sup>9+</sup>](#gettaskinfo9)替代。 1396 1397**需要权限**：ohos.permission.INTERNET 1398 1399**系统能力**: SystemCapability.MiscServices.Download 1400 1401**返回值：** 1402 1403 | 类型 | 说明 | 1404 | -------- | -------- | 1405 | Promise<[DownloadInfo](#downloadinfo7)> | 查询下载任务信息。 | 1406 1407**示例：** 1408 1409 ```js 1410 downloadTask.query().then((downloadInfo) => { 1411 console.info('Download task queried. Data:' + JSON.stringify(downloadInfo)) 1412 }) .catch((err) => { 1413 console.error('Failed to query the download task. Cause:' + err) 1414 }); 1415 ``` 1416 1417 1418### query<sup>(deprecated)</sup> 1419 1420query(callback: AsyncCallback<DownloadInfo>): void 1421 1422查询下载的任务，异步方法，使用callback形式返回结果。 1423 1424> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskInfo<sup>9+</sup>](#gettaskinfo9-1)替代。 1425 1426**需要权限**：ohos.permission.INTERNET 1427 1428**系统能力**: SystemCapability.MiscServices.Download 1429 1430**参数：** 1431 1432 | 参数名 | 类型 | 必填 | 说明 | 1433 | -------- | -------- | -------- | -------- | 1434 | callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | 是 | 查询下载任务的回调函数。 | 1435 1436**示例：** 1437 1438 ```js 1439 downloadTask.query((err, downloadInfo)=>{ 1440 if(err) { 1441 console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); 1442 } else { 1443 console.info('download query success. data:'+ JSON.stringify(downloadInfo)); 1444 } 1445 }); 1446 ``` 1447 1448 1449### queryMimeType<sup>(deprecated)</sup> 1450 1451queryMimeType(): Promise<string> 1452 1453查询下载的任务的 MimeType，异步方法，使用promise形式返回结果。 1454 1455> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskMimeType<sup>9+</sup>](#gettaskmimetype9)替代。 1456 1457**需要权限**：ohos.permission.INTERNET 1458 1459**系统能力**: SystemCapability.MiscServices.Download 1460 1461**返回值：** 1462 1463 | 类型 | 说明 | 1464 | -------- | -------- | 1465 | Promise<string> | 查询下载任务的MimeType。 | 1466 1467**示例：** 1468 1469 ```js 1470 downloadTask.queryMimeType().then((data) => { 1471 console.info('Download task queried. Data:' + JSON.stringify(data)); 1472 }).catch((err) => { 1473 console.error('Failed to query the download MimeType. Cause:' + JSON.stringify(err)) 1474 }); 1475 ``` 1476 1477 1478### queryMimeType<sup>(deprecated)</sup> 1479 1480queryMimeType(callback: AsyncCallback<string>): void; 1481 1482查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。 1483 1484> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskMimeType<sup>9+</sup>](#gettaskmimetype9-1)替代。 1485 1486**需要权限**：ohos.permission.INTERNET 1487 1488**系统能力**: SystemCapability.MiscServices.Download 1489 1490**参数：** 1491 1492 | 参数名 | 类型 | 必填 | 说明 | 1493 | -------- | -------- | -------- | -------- | 1494 | callback | AsyncCallback<string> | 是 | 查询下载任务的MimeType的回调函数。 | 1495 1496**示例：** 1497 1498 ```js 1499 downloadTask.queryMimeType((err, data)=>{ 1500 if(err) { 1501 console.error('Failed to query the download mimeType. Cause:' + JSON.stringify(err)); 1502 } else { 1503 console.info('Download task queried. data:' + JSON.stringify(data)); 1504 } 1505 }); 1506 ``` 1507 1508 1509### pause<sup>(deprecated)</sup> 1510 1511pause(): Promise<void> 1512 1513暂停下载任务，异步方法，使用promise形式返回结果。 1514 1515> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[suspend<sup>9+</sup>](#suspend9)替代。 1516 1517**需要权限**：ohos.permission.INTERNET 1518 1519**系统能力**: SystemCapability.MiscServices.Download 1520 1521**返回值：** 1522 1523 | 类型 | 说明 | 1524 | -------- | -------- | 1525 | Promise<void> | 暂停下载任务是否成功。 | 1526 1527**示例：** 1528 1529 ```js 1530 downloadTask.pause().then((result) => { 1531 if (result) { 1532 console.info('Download task paused. '); 1533 } else { 1534 console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); 1535 } 1536 }).catch((err) => { 1537 console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); 1538 }); 1539 ``` 1540 1541 1542### pause<sup>(deprecated)</sup> 1543 1544pause(callback: AsyncCallback<void>): void 1545 1546> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[suspend<sup>9+</sup>](#suspend9-1)替代。 1547 1548暂停下载任务，异步方法，使用callback形式返回结果。 1549 1550**需要权限**：ohos.permission.INTERNET 1551 1552**系统能力**: SystemCapability.MiscServices.Download 1553 1554**参数：** 1555 1556 | 参数名 | 类型 | 必填 | 说明 | 1557 | -------- | -------- | -------- | -------- | 1558 | callback | AsyncCallback<void> | 是 | 暂停下载任务的回调函数。 | 1559 1560**示例：** 1561 1562 ```js 1563 downloadTask.pause((err, result)=>{ 1564 if(err) { 1565 console.error('Failed to pause the download task. Cause:' + JSON.stringify(err)); 1566 return; 1567 } 1568 if (result) { 1569 console.info('Download task paused. '); 1570 } else { 1571 console.error('Failed to pause the download task. Cause:' + JSON.stringify(result)); 1572 } 1573 }); 1574 ``` 1575 1576 1577### resume<sup>(deprecated)</sup> 1578 1579resume(): Promise<void> 1580 1581重新启动暂停的下载任务，异步方法，使用promise形式返回结果。 1582 1583> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[restore<sup>9+</sup>](#restore9)替代。 1584 1585**需要权限**：ohos.permission.INTERNET 1586 1587**系统能力**: SystemCapability.MiscServices.Download 1588 1589**返回值：** 1590 1591 | 类型 | 说明 | 1592 | -------- | -------- | 1593 | Promise<void> | 重新启动暂停的下载任务是否成功。 | 1594 1595**示例：** 1596 1597 ```js 1598 downloadTask.resume().then((result) => { 1599 if (result) { 1600 console.info('Download task resumed.') 1601 } else { 1602 console.error('Failed to resume the download task. '); 1603 } 1604 console.info('Download task resumed.') 1605 }).catch((err) => { 1606 console.error('Failed to resume the download task. Cause:' + err); 1607 }); 1608 ``` 1609 1610 1611### resume<sup>(deprecated)</sup> 1612 1613resume(callback: AsyncCallback<void>): void 1614 1615> **说明：** 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[restore<sup>9+</sup>](#restore9-1)替代。 1616 1617重新启动暂停的下载任务，异步方法，使用callback形式返回结果。 1618 1619**需要权限**：ohos.permission.INTERNET 1620 1621**系统能力**: SystemCapability.MiscServices.Download 1622 1623**参数：** 1624 1625 | 参数名 | 类型 | 必填 | 说明 | 1626 | -------- | -------- | -------- | -------- | 1627 | callback | AsyncCallback<void> | 是 | 重新启动暂停的下载任务的回调函数。 | 1628 1629**示例：** 1630 1631 ```js 1632 downloadTask.resume((err, result)=>{ 1633 if (err) { 1634 console.error('Failed to resume the download task. Cause:' + err); 1635 return; 1636 } 1637 if (result) { 1638 console.info('Download task resumed.'); 1639 } else { 1640 console.error('Failed to resume the download task.'); 1641 } 1642 }); 1643 ``` 1644 1645 1646## DownloadConfig 1647下载任务的配置信息。 1648 1649**需要权限**：ohos.permission.INTERNET 1650 1651**系统能力**: SystemCapability.MiscServices.Download 1652 1653| 名称 | 类型 | 必填 | 说明 | 1654| -------- | -------- | -------- | -------- | 1655| url | string | 是 | 资源地址。 | 1656| 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 | 1657| enableMetered | boolean | 否 | 设置是否允许在按流量计费的连接下下载(默认使用false)。Wi-Fi为非计费网络，数据流量为计费网络。<br/>- true：是<br/>- false：否 | 1658| enableRoaming | boolean | 否 | 设置是否允许在漫游网络中下载(默认使用false)。 <br/>- true：是<br/>- false：否| 1659| description | string | 否 | 设置下载会话的描述。 | 1660| 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\'并将文件存储在此路径下。 | 1661| networkType | number | 否 | 设置允许下载的网络类型(默认使用NETWORK_MOBILE&NETWORK_WIFI)。<br/>- NETWORK_MOBILE：0x00000001<br/>- NETWORK_WIFI：0x00010000| 1662| title | string | 否 | 设置下载任务名称。 | 1663| background<sup>9+</sup> | boolean | 否 | 后台任务通知开关，开启后可在通知中显示下载状态(默认使用false)。 | 1664 1665 1666## DownloadInfo<sup>7+</sup> 1667下载任务信息，[getTaskInfo<sup>9+</sup>](#gettaskinfo9)接口的回调参数。 1668 1669**需要权限**：ohos.permission.INTERNET 1670 1671**系统能力**: SystemCapability.MiscServices.Download 1672 1673| 名称 | 类型 | 必填 | 说明 | 1674| -------- | ------ | ------ |---------------- | 1675| downloadId | number | 是 |下载任务ID。 | 1676| failedReason | number | 是 |下载失败原因，可以是任何[下载任务的错误码](#下载任务的错误码)常量。 | 1677| fileName | string | 是 |下载的文件名。 | 1678| filePath | string | 是 |存储文件的URI。 | 1679| pausedReason | number |是 | 会话暂停的原因，可以是任何[下载任务暂停原因](#下载任务暂停原因)常量。 | 1680| status | number | 是 |下载状态码，可以是任何[下载任务状态码](#下载任务状态码)常量。 | 1681| targetURI | string | 是 |下载文件的URI。 | 1682| downloadTitle | string | 是 |下载任务名称。 | 1683| downloadTotalBytes | number |是 | 下载的文件的总大小（int bytes）。 | 1684| description | string |是 | 待下载任务的描述信息。 | 1685| downloadedBytes | number | 是 |实时下载大小（int bytes）。 | 1686<!--no_check-->
