cordova-sqlite-evcore-extbuild-free SQLite 数据库插件

一款高性能、轻量级的 Cordova SQLite 数据库插件，基于 SQLite 原生引擎开发，集成增强型核心功能，支持数据库加密、事务管理、批量操作及跨平台适配，为混合式移动应用提供稳定可靠的本地数据存储解决方案，适用于离线数据缓存、本地业务数据存储等场景。

功能特性

• 完整 SQLite 支持：兼容 SQLite 3.40+ 所有核心语法，支持复杂查询、触发器、视图、索引等高级特性

• 数据库加密：支持基于 SQLCipher 内核的数据库加密功能，保障敏感数据安全（需额外配置）

• 事务管理：支持显式事务（BEGIN/COMMIT/ROLLBACK）和自动事务，确保数据一致性

• 批量操作：提供批量执行 SQL 语句接口，大幅提升批量插入/更新效率

• 跨平台适配：完美适配 Android 、 iOS和HarmonyOS 三平台

• 异步非阻塞：所有数据库操作均为异步执行，避免阻塞 UI 线程，提升应用响应速度

• 数据迁移支持：提供数据库版本升级回调，支持平滑的数据结构迁移和历史数据处理

安装方法

确保已创建 Cordova 项目（若未创建，执行 cordova create sqliteDemo com.example.sqlite SQLiteDemo 创建），进入项目根目录后通过以下方式安装插件：

1. 基础安装

# 安装hcordova
npm install -g hcordova

# 安装稳定版插件
hcordova plugin add cordova-sqlite-evcore-extbuild-free

2. 安装指定版本

# 安装 1.0.0 版本
hcordova plugin add [email protected] --plarform ohos

3. 从 GitCode 安装开发版

# 无加密开发版
hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-sqlite-evcore-extbuild-free.git  --plarform ohos

4. 卸载方法

进入项目根目录，执行以下命令卸载插件，若安装了加密依赖也需一并卸载：

# 卸载数据库插件
hcordova plugin remove cordova-sqlite-evcore-extbuild-free

# 指定HarmonyOS卸载
hcordova plugin remove cordova-sqlite-evcore-extbuild-free --platform ohos

5. 核心概念

1. 数据库实例

每个数据库对应一个实例对象，通过 openDatabase 方法创建，所有数据库操作均通过该实例执行。建议应用全局维护一个数据库实例，避免频繁创建和关闭连接。

2. 事务

确保一组数据库操作的原子性，要么全部执行成功，要么全部执行失败并回滚。本插件支持两种事务模式：

• 显式事务：通过 transaction 方法手动开启，需手动提交或回滚

• 隐式事务：单条 SQL 操作默认开启隐式事务，执行完成后自动提交

3. 结果集

查询操作（SELECT）返回的结果容器，包含查询结果的总数和具体数据，通过 rows.length 获取总数，通过 rows.item(index) 获取指定索引的记录。

4. 版本迁移

当数据库版本号提升时，触发 upgrade 回调，用于执行表结构修改、数据迁移等操作，确保旧版本数据平滑过渡到新版本。

6. API 参考

插件通过全局对象 window.sqlitePlugin 暴露所有 API，所有操作均为异步执行，通过回调函数处理结果。

1. 打开/创建数据库

打开已存在的数据库，若不存在则创建新数据库，返回数据库实例。

/**
 * 打开/创建数据库
 * @param {Object} options - 数据库配置选项
 * @param {Function} successCallback - 成功回调（参数：db 数据库实例）
 * @param {Function} errorCallback - 错误回调（参数：error 错误对象）
 */
sqlitePlugin.openDatabase(options, successCallback, errorCallback);

使用示例：

var global_db = window.sqlitePlugin.openDatabase({name: 'tonge.db', location: 'default'});

2. 事务操作

开启事务，批量执行 SQL 操作，确保原子性。

/**
 * 执行事务
 * @param {Function} transactionCallback - 事务回调（参数：tx 事务对象）
 * @param {Function} errorCallback - 事务失败回调（参数：error 错误对象）
 * @param {Function} successCallback - 事务成功回调（无参数）
 */
db.transaction(transactionCallback, errorCallback, successCallback);

使用示例：

global_db.transaction(function(tx) {
    //批量执行其他sql语句
    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))');
}, function(error){
    //事务执行失败
    alert("checkDb失败"+error);
}, function(){
   //事务执行成功
});

3. 执行sql语句

执行查询类 SQL 语句，返回结果集。

/**
 * 执行查询 SQL
 * @param {String} sql - 查询 SQL 语句
 * @param {Array} params - SQL 参数数组
 * @param {Function} successCallback - 成功回调（参数：result 结果集对象）
 * @param {Function} errorCallback - 错误回调（参数：error 错误对象）
 */
db.executeSql(sql, params, successCallback, errorCallback);

使用示例：

//执行更新和插入
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) {
				});
			}
		});
	}, function(error){
		console.log("updateConst失败"+error);
	},function(){
		console.log("updateConst成功:"+confKey);
		callBack();
	});
}

//执行查询语句
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.log("getMemAccount失败"+error);
	},function(){
		if(rows.length != 0) {
            //获取到了数据
			getMemAccountSuccess(rows.item(0));
		} else {
			console.log("没有获取到登录会员的数据");
		}
	});
}

//执行删除和插入
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.log("insertCorpUser失败"+error);
	},function(){
		console.log("insertCorpUser成功");
		callBack();
	});
}

4. 关闭数据库

关闭数据库连接，释放资源，建议在应用退出前执行。

/**
 * 关闭数据库
 * @param {Function} successCallback - 成功回调（无参数）
 * @param {Function} errorCallback - 错误回调（参数：error 错误对象）
 */
db.close(successCallback, errorCallback);

5. 删除数据库

删除指定名称的数据库文件，需先关闭数据库连接。

/**
 * 删除数据库
 * @param {String} dbName - 数据库名称
 * @param {Function} successCallback - 成功回调（无参数）
 * @param {Function} errorCallback - 错误回调（参数：error 错误对象）
 */
sqlitePlugin.deleteDatabase(dbName, successCallback, errorCallback);

许可证

本插件基于 Apache License 2.0 开源，详见 LICENSE 文件。

参考资源

• Android和iOS：cordova-sqlite-evcore-extbuild-free 官方指南

• GitCode 仓库：OpenHarmony-Cordova/cordova-sqlite-evcore-extbuild-free