# @chrisben/imgcache\.js 中文文档

规范地址：https://npmcn.com/package/%40chrisben/imgcache.js/

版本：2\.1\.1
npm 元数据更新时间：2022-06-12T15:53:10.415Z
中文译文更新时间：2026-11-09T14:44:57.153Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40chrisben/imgcache.js
原文对照：https://npmcn.com/package/%40chrisben/imgcache.js/?lang=original
项目主页：https://github.com/chrisben/imgcache.js
源码仓库：https://github.com/chrisben/imgcache.js

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

- 包体积（解压后）：232 kB，25 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=9\.10\.0
- 运行依赖：0 个
- 首次发布：2017-01-16T20:43:59.967Z
- 最新版本发布：2019-06-16T09:55:41.862Z
- 近 30 天下载量：3595（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 0 个）

## 中文简介

JS 库基于文件 API 以缓存图像进行离线恢复(目标: cordova/phonegap & chrome)

## 安装

```sh
npm install @chrisben/imgcache.js
```

也可以使用：`pnpm add @chrisben/imgcache.js`、`yarn add @chrisben/imgcache.js`、`bun add @chrisben/imgcache.js`

## README

# iggcache.js (英语)

这个JS库的目的是提供一个很好的界面,用于本地存储图像,用于使用PhoneGap/Cordova或 [支持新 html5 文件 API 的浏览器](http://caniuse.com/filesystem) (例如Chrome).

这个库对于使用 Phonegap/Cordova 的移动网络应用程序特别有用,因为正常的浏览器缓存不能依赖,离线导航也相当常见.

使用过的 [已装入图像](http://desandro.github.com/imagesloaded/) 如所示 `examples/example2.html`,可以自动看到:

-   在缓存中存储图像
-   如果无法加载( 下行/ 忙于服务器. ) , 则用缓存版本替换图像

这是我至今为止找到的最佳解决方案.

该图书馆与Phonegap/Cordova(v QQ 1.7)合作,支持的平台是:

-   机器人
-   iOS系统
-   视窗电话 8.1
-   亚马逊消防操作系统

大多数方法是 **叙利亚** : 必要时使用回调.

这个库使用平坦的旧ES5 JavaScript,没有收发器,没有依赖性.

# 使用 igcache.js 软件

## 可选的依赖关系

-   j 查询( 任何版本的1.6 都应该查询), Zepto 或 AngularJS (jQueryLite) _选项_
-   电话gap/科尔多瓦(v >=v 1.7) _选项_
-   \[装入图像\] (中文(简体) )[http://desandro.github.com/imagesloaded/ 互联网档案馆的存檔,存档日期2014-12-02](http://desandro.github.com/imagesloaded/)(中文(简体) ) _选项_

## 安装

注意: 您可以使用 [箭头](http://bower.io/) 或者说 [无](https://www.npmjs.com/) 将此库添加为您项目的依赖性( 仓库名 : `imgcache.js`) (中文(简体) ).

要开始使用此库, 导入 `lib/imgcache.js` 在您的 html 文件内 :

```html
<script src="lib/imgcache.js"></script>
```

使用PhoneGap/科尔多瓦:见 [CORDOVA.md (中文(简体) )](https://npmcn.com/package/%40chrisben/imgcache.js/CORDOVA.md)。 。 。 .

使用支持 \[html5 文件系统 API 的 Chrome 或其他浏览器:

-   当心交叉域 ajax 问题! 从同一个域取回图像或用服务器设置 CORS 解决方案...
-   如果页面是本地打开的(文件://.),则需要加载以下旗帜: `--allow-file-access-from-files --allow-file-access` 否则本地文件系统将无法访问( 安全错误)
-   通过本地文件系统导航打开文件系统的新标签:http://_您的网络域_/persistent/ 或文件系统:http://_您的网络域_/临时/

## 用作 AMD / 通用JS 模块

-   要使用 AMD 的库 :

```javascript
define(function (require) {
    var ImgCache = require("imgcache");
});
```

-   要使用 CommonJS 的库 :

```javascript
var cache = require("imgcache");
```

## 设置您的缓存

在初始化缓存前, 您必须指定您想要覆盖的任何默认选项 :

```javascript
// write log to console
ImgCache.options.debug = true;

// increase allocated space on Chrome to 50MB, default was 10MB
ImgCache.options.chromeQuota = 50*1024*1024;

// Instead of using the PERSISTENT or TEMPORARY filesystems, use one of the
// Cordova File plugin's app directories
// (https://github.com/apache/cordova-plugin-file#where-to-store-files).
// This is friendlier in a mobile application environment as we are able to store
// files in the correct platform-recommended/enforced directories.
// WARNING: Make sure this points to a __directory__!
// NOTE: Only has effect when running in a Cordova environment
ImgCache.options.cordovaFilesystemRoot = cordova.file.dataDirectory;
```

见 `ImgCache.options` 用于更多设置的源文件顶部.

设置自定义配置后, 初始化缓存 :

```javascript
ImgCache.init(function () {
    alert('ImgCache init: success!');

    // from within this function you're now able to call other ImgCache methods
    // or you can wait for the ImgCacheReady event

}, function () {
    alert('ImgCache init: error! Check the log for errors');
});
```

如果缓存成功初始化, `ImgCache.ready` 将设定为 `true`。也可以监视触发 `ImgCacheReady` 活动.

**如果你用iggcache.js 与PhoneGap/科尔多瓦, `ImgCache.init()` 必须在 `onDeviceReady` 事件已经触发, 而不是之前!**

注意在Chrome中,用户会被提示给页面权限,以便访问本地文件系统(如果用户拒绝,则会运行错误回调).

## 存储图像

图像存储到指定的本地文件夹 `ImgCache.options.localCacheFolder`。要在缓存中添加文件 :

```javascript
ImgCache.cacheFile('http://my-cdn.com/users/2/profile.jpg');
```

要缓存被定义为背景图像的图像,您可以使用缓存文件或使用帮助器功能 `ImgCache.cacheBackground` 接受 DOM/jQuery 元素,检索其背景属性并缓存该文件.

## 使用缓存图像

一旦一个图像被存储在缓存中,您就可以用被缓存的文件替换在img元素中显示的文件 :

```javascript
var target = $('img#profile');
ImgCache.cacheFile(target.attr('src'), function () {
  ImgCache.useCachedFile(target, function () {
    alert('now using local copy');
  }, function(){
    alert('could not load from cache');
  })
});
```

检查本地文件是否存储 :

```javascript
ImgCache.isCached(target.attr('src'), function(path, success) {
  if (success) {
    // already cached
    ImgCache.useCachedFile(target);
  } else {
    // not there, need to cache the image
    ImgCache.cacheFile(target.attr('src'), function () {
      ImgCache.useCachedFile(target);
    });
  }
});
```

当您不再使用本地缓存文件时 :

```javascript
var target = $('img#profile');
ImgCache.useOnlineFile(target);
```

## 清除缓存

要删除所有缓存文件, 请清除本地缓存文件夹 :

```javascript
ImgCache.clearCache(function () {
  // continue cleanup...
}, function () {
  // something went wrong
});
```

目前无法使缓存中的单个图像无效 .

## 高级 API

-   释迦.**输入**(a) 与《公约》有关的其他事项 _\-- 启用本地缓存_
-   释迦.**缓存文件**(a) 与《公约》有关的其他事项 _\-- 将文件副本写入本地缓存_
-   释迦.**已切换**(a) 与《公约》有关的其他事项 _\-- 检查是否在缓存中存在给定的图像 - 不检查该文件的最新版本是否被缓存_
-   释迦.**获取卡通文件**(a) 与《公约》有关的其他事项 _\-- 返回缓存文件_
-   释迦.**获取卡通文件URL**(a) 与《公约》有关的其他事项 _\-- 返回文件缓存版本的 URL_
-   释迦.**获取CachedFileBase64数据**(a) 与《公约》有关的其他事项 _\-- 返回缓存文件的基数64数据_
-   释迦.**切换文件**(a) 与《公约》有关的其他事项 _\-- 用缓存版本替换 ing src_
-   释迦.**使用 CachedFile with source 软件**(a) 与《公约》有关的其他事项 _\- 类似于使用CachedFile,但以图像源 URL 作为额外参数_
-   释迦.**使用在线文件**(a) 与《公约》有关的其他事项 _\-- 将img src 替换为原始(在线)版本 // 同步方法_
-   释迦.**清除缓存**(a) 与《公约》有关的其他事项 _\-- 清除本地缓存文件夹_
-   释迦.**已隐藏背景**(a) 与《公约》有关的其他事项 _\- 检查缓存中是否有给定元素背景图像 - 不检查该文件的最新版本是否被缓存_
-   释迦.**缓存背景**(a) 与《公约》有关的其他事项 _\-- 缓存元素的背景图像_
-   释迦.**使用切换背景**(a) 与《公约》有关的其他事项 _\-- 用缓存版本取代给定元素的背景图像源_
-   释迦.**使用 CachedBackground with source( 有源代码)**(a) 与《公约》有关的其他事项 _\- 类似于使用 CachedBackground 但以图像源url 作为额外参数_
-   释迦.**使用背景在线文件**(a) 与《公约》有关的其他事项 _\-- 将背景图像替换为原始(在线)版本_
-   释迦.**删除文件**(a) 与《公约》有关的其他事项 _\-- 从缓存中删除给定的文件_
-   释迦.**获取当前大小**(a) 与《公约》有关的其他事项 _\-- 以字节/ 同步方法返回 ImgCache 缓存的当前大小_

可通过下列方式获得私人方法:

-   ImgCache. 帮助者 _\-- 一般帮助方法_
-   ImgCache.dom 帮助器 _\- DOM 操作辅助功能_
-   ImgCache. 隐私 _\-- 私人方法_

## 选项

见 ImgCache. 选项列表位于源文件的上方 . 选项可以从您的脚本上覆盖, 不需要修改库 !

## B. 压倒一切的方法

-   ImgCache默认使用的散列法为SHA-1. 之所以选择它是因为它几乎没有相撞。 尽管如果有大量文件要缓存, 它可能会让事情放慢( 见 #81) 。 你可以通过ImgCache. overridables.hash来插入自己的方法.
-   如果启用了日志, ImgCache 默认会在控制台中输出一些日志项 。 您可以覆盖 ImgCache. overriables.log 以改变这种行为 .

## 承诺

包含 [iggcache - 保证](https://npmcn.com/package/%40chrisben/imgcache.js/lib/imgcache-promise.js) 包装到您的项目中, 以便能够使用 ES6 兼容的许诺( 使用 ) [青鸟](http://bluebirdjs.com/) 例如),如果你不喜欢回调,更喜欢使用更简单的然后/捕获方法.

这个包装器也确保了init方法总是被叫做"先",所以在使用这个包装器时,你不应该自己称呼这个方法.

看看这个 [样本代码](https://npmcn.com/package/%40chrisben/imgcache.js/examples/promises.html)。 。 。 .

## 单位测试和密码样本

运行本地服务器 :

```shell
npm install
npm start
```

然后在您的 Chrome 浏览器中打开给定的 URL(`index.html`)并点击"启动单位测试"进行发射单位测试.

你会找到几个代码样本.

要输入主javascript代码,你可以运行 `npm test` 开始 [埃斯林特语name](http://eslint.org/)

## 发布注释

见 [变化](https://npmcn.com/package/%40chrisben/imgcache.js/CHANGELOG.md) 为完整的发行笔记.

## 解决问题

请先仔细阅读这些文件。 如果您仍然有问题遵循这一清单:

-   设置调试 ON (P)`ImgCache.options.debug = true;`),并仔细跟踪控制台内的输出.
-   这是ImgCache第一个被称作的方法吗? (检查控制台与调试ON,以确保这一点)
-   在您的代码中添加提醒/ 控制台.log 的呼叫, 以查看哪些被调用, 哪些被调用 .
-   我是在运行最新版本的 ImgCache 吗? 如果没有,请尝试最新版本或查看 [更改日志](https://npmcn.com/package/%40chrisben/imgcache.js/CHANGELOG.md) 与您的问题相关的新版本.

如果使用 Cordova/ Phonegap , 请务必阅读 [此文档](https://npmcn.com/package/%40chrisben/imgcache.js/CORDOVA.md) 首先,然后重复检查以下内容:

-   所有需要的插件都激活了吗 ? (config.xml)
-   权限是否正确 ? (配置.xml) (中文(简体) )
-   我的代码运行ATER 后,"准备"事件启动?

如果您仍然被困住, 请在现有的问题中寻找类似的问题 .

如果您找不到任何信息, 请用您的问题描述打开一个问题, 如果您可以的话, 请用一个更简单的代码 .

每当你张贴一个问题,它是重要的,你增加以下细节以获得更快的答案:

-   ImgCache 版本
-   使用的选项
-   与之相关的联署材料框架(jQuery/Angular/Ionic
-   环境:克罗梅或克多瓦
-   如果使用 Cordova :
    -   其版本
    -   插件的版本
    -   目标OS(iOS / Android
    -   目标OS版本(例如:iOS 8.1)

## 已知问题

见 [识相](https://npmcn.com/package/%40chrisben/imgcache.js/KNOWN_ISSUES.md) 一份已知问题的清单.

## 另见

AngularJS 包装器 :

-   [角-imgcache.js (英语)](https://github.com/maistho/angular-imgcache.js)
-   [ngImg 缓存](https://github.com/sunsus/ngImgCache/)

离子框架包装器 :

-   [ionic-img-cache (缩写)](https://github.com/vitaliy-bobrov/ionic-img-cache)

离子实例 :

-   [离线离子](https://github.com/mahcr/offline-ionic)

## 许可证

版权所有 2012-2018 (c) Christophe BENOIT

Apache 许可证 - 见 LICENSE.md

代码从 [http://code.google.com/p/tiny-sha1/ (中文(简体) )](http://code.google.com/p/tiny-sha1/) 根据麻省理工学院的许可正在使用中. 这部分作品的版权属于本作的创作者.

## 常见问题

### @chrisben/imgcache\.js 是什么？

JS 库基于文件 API 以缓存图像进行离线恢复\(目标: cordova/phonegap & chrome\)

### 如何安装 @chrisben/imgcache\.js？

在项目目录运行 npm install @chrisben/imgcache\.js，或使用 pnpm add / yarn add / bun add。

### @chrisben/imgcache\.js 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/chrisben\_\_imgcache\.js 是否存在。

### @chrisben/imgcache\.js 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @chrisben/imgcache\.js 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=9\.10\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @chrisben/imgcache\.js 可以商用吗？

@chrisben/imgcache\.js 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @chrisben/imgcache\.js 的下载量有多少？

根据 npm 官方下载统计，@chrisben/imgcache\.js 在 2026/10/10 – 2026/11/08 这 30 天内被下载 3,595 次，日均约 120 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @chrisben/imgcache\.js 还在维护吗？

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