HTML5 Indexed Database API 入門(6) - 關於資料庫版本


每一個資料庫都會有一個版本號碼,DBDatabase 介面定義了一個 version 屬性,引用此屬性可以取得資料庫的版本資訊,當你開啟一個新的資料庫,若是沒有特別指定,一個新建立的資料庫其 version 屬性將是空值。

版本資訊是一組號碼,以 long 型態的數字作表示,這個值並非固定的,如果需要對其進行變更,於開啟連線時同時指定版本號碼即可,例如以下的程式碼:

var request = indexedDB.open('KTMS', n);

其中調用 open() 方法指定了第二個參數 n ,這個 n 將成為 KTMS 資料庫的最新版本號碼。

版本號碼的變更只能比目前資料庫的版本號碼大,這會觸發一個版本升級事件 upgradeneeded ,如果 n 與原來的資料庫版本相同,則會成功開啟資料庫連線, n 不能小於原來的版本號碼,否則會導致資料庫開啟過程的錯誤發生並且觸發 error 事件。

upgradeneeded 會在資料庫版本變更時被觸發,當你執行與資料庫物件結構改變有關的操作時-例如新增或是刪除物件倉儲,必須在這個事件處理器中執行,而其事件處理器參數同時提供了與版本資訊有關的屬性以支援存取操作,以下透過一個簡單的範例進行說明。


執行此範例首先會出現以下的畫面:


於「版本」文字方塊中,輸入欲調整的版本號碼,例如 62 ,由於小於目前的版本 65 ,按下「版本設定按鈕」畫面下方會顯示錯誤訊息,如右圖:


若是輸入大於目前版本的號碼,例如 66 ,則會進行新的版本設定,並出現以下的訊息,左圖的訊息表示完成版本設定,右圖是顯示目前的新版本號碼。



最後顯示如下圖的畫面,表示已經完成資料庫的版本設定並將其開啟。


來看看這個範例的程式碼,首先完成以下的畫面內容標籤配置:


<body>
    <div id="messagev"></div>
    <p>
        版本:<input type="text" id='version'   />
        資料庫:<input type="text" id='dbname' value ="KTMS" />
        <button onclick="click_handler()">版本設定</button>    
    </p>
    <div id="message"></div>
</body>

一開始的 messagev 標籤用來顯示目前的資料庫名稱與版本,接下來提供版本輸入的 <input /> 標籤 id 設定為 version ,而提供資料庫名稱輸入的則是 dbname ,預設名稱為 KTMS ,此為本章示範用的資料庫,後續一連串的範例均將開啟此資料庫進行操作示範,讀者可以自行調整所要建立的資料庫名稱。

於網頁載入之後執行的 onload 事件處理器中,輸入以下的程式碼:

window.onload = function () {
    requestName = document.getElementById('dbname').value;
    request = indexedDB.open(requestName);
    request.onsuccess = function (event) {
        db = event.target.result;
        document.getElementById('messagev').innerHTML =
            '資料庫:' + db.name + ' / 版本:' + db.version;
        db.close();
    };
};

這段程式碼開啟畫面中使用者指定的資料庫 ,並且於完成開啟之後,引用 name 與 version 兩個屬性項目,取得目前資料庫的名稱與版本顯示在畫面上。

function click_handler() {
    var version = parseInt(document.getElementById('version').value);
request = indexedDB.open(requestName, version);
    request.onerror = function (event) {
        document.getElementById('message').innerHTML =
'錯誤:' + event.target.errorCode;
    };
    request.onsuccess = function (event) {
        db = event.target.result;
        document.getElementById('message').innerHTML =
('資料庫開啟 /' + db.version);
    };
    request.onupgradeneeded = function (event) {
        alert('版本升級:' + event.oldVersion + '/' + event.newVersion);
        alert('目前版本:' + event.target.result.version);
    };
    db.close();
}

當使用者按下「版本設定」按鈕執行此段程式碼,其中調用 open() 以指定的版本 version 開啟資料庫,而當指定的版本號碼比原來資料庫的版本大的時候,便會觸發一個 upgradeneeded 事件,第二段反白的程式碼註冊此事件處理器,並且透過引用事件參數 event 的 oldVersion 取代原來的資料庫版本,而 newVersion 則是升級後的版本,這些資訊最後被整合顯示在畫面上。

如果指定的版本出現問題,例如小於目前的版本號碼,則會觸發 error 事件,事件處理器將顯示相關的訊息。而在成功開啟資料庫之後,會執行 success 事件處理器。

此範例最重要的是 upgradeneeded 事件,請特別注意這裏所示範例的事件處理器設定與事件的觸發時機,後續討論物件倉儲的建立與刪除作業時,會需要這一部份的相關知識。 

HTML5 Indexed Database API 入門系列


沒有留言: