在 PhoneGap 中,與儲存相關的物件主要有以下幾個:
Database 資料庫物件
SQLTransaction 交易物件
SQLResultSet 查詢結果物件
SQLResultSetList 查詢返回資料集物件
SQLError 錯誤物件
localStorage 本地儲存物件
透過 openDatabase 方法取得該物件:
var dbOne = window.openDatabase("test1", "1.0", "Test DB", 1000000);
四個參數分別是資料庫名稱、版本、顯示名稱與大小。建立完成後,在 Android 上可以在 /data/data/包名/app_database/dbOne.db 找到剛建立的資料庫檔,並用 DDMS 查看。
PhoneGap 沒有直接取得交易物件的方法,而是透過 Database 物件的 transaction 方法,把交易物件作為參數傳給一個回呼函式:
dbOne.transaction(createATable, errorCreateTable, successCreateTable);
其中 createATable 就是接收交易物件的回呼函式,有了交易物件,就能用它的 executeSql 方法執行 SQL:
function createATable(trans){
trans.executeSql('CREATE TABLE IF NOT EXISTS MyTab (id unique, data)');
trans.executeSql('INSERT INTO MyTab (id, data) VALUES (1, "First row")');
}
SQLError 同樣以參數形式傳給回呼函式。若上面的 transaction 執行失敗,就會呼叫 errorCreateTable,並把 SQLError 物件傳進去:
function errorCreateTable(err){
alert("err code:" + err.code + " err message:" + err.message);
}
code 與 message 是 SQLError 物件的兩個屬性。
SQLResultSet 由交易物件的 executeSql 方法傳給回呼函式,它包含三個屬性:insertId(插入資料行的 row ID)、rowsAffected(受影響的資料行數)、rows(一個 SQLResultSetList 物件,代表查詢返回的所有資料行)。
SQLResultSetList 則包含一個 length 屬性(資料行數)與一個 item 方法(取得某個特定資料行):
function querySuccess(trans, results){
var len = results.rows.length;
for (var i = 0; i < len; i++){
console.log("Row = " + i + " ID = " + results.rows.item(i).id + " Data = " + results.rows.item(i).data);
}
}
這個物件與手機裝置上的儲存沒有直接關係,而是 HTML5 本地儲存所提供的介面。
以下示範建立資料庫、建立資料表、插入資料並查詢的完整流程。HTML 部分:
<button onclick="pgapStorage()">pgapStorage</button>
<script type="text/javascript" src="cordova-2.1.0.js"></script>
<script type="text/javascript" src="pgapstorage.js"></script>
JS 部分:
function pgapStorage(){
// 建立或開啟資料庫,大小 100000 bytes
var dbOne = window.openDatabase("myDataBase", "1.0", "phonegapdatabase", 100000);
dbOne.transaction(createATable, errorCreateTableTrans, successCreateTableTrans);
}
function createATable(trans){
trans.executeSql('DROP TABLE IF EXISTS MyTab');
trans.executeSql('CREATE TABLE IF NOT EXISTS MyTab (id unique, data)');
trans.executeSql('INSERT INTO MyTab (id, data) VALUES (1, "First row")');
trans.executeSql('INSERT INTO MyTab (id, data) VALUES (2, "Second row")');
}
function errorCreateTableTrans(err){
alert("err code:" + err.code + " err message:" + err.message);
}
function successCreateTableTrans(){
var dbOne = window.openDatabase("myDataBase", "1.0", "phonegapdatabase", 100000);
dbOne.transaction(queryMyTab, successQueryMyTabTrans, errorQueryMyTabTrans);
}
function queryMyTab(trans){
trans.executeSql('SELECT * FROM MyTab', [], successQueryMyTab, errorQueryMyTab);
}
function successQueryMyTab(trans, results){
var len = results.rows.length;
for (var i = 0; i < len; i++){
alert("Row = " + i + " ID = " + results.rows.item(i).id + " Data = " + results.rows.item(i).data);
}
}
function errorQueryMyTab(err){
alert("err code:" + err.code + " err message:" + err.message);
}
透過這套 Database、SQLTransaction 與 SQLResultSet 的搭配,你就能在 PhoneGap 應用裡完成資料的持久化儲存與查詢了。