您现在的位置: IOS教程網 >> IOS系統 >  >> iOS 程式開發 >> iOS 開發綜合

PhoneGap API 中文說明文件:Storage(本機儲存)

編輯:iOS 開發綜合

Storage 模組概覽

Storage 模組提供對裝置本機儲存機制的存取能力。這套 API 並非 PhoneGap 獨創,而是建立在兩個 W3C 規格之上:Web SQL Database Specification 與 Web Storage API Specification。

這樣的設計帶來一個好處:如果裝置本身已經實作這些規格,PhoneGap 會直接採用內建實作;只有在缺少原生儲存支援的平台上,才會退回使用 PhoneGap 自己的相容實作。無論走哪一條路,開發者看到的介面都保持一致。

模組的組成如下:

  • 方法:openDatabase
  • 參數:name、version、display_name、size
  • 物件:Database、SQLTransaction、SQLResultSet、SQLResultSetList、SQLError、localStorage

openDatabase

開啟(或建立)一個 SQLite 資料庫,並傳回代表它的 Database 物件。

var dbShell = window.openDatabase(name, version, display_name, size);

四個參數的意義:

  • name:資料庫名稱。
  • version:資料庫版本號。
  • display_name:顯示用名稱。
  • size:資料庫大小,單位為位元組。

支援平台:Android、BlackBerry WebWorks(OS 6.0 以上)、iPhone。

// 簡短範例
var db = window.openDatabase("test", "1.0", "Test DB", 1000000);

Database

代表一個資料庫連線,提供操作資料的方法:

  • transaction:執行一個資料庫交易。
  • changeVersion:以原子性的方式校驗並更新版本號,通常用於資料表結構升級。

支援平台: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>

SQLTransaction

當你呼叫 Database 的 transaction 方法,回呼函式會收到一個 SQLTransaction 物件。透過在同一個交易物件上多次呼叫 executeSql,就能把多條 SQL 包裝成一個具原子性的交易單元。

tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);

支援平台:Android、BlackBerry WebWorks(OS 6.0 以上)、iPhone。

SQLResultSet

executeSql 的成功回呼會收到一個 SQLResultSet 物件,它有三個屬性:

  • insertId:插入作業所產生的最後一列記錄的 ID。若語句並非 INSERT,則此值不設定。
  • rowAffected:受語句影響的列數。查詢時恆為 0,INSERT 或 UPDATE 時才是實際變動筆數。
  • rows:一個 SQLResultSetList 物件,裝著查詢結果;若無結果則為空。
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);

SQLResultSetList

作為 SQLResultSet 的 rows 屬性,負責承載查詢結果。

  • 屬性 length:符合條件的列數。
  • 方法 item(index):依索引取出該列,傳回一個 JavaScript 物件,其屬性即為查詢所涉及的各欄位。
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

資料庫操作失敗時會拋出一個 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:逾時

localStorage

如果你不需要 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 即可。兩者都不需要伺服器參與,資料完全留在裝置本機,因此也要留意配額上限與使用者清除資料的行為。

  1. 上一篇文章:
  2. 下一篇文章:
蘋果刷機越獄教程| IOS教程問題解答| IOS技巧綜合| IOS7技巧| IOS8教程
Copyright © IOS教程網 All Rights Reserved