浏览代码

Change README.md for npm

Ben Hsieh 9 年前
父节点
当前提交
526d86935e
共有 1 个文件被更改,包括 25 次插入12 次删除
  1. 25
    12
      src/README.md

+ 25
- 12
src/README.md 查看文件

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)]()
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)
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)
6
+
5
 **Why do we need this**
7
 **Why do we need this**
6
 
8
 
7
-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 [[fetch] Does fetch with blob() marshal data across the bridge?](https://github.com/facebook/react-native/issues/854).
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).
8
 
10
 
9
 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.
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.
10
 
12
 
11
 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.
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.
12
 
14
 
13
-**Pre v0.5.0 Users**
15
+**Backward Compatible**
14
 
16
 
15
-All updates are `backward-compatible` generally you don't have to change existing code unless you're going to use new APIs. In latest version (v0.5.0), 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-usage) bellow. This module implements native methods, supports both Android (uses awesome native library  [AsyncHttpClient](https://github.com/AsyncHttpClient/async-http-client])) and IOS.
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.
16
 
18
 
17
 ## TOC
19
 ## TOC
18
 
20
 
19
 * [Installation](#user-content-installation)
21
 * [Installation](#user-content-installation)
20
-* [Guide](#user-content-guide)
22
+* [Recipes](#user-content-recipes)
21
  * [Download file](#user-content-download-example--fetch-files-that-needs-authorization-token)
23
  * [Download file](#user-content-download-example--fetch-files-that-needs-authorization-token)
22
  * [Upload file](#user-content-upload-example--dropbox-files-upload-api)
24
  * [Upload file](#user-content-upload-example--dropbox-files-upload-api)
23
  * [Multipart/form upload](#user-content-multipartform-data-example--post-form-data-with-file-and-data)
25
  * [Multipart/form upload](#user-content-multipartform-data-example--post-form-data-with-file-and-data)
79
 
81
 
80
 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).
82
 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).
81
 
83
 
82
-## Guide
84
+## Recipes
83
 
85
 
84
 ```js
86
 ```js
85
 import RNFetchBlob from 'react-native-fetch-blob'
87
 import RNFetchBlob from 'react-native-fetch-blob'
256
   })
258
   })
257
 ```
259
 ```
258
 
260
 
259
-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`)
261
+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.
260
 
262
 
261
 ```js
263
 ```js
262
 
264
 
274
       // Or simply wrap the file path with RNFetchBlob.wrap().
276
       // Or simply wrap the file path with RNFetchBlob.wrap().
275
       data: RNFetchBlob.wrap(PATH_TO_THE_FILE)
277
       data: RNFetchBlob.wrap(PATH_TO_THE_FILE)
276
     },
278
     },
279
+    {
280
+      name : 'ringtone',
281
+      filename : 'ring.mp3',
282
+      // use custom MIME type
283
+      type : 'application/mp3',
284
+      // upload a file from asset is also possible in version >= 0.6.2
285
+      data : RNFetchBlob.wrap(RNFetchBlob.fs.asset('default-ringtone.mp3'))
286
+    }
277
     // elements without property `filename` will be sent as plain text
287
     // elements without property `filename` will be sent as plain text
278
     { name : 'name', data : 'user'},
288
     { name : 'name', data : 'user'},
279
     { name : 'info', data : JSON.stringify({
289
     { name : 'info', data : JSON.stringify({
289
 
299
 
290
 #### Upload/Download progress
300
 #### Upload/Download progress
291
 
301
 
292
-In `version >= 0.4.2` it is possible to know the upload/download progress.
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.
293
 
303
 
294
 ```js
304
 ```js
295
   RNFetchBlob.fetch('POST', 'http://www.example.com/upload', {
305
   RNFetchBlob.fetch('POST', 'http://www.example.com/upload', {
391
 
401
 
392
 #### File Access
402
 #### File Access
393
 
403
 
394
-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 I realized that, it's hard to find a great solution to manage cached files, every one who use this moudle may need those APIs for there cases.
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.
395
 
405
 
396
-File Access APIs
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.
397
 
407
 
408
+File Access APIs
409
+- [asset (0.6.2)](https://github.com/wkh237/react-native-fetch-blob/wiki/File-System-Access-API#assetfilenamestringstring)
398
 - [dirs](https://github.com/wkh237/react-native-fetch-blob/wiki/File-System-Access-API#dirs)
410
 - [dirs](https://github.com/wkh237/react-native-fetch-blob/wiki/File-System-Access-API#dirs)
399
 - [createFile](https://github.com/wkh237/react-native-fetch-blob/wiki/File-System-Access-API#createfilepath-data-encodingpromise)
411
 - [createFile](https://github.com/wkh237/react-native-fetch-blob/wiki/File-System-Access-API#createfilepath-data-encodingpromise)
400
 - [writeFile (0.6.0)](https://github.com/wkh237/react-native-fetch-blob/wiki/File-System-Access-API#writefilepathstring-contentstring--array-encodingstring-appendbooleanpromise)
412
 - [writeFile (0.6.0)](https://github.com/wkh237/react-native-fetch-blob/wiki/File-System-Access-API#writefilepathstring-contentstring--array-encodingstring-appendbooleanpromise)
423
 
435
 
424
 ```js
436
 ```js
425
 let data = ''
437
 let data = ''
426
-RNFetchBlob.readStream(
438
+RNFetchBlob.fs.readStream(
427
     // encoding, should be one of `base64`, `utf8`, `ascii`
439
     // encoding, should be one of `base64`, `utf8`, `ascii`
428
     'base64',
440
     'base64',
429
     // file path
441
     // file path
450
 When use `writeStream`, the stream is also opened immediately, but you have to `write`, and `close` by yourself.
462
 When use `writeStream`, the stream is also opened immediately, but you have to `write`, and `close` by yourself.
451
 
463
 
452
 ```js
464
 ```js
453
-RNFetchBlob.writeStream(
465
+RNFetchBlob.fs.writeStream(
454
     PATH_TO_FILE,
466
     PATH_TO_FILE,
455
     // encoding, should be one of `base64`, `utf8`, `ascii`
467
     // encoding, should be one of `base64`, `utf8`, `ascii`
456
     'utf8',
468
     'utf8',
539
 
551
 
540
 | Version | |
552
 | Version | |
541
 |---|---|
553
 |---|---|
554
+| 0.6.2 | Add support of asset file and camera roll files, Support custom MIME type when sending multipart request, thanks @smartt |
542
 | 0.6.1 | Fix #37 progress report API issue on IOS |
555
 | 0.6.1 | Fix #37 progress report API issue on IOS |
543
 | 0.6.0 | Add readFile and writeFile API for easier file access, also added Android download manager support. |
556
 | 0.6.0 | Add readFile and writeFile API for easier file access, also added Android download manager support. |
544
 | 0.5.8 | Fix #33 PUT request will always be sent as POST on Android |
557
 | 0.5.8 | Fix #33 PUT request will always be sent as POST on Android |