Browse Source

Update README.md

wkh237 8 years ago
parent
commit
d06620c013
1 changed files with 39 additions and 39 deletions
  1. 39
    39
      README.md

+ 39
- 39
README.md View File

4
 
4
 
5
 A project committed to make file access and data transfer easier, efficient for React Native developers.
5
 A project committed to make file access and data transfer easier, efficient for React Native developers.
6
 
6
 
7
-> If you're going to use github repo as npm dependency please visit the [archive repository](https://github.com/wkh237/react-native-fetch-blob-package/releases/tag/v0.9.6).
7
+> If you're going to use GitHub repo as npm dependency please visit the [archive repository](https://github.com/wkh237/react-native-fetch-blob-package/releases/tag/v0.9.6).
8
 
8
 
9
 > For Firebase Storage solution, please upgrade to latest version for best compatibility.
9
 > For Firebase Storage solution, please upgrade to latest version for best compatibility.
10
 
10
 
42
 
42
 
43
 ## About
43
 ## About
44
 
44
 
45
-This project was initially for solving the issue [facebook/react-native#854](https://github.com/facebook/react-native/issues/854), because React Native lack of `Blob` implementation and it will cause some problem when transferring binary data. Now, this project is committed to make file access and transfer more easier, efficient for React Native developers. We've implemented highly customizable filesystem and network module which plays well together. For example, upload and download data directly from/to storage which is much more efficient in some cases(especially for large ones). The file system supports file stream, so you don't have to worry about OOM problem when accessing large files.
45
+This project was initially for solving the issue [facebook/react-native#854](https://github.com/facebook/react-native/issues/854) because React Native lack of `Blob` implementation and it will cause some problem when transferring binary data. Now, this project is committed to making file access and transfer easier, efficient for React Native developers. We've implemented highly customizable filesystem and network module which plays well together. For example, upload and download data directly from/to storage which is much more efficient in some cases(especially for large ones). The file system supports file stream, so you don't have to worry about OOM problem when accessing large files.
46
 
46
 
47
 In `0.8.0` we introduced experimental Web API polyfills that make it possible to use browser-based libraries in React Native, such as, [FireBase JS SDK](https://github.com/wkh237/rn-firebase-storage-upload-sample)
47
 In `0.8.0` we introduced experimental Web API polyfills that make it possible to use browser-based libraries in React Native, such as, [FireBase JS SDK](https://github.com/wkh237/rn-firebase-storage-upload-sample)
48
 
48
 
64
 
64
 
65
 **Automatically Link Native Modules**
65
 **Automatically Link Native Modules**
66
 
66
 
67
-For 0.29.2+ projects, simply link native packages via following command because rnpm has been merged into react-native, you no longer need it.
67
+For 0.29.2+ projects, simply link native packages via the following command because rnpm has been merged into react-native, you no longer need it.
68
 
68
 
69
 ```
69
 ```
70
 react-native link
70
 react-native link
88
 RNFB_ANDROID_PERMISSIONS=true rnpm link
88
 RNFB_ANDROID_PERMISSIONS=true rnpm link
89
 ```
89
 ```
90
 
90
 
91
-The link script might not take effect if you have non-default project structure, please visit [the wiki](https://github.com/wkh237/react-native-fetch-blob/wiki/Manually-Link-Package) to manually link the pacakge.
91
+The link script might not take effect if you have non-default project structure, please visit [the wiki](https://github.com/wkh237/react-native-fetch-blob/wiki/Manually-Link-Package) to manually link the package.
92
 
92
 
93
 **Grant Permission to External storage for Android 5.0 or lower**
93
 **Grant Permission to External storage for Android 5.0 or lower**
94
 
94
 
95
-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).
95
+Mechanism for granting Android permissions has slightly different since Android 6.0 released, please refer to [Official Document](https://developer.android.com/training/permissions/requesting.html).
96
 
96
 
97
 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`.
97
 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`.
98
 
98
 
123
 
123
 
124
 **Grant Access Permission for Android 6.0**
124
 **Grant Access Permission for Android 6.0**
125
 
125
 
126
-Beginning in Android 6.0 (API level 23), users grant permissions to apps while the app is running, not when they install the app. So adding permissions in `AndroidManifest.xml` won't work in Android 6.0 devices. To grant permissions in runtime, you might use modules like [react-native-android-permissions](https://github.com/lucasferreira/react-native-android-permissions).
126
+Beginning in Android 6.0 (API level 23), users grant permissions to apps while the app is running, not when they install the app. So adding permissions in `AndroidManifest.xml` won't work f Android 6.0 devices. To grant permissions in runtime, you might use modules like [react-native-android-permissions](https://github.com/lucasferreira/react-native-android-permissions).
127
 
127
 
128
 ## Usage
128
 ## Usage
129
 
129
 
148
 
148
 
149
 ### Regular Request
149
 ### Regular Request
150
 
150
 
151
-After `0.8.0` react-native-fetch-blob automatically decide how to send the body by checking its type and `Content-Type` in header. The rule is described in the following diagram
151
+After `0.8.0` react-native-fetch-blob automatically decide how to send the body by checking its type and `Content-Type` in the header. The rule is described in the following diagram
152
 
152
 
153
 <img src="img/RNFB-flow (1).png" style="width : 90%" />
153
 <img src="img/RNFB-flow (1).png" style="width : 90%" />
154
 
154
 
155
-To sum up :
155
+To sum up:
156
 
156
 
157
-- To send a form data, the `Content-Type` header does not matters. When the body is an `Array` we will set proper content type for you.
157
+- To send a form data, the `Content-Type` header does not matter. When the body is an `Array` we will set proper content type for you.
158
 - To send binary data, you have two choices, use BASE64 encoded string or path points to a file contains the body.
158
 - To send binary data, you have two choices, use BASE64 encoded string or path points to a file contains the body.
159
  - If the `Content-Type` containing substring`;BASE64` or `application/octet` the given body will be considered as a BASE64 encoded data which will be decoded to binary data as the request body.   
159
  - If the `Content-Type` containing substring`;BASE64` or `application/octet` the given body will be considered as a BASE64 encoded data which will be decoded to binary data as the request body.   
160
- - Otherwise, if a string starts with `RNFetchBlob-file://` (which can simply done by `RNFetchBlob.wrap(PATH_TO_THE_FILE)`), it will try to find the data from the URI string after `RNFetchBlob-file://` and use it as request body.
160
+ - Otherwise, if a string starts with `RNFetchBlob-file://` (which can simply be done by `RNFetchBlob.wrap(PATH_TO_THE_FILE)`), it will try to find the data from the URI string after `RNFetchBlob-file://` and use it as the request body.
161
 - To send the body as-is, simply use a `Content-Type` header not containing `;BASE64` or `application/octet`.
161
 - To send the body as-is, simply use a `Content-Type` header not containing `;BASE64` or `application/octet`.
162
 
162
 
163
-> It is Worth to mentioning that the HTTP request uses cache by default, if you're going to disable it simply add a Cache Control header `'Cache-Control' : 'no-store'`
163
+> It is Worth to mentioning that the HTTP request uses cache by default, if you're going to disable it simply add a Cache-Control header `'Cache-Control' : 'no-store'`
164
 
164
 
165
 > After 0.9.4, we disabled `Chunked` transfer encoding by default, if you're going to use it, you should explicitly set header `Transfer-Encoding` to `Chunked`.
165
 > After 0.9.4, we disabled `Chunked` transfer encoding by default, if you're going to use it, you should explicitly set header `Transfer-Encoding` to `Chunked`.
166
 
166
 
167
-### Download example : Fetch files that needs authorization token
167
+### Download example: Fetch files that need authorization token
168
 
168
 
169
 Most simple way is download to memory and stored as BASE64 encoded string, this is handy when the response data is small.
169
 Most simple way is download to memory and stored as BASE64 encoded string, this is handy when the response data is small.
170
 
170
 
214
 
214
 
215
 **Set Temp File Extension**
215
 **Set Temp File Extension**
216
 
216
 
217
-Sometimes you might need a file extension for some reason. For example, when using file path as source of `Image` component, the path should end with something like .png or .jpg, you can do this by add `appendExt` option to `config`.
217
+Sometimes you might need a file extension for some reason. For example, when using file path as the source of `Image` component, the path should end with something like .png or .jpg, you can do this by add `appendExt` option to `config`.
218
 
218
 
219
 ```js
219
 ```js
220
 RNFetchBlob
220
 RNFetchBlob
259
 
259
 
260
 ####  Upload example : Dropbox [files-upload](https://www.dropbox.com/developers/documentation/http/documentation#files-upload) API
260
 ####  Upload example : Dropbox [files-upload](https://www.dropbox.com/developers/documentation/http/documentation#files-upload) API
261
 
261
 
262
-`react-native-fetch-blob` will convert the base64 string in `body` to binary format using native API, this process will be  done in a separated thread, so it won't block your GUI.
262
+`react-native-fetch-blob` will convert the base64 string in `body` to binary format using native API, this process will be done in a separated thread, so it won't block your GUI.
263
 
263
 
264
 ```js
264
 ```js
265
 
265
 
310
   })
310
   })
311
 ```
311
 ```
312
 
312
 
313
-### Multipart/form-data example : Post form data with file and data
313
+### Multipart/form-data example: Post form data with file and data
314
 
314
 
315
 In `version >= 0.3.0` you can also post files with form data, just put an array in `body`, with elements have property `name`, `data`, and `filename`(optional).
315
 In `version >= 0.3.0` you can also post files with form data, just put an array in `body`, with elements have property `name`, `data`, and `filename`(optional).
316
 
316
 
317
-Elements have property `filename` will be transformed into binary format, otherwise it turns into utf8 string.
317
+Elements have property `filename` will be transformed into binary format, otherwise, it turns into utf8 string.
318
 
318
 
319
 ```js
319
 ```js
320
 
320
 
342
   })
