Browse Source

Change npm README.md

Ben Hsieh 8 years ago
parent
commit
e07e46512f
1 changed files with 56 additions and 12 deletions
  1. 56
    12
      src/README.md

+ 56
- 12
src/README.md View File

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/react-native-fetch-blob.svg?maxAge=2592000&style=flat-square)]()
2
-
3
-A project committed to make file acess and data transfer easier, effiecient for React Native developers.
1
+# react-native-fetch-blob [![release](https://img.shields.io/github/release/wkh237/react-native-fetch-blob.svg?style=flat-square)](https://github.com/wkh237/react-native-fetch-blob/releases) [![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/react-native-fetch-blob.svg?maxAge=2592000&style=flat-square)]()
4
 
2
 
5
 # [Visit our Github for latest document](https://github.com/wkh237/react-native-fetch-blob)
3
 # [Visit our Github for latest document](https://github.com/wkh237/react-native-fetch-blob)
6
 
4
 
5
+A project committed to make file acess and data transfer easier, effiecient for React Native developers.
6
+
7
 ## Features
7
 ## Features
8
 - Transfer data directly from/to storage without BASE64 bridging
8
 - Transfer data directly from/to storage without BASE64 bridging
9
 - File API supports normal files, Asset files, and CameraRoll files
9
 - File API supports normal files, Asset files, and CameraRoll files
10
 - Native-to-native file manipulation API, reduce JS bridging performance loss
10
 - Native-to-native file manipulation API, reduce JS bridging performance loss
11
 - File stream support for dealing with large file
11
 - File stream support for dealing with large file
12
-- Blob, File, XMLHttpRequest polyfills that make browser-based library available in RN
12
+- Blob, File, XMLHttpRequest polyfills that make browser-based library available in RN (experimental)
13
+
13
 
14
 
14
 ## TOC
15
 ## TOC
