Browse Source

Update npm README.md

Ben Hsieh 8 years ago
parent
commit
e2fab41dc3
1 changed files with 69 additions and 20 deletions
  1. 69
    20
      src/README.md

+ 69
- 20
src/README.md View File

1
-# react-native-fetch-blob [![npm](https://img.shields.io/npm/v/react-native-fetch-blob.svg?style=flat-square)](https://www.npmjs.com/package/react-native-fetch-blob) ![](https://img.shields.io/badge/PR-Welcome-brightgreen.svg?style=flat-square) [![npm](https://img.shields.io/npm/l/express.svg?maxAge=2592000&style=flat-square)]() [![npm](https://img.shields.io/badge/inProgress-0.7.0-yellow.svg?style=flat-square)](https://github.com/wkh237/react-native-fetch-blob/milestones)
1
+# react-native-fetch-blob [![release](https://img.shields.io/github/release/wkh237/react-native-fetch-blob.svg?maxAge=86400&style=flat-square)](https://www.npmjs.com/package/react-native-fetch-blob) [![npm](https://img.shields.io/npm/v/react-native-fetch-blob.svg?style=flat-square)](https://www.npmjs.com/package/react-native-fetch-blob) ![](https://img.shields.io/badge/PR-Welcome-brightgreen.svg?style=flat-square) [![npm](https://img.shields.io/npm/l/express.svg?maxAge=2592000&style=flat-square)]() [![npm](https://img.shields.io/badge/inProgress-0.7.0-yellow.svg?style=flat-square)](https://github.com/wkh237/react-native-fetch-blob/milestones)
2
 
2
 
3
 A module provides upload, download, and files access API. Supports file stream read/write for process large files.
3
 A module provides upload, download, and files access API. Supports file stream read/write for process large files.
4
 
4
 
5
 ## [Please check our github for updated document](https://github.com/wkh237/react-native-fetch-blob)
5
 ## [Please check our github for updated document](https://github.com/wkh237/react-native-fetch-blob)
6
 
6
 
