用于浏览器本地存储的js插件 - jStorage

简介

jStorage是一个跨浏览器的将key-value类型的数据存储到浏览器本地存储的js插件——jStorage支持所有主流浏览器，PC机（甚至包括是IE6）和移动终端均可用。此外，jStorage的实现不依赖任何其它js库(库无关)，它和其他js库(Query, Prototype, MooTools等)有良好的兼容性。但是为了让它能够支持老版本的IE(比如蛋疼的IE6)，需要依赖第三方库（Prototype, MooTools）或JSON2。

jStorage支持存储Strings，Numbers，JavaScript对象，Arrays，甚至是原生XML节点。 jStorage还支持设置TTL(Time to Live， 生存时间)类型的值用于自动到期存储的keys。最重要的是(也是attractive的) - 当浏览器页签中某个key值变更时或者订阅/发布事件以通知其他标签/窗口的能力。这使得jStorage能够成为Web应用程序本地PubSub(publish/subscribe)平台。

jStorage非常小，min压缩后只有7kb，zip打包后只有4kb。

索引

1. 基本信息
2. 下载
3. 交互测试
4. 浏览器支持
5. 用法
6. 函数参考
7. 使用示例
8. 问题
9. 联系和版权

基本信息

jStorage利用HTML5本地存储和IE低版本的userData behavior实现浏览器本地存储。

当前的可用情况：jStorage支持所有主流浏览器 — Internet Explorer 6+, Firefox 2+, Safari 4+, Chrome 4+, Opera 10.50+，如果浏览器不支持数据存储，也不会有任何异常产生—— jStorage仍然可以使用，只是没有实际存储而已。

下载

地址：github  (直接下载)

交互测试

添加一些值，并刷新页面 - 如果您的浏览器支持本地数据存储，那么值应该在页面刷新后依然存在。测试

测试订阅/发布事件

测试和第三方库并存的功能性

单元测试

浏览器支持

Browser	Storage support	Survives browser restart	Survives browser crash	Storage size
Chrome 4	+	+	+	5 MB
Firefox 3.6	+	+	+	5 MB
Firefox 3	+	+	+	5 MB
Firefox 2	+	+	+	5 MB
IE8	+	+	+	10 MB
IE7	+	+	+	128 kB
IE6	+	+	+	128 kB
Opera 10.50	+	+	-	5 MB
Opera 10.10	-	N/A	N/A	N/A
Safari 4	+	+	+	5 MB
Iphone Safari	+	+	+	5 MB
Safari 3	-	N/A	N/A	N/A

用法

jStorage的使用需要引入Prototype/MooTools/jQuery +jQuery-JSON /JSON2，无论哪种方式，语法保持不变。

JSON2

1. <script src="//cdnjs.cloudflare.com/ajax/libs/json2/20110223/json2.js"></script>
2. <script src="https://raw.github.com/andris9/jStorage/master/jstorage.js"></script>
3. <script> /* $.jStorage is now available */ </script>

jQuery

1. <script src="//cdnjs.cloudflare.com/ajax/libs/json2/20110223/json2.js"></script>
2. <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.8.0/jquery.min.js"></script>
3. <script src="https://raw.github.com/andris9/jStorage/master/jstorage.js"></script>
4. <script> /* $.jStorage is now available */ </script>

函数参考

set(key, value[, options])

$.jStorage.set(key, value, options)    ——   保存key-value键值对到本地存储。

key需要是字符串，否则会抛异常。

value值可以任意被JSON化的价值，包括对象和数组或XML节点。XML节点不能被嵌套在对象中——

正确用法：$.jStorage.set("xml", xml_node) 

错误：$.jStorage.set("xml", {xml: xml_node}) 

options是可选的对象。目前唯一可用的选项是可以用来设置key值对应的生存时间的值 ($.jStorage.set(key, value, {TTL: 1000});)。 如果TTL值设置为空，任何目前使用的TTL值的key将被删除。

示例：

1. <script src="json2.js"></script>
2. <script src="jquery.js"></script>
3. <script src="jstorage.js"></script>
4. <script>
5. $.jStorage.set("key1", "value1", {TTL: 3000});
6. setInterval(function(){
7. var vaule = $.jStorage.get("key1");
8. document.writeln(vaule + ";");
9. },1000);
10. </script>

get(key[, default])

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

get方法获取key对的vaule值，如果key不存在返回null，default存在时，如果key值存在返回实际值，如不存在返回default值。key需要是字符串，否则会抛异常。

deleteKey(key)

$.jStorage.deleteKey(key)    ——   删除key。key需要是字符串，否则会抛异常。

setTTL(key, ttl)

$.jStorage.set("mykey", "keyvalue");
$.jStorage.setTTL("mykey", 3000);    // TTL3秒
对key设置TTL(毫秒数)。设置0或负值以删除key

getTTL(key)

ttl = $.jStorage.getTTL("mykey");   // TTL in milliseconds or 0
获取key剩余的生存时间(毫秒数)。如果key值不存在或者未设置TTL，返回0

示例：

