更新记录

1.0.0（2026-06-16）

  • 完成 Android / iOS / HarmonyOS 三端 SQLite 能力适配
  • 插件接口统一升级为异步回调风格
  • 补齐三端原生异步执行封装
  • 支持 CRUD、分页、事务、批量执行、JSON 导入导出、数据库文件备份恢复
  • 重写插件说明文档，补充当前真实 API 使用方式
  • 优化 package.json 展示名、描述、关键词与插件市场搜索文案

平台兼容性

uni-app(4.33)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ - - - √ √ √ √ √
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
- - - - - - - - - - - -

uni-app x(4.34)

Chrome Safari Android iOS 鸿蒙 微信小程序
- - √ √ √ -

xtf-sqlite

xtf-sqlite 是一个面向 uni-app 与 uni-app x App 平台的 SQLite 多端数据库插件，基于 UTS 开发，支持 Android、iOS、HarmonyOS。

它的目标很明确：

  • 用一套 API 打通三端本地数据库
  • 让 uni-app 和 uni-app x 都能快速接入 SQLite
  • 覆盖从建库建表、增删改查，到事务、分页、批量执行、JSON 导入导出、数据库文件备份恢复的完整链路

一、插件适合什么场景

  • 离线缓存
  • 本地账单、聊天记录、草稿箱、收藏夹
  • 弱网业务数据持久化
  • 设备端临时业务库
  • SQL 调试工具、脚本初始化数据库

二、支持平台

  • Android
  • iOS
  • HarmonyOS

当前主要面向 App 端，不建议直接在 Web 或小程序端使用。

三、当前 API 风格

本插件当前所有数据库方法均使用异步回调风格：

method({
    ...业务参数,
    success(res) {
        console.log('success', res)
    },
    fail(err) {
        console.error('fail', err)
    },
    complete(res) {
        console.log('complete', res)
    }
})

常见回调约定：

  • success：成功结果
  • fail：插件错误对象
  • complete：无论成功失败都会触发

四、安装后导入

1. uni-app 写法

import {
    openDatabase,
    closeDatabase,
    executeSql,
    querySql,
    selectPage,
    createStringArg,
    createNumberArg
} from '@/uni_modules/xtf-sqlite'

2. uni-app x 写法

import {
    openDatabase,
    closeDatabase,
    executeSql,
    querySql,
    selectPage,
    createStringArg,
    createNumberArg
} from '@/uni_modules/xtf-sqlite'

大多数方法的调用结构一致，主要差异集中在 values、operations 等对象参数的推荐写法上。

五、uni-app 与 uni-app x 的主要区别

1. values 参数

用于 insert、update。

uni-app 推荐：

const values = {
    name: '张三',
    age: 18
}

uni-app x 推荐：

const values = new UTSJSONObject()
values.set('name', '张三')
values.set('age', 18)

2. operations 参数

用于 executeBatch。

uni-app 推荐：

const operations = [
    { type: 'execute', sql: "insert into users (name) values ('张三')" },
    { type: 'query', sql: 'select * from users' }
]

uni-app x 推荐：

const op1 = new UTSJSONObject()
op1.set('type', 'execute')
op1.set('sql', "insert into users (name) values ('张三')")

const op2 = new UTSJSONObject()
op2.set('type', 'query')
op2.set('sql', 'select * from users')

const operations = [op1, op2]

3. 参数绑定数组

绑定参数最终都使用 Array<UTSJSONObject>，因此推荐始终通过插件提供的辅助方法来构造：

  • createStringArg
  • createNumberArg
  • createDoubleArg
  • createBooleanArg
  • createNullArg
  • createBlobBase64Arg

这样在 uni-app 和 uni-app x 下都更稳定。

六、返回值结构说明

SQLiteStringResult

{ data: '...' }

常见于：

  • openDatabase
  • exportQueryJson
  • exportTableJson

SQLiteBooleanResult

{ data: true }

常见于：

  • closeDatabase
  • beginTransaction
  • commitTransaction
  • rollbackTransaction
  • inTransaction

SQLiteRecordsResult

{ data: [...] }

常见于：

  • querySql
  • querySqlArgs
  • selectRows
  • listTables
  • describeTable

SQLiteNumberResult

{ data: 10 }

常见于：

  • countRows

SQLiteExecuteResult

{
    success: true,
    sqlKind: 'insert',
    rowsAffected: 1,
    insertId: 1
}

常见于：

  • executeSql
  • executeSqlArgs
  • insert
  • update
  • deleteRows
  • dropTable
  • importJsonRows
  • exportDatabaseFile
  • importDatabaseFile

SQLiteRawResult

{
    success: true,
    mode: 'query',
    sqlKind: 'select',
    rowsAffected: 0,
    insertId: -1,
    count: 2,
    message: 'query completed',
    records: []
}

