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