59

0

localForage

localForage 是一个 JavaScript 库,通过简单类似 localStorage API 的异步存储来改进你的 Web 应用程序的离线体验。它能存储多种类型的数据,而不仅仅是字符串。

localForage

NPM 版本 npm jsDelivr 命中 压缩后的大小

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()您可以使用该方法设置数据库信息。可用选项有 drivernamestoreNameversionsizedescription

例子:

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 离线存储数据。我们有以下框架的驱动程序:

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

自定义驱动程序

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

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

在 localForage 上工作

你需要node/npmbower

要在 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).