常见于：

  • runSql
  • runSqlArgs

SQLitePageResult

{
    total: 100,
    page: 1,
    pageSize: 10,
    records: []
}

常见于：

  • selectPage

SQLiteBatchResult

{
    success: true,
    failedIndex: -1,
    rowsAffectedTotal: 3,
    errorMessage: '',
    results: []
}

常见于：

  • runSqlScript
  • executeBatch

七、参数辅助方法

这一组方法专门用来生成 SQL 绑定参数对象，建议统一使用。

createStringArg(value)

作用：创建字符串类型参数。

适用场景：姓名、标题、备注、文本条件查询。

const arg = createStringArg('张三')

createNumberArg(value)

作用：创建整数或普通数字参数。

适用场景：id、age、数量、状态码。

const arg = createNumberArg(18)

createDoubleArg(value)

作用：创建浮点参数。

适用场景：金额、经纬度、小数统计值。

const arg = createDoubleArg(19.99)

createBooleanArg(value)

作用：创建布尔参数。

适用场景：是否启用、是否完成、开关类字段。

const arg = createBooleanArg(true)

createNullArg()

作用：创建空值参数。

适用场景：需要显式插入 null 或更新为 null。

const arg = createNullArg()

createBlobBase64Arg(value)

作用：创建 Base64 二进制参数。

适用场景：图片缩略图、文件字节流、二进制缓存。

const arg = createBlobBase64Arg('AAECAwQ=')

八、每个方法的详细说明

1. openDatabase(options)

作用：打开数据库，返回连接 ID。后续所有数据库操作都需要这个 connectionId。

参数：

  • name：数据库文件名，例如 demo.db
  • directory：数据库目录，传空字符串时使用默认目录
  • readOnly：是否只读打开

成功回调：

  • res.data：数据库连接 ID，通常也是数据库路径

uni-app：

openDatabase({
    name: 'demo.db',
    directory: '',
    readOnly: false,
    success(res) {
        console.log(res.data)
    }
})

uni-app x：

openDatabase({
    name: 'demo.db',
    directory: '',
    readOnly: false,
    success(res) {
        console.log(res.data)
    }
})

2. closeDatabase(options)

作用：关闭数据库连接。

参数：

  • connectionId：要关闭的连接 ID

成功回调：

  • res.data：true 或 false

3. executeSql(options)

作用：执行不带参数的 SQL。

适合：

  • 建表
  • 删表
  • 无参更新
  • 无参删除

参数：

  • connectionId
  • sql

4. executeSqlArgs(options)

作用：执行带参数的 SQL。

适合：

  • 参数化插入
  • 参数化更新
  • 参数化删除

参数：

  • connectionId
  • sql
  • bindArgs

uni-app / uni-app x 共通示例：

executeSqlArgs({
    connectionId,
    sql: 'insert into users (name, age) values (?, ?)',
    bindArgs: [createStringArg('张三'), createNumberArg(18)],
    success(res) {
        console.log(res)
    }
})

5. querySql(options)

作用：执行不带参数的查询 SQL。

返回：

  • res.data：查询结果数组

6. querySqlArgs(options)

作用：执行带参数的查询 SQL。

适合：

  • 条件查询
  • 参数化筛选
  • 复杂查询组合

7. runSql(options)

作用：统一执行单条 SQL，由插件根据 mode 决定走“执行”还是“查询”。

参数：

  • connectionId
  • sql
  • mode

mode 支持：

  • auto
  • execute
  • query

返回：

  • SQLiteRawResult

8. runSqlArgs(options)

作用：统一执行带参数的单条 SQL。

适合：

  • 调试台执行参数化 SQL
  • 不确定是查询还是执行时统一走一个入口

9. runSqlScript(options)

作用：执行多条 SQL 脚本。

适合：

  • 初始化数据库
  • 迁移脚本
  • 批量建表或批量插入脚本

参数：

  • connectionId
  • script
  • useTransaction
  • stopOnError

10. insert(options)

作用：向指定表插入一行数据。

参数：

  • connectionId
  • table
  • values

uni-app：

insert({
    connectionId,
    table: 'users',
    values: {
        name: '张三',
        age: 18
    },
    success(res) {
        console.log(res)
    }
})

uni-app x：

const values = new UTSJSONObject()
values.set('name', '张三')
values.set('age', 18)

insert({
    connectionId,
    table: 'users',
    values,
    success(res) {
        console.log(res)
    }
})

11. update(options)

作用：按条件更新数据。

参数：

  • connectionId
  • table
  • values
  • whereClause
  • whereArgs

uni-app：

update({
    connectionId,
    table: 'users',
    values: { age: 20 },
    whereClause: 'name = ?',
    whereArgs: ['张三'],
    success(res) {
        console.log(res)
    }
})

