# @georstat/react-native-image-cache 中文文档

规范地址：https://npmcn.com/package/%40georstat/react-native-image-cache/

版本：3\.1\.0
npm 元数据更新时间：2023-09-07T05:44:25.514Z
中文译文更新时间：2026-11-16T04:53:59.937Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40georstat/react-native-image-cache
原文对照：https://npmcn.com/package/%40georstat/react-native-image-cache/?lang=original
项目主页：https://github.com/georstat/react-native-image-cache
源码仓库：https://github.com/georstat/react-native-image-cache

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：125 kB，44 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \*，react-native \*，react-native-file-access \>=3\.0\.0，react-native-reanimated \>=2\.2\.0
- 首次发布：2021-05-06T13:59:13.129Z
- 最新版本发布：2023-09-07T05:44:25.303Z
- 近 30 天下载量：6969（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 0 个）

## 中文简介

对 iOS 和 Android 的原生图像文件系统缓存

## 安装

```sh
npm install @georstat/react-native-image-cache
```

也可以使用：`pnpm add @georstat/react-native-image-cache`、`yarn add @georstat/react-native-image-cache`、`bun add @georstat/react-native-image-cache`

## README

# 在文件系统中以渐进加载方式重现原生图像缓存

[![npm version](https://img.shields.io/npm/v/@georstat/react-native-image-cache.svg?style=for-the-badge)](https://www.npmjs.com/package/@georstat/react-native-image-cache) [![npm downloads](https://img.shields.io/npm/dm/@georstat/react-native-image-cache.svg?style=for-the-badge)](https://www.npmjs.com/package/@georstat/react-native-image-cache) [![npm](https://img.shields.io/npm/dt/@georstat/react-native-image-cache.svg?style=for-the-badge)](https://www.npmjs.com/package/@georstat/react-native-image-cache) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](https://opensource.org/licenses/MIT) ![GitHub package.json version](https://img.shields.io/github/package-json/v/georstat/react-native-image-cache?style=for-the-badge) ![Platform - Android and iOS](https://img.shields.io/badge/platform-Android%20%7C%20iOS-blue.svg?style=for-the-badge)

灵感来自:

-   [wcandillon/ react-native-expo-image-cache (英语)](https://github.com/wcandillon/react-native-expo-image-cache) (威廉·坎迪伦)
-   [WrathChaos/反应-本土-进步-快速图像](https://github.com/WrathChaos/react-native-progressive-fast-image) (Freaky Coder) (英语)

## 特征

-   缓存 **远程** 文件系统中带有渐进加载的图像
-   可用于本地图像
-   用途 [`react-native-file-access`](https://github.com/alpha0010/react-native-file-access) 文件系统访问
-   写入 `Typescript`
-   用途 [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/docs/) 用于动画
-   网络故障重试
-   支持新建筑,两者均 `react-native-file-access` 财务报告和审定财务报表 `react-native-reanimated` 装潢准备好了.

## 注意:

#### 如果你没有用 [`react-native-reanimated`](https://github.com/software-mansion/react-native-reanimated) 2.x.x版本然后使用本模块的1.x.x版本

### 如果你要找一个有缩略图的图像库 [@georstat/ react-native-image-gallery (英语)](https://github.com/georstat/react-native-image-gallery)

## 预览

### iOS: (英语)

![@georstat:react-native-image-cache\_iOS\_demo](https://user-images.githubusercontent.com/717975/117460761-85fd8f00-af55-11eb-8804-69c008bfeb8d.gif)

### 机器人:

![@georstat:react-native-image-cache\_Android\_demo](https://user-images.githubusercontent.com/717975/117491773-4ba5e900-af79-11eb-8ae1-99604b47c55c.gif)

### 自定义装入图像组件 : (参见 [实例](https://github.com/georstat/react-native-image-cache/tree/main/example/src)(中文(简体) )

![@georstat:react-native-image-cache\_custom\_loading\_image\_component\_demo](https://user-images.githubusercontent.com/717975/125193571-b4e5f900-e255-11eb-8164-3ca097ce6e74.gif)

## 安装

#### 线条 :

```bash
yarn add @georstat/react-native-image-cache react-native-file-access react-native-reanimated
```

#### 无 :

```bash
npm i @georstat/react-native-image-cache react-native-file-access react-native-reanimated
```

#### 链接本地软件包 :

```bash
 cd ios
 pod install
```

### 记着!

用于原生反应 0.65 使用 [`react-native-file-access`](https://github.com/alpha0010/react-native-file-access) >= 2.0.0

## 使用量

#### 把这个全局配置放到您的应用程序条目 eg 上 . `App.tsx` 或者说 `index.js` (单位:千美元)**需求**:

**_说明_**数字 : `retryDelay` 财务报告和审定财务报表 `maxRetries` 是可选的,它们默认为 `0` 这意味着重试逻辑是 **已禁用**

```tsx
import { CacheManager } from '@georstat/react-native-image-cache';
import { Dirs } from 'react-native-file-access';

CacheManager.config = {
  baseDir: `${Dirs.CacheDir}/images_cache/`,
  blurRadius: 15,
  cacheLimit: 0,
  maxRetries: 3 /* optional, if not provided defaults to 0 */,
  retryDelay: 3000 /* in milliseconds, optional, if not provided defaults to 0 */,
  sourceAnimationDuration: 1000,
  thumbnailAnimationDuration: 1000,
};
```

#### 自定义缓存密钥, 用于缓存来自 Amazon S3 和类似服务的图像, 请添加此( 或任何适合您需要的) `CacheManager.config`数字 :

```tsx
CacheManager.config = {
  // ...
  getCustomCacheKey: (source: string) => {
    // Remove params from the URL for caching images (useful for caching images from Amazons S3 bucket and etc)
    let newCacheKey = source;
    if (source.includes('?')) {
      newCacheKey = source.substring(0, source.lastIndexOf('?'));
    }
    return newCacheKey;
  },
};
```

#### `cacheLimit` 配置 : (自动搜索缓存文件)

若为 `cacheLimit` 设置为 `0` (默认值) 那么缓存永远不会被自动浏览 。 此设置接受多个字节 eg . `1024 * 1024 * 256`(~256MB)和要求 `react-native-file-access` 2.4.0,如果使用 < 2.4.0,则留下默认值 `0` (残疾).

缓存缓存流 :

1.  从中获取所有文件 `baseDir`。 。 。 .
2.  按顺序排列 `lastModified`,最古老的第一.
3.  使用 `reduce` 数组方法.
4.  从第3步检查总大小并减去 `cacheLimit` 数值.
5.  运行一段时间循环并不断删除文件, 只要当前缓存大小( 第 4 步) 大于触发缓存搜索所需的大小( C)`cacheLimit` 数值).
6.  上面所有步骤只有在图像尚未被缓存时才会运行,它会在下载到缓存后运行.

Pruning在iOS模拟器上以5.7MB图像和从缓存上取出~5.00副本作为基准,没有任何问题. 请注意,各装置的螺旋速度/性能可能有所不同。 使用 `cacheLimit` 明智和不设大值.

如果您想在模拟器上运行自己的测试,那么缓存的图像就存储在这个位置上的Mac上: `/Users/<your_name>/Library/Developer/CoreSimulator/Devices/<simulator_device_id>/ data/Containers/Data/Application/<application_id>/Library/Caches/images_cache`, (中文(简体) ), 只要复制和粘贴 多个图像在那里, 有没有必要下载 通过应用程序.

#### 目录常数, 明智选择 : ([反应-内存-文件-访问文件](https://github.com/alpha0010/react-native-file-access#directory-constants)(中文(简体) )

-   `Dirs.CacheDir`
-   `Dirs.DatabaseDir` (仅限机器人)
-   `Dirs.DocumentDir`
-   `Dirs.LibraryDir` (仅iOS)
-   `Dirs.MainBundleDir`
-   `Dirs.SDCardDir` (仅限机器人)
    -   偏爱 `FileSystem.cpExternal()` 可能的话.

#### 组件 :

```tsx
import { CachedImage } from '@georstat/react-native-image-cache';

<CachedImage
  source="https://via.placeholder.com/3500x3500"
  style={{ height: 350, width: 150 }}
  thumbnailSource="https://via.placeholder.com/350x150"
/>;
```

#### 前置图像并保存在缓存中 :

接受2个参数:

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `image` | `Array or String` | (需要) 远程图像的尿液或远程尿液串阵列 |
| `options` | `Object` | 获取图像的自定义选项 http request eg. `{headers:{}, body:{}}` |

```tsx
import { CacheManager } from '@georstat/react-native-image-cache';

const url = 'https://..../image.jpg';

const urls = [
  'https://..../image.jpg',
  'https://..../image2.jpg',
  'https://..../image3.jpg',
];

CacheManager.prefetch(url); // prefetch single image

CacheManager.prefetch(urls); // prefetch mutliple images
```

#### 前置图像并返回 blob/ base64 :

接受2个参数:

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `image` | `String` | (需要) 远程图像的 uri |
| `options` | `Object` | 获取图像的自定义选项 http request eg. `{headers:{}, body:{}}` |

```tsx
import { CacheManager } from '@georstat/react-native-image-cache';

const url = 'https://..../image.jpg';

CacheManager.prefetchBlob(url).then(response => console.log(response)); // response is the base64 string
```

#### 清除本地缓存 :

```tsx
import { CacheManager } from '@georstat/react-native-image-cache';

await CacheManager.clearCache();
```

#### 删除单个缓存项 :

```tsx
const uri = 'https://.../example.jpg';

await CacheManager.removeCacheEntry(uri);
```

#### 获取本地缓存大小 :

```tsx
await CacheManager.getCacheSize();
```

#### 检查图像是否被缓存 :

```tsx
await CacheManager.isImageCached(uri);
```

## 道具

#### `CachedImage` 接受下列道具:

| 属性 | 螺旋管 | 说明 |
| --- | --- | --- |
| `source` | `String` | (单位:千美元)**需求**(原始内容存档于2018-10-21). Uri of image. |
| `sourceAnimationDuration` | `Number` | `source` 装入时图像动画持续时间, 默认为 `1000`ms( 覆盖配置) |
| `thumbnailSource` | `String` | (单位:千美元)**需求**缩略图图像的 Uri |
| `thumbnailAnimationDuration` | `Number` | 缩略图的动画持续时间, 默认为 `1000`ms( 覆盖配置) |
| `blurRadius` | `Number` | 模糊度可应用于 `thumbnailSource` 图像,默认为 `15` (覆盖配置) |
| `loadingImageComponent` | `React.CompnentType` | 默认为图像 `loadingSource` 道具 |
| `noCache` | `Boolean` | 不缓存图像, 默认为 `false` 这意味着总是缓存图像 |
| `maxAge` | `Number` | 缓存图像的最大时长, 默认为 `undefined` (无限入棺. **自动浏览不会考虑这个值, 如果图像 `cacheLimit` 到达** |
| `loadingImageStyle` | `Object` | 装入图像组件的样式 。 工作,如果你不提供 `loadingImageComponent` |
| `imageStyle` | `Object` | 图像样式,在通过本地图像加载时使用 `require()` |
| `loadingSource` | `object` | 装入图像组件的来源 。 工作,如果你不提供 `loadingImageComponent` |
| `onError` | `Func` | 从缓存中装入图像时运行 |
| `onLoad` | `Func` | 装入成功时已启动 |
| `onLoadEnd` | `Func` | 装入成功或失败时已启动 |
| `resizeMode` | `String` | 反应本地图像组件 [调整模式大小](https://reactnative.dev/docs/image#resizemode) 默认为 `contain` |
| `testID` | `String` | 测试ID,用于测试 |
| `tintColor` | `String` | 源图像的颜色 |
| `style` | `Object` | `source` 和 `thumbnailSource` 图像样式 |
| `options` | `Object` | 获取图像的自定义选项 http request eg. `{headers:{}, body:{}}` |
| `accessibilityHint` | `string` | 访问提示 `source` (可选) |
| `accessibilityLabel` | `string` | 访问标签 `source` (可选) |
| `accessibilityRole` | `string` | 无障碍角色 `source` (可选,默认为) `image`(中文(简体) ) |
| `accessibilityHintThumbnail` | `string` | 访问提示 `thumbnailSource` (可选) |
| `accessibilityLabelThumbnail` | `string` | 访问标签 `thumbnailSource` (可选) |
| `accessibilityRoleThumbnail` | `string` | 无障碍角色 `thumbnailSource` (可选,默认为) `image`(中文(简体) ) |
| `accessibilityHintLoadingImage` | `string` | 访问提示 `loadingSource` (可选) |
| `accessibilityLabelLoadingImage` | `string` | 访问标签 `loadingSource` (可选) |
| `accessibilityRoleLoadingImage` | `string` | 无障碍角色 `loadingSource` (可选,默认为) `image`(中文(简体) ) |

#### [更多关于反应土著无障碍的信息](https://reactnative.dev/docs/accessibility)

#### [关于反应土著无障碍的博客文章](https://medium.com/reactbrasil/introducing-react-native-accessibility-engine-fcf78f2a3805)

## 待办事宜:

-   [x] 将库转换为反应钩
-   [x] 制作 `baseDir` 可配置
-   [x] 删除单个缓存条目

# 发起人

此库为免费开发.

用这个链接给我们买杯咖啡: [!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/efstathios)

## 作者数 :

-   [埃夫斯塔蒂奥斯·恩托纳斯](https://github.com/efstathiosntonas)
-   [乔治·巴科吉安尼斯](https://github.com/geobako)
-   [乔治·卡利尼科斯](https://github.com/giokallis)

## 常见问题

### @georstat/react-native-image-cache 是什么？

对 iOS 和 Android 的原生图像文件系统缓存

### 如何安装 @georstat/react-native-image-cache？

在项目目录运行 npm install @georstat/react-native-image-cache，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\*）、react-native（\*）、react-native-file-access（\>=3\.0\.0）、react-native-reanimated（\>=2\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @georstat/react-native-image-cache 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @georstat/react-native-image-cache 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @georstat/react-native-image-cache 可以商用吗？

@georstat/react-native-image-cache 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @georstat/react-native-image-cache 的下载量有多少？

根据 npm 官方下载统计，@georstat/react-native-image-cache 在 2026/10/16 – 2026/11/14 这 30 天内被下载 6,969 次，日均约 232 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @georstat/react-native-image-cache 还在维护吗？

最新版本 3\.1\.0 发布于 2023/09/07（3 年前）；至今共发布 38 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/05/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

