@cordova-ohos/cordova-sqlite-evcore-extbuild-free

v0.19.2

Published

4 days ago

Cordova Sqlite Storage Plugin

0High
0Medium
0Low

cordova sqlite-storage ecosystem:cordova cordova-openharmony

cordova-sqlite-evcore-extbuild-free

本项目基于 [email protected] 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。

cordova-sqlite-evcore-extbuild-free

简介

cordova-sqlite-evcore-extbuild-free 是一款高性能、轻量级的 Cordova SQLite 数据库插件，基于 SQLite 原生引擎开发，集成增强型核心功能，支持数据库加密、事务管理、批量操作及跨平台适配，为混合式移动应用提供稳定可靠的本地数据存储解决方案，适用于离线数据缓存、本地业务数据存储等场景。本项目依赖于 cordova-sqlite-storage 插件，并无功能升级，只为 Android/iOS 项目移植 OHOS 系统，保持接口兼容性。

功能特性

完整 SQLite 支持：兼容 SQLite 3.40+ 所有核心语法，支持复杂查询、触发器、视图、索引等高级特性
数据库加密：支持基于 SQLCipher 内核的数据库加密功能，保障敏感数据安全（需额外配置）
事务管理：支持显式事务（BEGIN/COMMIT/ROLLBACK）和自动事务，确保数据一致性
批量操作：提供批量执行 SQL 语句接口，大幅提升批量插入/更新效率
跨平台适配：完美适配 Android、iOS 和 OpenHarmony 三平台
异步非阻塞：所有数据库操作均为异步执行，避免阻塞 UI 线程，提升应用响应速度
数据迁移支持：提供数据库版本升级回调，支持平滑的数据结构迁移和历史数据处理

支持平台

Android：API 19 及以上（Android 4.4+）
iOS：10.0 及以上
OHOS：5.0+

下载安装

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

从 npm 安装（推荐）

# 安装 hcordova
npm install -g hcordova

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

# 安装指定 OHOS 平台
hcordova plugin add cordova-sqlite-evcore-extbuild-free --platform ohos

# 安装指定版本（OHOS 平台）
hcordova plugin add [email protected] --platform ohos

从 GitCode 仓库安装

# 仅安装到 OHOS 平台（无加密开发版）
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-sqlite-evcore-extbuild-free.git --platform ohos

# 指定标签/分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-sqlite-evcore-extbuild-free.git@develop --platform ohos

离线安装（本地包）

适用于无网络环境，先下载插件包到本地，再执行离线安装：

# 下载插件包到本地（示例路径：~/Downloads/cordova-sqlite-evcore-extbuild-free）
# 执行离线安装
hcordova plugin add ~/Downloads/cordova-sqlite-evcore-extbuild-free --platform ohos

安装后验证

安装完成后，可通过以下命令验证插件是否成功添加到项目中：

# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装
hcordova plugin list

卸载

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

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

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

约束与限制

本项目依赖于 cordova-sqlite-storage 实现数据库所有功能，如果您是新项目，推荐使用 cordova-sqlite-storage 插件

兼容性

支持：

| 项目 | 版本/信息 | |-----|--------| | 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) |

使用示例

1. 打开/创建数据库示例

// 打开已存在的数据库，若不存在则创建新数据库，返回数据库实例
var global_db = window.sqlitePlugin.openDatabase({name: 'tonge.db', location: 'default'});

2. 事务操作示例

// 开启事务，批量执行 SQL 操作，确保原子性
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 语句示例

3.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) {
				});
			}
		});
	}, function(error){
		console.log("updateConst 失败"+error);
	},function(){
		console.log("updateConst 成功:"+confKey);
		callBack();
	});
}

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

3.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.log("insertCorpUser 失败"+error);
	},function(){
		console.log("insertCorpUser 成功");
		callBack();
	});
}

使用说明

核心概念

1. 数据库实例

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

2. 事务

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

显式事务：通过 transaction 方法手动开启，需手动提交或回滚
隐式事务：单条 SQL 操作默认开启隐式事务，执行完成后自动提交

3. 结果集

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

4. 版本迁移

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

API 参考

插件通过全局对象 window.sqlitePlugin 暴露所有 API，所有操作均为异步执行，通过回调函数处理结果。具体使用示例见「使用示例」章节。

1. 打开/创建数据库

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

2. 事务操作

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

3. 执行 sql 语句

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

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);

目录结构

cordova-sqlite-evcore-extbuild-free  # [根目录] SQLite 数据库插件项目根目录
├── .gitignore                       # [配置] Git 版本控制忽略文件配置
├── LICENSE                          # [文本] 开源许可证文件
├── OAT.xml                          # [配置] 门禁配置文件
├── package.json                     # [配置] NPM 包配置文件，定义依赖和脚本
├── plugin.xml                       # [配置] Cordova 插件核心配置文件，定义插件 ID、版本、依赖及文件映射
└── README.md                        # [文档] 项目说明文档

贡献代码

使用过程中发现任何问题都可以提 Issue ，当然也非常欢迎发 PR 共建。

许可证

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

官方资源

Android 和 iOS：cordova-sqlite-evcore-extbuild-free 官方指南
GitCode 仓库：CPF-Cordova/cordova-sqlite-evcore-extbuild-free