1# @system.request (上传下载)
2
3system.request部件主要给应用提供上传下载文件的基础能力。
4
5> **说明：**
6> - 从API Version 9开始所有接口不再维护，推荐使用新接口[`@ohos.request`](js-apis-request.md)。
7>
8> - 本模块首批接口从API version 3开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
9
10
11## 导入模块
12
13
14```
15import request from '@system.request';
16```
17
18## request.upload<sup>(deprecated)</sup>
19
20upload(options: UploadRequestOptions): void
21
22上传文件，无返回值。
23
24**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload
25
26**参数：**
27
28  | 参数名 | 类型 | 必填 | 说明 |
29  | -------- | -------- | -------- | -------- |
30  | options | [UploadRequestOptions](#uploadrequestoptionsdeprecated) | 是 | 上传的配置信息。 |
31
32**示例：**
33
34  ```js
35  import request, { UploadRequestOptions } from '@system.request';
36
37  let uploadRequestOptions: UploadRequestOptions = {
38    url: 'http://www.path.com',
39    method: 'POST',
40    files: [{
41      filename: "test",
42      name: "test",
43      uri: "internal://cache/test.jpg",
44      type: "jpg"
45    }],
46    data: [{
47      name: "name123",
48      value: "123"
49    }],
50    success: (data: object) => {
51      console.info(' upload success, code:' + JSON.stringify(data));
52    },
53    fail: (data:string, code:number) => {
54      console.info(' upload fail data: ' + data + 'code: ' + code);
55    },
56    complete: () => {
57      console.info(' upload complete');
58    }
59  }
60
61  try {
62    request.upload(uploadRequestOptions);
63    console.info('upload start ');
64  } catch (err) {
65    console.info(' upload err:' + err);
66  }
67  ```
68
69
70## UploadRequestOptions<sup>(deprecated)</sup>
71
72**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。
73
74
75  | 名称 | 类型 | 必填 | 说明 |
76  | -------- | -------- | -------- | -------- |
77  | url | string | 是 | 上传服务器地址。 |
78  | data | Array&lt;[RequestData](#requestdatadeprecated)&gt; | 否 | 请求的表单数据。 |
79  | files | Array&lt;[RequestFile](#requestfiledeprecated)&gt; | 是 | 待上传文件列表。请使用multipart/form-data进行提交。 |
80  | header | Object | 否 | 请求头。 |
81  | method | string | 否 | 请求方法：POST、PUT。缺省POST。 |
82  | success | Function | 否 | 接口调用成功的回调函数。 |
83  | fail | Function | 否 | 接口调用失败的回调函数。 |
84  | complete | Function | 否 | 接口调用结束的回调函数。 |
85
86**success参数：**
87  | 参数名 | 类型 | 必填 | 说明 |
88  | -------- | -------- | -------- | -------- |
89  | data | [UploadResponse](#uploadresponsedeprecated) | 是 | 上传任务成功返回信息。 |
90
91**fail参数：**
92  | 参数名 | 类型 | 必填 | 说明 |
93  | -------- | -------- | -------- | -------- |
94  | data | any | 是 | 上传任务失败返回header信息。 |
95  | code | number | 是 | 上传任务失败返回HTTP状态码。 |
96
97
98
99## UploadResponse<sup>(deprecated)</sup>
100
101**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。
102
103  | 名称 | 类型 | 必填 | 说明 |
104  | -------- | -------- | -------- | -------- |
105  | code | number | 是 | 服务器返回的HTTP状态码。 |
106  | data | string | 是 | 服务器返回的内容。根据返回头内容中的type决定该值的类型。 |
107  | headers | Object | 是 | 服务器返回的返回头内容。 |
108
109
110## RequestFile<sup>(deprecated)</sup>
111
112**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。
113
114  | 名称 | 类型 | 必填 | 说明 |
115  | -------- | -------- | -------- | -------- |
116  | filename | string | 否 | multipart&nbsp;提交时，请求头中的文件名。 |
117  | name | string | 否 | multipart&nbsp;提交时，表单项目的名称，缺省为file。 |
118  | uri | string | 是 | 文件的本地存储路径。 |
119  | type | string | 否 | 文件的内容类型，默认根据文件名或路径的后缀获取。 |
120
121
122## RequestData<sup>(deprecated)</sup>
123
124**系统能力**: SystemCapability.MiscServices.Upload。
125
126  | 名称 | 类型 | 必填 | 说明 |
127  | -------- | -------- | -------- | -------- |
128  | name | string | 是 | 表示form&nbsp;元素的名称。 |
129  | value | string | 是 | 表示form&nbsp;元素的值。 |
130
131
132
133## request.download<sup>(deprecated)</sup>
134
135download(options: DownloadRequestOptions): void
136
137下载文件，无返回值。
138
139**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download
140
141**参数：**
142
143  | 参数名 | 类型 | 必填 | 说明 |
144  | -------- | -------- | -------- | -------- |
145  | options | [DownloadRequestOptions](#downloadrequestoptionsdeprecated) | 是 | 下载的配置信息。 |
146
147**示例：**
148
149  ```js
150  import request, { DownloadRequestOptions } from '@system.request';
151
152  let downloadRequestOptions: DownloadRequestOptions = {
153    url: 'http://www.path.com',
154    filename: 'requestSystenTest',
155    header: "",
156    description: 'this is requeSystem download response',
157    success: (data:object) => {
158      console.info(' download success, code:' + JSON.stringify(data));
159    },
160    fail: (data:string, code:number) => {
161      console.info(' download fail data: ' + data + 'code: ' + code);
162    },
163    complete: () => {
164      console.info(' download complete');
165    }
166  }
167
168  try {
169    request.download(downloadRequestOptions);
170    console.info('download start ');
171  } catch(err) {
172    console.info(' download err:' + err);
173  }
174  ```
175
176
177## DownloadRequestOptions<sup>(deprecated)</sup>
178
179**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。
180
181  | 名称 | 类型 | 必填 | 说明 |
182  | -------- | -------- | -------- | -------- |
183  | url | string | 是 | 资源地址。 |
184  | filename | string | 否 | 本次下载文件的名称。默认从本次请求或资源地址中获取。 |
185  | header | Object | 否 | 请求头。 |
186  | description | string | 否 | 资源地址的下载描述，默认为文件名称。 |
187  | success | Function | 否 | 接口调用成功的回调函数。 |
188  | fail | Function | 否 | 接口调用失败的回调函数。 |
189  | complete | Function | 否 | 接口调用结束的回调函数。 |
190
191**success参数：**
192  | 参数名 | 类型 | 必填 | 说明 |
193  | -------- | -------- | -------- | -------- |
194  | data | [DownloadResponse](#downloadresponsedeprecated) | 是 | 下载任务成功返回信息。 |
195
196**fail参数：**
197  | 参数名 | 类型 | 必填 | 说明 |
198  | -------- | -------- | -------- | -------- |
199  | data | any | 是 | 下载任务失败返回header信息。 |
200  | code | number | 是 | 下载任务失败返回HTTP状态码。 |
201
202## DownloadResponse<sup>(deprecated)</sup>
203
204**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。
205
206  | 名称 | 类型 | 必填 | 说明 |
207  | -------- | -------- | -------- | -------- |
208  | token | string | 是 | 表示下载的token，获取下载状态的依据。 |
209
210
211## request.onDownloadComplete<sup>(deprecated)</sup>
212
213onDownloadComplete(options: OnDownloadCompleteOptions): void
214
215获取下载任务状态，无返回值。
216
217**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download
218
219**参数：**
220
221  | 参数名 | 类型 | 必填 | 说明 |
222  | -------- | -------- | -------- | -------- |
223  | options | [OnDownloadCompleteOptions](#ondownloadcompleteoptionsdeprecated) | 是 | 监听下载任务的配置信息。 |
224
225**示例：**
226
227  ```js
228  import request, { OnDownloadCompleteOptions } from '@system.request';
229
230  let onDownloadCompleteOptions: OnDownloadCompleteOptions = {
231    token: 'token-index',
232    success: (data:object) => {
233      console.info(' download success, code:' + JSON.stringify(data));
234    },
235    fail: (data:string, code:number) => {
236      console.info(' download fail data: ' + data + 'code: ' + code);
237    },
238    complete: () => {
239      console.info(' download complete');
240    }
241  }
242
243  request.onDownloadComplete(onDownloadCompleteOptions);
244  ```
245
246
247## OnDownloadCompleteOptions<sup>(deprecated)</sup>
248
249**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。
250
251  | 名称 | 类型 | 必填 | 说明 |
252  | -------- | -------- | -------- | -------- |
253  | token | string | 是 | download&nbsp;接口返回的结果&nbsp;token。 |
254  | success | Function | 否 | 接口调用成功的回调函数。 |
255  | fail | Function | 否 | 接口调用失败的回调函数。 |
256  | complete | Function | 否 | 接口调用结束的回调函数。 |
257
258**success参数：**
259  | 参数名 | 类型 | 必填 | 说明 |
260  | -------- | -------- | -------- | -------- |
261  | data | [OnDownloadCompleteResponse](#ondownloadcompleteresponsedeprecated) | 是 | 下载任务成功返回信息。 |
262
263**fail参数：**
264  | 参数名 | 类型 | 必填 | 说明 |
265  | -------- | -------- | -------- | -------- |
266  | data | any | 是 | 下载任务失败返回header信息。 |
267  | code | number | 是 | 下载任务失败返回HTTP状态码。 |
268
269
270## OnDownloadCompleteResponse<sup>(deprecated)</sup>
271
272**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。
273
274  | 名称 | 类型 | 必填 | 说明 |
275  | -------- | -------- | -------- | -------- |
276  | uri | string | 是 | 表示下载文件的uri。 |