@cordova-ohos/cordova-sqlite-storage
v7.0.1
Published
Cordova SQLite Storage Plugin
Readme
cordova-sqlite-storage
本项目基于 [email protected] 开发,本文档重点阐述其在 OpenHarmony(OHOS)系统中的具体应用。
简介
cordova-sqlite-storage 是一款专为 Cordova/PhoneGap 应用设计的轻量高效 SQLite 数据库插件,基于原生 SQLite 引擎封装,提供简洁易用的 API 接口,支持跨平台数据存储、事务管理、批量操作等核心能力,是混合移动应用本地数据持久化的理想解决方案,广泛适用于离线数据缓存、本地业务数据管理、日志存储等场景。本文档仅介绍该插件在 OHOS 系统中的应用、安装、配置、使用方法及注意事项,帮助开发者快速集成本地数据库功能,重点突出 OHOS 平台的特性与使用规范。
功能特性
全平台兼容:完美支持 Android、iOS、OHOS 三大主流移动平台,适配各系统最新版本特性,重点适配 OHOS 5.0+ 系统,遵循 OHOS 系统原生规范
原生性能加持:基于系统原生 SQLite 引擎开发,避免 JS 模拟数据库的性能损耗,操作响应迅速,读写效率高,适配 OHOS 系统性能优化要求
完整事务支持:支持显式事务(BEGIN/COMMIT/ROLLBACK)和隐式事务,确保数据操作的原子性和一致性,有效避免数据错乱
批量操作优化:提供批量执行 SQL 接口,大幅提升大批量数据插入、更新效率,减少 IO 开销,适配 OHOS 系统 IO 操作规范
版本迁移支持:内置数据库版本管理机制,通过升级回调实现平滑的表结构变更和数据迁移,无需手动处理旧版本数据兼容问题
灵活存储位置:支持配置数据库存储路径,适配 Android 分区存储和 iOS、OHOS 沙盒机制,可根据业务需求选择存储位置,符合 OHOS 系统沙箱安全规范
丰富错误反馈:提供详细的错误代码和描述信息,便于开发者快速定位和调试问题,降低集成难度
内存数据库支持:支持创建纯内存数据库,适用于临时数据处理场景,应用退出后数据自动清除,节省 OHOS 系统存储资源
OHOS 平台特性
该插件在 OHOS 平台的实现贴合系统原生存储规范,核心特性及特殊限制如下,需重点关注:
适配 OHOS 沙箱机制:数据库文件默认存储在应用沙箱路径下,无法访问沙箱外文件,确保系统数据安全
版本兼容性:适配 OHOS 5.0+ 系统,支持 DevEco Studio 5.0+ 开发环境,SDK 需为 API12+,确保插件功能稳定运行
事务稳定性:针对 OHOS 系统异步操作机制优化事务处理,避免因系统调度导致的事务异常,确保数据一致性
内存优化:适配 OHOS 系统内存管理机制,关闭数据库后自动释放资源,减少内存占用,提升应用运行稳定性
支持平台
OHOS(5.0+,适配系统沙箱机制,支持数据库创建、事务、批量操作,兼容 DevEco Studio 5.0+)
Android(适配主流版本,支持全量功能,适配分区存储,无特殊权限限制)
iOS(适配主流版本,支持全量功能,遵循 iOS 沙盒机制,无需额外权限配置)
前置准备
在集成插件前,需确保开发环境满足基础要求,完成必要的前置配置,具体步骤如下:
已安装 Node.js(v14.0.0 及以上)和 npm(v6.0.0 及以上),可通过
node -v和npm -v命令验证版本;已全局安装 HCordova CLI(v10.0.0 及以上),用于插件的安装、卸载和管理;
已创建 Cordova 项目(若尚未创建,可通过
cordova create sqliteApp com.example.sqliteapp SQLiteApp命令快速创建);确保项目适配 OHOS 5.0 及以上版本,DevEco Studio 版本为 5.0+,SDK 为 API12+,避免因版本过低导致插件功能异常;
熟悉 OHOS 系统沙箱路径规范,了解 Cordova 插件在 OHOS 平台的文件访问方式。
下载安装
通过 HCordova CLI 即可快速安装插件,支持全平台安装或指定 OHOS 平台安装,安装流程简洁高效,安装后可通过命令验证安装结果。
前提条件
安装插件前,需先安装 HCordova CLI,执行以下命令安装:
npm install -g hcordova基础安装(推荐,从 npm 仓库)
在 Cordova 项目根目录执行以下命令,插件会自动处理各平台依赖与基础配置,默认安装最新稳定版本,指定 OHOS 平台安装:
# 全平台安装
hcordova plugin add cordova-sqlite-storage
# 安装最新稳定版(仅 OHOS 平台)
hcordova plugin add cordova-sqlite-storage --platform ohos
# 安装指定版本(示例:1.0.0 版本,仅 OHOS 平台)
hcordova plugin add [email protected] --platform ohos从 GitCode 安装开发版
若需使用开发中的最新功能,可直接从 GitCode 仓库安装,仅适配 OHOS 平台(修正命令拼写错误):
# 无加密开发版
hcordova plugin add https://gitcode.com/CPF-Cordova/Cordova-sqlite-storage.git --platform ohos
# 指定标签/分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/Cordova-sqlite-storage.git@develop --platform ohos离线安装(本地包)
适用于无网络环境,先下载插件包到本地,再执行离线安装:
# 下载插件包到本地(示例路径:../Downloads/cordova-sqlite-storage)
# 执行离线安装
hcordova plugin add ../Downloads/cordova-sqlite-storage --platform ohos安装后验证
安装完成后,可通过以下命令验证插件是否成功添加到项目中:
# 查看已安装的插件列表,若包含本插件 ID 则表示插件已成功安装
hcordova plugin list卸载插件
如需移除插件,执行以下命令即可清理相关配置与依赖,支持全平台卸载或指定 OHOS 平台卸载:
# 全平台卸载数据库插件
hcordova plugin remove cordova-sqlite-storage
# 指定 OHOS 平台卸载
hcordova plugin remove cordova-sqlite-storage --platform ohos约束与限制
依赖插件:无强制依赖,@cordova-ohos/ohos 版本为 2.0.0 及以上;
平台限制:OHOS 平台仅支持 5.0 及以上版本,低于该版本的系统可能出现数据库创建失败、API 调用异常等问题;
路径限制:仅支持 OHOS 系统沙箱路径,无法访问沙箱外的文件;
API 调用时机:所有 JavaScript API 必须在
deviceready事件触发后调用,否则会出现window.sqlitePlugin对象未定义、调用失败等异常;数据库连接限制:建议应用全局维护一个数据库实例,避免频繁创建和关闭连接,否则会导致性能损耗和连接异常;
兼容性
支持:
| 项目 | 版本/信息 | |-----|--------| | SDK | API12+ | | IDE | DevEco Studio: 5.0+ | | ROM | 5.1+ | | Emulator | OpenHarmony 6.0+ |
在以下版本中已测试通过:
| 项目 | 版本/信息 | |-----|--------| | @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 | | SDK | 5.0.0(12) | | IDE | DevEco Studio: 6.0.13.200 | | ROM | 5.1.0.120 SP3 | | Emulator | OpenHarmony 6.0.1(21) |
使用示例
插件通过全局对象 window.sqlitePlugin 暴露所有核心 API,所有操作均为异步执行,通过回调函数处理结果。所有 API 需在 deviceready 事件触发后调用。以下为 OHOS 平台核心功能的完整使用示例,可直接复制到项目中使用。
1. 打开/创建数据库(核心操作)
打开已存在的数据库,若不存在则创建新数据库,全局维护一个数据库实例,避免频繁创建连接:
// 等待 Cordova 环境就绪
document.addEventListener('deviceready', function() {
/**
* 打开/创建数据库
* @param {Object} options - 数据库配置选项
* @param {Function} successCallback - 成功回调(参数:db 数据库实例)
* @param {Function} errorCallback - 错误回调(参数:error 错误对象)
*/
const global_db = window.sqlitePlugin.openDatabase({
name: 'tonge.db', // 数据库名称
location: 'default' // 默认存储位置
}, function(db) {
console.log("数据库打开/创建成功");
// 数据库实例全局可用
window.global_db = db;
}, function(error) {
console.error("数据库打开/创建失败:", error);
alert("数据库初始化失败");
});
}, false);2. 事务操作(批量执行 SQL)
开启显式事务,批量执行表创建、数据插入等操作,确保原子性,适用于初始化数据库表结构:
// 等待 Cordova 环境就绪
document.addEventListener('deviceready', function() {
// 先打开数据库
var global_db = window.sqlitePlugin.openDatabase({name: 'tonge.db', location: 'default'});
/**
* 执行事务
* @param {Function} transactionCallback - 事务回调(参数:tx 事务对象)
* @param {Function} errorCallback - 事务失败回调(参数:error 错误对象)
* @param {Function} successCallback - 事务成功回调(无参数)
*/
global_db.transaction(function(tx) {
// 批量创建表结构
tx.executeSql('CREATE TABLE IF NOT EXISTS TONGE_CONFIG_SYS(ID INTEGER PRIMARY KEY AUTOINCREMENT, CONF_KEY VARCHAR(64), CONF_VALUE VARCHAR(512))');
tx.executeSql('CREATE TABLE IF NOT EXISTS TONGE_SYS_CONST(ID INTEGER PRIMARY KEY AUTOINCREMENT, CONF_KEY VARCHAR(64), CONF_VALUE VARCHAR(4096))');
tx.executeSql('CREATE TABLE IF NOT EXISTS TONGE_MEM_ACCOUNT(ID INTEGER PRIMARY KEY AUTOINCREMENT, MEM_ACCOUNT VARCHAR(64), MEM_NAME VARCHAR(128), MEM_PASSWORD VARCHAR(128))');
}, function(error){
// 事务执行失败,自动回滚
console.error("事务执行失败:", error);
alert("数据库初始化失败"+error);
}, function(){
// 事务执行成功,所有操作提交
console.log("数据库表结构创建成功");
});
}, false);3. 执行 SQL 语句(增删改查)
通过 executeSql 方法执行查询、插入、更新、删除等 SQL 操作,以下为常用场景示例:
// 等待 Cordova 环境就绪
document.addEventListener('deviceready', function() {
// 全局数据库实例
var global_db = window.sqlitePlugin.openDatabase({name: 'tonge.db', location: 'default'});
// 1. 插入/更新数据(示例:更新系统常量,不存在则插入)
function updateConst(confKey, confVale, callBack) {
global_db.transaction(function(tx) {
tx.executeSql("update TONGE_SYS_CONST set CONF_VALUE=? where CONF_KEY=?", [confVale, confKey], function(tx, result){
if(result.rowsAffected == 0) {
// 无匹配数据,执行插入
tx.executeSql("insert into TONGE_SYS_CONST(CONF_KEY, CONF_VALUE) values(?, ?)", [confKey, confVale], function(tx, result) {
console.log("插入系统常量成功:", confKey);
});
} else {
console.log("更新系统常量成功:", confKey);
}
});
}, function(error){
console.error("updateConst 失败:", error);
},function(){
console.log("updateConst 执行完成:"+confKey);
callBack && callBack();
});
}
// 2. 查询数据(示例:查询会员账号信息)
function getMemAccount(memAccount, getMemAccountSuccess) {
var rows = null;
// 读事务(仅执行查询操作,性能更优)
global_db.readTransaction(function(tx) {
tx.executeSql("select * from TONGE_MEM_ACCOUNT where MEM_ACCOUNT=?", [memAccount], function(tx, result) {
rows = result.rows; // 结果集
});
}, function(error){
console.error("getMemAccount 失败:", error);
},function(){
if(rows.length != 0) {
// 获取指定索引的记录
getMemAccountSuccess && getMemAccountSuccess(rows.item(0));
} else {
console.log("没有获取到登录会员的数据");
}
});
}
// 3. 删除/插入数据(示例:插入企业用户,先删除旧数据)
function insertCorpUser(user, callBack) {
global_db.transaction(function(tx) {
tx.executeSql("delete from TONGE_CORP_USER where USER_NAME=?", [user.userName], function(tx, result) {
// 删除后执行插入
tx.executeSql("insert into TONGE_CORP_USER(USER_NAME, PASSWD, CORP_ID,CORP_NAME,SHOP_ID,SHOP_NAME,MEM_SERVER_ID,SMS_SERVER_ID,CORP_SERVER_ID,USER_TYPE,USER_AUTHORITY1,USER_AUTHORITY2,FUNCTION_ID,CARD_KIND,SELF_OPTION,FUNCTION_OPTION,FUNCTION_OPTION2,DISCOUNT,SHOP_SELF_OPTION,FIELDS_MUST,STAFF_ID, SYS_VERSION, LAST_DT, PIC_URL, FUNCTION_ROLE,START_DT) values(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",[user.userName, user.passwd, user.corpId, user.corpName, user.shopId, user.shopName, user.memServerId, user.smsServerId, user.corpServerId, user.userType, user.userAuthority1, user.userAuthority2, user.functionId, user.cardKind, user.selfOption, user.functionOption, user.functionOption2, user.discount, user.shopSelfOption, user.fieldsMust, user.staffId, user.sysVersion, user.lastDt, user.picUrl,user.functionRole,user.startDt], function(tx, result){
if(result.rowsAffected != 1) {
console.log("insertCorpUser 失败,影响行数"+result.rowsAffected);
}
});
});
}, function(error){
console.error("insertCorpUser 失败:", error);
},function(){
console.log("insertCorpUser 成功");
callBack && callBack();
});
}
// 调用示例
updateConst("system_version", "1.0.0", function() {
console.log("系统版本更新完成");
});
getMemAccount("test123", function(userInfo) {
console.log("查询到会员信息:", userInfo);
});
}, false);4. 关闭与删除数据库
关闭数据库连接释放资源,删除数据库文件(需先关闭连接),适用于应用退出或数据清理场景:
// 等待 Cordova 环境就绪
document.addEventListener('deviceready', function() {
// 全局数据库实例
var global_db = window.sqlitePlugin.openDatabase({name: 'tonge.db', location: 'default'});
// 1. 关闭数据库
function closeDatabase(callback) {
global_db.close(function() {
console.log("数据库关闭成功,资源已释放");
if (callback) {
callback();
}
}, function(error) {
console.error("数据库关闭失败:", error);
});
}
// 2. 删除数据库(需先关闭数据库连接)
function deleteDatabase() {
// 先关闭连接
closeDatabase(function() {
sqlitePlugin.deleteDatabase("tonge.db", function() {
console.log("数据库删除成功");
}, function(error) {
console.error("数据库删除失败:", error);
})
);
}
// 应用退出前调用关闭数据库
window.addEventListener('beforeunload', function() {
closeDatabase();
});
// 调用删除数据库(谨慎使用,会删除所有数据)
// deleteDatabase();
}, false);5. 数据库版本迁移
当数据库版本号提升时,触发 upgrade 回调,执行表结构修改、数据迁移操作,确保旧版本数据兼容:
// 等待 Cordova 环境就绪
document.addEventListener('deviceready', function() {
const global_db = window.sqlitePlugin.openDatabase({
name: 'tonge.db',
location: 'default',
version: '2.0' // 版本号从 1.0 提升到 2.0,触发 upgrade 回调
}, function(db) {
console.log("数据库打开成功(版本 2.0)");
}, function(error) {
console.error("数据库打开失败:", error);
}, function(db, oldVersion, newVersion, tx) {
// 版本迁移回调(oldVersion:旧版本号,newVersion:新版本号)
console.log("数据库版本迁移:", oldVersion, "->", newVersion);
if(oldVersion < 2) {
// 从 1.0 版本迁移到 2.0 版本,添加新字段
tx.executeSql("ALTER TABLE TONGE_SYS_CONST ADD COLUMN UPDATE_TIME DATETIME DEFAULT CURRENT_TIMESTAMP");
console.log("版本迁移完成,添加 UPDATE_TIME 字段");
}
});
}, false);使用说明
以下为插件使用的核心说明,包括 API 详解、参数说明、常见问题及注意事项等,帮助开发者快速上手并避免异常,重点突出 OHOS 平台特性与限制。
1. 核心 API 说明
插件所有方法均挂载在全局 window.sqlitePlugin 对象下,无需额外引入,所有操作均为异步执行,通过回调函数处理结果。所有 API 均需在 deviceready 事件触发后调用。
1.1 打开/创建数据库(核心 API)
功能:打开已存在的数据库,若不存在则创建新数据库,返回数据库实例,是所有数据库操作的基础。
语法:
sqlitePlugin.openDatabase(options, successCallback, errorCallback);参数说明:
options:配置参数对象,必填,包含以下属性:
name:数据库名称,必填,字符串类型;
location:存储位置,可选,默认 "default";
successCallback:成功回调,参数为 db(数据库实例),触发即表示数据库打开/创建成功;
errorCallback:失败回调,参数为 error(错误对象),包含错误代码和描述;
1.2 事务操作(核心 API)
功能:开启显式事务,批量执行 SQL 操作,确保原子性,要么全部成功,要么全部回滚。
语法(写事务,支持增删改查):
db.transaction(transactionCallback, errorCallback, successCallback);语法(读事务,仅支持查询,性能更优):
db.readTransaction(transactionCallback, errorCallback, successCallback);参数说明:
transactionCallback:事务回调,必填,参数为 tx(事务对象),用于执行 SQL 操作;
errorCallback:事务失败回调,可选,参数为 error(错误对象),事务执行过程中出现错误时触发,自动回滚;
successCallback:事务成功回调,可选,无参数,所有 SQL 操作执行完成且无错误时触发,自动提交。
1.3 执行 SQL 语句(核心 API)
功能:通过事务对象执行 SQL 语句,支持查询、插入、更新、删除等所有 SQL 操作。
语法:
tx.executeSql(sql, params, successCallback, errorCallback);参数说明:
sql:SQL 语句,必填,字符串类型,支持所有标准 SQLite SQL 语句;
params:SQL 参数数组,可选,用于替换 SQL 语句中的占位符(?),避免 SQL 注入;
successCallback:成功回调,可选,参数为 (tx, result),result 为结果集对象;
errorCallback:失败回调,可选,参数为 error(错误对象),SQL 执行失败时触发。
结果集(result)属性说明:
rows.length:查询结果的记录总数;
rows.item(index):获取指定索引(index)的记录,返回对象;
rowsAffected:增删改操作影响的行数。
1.4 关闭数据库
功能:关闭数据库连接,释放系统资源,建议在应用退出前执行。
语法:
db.close(successCallback, errorCallback);参数说明:
successCallback:成功回调,可选,无参数,数据库关闭成功时触发;
errorCallback:失败回调,可选,参数为 error(错误对象),关闭失败时触发。
1.5 删除数据库
功能:删除指定名称的数据库文件,需先关闭数据库连接,否则会删除失败。
语法:
sqlitePlugin.deleteDatabase(dbName, successCallback, errorCallback);参数说明:
dbName:数据库名称,必填,字符串类型,与创建时的 name 一致;
successCallback:成功回调,可选,无参数,数据库删除成功时触发;
errorCallback:失败回调,可选,参数为 error(错误对象),删除失败时触发。
2. 常见问题(FAQ)
Q1: 调用 openDatabase 后数据库创建失败怎么办?
检查版本兼容性:确保 OHOS 系统版本为 5.0+,DevEco Studio 版本为 5.0+,SDK 为 API12+;
检查插件安装:执行
hcordova plugin list确认插件已成功安装,若未安装则重新执行安装命令;检查数据库名称:数据库名称避免包含特殊字符,建议使用字母、数字和下划线组合。
Q2: 执行 SQL 语句时提示“table not found”(表不存在)怎么办?
检查表创建语句:确认 CREATE TABLE 语句语法正确,是否添加 IF NOT EXISTS 关键字(避免重复创建);
检查事务执行:确保表创建语句在事务中执行,且事务已成功提交;
检查数据库实例:确保使用正确的数据库实例执行 SQL 语句,避免实例未初始化或已关闭;
检查版本迁移:若数据库版本提升,确认版本迁移回调中已正确创建或修改表结构。
Q3: 事务执行失败后,数据没有回滚怎么办?
插件默认支持事务回滚,若未回滚,需检查以下几点:
确认使用显式事务:单条 SQL 操作默认隐式事务,执行失败会自动回滚;显式事务需确保在 errorCallback 中未手动提交;
检查错误触发时机:确保事务中的 SQL 语句执行失败时,触发了 errorCallback,此时会自动回滚;
检查数据库连接:避免事务执行过程中关闭数据库连接,否则会导致事务异常,无法正常回滚。
Q4: 大批量数据插入/更新效率低怎么办?
可通过以下方式优化大批量数据操作效率:
使用显式事务:将所有批量操作放在一个事务中执行,减少 IO 开销;
使用参数化 SQL:通过 params 数组传递参数,避免拼接 SQL 语句,提升执行速度;
减少回调嵌套:避免在每次 SQL 执行后触发回调,批量执行完成后统一处理结果;
优化数据量:若数据量极大,可分批次执行,避免单次操作占用过多系统资源。
Q5: 应用退出后,数据库数据丢失怎么办?
检查事务提交:确保所有增删改操作已通过事务提交,未提交的事务会导致数据未持久化;
检查数据库关闭:应用退出前,确保已调用 close 方法关闭数据库,避免数据写入未完成。
3. 注意事项
API 调用时机:所有 JavaScript API 必须在
deviceready事件触发后调用,否则会出现window.sqlitePlugin对象未定义、调用失败等异常。数据库连接:建议应用全局维护一个数据库实例,避免频繁创建和关闭连接,否则会导致性能损耗和连接异常;应用退出前务必关闭数据库,释放资源。
事务使用:大批量数据操作建议使用显式事务,确保原子性,同时提升执行效率;读操作建议使用 readTransaction,优化性能。
SQL 语法:遵循 SQLite 标准 SQL 语法,避免使用平台专属 SQL 语句,确保跨平台兼容性;避免 SQL 注入,优先使用参数化 SQL。
版本迁移:数据库版本号只能提升,不能降低;版本迁移回调中仅执行表结构修改、数据迁移操作,避免执行复杂业务逻辑。
数据安全:敏感数据建议配置数据库加密,妥善保管加密密码;避免存储过多大型数据(如图片、视频),建议仅存储文件路径,文件单独存储。
错误处理:建议为所有 API 调用添加错误回调,便于捕获异常,根据错误信息快速定位问题,提升应用稳定性。
目录结构
cordova-sqlite-storage # [根目录] SQLite 本地存储插件项目根目录
├── src # [源码目录] 存放原生平台代码
│ └── main # [主目录] 主代码目录
│ └── cpp # [C++ 目录] C++ 原生代码目录
│ └── sqlc # [C++ 模块] SQLite C++ 封装模块文件夹
│ ├── sqlite3.c # [C 源文件] SQLite 核心库的 C 语言实现
│ ├── sqlite3.h # [C 头文件] SQLite 核心库的头文件
│ ├── SQLiteConnectorDatabase.cpp # [C++ 实现] 数据库连接器实现,处理数据库连接逻辑
│ ├── SQLiteConnectorDatabase.h # [C++ 声明] 数据库连接器头文件
│ ├── SQLiteHarmonyDatabase.cpp # [C++ 实现] 针对 OHOS 系统的数据库适配实现
│ ├── SQLiteHarmonyDatabase.h # [C++ 声明] 针对 OHOS 系统的数据库适配头文件
│ ├── SQLitePlugin.cpp # [C++ 实现] 插件主逻辑,暴露给 Cordova 的接口
│ └── SQLitePlugin.h # [C++ 声明] 插件接口定义
├── www # [前端目录] 存放 JavaScript 接口文件
│ ├── LICENSE # [文本] 前端代码的开源许可证
│ └── SQLitePlugin.js # [JS 文件] 暴露给 Web 前端调用的 JavaScript 接口
├── .gitignore # [配置] Git 版本控制忽略文件配置
├── LICENSE # [文本] 项目根目录的开源许可证
├── OAT.xml # [配置] 门禁配置文件
├── package.json # [配置] NPM 包配置文件
├── plugin.xml # [配置] Cordova 插件核心配置文件
└── README.md # [文档] 项目说明文档贡献代码
使用过程中发现任何问题都可以提 Issue ,当然也非常欢迎发 PR 共建。
许可证
本插件基于 Apache License 2.0 开源,详见 LICENSE 文件。
官方资源
Android 和 iOS:cordova-sqlite-storage 官方指南
GitCode 仓库:https://gitcode.com/CPF-Cordova/Cordova-sqlite-storage
