在Qt Quick 视图中使用SQL数据库粒子与Graphical Effects

Qt Quick Local Storage QML Types

这是一个用于读写 SQLite 数据库的单例类。

方法

对象 openDatabaseSync(string name, string version, string description, 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 垃圾回收期间，数据库连接会自动关闭。

您可以在 QML 中的 JavaScript 函数中使用该 API：

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 的同步 API 规范（W3C 工作草案，2009 年 10 月 29 日）。

SQL 本地存储示例演示了使用离线存储 API 的基础知识。

打开或创建数据库

import QtQuick.LocalStorage as Sql

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

上述代码将返回由identifier 标识的数据库。如果该数据库尚不存在，则会创建该数据库，并以该数据库作为参数调用函数callback。identifier是包含该数据库的物理文件的名称（可带或不带相对路径）。description和estimated_size会被写入 INI 文件（如下所述），但目前尚未使用。

可能会抛出代码属性为 SQLException.DATABASE_ERR 或 SQLException.VERSION_ERR 的异常。

首次创建数据库时，还会生成一个 INI 文件，用于指定其特性：

键	值
标识符	传递给`openDatabase()`
版本	传递给数据库的版本`openDatabase()`
描述	传递给的数据库的描述`openDatabase()`
EstimatedSize	传递给的数据库的估计大小（以字节为单位）`openDatabase()`
驱动程序	当前为“QSQLITE”

应用程序工具可以使用这些数据。

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

此方法允许您执行方案升级。如果成功，则返回版本为to 的新数据库对象；否则返回undefined。

如果db的当前版本不为from，则会抛出异常。

否则，将创建一个数据库事务并将其传递给callback。在此函数中，您可以调用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对象并将它们存储在表中。

让我们假设一个简单的示例：我们将行程以JSON格式存储，并使用date 作为唯一键。以下是一个可用于此目的的表示例：

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 位置参数（“？”）上。

它返回一个 results 对象，该对象具有以下属性：

类型	属性	值	适用性
int	rows.length	结果中的行数	SELECT
var	rows.item(i)	返回结果中第 i行数据的功能	SELECT
int	rowsAffected	受修改操作影响的行数	UPDATE、DELETE
字符串	插入ID	插入行的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 是一个可选参数，当数据库尚未创建时会调用该参数。

返回已创建的数据库对象。

在Qt Quick 视图中使用SQL数据库粒子与Graphical Effects

© 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.