Qt Quick Local Storage QML Types

これはSQLiteデータベースを読み書きするためのシングルトン型である。

メソッド

オブジェクト openDatabaseSync(文字列名, 文字列バージョン, 文字列説明, int estimated_size, jsobject callback(db))

詳しい説明

このモジュールの型を使用するには、モジュールをインポートし、LocalStorage 型を使用して関連する関数を呼び出します：

import QtQuick
import QtQuick.LocalStorage

Item {
    Component.onCompleted: {
        var db = LocalStorage.openDatabaseSync(...)
    }
}

これらのデータベースはユーザ固有のものであり、QML固有のものですが、すべてのQMLアプリケーションからアクセス可能です。これらのデータベースは、QQmlEngine::offlineStoragePath()のDatabases サブディレクトリに、現在のところSQLiteデータベースとして格納されています。

データベース接続はJavascriptのガベージコレクション時に自動的に閉じられます。

APIはQMLのJavaScript関数から利用することができます：

import QtQuick

Rectangle {
    color: "white"
    width: 200
    height: 100

    Text {
        text: "?"
        anchors.horizontalCenter: parent.horizontalCenter
        function findGreetings() {
            var db = openDatabaseSync("QDeclarativeExampleDB", "1.0", "The Example QML SQL!", 1000000);

            db.transaction(
                function(tx) {
                    // Create the database if it doesn't already exist
                    tx.executeSql('CREATE TABLE IF NOT EXISTS Greeting(salutation TEXT, salutee TEXT)');

                    // Add (another) greeting row
                    tx.executeSql('INSERT INTO Greeting VALUES(?, ?)', [ 'hello', 'world' ]);

                    // Show all added greetings
                    var rs = tx.executeSql('SELECT * FROM Greeting');

                    var r = ""
                    for (var i = 0; i < rs.rows.length; i++) {
                        r += rs.rows.item(i).salutation + ", " + rs.rows.item(i).salutee + "\n"
                    }
                    text = r
                }
            )
        }
        Component.onCompleted: findGreetings()
    }
}

このAPIはHTML5 Web Database APIのSynchronous API,W3C Working Draft 29 October 2009に準拠しています。

SQL Local Storage の例では、Offline Storage API の基本的な使い方を説明しています。

データベースのオープンまたは作成

import QtQuick.LocalStorage as Sql

db = Sql.openDatabaseSync(identifier, version, description, estimated_size, callback(db))

上記のコードはidentifier で識別されるデータベースを返します。データベースがまだ存在しない場合は作成され、データベースをパラメータとして関数のコールバックが呼び出されます。identifierはデータベースを含む物理ファイル名（相対パスの有無は問いません）です。descriptionと estimated_sizeはINIファイル（後述）に書き込まれますが、現在は未使用です。

コードプロパティ SQLException.DATABASE_ERR または SQLException.VERSION_ERR を持つ例外を投げる可能性があります。

データベースが最初に作成されるとき、その特性を指定するINIファイルも作成されます：

キー	値
識別子	に渡されるデータベースの名前。`openDatabase()`
バージョン	渡されたデータベースのバージョン`openDatabase()`
説明	渡されたデータベースの説明`openDatabase()`
推定サイズ	に渡されるデータベースの推定サイズ（バイト）。`openDatabase()`
ドライバ	現在は "QSQLITE"

このデータはアプリケーション・ツールで使用できます。

db.changeVersion(from, to, callback(tx))

このメソッドでScheme Upgradeを実行できます。成功すれば、新しいデータベースオブジェクトを返します。そうでない場合は未定義を返します。

dbの現在のバージョンがfrom でない場合は例外がスローされます。

そうでない場合は、データベース・トランザクションが作成され、コールバックに渡されます。この関数では、データベースをアップグレードするためにtxに対して executeSqlを呼び出すことができます。

コードプロパティ SQLException.DATABASE_ERR または SQLException.UNKNOWN_ERR を持つ例外がスローされる可能性があります。

