From 590d0cded2e55ab463af009c91294502a32f9b8c Mon Sep 17 00:00:00 2001 From: kfiroo Date: Wed, 9 Aug 2017 17:24:01 +0300 Subject: [PATCH] README --- README.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 107 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index e0bd612..9bb7ab6 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,7 @@ This package is greatly inspired by [@jayesbe](https://github.com/jayesbe)'s ama ## Installation npm install react-native-cached-image --save - -or - + - or - yarn add react-native-cached-image We use [`react-native-fetch-blob`](https://github.com/wkh237/react-native-fetch-blob#installation) to handle file system access in this package and it requires an extra step during the installation. @@ -31,6 +29,39 @@ Add the following line to your android/app/src/AndroidManifest.xml TODO - add usage example +```jsx +import React from 'react'; +import { + CachedImage, + ImageCacheProvider +} from 'react-native-cached-image'; + +const images = [ + 'https://example.com/images/1.jpg', + 'https://example.com/images/2.jpg', + 'https://example.com/images/3.jpg', + // ... +]; + +export default class Example extends React.Component { + render() { + return ( + console.log('hey there')}> + + + + + + + + + ); + } +} +``` + ## API This package exposes 3 modules: @@ -42,14 +73,83 @@ const { } = require('react-native-cached-image'); ``` +### ImageCacheManager +This is where all the cache magic takes place. +The API usually takes a *URL* and a set of [`ImageCacheManagerOptions`](#imagecachemanageroptions). + +#### `ImageCacheManager.downloadAndCacheUrl(url: String, options: ImageCacheManagerOptions): Promise` +Check the cache for the the URL (after removing fixing the query string according to `ImageCacheManagerOptions.useQueryParamsInCacheKey`). +If the URL exists in cache and is not expired, resolve with the local cached file path. +Otherwise, download the file to the cache folder, add it to the cache and then return the cached file path. + +#### `ImageCacheManager.seedAndCacheUrl(url: String, seedPath: String, options: ImageCacheManagerOptions): Promise` +Check the cache for the the URL (after removing fixing the query string according to `ImageCacheManagerOptions.useQueryParamsInCacheKey`). +If the URL exists in cache and is not expired, resolve with the local cached file path. +Otherwise, copy the seed file into the cache folder, add it to the cache and then return the cached file path. + +#### `ImageCacheManager.deleteUrl(url: String, options: ImageCacheManagerOptions): Promise` +Removes the cache entry for the URL and the local file corresponding to it, if it exists. + +#### `ImageCacheManager.clearCache(options: ImageCacheManagerOptions): Promise` +Clear the URL cache and remove files in the cache folder (as stated in the `ImageCacheManagerOptions.cacheLocation`) + +#### `ImageCacheManager.getCacheInfo(options: ImageCacheManagerOptions): Promise.<{file: Array, size: Number}>` +Returns info about the cache, list of files and the total size of the cache. + + ### CachedImage -TODO - CachedImage props +`CachedImage` is a drop in replacement for the `Image` component that will attempt to cache remote URLs for better performance. +It's main use is to hide the cache layer from the user and provide a simple way to cache images. +`CachedImage` uses an instance of `ImageCacheManager` to interact with the cache, if there is an instance provided by `ImageCacheProvider` via the context it will be used, otherwise a new instance will be created with the options from the component's props. + +```jsx + +``` + +##### Props +* `renderImage` - a function that returns a component, used to override the underlying `Image` component. +* `activityIndicatorProps` - props for the `ActivityIndicator` that is shown while the image is downloaded. +* `defaultSource` - prop to display a background image while the source image is downloaded. This will work even in android, but will not display background image if there you set borderRadius on this component style prop +* `loadingIndicator` - _component_ prop to set custom `ActivityIndicator`. +* `fallbackSource` - prop to set placeholder image. when `source.uri` is null or cached failed, the `fallbackSource` will be display. +* any of the `ImageCacheManagerOptionsPropTypes` props - customize the `ImageCacheManager` for this specific `CachedImage` instance. ### ImageCacheProvider -TODO - ImageCacheProvider props +This is a top-level component with 2 major functions: +1. Provide the customized `ImageCacheManager` to nested `CachedImage`. +2. Preload a set of URLs. + +##### Props +* `urlsToPreload` - an array of URLs to preload when the component mounts. default [] +* `numberOfConcurrentPreloads` - control the number of concurrent downloads, usually used when the `urlsToPreload` array is very big. default `urlsToPreload.length` +* `onPreloadComplete` - callback for when the preload is complete and all images are cached. + +### ImageCacheManagerOptions +A set of options that are provided to the `ImageCacheManager` and provide ways to customize it to your needs. + +```jsx +type ImageCacheManagerOptions = { + headers: PropTypes.object, // an object to be used as the headers when sending the request for the url. default {} + + ttl: PropTypes.number, // the number of seconds each url will stay in the cache. default 2 weeks + + useQueryParamsInCacheKey: PropTypes.oneOfType([ // when handling a URL with query params, this indicates how it should be treated: + PropTypes.bool, // if a bool value is given the whole query string will be used / ignored + PropTypes.arrayOf(PropTypes.string) // if an array of strings is given, only these keys will be taken from the query string. + ]), // default false + + cacheLocation: PropTypes.string, // the path to the root of the cache folder. default the device cache dir + + allowSelfSignedSSL: PropTypes.bool, // true to allow self signed SSL URLs to be downloaded. default false +}; + +``` -### ImageCacheManager -TODO - ImageCacheManager api ## Contributing