localForage

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

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

要使用 localForage，只需将一个 JavaScript 文件拖放到您的页面中：

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

试试例子。

从 GitHub下载最新的 localForage，或使用 npm安装：

npm install localforage

支持

丢失的？需要帮忙？试试 localForage API 文档。localForage API文档也有中文版。

如果您在使用库、运行测试或想为 localForage 做出贡献时遇到问题，请在创建新问题之前先查看现有问题以解决您的问题。如果您仍然需要帮助，请随时提出问题。

如何使用 localForage

回调与承诺

因为 localForage 使用异步存储，所以它有一个异步 API。在其他方面与localStorage API完全相同 。

localForage 有一个双重 API，允许您使用 Node 样式的回调或Promises。如果您不确定哪一个适合您，建议使用 Promises。

下面是一个节点样式回调表单的示例：

localforage.setItem('key', 'value', function (err) {
  // if err is non-null, we got an error
  localforage.getItem('key', function (err, value) {
    // if err is non-null, we got an error. otherwise, value is the value
  });
});

和承诺形式：

localforage.setItem('key', 'value').then(function () {
  return localforage.getItem('key');
}).then(function (value) {
  // we got our value
}).catch(function (err) {
  // we got an error
});

或者，使用 async/ await：

try {
    const value = await localforage.getItem('somekey');
    // This code runs once the value has been loaded
    // from the offline store.
    console.log(value);
} catch (err) {
    // This code runs if there were any errors.
    console.log(err);
}

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

存储 Blob、TypedArrays 和其他 JS 对象

您可以在 localForage 中存储任何类型；您不仅限于 localStorage 中的字符串。即使 localStorage 是您的存储后端，localForage 也会在获取/设置值时自动 JSON.parse()执行 JSON.stringify()。

localForage 支持存储所有可以序列化为 JSON 的原生 JS 对象，以及 ArrayBuffers、Blobs 和 TypedArrays。查看 API 文档以获取 localForage 支持的类型的完整列表。

每个存储后端都支持所有类型，尽管 localStorage 中的存储限制使存储许多大型 Blob 成为不可能。

配置

config()您可以使用该方法设置数据库信息。可用选项有 driver、name、storeName、version、size和 description。

例子：

localforage.config({
    driver      : localforage.WEBSQL, // Force WebSQL; same as using setDriver()
    name        : 'myApp',
    version     : 1.0,
    size        : 4980736, // Size of database, in bytes. WebSQL-only for now.
    storeName   : 'keyvaluepairs', // Should be alphanumeric, with underscores.
    description : 'some description'
});

注意： 您必须在与数据交互 config() 之前调用。config()这意味着在使用 getItem(), setItem(), removeItem(), clear(), key(),keys()或之前调用 length()。

多个实例

您可以使用创建指向不同商店的 localForage 的多个实例 createInstance。支持使用的所有配置选项 config。

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

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

// Setting the key on one of these doesn't affect the other.
store.setItem("key", "value");
otherStore.setItem("key", "value2");

RequireJS

您可以将 localForage 与RequireJS一起使用：

define(['localforage'], function(localforage) {
    // As a callback:
    localforage.setItem('mykey', 'myvalue', console.log);

    // With a Promise:
    localforage.setItem('mykey', 'myvalue').then(console.log);
});

TypeScript

如果你在tsconfig.json中设置了allowSyntheticDefaultImports编译器选项（TypeScript v1.8+ 支持），你应该使用：true

import localForage from "localforage";

否则，您应该使用以下方法之一：

import * as localForage from "localforage";
// or, in case that the typescript version that you are using
// doesn't support ES6 style imports for UMD modules like localForage
import localForage = require("localforage");

框架支持

如果您使用列出的框架，则框架中的模型有一个 localForage 存储驱动程序，因此您可以使用 localForage 离线存储数据。我们有以下框架的驱动程序：

• AngularJS
• Angular 4 及更高版本
• Backbone
• Ember
• Vue
• NuxtJS

如果您有想要列出的驱动程序，请 打开一个问题将其添加到此列表中。

自定义驱动程序

如果需要，您可以创建自己的驱动程序；请参阅 defineDriverAPI 文档。

wiki 上有一个自定义驱动程序列表。

在 localForage 上工作

你需要node/npm和 bower。

要在 localForage 上工作，您应该首先 分叉它并安装它的依赖项。替换 USERNAME为您的 GitHub 用户名并运行以下命令：

# Install bower globally if you don't have it:
npm install -g bower

# Replace USERNAME with your GitHub username:
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 上支持的所有浏览器运行测试。

大小

从 1.7.3 版开始，添加到您的应用程序的有效负载相当小。使用 gzip 压缩提供服务，localForage 将为您的总包大小增加不到 10k：

minified ~29kBgzipped ~8.8kBbrotli'd~7.8kB

License

This program is free software; it is distributed under an Apache License.

Copyright (c) 2013-2016 Mozilla (Contributors).