En esta página

Qt Quick Local Storage QML Types

Se trata de un tipo «singleton» para leer y escribir en bases de datos SQLite.

Métodos

  • objeto openDatabaseSync(string nombre, string versión, string descripción, int tamaño_estimado, jsobject callback(db))

Descripción detallada

Para utilizar los tipos de este módulo, importa el módulo y llama a las funciones pertinentes utilizando el tipo ` LocalStorage `:

import QtQuick
import QtQuick.LocalStorage

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

Estas bases de datos son específicas de cada usuario y de QML, pero son accesibles para todas las aplicaciones QML. Se almacenan en el subdirectorio « Databases » de « QQmlEngine::offlineStoragePath » (), actualmente como bases de datos SQLite.

Las conexiones a las bases de datos se cierran automáticamente durante la recolección de basura de JavaScript.

La API se puede utilizar desde funciones de JavaScript en tu 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()
    }
}

La API cumple con la API síncrona de la API de bases de datos web de HTML5, borrador de trabajo del W3C del 29 de octubre de 2009.

El ejemplo «Almacenamiento local SQL» muestra los conceptos básicos del uso de la API de almacenamiento sin conexión.

Abrir o crear una base de datos

import QtQuick.LocalStorage as Sql

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

El código anterior devuelve la base de datos identificada por «identifier». Si la base de datos aún no existe, se crea y se invoca la función callback con la base de datos como parámetro. «identifier» es el nombre del archivo físico (con o sin ruta relativa) que contiene la base de datos. «description» y «estimated_size» se escriben en el archivo INI (descrito más adelante), pero actualmente no se utilizan.

Puede lanzar una excepción con la propiedad de código SQLException.DATABASE_ERR o SQLException.VERSION_ERR.

Cuando se crea una base de datos por primera vez, también se crea un archivo INI en el que se especifican sus características:

ClaveValor
IdentificadorEl nombre de la base de datos pasado a openDatabase()
VersiónLa versión de la base de datos pasada a openDatabase()
DescripciónLa descripción de la base de datos pasada a openDatabase()
Tamaño estimadoEl tamaño estimado (en bytes) de la base de datos pasada a openDatabase()
ControladorActualmente «QSQLITE»

Estos datos pueden ser utilizados por las herramientas de la aplicación.

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

Este método permite realizar una actualización de Scheme. Si se ejecuta correctamente, devuelve un nuevo objeto de base de datos con la versión «to». En caso contrario, devuelve «undefined».

Si la versión actual de db no es «from», se lanza una excepción.

De lo contrario, se crea una transacción de base de datos y se pasa a callback. En esta función, puedes llamar a executeSql sobre tx para actualizar la base de datos.

Puede lanzar una excepción con la propiedad de código SQLException.DATABASE_ERR o SQLException.UNKNOWN_ERR.

Véase el ejemplo a continuación.

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

Este método crea una transacción de lectura/escritura y la pasa a la función de llamada de retorno. En esta función, puedes llamar a `executeSql` sobre `tx` para leer y modificar la base de datos.

Si la función de llamada de retorno lanza excepciones, la transacción se revierte. A continuación encontrarás un ejemplo de una transacción de base de datos que captura excepciones.

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

En el ejemplo se puede ver una instrucción ` insert ` en la que se asignan valores a los campos y el registro se escribe en la tabla. Se trata de una instrucción ` insert ` con una sintaxis habitual en las bases de datos relacionales. No obstante, también es posible trabajar con objetos JSON y almacenarlos en una tabla.

Supongamos un ejemplo sencillo en el que almacenamos viajes en formato JSON utilizando « date » como clave única. Un ejemplo de tabla que podría utilizarse para ese fin:

create table trip_log(date text, data text)

La asignación de valores a un objeto JSON:

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

En ese caso, los datos se podrían guardar de la siguiente manera:

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

db.readTransaction(callback(tx))

Este método crea una transacción de solo lectura y la pasa a callback. En esta función, puedes llamar a executeSql sobre tx para leer la base de datos (con sentencias de tipo « select »).

results = tx.executeSql(statement, values)

Este método ejecuta una instrucción SQL, vinculando la lista de valores a los parámetros posicionales de SQL («?»).

Devuelve un objeto «results», con las siguientes propiedades:

TipoPropiedadValorAplicabilidad
introws.lengthEl número de filas del resultadoSELECT
varrows.item(i)Función que devuelve la fila i del resultadoSELECT
introwsAffectedEl número de filas afectadas por una modificaciónUPDATE, DELETE
cadenainsertIdEl identificador de la fila insertadaINSERT

Puede lanzar una excepción con la propiedad de código SQLException.DATABASE_ERR, SQLException.SYNTAX_ERR o SQLException.UNKNOWN_ERR.

A continuación se muestra un ejemplo:

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

Documentación del método

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

Abre o crea una base de datos SQL de almacenamiento local según los parámetros indicados.

  • name es el nombre de la base de datos
  • version es la versión de la base de datos
  • description es el nombre de visualización de la base de datos
  • estimated_size es el tamaño estimado de la base de datos, en bytes
  • callback es un parámetro opcional que se ejecuta si la base de datos aún no se ha creado.

Devuelve el objeto de base de datos creado.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.