PhoneGap API帮助文档翻译—Storage（存储）

文章源自:http://blog.csdn.net/phonegapcn/article/details/6702943

提供对设备的存储选项的访问。

此 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

openDatabase

返回一个新的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>

name:数据库的名称。

version:数据库的版本号。

display_name:数据库的显示名。

size:以字节为单位的数据库大小。

Database:包含允许用户操作数据库的方法。

方法：

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设备不支持此方法。

SQLTransaction

包含允许用户对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>

SQLResultSet

当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>

SQLResultSetList

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

出现错误时，将抛出一个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对象。

localStorage

提供对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 API帮助文档翻译—Storage（存储）

相关推荐