更新记录

1.2.8（2026-10-07）

• 完善示例项目。

1.2.7（2026-10-07）

• 修复已知问题。

1.2.6（2026-10-07）

• 修复已知问题。

平台兼容性

uni-app(4.83)

uni-app x(4.83)

其他

umi-sqlite

uni-app x App 原生 SQLite 插件（Android / iOS / HarmonyOS）。

• Android：android.database.sqlite.SQLiteDatabase（openOrCreateDatabase / compileStatement / rawQuery）
• iOS：系统 SQLite3 C API（Swift 混编 UmiSqliteKit，sqlite3_open_v2 + sqlite3_bind_* + sqlite3_step）
• 鸿蒙：@kit.ArkData relationalStore（getRdbStore / executeSql / querySql / beginTransaction）

仅 App。Android、iOS 真机运行必须打 自定义基座。鸿蒙走原生编译，无需自定义基座。

加密后的普通授权版只能从 @/uni_modules/umi-sqlite 导入，不要写 utssdk/ 内部路径。

API

用工厂函数构造 options，不要给插件 class 的 boolean 字段赋值，也不要手写对象字面量。Android / 鸿蒙工厂返回对应 class。iOS 工厂返回 UTSJSONObject（蒸汽模式不能把只有带参构造的 class 再传回原生），调用写法相同：openDatabase(sqliteOpenOptions(name))。

UmiSqliteOpenOptions（openDatabase）

工厂：sqliteOpenOptions(name)（path 为空）、sqliteOpenOptionsAt(name, path)。

UmiSqliteNameOptions（isOpenDatabase / closeDatabase）

工厂：sqliteNameOptions(name)。

UmiSqliteSqlOptions（executeSql / selectSql）

工厂：sqliteSqlOptions(name, sql)（args 为空）、sqliteSqlOptionsWithArgs(name, sql, args)。

executeSql 成功返回 UmiSqliteExecResult：changes 为受影响行数，lastInsertRowId 为最近插入行 id（非 INSERT 时可能为 0）。

UmiSqliteTxOptions（transaction）

工厂：sqliteTxOptions(name, operation)，例如 sqliteTxOptions(DB, 'begin')。其它字符串会失败（「事务操作仅支持 begin / commit / rollback」）。

建议：begin 成功后再执行 SQL；全部成功再 commit；任一步失败再 rollback。不要在未 begin 时直接 commit / rollback。

示例：

import {
    sqliteOpenOptions,
    sqliteNameOptions,
    sqliteSqlOptions,
    sqliteSqlOptionsWithArgs,
    sqliteTxOptions,
    openDatabase,
    isOpenDatabase,
    closeDatabase,
    executeSql,
    selectSql,
    transaction,
    readAnyErrMsg,
    UmiSqliteExecResult
} from '@/uni_modules/umi-sqlite'

const DB = 'umi_demo'

openDatabase(sqliteOpenOptions(DB)).then(() => {
    executeSql(sqliteSqlOptions(DB, 'CREATE TABLE IF NOT EXISTS todo (id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT, done INTEGER)')).then((_ddl : UmiSqliteExecResult) => {
        executeSql(sqliteSqlOptionsWithArgs(DB, 'INSERT INTO todo(title, done) VALUES (?, ?)', ['hello', 0])).then((ins : UmiSqliteExecResult) => {
            selectSql(sqliteSqlOptions(DB, 'SELECT id, title, done FROM todo ORDER BY id DESC')).then((rows : UTSJSONObject[]) => {
                console.log(rows, ins.lastInsertRowId)
            })
        })
    })
}, (err : any | null) => {
    console.log(readAnyErrMsg(err, '打开失败'))
})

事务：

transaction(sqliteTxOptions(DB, 'begin')).then(() => {
    executeSql(sqliteSqlOptionsWithArgs(DB, 'INSERT INTO todo(title, done) VALUES (?, ?)', ['a', 0])).then(() => {
        transaction(sqliteTxOptions(DB, 'commit'))
    }, (err : any | null) => {
        transaction(sqliteTxOptions(DB, 'rollback'))
    })
})

自定义路径（Android / iOS 为真实 sqlite 文件；鸿蒙写入应用沙箱 databaseDir/rdb/，path 只解析文件名和相对 customDir）：

openDatabase(sqliteOpenOptionsAt(DB, '/storage/emulated/0/Android/data/包名/files/demo.db'))

示例中心（Android / iOS / 鸿蒙）

Android 批量事务与线程

Android SQLite 的事务状态绑定当前线程。Vapor 下把 transaction(begin)、executeSql、transaction(commit) 拆成多次跨桥调用，可能切换线程而等待数据库连接，表现为一直“正在处理”。示例的批量插入、事务提交与回滚在 Android 上改用单次原生 executeSqlBatch 调用，事务开启、所有写入和结束在同一线程同步完成；iOS、鸿蒙仍走各端原有接口。页面共用代码通过 APP-ANDROID 条件编译选择分支。

