更新记录

1.0.0（2026-03-19）

1.0.0

平台兼容性

uni-app x(4.87)

lux-sqlite

适用于 uni-app x 的跨平台 SQLite UTS 插件，API 设计参考 plus.sqlite，支持 Android、iOS、鸿蒙三端。

⚠️ 开发必读

先试用，后付费：建议您先申请插件试用，确认功能完全符合项目需求。

申请试用：建议先下载提供的示例工程, 点击插件页面的“试用”按钮, 导入到示例工程(无法导入就在manufest.json重新获取uniapp应用ID)。
打包基座：由于官方试用限制，请务必进行 制作自定义调试基座 操作，否则插件无法生效。

平台兼容性

安装

将 lux-sqlite 目录放入项目的 uni_modules 文件夹中。
导入插件后，可以直接引入组件 <lime-sqlite /> 查看演示效果

<template>
    <lux-sqlite />
</template>

<script setup lang="uts">
</script>

<style>
</style>

引入

import {
    openDatabase,
    isOpenDatabase,
    closeDatabase,
    executeSql,
    selectSql,
    transaction,
    getDatabasePath
} from '@/uni_modules/lux-sqlite';

import type {
    DatabaseOptions,
    SqlOptions,
    TransactionOptions,
    SqliteSuccess,
    SqliteFail
} from '@/uni_modules/lux-sqlite';

API

openDatabase(options)

打开数据库，如果不存在则自动创建。

参数 DatabaseOptions：

示例：

openDatabase({
    name: 'mydb',
    success: (res: SqliteSuccess) => {
        console.log('打开成功', res.errMsg);
    },
    fail: (res: SqliteFail) => {
        console.error('打开失败', res.errCode, res.errMsg);
    }
});

isOpenDatabase(options): boolean

判断数据库是否已打开，返回 boolean。

参数 DatabaseOptions：

示例：

const isOpen = isOpenDatabase({ name: 'mydb' });
console.log('数据库是否打开：', isOpen);

closeDatabase(options)

关闭已打开的数据库。

参数 DatabaseOptions：

示例：

closeDatabase({
    name: 'mydb',
    success: (res: SqliteSuccess) => {
        console.log('关闭成功');
    }
});

executeSql(options)

执行增删改等不返回结果集的 SQL 语句，支持单条或多条。

参数 SqlOptions：

示例：

// 建表
executeSql({
    name: 'mydb',
    sql: 'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER)',
    success: (res: SqliteSuccess) => {
        console.log('建表成功');
    }
});

// 插入数据
executeSql({
    name: 'mydb',
    sql: "INSERT INTO users (name, age) VALUES ('张三', 18)",
    success: (res: SqliteSuccess) => {
        console.log('插入成功');
    },
    fail: (res: SqliteFail) => {
        console.error('插入失败', res.errMsg);
    }
});

// 批量执行多条 SQL
executeSql({
    name: 'mydb',
    sql: [
        "INSERT INTO users (name, age) VALUES ('李四', 20)",
        "INSERT INTO users (name, age) VALUES ('王五', 25)"
    ],
    success: (res: SqliteSuccess) => {
        console.log('批量插入成功');
    }
});

selectSql(options)

执行查询 SQL，结果通过成功回调的 data 字段返回。

参数 SqlOptions：

示例：

selectSql({
    name: 'mydb',
    sql: 'SELECT * FROM users',
    success: (res: SqliteSuccess) => {
        const rows = res.data ?? [];
        console.log('查询结果，共', rows.length, '条');
        for (let i = 0; i < rows.length; i++) {
            const row = rows[i] as UTSJSONObject;
            console.log('id:', row['id'], 'name:', row['name']);
        }
    },
    fail: (res: SqliteFail) => {
        console.error('查询失败', res.errMsg);
    }
});

transaction(options)

管理事务，支持开始、提交、回滚三种操作。

参数 TransactionOptions：

示例：

// 开始事务
transaction({ name: 'mydb', operation: 'begin' });

// 执行 SQL
executeSql({
    name: 'mydb',
    sql: "UPDATE users SET age = 19 WHERE name = '张三'",
    success: () => {
        // 提交事务
        transaction({ name: 'mydb', operation: 'commit' });
    },
    fail: () => {
        // 回滚事务
        transaction({ name: 'mydb', operation: 'rollback' });
    }
});

getDatabasePath(name): string

获取数据库文件的完整路径。

参数：

返回值： string - 数据库文件的绝对路径

示例：

const dbPath = getDatabasePath('mydb');
console.log('数据库路径：', dbPath);

返回值类型

SqliteSuccess

SqliteFail

错误码

完整示例

import {
    openDatabase,
    isOpenDatabase,
    closeDatabase,
    executeSql,
    selectSql,
    transaction
} from '@/uni_modules/lux-sqlite';
import type { SqliteSuccess, SqliteFail } from '@/uni_modules/lux-sqlite';

const DB_NAME = 'myapp';

// 1. 打开数据库
openDatabase({
    name: DB_NAME,
    success: () => {
        // 2. 建表
        executeSql({
            name: DB_NAME,
            sql: `CREATE TABLE IF NOT EXISTS users (
                id INTEGER PRIMARY KEY AUTOINCREMENT,
                name TEXT NOT NULL,
                age INTEGER
            )`,
            success: () => {
                // 3. 插入数据（使用事务）
                transaction({ name: DB_NAME, operation: 'begin' });
                executeSql({
                    name: DB_NAME,
                    sql: [
                        "INSERT INTO users (name, age) VALUES ('张三', 18)",
                        "INSERT INTO users (name, age) VALUES ('李四', 20)"
                    ],
                    success: () => {
                        transaction({ name: DB_NAME, operation: 'commit' });

                        // 4. 查询数据
                        selectSql({
                            name: DB_NAME,
                            sql: 'SELECT * FROM users',
                            success: (res: SqliteSuccess) => {
                                const rows = res.data ?? [];
                                console.log('查询到', rows.length, '条数据');
                            }
                        });
                    },
                    fail: () => {
                        transaction({ name: DB_NAME, operation: 'rollback' });
                    }
                });
            }
        });
    },
    fail: (res: SqliteFail) => {
        console.error('打开数据库失败：', res.errMsg);
    }
});

注意事项

• iOS 平台：依赖 FMDB 库（CocoaPods 自动安装），需制作自定义基座后才能运行
• HarmonyOS 平台：数据库操作为异步，success/fail 回调会在异步完成后触发；事务操作（begin/commit/rollback）为同步
• 数据库路径：默认存储在应用私有沙盒目录，卸载 App 后数据会被清除
• 多数据库：支持同时管理多个数据库，通过 name 参数区分

平台实现