1
This commit is contained in:
@@ -0,0 +1,218 @@
|
||||
# x-sqlite-s
|
||||
|
||||
## 简介
|
||||
x-sqlite-s 是一个用于 uni-appx 的 SQLite 数据库操作插件，支持基本的数据库。
|
||||
|
||||
### 兼容性
|
||||
|
||||
| Harmony | IOS | Android | WEB | 小程序 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 支持 | 支持 | 支持 | 支持 | x |
|
||||
|
||||
## 安装
|
||||
在插件市场搜索并导入 x-sqlite-s 插件。
|
||||
|
||||
## 特别注意
|
||||
配置中的密码等加密功能,未实现,只是一个预设功能.
|
||||
|
||||
## web注意事项
|
||||
|
||||
请到插件目录内复制static到你的根目录static即可。否则web无法使用。
|
||||
|
||||
## 类型定义
|
||||
|
||||
### SQLiteConfig 配置项
|
||||
**鸿蒙不支持自定义其它目录**为了全平台兼容，不建议设置defaultDirectory，
|
||||
在安卓和ios中defaultDirectory它可指定为缓存目录，下载目录，用户目录等等沙盒目录。
|
||||
但鸿蒙它是固定在`应用目录/rdb/自定义目录`，下，因为实际上是被固定在了`应用目录/rdb/`下.
|
||||
因此差异非常大。故，鸿蒙端defaultDirectory我将不会生效。仅在安卓和ios下生效。就算你写了我也不使用。
|
||||
|
||||
```typescript
|
||||
type SQLiteConfig = {
|
||||
password?: string; // 数据库密码
|
||||
encryption?: boolean; // 是否启用加密
|
||||
defaultDirectory?: string; // 数据库文件存储目录,鸿蒙不支持，它的目录是固定的加密区目录，无法像安卓,ios那样保存到其它目录：比如用户目录，缓存目录等。
|
||||
locateFile?: (filename: string) => string; // 自定义文件位置，web专用属性，默认内置
|
||||
}
|
||||
```
|
||||
|
||||
### SQLiteResult 返回结果
|
||||
```typescript
|
||||
type SQLiteResult = {
|
||||
rows?: any[][]; // 查询结果行数据
|
||||
columns?: string[]; // 列名
|
||||
maps?: any[]; // 查询结果对象数组，可通过列名访问数据
|
||||
changes?: number; // 影响的行数
|
||||
lastInsertRowid?: number; // 最后插入的行ID
|
||||
error?: string; // 错误信息
|
||||
}
|
||||
```
|
||||
|
||||
### SQLiteExecuteBatchParams 批量执行参数
|
||||
```typescript
|
||||
type SQLiteExecuteBatchParams = {
|
||||
sql: string; // SQL语句
|
||||
params?: any[]; // 参数列表
|
||||
}
|
||||
```
|
||||
|
||||
## API 说明
|
||||
|
||||
### 创建数据库
|
||||
```javascript
|
||||
createDb(filename?: string): boolean
|
||||
// web端是Promise函数,执行时可以await createDb
|
||||
// app是同步操作,不是Promise
|
||||
```
|
||||
创建或打开一个数据库。如果未指定文件名，默认为 "sqlite.db"。
|
||||
|
||||
### 执行SQL查询
|
||||
```javascript
|
||||
run(sql: string, params: any[] = []): SQLiteResult
|
||||
```
|
||||
执行一条SQL语句，支持参数绑定。
|
||||
|
||||
### 查询数据
|
||||
```javascript
|
||||
query(sql: string, params: any[] = []): SQLiteResult
|
||||
```
|
||||
执行查询语句并返回结果集。
|
||||
|
||||
### 插入数据
|
||||
```javascript
|
||||
insert(table: string, data: object): SQLiteResult
|
||||
```
|
||||
向指定表插入数据。
|
||||
|
||||
### 更新数据
|
||||
```javascript
|
||||
update(table: string, data: object, where: string, params: any[] = []): SQLiteResult
|
||||
```
|
||||
更新表中的数据。
|
||||
|
||||
### 删除数据
|
||||
```javascript
|
||||
delete(table: string, where: string, params: any[] = []): SQLiteResult
|
||||
```
|
||||
删除表中的数据。
|
||||
|
||||
### 事务处理
|
||||
```javascript
|
||||
beginTransaction(): SQLiteResult // 开始事务
|
||||
commit(): SQLiteResult // 提交事务
|
||||
rollback(): SQLiteResult // 回滚事务
|
||||
```
|
||||
|
||||
### 批量执行
|
||||
```javascript
|
||||
executeBatch(statements: SQLiteExecuteBatchParams[]): SQLiteResult[]
|
||||
```
|
||||
批量执行SQL语句，支持事务。
|
||||
|
||||
### 数据库文件管理
|
||||
|
||||
**createDb,loadFromBuffer,loadLocal三个函数**
|
||||
**web端是Promise函数**
|
||||
**app是同步操作,不是Promise**
|
||||
|
||||
```javascript
|
||||
createDb(filename?: string): boolean // 创建一个本地数据库,重命的重复创建不会覆盖,只是读取已有的数据库.
|
||||
saveLocal(filename?: string): SQLiteResult // 保存数据库到本地
|
||||
loadLocal(filename: string): SQLiteResult // 从本地加载数据库
|
||||
getDatabasePath(): string | null // app端获取数据库备份临时文件路径
|
||||
getDatabasePath(): Uint8Array | null // web端返回的是二进制数据
|
||||
loadFromBuffer(buffer: Uint8Array):void // web端专用函数,用来从进制制数据加载远程数据库
|
||||
setDefaultDirectory(directory: string): void // 设置数据库文件存储目录
|
||||
setPassword(password: string|null): void // 设置数据库密码，null或空值表示删除密码
|
||||
```
|
||||
|
||||
### 表操作
|
||||
```javascript
|
||||
tableExists(tableName: string): boolean // 检查表是否存在
|
||||
createTable(tableName: string, columns: UTSJSONObject): SQLiteResult // 创建表
|
||||
dropTable(tableName: string): SQLiteResult // 删除表
|
||||
```
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 基本操作
|
||||
```javascript
|
||||
import {xSqlite} from "@/uni_modules/x-sqlite-s"
|
||||
|
||||
// 创建数据库实例并配置
|
||||
const db = new xSqlite({
|
||||
encryption: true,
|
||||
password: "mypassword",
|
||||
defaultDirectory: "/custom/db/path"
|
||||
});
|
||||
|
||||
// 创建数据库
|
||||
db.createDb("mydb");
|
||||
|
||||
// 创建表
|
||||
db.createTable("users", {
|
||||
"id": "INTEGER PRIMARY KEY AUTOINCREMENT",
|
||||
"name": "TEXT",
|
||||
"age": "INTEGER"
|
||||
});
|
||||
|
||||
// 插入数据
|
||||
db.insert("users", {
|
||||
name: "张三",
|
||||
age: 25
|
||||
});
|
||||
|
||||
// 查询数据
|
||||
const result = db.query("SELECT * FROM users WHERE age > ?", [20]);
|
||||
console.log(result.rows); // 通过数组下标访问：[[1, "张三", 25], [2, "李四", 30]]
|
||||
console.log(result.maps); // 通过列名访问：[{"id": 1, "name": "张三", "age": 25}, {"id": 2, "name": "李四", "age": 30}]
|
||||
```
|
||||
|
||||
### 事务使用
|
||||
```javascript
|
||||
// 开始事务
|
||||
db.beginTransaction();
|
||||
|
||||
try {
|
||||
db.insert("users", { name: "李四", age: 30 });
|
||||
db.insert("users", { name: "王五", age: 35 });
|
||||
db.commit();
|
||||
} catch (e) {
|
||||
db.rollback();
|
||||
}
|
||||
```
|
||||
|
||||
### 批量操作
|
||||
```javascript
|
||||
const statements = [
|
||||
{
|
||||
sql: "INSERT INTO users (name, age) VALUES (?, ?)",
|
||||
params: ["赵六", 40]
|
||||
},
|
||||
{
|
||||
sql: "UPDATE users SET age = ? WHERE name = ?",
|
||||
params: [45, "张三"]
|
||||
}
|
||||
];
|
||||
|
||||
db.executeBatch(statements);
|
||||
```
|
||||
|
||||
### 数据库配置管理
|
||||
```javascript
|
||||
// 更改数据库存储目录
|
||||
db.setDefaultDirectory("/new/db/path");
|
||||
|
||||
// 更新数据库密码
|
||||
db.setPassword("newpassword");
|
||||
|
||||
// 移除数据库密码
|
||||
db.setPassword(null);
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
1. 在进行数据库操作前，确保已经成功创建/打开数据库
|
||||
2. 使用参数绑定来防止SQL注入
|
||||
3. 大量数据操作时建议使用事务
|
||||
4. 及时关闭不再使用的数据库连接
|
||||
5. 加密数据库需要在创建时指定密码
|
||||
Reference in New Issue
Block a user