1# @ohos.request (上传下载) 2 3request部件主要给应用提供上传下载文件、后台传输代理的基础能力。 4 5> **说明：** 6> 7> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10## 导入模块 11 12 13```js 14import request from '@ohos.request'; 15``` 16 17## 常量 18 19**需要权限**：ohos.permission.INTERNET 20 21**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。 22 23### 网络类型 24下载支持自定义网络类型，可以在[DownloadConfig](#downloadconfig)中通过networkType配置成以下网络类型。 25 26| 名称 | 参数类型 | 数值 | 说明 | 27| -------- | -------- | -------- | -------- | 28| NETWORK_MOBILE | number | 0x00000001 | 使用蜂窝网络时允许下载的位标志。 | 29| NETWORK_WIFI | number | 0x00010000 | 使用WLAN时允许下载的位标志。 | 30 31### 下载任务的错误码 32下载[on('fail')<sup>7+</sup>](#onfail7)事件callback的错误参数、[getTaskInfo<sup>9+</sup>](#gettaskinfo9)返回值的failedReason字段取值。 33 34| 名称 | 参数类型 | 数值 | 说明 | 35| -------- | -------- | -------- | -------- | 36| ERROR_CANNOT_RESUME<sup>7+</sup> | number | 0 | 网络原因导致恢复下载失败。 | 37| ERROR_DEVICE_NOT_FOUND<sup>7+</sup> | number | 1 | 找不到SD卡等存储设备。 | 38| ERROR_FILE_ALREADY_EXISTS<sup>7+</sup> | number | 2 | 要下载的文件已存在，下载会话不能覆盖现有文件。 | 39| ERROR_FILE_ERROR<sup>7+</sup> | number | 3 | 文件操作失败。 | 40| ERROR_HTTP_DATA_ERROR<sup>7+</sup> | number | 4 | HTTP传输失败。 | 41| ERROR_INSUFFICIENT_SPACE<sup>7+</sup> | number | 5 | 存储空间不足。 | 42| ERROR_TOO_MANY_REDIRECTS<sup>7+</sup> | number | 6 | 网络重定向过多导致的错误。 | 43| ERROR_UNHANDLED_HTTP_CODE<sup>7+</sup> | number | 7 | 无法识别的HTTP代码。 | 44| ERROR_UNKNOWN<sup>7+</sup> | number | 8 | 未知错误。 | 45| ERROR_OFFLINE<sup>9+</sup> | number | 9 | 网络未连接。 | 46| ERROR_UNSUPPORTED_NETWORK_TYPE<sup>9+</sup> | number | 10 | 网络类型不匹配。 | 47 48 49### 下载任务暂停原因 50下载相关[getTaskInfo<sup>9+</sup>](#gettaskinfo9)返回值的pausedReason字段取值。 51 52| 名称 | 参数类型 | 数值 | 说明 | 53| -------- | -------- | -------- | -------- | 54| PAUSED_QUEUED_FOR_WIFI<sup>7+</sup> | number | 0 | 下载被暂停并等待WLAN连接，因为文件大小超过了使用蜂窝网络的会话允许的最大值。 | 55| PAUSED_WAITING_FOR_NETWORK<sup>7+</sup> | number | 1 | 由于网络问题（例如网络断开）而暂停下载。 | 56| PAUSED_WAITING_TO_RETRY<sup>7+</sup> | number | 2 | 发生网络错误，将重试下载会话。 | 57| PAUSED_BY_USER<sup>9+</sup> | number | 3 | 用户暂停会话。 | 58| PAUSED_UNKNOWN<sup>7+</sup> | number | 4 | 未知原因导致暂停下载。 | 59 60### 下载任务状态码 61下载相关[getTaskInfo<sup>9+</sup>](#gettaskinfo9)返回值的status字段取值。 62 63| 名称 | 参数类型 | 数值 | 说明 | 64| -------- | -------- | -------- | -------- | 65| SESSION_SUCCESSFUL<sup>7+</sup> | number | 0 | 下载会话已完成。 | 66| SESSION_RUNNING<sup>7+</sup> | number | 1 | 下载会话正在进行中。 | 67| SESSION_PENDING<sup>7+</sup> | number | 2 | 正在调度下载会话。 | 68| SESSION_PAUSED<sup>7+</sup> | number | 3 | 下载会话已暂停。 | 69| SESSION_FAILED<sup>7+</sup> | number | 4 | 下载会话已失败，将不会重试。 | 70 71 72## request.uploadFile<sup>9+</sup> 73 74uploadFile(context: BaseContext, config: UploadConfig): Promise<UploadTask> 75 76上传，异步方法，使用promise形式返回结果。通过[on('complete'|'fail')<sup>9+</sup>](#oncomplete--fail9)可获取任务上传时的错误信息。 77 78**需要权限**：ohos.permission.INTERNET 79 80**系统能力**: SystemCapability.MiscServices.Upload 81 82**参数：** 83 84 | 参数名 | 类型 | 必填 | 说明 | 85 | -------- | -------- | -------- | -------- | 86 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 87 | config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 | 88 89 90**返回值：** 91 92 | 类型 | 说明 | 93 | -------- | -------- | 94 | Promise<[UploadTask](#uploadtask)> | 使用Promise方式，异步返回上传任务。 | 95 96**错误码：** 97 98以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 99 100 | 错误码ID | 错误信息 | 101 | -------- | -------- | 102 | 13400002 | bad file path. | 103 104**示例：** 105 106 ```ts 107 let uploadTask: request.UploadTask; 108 let uploadConfig: request.UploadConfig = { 109 url: 'http://www.example.com', //需要手动替换为真实服务器地址 110 header: { 'Accept': '*/*' }, 111 method: "POST", 112 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 113 data: [{ name: "name123", value: "123" }], 114 }; 115 try { 116 request.uploadFile(getContext(), uploadConfig).then((data: request.UploadTask) => { 117 uploadTask = data; 118 }).catch((err: BusinessError) => { 119 console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`); 120 }); 121 } catch (err) { 122 console.error(`Failed to request the upload. err: ${JSON.stringify(err)}`); 123 } 124 ``` 125 126> **说明：** 127> 128> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 129 130 131## request.uploadFile<sup>9+</sup> 132 133uploadFile(context: BaseContext, config: UploadConfig, callback: AsyncCallback<UploadTask>): void 134 135上传，异步方法，使用callback形式返回结果。通过[on('complete'|'fail')<sup>9+</sup>](#oncomplete--fail9)可获取任务上传时的错误信息。 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 151以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 152 153 | 错误码ID | 错误信息 | 154 | -------- | -------- | 155 | 13400002 | bad file path. | 156 157**示例：** 158 159 ```ts 160 let uploadTask: request.UploadTask; 161 let uploadConfig: request.UploadConfig = { 162 url: 'http://www.example.com', //需要手动替换为真实服务器地址 163 header: { 'Accept': '*/*' }, 164 method: "POST", 165 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 166 data: [{ name: "name123", value: "123" }], 167 }; 168 try { 169 request.uploadFile(getContext(), uploadConfig, (err: BusinessError, data: request.UploadTask) => { 170 if (err) { 171 console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`); 172 return; 173 } 174 uploadTask = data; 175 }); 176 } catch (err) { 177 console.error(`Failed to request the upload. err: ${JSON.stringify(err)}`); 178 } 179 ``` 180 181> **说明：** 182> 183> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 184 185## request.upload<sup>(deprecated)</sup> 186 187upload(config: UploadConfig): Promise<UploadTask> 188 189上传，异步方法，使用promise形式返回结果。 190 191**模型约束**：此接口仅可在FA模型下使用 192 193> **说明：** 194> 195> 从API Version 9开始不再维护，建议使用[request.uploadFile<sup>9+</sup>](#requestuploadfile9)替代。 196 197**需要权限**：ohos.permission.INTERNET 198 199**系统能力**: SystemCapability.MiscServices.Upload 200 201**参数：** 202 203 | 参数名 | 类型 | 必填 | 说明 | 204 | -------- | -------- | -------- | -------- | 205 | config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 | 206 207**返回值：** 208 209 | 类型 | 说明 | 210 | -------- | -------- | 211 | Promise<[UploadTask](#uploadtask)> | 使用Promise方式，异步返回上传任务。 | 212 213**示例：** 214 215 ```js 216 let uploadTask; 217 let uploadConfig = { 218 url: 'http://www.example.com', //需要手动替换为真实服务器地址 219 header: { 'Accept': '*/*' }, 220 method: "POST", 221 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 222 data: [{ name: "name123", value: "123" }], 223 }; 224 request.upload(uploadConfig).then((data) => { 225 uploadTask = data; 226 }).catch((err) => { 227 console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`); 228 }) 229 ``` 230 231 232## request.upload<sup>(deprecated)</sup> 233 234upload(config: UploadConfig, callback: AsyncCallback<UploadTask>): void 235 236上传，异步方法，使用callback形式返回结果。 237 238**模型约束**：此接口仅可在FA模型下使用 239 240> **说明：** 241> 242> 从API Version 9开始不再维护，建议使用[request.uploadFile<sup>9+</sup>](#requestuploadfile9-1)替代。 243 244**需要权限**：ohos.permission.INTERNET 245 246**系统能力**: SystemCapability.MiscServices.Upload 247 248**参数：** 249 250 | 参数名 | 类型 | 必填 | 说明 | 251 | -------- | -------- | -------- | -------- | 252 | config | [UploadConfig](#uploadconfig) | 是 | 上传的配置信息。 | 253 | callback | AsyncCallback<[UploadTask](#uploadtask)> | 是 | 回调函数，异步返回UploadTask对象。 | 254 255**示例：** 256 257 ```js 258 let uploadTask; 259 let uploadConfig = { 260 url: 'http://www.example.com', //需要手动替换为真实服务器地址 261 header: { 'Accept': '*/*' }, 262 method: "POST", 263 files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }], 264 data: [{ name: "name123", value: "123" }], 265 }; 266 request.upload(uploadConfig, (err, data) => { 267 if (err) { 268 console.error(`Failed to request the upload. Code: ${err.code}, message: ${err.message}`); 269 return; 270 } 271 uploadTask = data; 272 }); 273 ``` 274 275## UploadTask 276 277上传任务，使用下列方法前，需要先获取UploadTask对象，promise形式通过[request.uploadFile<sup>9+</sup>](#requestuploadfile9)获取，callback形式通过[request.uploadFile<sup>9+</sup>](#requestuploadfile9-1)获取。 278 279 280 281### on('progress') 282 283on(type: 'progress', callback:(uploadedSize: number, totalSize: number) => void): void 284 285订阅上传任务进度事件，异步方法，使用callback形式返回结果。 286 287> **说明：** 288> 289> 当应用处于后台时，为满足功耗性能要求，不支持调用此接口进行回调。 290 291**需要权限**：ohos.permission.INTERNET 292 293**系统能力**: SystemCapability.MiscServices.Upload 294 295**参数：** 296 297 | 参数名 | 类型 | 必填 | 说明 | 298 | -------- | -------- | -------- | -------- | 299 | type | string | 是 | 订阅的事件类型，取值为'progress'（上传的进度信息）。 | 300 | callback | function | 是 | 上传进度的回调函数。 | 301 302 回调函数的参数 303 304| 参数名 | 类型 | 必填 | 说明 | 305| -------- | -------- | -------- | -------- | 306| uploadedSize | number | 是 | 当前已上传文件大小，单位为B。 | 307| totalSize | number | 是 | 上传文件的总大小，单位为B。 | 308 309**示例：** 310 311 ```ts 312 let upProgressCallback = (uploadedSize: number, totalSize: number) => { 313 console.info("upload totalSize:" + totalSize + " uploadedSize:" + uploadedSize); 314 }; 315 uploadTask.on('progress', upProgressCallback); 316 ``` 317 318 319### on('headerReceive')<sup>7+</sup> 320 321on(type: 'headerReceive', callback: (header: object) => void): void 322 323订阅上传任务HTTP标头事件，异步方法，使用callback形式返回结果。 324 325**需要权限**：ohos.permission.INTERNET 326 327**系统能力**: SystemCapability.MiscServices.Upload 328 329**参数：** 330 331 | 参数名 | 类型 | 必填 | 说明 | 332 | -------- | -------- | -------- | -------- | 333 | type | string | 是 | 订阅的事件类型，取值为'headerReceive'（接收响应头）。 | 334 | callback | function | 是 | HTTP Response Header事件的回调函数。 | 335 336 回调函数的参数： 337 338| 参数名 | 类型 | 必填 | 说明 | 339| -------- | -------- | -------- | -------- | 340| header | object | 是 | HTTP Response Header。 | 341 342**示例：** 343 344 ```ts 345 let headerCallback = (headers: object) => { 346 console.info("upOnHeader headers:" + JSON.stringify(headers)); 347 }; 348 uploadTask.on('headerReceive', headerCallback); 349 ``` 350 351 352### on('complete' | 'fail')<sup>9+</sup> 353 354 on(type:'complete' | 'fail', callback: Callback<Array<TaskState>>): void; 355 356订阅上传任务完成或失败事件，异步方法，使用callback形式返回结果。 357 358**需要权限**：ohos.permission.INTERNET 359 360**系统能力**: SystemCapability.MiscServices.Upload 361 362**参数：** 363 364 | 参数名 | 类型 | 必填 | 说明 | 365 | -------- | -------- | -------- | -------- | 366 | type | string | 是 | 订阅的事件类型，取值为'complete'，表示上传任务完成；取值为'fail'，表示上传任务失败。| 367 | callback | Callback<Array<TaskState>> | 是 | 上传任务完成或失败的回调函数。 | 368 369 回调函数的参数 370 371| 参数名 | 类型 | 必填 | 说明 | 372| -------- | -------- | -------- | -------- | 373| taskstates | Array<[TaskState](#taskstate9)> | 是 | 上传任务返回结果 | 374 375**示例：** 376 377 ```ts 378 let upCompleteCallback = (taskStates: Array<request.TaskState>) => { 379 for (let i = 0; i < taskStates.length; i++) { 380 console.info("upOnComplete taskState:" + JSON.stringify(taskStates[i])); 381 } 382 }; 383 uploadTask.on('complete', upCompleteCallback); 384 385 let upFailCallback = (taskStates: Array<request.TaskState>) => { 386 for (let i = 0; i < taskStates.length; i++) { 387 console.info("upOnFail taskState:" + JSON.stringify(taskStates[i])); 388 } 389 }; 390 uploadTask.on('fail', upFailCallback); 391 ``` 392 393 394### off('progress') 395 396off(type: 'progress', callback?: (uploadedSize: number, totalSize: number) => void): void 397 398取消订阅上传任务进度事件。 399 400**需要权限**：ohos.permission.INTERNET 401 402**系统能力**: SystemCapability.MiscServices.Upload 403 404**参数：** 405 406 | 参数名 | 类型 | 必填 | 说明 | 407 | -------- | -------- | -------- | -------- | 408 | type | string | 是 | 取消订阅的事件类型，取值为'progress'（上传的进度信息）。 | 409 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。<br/>uploadedSize：当前已上传文件的大小，单位为B。<br/>totalSize：上传文件的总大小，单位为B。 | 410 411**示例：** 412 413 ```ts 414 let upProgressCallback1 = (uploadedSize: number, totalSize: number) => { 415 console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize); 416 }; 417 let upProgressCallback2 = (uploadedSize: number, totalSize: number) => { 418 console.info('Upload delete progress notification.' + 'totalSize:' + totalSize + 'uploadedSize:' + uploadedSize); 419 }; 420 uploadTask.on('progress', upProgressCallback1); 421 uploadTask.on('progress', upProgressCallback2); 422 //表示取消upProgressCallback1的订阅 423 uploadTask.off('progress', upProgressCallback1); 424 //表示取消订阅上传任务进度事件的所有回调 425 uploadTask.off('progress'); 426 ``` 427 428 429### off('headerReceive')<sup>7+</sup> 430 431off(type: 'headerReceive', callback?: (header: object) => void): void 432 433取消订阅上传任务HTTP标头事件。 434 435**需要权限**：ohos.permission.INTERNET 436 437**系统能力**: SystemCapability.MiscServices.Upload 438 439**参数：** 440 441 | 参数名 | 类型 | 必填 | 说明 | 442 | -------- | -------- | -------- | -------- | 443 | type | string | 是 | 取消订阅的事件类型，取值为'headerReceive'（接收响应头）。 | 444 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。<br/>header：HTTP Response Header。 | 445 446**示例：** 447 448 ```ts 449 let headerCallback1 = (header: object) => { 450 console.info(`Upload delete headerReceive notification. header: ${JSON.stringify(header)}`); 451 }; 452 let headerCallback2 = (header: object) => { 453 console.info(`Upload delete headerReceive notification. header: ${JSON.stringify(header)}`); 454 }; 455 uploadTask.on('headerReceive', headerCallback1); 456 uploadTask.on('headerReceive', headerCallback2); 457 //表示取消headerCallback1的订阅 458 uploadTask.off('headerReceive', headerCallback1); 459 //表示取消订阅上传任务HTTP标头事件的所有回调 460 uploadTask.off('headerReceive'); 461 ``` 462 463### off('complete' | 'fail')<sup>9+</sup> 464 465 off(type:'complete' | 'fail', callback?: Callback<Array<TaskState>>): void; 466 467取消订阅上传任务完成或失败事件。 468 469**需要权限**：ohos.permission.INTERNET 470 471**系统能力**: SystemCapability.MiscServices.Upload 472 473**参数：** 474 475 | 参数名 | 类型 | 必填 | 说明 | 476 | -------- | -------- | -------- | -------- | 477 | type | string | 是 | 订阅的事件类型，取值为'complete'，表示上传任务完成；取值为'fail'，表示上传任务失败。| 478 | callback | Callback<Array<TaskState>> | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 479 480**示例：** 481 482 ```ts 483 let upCompleteCallback1 = (taskStates: Array<request.TaskState>) => { 484 console.info('Upload delete complete notification.'); 485 for (let i = 0; i < taskStates.length; i++) { 486 console.info('taskState:' + JSON.stringify(taskStates[i])); 487 } 488 }; 489 let upCompleteCallback2 = (taskStates: Array<request.TaskState>) => { 490 console.info('Upload delete complete notification.'); 491 for (let i = 0; i < taskStates.length; i++) { 492 console.info('taskState:' + JSON.stringify(taskStates[i])); 493 } 494 }; 495 uploadTask.on('complete', upCompleteCallback1); 496 uploadTask.on('complete', upCompleteCallback2); 497 //表示取消headerCallback1的订阅 498 uploadTask.off('complete', upCompleteCallback1); 499 //表示取消订阅上传任务完成的所有回调 500 uploadTask.off('complete'); 501 502 let upFailCallback1 = (taskStates: Array<request.TaskState>) => { 503 console.info('Upload delete fail notification.'); 504 for (let i = 0; i < taskStates.length; i++) { 505 console.info('taskState:' + JSON.stringify(taskStates[i])); 506 } 507 }; 508 let upFailCallback2 = (taskStates: Array<request.TaskState>) => { 509 console.info('Upload delete fail notification.'); 510 for (let i = 0; i < taskStates.length; i++) { 511 console.info('taskState:' + JSON.stringify(taskStates[i])); 512 } 513 }; 514 uploadTask.on('fail', upFailCallback1); 515 uploadTask.on('fail', upFailCallback2); 516 //表示取消headerCallback1的订阅 517 uploadTask.off('fail', upFailCallback1); 518 //表示取消订阅上传任务失败的所有回调 519 uploadTask.off('fail'); 520 ``` 521 522### delete<sup>9+</sup> 523delete(): Promise<boolean> 524 525移除上传的任务，异步方法，使用promise形式返回结果。 526 527**需要权限**：ohos.permission.INTERNET 528 529**系统能力**: SystemCapability.MiscServices.Upload 530 531**返回值：** 532 533 | 类型 | 说明 | 534 | -------- | -------- | 535 | Promise<boolean> | 使用Promise方式，异步返回移除任务是否成功。true：成功，false：不成功。 | 536 537**示例：** 538 539 ```ts 540 uploadTask.delete().then((result: boolean) => { 541 console.info('Succeeded in deleting the upload task.'); 542 }).catch((err: BusinessError) => { 543 console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`); 544 }); 545 ``` 546 547 548### delete<sup>9+</sup> 549 550delete(callback: AsyncCallback<boolean>): void 551 552移除上传的任务，异步方法，使用callback形式返回结果。 553 554**需要权限**：ohos.permission.INTERNET 555 556**系统能力**: SystemCapability.MiscServices.Upload 557 558**参数：** 559 560 | 参数名 | 类型 | 必填 | 说明 | 561 | -------- | -------- | -------- | -------- | 562 | callback | AsyncCallback<boolean> | 是 | 回调函数，异步返回移除任务是否成功。true：成功，false：不成功。 | 563 564**示例：** 565 566 ```ts 567 uploadTask.delete((err: BusinessError, result: boolean) => { 568 if (err) { 569 console.error(`Failed to delete the upload task. Code: ${err.code}, message: ${err.message}`); 570 return; 571 } 572 console.info('Succeeded in deleting the upload task.'); 573 }); 574 ``` 575 576 577### remove<sup>(deprecated)</sup> 578 579remove(): Promise<boolean> 580 581移除上传的任务，异步方法，使用promise形式返回结果。 582 583> **说明：** 584> 585> 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9)替代。 586 587**需要权限**：ohos.permission.INTERNET 588 589**系统能力**: SystemCapability.MiscServices.Upload 590 591**返回值：** 592 593 | 类型 | 说明 | 594 | -------- | -------- | 595 | Promise<boolean> | 使用Promise方式，异步返回移除任务是否成功。true：成功，false：不成功。 | 596 597**示例：** 598 599 ```js 600 uploadTask.remove().then((result) => { 601 console.info('Succeeded in removing the upload task.'); 602 }).catch((err) => { 603 console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`); 604 }); 605 ``` 606 607 608### remove<sup>(deprecated)</sup> 609 610remove(callback: AsyncCallback<boolean>): void 611 612移除上传的任务，异步方法，使用callback形式返回结果。 613 614> **说明：** 615> 616> 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9-1)替代。 617 618**需要权限**：ohos.permission.INTERNET 619 620**系统能力**: SystemCapability.MiscServices.Upload 621 622**参数：** 623 624 | 参数名 | 类型 | 必填 | 说明 | 625 | -------- | -------- | -------- | -------- | 626 | callback | AsyncCallback<boolean> | 是 | 回调函数，异步返回移除任务是否成功。true：成功，false：不成功。 | 627 628**示例：** 629 630 ```js 631 uploadTask.remove((err, result) => { 632 if (err) { 633 console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`); 634 return; 635 } 636 if (result) { 637 console.info('Succeeded in removing the upload task.'); 638 } else { 639 console.error(`Failed to remove the upload task. Code: ${err.code}, message: ${err.message}`); 640 } 641 }); 642 ``` 643 644## UploadConfig 645上传任务的配置信息。 646 647**需要权限**：ohos.permission.INTERNET 648 649**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。 650 651| 名称 | 类型 | 必填 | 说明 | 652| -------- | -------- | -------- | -------- | 653| url | string | 是 | 资源地址。 | 654| header | Object | 是 | 添加要包含在上传请求中的HTTP或HTTPS标志头。 | 655| method | string | 是 | 请求方法：POST、PUT。缺省为POST。 | 656| files | Array<[File](#file)> | 是 | 要上传的文件列表。请使用 multipart/form-data提交。 | 657| data | Array<[RequestData](#requestdata)> | 是 | 请求的表单数据。 | 658 659## TaskState<sup>9+</sup> 660上传任务信息，[on('complete' | 'fail')<sup>9+</sup>](#oncomplete--fail9)和[off('complete' | 'fail')<sup>9+</sup>](#offcomplete--fail9)接口的回调参数。 661 662**需要权限**：ohos.permission.INTERNET 663 664**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。 665 666| 名称 | 类型 | 必填 | 说明 | 667| -------- | -------- | -------- | -------- | 668| path | string | 是 | 文件路径 | 669| responseCode | number | 是 | 上传任务返回值，0表示任务成功，其它返回码为失败，具体请查看message上传任务结果描述信息 | 670| message | string | 是 | 上传任务结果描述信息 | 671 672## File 673[UploadConfig](#uploadconfig)中的文件列表。 674 675**需要权限**：ohos.permission.INTERNET 676 677**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。 678 679| 名称 | 类型 | 必填 | 说明 | 680| -------- | -------- | -------- | -------- | 681| filename | string | 是 | multipart提交时，请求头中的文件名。 | 682| name | string | 是 | multipart提交时，表单项目的名称，缺省为file。 | 683| uri | string | 是 | 文件的本地存储路径。<br/>仅支持"internal"协议类型，"internal://cache/"为必填字段，示例：<br/>internal://cache/path/to/file.txt | 684| type | string | 是 | 文件的内容类型，默认根据文件名或路径的后缀获取。 | 685 686 687## RequestData 688[UploadConfig](#uploadconfig)中的表单数据。 689 690**需要权限**：ohos.permission.INTERNET 691 692**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。 693 694| 名称 | 类型 | 必填 | 说明 | 695| -------- | -------- | -------- | -------- | 696| name | string | 是 | 表示表单元素的名称。 | 697| value | string | 是 | 表示表单元素的值。 | 698 699## request.downloadFile<sup>9+</sup> 700 701downloadFile(context: BaseContext, config: DownloadConfig): Promise<DownloadTask> 702 703下载，异步方法，使用promise形式返回结果。通过[on('complete'|'pause'|'remove')<sup>7+</sup>](#oncompletepauseremove7)可获取任务下载时的状态信息，包括任务完成、暂停或移除。通过[on('fail')<sup>7+</sup>](#onfail7)可获取任务下载时的错误信息。 704 705 706**需要权限**：ohos.permission.INTERNET 707 708**系统能力**: SystemCapability.MiscServices.Download 709 710**参数：** 711 712 | 参数名 | 类型 | 必填 | 说明 | 713 | -------- | -------- | -------- | -------- | 714 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 715 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 716 717**返回值：** 718 719 | 类型 | 说明 | 720 | -------- | -------- | 721 | Promise<[DownloadTask](#downloadtask)> | 使用Promise方式，异步返回返回下载任务。 | 722 723**错误码：** 724 725以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 726 727 | 错误码ID | 错误信息 | 728 | -------- | -------- | 729 | 13400001 | file operation error. | 730 | 13400002 | bad file path. | 731 | 13400003 | task service ability error. | 732 733**示例：** 734 735 ```ts 736 let downloadTask: request.DownloadTask; 737 try { 738 request.downloadFile(getContext(), { url: 'https://xxxx/xxxx.hap' }).then((data: request.DownloadTask) => { 739 downloadTask = data; 740 }).catch((err: BusinessError) => { 741 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 742 }) 743 } catch (err) { 744 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 745 } 746 ``` 747 748> **说明：** 749> 750> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 751 752 753## request.downloadFile<sup>9+</sup> 754 755downloadFile(context: BaseContext, config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void; 756 757下载，异步方法，使用callback形式返回结果。通过[on('complete'|'pause'|'remove')<sup>7+</sup>](#oncompletepauseremove7)可获取任务下载时的状态信息，包括任务完成、暂停或移除。通过[on('fail')<sup>7+</sup>](#onfail7)可获取任务下载时的错误信息。 758 759 760**需要权限**：ohos.permission.INTERNET 761 762**系统能力**: SystemCapability.MiscServices.Download 763 764**参数：** 765 766 | 参数名 | 类型 | 必填 | 说明 | 767 | -------- | -------- | -------- | -------- | 768 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 769 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 770 | callback | AsyncCallback<[DownloadTask](#downloadtask)> | 是 | 回调函数，异步返回下载任务。 | 771 772**错误码：** 773 774以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 775 776 | 错误码ID | 错误信息 | 777 | -------- | -------- | 778 | 13400001 | file operation error. | 779 | 13400002 | bad file path. | 780 | 13400003 | task service ability error. | 781 782**示例：** 783 784 ```ts 785 let downloadTask: request.DownloadTask; 786 try { 787 request.downloadFile(getContext(), { 788 url: 'https://xxxx/xxxxx.hap', 789 filePath: 'xxx/xxxxx.hap' 790 }, (err: BusinessError, data: request.DownloadTask) => { 791 if (err) { 792 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 793 return; 794 } 795 downloadTask = data; 796 }); 797 } catch (err) { 798 console.error(`Failed to request the download. err: ${JSON.stringify(err)}`); 799 } 800 ``` 801 802> **说明：** 803> 804> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 805 806## request.download<sup>(deprecated)</sup> 807 808download(config: DownloadConfig): Promise<DownloadTask> 809 810下载，异步方法，使用promise形式返回结果。 811 812> **说明：** 813> 814> 从API Version 9开始不再维护，建议使用[request.downloadFile<sup>9+</sup>](#requestdownloadfile9)替代。 815 816**模型约束**：此接口仅可在FA模型下使用 817 818**需要权限**：ohos.permission.INTERNET 819 820**系统能力**: SystemCapability.MiscServices.Download 821 822**参数：** 823 824 | 参数名 | 类型 | 必填 | 说明 | 825 | -------- | -------- | -------- | -------- | 826 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 827 828**返回值：** 829 830 | 类型 | 说明 | 831 | -------- | -------- | 832 | Promise<[DownloadTask](#downloadtask)> | 使用Promise方式，异步返回返回下载任务。 | 833 834**示例：** 835 836 ```js 837 let downloadTask; 838 request.download({ url: 'https://xxxx/xxxx.hap' }).then((data) => { 839 downloadTask = data; 840 }).catch((err) => { 841 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 842 }) 843 ``` 844 845 846## request.download<sup>(deprecated)</sup> 847 848download(config: DownloadConfig, callback: AsyncCallback<DownloadTask>): void 849 850下载，异步方法，使用callback形式返回结果。 851 852> **说明：** 853> 854> 从API Version 9开始不再维护，建议使用[request.downloadFile<sup>9+</sup>](#requestdownloadfile9-1)替代。 855 856**模型约束**：此接口仅可在FA模型下使用 857 858**需要权限**：ohos.permission.INTERNET 859 860**系统能力**: SystemCapability.MiscServices.Download 861 862**参数：** 863 864 | 参数名 | 类型 | 必填 | 说明 | 865 | -------- | -------- | -------- | -------- | 866 | config | [DownloadConfig](#downloadconfig) | 是 | 下载的配置信息。 | 867 | callback | AsyncCallback<[DownloadTask](#downloadtask)> | 是 | 回调函数，异步返回下载任务。 | 868 869**示例：** 870 871 ```js 872 let downloadTask; 873 request.download({ url: 'https://xxxx/xxxxx.hap', 874 filePath: 'xxx/xxxxx.hap'}, (err, data) => { 875 if (err) { 876 console.error(`Failed to request the download. Code: ${err.code}, message: ${err.message}`); 877 return; 878 } 879 downloadTask = data; 880 }); 881 ``` 882 883## DownloadTask 884 885下载任务，使用下列方法前，需要先获取DownloadTask对象，promise形式通过[request.downloadFile<sup>9+</sup>](#requestdownloadfile9)获取，callback形式通过[request.downloadFile<sup>9+</sup>](#requestdownloadfile9-1)获取。 886 887 888### on('progress') 889 890on(type: 'progress', callback:(receivedSize: number, totalSize: number) => void): void 891 892订阅下载任务进度事件，异步方法，使用callback形式返回结果。 893 894> **说明：** 895> 896> 当应用处于后台时，为满足功耗性能要求，不支持调用此接口进行回调。 897 898**需要权限**：ohos.permission.INTERNET 899 900**系统能力**: SystemCapability.MiscServices.Download 901 902**参数：** 903 904 | 参数名 | 类型 | 必填 | 说明 | 905 | -------- | -------- | -------- | -------- | 906 | type | string | 是 | 订阅的事件类型，取值为'progress'（下载的进度信息）。 | 907 | callback | function | 是 | 下载任务进度的回调函数。 | 908 909 回调函数的参数： 910 911| 参数名 | 类型 | 必填 | 说明 | 912| -------- | -------- | -------- | -------- | 913| receivedSize | number | 是 | 当前下载的进度，单位为B。 | 914| totalSize | number | 是 | 下载文件的总大小，单位为B。 | 915 916**示例：** 917 918 ```ts 919 let progressCallback = (receivedSize: number, totalSize: number) => { 920 console.info("download receivedSize:" + receivedSize + " totalSize:" + totalSize); 921 }; 922 downloadTask.on('progress', progressCallback); 923 ``` 924 925 926### off('progress') 927 928off(type: 'progress', callback?: (receivedSize: number, totalSize: number) => void): void 929 930取消订阅下载任务进度事件。 931 932**需要权限**：ohos.permission.INTERNET 933 934**系统能力**: SystemCapability.MiscServices.Download 935 936**参数：** 937 938 | 参数名 | 类型 | 必填 | 说明 | 939 | -------- | -------- | -------- | -------- | 940 | type | string | 是 | 取消订阅的事件类型，取值为'progress'（下载的进度信息）。 | 941 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 <br/>receivedSize：当前下载任务的进度；<br/>totalSize：下载文件的总大小。 | 942 943**示例：** 944 945 ```ts 946 let progressCallback1 = (receivedSize: number, totalSize: number) => { 947 console.info('Download delete progress notification.' + 'receivedSize:' + receivedSize + 'totalSize:' + totalSize); 948 }; 949 let progressCallback2 = (receivedSize: number, totalSize: number) => { 950 console.info('Download delete progress notification.' + 'receivedSize:' + receivedSize + 'totalSize:' + totalSize); 951 }; 952 downloadTask.on('progress', progressCallback1); 953 downloadTask.on('progress', progressCallback2); 954 //表示取消progressCallback1的订阅 955 downloadTask.off('progress', progressCallback1); 956 //表示取消订阅下载任务进度事件的所有回调 957 downloadTask.off('progress'); 958 ``` 959 960 961### on('complete'|'pause'|'remove')<sup>7+</sup> 962 963on(type: 'complete'|'pause'|'remove', callback:() => void): void 964 965订阅下载任务相关的事件，异步方法，使用callback形式返回。 966 967**需要权限**：ohos.permission.INTERNET 968 969**系统能力**: SystemCapability.MiscServices.Download 970 971**参数：** 972 973 | 参数名 | 类型 | 必填 | 说明 | 974 | -------- | -------- | -------- | -------- | 975 | type | string | 是 | 订阅的事件类型。<br>- 取值为'complete'，表示下载任务完成；<br/>- 取值为'pause'，表示下载任务暂停；<br/>- 取值为'remove'，表示下载任务移除。 | 976 | callback | function | 是 | 下载任务相关的回调函数。| 977 978**示例：** 979 980 ```ts 981 let completeCallback = () => { 982 console.info('Download task completed.'); 983 }; 984 downloadTask.on('complete', completeCallback); 985 986 let pauseCallback = () => { 987 console.info('Download task pause.'); 988 }; 989 downloadTask.on('pause', pauseCallback); 990 991 let removeCallback = () => { 992 console.info('Download task remove.'); 993 }; 994 downloadTask.on('remove', removeCallback); 995 ``` 996 997 998### off('complete'|'pause'|'remove')<sup>7+</sup> 999 1000off(type: 'complete'|'pause'|'remove', callback?:() => void): void 1001 1002取消订阅下载任务相关的事件。 1003 1004**需要权限**：ohos.permission.INTERNET 1005 1006**系统能力**: SystemCapability.MiscServices.Download 1007 1008**参数：** 1009 1010 | 参数名 | 类型 | 必填 | 说明 | 1011 | -------- | -------- | -------- | -------- | 1012 | type | string | 是 | 取消订阅的事件类型。<br/>- 取值为'complete'，表示下载任务完成；<br/>- 取值为'pause'，表示下载任务暂停；<br/>- 取值为'remove'，表示下载任务移除。 | 1013 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。。 | 1014 1015**示例：** 1016 1017 ```ts 1018 let completeCallback1 = () => { 1019 console.info('Download delete complete notification.'); 1020 }; 1021 let completeCallback2 = () => { 1022 console.info('Download delete complete notification.'); 1023 }; 1024 downloadTask.on('complete', completeCallback1); 1025 downloadTask.on('complete', completeCallback2); 1026 //表示取消completeCallback1的订阅 1027 downloadTask.off('complete', completeCallback1); 1028 //表示取消订阅下载任务完成的所有回调 1029 downloadTask.off('complete'); 1030 1031 let pauseCallback1 = () => { 1032 console.info('Download delete pause notification.'); 1033 }; 1034 let pauseCallback2 = () => { 1035 console.info('Download delete pause notification.'); 1036 }; 1037 downloadTask.on('pause', pauseCallback1); 1038 downloadTask.on('pause', pauseCallback2); 1039 //表示取消pauseCallback1的订阅 1040 downloadTask.off('pause', pauseCallback1); 1041 //表示取消订阅下载任务暂停的所有回调 1042 downloadTask.off('pause'); 1043 1044 let removeCallback1 = () => { 1045 console.info('Download delete remove notification.'); 1046 }; 1047 let removeCallback2 = () => { 1048 console.info('Download delete remove notification.'); 1049 }; 1050 downloadTask.on('remove', removeCallback1); 1051 downloadTask.on('remove', removeCallback2); 1052 //表示取消removeCallback1的订阅 1053 downloadTask.off('remove', removeCallback1); 1054 //表示取消订阅下载任务移除的所有回调 1055 downloadTask.off('remove'); 1056 ``` 1057 1058 1059### on('fail')<sup>7+</sup> 1060 1061on(type: 'fail', callback: (err: number) => void): void 1062 1063订阅下载任务失败事件，异步方法，使用callback形式返回结果。 1064 1065**需要权限**：ohos.permission.INTERNET 1066 1067**系统能力**: SystemCapability.MiscServices.Download 1068 1069**参数：** 1070 1071 | 参数名 | 类型 | 必填 | 说明 | 1072 | -------- | -------- | -------- | -------- | 1073 | type | string | 是 | 订阅的事件类型，取值为'fail'（下载失败）。 | 1074 | callback | function | 是 | 下载失败的回调函数。 | 1075 1076 回调函数的参数： 1077 1078| 参数名 | 类型 | 必填 | 说明 | 1079| -------- | -------- | -------- | -------- | 1080| err | number | 是 | 下载失败的错误码，错误原因见[下载任务的错误码](#下载任务的错误码)。 | 1081 1082**示例：** 1083 1084 ```ts 1085 let failCallback = (err: number) => { 1086 console.error(`Failed to download the task. Code: ${err}`); 1087 }; 1088 downloadTask.on('fail', failCallback); 1089 ``` 1090 1091 1092### off('fail')<sup>7+</sup> 1093 1094off(type: 'fail', callback?: (err: number) => void): void 1095 1096取消订阅下载任务失败事件。 1097 1098**需要权限**：ohos.permission.INTERNET 1099 1100**系统能力**: SystemCapability.MiscServices.Download 1101 1102**参数：** 1103 1104 | 参数名 | 类型 | 必填 | 说明 | 1105 | -------- | -------- | -------- | -------- | 1106 | type | string | 是 | 取消订阅的事件类型，取值为'fail'（下载失败）。 | 1107 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。<br/>err：下载失败的错误码。 | 1108 1109**示例：** 1110 1111 ```ts 1112 let failCallback1 = (err: number) => { 1113 console.error(`Failed to download the task. Code: ${err}`); 1114 }; 1115 let failCallback2 = (err: number) => { 1116 console.error(`Failed to download the task. Code: ${err}`); 1117 }; 1118 downloadTask.on('fail', failCallback1); 1119 downloadTask.on('fail', failCallback2); 1120 //表示取消failCallback1的订阅 1121 downloadTask.off('fail', failCallback1); 1122 //表示取消订阅下载任务失败的所有回调 1123 downloadTask.off('fail'); 1124 ``` 1125 1126### delete<sup>9+</sup> 1127 1128delete(): Promise<boolean> 1129 1130移除下载的任务，异步方法，使用promise形式返回结果。 1131 1132**需要权限**：ohos.permission.INTERNET 1133 1134**系统能力**: SystemCapability.MiscServices.Download 1135 1136**返回值：** 1137 1138 | 类型 | 说明 | 1139 | -------- | -------- | 1140 | Promise<boolean> | 使用promise方式，异步返回移除任务是否成功。true：成功，false：不成功。 | 1141 1142**示例：** 1143 1144 ```ts 1145 downloadTask.delete().then((result: boolean) => { 1146 console.info('Succeeded in removing the download task.'); 1147 }).catch((err: BusinessError) => { 1148 console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); 1149 }); 1150 ``` 1151 1152 1153### delete<sup>9+</sup> 1154 1155delete(callback: AsyncCallback<boolean>): void 1156 1157移除下载的任务，异步方法，使用callback形式返回结果。 1158 1159**需要权限**：ohos.permission.INTERNET 1160 1161**系统能力**: SystemCapability.MiscServices.Download 1162 1163**参数：** 1164 1165 | 参数名 | 类型 | 必填 | 说明 | 1166 | -------- | -------- | -------- | -------- | 1167 | callback | AsyncCallback<boolean> | 是 | 回调函数，异步返回移除任务是否成功。true：成功，false：不成功。 | 1168 1169**示例：** 1170 1171 ```ts 1172 downloadTask.delete((err: BusinessError, result: boolean) => { 1173 if (err) { 1174 console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); 1175 return; 1176 } 1177 console.info('Succeeded in removing the download task.'); 1178 }); 1179 ``` 1180 1181 1182### getTaskInfo<sup>9+</sup> 1183 1184getTaskInfo(): Promise<DownloadInfo> 1185 1186查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。 1187 1188**需要权限**：ohos.permission.INTERNET 1189 1190**系统能力**: SystemCapability.MiscServices.Download 1191 1192**返回值：** 1193 1194 | 类型 | 说明 | 1195 | -------- | -------- | 1196 | Promise<[DownloadInfo](#downloadinfo7)> | 使用promise方式，异步返回下载任务信息。 | 1197 1198**示例：** 1199 1200 ```ts 1201 downloadTask.getTaskInfo().then((downloadInfo: request.DownloadInfo) => { 1202 console.info('Succeeded in querying the download task') 1203 }).catch((err: BusinessError) => { 1204 console.error(`Failed to query the download task. Code: ${err.code}, message: ${err.message}`) 1205 }); 1206 ``` 1207 1208 1209### getTaskInfo<sup>9+</sup> 1210 1211getTaskInfo(callback: AsyncCallback<DownloadInfo>): void 1212 1213查询下载的任务，异步方法，使用callback形式返回结果。 1214 1215**需要权限**：ohos.permission.INTERNET 1216 1217**系统能力**: SystemCapability.MiscServices.Download 1218 1219**参数：** 1220 1221 | 参数名 | 类型 | 必填 | 说明 | 1222 | -------- | -------- | -------- | -------- | 1223 | callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | 是 | 回调函数，异步返回下载任务信息。 | 1224 1225**示例：** 1226 1227 ```ts 1228 downloadTask.getTaskInfo((err: BusinessError, downloadInfo: request.DownloadInfo) => { 1229 if (err) { 1230 console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`); 1231 } else { 1232 console.info('Succeeded in querying the download mimeType'); 1233 } 1234 }); 1235 ``` 1236 1237 1238### getTaskMimeType<sup>9+</sup> 1239 1240getTaskMimeType(): Promise<string> 1241 1242查询下载的任务的 MimeType，异步方法，使用promise形式返回结果。 1243 1244**需要权限**：ohos.permission.INTERNET 1245 1246**系统能力**: SystemCapability.MiscServices.Download 1247 1248**返回值：** 1249 1250 | 类型 | 说明 | 1251 | -------- | -------- | 1252 | Promise<string> | 使用promise方式，异步返回下载任务的MimeType。 | 1253 1254**示例：** 1255 1256 ```ts 1257 downloadTask.getTaskMimeType().then((data: string) => { 1258 console.info('Succeeded in querying the download MimeType'); 1259 }).catch((err: BusinessError) => { 1260 console.error(`Failed to query the download MimeType. Code: ${err.code}, message: ${err.message}`) 1261 }); 1262 ``` 1263 1264 1265### getTaskMimeType<sup>9+</sup> 1266 1267getTaskMimeType(callback: AsyncCallback<string>): void; 1268 1269查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。 1270 1271**需要权限**：ohos.permission.INTERNET 1272 1273**系统能力**: SystemCapability.MiscServices.Download 1274 1275**参数：** 1276 1277 | 参数名 | 类型 | 必填 | 说明 | 1278 | -------- | -------- | -------- | -------- | 1279 | callback | AsyncCallback<string> | 是 | 回调函数，异步返回下载任务的MimeType。 | 1280 1281**示例：** 1282 1283 ```ts 1284 downloadTask.getTaskMimeType((err: BusinessError, data: string) => { 1285 if (err) { 1286 console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`); 1287 } else { 1288 console.info('Succeeded in querying the download mimeType'); 1289 } 1290 }); 1291 ``` 1292 1293 1294### suspend<sup>9+</sup> 1295 1296suspend(): Promise<boolean> 1297 1298暂停下载任务，异步方法，使用promise形式返回结果。 1299 1300**需要权限**：ohos.permission.INTERNET 1301 1302**系统能力**: SystemCapability.MiscServices.Download 1303 1304**返回值：** 1305 1306 | 类型 | 说明 | 1307 | -------- | -------- | 1308 | Promise<boolean> | 使用promise方式，异步返回暂停下载任务是否成功。 | 1309 1310**示例：** 1311 1312 ```ts 1313 downloadTask.suspend().then((result: boolean) => { 1314 console.info('Succeeded in pausing the download task.'); 1315 }).catch((err: BusinessError) => { 1316 console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); 1317 }); 1318 ``` 1319 1320 1321### suspend<sup>9+</sup> 1322 1323suspend(callback: AsyncCallback<boolean>): void 1324 1325暂停下载任务，异步方法，使用callback形式返回结果。 1326 1327**需要权限**：ohos.permission.INTERNET 1328 1329**系统能力**: SystemCapability.MiscServices.Download 1330 1331**参数：** 1332 1333 | 参数名 | 类型 | 必填 | 说明 | 1334 | -------- | -------- | -------- | -------- | 1335 | callback | AsyncCallback<boolean> | 是 | 回调函数，异步返回暂停下载任务是否成功。 | 1336 1337**示例：** 1338 1339 ```ts 1340 downloadTask.suspend((err: BusinessError, result: boolean) => { 1341 if (err) { 1342 console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); 1343 return; 1344 } 1345 console.info('Succeeded in pausing the download task.'); 1346 }); 1347 ``` 1348 1349 1350### restore<sup>9+</sup> 1351 1352restore(): Promise<boolean> 1353 1354重新启动暂停的下载任务，异步方法，使用promise形式返回结果。 1355 1356**需要权限**：ohos.permission.INTERNET 1357 1358**系统能力**: SystemCapability.MiscServices.Download 1359 1360**返回值：** 1361 1362 | 类型 | 说明 | 1363 | -------- | -------- | 1364 | Promise<boolean> | 使用promise方式，异步返回重新启动暂停的下载任务是否成功。 | 1365 1366**示例：** 1367 1368 ```ts 1369 downloadTask.restore().then((result: boolean) => { 1370 console.info('Succeeded in resuming the download task.') 1371 }).catch((err: BusinessError) => { 1372 console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); 1373 }); 1374 ``` 1375 1376 1377### restore<sup>9+</sup> 1378 1379restore(callback: AsyncCallback<boolean>): void 1380 1381重新启动暂停的下载任务，异步方法，使用callback形式返回结果。 1382 1383**需要权限**：ohos.permission.INTERNET 1384 1385**系统能力**: SystemCapability.MiscServices.Download 1386 1387**参数：** 1388 1389 | 参数名 | 类型 | 必填 | 说明 | 1390 | -------- | -------- | -------- | -------- | 1391 | callback | AsyncCallback<boolean> | 是 | 回调函数，异步返回重新启动暂停的下载任务是否成功。 | 1392 1393**示例：** 1394 1395 ```ts 1396 downloadTask.restore((err: BusinessError, result: boolean) => { 1397 if (err) { 1398 console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); 1399 return; 1400 } 1401 console.info('Succeeded in resuming the download task.'); 1402 }); 1403 ``` 1404 1405 1406### remove<sup>(deprecated)</sup> 1407 1408remove(): Promise<boolean> 1409 1410移除下载的任务，异步方法，使用promise形式返回结果。 1411 1412> **说明：** 1413> 1414> 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9-2)替代。 1415 1416**需要权限**：ohos.permission.INTERNET 1417 1418**系统能力**: SystemCapability.MiscServices.Download 1419 1420**返回值：** 1421 1422 | 类型 | 说明 | 1423 | -------- | -------- | 1424 | Promise<boolean> | 使用promise方式，异步返回移除任务是否成功。 | 1425 1426**示例：** 1427 1428 ```js 1429 downloadTask.remove().then((result) => { 1430 console.info('Succeeded in removing the download task.'); 1431 }).catch ((err) => { 1432 console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); 1433 }); 1434 ``` 1435 1436 1437### remove<sup>(deprecated)</sup> 1438 1439remove(callback: AsyncCallback<boolean>): void 1440 1441移除下载的任务，异步方法，使用callback形式返回结果。 1442 1443> **说明：** 1444> 1445> 从API Version 9开始不再维护，建议使用[delete<sup>9+</sup>](#delete9-3)替代。 1446 1447**需要权限**：ohos.permission.INTERNET 1448 1449**系统能力**: SystemCapability.MiscServices.Download 1450 1451**参数：** 1452 1453 | 参数名 | 类型 | 必填 | 说明 | 1454 | -------- | -------- | -------- | -------- | 1455 | callback | AsyncCallback<boolean> | 是 | 回调函数，异步返回移除任务是否成功。 | 1456 1457**示例：** 1458 1459 ```js 1460 downloadTask.remove((err, result)=>{ 1461 if(err) { 1462 console.error(`Failed to remove the download task. Code: ${err.code}, message: ${err.message}`); 1463 return; 1464 } 1465 console.info('Succeeded in removing the download task.'); 1466 }); 1467 ``` 1468 1469 1470### query<sup>(deprecated)</sup> 1471 1472query(): Promise<DownloadInfo> 1473 1474查询下载任务，异步方法，使用promise形式返回DownloadInfo里的信息。 1475 1476> **说明：** 1477> 1478> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskInfo<sup>9+</sup>](#gettaskinfo9)替代。 1479 1480**需要权限**：ohos.permission.INTERNET 1481 1482**系统能力**: SystemCapability.MiscServices.Download 1483 1484**返回值：** 1485 1486 | 类型 | 说明 | 1487 | -------- | -------- | 1488 | Promise<[DownloadInfo](#downloadinfo7)> | 使用promise方式，异步返回下载任务信息。 | 1489 1490**示例：** 1491 1492 ```js 1493 downloadTask.query().then((downloadInfo) => { 1494 console.info('Succeeded in querying the download task.') 1495 }) .catch((err) => { 1496 console.error(`Failed to query the download task. Code: ${err.code}, message: ${err.message}`) 1497 }); 1498 ``` 1499 1500 1501### query<sup>(deprecated)</sup> 1502 1503query(callback: AsyncCallback<DownloadInfo>): void 1504 1505查询下载的任务，异步方法，使用callback形式返回结果。 1506 1507> **说明：** 1508> 1509> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskInfo<sup>9+</sup>](#gettaskinfo9-1)替代。 1510 1511**需要权限**：ohos.permission.INTERNET 1512 1513**系统能力**: SystemCapability.MiscServices.Download 1514 1515**参数：** 1516 1517 | 参数名 | 类型 | 必填 | 说明 | 1518 | -------- | -------- | -------- | -------- | 1519 | callback | AsyncCallback<[DownloadInfo](#downloadinfo7)> | 是 | 回调函数，异步返回下载任务信息。 | 1520 1521**示例：** 1522 1523 ```js 1524 downloadTask.query((err, downloadInfo)=>{ 1525 if(err) { 1526 console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`); 1527 } else { 1528 console.info('Succeeded in querying the download task.'); 1529 } 1530 }); 1531 ``` 1532 1533 1534### queryMimeType<sup>(deprecated)</sup> 1535 1536queryMimeType(): Promise<string> 1537 1538查询下载的任务的 MimeType，异步方法，使用promise形式返回结果。 1539 1540> **说明：** 1541> 1542> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskMimeType<sup>9+</sup>](#gettaskmimetype9)替代。 1543 1544**需要权限**：ohos.permission.INTERNET 1545 1546**系统能力**: SystemCapability.MiscServices.Download 1547 1548**返回值：** 1549 1550 | 类型 | 说明 | 1551 | -------- | -------- | 1552 | Promise<string> | 使用promise方式，异步返回下载任务的MimeType。 | 1553 1554**示例：** 1555 1556 ```js 1557 downloadTask.queryMimeType().then((data) => { 1558 console.info('Succeeded in querying the download MimeType.'); 1559 }).catch((err) => { 1560 console.error(`Failed to query the download MimeType. Code: ${err.code}, message: ${err.message}`) 1561 }); 1562 ``` 1563 1564 1565### queryMimeType<sup>(deprecated)</sup> 1566 1567queryMimeType(callback: AsyncCallback<string>): void; 1568 1569查询下载的任务的 MimeType，异步方法，使用callback形式返回结果。 1570 1571> **说明：** 1572> 1573> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[getTaskMimeType<sup>9+</sup>](#gettaskmimetype9-1)替代。 1574 1575**需要权限**：ohos.permission.INTERNET 1576 1577**系统能力**: SystemCapability.MiscServices.Download 1578 1579**参数：** 1580 1581 | 参数名 | 类型 | 必填 | 说明 | 1582 | -------- | -------- | -------- | -------- | 1583 | callback | AsyncCallback<string> | 是 | 回调函数，异步返回下载任务的MimeType。 | 1584 1585**示例：** 1586 1587 ```js 1588 downloadTask.queryMimeType((err, data)=>{ 1589 if(err) { 1590 console.error(`Failed to query the download mimeType. Code: ${err.code}, message: ${err.message}`); 1591 } else { 1592 console.info('Succeeded in querying the download mimeType.'); 1593 } 1594 }); 1595 ``` 1596 1597 1598### pause<sup>(deprecated)</sup> 1599 1600pause(): Promise<void> 1601 1602暂停下载任务，异步方法，使用promise形式返回结果。 1603 1604> **说明：** 1605> 1606> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[suspend<sup>9+</sup>](#suspend9)替代。 1607 1608**需要权限**：ohos.permission.INTERNET 1609 1610**系统能力**: SystemCapability.MiscServices.Download 1611 1612**返回值：** 1613 1614 | 类型 | 说明 | 1615 | -------- | -------- | 1616 | Promise<void> | 使用promise方式，异步返回暂停下载任务是否成功。 | 1617 1618**示例：** 1619 1620 ```js 1621 downloadTask.pause().then((result) => { 1622 console.info('Succeeded in pausing the download task.'); 1623 }).catch((err) => { 1624 console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); 1625 }); 1626 ``` 1627 1628 1629### pause<sup>(deprecated)</sup> 1630 1631pause(callback: AsyncCallback<void>): void 1632 1633> **说明：** 1634> 1635> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[suspend<sup>9+</sup>](#suspend9-1)替代。 1636 1637暂停下载任务，异步方法，使用callback形式返回结果。 1638 1639**需要权限**：ohos.permission.INTERNET 1640 1641**系统能力**: SystemCapability.MiscServices.Download 1642 1643**参数：** 1644 1645 | 参数名 | 类型 | 必填 | 说明 | 1646 | -------- | -------- | -------- | -------- | 1647 | callback | AsyncCallback<void> | 是 | 回调函数，异步返回暂停下载任务是否成功。 | 1648 1649**示例：** 1650 1651 ```js 1652 downloadTask.pause((err, result)=>{ 1653 if(err) { 1654 console.error(`Failed to pause the download task. Code: ${err.code}, message: ${err.message}`); 1655 return; 1656 } 1657 console.info('Succeeded in pausing the download task.'); 1658 }); 1659 ``` 1660 1661 1662### resume<sup>(deprecated)</sup> 1663 1664resume(): Promise<void> 1665 1666重新启动暂停的下载任务，异步方法，使用promise形式返回结果。 1667 1668> **说明：** 1669> 1670> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[restore<sup>9+</sup>](#restore9)替代。 1671 1672**需要权限**：ohos.permission.INTERNET 1673 1674**系统能力**: SystemCapability.MiscServices.Download 1675 1676**返回值：** 1677 1678 | 类型 | 说明 | 1679 | -------- | -------- | 1680 | Promise<void> | 使用promise方式，异步返回重新启动暂停的下载任务是否成功。 | 1681 1682**示例：** 1683 1684 ```js 1685 downloadTask.resume().then((result) => { 1686 console.info('Succeeded in resuming the download task.') 1687 }).catch((err) => { 1688 console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); 1689 }); 1690 ``` 1691 1692 1693### resume<sup>(deprecated)</sup> 1694 1695resume(callback: AsyncCallback<void>): void 1696 1697> **说明：** 1698> 1699> 从API Version 7开始支持，从API Version 9开始不再维护，建议使用[restore<sup>9+</sup>](#restore9-1)替代。 1700 1701重新启动暂停的下载任务，异步方法，使用callback形式返回结果。 1702 1703**需要权限**：ohos.permission.INTERNET 1704 1705**系统能力**: SystemCapability.MiscServices.Download 1706 1707**参数：** 1708 1709 | 参数名 | 类型 | 必填 | 说明 | 1710 | -------- | -------- | -------- | -------- | 1711 | callback | AsyncCallback<void> | 是 | 回调函数，异步返回重新启动暂停的下载任务是否成功。 | 1712 1713**示例：** 1714 1715 ```js 1716 downloadTask.resume((err, result)=>{ 1717 if (err) { 1718 console.error(`Failed to resume the download task. Code: ${err.code}, message: ${err.message}`); 1719 return; 1720 } 1721 console.info('Succeeded in resuming the download task.'); 1722 }); 1723 ``` 1724 1725 1726## DownloadConfig 1727下载任务的配置信息。 1728 1729**需要权限**：ohos.permission.INTERNET 1730 1731**系统能力**: SystemCapability.MiscServices.Download 1732 1733| 名称 | 类型 | 必填 | 说明 | 1734| -------- | -------- | -------- | -------- | 1735| url | string | 是 | 资源地址。 | 1736| 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 | 1737| enableMetered | boolean | 否 | 设置是否允许在按流量计费的连接下下载(默认使用false)。Wi-Fi为非计费网络，数据流量为计费网络。<br/>- true：是<br/>- false：否 | 1738| enableRoaming | boolean | 否 | 设置是否允许在漫游网络中下载(默认使用false)。 <br/>- true：是<br/>- false：否| 1739| description | string | 否 | 设置下载会话的描述。 | 1740| 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\`，并将文件存储在此路径下。| 1741| networkType | number | 否 | 设置允许下载的网络类型(默认使用NETWORK_MOBILE&NETWORK_WIFI)。<br/>- NETWORK_MOBILE：0x00000001<br/>- NETWORK_WIFI：0x00010000| 1742| title | string | 否 | 设置下载任务名称。 | 1743| background<sup>9+</sup> | boolean | 否 | 后台任务通知开关，开启后可在通知中显示下载状态(默认使用false)。 | 1744 1745 1746## DownloadInfo<sup>7+</sup> 1747下载任务信息，[getTaskInfo<sup>9+</sup>](#gettaskinfo9)接口的回调参数。 1748 1749**需要权限**：ohos.permission.INTERNET 1750 1751**系统能力**: SystemCapability.MiscServices.Download 1752 1753| 名称 | 类型 |必填 | 说明 | 1754| -------- | -------- | -------- | -------- | 1755| downloadId | number |是 | 下载任务ID。 | 1756| failedReason | number|是 | 下载失败原因，可以是任何[下载任务的错误码](#下载任务的错误码)常量。 | 1757| fileName | string |是| 下载的文件名。 | 1758| filePath | string |是| 存储文件的URI。 | 1759| pausedReason | number |是| 会话暂停的原因，可以是任何[下载任务暂停原因](#下载任务暂停原因)常量。 | 1760| status | number |是| 下载状态码，可以是任何[下载任务状态码](#下载任务状态码)常量。 | 1761| targetURI | string |是| 下载文件的URI。 | 1762| downloadTitle | string |是| 下载任务名称。 | 1763| downloadTotalBytes | number |是| 下载的文件的总大小（int bytes）。 | 1764| description | string |是| 待下载任务的描述信息。 | 1765| downloadedBytes | number |是| 实时下载大小（int bytes）。 | 1766 1767## Action<sup>10+</sup> 1768 1769定义操作选项。 1770 1771**系统能力**: SystemCapability.Request.FileTransferAgent 1772 1773| 名称 | 值 |说明 | 1774| -------- | -------- |-------- | 1775| DOWNLOAD | 0 |表示下载任务。 | 1776| UPLOAD | 1 |表示上传任务。 | 1777 1778 1779## Mode<sup>10+</sup> 1780定义模式选项。 1781 1782**系统能力**: SystemCapability.Request.FileTransferAgent 1783 1784| 名称 | 值 |说明 | 1785| -------- | -------- |-------- | 1786| BACKGROUND | 0 |表示后台任务。 | 1787| FOREGROUND | 1 |表示前端任务。 | 1788 1789## Network<sup>10+</sup> 1790 1791定义网络选项。 1792 1793**系统能力**: SystemCapability.Request.FileTransferAgent 1794 1795| 名称 | 值 |说明 | 1796| -------- | -------- |-------- | 1797| ANY | 0 |表示不限网络类型。 | 1798| WIFI | 1 |表示无线网络。 | 1799| CELLULAR | 2 |表示蜂窝数据网络。 | 1800 1801## FileSpec<sup>10+</sup> 1802表单项的文件信息。 1803 1804**系统能力**: SystemCapability.Request.FileTransferAgent 1805 1806| 名称 | 类型 | 必填 | 说明 | 1807| -------- | -------- | -------- | -------- | 1808| path | string | 是 | 文件路径位于调用方的缓存文件夹下的相对路径。 | 1809| mimeType | string | 否 | 文件的mimetype通过文件名获取。 | 1810| filename | string | 否 | 文件名，默认值通过路径获取。 | 1811| extras | Object | 否 | 文件信息的附加内容。 | 1812 1813 1814## FormItem<sup>10+</sup> 1815任务的表单项信息。 1816 1817**系统能力**: SystemCapability.Request.FileTransferAgent 1818 1819| 名称 | 类型 | 必填 | 说明 | 1820| -------- | -------- | -------- | -------- | 1821| name | string | 是 | 表单参数名。 | 1822| value | string \| [FileSpec](#filespec10) \| Array<[FileSpec](#filespec10)> | 是 | 表单参数值。 | 1823 1824 1825## Config<sup>10+</sup> 1826上传/下载任务的配置信息。 1827 1828**系统能力**: SystemCapability.Request.FileTransferAgent 1829 1830| 名称 | 类型 | 必填 | 说明 | 1831| -------- | -------- | -------- | -------- | 1832| action | [Action](#action10) | 是 | 任务操作选项。<br/>-UPLOAD表示上传任务。<br/>-DOWNLOAD表示下载任务。 | 1833| url | string | 是 | 资源地址，其最大长度为2048个字符。 | 1834| title | string | 否 | 任务标题，其最大长度为256个字符，默认值为空。 | 1835| description | string | 否 | 任务的详细信息，其最大长度为1024个字符，默认值为空字符串。 | 1836| mode | [Mode](#mode10) | 否 | 任务模式,默认为后台任务。<br/>-对于前端任务，有回调通知。<br/>-对于后台任务，有系统通知、检测网络连接、恢复、自动重试功能。 | 1837| overwrite | boolean | 否 | 下载过程中路径已存在时的解决方案选择，默认为false。<br/>- true，覆盖已存在的文件。<br/>- false，下载失败。 | 1838| method | string | 否 | 上传或下载的HTTP标准方法，包括GET、POST和PUT，不区分大小写。<br/>-上传时，使用PUT或POST，默认值为PUT。<br/>-下载时，使用GET或POST，默认值为GET。 | 1839| headers | object | 否 | 添加要包含在任务中的HTTP协议标志头。<br/>-对于上传请求，默认的Content-Type为"multipart/form-data"。<br/>-对于下载请求，默认的Content-Type为"application/json"。 | 1840| data | string \| Array<[FormItem](#formitem10)> | 否 | -下载时，data为字符串类型，通常使用json(object将被转换为json文本)，默认为空。<br/>-上传时，data是表单项数组Array<[FormItem](#formitem10)>，默认为空。 | 1841| saveas | string | 否 | 保存下载文件的路径，包括如下两种：<br/>-相对路径，如"./xxx/yyy/zzz.html"、"xxx/yyy/zzz.html"，位于调用方的缓存路径下。<br/>-uri路径，如"datashare://bundle/xxx/yyy/zzz.html"，仅对具有访问url路径权限的应用开放。该功能暂不支持。<br/>默认为相对路径，即下载至应用当前缓存路径下。 | 1842| network | [Network](#network10) | 否 | 网络选项，当前支持无线网络WIFI和蜂窝数据网络CELLULAR，默认为ANY（WIFI或CELLULAR）。 | 1843| metered | boolean | 否 | 是否允许在按流量计费的网络中工作，默认为false。<br/>-true：是 <br/>-false：否| 1844| roaming | boolean | 否 | 是否允许在漫游网络中工作，默认为true。<br/>-true：是 <br/>-false：否 | 1845| retry | boolean | 否 | 是否为后台任务启用自动重试，仅应用于后台任务，默认为true。<br/>-true：是 <br/>-false：否 | 1846| redirect | boolean | 否 | 是否允许重定向，默认为true。<br/>-true：是 <br/>-false：否 | 1847| index | number | 否 | 任务的路径索引，通常用于任务断点续传，默认为0。 | 1848| begins | number | 否 | 文件起点，通常用于断点续传。默认值为0，取值为闭区间。<br/>-下载时，请求读取服务器开始下载文件时的起点位置（http协议中设置"Range"选项）。<br/>-上传时，在上传开始时读取。 | 1849| ends | number | 否 | 文件终点，通常用于断点续传。默认值为-1，取值为闭区间。<br/>-下载时，请求读取服务器开始下载文件时的结束位置（http协议中设置"Range"选项）。<br/>-上传时，在上传时结束读取。 | 1850| gauge | boolean | 否 | 后台任务的过程进度通知策略，仅应用于后台任务，默认值为false。<br/>-false：代表仅完成或失败的通知。<br/>-true，发出每个进度已完成或失败的通知。 | 1851| precise | boolean | 否 | -如果设置为true，在上传/下载无法获取文件大小时任务失败。<br/>-如果设置为false，将文件大小设置为-1时任务继续。<br/>默认值为false。 | 1852| token | string | 否 | 当创建了一个带有token的任务后，token则为正常查询期间必须提供的，否则将无法通过查询进行检索。其最小为8个字节，最大为2048个字节。默认为空。 | 1853| extras | object | 否 | 配置的附加功能，默认为空。 | 1854 1855## State<sup>10+</sup> 1856 1857定义任务当前的状态。 1858 1859**系统能力**: SystemCapability.Request.FileTransferAgent 1860 1861| 名称 | 值 |说明 | 1862| -------- | -------- |-------- | 1863| INITIALIZED | 0x00 |通过配置信息（[Config](#config10)）创建初始化任务。 | 1864| WAITING | 0x10 |表示任务缺少运行或重试的资源与网络状态不匹配。 | 1865| RUNNING | 0x20 |表示正在处理的任务。 | 1866| RETRYING | 0x21 |表示任务至少失败一次，现在正在再次处理中。 | 1867| PAUSED | 0x30 |表示任务暂停，通常后续会恢复任务。 | 1868| STOPPED | 0x31 |表示任务停止。 | 1869| COMPLETED | 0x40 |表示任务完成。 | 1870| FAILED | 0x41 |表示任务失败。 | 1871| REMOVED | 0x50 |表示任务移除。 | 1872 1873 1874## Progress<sup>10+</sup> 1875任务进度的数据结构。 1876 1877**系统能力**: SystemCapability.Request.FileTransferAgent 1878 1879| 名称 | 类型 | 必填 | 说明 | 1880| -------- | -------- | -------- | -------- | 1881| state | [State](#state10) | 是 | 任务当前的状态。 | 1882| index | number | 是 | 任务中当前正在处理的文件索引。 | 1883| processed | number | 是 | 任务中当前文件的已处理数据大小，单位为B。| 1884| sizes | Array<number> | 是 | 任务中文件的大小，单位为B。 | 1885| extras | object | 否 | 交互的额外内容，例如来自服务器的响应的header和body。 | 1886 1887 1888## Faults<sup>10+</sup> 1889 1890定义任务失败的原因。 1891 1892**系统能力**: SystemCapability.Request.FileTransferAgent 1893 1894| 名称 | 值 |说明 | 1895| -------- | -------- |-------- | 1896| OTHERS | 0xFF |表示其他故障。 | 1897| DISCONNECTED | 0x00 |表示网络断开连接。 | 1898| TIMEOUT | 0x10 |表示任务超时。 | 1899| PROTOCOL | 0x20 |表示协议错误，例如:服务器内部错误（500）、无法处理的数据区间（416）等。 | 1900| FSIO | 0x40 |表示文件系统io错误，例如打开/查找/读取/写入/关闭。 | 1901 1902 1903## Filter<sup>10+</sup> 1904过滤条件。 1905 1906**系统能力**: SystemCapability.Request.FileTransferAgent 1907 1908| 名称 | 类型 | 必填 | 说明 | 1909| -------- | -------- | -------- | -------- | 1910| bundle | string | 否 | 指定应用程序的包名，仅对系统应用开放。<br/>**系统接口**：此接口为系统接口。 | 1911| before | number | 否 | 结束的Unix时间戳（毫秒），默认为调用时刻。 | 1912| after | number | 否 | 开始的Unix时间戳（毫秒），默认值为调用时刻减24小时。 | 1913| state | [State](#state10) | 否 | 指定任务的状态。 | 1914| action | [Action](#action10) | 否 | 任务操作选项。<br/>-UPLOAD表示上传任务。<br/>-DOWNLOAD表示下载任务。 | 1915| mode | [Mode](#mode10) | 否 | 任务模式。<br/>-FOREGROUND表示前端任务。<br/>-BACKGROUND表示后台任务。 | 1916 1917## TaskInfo<sup>10+</sup> 1918查询结果的任务信息数据结构，提供普通查询和系统查询，两种字段的可见范围不同。 1919 1920**系统能力**: SystemCapability.Request.FileTransferAgent 1921 1922| 名称 | 类型 | 必填 | 说明 | 1923| -------- | -------- | -------- | -------- | 1924| uid | string | 否 | 应用程序的UID，仅用于系统查询。<br/>**系统接口**：此接口为系统接口。| 1925| bundle | string | 否 | 应用程序的包名，仅用于系统查询。<br/>**系统接口**：此接口为系统接口。| 1926| saveas | string | 否 | 保存下载文件的路径，包括如下两种：<br/>-相对路径，如"./xxx/yyy/zzz.html"、"xxx/yyy/zzz.html"，位于调用方的缓存路径下。<br/>-uri路径，如"datashare://bundle/xxx/yyy/zzz.html"，仅对具有访问url路径权限的应用开放。该功能暂不支持。<br/>默认为相对路径，即下载至应用当前缓存路径下。| 1927| url | string | 否 | 任务的url。<br/>- 通过[request.agent.show<sup>10+</sup>](#requestagentshow10-1)、[request.agent.touch<sup>10+</sup>](#requestagenttouch10-1)、[request.agent.query<sup>10+</sup>](#requestagentquery10-1)进行查询。其中，使用[request.agent.query<sup>10+</sup>](#requestagentquery10-1)进行查询时会返回空字符串。 | 1928| data | string \| Array<[FormItem](#formitem10)> | 否 | 任务值。<br/>- 通过[request.agent.show<sup>10+</sup>](#requestagentshow10-1)、[request.agent.touch<sup>10+</sup>](#requestagenttouch10-1)、[request.agent.query<sup>10+</sup>](#requestagentquery10-1)进行查询。其中，使用[request.agent.query<sup>10+</sup>](#requestagentquery10-1)进行查询时会返回空字符串。 | 1929| tid | string | 是 | 任务id。 | 1930| title | string | 是 | 任务标题。 | 1931| description | string | 是 | 任务描述。 | 1932| action | [Action](#action10) | 是 | 任务操作选项。<br/>-UPLOAD表示上传任务。<br/>-DOWNLOAD表示下载任务。 | 1933| mode | [Mode](#mode10) | 是 | 指定任务模式。<br/>-FOREGROUND表示前端任务。<br/>-BACKGROUND表示后台任务。 | 1934| mimeType | string | 是 | 任务配置中的mimetype。 | 1935| progress | [Progress](#progress10) | 是 | 任务的过程进度。 | 1936| gauge | boolean | 是 | 后台任务的进度通知策略。 | 1937| ctime | number | 是 | 创建任务的Unix时间戳（毫秒），由当前设备的系统生成。<br/>说明：使用[request.agent.search<sup>10+</sup>](#requestagentsearch10-1)进行查询时，该值需处于[after,before]区间内才可正常查询到任务id，before和after信息详见[Filter](#filter10)。 1938| mtime | number | 是 | 任务状态改变时的Unix时间戳（毫秒），由当前设备的系统生成。| 1939| retry | boolean | 是 | 任务的重试开关，仅应用于后台任务。 | 1940| tries | number | 是 | 任务的尝试次数。 | 1941| faults | [Faults](#faults10) | 是 | 任务的失败原因。<br/>-OTHERS表示其他故障。<br/>-DISCONNECT表示网络断开连接。<br/>-TIMEOUT表示任务超时。<br/>-PROTOCOL表示协议错误。<br/>-FSIO表示文件系统io错误。| 1942| reason | string | 是 | 等待/失败/停止/暂停任务的原因。| 1943| extras | string | 否 | 任务的额外部分。| 1944 1945 1946## Task<sup>10+</sup> 1947上传或下载任务。使用该方法前需要先获取Task对象，promise形式通过[request.agent.create<sup>10+</sup>](#requestagentcreate10-1)获取，callback形式通过[request.agent.create<sup>10+</sup>](#requestagentcreate10)获取。 1948 1949### 属性 1950包括任务id和任务的配置信息。 1951 1952**系统能力**: SystemCapability.Request.FileTransferAgent 1953 1954| 名称 | 类型 | 必填 | 说明 | 1955| -------- | -------- | -------- | -------- | 1956| tid | string | 是 | 任务id，在系统上是唯一的，由系统自动生成。 | 1957| config | [Config](#config10) | 是 | 任务的配置信息。 | 1958 1959 1960### on('progress')<sup>10+</sup> 1961 1962on(event: 'progress', callback: (progress: Progress) => void): void 1963 1964订阅任务进度的事件，异步方法，使用callback形式返回结果。 1965 1966**系统能力**: SystemCapability.Request.FileTransferAgent 1967 1968**参数：** 1969 1970 | 参数名 | 类型 | 必填 | 说明 | 1971 | -------- | -------- | -------- | -------- | 1972 | event | string | 是 | 订阅的事件类型。<br>- 取值为'progress'，表示任务进度。 | 1973 | callback | function | 是 | 发生相关的事件时触发该回调方法，返回任务进度的数据结构。| 1974 1975**错误码：** 1976 1977以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 1978 1979 | 错误码ID | 错误信息 | 1980 | -------- | -------- | 1981 | 21900005 | task mode error. | 1982 1983**示例：** 1984 1985 ```ts 1986 let attachments: Array<request.agent.FormItem> = [{ 1987 name: "taskOnTest", 1988 value: { 1989 filename: "taskOnTest.avi", 1990 mimeType: "application/octet-stream", 1991 path: "./taskOnTest.avi", 1992 } 1993 }]; 1994 let config: request.agent.Config = { 1995 action: request.agent.Action.UPLOAD, 1996 url: 'http://127.0.0.1', 1997 title: 'taskOnTest', 1998 description: 'Sample code for event listening', 1999 mode: request.agent.Mode.FOREGROUND, 2000 overwrite: false, 2001 method: "PUT", 2002 data: attachments, 2003 saveas: "./", 2004 network: request.agent.Network.CELLULAR, 2005 metered: false, 2006 roaming: true, 2007 retry: true, 2008 redirect: true, 2009 index: 0, 2010 begins: 0, 2011 ends: -1, 2012 gauge: false, 2013 precise: false, 2014 token: "it is a secret" 2015 }; 2016 let createOnCallback = (progress: request.agent.Progress) => { 2017 console.info('upload task progress.'); 2018 }; 2019 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2020 task.on('progress', createOnCallback); 2021 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2022 }).catch((err: BusinessError) => { 2023 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2024 }); 2025 ``` 2026 2027> **说明：** 2028> 2029> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2030 2031### on('completed')<sup>10+</sup> 2032 2033on(event: 'completed', callback: (progress: Progress) => void): void 2034 2035订阅任务完成事件，异步方法，使用callback形式返回结果。 2036 2037**系统能力**: SystemCapability.Request.FileTransferAgent 2038 2039**参数：** 2040 2041 | 参数名 | 类型 | 必填 | 说明 | 2042 | -------- | -------- | -------- | -------- | 2043 | event | string | 是 | 订阅的事件类型。<br>- 取值为'completed'，表示任务完成。 | 2044 | callback | function | 是 | 发生相关的事件时触发该回调方法，返回任务进度的数据结构。 | 2045 2046**错误码：** 2047 2048以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2049 2050 | 错误码ID | 错误信息 | 2051 | -------- | -------- | 2052 | 21900005 | task mode error. | 2053 2054**示例：** 2055 2056 ```ts 2057 let attachments: Array<request.agent.FormItem> = [{ 2058 name: "taskOnTest", 2059 value: { 2060 filename: "taskOnTest.avi", 2061 mimeType: "application/octet-stream", 2062 path: "./taskOnTest.avi", 2063 } 2064 }]; 2065 let config: request.agent.Config = { 2066 action: request.agent.Action.UPLOAD, 2067 url: 'http://127.0.0.1', 2068 title: 'taskOnTest', 2069 description: 'Sample code for event listening', 2070 mode: request.agent.Mode.FOREGROUND, 2071 overwrite: false, 2072 method: "PUT", 2073 data: attachments, 2074 saveas: "./", 2075 network: request.agent.Network.CELLULAR, 2076 metered: false, 2077 roaming: true, 2078 retry: true, 2079 redirect: true, 2080 index: 0, 2081 begins: 0, 2082 ends: -1, 2083 gauge: false, 2084 precise: false, 2085 token: "it is a secret" 2086 }; 2087 let createOnCallback = (progress: request.agent.Progress) => { 2088 console.info('upload task completed.'); 2089 }; 2090 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2091 task.on('completed', createOnCallback); 2092 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2093 }).catch((err: BusinessError) => { 2094 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2095 }); 2096 ``` 2097 2098> **说明：** 2099> 2100> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2101 2102### on('failed')<sup>10+</sup> 2103 2104on(event: 'failed', callback: (progress: Progress) => void): void 2105 2106订阅任务失败事件，异步方法，使用callback形式返回结果。 2107 2108**系统能力**: SystemCapability.Request.FileTransferAgent 2109 2110**参数：** 2111 2112 | 参数名 | 类型 | 必填 | 说明 | 2113 | -------- | -------- | -------- | -------- | 2114 | event | string | 是 | 订阅的事件类型。<br>- 取值为'failed'，表示任务失败。 | 2115 | callback | function | 是 | 发生相关的事件时触发该回调方法，返回任务进度的数据结构。 | 2116 2117**错误码：** 2118 2119以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2120 2121 | 错误码ID | 错误信息 | 2122 | -------- | -------- | 2123 | 21900005 | task mode error. | 2124 2125**示例：** 2126 2127 ```ts 2128 let attachments: Array<request.agent.FormItem> = [{ 2129 name: "taskOnTest", 2130 value: { 2131 filename: "taskOnTest.avi", 2132 mimeType: "application/octet-stream", 2133 path: "./taskOnTest.avi", 2134 } 2135 }]; 2136 let config: request.agent.Config = { 2137 action: request.agent.Action.UPLOAD, 2138 url: 'http://127.0.0.1', 2139 title: 'taskOnTest', 2140 description: 'Sample code for event listening', 2141 mode: request.agent.Mode.FOREGROUND, 2142 overwrite: false, 2143 method: "PUT", 2144 data: attachments, 2145 saveas: "./", 2146 network: request.agent.Network.CELLULAR, 2147 metered: false, 2148 roaming: true, 2149 retry: true, 2150 redirect: true, 2151 index: 0, 2152 begins: 0, 2153 ends: -1, 2154 gauge: false, 2155 precise: false, 2156 token: "it is a secret" 2157 }; 2158 let createOnCallback = (progress: request.agent.Progress) => { 2159 console.info('upload task failed.'); 2160 }; 2161 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2162 task.on('failed', createOnCallback); 2163 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2164 }).catch((err: BusinessError) => { 2165 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2166 }); 2167 ``` 2168 2169> **说明：** 2170> 2171> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2172 2173 2174### off('progress')<sup>10+</sup> 2175 2176off(event: 'progress', callback?: (progress: Progress) => void): void 2177 2178取消订阅任务进度事件。 2179 2180**系统能力**: SystemCapability.Request.FileTransferAgent 2181 2182**参数：** 2183 2184 | 参数名 | 类型 | 必填 | 说明 | 2185 | -------- | -------- | -------- | -------- | 2186 | event | string | 是 | 订阅的事件类型。<br>- 取值为'progress'，表示任务进度。 | 2187 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 2188 2189**错误码：** 2190 2191以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2192 2193 | 错误码ID | 错误信息 | 2194 | -------- | -------- | 2195 | 21900005 | task mode error. | 2196 2197**示例：** 2198 2199 ```ts 2200 let attachments: Array<request.agent.FormItem> = [{ 2201 name: "taskOffTest", 2202 value: { 2203 filename: "taskOffTest.avi", 2204 mimeType: "application/octet-stream", 2205 path: "./taskOffTest.avi", 2206 } 2207 }]; 2208 let config: request.agent.Config = { 2209 action: request.agent.Action.UPLOAD, 2210 url: 'http://127.0.0.1', 2211 title: 'taskOffTest', 2212 description: 'Sample code for event listening', 2213 mode: request.agent.Mode.FOREGROUND, 2214 overwrite: false, 2215 method: "PUT", 2216 data: attachments, 2217 saveas: "./", 2218 network: request.agent.Network.CELLULAR, 2219 metered: false, 2220 roaming: true, 2221 retry: true, 2222 redirect: true, 2223 index: 0, 2224 begins: 0, 2225 ends: -1, 2226 gauge: false, 2227 precise: false, 2228 token: "it is a secret" 2229 }; 2230 let createOffCallback1 = (progress: request.agent.Progress) => { 2231 console.info('upload task progress.'); 2232 }; 2233 let createOffCallback2 = (progress: request.agent.Progress) => { 2234 console.info('upload task progress.'); 2235 }; 2236 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2237 task.on('progress', createOffCallback1); 2238 task.on('progress', createOffCallback2); 2239 //表示取消createOffCallback1的订阅 2240 task.off('progress', createOffCallback1); 2241 //表示取消订阅前端任务进度的所有回调 2242 task.off('progress'); 2243 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2244 }).catch((err: BusinessError) => { 2245 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2246 }); 2247 ``` 2248 2249> **说明：** 2250> 2251> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2252 2253### off('completed')<sup>10+</sup> 2254 2255off(event: 'completed', callback?: (progress: Progress) => void): void 2256 2257取消订阅任务完成事件。 2258 2259**系统能力**: SystemCapability.Request.FileTransferAgent 2260 2261**参数：** 2262 2263 | 参数名 | 类型 | 必填 | 说明 | 2264 | -------- | -------- | -------- | -------- | 2265 | event | string | 是 | 订阅的事件类型。<br>- 取值为'completed'，表示任务完成。 | 2266 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 2267 2268**错误码：** 2269 2270以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2271 2272 | 错误码ID | 错误信息 | 2273 | -------- | -------- | 2274 | 21900005 | task mode error. | 2275 2276**示例：** 2277 2278 ```ts 2279 let attachments: Array<request.agent.FormItem> = [{ 2280 name: "taskOffTest", 2281 value: { 2282 filename: "taskOffTest.avi", 2283 mimeType: "application/octet-stream", 2284 path: "./taskOffTest.avi", 2285 } 2286 }]; 2287 let config: request.agent.Config = { 2288 action: request.agent.Action.UPLOAD, 2289 url: 'http://127.0.0.1', 2290 title: 'taskOffTest', 2291 description: 'Sample code for event listening', 2292 mode: request.agent.Mode.FOREGROUND, 2293 overwrite: false, 2294 method: "PUT", 2295 data: attachments, 2296 saveas: "./", 2297 network: request.agent.Network.CELLULAR, 2298 metered: false, 2299 roaming: true, 2300 retry: true, 2301 redirect: true, 2302 index: 0, 2303 begins: 0, 2304 ends: -1, 2305 gauge: false, 2306 precise: false, 2307 token: "it is a secret" 2308 }; 2309 let createOffCallback1 = (progress: request.agent.Progress) => { 2310 console.info('upload task completed.'); 2311 }; 2312 let createOffCallback2 = (progress: request.agent.Progress) => { 2313 console.info('upload task completed.'); 2314 }; 2315 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2316 task.on('completed', createOffCallback1); 2317 task.on('completed', createOffCallback2); 2318 //表示取消createOffCallback1的订阅 2319 task.off('completed', createOffCallback1); 2320 //表示取消订阅前端任务完成的所有回调 2321 task.off('completed'); 2322 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2323 }).catch((err: BusinessError) => { 2324 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2325 }); 2326 ``` 2327 2328> **说明：** 2329> 2330> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2331 2332### off('failed')<sup>10+</sup> 2333 2334off(event: 'failed', callback?: (progress: Progress) => void): void 2335 2336取消订阅任务失败事件。 2337 2338**系统能力**: SystemCapability.Request.FileTransferAgent 2339 2340**参数：** 2341 2342 | 参数名 | 类型 | 必填 | 说明 | 2343 | -------- | -------- | -------- | -------- | 2344 | event | string | 是 | 订阅的事件类型。<br>- 取值为'failed'，表示任务失败。 | 2345 | callback | function | 否 | 需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。 | 2346 2347**错误码：** 2348 2349以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2350 2351 | 错误码ID | 错误信息 | 2352 | -------- | -------- | 2353 | 21900005 | task mode error. | 2354 2355**示例：** 2356 2357 ```ts 2358 let attachments: Array<request.agent.FormItem> = [{ 2359 name: "taskOffTest", 2360 value: { 2361 filename: "taskOffTest.avi", 2362 mimeType: "application/octet-stream", 2363 path: "./taskOffTest.avi", 2364 } 2365 }]; 2366 let config: request.agent.Config = { 2367 action: request.agent.Action.UPLOAD, 2368 url: 'http://127.0.0.1', 2369 title: 'taskOffTest', 2370 description: 'Sample code for event listening', 2371 mode: request.agent.Mode.FOREGROUND, 2372 overwrite: false, 2373 method: "PUT", 2374 data: attachments, 2375 saveas: "./", 2376 network: request.agent.Network.CELLULAR, 2377 metered: false, 2378 roaming: true, 2379 retry: true, 2380 redirect: true, 2381 index: 0, 2382 begins: 0, 2383 ends: -1, 2384 gauge: false, 2385 precise: false, 2386 token: "it is a secret" 2387 }; 2388 let createOffCallback1 = (progress: request.agent.Progress) => { 2389 console.info('upload task failed.'); 2390 }; 2391 let createOffCallback2 = (progress: request.agent.Progress) => { 2392 console.info('upload task failed.'); 2393 }; 2394 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2395 task.on('failed', createOffCallback1); 2396 task.on('failed', createOffCallback2); 2397 //表示取消createOffCallback1的订阅 2398 task.off('failed', createOffCallback1); 2399 //表示取消订阅前端任务失败的所有回调 2400 task.off('failed'); 2401 console.info(`Succeeded in creating a upload task. result: ${task.tid}`); 2402 }).catch((err: BusinessError) => { 2403 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2404 }); 2405 ``` 2406 2407> **说明：** 2408> 2409> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2410 2411### start<sup>10+</sup> 2412 2413start(callback: AsyncCallback<void>): void 2414 2415启动任务，无法启动已初始化的任务。使用callback异步回调。 2416 2417**需要权限**：ohos.permission.INTERNET 2418 2419**系统能力**: SystemCapability.Request.FileTransferAgent 2420 2421**参数：** 2422 2423 | 参数名 | 类型 | 必填 | 说明 | 2424 | -------- | -------- | -------- | -------- | 2425 | callback | function | 是 | 回调函数，开启任务成功，err为undefined，否则为错误对象。 | 2426 2427**错误码：** 2428 2429以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2430 2431 | 错误码ID | 错误信息 | 2432 | -------- | -------- | 2433 | 13400003 | task service ability error. | 2434 | 21900007 | task state error. | 2435 2436**示例：** 2437 2438 ```ts 2439 let config: request.agent.Config = { 2440 action: request.agent.Action.DOWNLOAD, 2441 url: 'http://127.0.0.1', 2442 title: 'taskStartTest', 2443 description: 'Sample code for start the download task', 2444 mode: request.agent.Mode.BACKGROUND, 2445 overwrite: false, 2446 method: "GET", 2447 data: "", 2448 saveas: "./", 2449 network: request.agent.Network.CELLULAR, 2450 metered: false, 2451 roaming: true, 2452 retry: true, 2453 redirect: true, 2454 index: 0, 2455 begins: 0, 2456 ends: -1, 2457 gauge: false, 2458 precise: false, 2459 token: "it is a secret" 2460 }; 2461 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2462 task.start((err: BusinessError) => { 2463 if (err) { 2464 console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`); 2465 return; 2466 } 2467 console.info(`Succeeded in starting a download task.`); 2468 }); 2469 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2470 }).catch((err: BusinessError) => { 2471 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2472 }); 2473 ``` 2474 2475> **说明：** 2476> 2477> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2478 2479### start<sup>10+</sup> 2480 2481start(): Promise<void> 2482 2483启动任务，无法启动已初始化的任务。使用Promise异步回调。 2484 2485**需要权限**：ohos.permission.INTERNET 2486 2487**系统能力**: SystemCapability.Request.FileTransferAgent 2488 2489**返回值：** 2490 2491| 类型 | 说明 | 2492| ------------------- | ------------------------- | 2493| Promise<void> | Promise对象。无返回结果的Promise对象。 | 2494 2495**错误码：** 2496 2497以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2498 2499 | 错误码ID | 错误信息 | 2500 | -------- | -------- | 2501 | 13400003 | task service ability error. | 2502 | 21900007 | task state error. | 2503 2504**示例：** 2505 2506 ```ts 2507 let config: request.agent.Config = { 2508 action: request.agent.Action.DOWNLOAD, 2509 url: 'http://127.0.0.1', 2510 title: 'taskStartTest', 2511 description: 'Sample code for start the download task', 2512 mode: request.agent.Mode.BACKGROUND, 2513 overwrite: false, 2514 method: "GET", 2515 data: "", 2516 saveas: "./", 2517 network: request.agent.Network.CELLULAR, 2518 metered: false, 2519 roaming: true, 2520 retry: true, 2521 redirect: true, 2522 index: 0, 2523 begins: 0, 2524 ends: -1, 2525 gauge: false, 2526 precise: false, 2527 token: "it is a secret" 2528 }; 2529 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2530 task.start().then(() => { 2531 console.info(`Succeeded in starting a download task.`); 2532 }).catch((err: BusinessError) => { 2533 console.error(`Failed to start the download task, Code: ${err.code}, message: ${err.message}`); 2534 }); 2535 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2536 }).catch((err: BusinessError) => { 2537 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2538 }); 2539 ``` 2540 2541> **说明：** 2542> 2543> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2544 2545### pause<sup>10+</sup> 2546 2547pause(callback: AsyncCallback<void>): void 2548 2549暂停任务，可以暂停正在等待/正在运行/正在重试的后台任务。使用callback异步回调。 2550 2551**系统能力**: SystemCapability.Request.FileTransferAgent 2552 2553**参数：** 2554 2555 | 参数名 | 类型 | 必填 | 说明 | 2556 | -------- | -------- | -------- | -------- | 2557 | callback | function | 是 | 回调函数，暂停任务成功，err为undefined，否则为错误对象。 | 2558 2559**错误码：** 2560 2561以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2562 2563 | 错误码ID | 错误信息 | 2564 | -------- | -------- | 2565 | 13400003 | task service ability error. | 2566 | 21900005 | task mode error. | 2567 | 21900007 | task state error. | 2568 2569**示例：** 2570 2571 ```ts 2572 let config: request.agent.Config = { 2573 action: request.agent.Action.DOWNLOAD, 2574 url: 'http://127.0.0.1', 2575 title: 'taskPauseTest', 2576 description: 'Sample code for pause the download task', 2577 mode: request.agent.Mode.BACKGROUND, 2578 overwrite: false, 2579 method: "GET", 2580 data: "", 2581 saveas: "./", 2582 network: request.agent.Network.CELLULAR, 2583 metered: false, 2584 roaming: true, 2585 retry: true, 2586 redirect: true, 2587 index: 0, 2588 begins: 0, 2589 ends: -1, 2590 gauge: false, 2591 precise: false, 2592 token: "it is a secret" 2593 }; 2594 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2595 task.pause((err: BusinessError) => { 2596 if (err) { 2597 console.error(`Failed to pause the download task, Code: ${err.code}, message: ${err.message}`); 2598 return; 2599 } 2600 console.info(`Succeeded in pausing a download task. `); 2601 }); 2602 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2603 }).catch((err: BusinessError) => { 2604 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2605 }); 2606 ``` 2607 2608 2609### pause<sup>10+</sup> 2610 2611pause(): Promise<void> 2612 2613暂停任务，可以暂停正在等待/正在运行/正在重试的后台任务。使用Promise异步回调。 2614 2615**系统能力**: SystemCapability.Request.FileTransferAgent 2616 2617**返回值：** 2618 2619| 类型 | 说明 | 2620| ------------------- | ------------------------- | 2621| Promise<void> | Promise对象。无返回结果的Promise对象。 | 2622 2623**错误码：** 2624 2625以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2626 2627 | 错误码ID | 错误信息 | 2628 | -------- | -------- | 2629 | 13400003 | task service ability error. | 2630 | 21900005 | task mode error. | 2631 | 21900007 | task state error. | 2632 2633**示例：** 2634 2635 ```ts 2636 let config: request.agent.Config = { 2637 action: request.agent.Action.DOWNLOAD, 2638 url: 'http://127.0.0.1', 2639 title: 'taskPauseTest', 2640 description: 'Sample code for pause the download task', 2641 mode: request.agent.Mode.BACKGROUND, 2642 overwrite: false, 2643 method: "GET", 2644 data: "", 2645 saveas: "./", 2646 network: request.agent.Network.CELLULAR, 2647 metered: false, 2648 roaming: true, 2649 retry: true, 2650 redirect: true, 2651 index: 0, 2652 begins: 0, 2653 ends: -1, 2654 gauge: false, 2655 precise: false, 2656 token: "it is a secret" 2657 }; 2658 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2659 task.pause().then(() => { 2660 console.info(`Succeeded in pausing a download task. `); 2661 }).catch((err: BusinessError) => { 2662 console.error(`Failed to pause the upload task, Code: ${err.code}, message: ${err.message}`); 2663 }); 2664 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2665 }).catch((err: BusinessError) => { 2666 console.error(`Failed to create a upload task, Code: ${err.code}, message: ${err.message}`); 2667 }); 2668 ``` 2669 2670 2671### resume<sup>10+</sup> 2672 2673resume(callback: AsyncCallback<void>): void 2674 2675重新启动任务，可以恢复暂停的后台任务。使用callback异步回调。 2676 2677**需要权限**：ohos.permission.INTERNET 2678 2679**系统能力**: SystemCapability.Request.FileTransferAgent 2680 2681**参数：** 2682 2683 | 参数名 | 类型 | 必填 | 说明 | 2684 | -------- | -------- | -------- | -------- | 2685 | callback | function | 是 | 回调函数，重新启动任务成功，err为undefined，否则为错误对象 | 2686 2687**错误码：** 2688 2689以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2690 2691 | 错误码ID | 错误信息 | 2692 | -------- | -------- | 2693 | 13400003 | task service ability error. | 2694 | 21900005 | task mode error. | 2695 | 21900007 | task state error. | 2696 2697**示例：** 2698 2699 ```ts 2700 let config: request.agent.Config = { 2701 action: request.agent.Action.DOWNLOAD, 2702 url: 'http://127.0.0.1', 2703 title: 'taskResumeTest', 2704 description: 'Sample code for resume the download task', 2705 mode: request.agent.Mode.BACKGROUND, 2706 overwrite: false, 2707 method: "GET", 2708 data: "", 2709 saveas: "./", 2710 network: request.agent.Network.CELLULAR, 2711 metered: false, 2712 roaming: true, 2713 retry: true, 2714 redirect: true, 2715 index: 0, 2716 begins: 0, 2717 ends: -1, 2718 gauge: false, 2719 precise: false, 2720 token: "it is a secret" 2721 }; 2722 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2723 task.resume((err: BusinessError) => { 2724 if (err) { 2725 console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`); 2726 return; 2727 } 2728 console.info(`Succeeded in resuming a download task. `); 2729 }); 2730 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2731 }).catch((err: BusinessError) => { 2732 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2733 }); 2734 ``` 2735 2736 2737### resume<sup>10+</sup> 2738 2739resume(): Promise<void> 2740 2741重新启动任务，可以恢复暂停的后台任务。使用Promise异步回调。 2742 2743**需要权限**：ohos.permission.INTERNET 2744 2745**系统能力**: SystemCapability.Request.FileTransferAgent 2746 2747**返回值：** 2748 2749| 类型 | 说明 | 2750| ------------------- | ------------------------- | 2751| Promise<void> | Promise对象。无返回结果的Promise对象。 | 2752 2753**错误码：** 2754 2755以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2756 2757 | 错误码ID | 错误信息 | 2758 | -------- | -------- | 2759 | 13400003 | task service ability error. | 2760 | 21900005 | task mode error. | 2761 | 21900007 | task state error. | 2762 2763**示例：** 2764 2765 ```ts 2766 let config: request.agent.Config = { 2767 action: request.agent.Action.DOWNLOAD, 2768 url: 'http://127.0.0.1', 2769 title: 'taskResumeTest', 2770 description: 'Sample code for resume the download task', 2771 mode: request.agent.Mode.BACKGROUND, 2772 overwrite: false, 2773 method: "GET", 2774 data: "", 2775 saveas: "./", 2776 network: request.agent.Network.CELLULAR, 2777 metered: false, 2778 roaming: true, 2779 retry: true, 2780 redirect: true, 2781 index: 0, 2782 begins: 0, 2783 ends: -1, 2784 gauge: false, 2785 precise: false, 2786 token: "it is a secret" 2787 }; 2788 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2789 task.resume().then(() => { 2790 console.info(`Succeeded in resuming a download task. `); 2791 }).catch((err: BusinessError) => { 2792 console.error(`Failed to resume the download task, Code: ${err.code}, message: ${err.message}`); 2793 }); 2794 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2795 }).catch((err: BusinessError) => { 2796 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2797 }); 2798 ``` 2799 2800 2801### stop<sup>10+</sup> 2802 2803stop(callback: AsyncCallback<void>): void 2804 2805停止任务，可以停止正在运行/正在等待/正在重试的任务。使用callback异步回调。 2806 2807**系统能力**: SystemCapability.Request.FileTransferAgent 2808 2809**参数：** 2810 2811 | 参数名 | 类型 | 必填 | 说明 | 2812 | -------- | -------- | -------- | -------- | 2813 | callback | function | 是 | 回调函数，停止任务成功，err为undefined，否则为错误对象 | 2814 2815**错误码：** 2816 2817以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2818 2819 | 错误码ID | 错误信息 | 2820 | -------- | -------- | 2821 | 13400003 | task service ability error. | 2822 | 21900007 | task state error. | 2823 2824**示例：** 2825 2826 ```ts 2827 let config: request.agent.Config = { 2828 action: request.agent.Action.DOWNLOAD, 2829 url: 'http://127.0.0.1', 2830 title: 'taskStopTest', 2831 description: 'Sample code for stop the download task', 2832 mode: request.agent.Mode.BACKGROUND, 2833 overwrite: false, 2834 method: "GET", 2835 data: "", 2836 saveas: "./", 2837 network: request.agent.Network.CELLULAR, 2838 metered: false, 2839 roaming: true, 2840 retry: true, 2841 redirect: true, 2842 index: 0, 2843 begins: 0, 2844 ends: -1, 2845 gauge: false, 2846 precise: false, 2847 token: "it is a secret" 2848 }; 2849 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2850 task.stop((err: BusinessError) => { 2851 if (err) { 2852 console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`); 2853 return; 2854 } 2855 console.info(`Succeeded in stopping a download task. `); 2856 }); 2857 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2858 }).catch((err: BusinessError) => { 2859 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2860 }); 2861 ``` 2862 2863 2864### stop<sup>10+</sup> 2865 2866stop(): Promise<void> 2867 2868停止任务，可以停止正在运行/正在等待/正在重试的任务。使用Promise异步回调。 2869 2870**系统能力**: SystemCapability.Request.FileTransferAgent 2871 2872**返回值：** 2873 2874| 类型 | 说明 | 2875| ------------------- | ------------------------- | 2876| Promise<void> | Promise对象。无返回结果的Promise对象。 | 2877 2878**错误码：** 2879 2880以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2881 2882 | 错误码ID | 错误信息 | 2883 | -------- | -------- | 2884 | 13400003 | task service ability error. | 2885 | 21900007 | task state error. | 2886 2887**示例：** 2888 2889 ```ts 2890 let config: request.agent.Config = { 2891 action: request.agent.Action.DOWNLOAD, 2892 url: 'http://127.0.0.1', 2893 title: 'taskStopTest', 2894 description: 'Sample code for stop the download task', 2895 mode: request.agent.Mode.BACKGROUND, 2896 overwrite: false, 2897 method: "GET", 2898 data: "", 2899 saveas: "./", 2900 network: request.agent.Network.CELLULAR, 2901 metered: false, 2902 roaming: true, 2903 retry: true, 2904 redirect: true, 2905 index: 0, 2906 begins: 0, 2907 ends: -1, 2908 gauge: false, 2909 precise: false, 2910 token: "it is a secret" 2911 }; 2912 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 2913 task.stop().then(() => { 2914 console.info(`Succeeded in stopping a download task. `); 2915 }).catch((err: BusinessError) => { 2916 console.error(`Failed to stop the download task, Code: ${err.code}, message: ${err.message}`); 2917 }); 2918 console.info(`Succeeded in creating a download task. result: ${task.tid}`); 2919 }).catch((err: BusinessError) => { 2920 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2921 }); 2922 ``` 2923 2924## request.agent.create<sup>10+</sup> 2925 2926create(context: BaseContext, config: Config, callback: AsyncCallback<Task>): void 2927 2928创建要上传或下载的任务，并将其排入队列，每个应用最多支持创建10个未完成的任务。使用callback异步回调。 2929 2930 2931**需要权限**：ohos.permission.INTERNET 2932 2933**系统能力**: SystemCapability.Request.FileTransferAgent 2934 2935**参数：** 2936 2937 | 参数名 | 类型 | 必填 | 说明 | 2938 | -------- | -------- | -------- | -------- | 2939 | config | [Config](#config10) | 是 | 上传/下载任务的配置信息。 | 2940 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 2941 | callback | AsyncCallback<[Task](#task10)> | 是 | 回调函数，返回创建任务的配置信息。 | 2942 2943**错误码：** 2944 2945以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 2946 2947 | 错误码ID | 错误信息 | 2948 | -------- | -------- | 2949 | 13400001 | file operation error. | 2950 | 13400003 | task service ability error. | 2951 | 21900004 | application task queue full error. | 2952 | 21900005 | task mode error. | 2953 2954**示例：** 2955 2956 ```ts 2957 let attachments: Array<request.agent.FormItem> = [{ 2958 name: "createTest", 2959 value: { 2960 filename: "createTest.avi", 2961 mimeType: "application/octet-stream", 2962 path: "./createTest.avi", 2963 } 2964 }]; 2965 let config: request.agent.Config = { 2966 action: request.agent.Action.UPLOAD, 2967 url: 'http://127.0.0.1', 2968 title: 'createTest', 2969 description: 'Sample code for create task', 2970 mode: request.agent.Mode.BACKGROUND, 2971 overwrite: false, 2972 method: "PUT", 2973 data: attachments, 2974 saveas: "./", 2975 network: request.agent.Network.CELLULAR, 2976 metered: false, 2977 roaming: true, 2978 retry: true, 2979 redirect: true, 2980 index: 0, 2981 begins: 0, 2982 ends: -1, 2983 gauge: false, 2984 precise: false, 2985 token: "it is a secret" 2986 }; 2987 request.agent.create(getContext(), config, (err: BusinessError, task: request.agent.Task) => { 2988 if (err) { 2989 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 2990 return; 2991 } 2992 console.info(`Succeeded in creating a download task. result: ${task.config}`); 2993 }); 2994 ``` 2995 2996> **说明：** 2997> 2998> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 2999 3000## request.agent.create<sup>10+</sup> 3001 3002create(context: BaseContext, config: Config): Promise<Task> 3003 3004创建要上传或下载的任务，并将其排入队列，每个应用最多支持创建10个未完成的任务。使用Promise异步回调。 3005 3006 3007**需要权限**：ohos.permission.INTERNET 3008 3009**系统能力**: SystemCapability.Request.FileTransferAgent 3010 3011**参数：** 3012 3013 | 参数名 | 类型 | 必填 | 说明 | 3014 | -------- | -------- | -------- | -------- | 3015 | context | [BaseContext](js-apis-inner-application-baseContext.md) | 是 | 基于应用程序的上下文。 | 3016 | config | [Config](#config10) | 是 | 上传/下载任务的配置信息。 | 3017 3018**返回值：** 3019 3020| 类型 | 说明 | 3021| ------------------- | ------------------------- | 3022| Promise<[Task](#task10)> | Promise对象。返回任务配置信息的Promise对象。 | 3023 3024**错误码：** 3025 3026以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3027 3028 | 错误码ID | 错误信息 | 3029 | -------- | -------- | 3030 | 13400001 | file operation error. | 3031 | 13400003 | task service ability error. | 3032 | 21900004 | application task queue full error. | 3033 | 21900005 | task mode error. | 3034 3035**示例：** 3036 3037 ```ts 3038 let attachments: Array<request.agent.FormItem> = [{ 3039 name: "createTest", 3040 value: { 3041 filename: "createTest.avi", 3042 mimeType: "application/octet-stream", 3043 path: "./createTest.avi", 3044 } 3045 }]; 3046 let config: request.agent.Config = { 3047 action: request.agent.Action.UPLOAD, 3048 url: 'http://127.0.0.1', 3049 title: 'createTest', 3050 description: 'Sample code for create task', 3051 mode: request.agent.Mode.BACKGROUND, 3052 overwrite: false, 3053 method: "PUT", 3054 data: attachments, 3055 saveas: "./", 3056 network: request.agent.Network.CELLULAR, 3057 metered: false, 3058 roaming: true, 3059 retry: true, 3060 redirect: true, 3061 index: 0, 3062 begins: 0, 3063 ends: -1, 3064 gauge: false, 3065 precise: false, 3066 token: "it is a secret" 3067 }; 3068 request.agent.create(getContext(), config).then((task: request.agent.Task) => { 3069 console.info(`Succeeded in creating a download task. result: ${task.config}`); 3070 }).catch((err) => { 3071 console.error(`Failed to create a download task, Code: ${err.code}, message: ${err.message}`); 3072 }); 3073 ``` 3074 3075> **说明：** 3076> 3077> 示例中context的获取方式请参见[获取UIAbility的上下文信息](../../application-models/uiability-usage.md#获取uiability的上下文信息)。 3078 3079## request.agent.remove<sup>10+</sup> 3080 3081remove(id: string, callback: AsyncCallback<void>): void 3082 3083移除属于调用方的指定任务，如果正在处理中，该任务将被迫停止。使用callback异步回调。 3084 3085**系统能力**: SystemCapability.Request.FileTransferAgent 3086 3087**参数：** 3088 3089 | 参数名 | 类型 | 必填 | 说明 | 3090 | -------- | -------- | -------- | -------- | 3091 | id | string | 是 | 任务id。 | 3092 | callback | AsyncCallback<void> | 是 | 回调函数，删除指定任务成功，err为undefined，否则为错误对象。 | 3093 3094**错误码：** 3095 3096以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3097 3098 | 错误码ID | 错误信息 | 3099 | -------- | -------- | 3100 | 13400003 | task service ability error. | 3101 | 21900006 | task not found error. | 3102 3103**示例：** 3104 3105 ```ts 3106 request.agent.remove("123456", (err: BusinessError) => { 3107 if (err) { 3108 console.error(`Failed to removing a download task, Code: ${err.code}, message: ${err.message}`); 3109 return; 3110 } 3111 console.info(`Succeeded in creating a download task.`); 3112 }); 3113 ``` 3114 3115 3116## request.agent.remove<sup>10+</sup> 3117 3118remove(id: string): Promise<void> 3119 3120移除属于调用方的指定任务，如果正在处理中，该任务将被迫停止，使用Promise异步回调。 3121 3122**系统能力**: SystemCapability.Request.FileTransferAgent 3123 3124**参数：** 3125 3126 | 参数名 | 类型 | 必填 | 说明 | 3127 | -------- | -------- | -------- | -------- | 3128 | id | string | 是 | 任务id。 | 3129 3130**返回值：** 3131 3132| 类型 | 说明 | 3133| ------------------- | ------------------------- | 3134| Promise<void> | Promise对象。无返回结果的Promise对象。 | 3135 3136**错误码：** 3137 3138以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3139 3140 | 错误码ID | 错误信息 | 3141 | -------- | -------- | 3142 | 13400003 | task service ability error. | 3143 | 21900006 | task not found error. | 3144 3145**示例：** 3146 3147 ```ts 3148 request.agent.remove("123456").then(() => { 3149 console.info(`Succeeded in removing a download task. `); 3150 }).catch((err: BusinessError) => { 3151 console.error(`Failed to remove a download task, Code: ${err.code}, message: ${err.message}`); 3152 }); 3153 ``` 3154 3155 3156## request.agent.show<sup>10+</sup> 3157 3158show(id: string, callback: AsyncCallback<TaskInfo>): void 3159 3160根据任务id查询任务的详细信息。使用callback异步回调。 3161 3162**系统能力**: SystemCapability.Request.FileTransferAgent 3163 3164**参数：** 3165 3166 | 参数名 | 类型 | 必填 | 说明 | 3167 | -------- | -------- | -------- | -------- | 3168 | id | string | 是 | 任务id。 | 3169 | callback | AsyncCallback<TaskInfo> | 是 | 回调函数，返回任务详细信息。 | 3170 3171**错误码：** 3172以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3173 3174 | 错误码ID | 错误信息 | 3175 | -------- | -------- | 3176 | 13400003 | task service ability error. | 3177 | 21900006 | task not found error. | 3178 3179**示例：** 3180 3181 ```ts 3182 request.agent.show("123456", (err: BusinessError, taskInfo: request.agent.TaskInfo) => { 3183 if (err) { 3184 console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`); 3185 return; 3186 } 3187 console.info(`Succeeded in showing a upload task.`); 3188 }); 3189 ``` 3190 3191 3192## request.agent.show<sup>10+</sup> 3193 3194show(id: string): Promise<TaskInfo> 3195 3196根据任务id查询任务的详细信息。使用Promise异步回调。 3197 3198**系统能力**: SystemCapability.Request.FileTransferAgent 3199 3200**参数：** 3201 3202 | 参数名 | 类型 | 必填 | 说明 | 3203 | -------- | -------- | -------- | -------- | 3204 | id | string | 是 | 任务id。 | 3205 3206**返回值：** 3207 3208| 类型 | 说明 | 3209| ------------------- | ------------------------- | 3210| Promise<TaskInfo> | Promise对象。返回任务详细信息的Promise对象。 | 3211 3212**错误码：** 3213以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3214 3215 | 错误码ID | 错误信息 | 3216 | -------- | -------- | 3217 | 13400003 | task service ability error. | 3218 | 21900006 | task not found error. | 3219 3220**示例：** 3221 3222 ```ts 3223 request.agent.show("123456").then((taskInfo: request.agent.TaskInfo) => { 3224 console.info(`Succeeded in showing a upload task.`); 3225 }).catch((err: BusinessError) => { 3226 console.error(`Failed to show a upload task, Code: ${err.code}, message: ${err.message}`); 3227 }); 3228 ``` 3229 3230 3231## request.agent.touch<sup>10+</sup> 3232 3233touch(id: string, token: string, callback: AsyncCallback<TaskInfo>): void 3234 3235根据任务id和token查询任务的详细信息。使用callback异步回调。 3236 3237**系统能力**: SystemCapability.Request.FileTransferAgent 3238 3239**参数：** 3240 3241 | 参数名 | 类型 | 必填 | 说明 | 3242 | -------- | -------- | -------- | -------- | 3243 | id | string | 是 | 任务id。 | 3244 | token | string | 是 | 任务查询token。 | 3245 | callback | AsyncCallback<void> | 是 | 回调函数，返回任务详细信息。 | 3246 3247**错误码：** 3248以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3249 3250 | 错误码ID | 错误信息 | 3251 | -------- | -------- | 3252 | 13400003 | task service ability error. | 3253 | 21900006 | task not found error. | 3254 3255**示例：** 3256 3257 ```ts 3258 request.agent.touch("123456", "token", (err: BusinessError, taskInfo: request.agent.TaskInfo) => { 3259 if (err) { 3260 console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`); 3261 return; 3262 } 3263 console.info(`Succeeded in touching a upload task.`); 3264 }); 3265 ``` 3266 3267 3268## request.agent.touch<sup>10+</sup> 3269 3270touch(id: string, token: string): Promise<TaskInfo> 3271 3272根据任务id和token查询任务的详细信息。使用Promise异步回调。 3273 3274**系统能力**: SystemCapability.Request.FileTransferAgent 3275 3276**参数：** 3277 3278 | 参数名 | 类型 | 必填 | 说明 | 3279 | -------- | -------- | -------- | -------- | 3280 | id | string | 是 | 任务id。 | 3281 | token | string | 是 | 任务查询token。 | 3282 3283**返回值：** 3284 3285| 类型 | 说明 | 3286| ------------------- | ------------------------- | 3287| Promise<TaskInfo> | Promise对象。返回任务详细信息的Promise对象。 | 3288 3289**错误码：** 3290以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3291 3292 | 错误码ID | 错误信息 | 3293 | -------- | -------- | 3294 | 13400003 | task service ability error. | 3295 | 21900006 | task not found error. | 3296 3297**示例：** 3298 3299 ```ts 3300 request.agent.touch("123456", "token").then((taskInfo: request.agent.TaskInfo) => { 3301 console.info(`Succeeded in touching a upload task. `); 3302 }).catch((err: BusinessError) => { 3303 console.error(`Failed to touch a upload task, Code: ${err.code}, message: ${err.message}`); 3304 }); 3305 ``` 3306 3307## request.agent.search<sup>10+</sup> 3308 3309search(callback: AsyncCallback<Array<string>>): void 3310 3311根据默认[Filter](#filter10)过滤条件查找任务id。使用callback异步回调。 3312 3313**系统能力**: SystemCapability.Request.FileTransferAgent 3314 3315**参数：** 3316 3317 | 参数名 | 类型 | 必填 | 说明 | 3318 | -------- | -------- | -------- | -------- | 3319 | callback | AsyncCallback<Array<string>> | 是 | 回调函数，返回满足条件任务id。 | 3320 3321**错误码：** 3322以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3323 3324 | 错误码ID | 错误信息 | 3325 | -------- | -------- | 3326 | 13400003 | task service ability error. | 3327 3328**示例：** 3329 3330 ```ts 3331 request.agent.search((err: BusinessError, data: Array<string>) => { 3332 if (err) { 3333 console.error(`Failed to search a upload task, Code: ${err.code}, message: ${err.message}`); 3334 return; 3335 } 3336 console.info(`Succeeded in searching a upload task. `); 3337 }); 3338 ``` 3339 3340## request.agent.search<sup>10+</sup> 3341 3342search(filter: Filter, callback: AsyncCallback<Array<string>>): void 3343 3344根据[Filter](#filter10)过滤条件查找任务id。使用callback异步回调。 3345 3346**系统能力**: SystemCapability.Request.FileTransferAgent 3347 3348**参数：** 3349 3350 | 参数名 | 类型 | 必填 | 说明 | 3351 | -------- | -------- | -------- | -------- | 3352 | filter | [Filter](#filter10) | 是 | 过滤条件。 | 3353 | callback | AsyncCallback<Array<string>> | 是 | 回调函数，返回满足条件任务id。 | 3354 3355**错误码：** 3356以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3357 3358 | 错误码ID | 错误信息 | 3359 | -------- | -------- | 3360 | 13400003 | task service ability error. | 3361 3362**示例：** 3363 3364 ```ts 3365 let filter: request.agent.Filter = { 3366 bundle: "com.example.myapplication", 3367 action: request.agent.Action.UPLOAD, 3368 mode: request.agent.Mode.BACKGROUND 3369 } 3370 request.agent.search(filter, (err: BusinessError, data: Array<string>) => { 3371 if (err) { 3372 console.error(`Failed to search a upload task, Code: ${err.code}, message: ${err.message}`); 3373 return; 3374 } 3375 console.info(`Succeeded in searching a upload task. `); 3376 }); 3377 ``` 3378 3379 3380## request.agent.search<sup>10+</sup> 3381 3382search(filter?: Filter): Promise<Array<string>> 3383 3384根据[Filter](#filter10)过滤条件查找任务id。使用Promise异步回调。 3385 3386**系统能力**: SystemCapability.Request.FileTransferAgent 3387 3388**参数：** 3389 3390 | 参数名 | 类型 | 必填 | 说明 | 3391 | -------- | -------- | -------- | -------- | 3392 | filter | [Filter](#filter10) | 否 | 过滤条件。 | 3393 3394**返回值：** 3395 3396| 类型 | 说明 | 3397| ------------------- | ------------------------- | 3398| Promise<Array<string>> | Promise对象。返回满足条件任务id的Promise对象。 | 3399 3400**错误码：** 3401以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3402 3403 | 错误码ID | 错误信息 | 3404 | -------- | -------- | 3405 | 13400003 | task service ability error. | 3406 3407**示例：** 3408 3409 ```ts 3410 let filter: request.agent.Filter = { 3411 bundle: "com.example.myapplication", 3412 action: request.agent.Action.UPLOAD, 3413 mode: request.agent.Mode.BACKGROUND 3414 } 3415 request.agent.search(filter).then((data: Array<string>) => { 3416 console.info(`Succeeded in searching a upload task. `); 3417 }).catch((err: BusinessError) => { 3418 console.error(`Failed to search a upload task, Code: ${err.code}, message: ${err.message}`); 3419 }); 3420 ``` 3421 3422 3423## request.agent.query<sup>10+</sup> 3424 3425query(id: string, callback: AsyncCallback<TaskInfo>): void 3426 3427根据任务id查询任务的详细信息。使用callback异步回调。 3428 3429**需要权限**：ohos.permission.DOWNLOAD_SESSION_MANAGER 或 ohos.permission.UPLOAD_SESSION_MANAGER 3430 3431**系统能力**: SystemCapability.Request.FileTransferAgent 3432 3433**系统接口**：此接口为系统接口。 3434 3435**参数：** 3436 3437 | 参数名 | 类型 | 必填 | 说明 | 3438 | -------- | -------- | -------- | -------- | 3439 | id | string | 是 | 任务id。 | 3440 | callback | AsyncCallback<TaskInfo> | 是 | 回调函数，返回任务详细信息。 | 3441 3442**错误码：** 3443以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3444 3445 | 错误码ID | 错误信息 | 3446 | -------- | -------- | 3447 | 13400003 | task service ability error. | 3448 | 21900006 | task not found error. | 3449 3450**示例：** 3451 3452 ```ts 3453 request.agent.query("123456", (err: BusinessError, taskInfo: request.agent.TaskInfo) => { 3454 if (err) { 3455 console.error(`Failed to query a upload task, Code: ${err.code}, message: ${err.message}`); 3456 return; 3457 } 3458 console.info(`Succeeded in querying a upload task. result: ${taskInfo.uid}`); 3459 }); 3460 ``` 3461 3462 3463## request.agent.query<sup>10+</sup> 3464 3465query(id: string): Promise<TaskInfo> 3466 3467根据任务id查询任务的详细信息。使用Promise异步回调。 3468 3469**需要权限**：ohos.permission.DOWNLOAD_SESSION_MANAGER 或 ohos.permission.UPLOAD_SESSION_MANAGER 3470 3471**系统能力**: SystemCapability.Request.FileTransferAgent 3472 3473**系统接口**：此接口为系统接口。 3474 3475**参数：** 3476 3477 | 参数名 | 类型 | 必填 | 说明 | 3478 | -------- | -------- | -------- | -------- | 3479 | id | string | 是 | 任务id。 | 3480 3481**返回值：** 3482 3483| 类型 | 说明 | 3484| ------------------- | ------------------------- | 3485| Promise<TaskInfo> | Promise对象。返回任务详细信息的Promise对象。 | 3486 3487**错误码：** 3488以下错误码的详细介绍请参见[上传下载错误码](../errorcodes/errorcode-request.md)。 3489 3490 | 错误码ID | 错误信息 | 3491 | -------- | -------- | 3492 | 13400003 | task service ability error. | 3493 | 21900006 | task not found error. | 3494 3495**示例：** 3496 3497 ```ts 3498 request.agent.query("123456").then((taskInfo: request.agent.TaskInfo) => { 3499 console.info(`Succeeded in querying a upload task. result: ${taskInfo.uid}`); 3500 }).catch((err: BusinessError) => { 3501 console.error(`Failed to query a upload task, Code: ${err.code}, message: ${err.message}`); 3502 }); 3503 ``` 3504 3505<!--no_check-->
