From 8bedd2287aa5c915e93a6a1289f7d48e20a9c874 Mon Sep 17 00:00:00 2001 From: wanganxp Date: Sun, 25 Oct 2020 10:07:35 +0800 Subject: [PATCH] Update uni-clientdb-component.md --- docs/uniCloud/uni-clientdb-component.md | 163 ++++++++++++++---------- 1 file changed, 96 insertions(+), 67 deletions(-) diff --git a/docs/uniCloud/uni-clientdb-component.md b/docs/uniCloud/uni-clientdb-component.md index c1118f0d60..37c8da991b 100644 --- a/docs/uniCloud/uni-clientdb-component.md +++ b/docs/uniCloud/uni-clientdb-component.md @@ -1,16 +1,30 @@ -# uni-clientdb +## uni-clientdb组件 -uni-clientdb组件是一个数据库查询组件，它是对uni-clientdb的js库的再封装。 +`` 组件是一个数据库查询组件，它是对`uni-clientdb`的js库的再封装。 -前端可以以组件方式非常方便的获取uniCloud的云端数据库中的数据，并绑定在界面上进行渲染。 +前端通过组件方式直接获取uniCloud的云端数据库中的数据，并绑定在界面上进行渲染。 -在传统开发中，开发者需要在前端定义data、通过request联网获取接口数据、然后赋值给data。同时后端还是写接口来查库和反馈数据。 +在传统开发中，开发者需要在前端定义data、通过request联网获取接口数据、然后赋值给data。同时后端还需要写接口来查库和反馈数据。 -有了uni-clientdb组件，**上述工作只需要1行代码**！写组件，设组件的属性，在组件中指定要查什么表、哪些字段、以及查询条件，就OK了！ +有了`` 组件，**上述工作只需要1行代码**！写组件，设组件的属性，在属性中指定要查什么表、哪些字段、以及查询条件，就OK了！ -尤其适用于列表、详情等展示类页面。开发效率可以大幅度的提升。 +如下： -同时，它的查询写法也比sql语句和nosql语法更简洁、更符合js开发者的习惯。没学过sql或nosql的前端，也可以轻松掌握。 +```html + + + {{ data.name}} + + +``` + +`` 组件尤其适用于列表、详情等展示类页面。开发效率可以大幅度的提升。 + +`` 组件的查询语法是`jql`，这是一种比sql语句和nosql语法更简洁、更符合js开发者习惯的查询语法。没学过sql或nosql的前端，也可以轻松掌握。[jql详见](https://uniapp.dcloud.net.cn/uniCloud/uni-clientDB?id=jsquery) + +`` 组件只支持查询。如果要对数据库进行新增修改删除操作，仍需使用clientDB的js API进行add、update、remove操作。 + +`` 组件没有预置到基础库，需单独下载插件到工程中。下载地址为：[https://ext.dcloud.net.cn/plugin?id=3256](https://ext.dcloud.net.cn/plugin?id=3256) **平台差异及版本说明** @@ -18,31 +32,50 @@ uni-clientdb组件是一个数据库查询组件，它是对uni-clientdb的js库 |:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:| |√（2.9.5+）|√|√|√|√|√|√|x|√| +从HBuilderX 2.9.5+ 起支持``组件，与小程序基础库版本无关。 -#### 属性 +### 属性 |属性|类型|描述| |:-|:-|:-| |v-slot:default||查询状态（失败、联网中）及结果（data）| |ref|string|vue组件引用标记| -|collection|string|表名| +|collection|string|表名。支持输入多个表名，用 `,` 分割| |field|string|查询字段，多个字段用 `,` 分割| -|where|string|查询条件，内容较多，另见文档：[详情](https://uniapp.dcloud.net.cn/uniCloud/uni-clientDB?id=jsquery)| +|where|string|查询条件，内容较多，另见`jql`文档：[详情](https://uniapp.dcloud.net.cn/uniCloud/uni-clientDB?id=jsquery)| |orderby|string|排序字段及正序倒叙设置| +|page-data|String|分页策略选择。值为 `add` 代表下一页的数据追加到之前的数据中，常用于滚动到底加载下一页；值为 `replace` 时则替换当前data数据，常用于PC式交互，列表底部有页码分页按钮| |page-current|Number|当前页| |page-size|Number|每页数据数量| -|page-data|String|`add` 多次查询的集合, `replace` 当前查询的集合| |getcount|Boolan|是否查询总数据条数，默认 `false`，需要分页模式时指定为 `true`| -|getone|Boolean|指定查询结果是否返回数组第一条数据，默认 false。在false情况下返回的是数组，即便只有一条结果，也需要[0]的方式获取。在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进行修改| +|@load|EventHandle|成功回调。联网返回结果后，若希望先修改下数据再渲染界面，则在本方法里对data进行修改| |@error|EventHandle|失败回调| -**提示：支持跨表查询，后续会补充、groupby等高级功能** +TODO：暂不支持groupby、in子查询功能。后续会补充 -#### v-slot:default +**示例** + +比如云数据库有个user的表，里面有字段id、name，查询id=1的数据，那么写法如下： +```html + + +``` + +**注意：除非使用admin账户登录操作，否则需要在 uniCloud 控制台对要查询的表增加 Schema 权限配置。至少配置读取权限，否则无权查询**，详情 [https://uniapp.dcloud.net.cn/uniCloud/schema](https://uniapp.dcloud.net.cn/uniCloud/schema) + +### v-slot:default ``` @@ -60,17 +93,20 @@ uni-clientdb组件是一个数据库查询组件，它是对uni-clientdb的js库 **提示：如果不指定分页模式， `data` 为多次查询的集合** -#### orderby +### orderby 格式为 `字段名` 空格 `asc`(升序)/`desc`(降序)`，多个字段用 `,` 分割，优先级为字段顺序 + + 示例代码 ``` ``` +### 事件 -#### 事件 +- load事件 load事件在查询执行后、渲染前触发，一般用于查询数据的二次加工。比如查库结果不能直接渲染时，可以在load事件里先对data进行预处理。 @@ -86,6 +122,10 @@ handleLoad(data, ended, pagination) { } ``` +数据库里的时间一般是时间戳，不能直接渲染。虽然可以在load事件中对时间格式化，但简单的方式是使用[``组件](https://ext.dcloud.net.cn/plugin?id=3279)，无需写js处理。 + +- error事件 + error事件在查询报错时触发 ``` html @@ -99,14 +139,17 @@ handleError(e) { ``` -#### 方法 +### 方法 -当 uni-clientdb 组件的 manual 属性设为为 true 时，不会在页面初始化时联网查询数据，此时需要通过本方法手动加载数据 +- loadData + +当 `` 组件的 manual 属性设为为 true 时，不会在页面初始化时联网查询数据，此时需要通过本方法手动加载数据 ```js this.$refs.udb.loadData() //udb为uni-clientdb组件的ref属性值 ``` +- loadMore 在列表的加载下一页场景下，使用ref方式访问组件方法，加载更多数据，每加载成功一次，当前页 +1 @@ -114,26 +157,20 @@ this.$refs.udb.loadData() //udb为uni-clientdb组件的ref属性值 this.$refs.udb.loadMore() //udb为uni-clientdb组件的ref属性值 ``` +- dataList -#### 示例代码 +在js中，可以打印`` 组件的data -**需要在 uniCloud 控制台对要查询的表增加 Schema 权限配置。至少配置读取权限，否则无权查询**，详情 [https://uniapp.dcloud.net.cn/uniCloud/schema](https://uniapp.dcloud.net.cn/uniCloud/schema) +```js +console.log(this.$refs.udb.dataList); +``` -比如云数据库有个user的表，里面有字段id、name，查询id=1的数据，那么写法如下： -```html - +但是在浏览器控制台里无法使用this来打印查看数据，为此特别新增了`unidev.clientDB.data`方法以优化调试体验。 -``` +H5平台，开发模式下浏览器控制台输入 `unidev.clientDB.data`，可查看组件内部数据，多个组件通过索引查看 `unidev.clientDB.data[0]` -跨表查询示例 + +### 联表查询 ```html // 注意 `collection` 属性需要传入所有用到的表名，用逗号分隔，主表需要放在第一位 @@ -143,17 +180,19 @@ this.$refs.udb.loadMore() //udb为uni-clientdb组件的ref属性值 - {{ data.name}} + + {{ item.name}} + ``` -跨表查询详情参考 [https://uniapp.dcloud.net.cn/uniCloud/database?id=lookup](https://uniapp.dcloud.net.cn/uniCloud/database?id=lookup) +联表查询详情参考 [https://uniapp.dcloud.net.cn/uniCloud/database?id=lookup](https://uniapp.dcloud.net.cn/uniCloud/database?id=lookup) - -模式1：上拉加载上一页。下一页的查询结果会追加合并到data里 +### 列表分页@page +- 列表分页模式1：上拉加载上一页。下一页的查询结果会追加合并到data里 ```html