Storage 模組提供對裝置本機儲存機制的存取能力。這套 API 並非 PhoneGap 獨創,而是建立在兩個 W3C 規格之上:Web SQL Database Specification 與 Web Storage API Specification。
這樣的設計帶來一個好處:如果裝置本身已經實作這些規格,PhoneGap 會直接採用內建實作;只有在缺少原生儲存支援的平台上,才會退回使用 PhoneGap 自己的相容實作。無論走哪一條路,開發者看到的介面都保持一致。
模組的組成如下:
openDatabasename、version、display_name、sizeDatabase、SQLTransaction、SQLResultSet、SQLResultSetList、SQLError、localStorage開啟(或建立)一個 SQLite 資料庫,並傳回代表它的 Database 物件。
var dbShell = window.openDatabase(name, version, display_name, size);
四個參數的意義:
支援平台:Android、BlackBerry WebWorks(OS 6.0 以上)、iPhone。
// 簡短範例
var db = window.openDatabase("test", "1.0", "Test DB", 1000000);
代表一個資料庫連線,提供操作資料的方法:
支援平台:Android、BlackBerry WebWorks(OS 6.0 以上)、iPhone。值得一提的是,Android 1.X 並不支援 changeVersion。
// 交易範例
function populateDB(tx) {
tx.executeSql('DROP TABLE DEMO IF EXISTS');
tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "First row")');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Second row")');
}
function errorCB(err) {
alert("Error processing SQL: " + err.code);
}
function successCB() {
alert("success!");
}
var db = window.openDatabase("Database", "1.0", "PhoneGap Demo", 200000);
db.transaction(populateDB, errorCB, successCB);
// 版本升級範例
db.changeVersion("1.0", "1.1");
包裝成完整頁面的寫法:
<!DOCTYPE html>
<html>
<head>
<title>Storage Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
var db = window.openDatabase("Database", "1.0", "PhoneGap Demo", 200000);
db.transaction(populateDB, errorCB, successCB);
}
// 建立資料表並寫入資料
function populateDB(tx) {
tx.executeSql('DROP TABLE DEMO IF EXISTS');
tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "First row")');
tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Second row")');
}
function errorCB(tx, err) {
alert("Error processing SQL: " + err);
}
function successCB() {
alert("success!");
}
</script>
</head>
<body>
<h1>Example</h1>
<p>Database</p>
</body>
</html>
當你呼叫 Database 的 transaction 方法,回呼函式會收到一個 SQLTransaction 物件。透過在同一個交易物件上多次呼叫 executeSql,就能把多條 SQL 包裝成一個具原子性的交易單元。
tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
支援平台:Android、BlackBerry WebWorks(OS 6.0 以上)、iPhone。
executeSql 的成功回呼會收到一個 SQLResultSet 物件,它有三個屬性:
function queryDB(tx) {
tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
}
function querySuccess(tx, results) {
// 因為沒有插入記錄,所以 insertId 為空
console.log("Insert ID = " + results.insertId);
// 查詢語句恆為 0
console.log("Rows Affected = " + results.rowAffected);
// 查到的列數
console.log("Row count = " + results.rows.length);
}
function errorCB(err) {
alert("Error processing SQL: " + err.code);
}
var db = window.openDatabase("Database", "1.0", "PhoneGap Demo", 200000);
db.transaction(queryDB, errorCB);
作為 SQLResultSet 的 rows 屬性,負責承載查詢結果。
function querySuccess(tx, results) {
var len = results.rows.length;
console.log("DEMO 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);
}
}
支援平台:Android、BlackBerry WebWorks(OS 6.0 以上)、iPhone。
資料庫操作失敗時會拋出一個 SQLError 物件,包含 code(錯誤碼)與 message(錯誤說明)兩個屬性。可用的錯誤碼常量:
SQLError.UNKNOWN_ERR:未知錯誤SQLError.DATABASE_ERR:資料庫錯誤SQLError.VERSION_ERR:版本錯誤SQLError.TOO_LARGE_ERR:資料集過大SQLError.QUOTA_ERR:超出配額SQLError.SYNTAX_ERR:語法錯誤SQLError.CONSTRAINT_ERR:約束錯誤SQLError.TIMEOUT_ERR:逾時如果你不需要 SQL,只想存幾組鍵值對,localStorage 會更省事。它對應 W3C Storage 介面,以 key-value 的形式保存字串資料。
var storage = window.localStorage;
可用方法:
key(index):傳回指定位置的鍵名。getItem(key):取出指定鍵的值。setItem(key, value):寫入一組鍵值對。removeItem(key):刪除指定鍵。clear():清空所有鍵值對。支援平台:Android、BlackBerry WebWorks(OS 6.0 以上)、iPhone。
// 各方法的簡短用法
var keyName = window.localStorage.key(0);
window.localStorage.setItem("key", "value");
var value = window.localStorage.getItem("key"); // value 現在是 "value"
window.localStorage.removeItem("key");
window.localStorage.clear();
完整範例:
<!DOCTYPE html>
<html>
<head>
<title>localStorage Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
window.localStorage.setItem("key", "value");
var keyname = window.localStorage.key(0);
// keyname 現在是 "key"
var value = window.localStorage.getItem("key");
// value 現在是 "value"
window.localStorage.removeItem("key");
window.localStorage.setItem("key2", "value2");
window.localStorage.clear();
// localStorage 現在是空的
}
</script>
</head>
<body>
<h1>Example</h1>
<p>localStorage</p>
</body>
</html>
選型上可以這樣想:結構化、需要關聯查詢的資料交給 Web SQL;零散設定值、偏好選項這類簡單資料用 localStorage 即可。兩者都不需要伺服器參與,資料完全留在裝置本機,因此也要留意配額上限與使用者清除資料的行為。