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