PhoneGap 中與儲存相關的物件共六個:
透過 openDatabase 取得,四個參數分別是名稱、版本、顯示名稱與大小:
window.openDatabase(database_name, database_version,
database_displayname, database_size);
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);
function createATable(trans) {
trans.executeSql('CREATE TABLE IF NOT EXISTS MyTab (id unique, data)');
tx.executeSql('INSERT INTO MyTab (id, data) VALUES (1, "First row")');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Second row")');
}
這裡的 trans 就是事務物件,有了它便能呼叫 executeSql 執行 SQL。上例建立了 MyTab 表並插入兩筆資料。
錯誤物件同樣以參數形式傳給回呼函數。上面那行呼叫中的 errorCreateTable 就是失敗時的回呼:
function errorCreateTable(err) {
alert("err code: " + err.code + " err message: " + err.message);
}
code 與 message 是 SQLError 的兩個主要屬性。
由 executeSql 傳給回呼函數,回呼簽名固定為兩個參數——事務物件與結果集物件:
tx.executeSql('SELECT * FROM MyTab', [], querySuccess, errorCB);
function querySuccess(trans, results) {
alert("Returned rows = " + results.rows.length);
if (!results.rowsAffected) {
alert('No rows affected!');
return false;
}
}
SQLResultSet 有三個屬性:
這個物件有一個屬性 length(資料行數)與一個方法 item(index)(取得第 index 筆資料)。逐列讀取的典型寫法:
function querySuccess(trans, results) {
var len = results.rows.length;
console.log("MyTab table: " + len + " rows found.");
for (var i = 0; i < len; i++) {
console.log("Row = " + i
+ " ID = " + results.rows.item(i).id
+ " Data = " + results.rows.item(i).data);
}
}
值得澄清的是,localStorage 與手機裝置上的原生儲存沒有直接關係,它是 HTML5 本地儲存規範提供的一組介面,PhoneGap 只是讓它在 WebView 中可用。適合存放少量、結構簡單的鍵值資料(例如使用者偏好設定),大量或需要查詢的資料仍應走上面的 SQLite 路徑。
HTML 部分:
<!DOCTYPE html> <html> <head> <title>new document</title> <script type="text/javascript" charset="utf-8" src="cordova-2.1.0.js"></script> <script type="text/javascript" charset="utf-8" src="pgapstorage.js"></script> </head> <body> <button onclick="pgapStorage()">pgapStorage</button> </body> </html>
JS 部分:
function pgapStorage() {
// 建立或開啟資料庫,大小 100000 bytes
var dbOne = window.openDatabase("myDataBase", "1.0", "phonegapdatabase", 100000);
// 把事務物件傳給 createATable;失敗時把 SQLError 傳給 errorCreateTableTrans
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() {
alert("successfully");
var dbOne = window.openDatabase("myDataBase", "1.0", "phonegapdatabase", 100000);
dbOne.transaction(queryMyTab, successQueryMyTabTrans, errorQueryMyTabTrans);
}
function successQueryMyTabTrans() {
alert("successQueryMyTabTrans");
}
function errorQueryMyTabTrans(err) {
alert("err code: " + err.code + " err message: " + err.message);
}
// 查詢:成功走 successQueryMyTab,失敗走 errorQueryMyTab
function queryMyTab(trans) {
trans.executeSql('SELECT * FROM MyTab', [], successQueryMyTab, errorQueryMyTab);
}
function successQueryMyTab(trans, results) {
var len = results.rows.length;
alert(len);
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);
}
整組 API 都是回呼式的,這帶來一個實務上的注意點:查詢必須寫在「建立成功」的回呼裡,而不能寫在建立之後順著往下排。範例中 successCreateTableTrans 之所以要再開一次資料庫並啟動新事務,就是因為外層的事務已經結束,無法重用。理解「事務的邊界由回呼決定」這一點,能省下不少 debug 時間。