342
   })
343
 ```
343
 ```
344
 
344
 
345
-What if you want to append a file to form data ? Just like [upload a file from storage](#user-content-upload-a-file-from-storage) example, wrap `data` by `wrap` API (this feature is only available for `version >= v0.5.0`). On version >= `0.6.2`, it is possible to set custom MIME type when appending file to form data. But keep in mind when the file is large it's likely crash your app. Please consider use other strategy (see [#94](https://github.com/wkh237/react-native-fetch-blob/issues/94)).
345
+What if you want to append a file to form data? Just like [upload a file from storage](#user-content-upload-a-file-from-storage) example, wrap `data` by `wrap` API (this feature is only available for `version >= v0.5.0`). On version >= `0.6.2`, it is possible to set custom MIME type when appending a file to form data. But keep in mind when the file is large it's likely to crash your app. Please consider use other strategy (see [#94](https://github.com/wkh237/react-native-fetch-blob/issues/94)).
346
 
346
 
347
 ```js
347
 ```js
348
 
348
 
406
     })
406
     })
407
 ```
407
 ```
408
 
408
 
409
-In `0.9.6`, you can specify an object as first argument which contains `count` and `interval`, to the frequency of progress event (this will be done in native context in order to reduce RCT bridge overhead). Notice that `count` argument will not work if the server does not provide response content length.
409
+In `0.9.6`, you can specify an object as the first argument which contains `count` and `interval`, to the frequency of progress event (this will be done in the native context  a  reduce RCT bridge overhead). Notice that `count` argument will not work if the server does not provide response content length.
410
 
