218 lines
6.2 KiB
Markdown
218 lines
6.2 KiB
Markdown
# 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. 加密数据库需要在创建时指定密码 |