# uni-clientdb
uni-clientdb组件是一个数据库查询组件,它是对uni-clientdb的js库的再封装。
前端可以以组件方式非常方便的获取uniCloud的云端数据库中的数据,并绑定在界面上进行渲染。
在传统开发中,开发者需要在前端定义data、通过request联网获取接口数据、然后赋值给data。同时后端还是写接口来查库和反馈数据。
有了uni-clientdb组件,**上述工作只需要1行代码**!写组件,设组件的属性,在组件中指定要查什么表、哪些字段、以及查询条件,就OK了!
尤其适用于列表、详情等展示类页面。开发效率可以大幅度的提升。
同时,它的查询写法也比sql语句和nosql语法更简洁、更符合js开发者的习惯。没学过sql或nosql的前端,也可以轻松掌握。
**平台差异及版本说明**
HBuilderX 2.9.5+ 暂不支持快应用
#### 属性
|属性|类型|描述|
|:-|:-|:-|
|v-slot:default||查询状态(失败、联网中)及结果(data)|
|ref|string|vue组件引用标记|
|collection|string|表名|
|field|string|查询字段,多个字段用 `,` 分割|
|where|string|查询条件,内容较多,另见文档:[详情](https://uniapp.dcloud.net.cn/uniCloud/uni-clientDB?id=jsquery)|
|orderby|string|排序字段及正序倒叙设置|
|page-current|Number|当前页|
|page-size|Number|每页数据数量|
|need-total|Boolan|是否查询总数据条数,默认 `false`,需要分页模式时指定为 `true`|
|getone|Boolean|指定查询结果是否返回数组第一条数据,默认 false。在false情况下返回的是数组,即便只有一条结果,也需要[0]的方式获取。在true下,直接返回结果数据,少一层数组。应用场景:详情页|
|action|string|云端执行数据库查询的前或后,触发某个action函数操作,进行预处理或后处理,[详情](https://uniapp.dcloud.net.cn/uniCloud/uni-clientDB?id=%e4%ba%91%e7%ab%af%e9%83%a8%e5%88%86)。场景:前端无权操作的数据,比如阅读数+1|
|manual|Boolean|是否手动加载数据,默认为 false,页面onready时自动联网加载数据。如果设为 true,则需要自行指定时机通过方法`this.$refs.udb.loadData()`来触发联网,其中的`udb`指组件的ref值|
|@load|EventHandle|成功回调。如联网返回结果后,想修改下数据再渲染界面,则在本方法里对data进行修改|
|@error|EventHandle|失败回调|
**提示:目前仅支持单表查询,后续会补充跨表查询、groupby等高级功能**
#### v-slot:default
```
```
|属性|类型|描述|
|:-|:-|:-|
|data|Array|Object|查询结果,默认值为`Array`, 当 `getone` 指定为 `true` 时,值为数组中第一条数据,类型为 `Object`,减少了一层|
|pagination|Object|分页属性|
|loading|Boolean|查询中的状态。可根据此状态,在template中通过v-if显示等待内容,如`加载中...`|
|error|Object|查询错误。可根据此状态,在template中通过v-if显示等待内容,如`加载错误`|
|options|Object|在小程序中,插槽不能访问外面的数据,需通过此参数传递, 不支持传递函数|
**提示:如果不指定分页模式, `data` 为多次查询的集合**
#### orderby
格式为 `字段名` 空格 `asc`(升序)/`desc`(降序)`,多个字段用 `,` 分割,优先级为字段顺序
示例代码
```
```
#### 事件
load事件在查询执行后、渲染前触发,一般用于查询数据的二次加工。比如查库结果不能直接渲染时,可以在load事件里先对data进行预处理。
```
@load
handleLoad(data, ended, pagination) {
// `data` 当前查询结果
// `ended` 是否有更多数据
// `pagination` 分页信息
}
```
error事件在查询报错时触发
```
@error
handleError(e) {
// {errorMessage}
}
```
#### 方法
当 uni-clientdb 组件的 manual 属性设为为 true 时,不会在页面初始化时联网查询数据,此时需要通过本方法手动加载数据
```js
this.$refs.udb.loadData() //udb为uni-clientdb组件的ref属性值
```
在列表的加载下一页场景下,使用ref方式访问组件方法,加载更多数据,每加载成功一次,当前页 +1
```js
this.$refs.udb.loadMore() //udb为uni-clientdb组件的ref属性值
```
#### 示例代码
**需要在 uniCloud 控制台对要查询的表增加 Schema 权限配置。至少配置读取权限,否则无权查询**,详情 [https://uniapp.dcloud.net.cn/uniCloud/schema](https://uniapp.dcloud.net.cn/uniCloud/schema)
比如云数据库有个user的表,里面有字段id、name,查询id=1的数据,那么写法如下:
```html
{{ data.name}}
```
模式1:上拉加载上一页。下一页的查询结果会追加合并到data里
```html
{{error.errMsg}}
{{ item.createTime }}
加载中...
```
模式2:使用分页控件,点击第二页则只显示第二页数据,第一页数据清空。data会重置为下一页的查询结果,上一页数据丢弃
```html
{{pagination}}
{{error.errMsg}}
{{ item.createTime }}
加载中...
```
组件嵌套示例,访问父组件 data
```
{{pagination}}
{{error.errMsg}}
{{ item.name }}
{{ item.createTime }}
加载中...
{{options}}
{{error.errMsg}}
{{ item.name }}
```
完整项目示例见插件市场: [https://ext.dcloud.net.cn/plugin?id=3256](https://ext.dcloud.net.cn/plugin?id=3256)
**调试小技巧**
- H5平台,开发模式下浏览器控制台输入 `unidev.clientDB.data`,可查看组件内部数据,多个组件通过索引查看 `unidev.clientDB.data[0]`
**Tips**
- 时间显示,推荐使用``组件,可以避免在 load 事件中写代码对时间进行格式处理。