用於瀏覽器本地存儲的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

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

jQuery

<script src="//cdnjs.cloudflare.com/ajax/libs/json2/20110223/json2.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.8.0/jquery.min.js"></script>
<script src="https://raw.github.com/andris9/jStorage/master/jstorage.js"></script>
<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將被刪除。

示例：

<script src="json2.js"></script>
<script src="jquery.js"></script>
<script src="jstorage.js"></script>
<script>
 $.jStorage.set("key1", "value1", {TTL: 3000});
 setInterval(function(){
    var vaule = $.jStorage.get("key1");
    document.writeln(vaule + ";");
 },1000);
</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

示例：

<script>
 $.jStorage.set("key1", "value1", {TTL: 5000});
 setInterval(function(){
    var ttl = $.jStorage.getTTL("key1");
    document.writeln(ttl + ";");
 },1000);
</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通道
示例：

<script src="json2.js"></script>
<script src="jquery.js"></script>
<script src="jstorage.js"></script>
<script>
  function sync(){
      $.jStorage.publish("sync-textarea", $("data").value);
  }
  $.jStorage.subscribe("sync-textarea", function(channel, data){
      $("data").value = data;
  });
</script>
<div>
  <h2>Interactive test - publish/subscribe</h2>
  <p>Open the same page in other tabs or windows of the same browser</p>
  <p><textarea id="data" style="width: 600px; height: 100px;"></textarea></p>
  <p><input type="button" id="nupp" value="Sync entered data with other tabs/windows" onclick="sync()"></p>
</div>

listenKeyChange(key, callback)

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

監聽key值update，設置回調函數處理。在其他窗口/標簽的更新有會觸發，所以這個功能也可以用於某種形式的發布/訂閱服務。

示例：

<pre name="code" class="html">  <script src="json2.js"></script>
  <script src="jquery.js"></script>
  <script src="jstorage.js"></script>
  <script>
    function changeKey(){
      $.jStorage.set("mykey", 1);
    }
    function deleteKey(){
      $.jStorage.deleteKey("mykey");
    }
    $.jStorage.listenKeyChange("mykey", function(key, action){
        console.log(key + " has been " + action);
    });
    $.jStorage.listenKeyChange("mykey", function(key, action){
        console.log(key + " has been:::: " + action);
    });
  </script>
  <div>
    <p><input type="button" onclick="changeKey()" value="changeKey"></p>
    <p><input type="button" onclick="deleteKey()" value="deleteKey"></p>
  </div></pre>

stopListening(key[, callback]) 

$.jStorage.stopListening("mykey")     —— 清除mykey的所有listeners，如果callback設置了，只有使用過的回調會被清除，否則所有的listeners都會被丟棄

使用示例

<span style="font-weight:normal">jQuery -jQuery沒有內置JSON編碼/解碼器，如果要支持IE6//IE7，需要以如下方式引用
<script src="//cdnjs.cloudflare.com/ajax/libs/json2/20110223/json2.js"></script>
<script src="//code.jquery.com/jquery-1.9.1.min.js"></script>
<script src="jstorage.js"></script>
<script>
// Check if "key" exists in the storage
var value = $.jStorage.get("key");
if(!value){
    // if not - load the data from the server
    value = load_data_from_server()
    // and save it
    $.jStorage.set("key",value);
}
</script></span>

<span style="font-weight:normal">Prototype
<script src="//ajax.googleapis.com/ajax/libs/prototype/1.7.1.0/prototype.js"></script>
<script src="jstorage.js"></script>
<script>
// Check if "key" exists in the storage
var value = $.jStorage.get("key");
if(!value){
    // if not - load the data from the server
    value = load_data_from_server()
    // and save it
    $.jStorage.set("key",value);
}
</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,  [e-mail]
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/