TuiSqlite

数据库工具 — 提供 SQLite 数据库的创建、建表、增删改查与持久化能力。

介绍

TuiSqlite 是 uni-app x 环境下的 SQLite 数据库封装，支持应用的本地数据库管理。适用于离线数据存储、本地缓存、配置持久化等场景。

导入

import { TuiSqlite } from '@/uni_modules/tui-sqlite'
import type { SQLiteResult } from '@/uni_modules/tui-sqlite'

基础用法

// 初始化数据库实例
const db = new TuiSqlite({
  defaultDirectory: uni.env.USER_DATA_PATH + '/db/sq'
})

// 创建数据库
db.createDb('myDb')

// 创建表
db.createTable('users', {
  id: 'INTEGER PRIMARY KEY AUTOINCREMENT',
  name: 'TEXT',
  age: 'INTEGER',
  updated_at: 'TEXT'
})

// 新增
db.insert('users', { name: '张三', age: 25, updated_at: `${Date.now()}` })

// 查询
const result = db.query('SELECT id, name, age FROM users ORDER BY id ASC')

// 修改
db.update('users', { name: '李四', age: 30 }, 'id = ?', [1])

// 删除
db.delete('users', 'id = ?', [1])

// 关闭
db.close()

API

构造函数

new TuiSqlite({ defaultDirectory: string })

参数	说明	类型
defaultDirectory	数据库文件存储目录	String

实例方法

createDb

createDb(dbName: string): boolean | Promise<boolean>

创建或打开一个数据库。Android/iOS 为同步方法，Harmony 为异步方法。

createTable

createTable(tableName: string, schema: object): SQLiteResult

创建数据表。

参数	说明	类型
tableName	表名	String
schema	字段定义，key 为字段名，value 为类型描述	Object

insert

insert(tableName: string, data: object): SQLiteResult

插入一条记录。

参数	说明	类型
tableName	表名	String
data	插入的数据，key 为字段名	Object

update

update(tableName: string, data: object, whereClause: string, whereParams: any[]): SQLiteResult

更新符合条件的记录。

参数	说明	类型
tableName	表名	String
data	更新的数据	Object
whereClause	WHERE 条件语句（含占位符 ?）	String
whereParams	占位符参数数组	any[]

delete

delete(tableName: string, whereClause: string, whereParams: any[]): SQLiteResult

删除符合条件的记录。

参数	说明	类型
tableName	表名	String
whereClause	WHERE 条件语句	String
whereParams	占位符参数数组	any[]

query

query(sql: string): SQLiteResult

执行查询语句。

参数	说明	类型
sql	SQL 查询语句	String

saveLocal

saveLocal(backupName: string): SQLiteResult | Promise<SQLiteResult>

将数据库保存为备份文件。Android/iOS 同步，Harmony 异步。

loadLocal

loadLocal(backupName: string): SQLiteResult | Promise<SQLiteResult>

从备份文件加载恢复数据库。Android/iOS 同步，Harmony 异步。

close

close(): void

关闭数据库连接。

SQLiteResult

属性名	说明	类型
columns	列名数组	String[]
rows	数据行，按列顺序排列	any[][]
error	错误信息，无错误时为 null	String | null

完整示例

参考 demo：demo/sqlite/sqlite.uvue

const DB_DIRECTORY = uni.env.USER_DATA_PATH + '/db/sq'
const db = new TuiSqlite({ defaultDirectory: DB_DIRECTORY })

// 创建数据库
db.createDb('sqliteDb')

// 创建表
db.createTable('users', {
  id: 'INTEGER PRIMARY KEY AUTOINCREMENT',
  name: 'TEXT',
  age: 'INTEGER',
  updated_at: 'TEXT'
})

// 新增
db.insert('users', { name: '演示用户1', age: 25, updated_at: `${Date.now()}` })

// 查询全部
const result = db.query('SELECT id, name, age, updated_at FROM users ORDER BY id ASC')

// 处理查询结果
const columnsList = result.columns as string[]
const rows = result.rows as any[][]
rows.forEach(row => {
  const item: UTSJSONObject = {}
  for (let i = 0; i < columnsList.length; i++) {
    item[columnsList[i]] = i < row.length ? row[i] : null
  }
  console.log(item)
})

// 关闭数据库
db.close()

注意事项

• 仅支持 App 端（#ifdef APP）
• Android/iOS 使用同步方法，Harmony 使用异步方法（await）
• 建议在页面 onBeforeUnmount 时调用 close() 关闭数据库
• 数据库文件默认存储在应用沙盒目录