localForage

localForage 是一个快速而简单的 JavaScript 存储库。通过使用异步存储（IndexedDB 或 WebSQL）和简单的类 localStorage 的 API ，localForage 能改善 Web 应用的离线体验。

在不支持 IndexedDB 或 WebSQL 的浏览器中，localForage 使用 localStorage。有关兼容性详情，请参阅 wiki。

使用 localForage，只需将 JavaScript 文件放入页面即可：

<script src="localforage/dist/localforage.js"></script>
<script>localforage.getItem('something', myCallback);</script>

试一试示例。

下载 GitHub 上最新的 localForage ，或通过npm 安装：

npm install localforage

或通过 bower：

bower install localforage

localForage 也兼容 browserify。

支持

感到迷茫？需要帮助？试一试 localForage API 文档。

如果你正在使用本库，运行测试或想为 localForage 做出贡献，可访问 irc.freenode.net 并在#localforage 频道咨询有关 localForage 的问题。

最佳咨询人员是 tofumatt，他在线时间一般为格林威治时间 10 am - 8 pm。

Safari 10.1+

从 Safari 10.1 开始，默认为 IndexedDB；请参阅 CHANGELOG 了解更多。

如何使用 localForage

回调函数 vs Promise

由于 localForage 使用异步存储，因此 API 是异步的。在其他方面，与 localStorage API 完全相同。

localForage 支持两种 API，你可以使用回调函数形式或 Promise。如果你不确定哪一个更适合你，那么建议使用 Promise。

下面是一个回调函数形式的示例：

localforage.setItem('key', 'value', function (err) {
  // 若 err 不为 null，则表示出错
  localforage.getItem('key', function (err, value) {
    // 若 err 不为 null，则表示出错，否则 value 为 key 对应的值
  });
});

Promise 形式：

localforage.setItem('key', 'value').then(function () {
  return localforage.getItem('key');
}).then(function (value) {
  // 成功获取值
}).catch(function (err) {
  // 出错了
});

更多的示例，请访问 API 文档。

存储 Blobs，TypedArrays 或其他类型 JS 对象

你可以在 localForage 中存储任何类型; 不像 localStorage 只能存储字符串。即使后端的存储形式为 localStorage，当需要获取/设置值时，localForage 也会自动执行 JSON.parse() 和 JSON.stringify()。

只要是可以序列化为 JSON 的原生 JS 对象，localForage 都可以存储，包括 ArrayBuffers，Blob 和 TypedArrays。在 API 文档可查看 localForage 支持所有类型。

所有的后端存储驱动支持所有类型在，但 localStorage 有存储限制，所以无法存储大型 Blob。

配置

你可以通过 config() 方法设置数据库信息。可用的选项有 driver，name，storeName，version，size，和 description。

示例：

localforage.config({
    driver      : localforage.WEBSQL, // 使用 WebSQL；也可以使用 setDriver()
    name        : 'myApp',
    version     : 1.0,
    size        : 4980736, // 数据库的大小，单位为字节。现仅 WebSQL 可用
    storeName   : 'keyvaluepairs', // 仅接受字母，数字和下划线
    description : 'some description'
});

**注意：**在数据交互之前，你必须先调用 config()。即在使用 getItem()，setItem()，removeItem()，clear()，key()，keys() 或 length() 前要先调用 config()。

多实例

通过 createInstance 方法，你可以创建多个 localForage 实例，且能指向不同数据仓库。所有 config 中的配置选项都可用。

var store = localforage.createInstance({
  name: "nameHere"
});

var otherStore = localforage.createInstance({
  name: "otherName"
});

// 设置某个数据仓库 key 的值不会影响到另一个数据仓库
store.setItem("key", "value");
otherStore.setItem("key", "value2");

RequireJS

你可以通过 RequireJS 使用 localForage：

define(['localforage'], function(localforage) {
    // 作为回调函数
    localforage.setItem('mykey', 'myvalue', console.log);

    // 使用 Promise
    localforage.setItem('mykey', 'myvalue').then(console.log);
});

Browserify 和 webpack

localForage 1.3+ 支持 Browserify 和 webpack。如果你使用的是早期版本的 localForage，且与 Browserify 或 webpack 搭配时有问题，请升级至 1.3.0 或更高版本。

在预构建一个正常的 JavaScript 文件的时候，webpack 可能会提示警告信息。如果你不想看到警告，你可以使用下面的配置，在 webpack 解析时忽略 localforage：

module: {
  noParse: /node_modules\/localforage\/dist\/localforage.js/,
  loaders: [...],

TypeScript

若你在 tsconfig.json（支持 TypeScript v1.8+）中将 allowSyntheticDefaultImports 编译选项设置为 true，那么你应该这样使用：

import localForage from "localforage";

否则，你应该使用以下方法中的一种：

import * as localForage from "localforage";
// 若你用的 TypeScript 版本不支持 ES6 风格导入像 localForage 这样的 UMD 模块，则用如下方式导入：
import localForage = require("localforage");

框架支持

若你使用如下的框架，localForage 为这几种框架都提供了模块作为驱动，你可以通过 localForage 离线存储数据。支持的框架驱动如下：

如果你有其他驱动，同时想将其加入此列表，请提出 issue。

自定义驱动

你可以创建你自己的驱动; 参阅 defineDriver API 文档。

Wiki 中有自定义驱动列表。

开发 localForage

你需要有 node/npm 和 bower。

开发 localForage，需要先 fork 并安装依赖。将 USERNAME 替换为你的 GitHub 用户名，并运行以下命令：

# 若你没有安装过 bower，则需要先全局安装 bower
npm install -g bower

# 将 USERNAME 替换为你的 GitHub 用户名：
git clone git@github.com:USERNAME/localForage.git
cd localForage
npm install
bower install

缺少 bower 依赖会导致测试失败！

执行测试

本地执行测试需要安装 PhantomJS。执行 npm test（或直接：grunt test）。你的代码必须通过 linter 的检查。

localForage 仅能在浏览器中运行，因此执行测试需要一个浏览器环境。本地测试在无头 WebKit 浏览器上运行（使用 PhantomJS）。

通过 Sauce Labs，localForage 支持 Travis CI，当你 Pull request 时，将在所有浏览器中自动执行测试。

许可协议

本程序为免费软件；许可协议为 Apache License.

xmoyKing/localForage-cn