410
 
411
 
411
 
412
 ```js
412
 ```js
432
 
432
 
433
 ### Cancel Request
433
 ### Cancel Request
434
 
434
 
435
-After `0.7.0` it is possible to cancel an HTTP request. When the request is cancelled, it will throw a promise rejection, be sure to catch it.
435
+After `0.7.0` it is possible to cancel an HTTP request. When the request is canceled, it will throw a promise rejection, be sure to catch it.
436
 
436
 
437
 ```js
437
 ```js
438
 let task = RNFetchBlob.fetch('GET', 'http://example.com/file/1')
438
 let task = RNFetchBlob.fetch('GET', 'http://example.com/file/1')
461
 
461
 
462
 **Media Scanner**
462
 **Media Scanner**
463
 
463
 
464
-Media scanner scan the file and categorize by given MIME type, if MIME type not specified, it will try to resolve the file using its file extension.
464
+Media scanner scans the file and categorize by given MIME type, if MIME type not specified, it will try to resolve the file using its file extension.
465
 
465
 
466
 ```js
466
 ```js
467
 
467
 
482
 
482
 
483
 **Download Manager**
483
 **Download Manager**
484
 
484
 
485
-When download large files on Android it is recommended to use `Download Manager`, it supports lot of native features like progress bar, and notification, also the download task will be handled by OS, and more effective.
485
+When downloading large files on Android it is recommended to use `Download Manager`, it supports a lot of native features like the progress bar, and notification, also the download task will be handled by OS, and more effective.
486
 
