README

如果你不需要支持旧版本的 Internet Explorer（IE7及以下），请使用 simpleStorage。

jStorage

jStorage 是一个跨浏览器的键值存储数据库，用于在浏览器中本地存储数据 - jStorage 支持所有主流浏览器，包括 桌面（是的，甚至是 Internet Explorer 6）和 移动。

此外，jStorage 与任何其他 JavaScript 库无关，它可以很好地与同一页面上的任何其他 JavaScript 库一起工作，无论是 jQuery、Prototype、MooTools 还是其他任何东西。尽管如此，你仍然需要在页面上有第三方库（Prototype、MooTools）或 JSON2 来支持旧版本的 IE。

jStorage 支持存储字符串、数字、JavaScript 对象、数组，甚至原生 XML 节点，这使得它类似于 JSON 存储。jStorage 还支持为存储的键设置 TTL 值以便自动过期，并且 - 最好的是 - 当键值改变时通知其他标签页/窗口，这使得 jStorage 也成为 Web 应用的本地 PubSub 平台。

jStorage 非常小巧，压缩后约为 7kB，gzip 压缩后约为 3kB。

函数参考

set(key, value[, options])

$.jStorage.set(key, value, options)

将值保存到本地存储。key 必须是字符串，否则会抛出异常。value 可以是任何可 JSON 化的值，包括对象和数组或 XML 节点。目前 XML 节点不能嵌套在其他对象中： $.jStorage.set("xml", xml_node) 是可行的，但 $.jStorage.set("xml", {xml: xml_node}) 是不可行的。

Options 是一个可选的选项对象。目前只有一个可用选项是 options.TTL，可以用来为键设置 TTL 值 $.jStorage.set(key, value, {TTL: 1000})。注意 - 如果没有设置 TTL 选项值，将删除键当前使用的任何 TTL 值。

get(key[, default])

value = $.jStorage.get(key)
value = $.jStorage.get(key, "default value")

如果键存在，则 get 获取其值，否则获取默认值。key 必须是字符串，否则会抛出异常。默认值可以是任何值。

deleteKey(key)

$.jStorage.deleteKey(key)

从存储中删除一个键。key 必须是字符串，否则会抛出异常。

setTTL(key, ttl)

$.jStorage.set("mykey", "keyvalue");
$.jStorage.setTTL("mykey", 3000); // expires in 3 seconds

为现有键设置 TTL（以毫秒为单位）。使用 0 或负值来清除 TTL。

getTTL(key)

ttl = $.jStorage.getTTL("mykey"); // TTL in milliseconds or 0
Gets remaining TTL (in milliseconds) for a key or 0 if not TTL has been set.

flush()

$.jStorage.flush()

清除缓存。

index()

$.jStorage.index()

返回当前正在使用的所有键的数组。

var index = $.jStorage.index();
console.log(index); // ["key1","key2","key3"]

storageSize()

$.jStorage.storageSize()

返回存储数据的字节数。

currentBackend()

$.jStorage.currentBackend()

返回当前正在使用的存储引擎或如果没有则返回 false。

reInit()

$.jStorage.reInit()

从浏览器存储重新加载数据。

storageAvailable()

$.jStorage.storageAvailable()

如果存储可用，则返回 true。

subscribe(channel, callback)

$.jStorage.subscribe("ch1", function(channel, payload){
    console.log(payload+ " from " + channel);
});

订阅一个发布/订阅频道（请参阅演示）

publish(channel, payload)

$.jStorage.publish("ch1", "data");

将有效载荷发布到发布/订阅频道（请参阅演示）

listenKeyChange(key, callback)

$.jStorage.listenKeyChange("mykey", function(key, action){
    console.log(key + " has been " + action);
});

监听选定键的更新。注意！即使是其他窗口/标签页中做出的更新也会反映出来，因此该功能也可以用于某些类型的发布/订阅服务。

如果你想监听任何键的变化，请使用 "*" 作为键名

$.jStorage.listenKeyChange("*", function(key, action){
    console.log(key + " has been " + action);
});

stopListening(key[, callback])

$.jStorage.stopListening("mykey"); // cancel all listeners for "mykey" change

停止监听键变化。如果设置了回调，则仅清除使用的回调，否则将删除所有监听器。

捐赠

支持 jStorage 开发

特性

jStorage 支持以下特性

• 使用任何与JSON兼容的数据格式（+原生XML节点）从浏览器存储中存储和检索数据
• 为存储的键设置TTL值以实现自动过期
• 发布和订阅跨窗口/标签页事件
• 监听当前或任何其他浏览器窗口中的键变更（更新、删除）
• 支持任何浏览器，包括IE6，桌面和移动端

浏览器支持

当前可用性：jStorage支持所有主流浏览器 - Internet Explorer 6+、Firefox 2+、Safari 4+、Chrome 4+、Opera 10.50+

如果浏览器不支持数据缓存，则不会抛出异常 - jStorage仍可通过脚本使用，但实际上不会存储任何内容。

测试

查看单元测试 tests/index.html

文档

项目主页和文档：www.jstorage.info

许可证

Unlicense 自版本 0.4.7以来

MIT（版本至 0.4.6）