Qt Quick Local Storage QML Types

Il s'agit d'un type unique permettant de lire et d'écrire dans les bases de données SQLite.

Méthodes

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

Description détaillée

Pour utiliser les types de ce module, il suffit d'importer le module et d'appeler les fonctions concernées à l'aide du type LocalStorage:

import QtQuick
import QtQuick.LocalStorage

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

Ces bases de données sont spécifiques à l'utilisateur et à QML, mais accessibles à toutes les applications QML. Elles sont stockées dans le sous-répertoire Databases de QQmlEngine::offlineStoragePath(), actuellement sous forme de bases de données SQLite.

Les connexions aux bases de données sont automatiquement fermées lors de la collecte des déchets Javascript.

L'API peut être utilisée à partir de fonctions JavaScript dans votre QML :

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()
    }
}

L'API est conforme à l'API synchrone de l'API de base de données Web HTML5, projet de travail du W3C du 29 octobre 2009.

L'exemple de stockage local SQL démontre les bases de l'utilisation de l'API de stockage hors ligne.

Ouvrir ou créer une base de données

import QtQuick.LocalStorage as Sql

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

Le code ci-dessus renvoie la base de données identifiée par l'identifiant. Si la base de données n'existe pas encore, elle est créée et la fonction callback est appelée avec la base de données comme paramètre. identifier est le nom du fichier physique (avec ou sans chemin relatif) contenant la base de données. description et estimated_size sont écrits dans le fichier INI (décrit ci-dessous), mais sont actuellement inutilisés.

Peut lever une exception avec la propriété de code SQLException.DATABASE_ERR, ou SQLException.VERSION_ERR.

Lorsqu'une base de données est créée pour la première fois, un fichier INI spécifiant ses caractéristiques est également créé :

Ces données peuvent être utilisées par des outils d'application.

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

Cette méthode permet d'effectuer une mise à jour du schéma. Si elle réussit, elle renvoie un nouvel objet de base de données de la version to. Dans le cas contraire, elle renvoie une valeur indéfinie.

Si la version actuelle de db n'est pas from, une exception est levée.

Dans le cas contraire, une transaction de base de données est créée et transmise à la fonction callback. Dans cette fonction, vous pouvez appeler executeSql sur tx pour mettre à jour la base de données.

Une exception peut être levée avec la propriété de code SQLException.DATABASE_ERR ou SQLException.UNKNOWN_ERR.

Voir l'exemple ci-dessous.

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

Cette méthode crée une transaction en lecture/écriture et la transmet à la fonction callback. Dans cette fonction, vous pouvez appeler executeSql sur tx pour lire et modifier la base de données.

Si la fonction callback génère des exceptions, la transaction est annulée. Vous trouverez ci-dessous un exemple de transaction de base de données qui capture les exceptions.

{
    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)
    };
}

Dans l'exemple, vous pouvez voir une instruction insert dans laquelle des valeurs sont attribuées aux champs et l'enregistrement est écrit dans la table. Il s'agit d'une instruction insert dont la syntaxe est habituelle pour une base de données relationnelle. Toutefois, il est également possible de travailler avec des objets JSON et de les stocker dans une table.

Prenons un exemple simple où nous stockons des voyages au format JSON en utilisant date comme clé unique. Voici un exemple de tableau qui pourrait être utilisé à cette fin :

create table trip_log(date text, data text)

L'affectation de valeurs à un objet JSON :

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

Dans ce cas, les données peuvent être sauvegardées de la manière suivante :

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

db.readTransaction(callback(tx))

Cette méthode crée une transaction en lecture seule et la transmet à la fonction callback. Dans cette fonction, vous pouvez appeler executeSql sur tx pour lire la base de données (avec des instructions select ).

results = tx.executeSql(statement, values)

Cette méthode exécute une instruction SQL, en liant la liste des valeurs aux paramètres positionnels SQL (" ?").

Elle renvoie un objet results, avec les propriétés suivantes :

Peut lever une exception avec la propriété de code SQLException.DATABASE_ERR, SQLException.SYNTAX_ERR, ou SQLException.UNKNOWN_ERR.

Voir l'exemple ci-dessous :

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
                             })
        }
    })
}

Documentation de la méthode

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

Ouvre ou crée une base de données sql de stockage local en fonction des paramètres donnés.

• name est le nom de la base de données
• version est la version de la base de données
• description est le nom d'affichage de la base de données
• estimated_size est la taille estimée de la base de données, en octets
• callback est un paramètre facultatif, qui est invoqué si la base de données n'a pas encore été créée.

Renvoie l'objet de base de données créé.