react-native-cached-fast-image

CachedImage component for react-native

Installation

npm install react-native-cached-fast-image --save
- or -
yarn add react-native-cached-fast-image


react-native link react-native-fast-image
react-native link react-native-fetch-blob

本组件依赖于react-native-fetch-blob和react-native-fast-image

Usage

使用前后安装包大小对比

[] [] [] TODO - add usage example

import React from 'react';
import {
    CachedImage,
    ImageCacheProvider
} from 'react-native-cached-fast-image';
//发布最终上线版的时候所有图片要上传阿里云oss，并开启该开关所有静态图片资源走远程更新有利于减少安装包大小
global.useOssRemoteImage =  false;//当改值为true时打release包默认获取oss云端的图片，为false时打包本地静态图片资源
global.ossBaseUrl = 'https://gzol.oss-cn-qingdao.aliyuncs.com/merchant/';
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 (
            <ImageCacheProvider
                urlsToPreload={images}
                onPreloadComplete={() => console.log('hey there')}>

                <CachedImage source={{uri: images[0]}}/>

                <CachedImage source={{uri: images[1]}}/>

                <CachedImage source={{uri: images[2]}}/>

            </ImageCacheProvider>
        );
    }
}

API

This package exposes 3 modules:

const {
    CachedImage,            // react-native component that is a drop-in replacement for your react-native `Image` components
    ImageCacheProvider,     // a top level component that provides accsess to the underlying `ImageCacheManager` and preloads images
    ImageCacheManager,      // the logic behind cache machanism - ttl, fs, url resolving etc.
} = require('react-native-cached-fast-image');

ImageCacheManager

This is where all the cache magic takes place. The API usually takes a URL and a set of ImageCacheManagerOptions.

`ImageCacheManager.downloadAndCacheUrl(url: String, options: ImageCacheManagerOptions): Promise<String>`

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<String>`

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

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.

<CachedImage
    source={{
        uri: 'https://example.com/path/to/your/image.jpg'
    }}
    style={styles.image}
/>

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

This is a top-level component with 2 major functions:

Provide the customized ImageCacheManager to nested CachedImage.
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.

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
};

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.