7
-**Why do we need this**
8
-
9
-React Native does not support `Blob` object at this moment, which means if you're going to send/receive binary data via `fetch` API, that might not work as you expect. See [facebook/react-native#854](https://github.com/facebook/react-native/issues/854).
10
-
11
-For some use cases, you might get into trouble. For example, displaying an image that requires a specific field in headers (ex. "Authorization : Bearer ...") or body, so you can't just pass the image uri to `Image` component because that will probably returns a 401 response. Or you're going to upload binary data which generated from JS, the server will get an empry body due to [this issue](https://github.com/facebook/react-native/issues/854). With help of APIs provided by this module, you can send HTTP request with any headers, and decide how to handle the response/reqeust data without worry about if it is not supported by `fetch` API. The response data can be just simply converted into BASE64 string, or stored to a file directly so that you can read it by using file access APIs such as readFile, readStream.
12
-
13
-This module was designed to be a substitution of `Blob`, there's a set of APIs including basic file system CRUD method, and file stream reader/writer. Also it has a special `fetch` implementation that supports binary request/response body.
14
-
15
-**Backward Compatible**
16
-
17
-All updates are `backward-compatible` generally you don't have to change existing code unless you're going to use new APIs. But we recommend pre `0.5.0` users consider upgrade the package to latest version, since we have introduced new APIs can either `upload` or `download` files simply using a file path. It's much more memory efficent in some use case. We've also introduced `fs` APIs for access files, and `file stream` API that helps you read/write files (especially for **large ones**), see [Examples](#user-content-recipes) bellow. This module implements native methods, supports both Android (uses awesome native library  [AsyncHttpClient](https://github.com/AsyncHttpClient/async-http-client])) and IOS.
18
-
19
 ## TOC
7
 ## TOC
20
-
8
+* [About](#user-content-about)
9
+* [Backward Compatible](#user-content-backward-compatible)
21
 * [Installation](#user-content-installation)
10
 * [Installation](#user-content-installation)
22
 * [Recipes](#user-content-recipes)
11
 * [Recipes](#user-content-recipes)
23
  * [Download file](#user-content-download-example--fetch-files-that-needs-authorization-token)
12
  * [Download file](#user-content-download-example--fetch-files-that-needs-authorization-token)
24
  * [Upload file](#user-content-upload-example--dropbox-files-upload-api)
13
  * [Upload file](#user-content-upload-example--dropbox-files-upload-api)
25
  * [Multipart/form upload](#user-content-multipartform-data-example--post-form-data-with-file-and-data)
14
  * [Multipart/form upload](#user-content-multipartform-data-example--post-form-data-with-file-and-data)
26
  * [Upload/Download progress](#user-content-uploaddownload-progress)
15
  * [Upload/Download progress](#user-content-uploaddownload-progress)
16
+ * [Cancel HTTP request](#user-content-cancel-request)
27
  * [Android Media Scanner, and Download Manager Support](#user-content-android-media-scanner-and-download-manager-support)
17
  * [Android Media Scanner, and Download Manager Support](#user-content-android-media-scanner-and-download-manager-support)
28
  * [File access](#user-content-file-access)
18
  * [File access](#user-content-file-access)
29
  * [File stream](#user-content-file-stream)
19
  * [File stream](#user-content-file-stream)
30
  * [Manage cached files](#user-content-cache-file-management)
20
  * [Manage cached files](#user-content-cache-file-management)
31
  * [Self-Signed SSL Server](#user-content-self-signed-ssl-server)
21
  * [Self-Signed SSL Server](#user-content-self-signed-ssl-server)
32
 * [API References](https://github.com/wkh237/react-native-fetch-blob/wiki/Fetch-API)
22
 * [API References](https://github.com/wkh237/react-native-fetch-blob/wiki/Fetch-API)
23
+* [Trouble Shooting](https://github.com/wkh237/react-native-fetch-blob/wiki/Trouble-Shooting)
33
 * [Development](#user-content-development)
24
 * [Development](#user-content-development)
34
 
25
 
26
+## About
27
+
28
+React Native does not support `Blob` object at this moment, which means if you're going to send/receive binary data via `fetch` API, that might not work as you expect. See [facebook/react-native#854](https://github.com/facebook/react-native/issues/854).
29
+
30
+For some use cases, you might get into trouble. For example, displaying an image that requires a specific field in headers (ex. "Authorization : Bearer ...") or body, so you can't just pass the image uri to `Image` component because that will probably returns a 401 response. Or you're going to upload binary data which generated from JS, the server will get an empry body due to [this issue](https://github.com/facebook/react-native/issues/854). With help of APIs provided by this module, you can send HTTP request with any headers, and decide how to handle the response/reqeust data without worry about if it is not supported by `fetch` API. The response data can be just simply converted into BASE64 string, or stored to a file directly so that you can read it by using file access APIs such as readFile, readStream.
31
+
32
+This module was designed to be a substitution of `Blob`, there's a set of APIs including basic file system CRUD method, and file stream reader/writer. Also it has a special `fetch` implementation that supports binary request/response body.
33
+
34
+## Backward Compatible
35
+
36
+All updates are `backward-compatible` generally you don't have to change existing code unless you're going to use new APIs. But we recommend pre `0.5.0` users consider upgrade the package to latest version, since we have introduced new APIs can either `upload` or `download` files simply using a file path. It's much more memory efficent in some use case. We've also introduced `fs` APIs for access files, and `file stream` API that helps you read/write files (especially for **large ones**), see [Examples](#user-content-recipes) bellow. This module implements native methods, supports both Android (uses same native library as offical RN fetch API [OkHttp](https://github.com/square/okhttp)) and IOS.
37
+
35
 ## Installation
38
 ## Installation
36
 
39
 
37
 Install package from npm
40
 Install package from npm
46
 rnpm link
49
 rnpm link
47
 ```
50
 ```
48
 
51
 
52
+### For React Native >= 0.29.0 (Android)
53
+
54
+> If you're using react-native >= `0.29.0`, the package might not be able to link through `rnpm link`, and you might see an error screen similar to [#51](https://github.com/wkh237/react-native-fetch-blob/issues/51), this is because a [a bug in 0.29.0](https://github.com/facebook/react-native/commit/4dabb575b1b311ba541fae7eabbd49f08b5391b3), someone has already fixed it, but the solution does not work on our project, you may have to manually add the package yourself.
55
+
56
+Add this code to `MainApplication.java`
57
+
58
+```diff
59
+...
60
++ import com.RNFetchBlob.RNFetchBlobPackage;                                                                                 
61
+...
62
+protected List<ReactPackage> getPackages() {
63
+      return Arrays.<ReactPackage>asList(
64
+          new MainReactPackage(),
65
++          new RNFetchBlobPackage()                                                                                         
66
+      );
67
+    }
68
+  };
69
+...
70
+```
71
+> If you still having problem on installing this package, please check the [trouble shooting page](https://github.com/wkh237/react-native-fetch-blob/wiki/Trouble-Shooting) or [file an issue](https://github.com/wkh237/react-native-fetch-blob/issues/new)
72
+
49
 **Grant Permission to External storage for Android 5.0 or lower**
73
 **Grant Permission to External storage for Android 5.0 or lower**
50
 
74
 
51
-Mechanism about granting Android permissions has slightly different since Android 6.0 released, please refer to [Officail Document](https://developer.android.com/training/permissions/requesting.html).
75
+Mechanism about granting Android permissions has slightly different since Android 6.0 released, please refer to [Official Document](https://developer.android.com/training/permissions/requesting.html).
52
 
76
 
53
-If you're going to access external storage (say, SD card storage) for `Android 5.0` (or lower) devices, you might have to add the following line to `AndroidManifetst.xml`.
77
+If you're going to access external storage (say, SD card storage) for `Android 5.0` (or lower) devices, you might have to add the following line to `AndroidManifest.xml`.
54
 
78
 
55
 ```diff
79
 ```diff
56
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
80
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
112
 
136
 
113
 #### Download to storage directly
137
 #### Download to storage directly
114
 
138
 
115
-The simplest way is give a `fileCach` option to config, and set it to `true`. This will let the incoming response data stored in a temporary path **wihout** any file extension.
139
+The simplest way is give a `fileCache` option to config, and set it to `true`. This will let the incoming response data stored in a temporary path **without** any file extension.
116
 
140
 
117
 **These files won't be removed automatically, please refer to [Cache File Management](#user-content-cache-file-management)**
141
 **These files won't be removed automatically, please refer to [Cache File Management](#user-content-cache-file-management)**
118
 
142
 
151
     console.log('The file saved to ', res.path())
175
     console.log('The file saved to ', res.path())
152
     // Beware that when using a file path as Image source on Android,
176
     // Beware that when using a file path as Image source on Android,
153
     // you must prepend "file://"" before the file path
177
     // you must prepend "file://"" before the file path
154
-    imageView = <Image source={{ uri : Platform.OS === 'android' ? 'file://' : '' + res.path() }}/>
178
+    imageView = <Image source={{ uri : Platform.OS === 'android' ? 'file://' + res.path()  : '' + res.path() }}/>
155
   })
179
   })
156
 ```
180
 ```
157
 
181
 
299
 
323
 
300
 #### Upload/Download progress
324
 #### Upload/Download progress
301
 
325
 
302
-In `version >= 0.4.2` it is possible to know the upload/download progress. On Anroid, only download progress is supported. See [wiki](https://github.com/wkh237/react-native-fetch-blob/wiki/Fetch-API#fetchprogresseventlistenerpromisernfetchblobresponse) for more information.
326
+In `version >= 0.4.2` it is possible to know the upload/download progress. After `0.7.0` IOS and Android upload progress are supported.
303
 
327
 
304
 ```js
328
 ```js
305
   RNFetchBlob.fetch('POST', 'http://www.example.com/upload', {
329
   RNFetchBlob.fetch('POST', 'http://www.example.com/upload', {
306
       ... some headers,
330
       ... some headers,
307
       'Content-Type' : 'octet-stream'
331
       'Content-Type' : 'octet-stream'
308
     }, base64DataString)
332
     }, base64DataString)
333
+    // listen to upload progress event
334
+    .uploadProgress((written, total) => {
335
+        console.log('uploaded', written / total)
336
+    })
337
+    // listen to download progress event
309
     .progress((received, total) => {
338
     .progress((received, total) => {
310
         console.log('progress', received / total)
339
         console.log('progress', received / total)
311
     })
340
     })
317
     })
346
     })
318
 ```
347
 ```
319
 
348
 
349
+#### Cancel Request
350
+
351
+After `0.7.0` it is possible to cancel a HTTP request. When the request cancel, it will definately throws an promise rejection, be sure to catch it.
352
+
353
+```js
354
+let task = RNFetchBlob.fetch('GET', 'http://example.com/file/1')
355
+
356
+task.then(() => { ... })
357
+    // handle request cancelled rejection
358
+    .catch((err) => {
359
+        console.log(err)
360
+    })
361
+// cancel the request, the callback function is optional
362
+task.cancel((err) => { ... })
363
+
364
+```
365
+
320
 #### Android Media Scanner, and Download Manager Support
366
 #### Android Media Scanner, and Download Manager Support
321
 
367
 
322
 If you want to make a file in `External Storage` becomes visible in Picture, Downloads, or other built-in apps, you will have to use `Media Scanner` or `Download Manager`.
368
 If you want to make a file in `External Storage` becomes visible in Picture, Downloads, or other built-in apps, you will have to use `Media Scanner` or `Download Manager`.
403
 
449
 
404
 File access APIs were made when developing `v0.5.0`, which helping us write tests, and was not planned to be a part of this module. However we realized that, it's hard to find a great solution to manage cached files, every one who use this moudle may need these APIs for there cases.
450
 File access APIs were made when developing `v0.5.0`, which helping us write tests, and was not planned to be a part of this module. However we realized that, it's hard to find a great solution to manage cached files, every one who use this moudle may need these APIs for there cases.
405
 
451
 
406
-Before get started using file APIs we recommend read [Differences between File Source](https://github.com/wkh237/react-native-fetch-blob/wiki/File-System-Access-API#differences-between-file-source) first.
452
+Before start using file APIs, we recommend read [Differences between File Source](https://github.com/wkh237/react-native-fetch-blob/wiki/File-System-Access-API#differences-between-file-source) first.
407
 
453
 
408
 File Access APIs
454
 File Access APIs
409
 - [asset (0.6.2)](https://github.com/wkh237/react-native-fetch-blob/wiki/File-System-Access-API#assetfilenamestringstring)
455
 - [asset (0.6.2)](https://github.com/wkh237/react-native-fetch-blob/wiki/File-System-Access-API#assetfilenamestringstring)
551
 
597
 
552
 | Version | |
598
 | Version | |
553
 |---|---|
599
 |---|---|
600
+| 0.7.0 | Add support of Android upload progress, and remove AsyncHttpClient dependency from Android native implementation. |
601
+| 0.6.4 | Fix rnpm link script. |
602
+| 0.6.3 | Fix performance issue on IOS, increase max concurrent request limitation from 1. |
554
 | 0.6.2 | Add support of asset file and camera roll files, Support custom MIME type when sending multipart request, thanks @smartt |
603
 | 0.6.2 | Add support of asset file and camera roll files, Support custom MIME type when sending multipart request, thanks @smartt |
555
 | 0.6.1 | Fix #37 progress report API issue on IOS |
604
 | 0.6.1 | Fix #37 progress report API issue on IOS |
556
 | 0.6.0 | Add readFile and writeFile API for easier file access, also added Android download manager support. |
605
 | 0.6.0 | Add readFile and writeFile API for easier file access, also added Android download manager support. |