更新记录

1.0.2（2026-10-15） 下载此版本

修改说明

1.0.1（2026-10-15） 下载此版本

修改说明

1.0.0（2026-10-15） 下载此版本

uts插件，sqlite基础使用，安卓已测试，iOS未测试

平台兼容性

uni-app(4.87)

uni-app x(4.87)

其他

sqlite-native

SQLite 原生插件（UTS）。Android 端基于 SQLiteDatabase、iOS 端基于系统 SQLite3 实现，用法与 plus.sqlite 类似，但改为 Promise 风格，统一返回 { code, message, data } 结构，原 uni-app 项目的调用方式容易平滑迁移。

⚠️ 测试状态（务必先看）

iOS 端已知未验证风险点：

1. app-ios/config.json 中 frameworks: ["libsqlite3.tbd"] 能否正常链接（需 Mac 环境实测）
2. SQLITE_TRANSIENT 宏 Swift 不导入，已用 unsafeBitCast(-1, to: sqlite3_destructor_type.self) 手工构造，绑定中文/长文本未实测
3. 沙盒路径映射（_doc → Documents 等）未在真机确认
4. 返回值类型转换（Swift NSNumber / [UTSJSONObject] → UTS number / UTSJSONObject[]）未实测

使用 iOS 端前，请先在 Mac + Xcode 环境编译自定义基座，用示例页面 pages/index/index.uvue 跑通打开、建表、增删改查、批量事务、分页查询后再接入业务。

特性

• 支持 Android（Kotlin 混编，✅ 已测试）与 iOS（Swift 混编，调用系统 SQLite3，⚠️ 未测试）
• Promise 风格 API，失败不 reject，统一 resolve { code, message, data }，code == 0 表示成功
• 支持 ? 占位符参数绑定，避免 SQL 字符串拼接
• 支持单事务批量执行，任一条失败整体回滚
• 返回 rows 为 UTSJSONObject 数组，兼容任意列类型（数字/文本/null）

目录结构

sqlite-native
├── package.json
└── utssdk
    ├── interface.uts              // 接口与类型声明
    ├── unierror.uts               // 错误码与 message 映射
    ├── app-android
    │   ├── config.json
    │   ├── SqliteNative.kt        // Kotlin 原生实现
    │   └── index.uts              // Android 胶水层
    └── app-ios
        ├── config.json            // 声明系统库 libsqlite3.tbd
        ├── SqliteNative.swift     // Swift 原生实现
        └── index.uts              // iOS 胶水层

引入

import {
    openDatabase,
    isOpenDatabase,
    closeDatabase,
    closeAllDatabase,
    deleteDatabase,
    executeSql,
    executeSqlBatch,
    SqliteDatabaseOptions,
    SqliteExecuteOptions,
    SqliteTransactionOptions
} from '@/uni_modules/sqlite-native'

返回结构

type SqliteEmptyResult = { code : number, message : string, data : any | null }
type SqliteBoolResult = { code : number, message : string, data : boolean | null }
type SqliteDatabaseInfoResult = { code : number, message : string, data : SqliteDatabaseInfo | null }
type SqliteQueryResult = { code : number, message : string, data : SqliteRows | null }

type SqliteDatabaseInfo = { name : string, path : string, filePath : string }
type SqliteRows = { rows : UTSJSONObject[], insertId : number, affectedRows : number }

API

参数说明：

• name：数据库文件名，可带相对路径，如 biz/order.db；没有 .db/.sqlite/.sqlite3 后缀时自动补 .db
• path：数据库所在目录，缺省 _doc
• args：参数数组，按顺序替换 sql 中的 ?
• sqls：SQL 数组，批量在同一事务中执行，失败整体回滚

结果字段说明：

• rows：查询结果集，非查询语句为空数组
• insertId：仅 insert/replace 返回新记录自增 id，其他语句为 -1
• affectedRows：insert/update/delete 为影响行数，select 为结果行数，DDL 为 -1

与 plus.sqlite 的对照

API 命名与入参保持一致，便于从原 uni-app 项目迁移，主要差别是「回调 → Promise」：

迁移示例：

// 原 uni-app 项目
plus.sqlite.executeSql({ name, sql, success: (res) => console.log(res.rows) })

// 本插件
const res = await executeSql({ name, sql } as SqliteExecuteOptions)
if (res.code == 0 && res.data != null) {
    console.log(res.data.rows)
}

错误码

存储目录

Android 从旧版本升级时，若 _doc 下还没有文件而内部 app_doc 中存在同名旧库，会自动迁移到外部专属目录并在控制台打印迁移日志。

使用示例

const options = { name: 'order.db', path: '_doc' } as SqliteDatabaseOptions

// 打开（重复打开会复用已有连接）
const openRes = await openDatabase(options)
if (openRes.code != 0) {
    console.error(openRes.code, openRes.message)
    return
}

// 建表
await executeSql({
    name: 'order.db',
    sql: 'create table if not exists order (id integer primary key autoincrement, no text, amount real)'
} as SqliteExecuteOptions)

// 新增（参数绑定）
const insertRes = await executeSql({
    name: 'order.db',
    sql: 'insert into order (no, amount) values (?, ?)',
    args: ['A001', 99.5]
} as SqliteExecuteOptions)
console.log(insertRes.data?.insertId)

// 查询
const queryRes = await executeSql({
    name: 'order.db',
    sql: 'select id, no, amount from order where amount >= ? order by id desc limit ?',
    args: [50, 10]
} as SqliteExecuteOptions)
if (queryRes.code == 0 && queryRes.data != null) {
    for (const row of queryRes.data.rows) {
        console.log(row.getString('no'), row.getNumber('amount'))
    }
}

// 批量新增（单事务，失败整体回滚）
const batchRes = await executeSqlBatch({
    name: 'order.db',
    sqls: [
        "insert into order (no, amount) values ('A002', 10)",
        "update order set amount = 20 where no = 'A001'",
        "delete from order where amount < 5"
    ]
} as SqliteTransactionOptions)

// 关闭
await closeDatabase(options)

注意事项

• 只读/写入操作均为同步 SQLite 调用，iOS 端方法体默认不在主线程，Android 端 UTS 代码运行在 main 线程，大数据量 SQL 建议自行控制单次数据量
• 数据库连接由插件缓存，closeDatabase / closeAllDatabase 需显式调用；closeAllDatabase 会在应用切换等时机遗留连接时统一释放
• iOS 端依赖系统 libsqlite3.tbd（已在 app-ios/config.json 声明），首次真机运行需在 Mac + Xcode 环境编译自定义基座
• iOS 端当前为未验证状态，详见文首「测试状态」
• 示例参考项目中的 pages/index/index.uvue，覆盖打开/关闭、建表/删表/清表、增删改查、批量增删改、批量造数与分页查询