!12245 【仅md格式规范】system.request文档整改

Merge pull request !12245 from ann_lesley/master

!12245 【仅md格式规范】system.request文档整改
Merge pull request !12245 from ann_lesley/master
fa9affed · openharmony_ci · Gitee · db2f54f2 · 3aa18cdf · fa9affed
隐藏空白更改
内联并排

Showing with 202 addition and 134 deletion

zh-cn/application-dev/reference/apis/js-apis-system-request.md .../application-dev/reference/apis/js-apis-system-request.md +202 -134

未找到文件。
--- a/zh-cn/application-dev/reference/apis/js-apis-system-request.md
+++ b/zh-cn/application-dev/reference/apis/js-apis-system-request.md
 # 上传下载

+system.request部件主要给应用提供上传下载文件的基础能力。
+
 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
-> - 从API Version 6开始，该接口不再维护，推荐使用新接口[`@ohos.request`](js-apis-request.md)。
+> - 从API Version 9开始所有接口不再维护，推荐使用新接口[`@ohos.request`](js-apis-request.md)。
 > 
-> - 本模块首批接口从API version 4开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
+> - 本模块首批接口从API version 3开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。


 ## 导入模块
@@ -13,179 +15,245 @@
 import request from '@system.request';
 ```

-## 权限列表
+## request.upload

-ohos.permission.INTERNET。
+upload(options: UploadRequestOptions): void

+上传文件，无返回值。

-## request.upload
+**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload

-upload(Object): void
+**参数：**

-上传文件。
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | options | [UploadRequestOptions](#uploadrequestoptions) | 是 | 上传的配置信息。 |

-**参数：**
+**示例：**

-| 参数名 | 类型 | 必填 | 说明 |
-| -------- | -------- | -------- | -------- |
-| url | string | 是 | 上传服务器地址。 |
-| header | Object | 否 | 请求头。 |
-| method | string | 否 | 请求方法：POST、PUT。缺省POST。 |
-| files | Array&lt;File&gt; | 是 | 待上传文件列表。请使用multipart/form-data进行提交。 |
-| data | Array&lt;RequestData&gt; | 否 | 请求的表单数据。 |
-| success | Function | 否 | 接口调用成功的回调函数。 |
-| fail | Function | 否 | 接口调用失败的回调函数。 |
-| complete | Function | 否 | 接口调用结束的回调函数。 |
+  ```js
+  let uploadRequestOptions = {
+    url: 'http://www.path.com',
+    method: 'POST',
+    files: [{ filename: "test", name: "test", uri: "internal://cache/test.jpg", type: "jpg" }],
+    data: [{ name: "name123", value: "123" }],
+    success: function(data) {
+      console.info(' upload success, code:' + JSON.stringify(data));
+    },
+    fail: function(data, code) {
+      console.info(' upload fail data: ' + data + 'code: ' + code);
+    },
+    complete: function (){
+      console.info(' upload complete');
+    }
+  }
+  try {
+    request.upload(uploadRequestOptions);
+    console.info('upload start ');
+  } catch(err) {
+    console.info(' upload err:' + err);
+  }
+  ```
+  

-**表1** File
+## UploadRequestOptions

-| 参数名 | 类型 | 必填 | 说明 |
-| -------- | -------- | -------- | -------- |
-| filename | string | 否 | multipart&nbsp;提交时，请求头中的文件名。 |
-| name | string | 否 | multipart&nbsp;提交时，表单项目的名称，缺省为file。 |
-| uri | string | 是 | 文件的本地存储路径。 |
-| type | string | 否 | 文件的内容类型，默认根据文件名或路径的后缀获取。 |
+**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。

-**表2** RequestData

-| 参数名 | 类型 | 必填 | 说明 |
-| -------- | -------- | -------- | -------- |
-| name | string | 是 | 表示form&nbsp;元素的名称。 |
-| value | string | 是 | 表示form&nbsp;元素的值。 |
+  | 名称 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | url | string | 是 | 上传服务器地址。 |
+  | data | Array&lt;[RequestData](#requestdata)&gt; | 否 | 请求的表单数据。 |
+  | files | Array&lt;[RequestFile](#requestfile)&gt; | 是 | 待上传文件列表。请使用multipart/form-data进行提交。 |
+  | header | Object | 否 | 请求头。 |
+  | method | string | 否 | 请求方法：POST、PUT。缺省POST。 |
+  | success | Function | 否 | 接口调用成功的回调函数。 |
+  | fail | Function | 否 | 接口调用失败的回调函数。 |
+  | complete | Function | 否 | 接口调用结束的回调函数。 |

-success返回值：
+**success参数：**
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | data | [UploadResponse](#uploadresponse) | 是 | 上传任务成功返回信息。 |

-| 参数名 | 类型 | 说明 |
-| -------- | -------- | -------- |
-| code | number | 服务器返回的HTTP状态码。 |
-| data | string | 服务器返回的内容。根据返回头内容中的type决定该值的类型。 |
-| headers | Object | 服务器返回的返回头内容。 |
+**fail参数：**
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | data | any | 是 | 上传任务失败返回header信息。 |
+  | code | number | 是 | 上传任务失败返回HTTP状态码。 |

-fail返回值中的data中的code为HTTP状态码。

-**示例：**

-```
-export default {    
-  upLoad() {
-    request.upload({
-      url: 'http://www.path.com',
-      files: [
-        {
-           uri: 'internal://cache/path/to/file.txt',
-           name: 'file',
-           filename: 'file.txt',
-        },
-      ],
-      data:[
-        {
-          name: 'name1',
-          value: 'value',
-         },
-       ],
-       success: function(data) {
-         console.log('upload success, code:' + data.code);
-       },
-       fail: function() {
-         console.log('upload fail');
-       },
-     });
-  }
-}
-```
+## UploadResponse

+**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。

-## request.download
+  | 名称 | 类型 | 说明 |
+  | -------- | -------- | -------- |
+  | code | number | 服务器返回的HTTP状态码。 |
+  | data | string | 服务器返回的内容。根据返回头内容中的type决定该值的类型。 |
+  | headers | Object | 服务器返回的返回头内容。 |

-download(Object): void

-下载文件。
+## RequestFile

-**参数：**
+**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Upload。
+
+  | 名称 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | filename | string | 否 | multipart&nbsp;提交时，请求头中的文件名。 |
+  | name | string | 否 | multipart&nbsp;提交时，表单项目的名称，缺省为file。 |
+  | uri | string | 是 | 文件的本地存储路径。 |
+  | type | string | 否 | 文件的内容类型，默认根据文件名或路径的后缀获取。 |
+
+
+## RequestData
+
+**系统能力**: SystemCapability.MiscServices.Upload。

-| 参数名 | 类型 | 必填 | 说明 |
-| -------- | -------- | -------- | -------- |
-| url | string | 是 | 资源地址。 |
-| header | Object | 否 | 请求头。 |
-| description | string | 否 | 资源地址的下载描述，默认为文件名称。 |
-| filename | string | 否 | 本次下载文件的名称。默认从本次请求或资源地址中获取。 |
-| success | Function | 否 | 接口调用成功的回调函数。 |
-| fail | Function | 否 | 接口调用失败的回调函数。 |
-| complete | Function | 否 | 接口调用结束的回调函数。 |
+  | 名称 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | name | string | 是 | 表示form&nbsp;元素的名称。 |
+  | value | string | 是 | 表示form&nbsp;元素的值。 |

-success返回值：

-| 参数名 | 类型 | 说明 |
-| -------- | -------- | -------- |
-| token | string | 表示下载的&nbsp;token，获取下载状态的依据。 |

-fail返回错误代码：
+## request.download
+
+download(options: DownloadRequestOptions): void
+
+下载文件，无返回值。
+
+**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download
+
+**参数：**

-| 错误码 | 说明 |
-| -------- | -------- |
-| 400 | 表示下载任务失败。 |
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | options | [DownloadRequestOptions](#downloadrequestoptions) | 是 | 下载的配置信息。 |

 **示例：**

-```
-export default {    
-  downLoad() {        
-    request.download({            
-      url: 'http://www.path.com',            
-      success: function(data) {                
-        console.log('call success callback success: ' + data.token);            
-      },            
-      fail: function(data, code) {                
-        console.log('handling fail');            
-      },        
-    });    
+  ```js
+  let downloadRequestOptions = {
+    url: 'http://www.path.com',
+    filename: 'requestSystenTest',
+    header: '',
+    description: 'this is requeSystem download response',
+    success: function(data) {
+      console.info(' download success, code:' + JSON.stringify(data));
+    },
+    fail: function(data, code) {
+      console.info(' download fail data: ' + data + 'code: ' + code);
+    },
+    complete: function (){
+      console.info(' download complete');
+    }
  }
-}
-```
+  try {
+    request.download(downloadRequestOptions);
+    console.info('download start ');
+  } catch(err) {
+    console.info(' download err:' + err);
+  }
+  ```


-## request.onDownloadComplete
+## DownloadRequestOptions

-onDownloadComplete(Object): void
+**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。

-获取下载任务状态。
+  | 名称 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | url | string | 是 | 资源地址。 |
+  | filename | string | 否 | 本次下载文件的名称。默认从本次请求或资源地址中获取。 |
+  | header | Object | 否 | 请求头。 |
+  | description | string | 否 | 资源地址的下载描述，默认为文件名称。 |
+  | success | Function | 否 | 接口调用成功的回调函数。 |
+  | fail | Function | 否 | 接口调用失败的回调函数。 |
+  | complete | Function | 否 | 接口调用结束的回调函数。 |

-**参数：**
+**success参数：**
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | data | [DownloadResponse](#downloadresponse) | 是 | 下载任务成功返回信息。 |
+
+**fail参数：**
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | data | any | 是 | 下载任务失败返回header信息。 |
+  | code | number | 是 | 下载任务失败返回HTTP状态码。 |
+
+## DownloadResponse
+
+**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。
+
+  | 名称 | 类型 | 说明 |
+  | -------- | -------- | -------- |
+  | token | string | 表示下载的token，获取下载状态的依据。 |
+
+
+## request.onDownloadComplete

-| 参数名 | 类型 | 必填 | 说明 |
-| -------- | -------- | -------- | -------- |
-| token | string | 是 | download&nbsp;接口返回的结果&nbsp;token。 |
-| success | Function | 否 | 接口调用成功的回调函数。 |
-| fail | Function | 否 | 接口调用失败的回调函数。 |
-| complete | Function | 否 | 接口调用结束的回调函数。 |
+onDownloadComplete(options: OnDownloadCompleteOptions): void

-success返回值：
+获取下载任务状态，无返回值。

-| 参数名 | 类型 | 说明 |
-| -------- | -------- | -------- |
-| uri | string | 表示下载文件的uri。 |
+**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download

-fail返回错误代码：
+**参数：**

-| 错误码 | 说明 |
-| -------- | -------- |
-| 400 | 表示下载任务失败。 |
-| 401 | 表示不存在该下载任务。 |
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | options | [OnDownloadCompleteOptions](#ondownloadcompleteoptions) | 是 | 监听下载任务的配置信息。 |

 **示例：**

-```
-export default {    
-  onDownloadComplete() {        
-    request.onDownloadComplete({            
-      token: 'token-index',            
-      success: function(data) {                
-        console.log('download success, uri:' + data.uri);            
-      },            
-      fail: function(data, code) {                
-        console.log('download fail');            
-      },
-    });    
+  ```js
+  let onDownloadCompleteOptions = {
+    token: 'token-index',
+    success: function(data) {
+      console.info(' download success, code:' + JSON.stringify(data));
+    },
+    fail: function(data, code) {
+      console.info(' download fail data: ' + data + 'code: ' + code);
+    },
+    complete: function (){
+      console.info(' download complete');
+    }
  }
-}
-```
\ No newline at end of file
+  request.onDownloadComplete(onDownloadCompleteOptions);
+  ```
+
+
+## OnDownloadCompleteOptions
+
+**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。
+
+  | 名称 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | token | string | 是 | download&nbsp;接口返回的结果&nbsp;token。 |
+  | success | Function | 否 | 接口调用成功的回调函数。 |
+  | fail | Function | 否 | 接口调用失败的回调函数。 |
+  | complete | Function | 否 | 接口调用结束的回调函数。 |
+
+**success参数：**
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | data | [OnDownloadCompleteResponse](#ondownloadcompleteresponse) | 是 | 下载任务成功返回信息。 |
+
+**fail参数：**
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | data | any | 是 | 下载任务失败返回header信息。 |
+  | code | number | 是 | 下载任务失败返回HTTP状态码。 |
+
+
+## OnDownloadCompleteResponse
+
+**系统能力**: 以下各项对应的系统能力均为SystemCapability.MiscServices.Download。
+
+  | 名称 | 类型 | 说明 |
+  | -------- | -------- | -------- |
+  | uri | string | 表示下载文件的uri。 |
\ No newline at end of file