# ZDbUtil
**Repository Path**: HW-Commons/ZDbUtil
## Basic Information
- **Project Name**: ZDbUtil
- **Description**: ZDbUtil是一款基于SQLite的鸿蒙数据库框架
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 4
- **Forks**: 1
- **Created**: 2025-01-10
- **Last Updated**: 2025-06-13
## Categories & Tags
**Categories**: Uncategorized
**Tags**: 数据库, Sqlite, 鸿蒙, OpenHarmony, OpenHarmony组件
## README
## 介绍
ZDbUtil是一款数据库操作工具库
- 通过注解类和字段，与数据库的表进行关联
- 支持状态管理（V1）中被@Observed装饰的类
- 支持状态管理（V2）中被@ObservedV2装饰的类
- 支持存放复杂类型的数据，通过 json 格式进行存储
## 链接
### [源码](https://gitee.com/HW-Commons/ZDbUtil)
### [示例](https://gitee.com/HW-Commons/ZDbUtil/tree/master/entry/src/main/ets)
## 效果图
## 下载安装
在每个har/hsp模块中，通过ohpm工具下载安装库：
```
ohpm install @hzw/zdb
```
## 注解
### Table
- **参数**
- `name`: 表名，默认为类名
### Id
- **参数**
- `primaryKey`: 是否主键
- `autoIncrement`: 是否自增
### Column
- **参数**:
- `name`: 列名，默认为字段名称
- `type`: 列类型，查看ColumnType
- `Integer`: 整型
- `Text`: 文本类型
- `Boolean`: 布尔类型
- `Real`: 浮点类型
- `notNull`: 是否为空
- `unique`: 是否唯一
### OneToOne
- **参数**:
- `joinTable`: 关联表的类
- `relatedIdProperty`: 关联id属性名
### ObjToJson
- **参数**:
- `cls`: 复杂对象的类信息
## 使用方法
### 定义实体类
只要添加了`@Table`注解，`@Id`注解，`@Column`注解
在初始化数据库时，会自动创建表，并添加列。
```typescript
import { Column, ColumnType, Id, ObjToJson, OneToOne, Table } from '@hzw/zdb';
// 作业本
export class StudentHomeworkBook {
// 书本名
name?: string
}
// 父亲
export class StudentFather {
// 名字
name?: string
// 父亲
@ObjToJson({ cls: StudentFather })
father?: StudentFather | undefined
}
// 分类
@Table()
export class StudentClassify {
// id
@Id({ primaryKey: true, autoIncrement: true })
@Column({ type: ColumnType.Integer })
id?: number
// 名称
@Column({ type: ColumnType.Text })
name?: string
// 创建时间
@Column({ type: ColumnType.Integer })
createTime?: number
// 更新时间
@Column({ type: ColumnType.Integer })
editTime?: number | undefined
}
// 学生
@Table()
export class StudentInfo {
// id
@Id({ primaryKey: true, autoIncrement: true })
@Column({ type: ColumnType.Integer })
id?: number | undefined
// 标题
@Column({ type: ColumnType.Text })
title?: string | undefined
// 创建时间
@Column({ type: ColumnType.Integer })
createTime?: number | undefined
// 成绩
@Column({ type: ColumnType.Real })
score?: number | undefined
// 是否管理员
@Column({ type: ColumnType.Boolean })
isManager?: boolean | undefined
// 分类id
@Column({ type: ColumnType.Integer })
classifyId?: number | undefined
// 分类
@OneToOne({ joinTable: StudentClassify, relatedIdProperty: "classifyId" })
classify?: StudentClassify | undefined
// 名下作业本
@ObjToJson({ cls: StudentHomeworkBook })
homeworkBookList?: StudentHomeworkBook[] | undefined
// 父亲
@ObjToJson({ cls: StudentFather })
father?: StudentFather | undefined
}
```
### 初始化数据库并根据被@Table注解的类创建表
```typescript
ZDbUtil.initDatabase({
context: this.context
})
```
### 创建表
如果类不被@Table注解，则需要手动
```typescript
// 定义表的数据结构
const student: StudentInfo2 = {
"id": 0,
"title": "",
"createTime": 0,
"isManager": false,
"classifyId": 0,
"score": 0.0,
"homeworkBookList": [],
"father": {
"name": "",
"father": {
"name": "",
}
}
}
// 创建表
// 第一个参数是表的数据结构
// 第二个参数是表名
// 第三个参数是id名
ZDbUtil.initTableByName(student, "Student", "id").then(() => {
promptAction.showToast({ message: "创建成功" });
})
```
### 查数据
如果查询的数据类型有被@Table注解，则通过这种方式查询数据
```typescript
ZDbUtil.querySqlBuilder(StudentClassify)
.limitAs(this.pageSize)
.offsetAs(this.page * this.pageSize)
// ...
.query()
.then((data) => {
})
```
否则通过这种方式查询数据
```typescript
// 定义表的数据结构
const student: StudentInfo2 = {
"id": 0,
"title": "",
"createTime": 0,
"isManager": false,
"classifyId": 0,
"score": 99.9,
"homeworkBookList": [],
"father": {}
}
// 定义关联表的数据结构
const classify: StudentClassify2 = {
"id": 0,
"name": "",
"createTime": 0,
"editTime": 0,
}
// 查询表
// 第一个参数是表的数据结构
// 第二个参数是表名
// 第三个参数是id名
ZDbUtil.querySqlObjBuilder(student, "Student", "id")
// 关联表
// 第一个参数是关联表的数据结构
// 第二个参数是关联表的表名
// 第三个参数是关联表的id名
// 第四个参数是与关联表关联的id字段名
// 第五个参数是存放关联表数据的字段名
.initJoinTableInfo(classify, "Classify", "id", "classifyId", "classify")
.limitAs(this.pageSize)
.offsetAs(this.page * this.pageSize)
.query()
.then((data) => {
this.list = data;
})
```
### 插入数据
data类型确定，且被@Table注解，直接插入数据
```typescript
ZDbUtil.insertOrReplace(data).then(() => {
promptAction.showToast({ message: "添加成功" });
})
```
data类型是Object，通过传入被@Table注解的类，插入数据
```typescript
// 插入数据
// 第一个参数为插入的数据
// 第二个参数为被@Table注解的类，数据将会被插入到与注解类关联的表中
ZDbUtil.insertOrReplaceByCls(data, StudentClassify).then(() => {
promptAction.showToast({ message: "添加成功" });
})
```
data类型是Object，通过传入表名插入数据
```typescript
// 插入数据到数据库
// 第一个参数是插入的数据
// 第二个参数是表名
ZDbUtil.insertOrReplaceByName(data, "Student").then(() => {
promptAction.showToast({ message: "添加成功" });
this.loadData()
})
```
### 批量插入数据
data类型确定，且被@Table注解，直接插入数据
```typescript
ZDbUtil.batchInsert(data).then(() => {
promptAction.showToast({ message: "添加成功" });
})
```
data类型是Object，通过传入被@Table注解的类，插入数据
```typescript
// 批量插入数据
// 第一个参数为插入的数据
// 第二个参数为被@Table注解的类，数据将会被插入到与注解类关联的表中
ZDbUtil.batchInsertByCls(data, StudentClassify).then(() => {
promptAction.showToast({ message: "添加成功" });
})
```
data类型是Object，通过传入表名插入数据
```typescript
// 批量插入数据到数据库
// 第一个参数是插入的数据
// 第二个参数是表名
ZDbUtil.batchInsertByName(data, "Student").then(() => {
promptAction.showToast({ message: "添加成功" });
this.loadData()
})
```
### 删除数据
data类型确定，且被@Table注解，直接删除数据
```typescript
ZDbUtil.delete(item).then(() => {
promptAction.showToast({ message: "删除成功" });
})
```
data类型是Object，通过传入被@Table注解的类，删除数据
```typescript
ZDbUtil.deleteByCls(data, StudentInfo).then(() => {
promptAction.showToast({ message: "删除成功" });
})
```
直接通过传入表名，id名，id的值删除数据
```typescript
// 第一个参数是表名
// 第二个参数是id名
// 第三个参数是id的值
ZDbUtil.deleteByName("Student", "id", item.id).then(() => {
promptAction.showToast({ message: "删除成功" });
this.loadData()
})
```
### 清空数据
根据被@Table注解的类，清空与之关联的表的所有数据
```typescript
ZDbUtil.clear(StudentInfo).then(() => {
promptAction.showToast({ message: "清空成功" });
})
```
根据表名，清空该表的所有数据
```typescript
ZDbUtil.clearByName("Classify").then(() => {
promptAction.showToast({ message: "清空成功" });
this.selectClassify = undefined
this.loadClassify()
this.loadData()
})
```
## 作者其他库
- 鸿蒙ui组件库：https://gitee.com/HW-Commons/ZUtils/tree/master
- 验证码输入组件 (CaptchaCode)：https://gitee.com/HW-Commons/ZUtils/tree/master/ui/captchaCode
- 倒计时组件 (Countdown)：https://gitee.com/HW-Commons/ZUtils/tree/master/ui/countdown
- 加载等待组件 (Loading)：https://gitee.com/HW-Commons/ZUtils/tree/master/ui/loading
- 下拉刷新组件 (Refresh)：https://gitee.com/HW-Commons/ZUtils/tree/master/ui/refresh
- 图片选择组件 (SelectImage)：https://gitee.com/HW-Commons/ZUtils/tree/master/ui/selectImage
- 鸿蒙数据库工具：https://gitee.com/HW-Commons/ZDbUtil
- 鸿蒙JSON/对象转换工具：https://gitee.com/HW-Commons/ZJson
## 联系我们
**欢迎大家提交issue、PR（可以统一收集问题，方便更多人查阅，会第一时间回复处理）** ，或进群交流(+v: _hhbin)。