uni-app x：

const values = new UTSJSONObject()
values.set('age', 20)

update({
    connectionId,
    table: 'users',
    values,
    whereClause: 'name = ?',
    whereArgs: ['张三'],
    success(res) {
        console.log(res)
    }
})

12. deleteRows(options)

作用：按条件删除数据。

参数：

  • connectionId
  • table
  • whereClause
  • whereArgs

13. selectRows(options)

作用：按表名方式查询数据。

适合：

  • 普通列表页
  • 简单筛选页
  • 不想自己拼完整 SQL 时

参数：

  • connectionId
  • table
  • columns
  • whereClause
  • whereArgs
  • groupBy
  • having
  • orderBy
  • limit

14. countRows(options)

作用：统计符合条件的数据总数。

适合：

  • 列表页总数统计
  • 分页总条数
  • 业务汇总数量

15. selectPage(options)

作用：按页查询数据，返回总数与记录列表。

适合：

  • 分页列表
  • 首屏列表加载
  • 本地数据翻页

16. beginTransaction(options)

作用：开启事务。

17. commitTransaction(options)

作用：提交事务。

18. rollbackTransaction(options)

作用：回滚事务。

19. inTransaction(options)

作用：判断当前连接是否处于事务中。

20. executeBatch(options)

作用：批量执行多条操作。

参数：

  • connectionId
  • operations
  • useTransaction
  • stopOnError

支持的 type：

  • execute
  • insert
  • update
  • delete
  • query
  • select
  • count
  • page

21. exportQueryJson(options)

作用：把任意查询结果导出为 JSON 字符串。

22. exportTableJson(options)

作用：按表导出 JSON 字符串。

23. importJsonRows(options)

作用：把 JSON 数据导入到指定表。

参数：

  • connectionId
  • table
  • jsonText
  • replaceExisting

24. exportDatabaseFile(options)

作用：把数据库文件导出到目标路径。

适合：

  • 用户备份
  • 开发调试导库
  • 本地数据库迁移

25. importDatabaseFile(options)

作用：从指定路径导入数据库文件并替换当前数据库。

26. listTables(options)

作用：列出数据库中的表和视图。

27. describeTable(options)

作用：查看指定表的字段结构。

28. dropTable(options)

作用：删除指定表。

九、简单完整示例

uni-app 示例

openDatabase({
    name: 'demo.db',
    directory: '',
    readOnly: false,
    success(res) {
        const connectionId = res.data
        executeSql({
            connectionId,
            sql: 'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, age INTEGER NOT NULL)',
            success() {
                insert({
                    connectionId,
                    table: 'users',
                    values: { name: '张三', age: 18 },
                    success() {
                        querySql({
                            connectionId,
                            sql: 'select * from users order by id desc',
                            success(queryRes) {
                                console.log(queryRes.data)
                            }
                        })
                    }
                })
            }
        })
    }
})

uni-app x 示例

openDatabase({
    name: 'demo.db',
    directory: '',
    readOnly: false,
    success(res) {
        const connectionId = res.data
        executeSql({
            connectionId,
            sql: 'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, age INTEGER NOT NULL)',
            success() {
                const values = new UTSJSONObject()
                values.set('name', '张三')
                values.set('age', 18)
                insert({
                    connectionId,
                    table: 'users',
                    values,
                    success() {
                        querySql({
                            connectionId,
                            sql: 'select * from users order by id desc',
                            success(queryRes) {
                                console.log(queryRes.data)
                            }
                        })
                    }
                })
            }
        })
    }
})

十、使用建议

  • 普通列表页优先用 selectRows、selectPage、countRows
  • 调试台、复杂 SQL 优先用 runSql / runSqlArgs
  • 数据库初始化和迁移优先用 runSqlScript
  • 多步写入优先结合事务或 executeBatch
  • 建议优先使用参数化 SQL，避免手写字符串拼接

十一、注意事项

  • 插件当前重点支持 App 端
  • 不同平台对部分复杂 SQL 的支持细节可能存在差异，建议上线前在目标端充分验证
  • 如果业务主动开启了 WAL 模式，数据库文件导入导出时建议同步处理 -wal 与 -shm 文件
  • 示例页面里为了方便演示，部分调用会做 Promise 二次封装；业务项目中可按团队习惯继续封装

十二、总结

如果你正在找这些能力：

  • uni-app sqlite
  • uni-app x sqlite
  • uts sqlite
  • HarmonyOS sqlite
  • 本地数据库插件
  • 离线数据库插件

那么 xtf-sqlite 就是为这类需求准备的多端 SQLite 插件。

隐私、权限声明

1. 本插件需要申请的系统权限列表：

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

无

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

评论列表 撰写评论 向官方投诉

暂无用户评论。