15
 * [About](#user-content-about)
16
 * [About](#user-content-about)
16
 * [Installation](#user-content-installation)
17
 * [Installation](#user-content-installation)
17
-* [Recipes](#user-content-recipes)
18
 * [HTTP Data Transfer](#user-content-http-data-transfer)
18
 * [HTTP Data Transfer](#user-content-http-data-transfer)
19
  * [Regular Request](#user-content-regular-request)
19
  * [Regular Request](#user-content-regular-request)
20
  * [Download file](#user-content-download-example--fetch-files-that-needs-authorization-token)
20
  * [Download file](#user-content-download-example--fetch-files-that-needs-authorization-token)
24
  * [Cancel HTTP request](#user-content-cancel-request)
24
  * [Cancel HTTP request](#user-content-cancel-request)
25
  * [Android Media Scanner, and Download Manager Support](#user-content-android-media-scanner-and-download-manager-support)
25
  * [Android Media Scanner, and Download Manager Support](#user-content-android-media-scanner-and-download-manager-support)
26
  * [Self-Signed SSL Server](#user-content-self-signed-ssl-server)
26
  * [Self-Signed SSL Server](#user-content-self-signed-ssl-server)
27
+ * [RNFetchBlob as Fetch](#user-content-rnfetchblob-as-fetch)
27
 * [File System](#user-content-file-system)
28
 * [File System](#user-content-file-system)
28
  * [File access](#user-content-file-access)
29
  * [File access](#user-content-file-access)
29
  * [File stream](#user-content-file-stream)
30
  * [File stream](#user-content-file-stream)
40
 
41
 
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)
42
 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)
42
 
43
 
44
+
43
 ## Installation
45
 ## Installation
44
 
46
 
45
 Install package from npm
47
 Install package from npm
63
 ```diff
65
 ```diff
64
 include ':app'      
66
 include ':app'      
65
 + include ':react-native-fetch-blob'                                                                                                  
67
 + include ':react-native-fetch-blob'                                                                                                  
66
-+ project(':react-native-fetch-blob').projectDir = new File(rootProject.projectDir,' ../node_modules/react-native-fetch-blob/android')                        
68
++ project(':react-native-fetch-blob').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-fetch-blob/android')                        
67
 ```
69
 ```
68
 
70
 
69
 Add this line to `MainApplication.java`, so that RNFetchBlob package becomes part of react native package.
71
 Add this line to `MainApplication.java`, so that RNFetchBlob package becomes part of react native package.
118
 
120
 
119
 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).
121
 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).
120
 
122
 
121
-## Recipes
123
+## Usage
122
 
124
 
123
 ES6
125
 ES6
124
 
126
 
332
   })
334
   })
333
 ```
335
 ```
334
 
336
 
335
-What if you want to upload a file in some field ? 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.
337
+What if you want to upload a file using 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.
336
 
338
 
337
 ```js
339
 ```js
338
 
340
 
413
 
415
 
414
 ```
416
 ```
415
 
417
 
416
-#### Android Media Scanner, and Download Manager Support
418
+### RNFetchBlob as Fetch
419
+
420
+0.9.0
421
+
422
+If you have existing code that uses `whatwg-fetch`(the official **fetch**), you don't have to change them after 0.9.0, just use fetch replacement. The difference between Official fetch and fetch replacement is, official fetch uses [whatwg-fetch](https://github.com/github/fetch) js library which wraps XMLHttpRequest polyfill under the hood it's a great library for web developers, however that does not play very well with RN. Our implementation is simply a wrapper of  RNFetchBlob.fetch and fs APIs, so you can access all the features we provide.
423
+
424
+[See document and examples](https://github.com/wkh237/react-native-fetch-blob/wiki/Fetch-API#fetch-replacement)
425
+
426
+### Android Media Scanner, and Download Manager Support
417
 
427
 
418
 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`.
428
 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`.
419
 
429
 
495
 .then(...)
505
 .then(...)
496
 ```
506
 ```
497
 
507
 
508
+**Open Downloaded File with Intent**
509
+
510
+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.
511
+
512
+Download and install an APK programatically
513
+
514
+```js
515
+
516
+const android = RNFetchBlob.android
517
+
518
+RNFetchBlob.config({
519
+    addAndroidDownloads : {
520
+      useDownloadManager : true,
521
+      title : 'awesome.apk',
522
+      description : 'An APK that will be installed',
523
+      mime : 'application/vnd.android.package-archive',
524
+      mediaScannable : true,
525
+      notification : true,
526
+    }
527
+  })
528
+  .fetch('GET', `http://www.example.com/awesome.apk`)
529
+  .then((res) => {
530
+      android.actionViewIntent(res.path(), 'application/vnd.android.package-archive')
531
+  })
532
+```
533
+
534
+Or show an image in image viewer
535
+
536
+```js
537
+      android.actionViewIntent(PATH_OF_IMG, 'image/png')
538
+```
539
+
498
 ### File System
540
 ### File System
499
 
541
 
500
 #### File Access
542
 #### File Access
647
 
689
 
648
 ### Web API Polyfills
690
 ### Web API Polyfills
649
 
691
 
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.
692
+After `0.8.0` we've made some [Web API polyfills](https://github.com/wkh237/react-native-fetch-blob/wiki/Web-API-Polyfills-(experimental)) that makes some browser-based library available in RN.
651
 
693
 
652
 - Blob
694
 - Blob
653
 - XMLHttpRequest (Use our implementation if you're going to use it with Blob)
695
 - XMLHttpRequest (Use our implementation if you're going to use it with Blob)
654
 
696
 
697
+Here's a [sample app](https://github.com/wkh237/rn-firebase-storage-upload-sample) that uses polyfills to upload files to FireBase.
698
+
655
 ### Performance Tips
699
 ### Performance Tips
656
 
700
 
657
 ---
701
 ---
658
 
702
 
659
-**Reduce RCT Bridge Overhead and BASE64 Time**
703
+**Reduce RCT Bridge and BASE64 Overheard**
660
 
704
 
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.
705
 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.
662
 
706
 
678
 
722
 
679
 | Version | |
723
 | Version | |
680
 |---|---|
724
 |---|---|
681
-| 0.8.2 | Fix Android RN 0.31 installation issue #78 |
725
+| 0.9.0 | Fix unicode response data format issue #73. Improve Android performance by using thread pool instead of async task. Add Fetch replacement #70. Add Android only API `actionViewIntent` to open file or install APK in app |
682
 | 0.8.1 | Remove Web API log and fix ios progress report function. |
726
 | 0.8.1 | Remove Web API log and fix ios progress report function. |
683
 | 0.8.0 | Added Web API polyfills, support regular request, added timeout option. |
727
 | 0.8.0 | Added Web API polyfills, support regular request, added timeout option. |
684
 | 0.7.5 | Fix installation script that make it compatible to react-native < 0.28 |
728
 | 0.7.5 | Fix installation script that make it compatible to react-native < 0.28 |