以下の例を参照してください。

    var db = LocalStorage.openDatabaseSync("ActivityTrackDB", "", "Database tracking sports
activities", 1000000); if (db.version == "0.1") { db.changeVersion("0.1", "0.2", function(tx) {
            tx.executeSql("INSERT INTO trip_log VALUES(?, ?, ?)",
                        [ "01/10/2016","Sylling - Vikersund", "53" ]);
        }
    });

db.transaction(callback(tx))

このメソッドは読み取り/書き込みトランザクションを作成し、コールバックに渡します。この関数では、txに対してexecuteSql を呼び出すことで、データベースの読み取りと変更を行うことができます。

コールバックが例外をスローした場合、トランザクションはロールバックされます。以下に、例外をキャッチするデータベーストランザクションの例を示します。

{
    let db = LocalStorage.openDatabaseSync("Activity_Tracker_DB", "", "Track exercise", 1000000)
    try {
        db.transaction(function (tx) {
            tx.executeSql('CREATE TABLE IF NOT EXISTS trip_log (date text,trip_desc text,distance numeric)')
        })
    } catch (err) {
        console.log("Error creating table in database: " + err)
    };
}

この例では、フィールドに値が代入され、レコードがテーブルに書き込まれるinsert 。これは、リレーショナル・データベースで一般的な構文のinsert 。しかし、JSONオブジェクトを操作してテーブルに格納することも可能である。

単純な例として、date をユニークキーとして、JSON形式で旅行を保存する場合を考えてみよう。そのために使用できるテーブルの例です：

create table trip_log(date text, data text)

JSONオブジェクトへの値の割り当て：

var obj = {description = "Vikersund - Noresund", distance = "60"}

その場合、データは次のように保存できる：

db.transaction(function(tx) {
    result = tx.executeSQL("insert into trip_log values (?,?)",
                           ["01/11/2016", JSON.stringify(obj)])

db.readTransaction(callback(tx))

このメソッドは読み取り専用のトランザクションを作成し、コールバックに渡す。この関数では、txに対してexecuteSql を呼び出してデータベースを読み込むことができます（select ステートメントを使用）。

results = tx.executeSql(statement, values)

このメソッドは SQL文を実行し、値のリストを SQL の位置パラメーター ("?") にバインドします。

以下のプロパティを持つ結果オブジェクトを返します：

タイプ	プロパティ	値	適用性
int	行の長さ	結果の行数	SELECT
var	rows.item(i)	結果のi行目を返す関数	SELECT
int	影響を受ける行数	変更によって影響を受ける行の数。	UPDATE、DELETE
文字列	insertId	挿入された行のID	INSERT

コードプロパティ SQLException.DATABASE_ERR、SQLException.SYNTAX_ERR、または SQLException.UNKNOWN_ERR を持つ例外をスローする可能性があります。

例を以下に示します：

function dbReadAll()
{
    let db = dbGetHandle()
    db.transaction(function (tx) {
        let results = tx.executeSql(
                'SELECT rowid,date,trip_desc,distance FROM trip_log order by rowid desc')
        for (let i = 0; i < results.rows.length; i++) {
            listModel.append({
                                 id: results.rows.item(i).rowid,
                                 checked: " ",
                                 date: results.rows.item(i).date,
                                 trip_desc: results.rows.item(i).trip_desc,
                                 distance: results.rows.item(i).distance
                             })
        }
    })
}

メソッドのドキュメント

object openDatabaseSync(string name, string version, string description, int estimated_size,
jsobject callback(db))

与えられたパラメータでローカルストレージの sql データベースをオープンまたは作成します。

name はデータベース名です。
version はデータベースのバージョンです。
description はデータベースの表示名です。
estimated_size はデータベースの推定サイズ（バイト単位）です。
callback はオプションのパラメータで、データベースがまだ作成されていない場合に呼び出されます。

作成されたデータベースオブジェクトを返します。

本ドキュメントに含まれる文書の著作権は、それぞれの所有者に帰属します。本書で提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の商標です。その他すべての商標は、それぞれの所有者に帰属します。