Android 专用接口：executeSqlBatch(name: string, sql: string, argsJson: string, operation: string): Promise<string>。argsJson 是二维参数数组的 JSON，每行对应一次 SQL；operation 为 commit 或 rollback。成功返回 "ok"，异常时结束事务并拒绝 Promise，未标记成功的写入自动回滚。该接口不会嵌套调用其他 Promise，也不会通过页面拆分事务。

// #ifdef APP-ANDROID
import { executeSqlBatch } from '@/uni_modules/umi-sqlite'
const rows : any[][] = [['示例一', 0], ['示例二', 0]]
const json = JSON.stringify(rows)
if (json != null) {
    await executeSqlBatch('umi_demo', 'INSERT INTO todo(title, done) VALUES (?, ?)', json as string, 'commit')
}
// #endif

若旧代码已卡在事务中，先停止并重新启动应用，重新编译原生插件（使用自定义基座时重打），再测试；单纯页面热刷新无法保证释放旧线程持有的事务。

VDOM / Vapor 与样式隔离 2.0

保持 manifest.json 的 uni-app-x.styleIsolationVersion 为 "2"，仅通过 vapor 切换模式：false 为 VDOM，true 为 Vapor。示例页显式声明 defineOptions({ styleIsolation: 'isolated' })，布局和文字样式全部在该页面中定义，不依赖全局样式穿透；input 上的 class 作用于组件根节点，maxlength 使用数值绑定。此页面不使用组件内部样式穿透。

main.uts 保留标准的 createSSRApp(App) / return { app } 入口，由编译器处理挂载和隔离初始化。不要在业务代码中手动调用 mount、提供假的 enableStyleIsolation，或修改 unpackage 中的产物。

页面通过 options 工厂和 sqliteRowCell 访问三端原生插件，避免直接调用原生类型；iOS options 使用 UTSJSONObject，Android/鸿蒙由各端工厂构造对应对象。VDOM 和 Vapor 使用相同业务代码。

可执行 node scripts/verify-compatibility.cjs 做源码检查，默认使用 D:/office/HBuilderX/plugins/uniapp-cli-vite/node_modules 内置编译依赖；其他安装位置可通过 HBUILDERX_NODE_MODULES 指定。此检查覆盖页面 UTS 语法、Vue 模板、页面样式、三端接口导出，以及 iOS 两种模式的入口转换；不等于三端原生构建、Vapor 模板后端或真机测试通过。

真机验收需分别在 Android、iOS、鸿蒙的 VDOM / Vapor 下运行以下场景。切换模式后重新生成对应模式的资源，并在使用自定义基座时重新构建安装。原生 SDK 应与编译器版本一致。

曾在 iOS 5.24 的 VDOM 启动阶段遇到 enableStyleIsolation undefined、container._vnode undefined。检查本地 IPA，hxVersion 和 uniRuntimeVersion 均为 5.24，内置框架也存在 enableStyleIsolation 导出，因此尚不能确定根因是版本不匹配。需要完整启动堆栈、实际安装包和运行模式进一步诊断；不得通过关闭样式隔离 2.0 宣称已修复。

项目的 pages/index/index.uvue 提供三端共用的交互示例，使用默认库 umi_demo 和 todo 表，兼容已有示例数据。先点击“打开库”完成连接和建表，再体验以下操作。

查询、更新和删除使用参数绑定，不拼接输入值。页面处理操作期间阻止其他数据库按钮重复执行，未打开或未完成建表时给出提示；操作日志保留最近 30 条。写操作后的结果仍遵循当前筛选条件，查看新数据时可点击“查看全部”。

参数化 SQL 示例（通过 sqliteSqlOptionsWithArgs(DB, sql, args) 调用）：

INSERT INTO todo(title, done) VALUES (?, ?);
SELECT id, title, done FROM todo
WHERE title LIKE ? AND done = ? ORDER BY id DESC LIMIT 20;
UPDATE todo SET done = ? WHERE id = ?;
UPDATE todo SET done = ? WHERE done = ?;
DELETE FROM todo WHERE id = ?;
DELETE FROM todo WHERE done = ?;

三端验收建议：首次进入直接点击插入、查询、事务，应该提示先打开；打开后清空示例数据，批量插入应得到 10 条；事务提交后应得到 13 条，回滚后仍为 13 条；选择一条标为完成，筛选“已完成”应能查到；删除已完成后应剩 12 条；关闭并重开数据仍保留。删除确认框点击取消时不应改变数据。iOS 修改原生插件后需重新编译安装对应应用或自定义基座。

注意

• executeSql 不要跑 SELECT；查询用 selectSql。
• Android rawQuery 的绑定参数只能是字符串，数字/布尔会转成文本再绑定。写操作走 SQLiteStatement，可按 null / 整数 / 浮点 / 文本绑定。
• 鸿蒙库文件由 StoreConfig.name 管理，不要指望任意绝对路径可写。
• 跨插件不要事后写 boolean 字段；本插件 options 只用 string / number / any[]。
• 页面 import 的函数必须出现在各端 utssdk/app-*/index.uts 的 export function / export class 中。