更新记录

1.0.0（2026-07-21）

• 首发版本，统一 Promise API 与 interface.uts 公共契约。
• 支持 Android、iOS、Harmony、Web、mp-weixin 五端；App 端原生 SQLite，Web/小程序降级实现。
• 提供连接管理、SQL/事务、建表改表、增删改查、批量新增、混合 CRUD 批处理。
• 支持迁移、备份恢复（App）、JSON 导入导出、PRAGMA、结构检查、健康检查、诊断与能力查询。
• 写操作默认需 where/query 条件；全表更新/删除须显式传 allowAll: true。
• 兼容 table/values/where/orderBy/limit 等语义化参数；batch/batchCrud 支持同库并发保护。

平台兼容性

uni-app(4.87)

uni-app x(5.0)

xview-sqlite

xview-sqlite 是面向 uni-app 与 uni-app x 的五端本地数据库 UTS 插件。统一 Promise API，支持建表、增删改查、批量操作、事务、迁移、备份与 JSON 导入导出。

功能特性

• 连接管理：打开、关闭、路径查询、连接状态检查、全局连接清理
• SQL 能力：原始 SQL、查询 SQL、参数化 SQL、批处理、事务
• 结构化 CRUD：单条/批量新增、条件查询、更新、删除、混合 CRUD 批处理
• 表结构：建表、追加字段、字段差异检查、清表、删表、表存在检查
• 增强能力：版本迁移、备份恢复、JSON 导入导出、PRAGMA、结构检查、健康检查
• 诊断能力：平台能力矩阵、调用诊断日志

快速开始

1. 导入插件

将 uni_modules/xview-sqlite 放入项目，页面从插件根目录导入：

import { openDatabase, createTable, insertRow, selectRows } from '@/uni_modules/xview-sqlite'

2. 打开数据库并建表

await openDatabase({ name: 'xview_demo', path: 'xview_demo.db' })

await createTable({
    name: 'xview_demo',
    tableName: 'notes',
    fields: [
        { field: 'id', type: 'INTEGER PRIMARY KEY AUTOINCREMENT', primaryKey: true, autoIncrement: true },
        { field: 'title', type: 'TEXT', notNull: true }
    ]
})

3. 增删改查

// 新增
await insertRow({
    name: 'xview_demo',
    tableName: 'notes',
    data: { title: 'hello' }
})

// 查询
const res = await selectRows({
    name: 'xview_demo',
    tableName: 'notes',
    query: { title: 'hello' }
})

// 更新（需条件或 allowAll）
await updateRows({
    name: 'xview_demo',
    tableName: 'notes',
    update: { title: 'world' },
    query: { title: 'hello' }
})

// 删除（需条件或 allowAll）
await deleteRows({
    name: 'xview_demo',
    tableName: 'notes',
    query: { title: 'world' }
})

所有异步 API 返回 Promise<XviewSqliteResult>，通过 success、message、data 判断结果。

平台差异说明

App 端（Android / iOS / Harmony）

• 使用真实 SQLite 或官方关系型存储
• 支持 backupDatabase / restoreDatabase 文件级备份恢复
• iOS 备份/恢复使用 SQLite3 online backup API
• Harmony 的 path 仅取文件名，物理路径由系统管理；getDatabasePath 返回存储名称

Web / mp-weixin 降级端

• getCapabilities() 返回 nativeSqlite=false
• 不支持文件级 backupDatabase / restoreDatabase，请改用 exportDatabase / importDatabase
• Web 内部元数据表不出现在 listTables 结果中
• mp-weixin 存储 key 以数据库名开头，例如 xview_demo、xview_demo_table_notes

API 一览

返回值

type XviewSqliteResult = {
    success: boolean
    message: string
    data: any | null
}

连接管理

SQL

结构化 CRUD

参数别名：同时支持 tableName / table、data / values、query / where + whereParams、options / orderBy / groupBy / having / limit / offset。

写操作安全：updateRows、deleteRows、batchCrud 中的 update/delete 默认必须带 query 或 where；全表操作须显式传 allowAll: true。

批处理并发：batch、insertRows、batchCrud 对同一数据库名做并发保护，上一轮未完成时返回忙碌结果，避免嵌套事务。

表结构

增强与诊断

完整类型定义见 utssdk/interface.uts。

完整示例

import {
    openDatabase,
    isOpenDatabase,
    createTable,
    isTableExists,
    executePrepared,
    insertRows,
    selectRows,
    runMigrations,
    getCapabilities
} from '@/uni_modules/xview-sqlite'

await openDatabase({ name: 'xview_demo', path: 'xview_demo.db' })

await createTable({
    name: 'xview_demo',
    tableName: 'notes',
    fields: [
        { field: 'id', type: 'INTEGER PRIMARY KEY AUTOINCREMENT', primaryKey: true, autoIncrement: true },
        { field: 'title', type: 'TEXT', notNull: true }
    ]
})

await isOpenDatabase({ name: 'xview_demo' })
await isTableExists({ name: 'xview_demo', tableName: 'notes' })

await executePrepared({
    name: 'xview_demo',
    sql: 'INSERT INTO notes (title) VALUES (?)',
    params: ['hello']
})

await insertRows({
    name: 'xview_demo',
    tableName: 'notes',
    rows: [{ title: 'batch A' }, { title: 'batch B' }],
    useTransaction: true
})

const rows = await selectRows({
    name: 'xview_demo',
    table: 'notes',
    where: 'title LIKE ?',
    whereParams: ['batch%'],
    orderBy: 'id DESC',
    limit: 20
})

const capabilities = getCapabilities()

权限与隐私

• 默认不申请外部存储权限
• 数据保存在应用沙箱、IndexedDB 或微信小程序本地存储中
• 无广告、无第三方数据上报