You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Mar 16, 2019. It is now read-only.
This project was initially for solving the issue [facebook/react-native#854](https://github.com/facebook/react-native/issues/854), because React Native does not support `Blob`object and it will cause some problem when sending and receiving binary data. There's aleady [a PR ](https://github.com/facebook/react-native/pull/8324) merged into RN master branch which will probably solving the issue in the near future.
39
+
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 transfering binary data. Now, this project is committed to make file access and transfer more easier, effiecient 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.
28
40
29
-
Now, this project is committed to make file acess and transfer more easier and more effiecient for React Native developers. We've implemented lot of file access function which plays well with our network module. For example, it can upload and download data directly into/from file system, which is much more performant (especially for large ones) than converting data to BASE64 passing them around through React JS Bridge, also, file stream support so that you can read large file not causing OOM error.
41
+
In `0.8.0` we introduced experimential Web API polyfills that make it possible to use browser-based libraries in React Native, for example, [FireBase JS SDK](https://github.com/wkh237/rn-firebase-storage-upload-sample)
30
42
31
43
## Installation
32
44
@@ -42,17 +54,6 @@ Link package using [rnpm](https://github.com/rnpm/rnpm)
42
54
rnpm link
43
55
```
44
56
45
-
### version 0.7.0+ does not work with react-native 0.27 (Android)
46
-
47
-
On 0.7.5, we have fixed Android OkHttp dependency issue on pre 0.28 projects excepted 0.27, 0.29.0, and 0.29.1. For 0.29.0 and 0.29.1 it's because `rnpm link` is broken in these versions, you may need to manually link Android package. It is recommended to upgrade you project if possible
48
-
49
-
```
50
-
$ react-native upgrade
51
-
```
52
-
53
-
After the project upgraded, run `rnpm link` again.
54
-
55
-
56
57
### Manually link the package (Android)
57
58
58
59
If rnpm link command failed to link the package automatically, you might try manually link the package.
@@ -135,8 +136,28 @@ If you're using ES5 require statement to load the module, please add `default`.
135
136
var RNFetchBlob = require('react-native-fetch-blob').default
136
137
```
137
138
139
+
### HTTP Data Transfer
140
+
141
+
---
142
+
143
+
#### Regular Request
144
+
145
+
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
- To send a form data, the `Content-Type` header won't take effect if the body is an `Array` because we will set proper content type for you.
152
+
- To send binary data, you have two choices, use BASE64 encoded string or a file path which points to a file contains the body. The `Content-Type` header does not matters.
153
+
- The body is a BASE64 encoded string, the `Content-Type` header filed must containing substring`;BASE64` or `application/octet`
154
+
- The body is a path point to a file, it must be a string starts with `RNFetchBlob-file://`, which can simply done by `RNFetchBlob.wrap(PATH_TO_THE_FILE)`
155
+
- To send the body as-is, set a `Content-Type` header not containing `;BASE64` or `application/octet`.
156
+
138
157
#### Download example : Fetch files that needs authorization token
139
158
159
+
Most simple way is download to memory and stored as BASE64 encoded string, this is handy when the response data is small.
160
+
140
161
```js
141
162
142
163
// send http request in a new thread (using native code)
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.
185
+
If the response data is large, that would be a bad idea to convert it into BASE64 string. The better solution is store the response data directly into file system. The simplest way is give a `fileCache` option to config, and set it to `true`. This will make incoming response data stored in a temporary path **without** any file extension.
165
186
166
187
**These files won't be removed automatically, please refer to [Cache File Management](#user-content-cache-file-management)**
167
188
@@ -206,7 +227,7 @@ RNFetchBlob
206
227
207
228
**Use Specific File Path**
208
229
209
-
If you prefer a specific path rather than random generated one, you can use `path` option. We've added a constant [dirs](#user-content-dirs) in v0.5.0 that contains several common used directories.
230
+
If you prefer a specific path rather than randomly generated one, you can use `path` option. We've added a constant [dirs](#user-content-dirs) in v0.5.0 that contains several common used directories.
210
231
211
232
```js
212
233
let dirs =RNFetchBlob.fs.dirs
@@ -294,6 +315,10 @@ Elements have property `filename` will be transformed into binary format, otherw
294
315
}, [
295
316
// element with property `filename` will be transformed into `file` in form data
296
317
{ name :'avatar', filename :'avatar.png', data: binaryDataInBase64},
318
+
// custom content type
319
+
{ name :'avatar-png', filename :'avatar-png.png', type:'image/png', data: binaryDataInBase64},
320
+
// part file from storage
321
+
{ name :'avatar-foo', filename :'avatar-foo.png', type:'image/foo', data:RNFetchBlob.wrap(path_to_a_file)},
297
322
// elements without property `filename` will be sent as plain text
298
323
{ name :'name', data :'user'},
299
324
{ name :'info', data :JSON.stringify({
@@ -470,6 +495,8 @@ RNFetchBlob.config({
470
495
.then(...)
471
496
```
472
497
498
+
### File System
499
+
473
500
#### File Access
474
501
475
502
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.
@@ -618,10 +645,40 @@ RNFetchBlob.config({
618
645
})
619
646
```
620
647
648
+
### Web API Polyfills
649
+
650
+
After `0.8.0` we've made some [Web API polyfills](https://github.com/wkh237/react-native-fetch-blob/wiki/Web-API-Polyfills-(work-in-progress)) that makes some browser-based library available in RN.
651
+
652
+
- Blob
653
+
- XMLHttpRequest (Use our implementation if you're going to use it with Blob)
654
+
655
+
### Performance Tips
656
+
657
+
---
658
+
659
+
**Reduce RCT Bridge Overhead and BASE64 Time**
660
+
661
+
React Native connects JS and Native context by passing JSON through React bridge, therefore there will be an overhead to convert data before they sent. 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.
Due to the [lack of typed array implementation in JavascriptCore, and limitation of React Native structure](https://github.com/facebook/react-native/issues/1424), to convert data to JS byte array spends lot of time. Use it only when needed, the following chart shows how much time it takes when reading a file with different encoding.
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.
0 commit comments