“ | 提供對設備的存儲選項的訪問。 |
此API基於W3C
WEB SQL Database Specification和W3C Web Storage API Specification。有些設備已經提供了對該規範的實現,對於這些設備採用內置實現而非使用PhoneGap的實現。對於沒有存儲支持的設備,PhoneGap的實現應該是完全兼容W3C規範。
方法:
- openDatabase
參數:
- name
- version
- display_name
- size
對象:
- Database
- SQLTransaction
- SQLResultSet
- SQLResultSetList
- SQLError
- localStorage
返回一個新的Database對象。
var dbShell = window.openDatabase(name, version, display_name, size);
說明:
window.openDatabase返回一個新的Database對象。
該方法將創建一個新的SQL Lite數據庫,並返回該Database對象。可使用該Database對象操作數據。
支持的平臺:
- Android
- BlackBerry WebWorks (OS 6.0或更高版本)
- iPhone
簡單的範例:
var db = window.openDatabase("test", "1.0", "Test DB", 1000000);
完整的範例:
<!DOCTYPE html>
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// 等待加載PhoneGap
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap加載完畢
function onDeviceReady() {
var db = window.openDatabase("test", "1.0", "Test DB", 1000000);
}
</script>
</head>
<body>
<h1>Example</h1>
<p>Open Database</p>
</body>
</html>
包含允許用戶操作數據庫的方法。
方法:
- transaction:運行一個數據庫事務。
- changeVersion:該方法允許腳本執行以下原子操作:校驗數據庫的版本號並更新版本號以完成架構更新。
詳述:
調用window.openDatabase()將返回一個Database對象。
支持的平臺:
- Android
- BlackBerry WebWorks (OS 6.0或更高版本)
- iPhone
Transaction 的簡單範例:
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);
Change Version的簡單範例:
var db = window.openDatabase("Database", "1.0", "PhoneGap Demo", 200000);
db.changeVersion("1.0", "1.1");
完整的範例:
<!DOCTYPE html>
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// 等待加載PhoneGap
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap加載完畢
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>
Android 1.X 的特異情況:
- changeVersion:Android 1.X設備不支持此方法。
包含允許用戶對Database對象執行SQL語句的方法。
方法:
- executeSql:執行一條SQL語句。
詳述:
當你調用Database對象的transaction方法後,其回調函數將被調用並接收一個SQLTransaction對象。用戶可以通過多次調用executeSql來建立一個數據庫事務處理。
支持的平臺:
- Android
- BlackBerry WebWorks (OS 6.0或更高版本)
- iPhone
Execute SQL的簡單範例:
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);
}
function successCB() {
alert("success!");
}
var db = window.openDatabase("Database", "1.0", "PhoneGap Demo", 200000);
db.transaction(populateDB, errorCB, successCB);
完整的範例:
<!DOCTYPE html>
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// 等待加載PhoneGap
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap加載完畢
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(err) {
alert("Error processing SQL: "+err);
}
// 事務執行成功後調用的回調函數
function successCB() {
alert("success!");
}
</script>
</head>
<body>
<h1>Example</h1>
<p>SQLTransaction</p>
</body>
</html>
當SQLTransaction對象的executeSql方法被調用,將會觸發executeSql中設定的回調函數並返回一個SQLResultSet對象。
屬性:
- insertId:SQLResultSet對象通過SQL語句插入到數據庫的行記錄的行ID。[譯註:如果插入多行的時候,返回最後一個行的ID]
- rowAffected:被SQL語句改變的記錄行數,如果語句沒有影響任何行則設置爲0。
- rows:是一個SQLResultSetRowList對象,表示返回的多條記錄。如果沒有返回任何記錄,則此對象爲空。
詳述:
當你調用SQLTransaction對象的executeSql方法,將會觸發executeSql中設定的回調函數並返回一個SQLResultSet對象。該結果對象包含三個屬性:第一個是insertID返回成功的SQL插入語句所插入行的ID,如果SQL語句不是插入語句則insertID將不被設定;第二個是rowAffected,在SQL查詢操作時此屬性總是0,當插入或更新操作時此屬性返回受到影響的行數;最後一個屬性是SQLResultSetList類型,返回SQL查詢語句的返回數據。
支持的平臺:
- Android
- BlackBerry WebWorks (OS 6.0或更高版本)
- iPhone
Execute SQL的簡單範例:
function queryDB(tx) {
tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
}
function querySuccess(tx, results) {
// 因爲沒有插入記錄,所以返回值爲空
console.log("Insert ID = " + results.insertId);
// 因爲這是一條查詢語句所以返回值爲0
console.log("Rows Affected = " + results.rowAffected);
// 返回查詢到的記錄行數量
console.log("Insert ID = " + 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);
完整的範例:
<!DOCTYPE html>
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// 等待加載PhoneGap
document.addEventListener("deviceready", onDeviceReady, false);
// 填充數據庫
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 queryDB(tx) {
tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
}
// 查詢成功後調用的回調函數
function querySuccess(tx, results) {
// 因爲沒有插入記錄,所以返回值爲空
console.log("Insert ID = " + results.insertId);
// 因爲這是一條查詢語句所以返回值爲0
console.log("Rows Affected = " + results.rowAffected);
// 返回查詢到的記錄行數量
console.log("Insert ID = " + results.rows.length);
}
// 事務執行出錯後調用的回調函數
function errorCB(err) {
console.log("Error processing SQL: "+err.code);
}
// 事務執行成功後調用的回調函數
function successCB() {
var db = window.openDatabase("Database", "1.0", "PhoneGap Demo", 200000);
db.transaction(queryDB, errorCB);
}
// PhoneGap加載完畢
function onDeviceReady() {
var db = window.openDatabase("Database", "1.0", "PhoneGap Demo", 200000);
db.transaction(populateDB, errorCB, successCB);
}
</script>
</head>
<body>
<h1>Example</h1>
<p>Database</p>
</body>
</html>
SQLResultSet對象的一個屬性,包含SQL查詢所返回的所有行數據。
屬性:
- length: SQL查詢所返回的記錄行數。
方法:
- item:根據指定索引返回一個行記錄的JavaScript對象。
詳述:
SQlResultSetList包含一個SQL查詢語句所返回的數據。該對象包含一個長度屬性告知用戶有多少符合查詢條件的行記錄數被返回。通過傳遞指定的索引給該對象的item方法獲取指定的行記錄數據,此item方法返回一個JavaScript對象,其屬性包含前述查詢語句所針對的數據庫的所有列。
支持的平臺:
- Android
- BlackBerry WebWorks (OS BlackBerry WebWorks (OS 6.0或更高版本)
- iPhone
Execute SQL的簡單範例:
function queryDB(tx) {
tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
}
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);
}
}
function errorCB(err) {
alert("Error processing SQL: "+err.code);
}
var db = window.openDatabase("Database", "1.0", "PhoneGap Demo", 200000);
db.transaction(queryDB, errorCB);
完整的範例:
<!DOCTYPE html>
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// 等待加載PhoneGap
document.addEventListener("deviceready", onDeviceReady, false);
// 填充數據庫
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 queryDB(tx) {
tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
}
// 查詢成功後調用的回調函數
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);
}
}
// 事務執行出錯後調用的回調函數
function errorCB(err) {
console.log("Error processing SQL: "+err.code);
}
// 事務執行成功後調用的回調函數
function successCB() {
var db = window.openDatabase("Database", "1.0", "PhoneGap Demo", 200000);
db.transaction(queryDB, errorCB);
}
// PhoneGap加載完畢
function onDeviceReady() {
var db = window.openDatabase("Database", "1.0", "PhoneGap Demo", 200000);
db.transaction(populateDB, errorCB, successCB);
}
</script>
</head>
<body>
<h1>Example</h1>
<p>Database</p>
</body>
</html>
出現錯誤時,將拋出一個SQLError對象。
屬性:
- code: 一個在下面常量列表中定義好的錯誤代碼c。
- 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:超時錯誤
說明:
操作數據庫出現錯誤時,將拋出一個SQLError對象。
提供對W3C Storage接口(http://dev.w3.org/html5/webstorage/#the-localstorage-attribute)的訪問。
var storage = window.localStorage;
方法:
- key:返回指定位置的鍵的名稱。
- getItem: 返回指定鍵所對應的記錄。
- setItem:存儲一個鍵值對。
- removeItem:刪除指定鍵對應的記錄。
- clear:刪除所有的鍵值對。
詳述:
localStorage提供對W3C Storage接口的訪問,可以使用鍵值對的方式存儲數據。
支持的平臺:
- Android
- BlackBerry WebWorks(OS 6.0或更高版本)
- iPhone
Key 的簡單範例:
var keyName = window.localStorage.key(0);
Set Item的簡單範例:
window.localStorage.setItem("key", "value");
Get Item的簡單範例:
var value = window.localStorage.getItem("key");
// value的值現在是"value"
Remove Item的簡單範例:
window.localStorage.removeItem("key");
Clear的簡單範例:
window.localStorage.clear();
完整的範例:
<!DOCTYPE html>
<html>
<head>
<title>Contact Example</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// 等待加載PhoneGap
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap加載完畢
function onDeviceReady() {
window.localStorage.setItem("key", "value");
var keyname = window.localStorage.key(i);
[譯註:應當是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>
更多信息參考:
PhoneGap中國:www.phonegap.cn
中文討論組:groups.google.com/group/PhoneGapCN