{"_id":"@cordova-ohos/cordova-sqlite-storage","_rev":"3-c50d9f96d8cdefa31719df5366db8fac","name":"@cordova-ohos/cordova-sqlite-storage","dist-tags":{"latest":"7.0.1"},"versions":{"7.0.0":{"name":"@cordova-ohos/cordova-sqlite-storage","version":"7.0.0","keywords":["cordova","sqlite-storage","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-sqlite-storage@7.0.0","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-sqlite-storage/issues"},"dist":{"shasum":"5744ceee335f44d658d1f124ebee6c50f618ab6a","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-sqlite-storage/-/cordova-sqlite-storage-7.0.0.tgz","fileCount":15,"integrity":"sha512-Knh9V3EnsFMZK2c7VaIN9WCvi7VZydtCZF4g+AUYspDC8eyj6LvIu5HRoeU+I8rzUeWSsBrNcqV1MXzsXS2/rQ==","signatures":[{"sig":"MEQCIDSjsBxA1MLhk5sgbxNkR9WQ3hfYIzPVV09hSltahrX3AiAHIcllLnWQgx1DfqIrGbQW4symTwZX0pgiaSyOEkRcDQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":10093665},"cordova":{"id":"cordova-sqlite-storage","platforms":["ohos"]},"engines":{"cordovaDependencies":{"7.0.0":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"f6701b03ba891e1cf547d99d9c9ae39556102668","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-sqlite-storage","type":"git"},"_npmVersion":"10.5.1","description":"Cordova sqlite storage Plugin","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-sqlite-storage_7.0.0_1774228994789_0.9712654261251066","host":"s3://npm-registry-packages-npm-production"}},"7.0.1":{"name":"@cordova-ohos/cordova-sqlite-storage","version":"7.0.1","description":"Cordova SQLite Storage Plugin","cordova":{"id":"cordova-sqlite-storage","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-sqlite-storage"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-sqlite-storage/issues"},"keywords":["cordova","sqlite-storage","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"7.0.1":{"@cordova-ohos/ohos":">=2.0.0","hcordova":">=1.0.0"}}},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-sqlite-storage@7.0.1","gitHead":"fe6b542a59c4e2e2159612bdd734e4150177327d","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-dsrKJp9ORiOnqzFZEJMLZE9X7cbZebkqa0lpZ7bBk//hb7nqcVvXKeOU1eEqS8yZuJxoTC3Z1TLyULj9rVLUvA==","shasum":"efa8e25457181f13c1284773dc97b4358fdf47d1","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-sqlite-storage/-/cordova-sqlite-storage-7.0.1.tgz","fileCount":16,"unpackedSize":10149438,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBElYwo2ZbE2A+C60o7a0LNsYtMm+mQeky3WKfYtEeIbAiBsyyXgoRpd7SdC2faZzVUgWgFbED898jVWLq2ohC2QBg=="}]},"_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"directories":{},"maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cordova-sqlite-storage_7.0.1_1785154387989_0.31064048609533645"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-23T01:23:14.710Z","modified":"2026-07-27T12:13:08.436Z","7.0.0":"2026-03-23T01:23:15.081Z","7.0.1":"2026-07-27T12:13:08.194Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-sqlite-storage/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","sqlite-storage","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-sqlite-storage"},"description":"Cordova SQLite Storage Plugin","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"readme":"# <center>cordova-sqlite-storage</center>\r\n\r\n[![zh-CN](https://img.shields.io/badge/lang-中文-blue.svg)](README.md)\r\n[![en](https://img.shields.io/badge/lang-English-blue.svg)](README.en.md)\r\n\r\n本项目基于 [cordova-sqlite-storage@7.0.0](https://www.npmjs.com/package/cordova-sqlite-storage/v/7.0.0) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-sqlite-storage](#cordova-sqlite-storage)\r\n  - [简介](#简介)\r\n  - [功能特性](#功能特性)\r\n  - [OHOS 平台特性](#ohos-平台特性)\r\n  - [支持平台](#支持平台)\r\n  - [前置准备](#前置准备)\r\n  - [下载安装](#下载安装)\r\n    - [前提条件](#前提条件)\r\n    - [基础安装（推荐，从 npm 仓库）](#基础安装推荐从-npm-仓库)\r\n    - [从 GitCode 安装开发版](#从-gitcode-安装开发版)\r\n    - [离线安装（本地包）](#离线安装本地包)\r\n    - [安装后验证](#安装后验证)\r\n    - [卸载插件](#卸载插件)\r\n  - [约束与限制](#约束与限制)\r\n    - [兼容性](#兼容性)\r\n  - [使用示例](#使用示例)\r\n    - [1. 打开/创建数据库（核心操作）](#1-打开创建数据库核心操作)\r\n    - [2. 事务操作（批量执行 SQL）](#2-事务操作批量执行-sql)\r\n    - [3. 执行 SQL 语句（增删改查）](#3-执行-sql-语句增删改查)\r\n    - [4. 关闭与删除数据库](#4-关闭与删除数据库)\r\n    - [5. 数据库版本迁移](#5-数据库版本迁移)\r\n  - [使用说明](#使用说明)\r\n    - [1. 核心 API 说明](#1-核心-api-说明)\r\n      - [1.1 打开/创建数据库（核心 API）](#11-打开创建数据库核心-api)\r\n      - [1.2 事务操作（核心 API）](#12-事务操作核心-api)\r\n      - [1.3 执行 SQL 语句（核心 API）](#13-执行-sql-语句核心-api)\r\n      - [1.4 关闭数据库](#14-关闭数据库)\r\n      - [1.5 删除数据库](#15-删除数据库)\r\n    - [2. 常见问题（FAQ）](#2-常见问题faq)\r\n      - [Q1: 调用 openDatabase 后数据库创建失败怎么办？](#q1-调用-opendatabase-后数据库创建失败怎么办)\r\n      - [Q2: 执行 SQL 语句时提示“table not found”（表不存在）怎么办？](#q2-执行-sql-语句时提示table-not-found表不存在怎么办)\r\n      - [Q3: 事务执行失败后，数据没有回滚怎么办？](#q3-事务执行失败后数据没有回滚怎么办)\r\n      - [Q4: 大批量数据插入/更新效率低怎么办？](#q4-大批量数据插入更新效率低怎么办)\r\n      - [Q5: 应用退出后，数据库数据丢失怎么办？](#q5-应用退出后数据库数据丢失怎么办)\r\n    - [3. 注意事项](#3-注意事项)\r\n  - [目录结构](#目录结构)\r\n  - [贡献代码](#贡献代码)\r\n  - [许可证](#许可证)\r\n  - [官方资源](#官方资源)\r\n\r\n\r\n## 简介\r\n\r\ncordova-sqlite-storage 是一款专为 Cordova/PhoneGap 应用设计的轻量高效 SQLite 数据库插件，基于原生 SQLite 引擎封装，提供简洁易用的 API 接口，支持跨平台数据存储、事务管理、批量操作等核心能力，是混合移动应用本地数据持久化的理想解决方案，广泛适用于离线数据缓存、本地业务数据管理、日志存储等场景。本文档仅介绍该插件在 OHOS 系统中的应用、安装、配置、使用方法及注意事项，帮助开发者快速集成本地数据库功能，重点突出 OHOS 平台的特性与使用规范。\r\n\r\n## 功能特性\r\n\r\n- **全平台兼容**：完美支持 Android、iOS、OHOS 三大主流移动平台，适配各系统最新版本特性，重点适配 OHOS 5.0+ 系统，遵循 OHOS 系统原生规范\r\n\r\n- **原生性能加持**：基于系统原生 SQLite 引擎开发，避免 JS 模拟数据库的性能损耗，操作响应迅速，读写效率高，适配 OHOS 系统性能优化要求\r\n\r\n- **完整事务支持**：支持显式事务（BEGIN/COMMIT/ROLLBACK）和隐式事务，确保数据操作的原子性和一致性，有效避免数据错乱\r\n\r\n- **批量操作优化**：提供批量执行 SQL 接口，大幅提升大批量数据插入、更新效率，减少 IO 开销，适配 OHOS 系统 IO 操作规范\r\n\r\n- **版本迁移支持**：内置数据库版本管理机制，通过升级回调实现平滑的表结构变更和数据迁移，无需手动处理旧版本数据兼容问题\r\n\r\n- **灵活存储位置**：支持配置数据库存储路径，适配 Android 分区存储和 iOS、OHOS 沙盒机制，可根据业务需求选择存储位置，符合 OHOS 系统沙箱安全规范\r\n\r\n- **丰富错误反馈**：提供详细的错误代码和描述信息，便于开发者快速定位和调试问题，降低集成难度\r\n\r\n- **内存数据库支持**：支持创建纯内存数据库，适用于临时数据处理场景，应用退出后数据自动清除，节省 OHOS 系统存储资源\r\n\r\n## OHOS 平台特性\r\n\r\n该插件在 OHOS 平台的实现贴合系统原生存储规范，核心特性及特殊限制如下，需重点关注：\r\n\r\n- 适配 OHOS 沙箱机制：数据库文件默认存储在应用沙箱路径下，无法访问沙箱外文件，确保系统数据安全\r\n\r\n- 版本兼容性：适配 OHOS 5.0+ 系统，支持 DevEco Studio 5.0+ 开发环境，SDK 需为 API12+，确保插件功能稳定运行\r\n\r\n- 事务稳定性：针对 OHOS 系统异步操作机制优化事务处理，避免因系统调度导致的事务异常，确保数据一致性\r\n\r\n- 内存优化：适配 OHOS 系统内存管理机制，关闭数据库后自动释放资源，减少内存占用，提升应用运行稳定性\r\n\r\n\r\n## 支持平台\r\n\r\n- **OHOS**（5.0+，适配系统沙箱机制，支持数据库创建、事务、批量操作，兼容 DevEco Studio 5.0+）\r\n\r\n- **Android**（适配主流版本，支持全量功能，适配分区存储，无特殊权限限制）\r\n\r\n- **iOS**（适配主流版本，支持全量功能，遵循 iOS 沙盒机制，无需额外权限配置）\r\n\r\n## 前置准备\r\n\r\n在集成插件前，需确保开发环境满足基础要求，完成必要的前置配置，具体步骤如下：\r\n\r\n- 已安装 Node.js（v14.0.0 及以上）和 npm（v6.0.0 及以上），可通过 `node -v` 和 `npm -v` 命令验证版本；\r\n\r\n- 已全局安装 HCordova CLI（v10.0.0 及以上），用于插件的安装、卸载和管理；\r\n\r\n- 已创建 Cordova 项目（若尚未创建，可通过 `cordova create sqliteApp com.example.sqliteapp SQLiteApp` 命令快速创建）；\r\n\r\n- 确保项目适配 OHOS 5.0 及以上版本，DevEco Studio 版本为 5.0+，SDK 为 API12+，避免因版本过低导致插件功能异常；\r\n\r\n- 熟悉 OHOS 系统沙箱路径规范，了解 Cordova 插件在 OHOS 平台的文件访问方式。\r\n\r\n## 下载安装\r\n\r\n通过 HCordova CLI 即可快速安装插件，支持全平台安装或指定 OHOS 平台安装，安装流程简洁高效，安装后可通过命令验证安装结果。\r\n\r\n### 前提条件\r\n\r\n安装插件前，需先安装 HCordova CLI，执行以下命令安装：\r\n\r\n```bash\r\nnpm install -g hcordova\r\n```\r\n\r\n### 基础安装（推荐，从 npm 仓库）\r\n\r\n在 Cordova 项目根目录执行以下命令，插件会自动处理各平台依赖与基础配置，默认安装最新稳定版本，指定 OHOS 平台安装：\r\n\r\n```bash\r\n# 全平台安装\r\nhcordova plugin add cordova-sqlite-storage\r\n\r\n# 安装最新稳定版（仅 OHOS 平台）\r\nhcordova plugin add cordova-sqlite-storage --platform ohos\r\n\r\n# 安装指定版本（示例：1.0.0 版本，仅 OHOS 平台）\r\nhcordova plugin add cordova-sqlite-storage@1.0.0 --platform ohos\r\n```\r\n\r\n### 从 GitCode 安装开发版\r\n\r\n若需使用开发中的最新功能，可直接从 GitCode 仓库安装，仅适配 OHOS 平台（修正命令拼写错误）：\r\n\r\n```bash\r\n# 无加密开发版\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/Cordova-sqlite-storage.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/Cordova-sqlite-storage.git@develop --platform ohos\r\n```\r\n\r\n### 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：../Downloads/cordova-sqlite-storage）\r\n# 执行离线安装\r\nhcordova plugin add ../Downloads/cordova-sqlite-storage --platform ohos\r\n```\r\n\r\n### 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装\r\nhcordova plugin list\r\n```\r\n\r\n\r\n### 卸载插件\r\n\r\n如需移除插件，执行以下命令即可清理相关配置与依赖，支持全平台卸载或指定 OHOS 平台卸载：\r\n\r\n```bash\r\n# 全平台卸载数据库插件\r\nhcordova plugin remove cordova-sqlite-storage\r\n\r\n# 指定 OHOS 平台卸载\r\nhcordova plugin remove cordova-sqlite-storage --platform ohos\r\n```\r\n\r\n## 约束与限制\r\n\r\n- 依赖插件：无强制依赖，@cordova-ohos/ohos 版本为 2.0.0 及以上；\r\n\r\n- 平台限制：OHOS 平台仅支持 5.0 及以上版本，低于该版本的系统可能出现数据库创建失败、API 调用异常等问题；\r\n\r\n- 路径限制：仅支持 OHOS 系统沙箱路径，无法访问沙箱外的文件；\r\n\r\n- API 调用时机：所有 JavaScript API 必须在 `deviceready` 事件触发后调用，否则会出现 `window.sqlitePlugin` 对象未定义、调用失败等异常；\r\n\r\n- 数据库连接限制：建议应用全局维护一个数据库实例，避免频繁创建和关闭连接，否则会导致性能损耗和连接异常；\r\n\r\n### 兼容性\r\n\r\n支持：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| SDK | API12+ |\r\n| IDE | DevEco Studio: 5.0+ |\r\n| ROM | 5.1+ |\r\n| Emulator | OpenHarmony 6.0+ |\r\n\r\n在以下版本中已测试通过：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 |\r\n| SDK | 5.0.0(12) |\r\n| IDE | DevEco Studio: 6.0.13.200 |\r\n| ROM | 5.1.0.120 SP3 |\r\n| Emulator | OpenHarmony 6.0.1(21) |\r\n\r\n## 使用示例\r\n\r\n插件通过全局对象 `window.sqlitePlugin` 暴露所有核心 API，所有操作均为异步执行，通过回调函数处理结果。所有 API 需在 `deviceready` 事件触发后调用。以下为 OHOS 平台核心功能的完整使用示例，可直接复制到项目中使用。\r\n\r\n### 1. 打开/创建数据库（核心操作）\r\n\r\n打开已存在的数据库，若不存在则创建新数据库，全局维护一个数据库实例，避免频繁创建连接：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    /**\r\n     * 打开/创建数据库\r\n     * @param {Object} options - 数据库配置选项\r\n     * @param {Function} successCallback - 成功回调（参数：db 数据库实例）\r\n     * @param {Function} errorCallback - 错误回调（参数：error 错误对象）\r\n     */\r\n    const global_db = window.sqlitePlugin.openDatabase({\r\n        name: 'tonge.db', // 数据库名称\r\n        location: 'default' // 默认存储位置\r\n    }, function(db) {\r\n        console.log(\"数据库打开/创建成功\");\r\n        // 数据库实例全局可用\r\n        window.global_db = db;\r\n    }, function(error) {\r\n        console.error(\"数据库打开/创建失败：\", error);\r\n        alert(\"数据库初始化失败\");\r\n    });\r\n}, false);\r\n```\r\n\r\n### 2. 事务操作（批量执行 SQL）\r\n\r\n开启显式事务，批量执行表创建、数据插入等操作，确保原子性，适用于初始化数据库表结构：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    // 先打开数据库\r\n    var global_db = window.sqlitePlugin.openDatabase({name: 'tonge.db', location: 'default'});\r\n    \r\n    /**\r\n     * 执行事务\r\n     * @param {Function} transactionCallback - 事务回调（参数：tx 事务对象）\r\n     * @param {Function} errorCallback - 事务失败回调（参数：error 错误对象）\r\n     * @param {Function} successCallback - 事务成功回调（无参数）\r\n     */\r\n    global_db.transaction(function(tx) {\r\n        // 批量创建表结构\r\n        tx.executeSql('CREATE TABLE IF NOT EXISTS TONGE_CONFIG_SYS(ID INTEGER PRIMARY KEY AUTOINCREMENT, CONF_KEY VARCHAR(64), CONF_VALUE VARCHAR(512))');\r\n        tx.executeSql('CREATE TABLE IF NOT EXISTS TONGE_SYS_CONST(ID INTEGER PRIMARY KEY AUTOINCREMENT, CONF_KEY VARCHAR(64), CONF_VALUE VARCHAR(4096))');\r\n        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))');\r\n    }, function(error){\r\n        // 事务执行失败，自动回滚\r\n        console.error(\"事务执行失败：\", error);\r\n        alert(\"数据库初始化失败\"+error);\r\n    }, function(){\r\n        // 事务执行成功，所有操作提交\r\n        console.log(\"数据库表结构创建成功\");\r\n    });\r\n}, false);\r\n```\r\n\r\n### 3. 执行 SQL 语句（增删改查）\r\n\r\n通过 executeSql 方法执行查询、插入、更新、删除等 SQL 操作，以下为常用场景示例：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    // 全局数据库实例\r\n    var global_db = window.sqlitePlugin.openDatabase({name: 'tonge.db', location: 'default'});\r\n\r\n    // 1. 插入/更新数据（示例：更新系统常量，不存在则插入）\r\n    function updateConst(confKey, confVale, callBack) {\r\n        global_db.transaction(function(tx) {\r\n            tx.executeSql(\"update TONGE_SYS_CONST set CONF_VALUE=? where CONF_KEY=?\", [confVale, confKey], function(tx, result){\r\n                if(result.rowsAffected == 0) {\r\n                    // 无匹配数据，执行插入\r\n                    tx.executeSql(\"insert into TONGE_SYS_CONST(CONF_KEY, CONF_VALUE) values(?, ?)\", [confKey, confVale], function(tx, result) {\r\n                        console.log(\"插入系统常量成功：\", confKey);\r\n                    });\r\n                } else {\r\n                    console.log(\"更新系统常量成功：\", confKey);\r\n                }\r\n            });\r\n        }, function(error){\r\n            console.error(\"updateConst 失败：\", error);\r\n        },function(){\r\n            console.log(\"updateConst 执行完成:\"+confKey);\r\n            callBack && callBack();\r\n        });\r\n    }\r\n\r\n    // 2. 查询数据（示例：查询会员账号信息）\r\n    function getMemAccount(memAccount, getMemAccountSuccess) {\r\n        var rows = null;\r\n        // 读事务（仅执行查询操作，性能更优）\r\n        global_db.readTransaction(function(tx) {\r\n            tx.executeSql(\"select * from TONGE_MEM_ACCOUNT where MEM_ACCOUNT=?\", [memAccount], function(tx, result) {\r\n                rows = result.rows; // 结果集\r\n            });\r\n        }, function(error){\r\n            console.error(\"getMemAccount 失败：\", error);\r\n        },function(){\r\n            if(rows.length != 0) {\r\n                // 获取指定索引的记录\r\n                getMemAccountSuccess && getMemAccountSuccess(rows.item(0));\r\n            } else {\r\n                console.log(\"没有获取到登录会员的数据\");\r\n            }\r\n        });\r\n    }\r\n\r\n    // 3. 删除/插入数据（示例：插入企业用户，先删除旧数据）\r\n    function insertCorpUser(user, callBack) {\r\n        global_db.transaction(function(tx) {\r\n            tx.executeSql(\"delete from TONGE_CORP_USER where USER_NAME=?\", [user.userName], function(tx, result) {\r\n                // 删除后执行插入\r\n                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){\r\n                    if(result.rowsAffected != 1) {\r\n                        console.log(\"insertCorpUser 失败,影响行数\"+result.rowsAffected);\r\n                    }\r\n                });\r\n            });\r\n        }, function(error){\r\n            console.error(\"insertCorpUser 失败：\", error);\r\n        },function(){\r\n            console.log(\"insertCorpUser 成功\");\r\n            callBack && callBack();\r\n        });\r\n    }\r\n\r\n    // 调用示例\r\n    updateConst(\"system_version\", \"1.0.0\", function() {\r\n        console.log(\"系统版本更新完成\");\r\n    });\r\n    getMemAccount(\"test123\", function(userInfo) {\r\n        console.log(\"查询到会员信息：\", userInfo);\r\n    });\r\n}, false);\r\n```\r\n\r\n### 4. 关闭与删除数据库\r\n\r\n关闭数据库连接释放资源，删除数据库文件（需先关闭连接），适用于应用退出或数据清理场景：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    // 全局数据库实例\r\n    var global_db = window.sqlitePlugin.openDatabase({name: 'tonge.db', location: 'default'});\r\n\r\n    // 1. 关闭数据库\r\n    function closeDatabase(callback) {\r\n        global_db.close(function() {\r\n            console.log(\"数据库关闭成功，资源已释放\");\r\n            if (callback) {\r\n                callback();\r\n            }\r\n        }, function(error) {\r\n            console.error(\"数据库关闭失败：\", error);\r\n        });\r\n    }\r\n\r\n    // 2. 删除数据库（需先关闭数据库连接）\r\n    function deleteDatabase() {\r\n        // 先关闭连接\r\n        closeDatabase(function() {\r\n            sqlitePlugin.deleteDatabase(\"tonge.db\", function() {\r\n                console.log(\"数据库删除成功\");\r\n            }, function(error) {\r\n                console.error(\"数据库删除失败：\", error);\r\n            })\r\n        );\r\n    }\r\n\r\n    // 应用退出前调用关闭数据库\r\n    window.addEventListener('beforeunload', function() {\r\n        closeDatabase();\r\n    });\r\n\r\n    // 调用删除数据库（谨慎使用，会删除所有数据）\r\n    // deleteDatabase();\r\n}, false);\r\n```\r\n\r\n### 5. 数据库版本迁移\r\n\r\n当数据库版本号提升时，触发 upgrade 回调，执行表结构修改、数据迁移操作，确保旧版本数据兼容：\r\n\r\n```js\r\n// 等待 Cordova 环境就绪\r\ndocument.addEventListener('deviceready', function() {\r\n    const global_db = window.sqlitePlugin.openDatabase({\r\n        name: 'tonge.db',\r\n        location: 'default',\r\n        version: '2.0' // 版本号从 1.0 提升到 2.0，触发 upgrade 回调\r\n    }, function(db) {\r\n        console.log(\"数据库打开成功（版本 2.0）\");\r\n    }, function(error) {\r\n        console.error(\"数据库打开失败：\", error);\r\n    }, function(db, oldVersion, newVersion, tx) {\r\n        // 版本迁移回调（oldVersion：旧版本号，newVersion：新版本号）\r\n        console.log(\"数据库版本迁移：\", oldVersion, \"->\", newVersion);\r\n        if(oldVersion < 2) {\r\n            // 从 1.0 版本迁移到 2.0 版本，添加新字段\r\n            tx.executeSql(\"ALTER TABLE TONGE_SYS_CONST ADD COLUMN UPDATE_TIME DATETIME DEFAULT CURRENT_TIMESTAMP\");\r\n            console.log(\"版本迁移完成，添加 UPDATE_TIME 字段\");\r\n        }\r\n    });\r\n}, false);\r\n```\r\n\r\n## 使用说明\r\n\r\n以下为插件使用的核心说明，包括 API 详解、参数说明、常见问题及注意事项等，帮助开发者快速上手并避免异常，重点突出 OHOS 平台特性与限制。\r\n\r\n### 1. 核心 API 说明\r\n\r\n插件所有方法均挂载在全局 `window.sqlitePlugin` 对象下，无需额外引入，所有操作均为异步执行，通过回调函数处理结果。所有 API 均需在 `deviceready` 事件触发后调用。\r\n\r\n#### 1.1 打开/创建数据库（核心 API）\r\n\r\n功能：打开已存在的数据库，若不存在则创建新数据库，返回数据库实例，是所有数据库操作的基础。\r\n\r\n语法：\r\n\r\n```javascript\r\nsqlitePlugin.openDatabase(options, successCallback, errorCallback);\r\n```\r\n\r\n参数说明：\r\n\r\n- options：配置参数对象，必填，包含以下属性：\r\n        \r\n    - name：数据库名称，必填，字符串类型；\r\n\r\n    - location：存储位置，可选，默认 \"default\"；\r\n\r\n- successCallback：成功回调，参数为 db（数据库实例），触发即表示数据库打开/创建成功；\r\n\r\n- errorCallback：失败回调，参数为 error（错误对象），包含错误代码和描述；\r\n\r\n#### 1.2 事务操作（核心 API）\r\n\r\n功能：开启显式事务，批量执行 SQL 操作，确保原子性，要么全部成功，要么全部回滚。\r\n\r\n语法（写事务，支持增删改查）：\r\n\r\n```javascript\r\ndb.transaction(transactionCallback, errorCallback, successCallback);\r\n```\r\n\r\n语法（读事务，仅支持查询，性能更优）：\r\n\r\n```javascript\r\ndb.readTransaction(transactionCallback, errorCallback, successCallback);\r\n```\r\n\r\n参数说明：\r\n\r\n- transactionCallback：事务回调，必填，参数为 tx（事务对象），用于执行 SQL 操作；\r\n\r\n- errorCallback：事务失败回调，可选，参数为 error（错误对象），事务执行过程中出现错误时触发，自动回滚；\r\n\r\n- successCallback：事务成功回调，可选，无参数，所有 SQL 操作执行完成且无错误时触发，自动提交。\r\n\r\n#### 1.3 执行 SQL 语句（核心 API）\r\n\r\n功能：通过事务对象执行 SQL 语句，支持查询、插入、更新、删除等所有 SQL 操作。\r\n\r\n语法：\r\n\r\n```javascript\r\ntx.executeSql(sql, params, successCallback, errorCallback);\r\n```\r\n\r\n参数说明：\r\n\r\n- sql：SQL 语句，必填，字符串类型，支持所有标准 SQLite SQL 语句；\r\n\r\n- params：SQL 参数数组，可选，用于替换 SQL 语句中的占位符（?），避免 SQL 注入；\r\n\r\n- successCallback：成功回调，可选，参数为 (tx, result)，result 为结果集对象；\r\n\r\n- errorCallback：失败回调，可选，参数为 error（错误对象），SQL 执行失败时触发。\r\n\r\n结果集（result）属性说明：\r\n\r\n- rows.length：查询结果的记录总数；\r\n\r\n- rows.item(index)：获取指定索引（index）的记录，返回对象；\r\n\r\n- rowsAffected：增删改操作影响的行数。\r\n\r\n#### 1.4 关闭数据库\r\n\r\n功能：关闭数据库连接，释放系统资源，建议在应用退出前执行。\r\n\r\n语法：\r\n\r\n```javascript\r\ndb.close(successCallback, errorCallback);\r\n```\r\n\r\n参数说明：\r\n\r\n- successCallback：成功回调，可选，无参数，数据库关闭成功时触发；\r\n\r\n- errorCallback：失败回调，可选，参数为 error（错误对象），关闭失败时触发。\r\n\r\n#### 1.5 删除数据库\r\n\r\n功能：删除指定名称的数据库文件，需先关闭数据库连接，否则会删除失败。\r\n\r\n语法：\r\n\r\n```javascript\r\nsqlitePlugin.deleteDatabase(dbName, successCallback, errorCallback);\r\n```\r\n\r\n参数说明：\r\n\r\n- dbName：数据库名称，必填，字符串类型，与创建时的 name 一致；\r\n\r\n- successCallback：成功回调，可选，无参数，数据库删除成功时触发；\r\n\r\n- errorCallback：失败回调，可选，参数为 error（错误对象），删除失败时触发。\r\n\r\n### 2. 常见问题（FAQ）\r\n\r\n#### Q1: 调用 openDatabase 后数据库创建失败怎么办？\r\n\r\n1. 检查版本兼容性：确保 OHOS 系统版本为 5.0+，DevEco Studio 版本为 5.0+，SDK 为 API12+；\r\n\r\n2. 检查插件安装：执行 `hcordova plugin list` 确认插件已成功安装，若未安装则重新执行安装命令；\r\n\r\n3. 检查数据库名称：数据库名称避免包含特殊字符，建议使用字母、数字和下划线组合。\r\n\r\n#### Q2: 执行 SQL 语句时提示“table not found”（表不存在）怎么办？\r\n\r\n1. 检查表创建语句：确认 CREATE TABLE 语句语法正确，是否添加 IF NOT EXISTS 关键字（避免重复创建）；\r\n\r\n2. 检查事务执行：确保表创建语句在事务中执行，且事务已成功提交；\r\n\r\n3. 检查数据库实例：确保使用正确的数据库实例执行 SQL 语句，避免实例未初始化或已关闭；\r\n\r\n4. 检查版本迁移：若数据库版本提升，确认版本迁移回调中已正确创建或修改表结构。\r\n\r\n#### Q3: 事务执行失败后，数据没有回滚怎么办？\r\n\r\n插件默认支持事务回滚，若未回滚，需检查以下几点：\r\n\r\n1. 确认使用显式事务：单条 SQL 操作默认隐式事务，执行失败会自动回滚；显式事务需确保在 errorCallback 中未手动提交；\r\n\r\n2. 检查错误触发时机：确保事务中的 SQL 语句执行失败时，触发了 errorCallback，此时会自动回滚；\r\n\r\n3. 检查数据库连接：避免事务执行过程中关闭数据库连接，否则会导致事务异常，无法正常回滚。\r\n\r\n#### Q4: 大批量数据插入/更新效率低怎么办？\r\n\r\n可通过以下方式优化大批量数据操作效率：\r\n\r\n1. 使用显式事务：将所有批量操作放在一个事务中执行，减少 IO 开销；\r\n\r\n2. 使用参数化 SQL：通过 params 数组传递参数，避免拼接 SQL 语句，提升执行速度；\r\n\r\n3. 减少回调嵌套：避免在每次 SQL 执行后触发回调，批量执行完成后统一处理结果；\r\n\r\n4. 优化数据量：若数据量极大，可分批次执行，避免单次操作占用过多系统资源。\r\n\r\n#### Q5: 应用退出后，数据库数据丢失怎么办？\r\n\r\n1. 检查事务提交：确保所有增删改操作已通过事务提交，未提交的事务会导致数据未持久化；\r\n\r\n2. 检查数据库关闭：应用退出前，确保已调用 close 方法关闭数据库，避免数据写入未完成。\r\n\r\n### 3. 注意事项\r\n\r\n- API 调用时机：所有 JavaScript API 必须在 `deviceready` 事件触发后调用，否则会出现 `window.sqlitePlugin` 对象未定义、调用失败等异常。\r\n\r\n- 数据库连接：建议应用全局维护一个数据库实例，避免频繁创建和关闭连接，否则会导致性能损耗和连接异常；应用退出前务必关闭数据库，释放资源。\r\n\r\n- 事务使用：大批量数据操作建议使用显式事务，确保原子性，同时提升执行效率；读操作建议使用 readTransaction，优化性能。\r\n\r\n- SQL 语法：遵循 SQLite 标准 SQL 语法，避免使用平台专属 SQL 语句，确保跨平台兼容性；避免 SQL 注入，优先使用参数化 SQL。\r\n\r\n- 版本迁移：数据库版本号只能提升，不能降低；版本迁移回调中仅执行表结构修改、数据迁移操作，避免执行复杂业务逻辑。\r\n\r\n- 数据安全：敏感数据建议配置数据库加密，妥善保管加密密码；避免存储过多大型数据（如图片、视频），建议仅存储文件路径，文件单独存储。\r\n\r\n- 错误处理：建议为所有 API 调用添加错误回调，便于捕获异常，根据错误信息快速定位问题，提升应用稳定性。\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-sqlite-storage                 # [根目录] SQLite 本地存储插件项目根目录\r\n├── src                                # [源码目录] 存放原生平台代码\r\n│   └── main                           # [主目录] 主代码目录\r\n│       └── cpp                        # [C++ 目录] C++ 原生代码目录\r\n│           └── sqlc                   # [C++ 模块] SQLite C++ 封装模块文件夹\r\n│               ├── sqlite3.c          # [C 源文件] SQLite 核心库的 C 语言实现\r\n│               ├── sqlite3.h          # [C 头文件] SQLite 核心库的头文件\r\n│               ├── SQLiteConnectorDatabase.cpp # [C++ 实现] 数据库连接器实现，处理数据库连接逻辑\r\n│               ├── SQLiteConnectorDatabase.h   # [C++ 声明] 数据库连接器头文件\r\n│               ├── SQLiteHarmonyDatabase.cpp   # [C++ 实现] 针对 OHOS 系统的数据库适配实现\r\n│               ├── SQLiteHarmonyDatabase.h     # [C++ 声明] 针对 OHOS 系统的数据库适配头文件\r\n│               ├── SQLitePlugin.cpp            # [C++ 实现] 插件主逻辑，暴露给 Cordova 的接口\r\n│               └── SQLitePlugin.h              # [C++ 声明] 插件接口定义\r\n├── www                                # [前端目录] 存放 JavaScript 接口文件\r\n│   ├── LICENSE                        # [文本] 前端代码的开源许可证\r\n│   └── SQLitePlugin.js                # [JS 文件] 暴露给 Web 前端调用的 JavaScript 接口\r\n├── .gitignore                         # [配置] Git 版本控制忽略文件配置\r\n├── LICENSE                            # [文本] 项目根目录的开源许可证\r\n├── OAT.xml                            # [配置] 门禁配置文件\r\n├── package.json                       # [配置] NPM 包配置文件\r\n├── plugin.xml                         # [配置] Cordova 插件核心配置文件\r\n└── README.md                          # [文档] 项目说明文档\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Cordova/Cordova-sqlite-storage/issues) ，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/Cordova-sqlite-storage/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 官方资源\r\n\r\n- Android 和 iOS：[cordova-sqlite-storage 官方指南](https://www.npmjs.com/package/cordova-sqlite-storage)\r\n\r\n- GitCode 仓库：[https://gitcode.com/CPF-Cordova/Cordova-sqlite-storage](https://gitcode.com/CPF-Cordova/Cordova-sqlite-storage)\r\n","readmeFilename":"README.md"}