486
 
487
 <img src="img/download-manager.png" width="256">
487
 <img src="img/download-manager.png" width="256">
488
 
488
 
509
 ```
509
 ```
510
 
510
 
511
 
511
 
512
-**Download Notification and Visibiliy in Download App (Android Only)**
512
+**Download Notification and Visibility in Download App (Android Only)**
513
 
513
 
514
 <img src="img/android-notification1.png" width="256">
514
 <img src="img/android-notification1.png" width="256">
515
 <img src="img/android-notification2.png" width="256">
515
 <img src="img/android-notification2.png" width="256">
516
 
516
 
517
 
517
 
518
-If you want to display a notification when file's completely download to storage (as the above), or make the downloaded file visible in "Downloads" app. You have to add some options to `config`.
518
+If you want to display a notification when the file is completely download to storage (as the above) or make the downloaded file visible in "Downloads" app. You have to add some options to `config`.
519
 
519
 
520
 ```js
520
 ```js
521
 RNFetchBlob.config({
521
 RNFetchBlob.config({
539
 
539
 
540
 **Open Downloaded File with Intent**
540
 **Open Downloaded File with Intent**
541
 
541
 
542
-This is a new feature added in `0.9.0`, if you're going to open a file path using official [Linking](https://facebook.github.io/react-native/docs/linking.html) API that might not work as expected, also, if you're going to install an APK in `Downloads` app, that will not work too. As an alternative, you can try `actionViewIntent` API, which will send an ACTION_VIEW intent for you which uses the given `MIME` type.
542
+This is a new feature added in `0.9.0` if you're going to open a file path using official [Linking](https://facebook.github.io/react-native/docs/linking.html) API that might not work as expected, also, if you're going to install an APK in `Downloads` app, that will not work too. As an alternative, you can try `actionViewIntent` API, which will send an ACTION_VIEW intent for you which uses the given `MIME` type.
543
 
543
 
544
-Download and install an APK programatically
544
+Download and install an APK programmatically
545
 
545
 
546
 ```js
546
 ```js
547
 
547
 
573
 
573
 
574
 ### File Access
574
 ### File Access
575
 
575
 
576
-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.
576
+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, everyone who uses this module may need these APIs for there cases.
577
 
577
 
578
 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.
578
 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.
579
 
579
 
601
 
601
 
602
 ### File Stream
602
 ### File Stream
603
 
603
 
604
-In `v0.5.0` we've added  `writeStream` and `readStream`, which allows your app read/write data from file path. This API creates a file stream, rather than convert whole data into BASE64 encoded string, it's handy when processing **large files**.
604
+In `v0.5.0` we've added  `writeStream` and `readStream`, which allows your app read/write data from the file path. This API creates a file stream, rather than convert whole data into BASE64 encoded string, it's handy when processing **large files**.
605
 
605
 
606
-When calling `readStream` method, you have to `open` the stream, and start to read data. When the file is large, consider use an appropriate `bufferSize` and `interval` to reduce the native event dispatching overhead (see [Performance Tips](#user-content-performance-tips))
606
+When calling `readStream` method, you have to `open` the stream, and start to read data. When the file is large, consider using an appropriate `bufferSize` and `interval` to reduce the native event dispatching overhead (see [Performance Tips](#user-content-performance-tips))
607
 
607
 
608
 ```js
608
 ```js
609
 let data = ''
609
 let data = ''
631
 })
631
 })
632
 ```
632
 ```
633
 
633
 
634
-When use `writeStream`, the stream is also opened immediately, but you have to `write`, and `close` by yourself.
634
+When using `writeStream`, the stream is also opened immediately, but you have to `write`, and `close` by yourself.
635
 
635
 
636
 ```js
636
 ```js
637
 RNFetchBlob.fs.writeStream(
637
 RNFetchBlob.fs.writeStream(
650
 
650
 
651
 ### Cache File Management
651
 ### Cache File Management
652
 
652
 
653
-When using `fileCache` or `path` options along with `fetch` API, response data will automatically stored into file system. The files will **NOT** removed unless you `unlink` it. There're several ways to remove the files
653
+When using `fileCache` or `path` options along with `fetch` API, response data will automatically store into the file system. The files will **NOT** removed unless you `unlink` it. There're several ways to remove the files
654
 
654
 
655
 ```js
655
 ```js
656
 
656
 
671
 
671
 
672
 ```
672
 ```
673
 
673
 
674
-You can also grouping requests by using `session` API, and use `dispose` to remove them all when needed.
674
+You can also group requests by using `session` API and use `dispose` to remove them all when needed.
675
 
675
 
676
 ```js
676
 ```js
677
 
677
 
707
 
707
 
708
 ### Transfer Encoding
708
 ### Transfer Encoding
709
 
709
 
710
-After `0.9.4`, the `Chunked` transfer encoding is disabled by default due to some service provoder may not support chunked transfer. To enable it, set `Transfer-Encoding` header to `Chunked`.
710
+After `0.9.4`, the `Chunked` transfer encoding is disabled by default due to some service provider may not support chunked transfer. To enable it, set `Transfer-Encoding` header to `Chunked`.
711
 
711
 
712
 ```js
712
 ```js
713
 RNFetchBlob.fetch('POST', 'http://example.com/upload', { 'Transfer-Encoding' : 'Chunked' }, bodyData)
713
 RNFetchBlob.fetch('POST', 'http://example.com/upload', { 'Transfer-Encoding' : 'Chunked' }, bodyData)
740
 
740
 
741
 **Read Stream and Progress Event Overhead**
741
 **Read Stream and Progress Event Overhead**
742
 
742
 
743
-When reading data via `fs.readStream` the process seems blocking JS thread when file is large, it's because the default buffer size is quite small (4kb) which result in large amount of events triggered in JS thread, try to increase the buffer size (for example 100kb = 102400) and set a larger interval (which is introduced in 0.9.4 default value is 10ms) to limit the frequency.
743
+When reading data via `fs.readStream` the process seems to block JS thread when file is large, it's because the default buffer size is quite small (4kb) which result in large amount of events triggered in JS thread, try to increase the buffer size (for example 100kb = 102400) and set a larger interval (which is introduced in 0.9.4 default value is 10ms) to limit the frequency.
744
 
744
 
745
 **Reduce RCT Bridge and BASE64 Overhead**
745
 **Reduce RCT Bridge and BASE64 Overhead**
746
 
746
 
747
-React Native connects JS and Native context by passing JSON around React Native bridge, and there will be an overhead to convert data before they sent to each side. When data is large, this will be quite a performance impact to your app, it's recommended to use file storage instead of BASE64 if possible.The following chart shows how much faster when loading data from storage than BASE64 encoded string on iphone 6.
747
+React Native connects JS and Native context by passing JSON around React Native bridge, and there will be an overhead to convert data before they sent to each side. When data is large, this will be quite a performance impact to your app, it's recommended to use file storage instead of BASE64 if possible.The following chart shows how much faster when loading data from storage than BASE64 encoded string on iPhone 6.
748
 
748
 
749
 <img src="img/performance_1.png" style="width : 100%"/>
749
 <img src="img/performance_1.png" style="width : 100%"/>
750
 
750
 
756
 
756
 
757
 **Concate and Replacing Files**
757
 **Concate and Replacing Files**
758
 
758
 
759
-If you're going to concatenate files, you don't have to read the data to JS context anymore ! In `0.8.0` we introduced new encoding `uri` for writeFile and appendFile API. Which make it possible to done the whole process in native.
759
+If you're going to concatenate files, you don't have to read the data to JS context anymore! In `0.8.0` we introduced new encoding `uri` for writeFile and appendFile API. Which make it possible to done the whole process in native.
760
 
760
 
761
 <img src="img/performance_f2f.png" style="width : 100%"/>
761
 <img src="img/performance_f2f.png" style="width : 100%"/>
762
 
762
 
763
 ## Caveats
763
 ## Caveats
764
 
764
 
765
 * This library does not urlencode unicode characters in URL automatically, see [#146](https://github.com/wkh237/react-native-fetch-blob/issues/146).
765
 * This library does not urlencode unicode characters in URL automatically, see [#146](https://github.com/wkh237/react-native-fetch-blob/issues/146).
766
-* When a `Blob` is created from existing file, the file **WILL BE REMOVE** if you `close` the blob.
767
-* If you replaced `window.XMLHttpRequest` for some reason (e.g. make Firebase SDK work), it will also effect how official `fetch` works (basically it should work just fine).
768
-* When file stream and upload/download progress event slow down your app, consider upgrade to `0.9.6+`, use [additional arguments](https://github.com/wkh237/react-native-fetch-blob/wiki/Fetch-API#fetchprogressconfig-eventlistenerpromisernfetchblobresponse) to limit its frequency.
766
+* When a `Blob` ,  from existing file, the file **WILL BE REMOVE** if you `close` the blob.
767
+* If you replaced `window.XMLHttpRequest` for some reason (e.g. make Firebase SDK work), it will also affect how official `fetch` works (basically it should work just fine).
768
+* When file stream and upload/download progress event slow down your app, consider an upgrade to `0.9.6+`, use [additional arguments](https://github.com/wkh237/react-native-fetch-blob/wiki/Fetch-API#fetchprogressconfig-eventlistenerpromisernfetchblobresponse) to limit its frequency.
769
 * When passing a file path to the library, remove `file://` prefix.
769
 * When passing a file path to the library, remove `file://` prefix.
770
 
770
 
771
-when you got problem, have a look at [Trouble Shooting](https://github.com/wkh237/react-native-fetch-blob/wiki/Trouble-Shooting) or [issues labeled Trouble Shooting](https://github.com/wkh237/react-native-fetch-blob/issues?utf8=✓&q=label%3A%22trouble%20shooting%22%20), there'd be some helpful information.
771
+when you got problem, have a look at [Trouble Shooting](https://github.com/wkh237/react-native-fetch-blob/wiki/Trouble-Shooting) or [issues labeled Trouble Shooting](https://github.com/wkh237/react-native-fetch-blob/issues?utf8=✓&q=label:%22trouble%20shooting%22%20), there'd be some helpful information.
772
 
772
 
773
 ## Changes
773
 ## Changes
774
 
774