1. <script>
2. $.jStorage.set("key1", "value1", {TTL: 5000});
3. setInterval(function(){
4. var ttl = $.jStorage.getTTL("key1");
5. document.writeln(ttl + ";");
6. },1000);
7. </script>

flush()

$.jStorage.flush()   ——   清除所有key

index()

$.jStorage.index()   ——   以数组形式返回当前使用的所有key
var index = $.jStorage.index();
console.log(index); // ["key1","key2","key3"]

storageSize()

$.jStorage.storageSize()  ——   返回存储的数据所占用的bytes

currentBackend()

$.jStorage.currentBackend()    ——   返回当前使用的存储引擎，如果没有存储引擎返回false。

reInit()

$.jStorage.reInit()     ——   重载数据。

storageAvailable()

$.jStorage.storageAvailable()     ——   如果存储可用，返回true

subscribe(channel, callback)

$.jStorage.subscribe("ch1", function(channel, payload){    // 订阅 PubSub通道
    console.log(payload+ " from " + channel);
});

publish(channel, payload)

$.jStorage.publish("ch1", "data")     ——    发布有效值到PubSub通道
示例：

1. <script src="json2.js"></script>
2. <script src="jquery.js"></script>
3. <script src="jstorage.js"></script>
4. <script>
5. function sync(){
6. $.jStorage.publish("sync-textarea", $("data").value);
7. }
8. $.jStorage.subscribe("sync-textarea", function(channel, data){
9. $("data").value = data;
10. });
11. </script>
12. <div>
13. <h2>Interactive test - publish/subscribe</h2>
14. <p>Open the same page in other tabs or windows of the same browser</p>
15. <p><textarea id="data" style="width: 600px; height: 100px;"></textarea></p>
16. <p><input type="button" id="nupp" value="Sync entered data with other tabs/windows" onclick="sync()"></p>
17. </div>

listenKeyChange(key, callback)

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

监听key值update，设置回调函数处理。在其他窗口/标签的更新有会触发，所以这个功能也可以用于某种形式的发布/订阅服务。

示例：

1. <pre name="code" class="html">  <script src="json2.js"></script>
2. <script src="jquery.js"></script>
3. <script src="jstorage.js"></script>
4. <script>
5. function changeKey(){
6. $.jStorage.set("mykey", 1);
7. }
8. function deleteKey(){
9. $.jStorage.deleteKey("mykey");
10. }
11. $.jStorage.listenKeyChange("mykey", function(key, action){
12. console.log(key + " has been " + action);
13. });
14. $.jStorage.listenKeyChange("mykey", function(key, action){
15. console.log(key + " has been:::: " + action);
16. });
17. </script>
18. <div>
19. <p><input type="button" onclick="changeKey()" value="changeKey"></p>
20. <p><input type="button" onclick="deleteKey()" value="deleteKey"></p>
21. </div></pre>

stopListening(key[, callback])

$.jStorage.stopListening("mykey")     —— 清除mykey的所有listeners，如果callback设置了，只有使用过的回调会被清除，否则所有的listeners都会被丢弃

使用示例

1. <span style="font-weight:normal">jQuery -jQuery没有内置JSON编码/解码器，如果要支持IE6//IE7，需要以如下方式引用
2. <script src="//cdnjs.cloudflare.com/ajax/libs/json2/20110223/json2.js"></script>
3. <script src="//code.jquery.com/jquery-1.9.1.min.js"></script>
4. <script src="jstorage.js"></script>
5. <script>
6. // Check if "key" exists in the storage
7. var value = $.jStorage.get("key");
8. if(!value){
9. // if not - load the data from the server
10. value = load_data_from_server()
11. // and save it
12. $.jStorage.set("key",value);
13. }
14. </script></span>

1. <span style="font-weight:normal">Prototype
2. <script src="//ajax.googleapis.com/ajax/libs/prototype/1.7.1.0/prototype.js"></script>
3. <script src="jstorage.js"></script>
4. <script>
5. // Check if "key" exists in the storage
6. var value = $.jStorage.get("key");
7. if(!value){
8. // if not - load the data from the server
9. value = load_data_from_server()
10. // and save it
11. $.jStorage.set("key",value);
12. }
13. </script></span>

问题

Why would you want to use jStorage when cookies work already in every browser?

• Cookies are not meant to save large quantities of data locally - they are meant to pass around ID values to keep track of users. Internet Explorer allows to use up to 20 cookies per domain with the payload of 4kB per cookie. It isn't very much, especially considering the need to chunk larger data into smaller bits. The fact that the data (max. 80 kB) is sent to the server with *every* call doesn't sound much of a good idea either.

联系和版权

© 2010 - 2012 Andris Reinman, andris.reinman@gmail.com
jStorage is licensed under MIT-styled license, so basically you can do whatever you want to do with it.

最近开发一个需求，同一个浏览器打开了多个页签，用户在一个页签上点了注销按钮，其他浏览器页签也要被注销。用户闲置30分钟超时也要一样的效果。由于不想从后台向前台发事件，计划借助浏览器本地存储的功能实现。闲逛git无意间发现一个开源小插件，简直是为这需求量身定制，因此翻译这篇API文档。
参考：

http://www.jstorage.info/