::: sourceCode ## unicloud-db > issues: https://issues.dcloud.net.cn/?mid=component.unicloud.unicloud-db ::: > 组件类型:[UniCloudDBElement](#uniclouddbelement) 是一个数据库查询组件,它将clientDB的API封装为组件,进一步减少开发者使用所需的代码量。 ### 兼容性 Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 ### 属性 | 名称 | 类型 | 兼容性 | 描述 | | :- | :- | :-: | :- | | id | string([string.IDString](/uts/data-type.md#ide-string)) | Web: -; 微信小程序: -; 支付宝小程序: 5.31; Android: -; iOS: -; HarmonyOS: 4.61 | 唯一标识 | | v-slot:default | string | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | {data, loading, hasMore, pagination, error} | | collection | string([string.DBCollectionString](/uts/data-type.md#ide-string)) | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 表名 | | field | string([string.DBFieldString](/uts/data-type.md#ide-string)) | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 查询字段,多个字段用 `,` 分割 | | where | string([string.JQLString](/uts/data-type.md#ide-string)) | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 查询条件 | | orderby | string | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 排序字段及正序倒序设置 | | groupby | string | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 对数据进行分组 | | group-field | string | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 对数据进行分组统计 | | distinct | boolean | Web: 4.0; 微信小程序: -; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11 | 是否对数据查询结果中重复的记录进行去重 | | page-data | string | Web: 4.0; 微信小程序: -; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | add 多次查询的集合, replace 当前查询的集合 | | page-current | number | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 当前页 | | page-size | number | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 每页数据数量 | | getone | boolean | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: x; iOS: x; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.0 | 指定查询结果是否返回数组第一条数据,默认 false。在false情况下返回的是数组,即便只有一条结果,也需要\[0]的方式获取。在true下,直接返回结果数据,少一层数组 | | getcount | boolean | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 是否查询总数量 | | gettree | boolean | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 是否查询树状结构数据 | | startwith | string | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | gettree的第一层级条件,此初始条件可以省略,不传startWith时默认从最顶级开始查询 | | limitlevel | number | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | gettree查询返回的树的最大层级。超过设定层级的节点不会返回。默认10级,最大15,最小1 | | manual | boolean | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 是否手动加载数据,默认为 false,页面onLoad时自动联网加载数据 | | loadtime | string | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 加载数据时机,默认auto,可选值 auto\|onready\|manual | | @load | (data : Array\, ended : boolean, pagination : [UTSJSONObject](/uts/buildin-object-api/utsjsonobject.md)) => void | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 成功回调。如联网返回结果后,想修改下数据再渲染界面,则在本方法里对data进行修改 | | @error | (event: [UniEvent](/component/common.md#unievent)) => void | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 失败回调 | | ~~action~~ | string([string.ClientDBActionString](/uts/data-type.md#ide-string)) | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: x; iOS: x; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.0 | 云端执行数据库查询的前或后,触发某个action函数操作,进行预处理或后处理(推荐改用JQL触发器) | #### v-slot:default 的属性描述 | 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | data | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 查询结果,类型为Array\ | | loading | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 查询中的状态。可根据此状态,在template中通过v-if显示等待内容 | | hasMore | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 是否有更多数据。可根据此状态,在template中通过v-if显示没有更多数据了 | | error | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 查询错误。可根据此状态,在template中通过v-if显示等待内容 | | pagination | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 分页属性 | ##### pagination 的属性描述 | 合法值 | 描述 | | :- | :- | | current | 当前页号 | | size | 分页大小 | | count | 数据库的总数据量, 设置 :getcount=true 时有效 | #### distinct 的属性描述 | 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | true | Web: -; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: -; iOS: -; HarmonyOS: - | 去重 | | false | Web: -; 微信小程序: -; 支付宝小程序: 5.31; Android: -; iOS: -; HarmonyOS: - | 不去重 | #### page-data 的属性描述 | 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | add | Web: -; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: -; iOS: -; HarmonyOS: 4.61 | 多次查询的集合 | | replace | Web: -; 微信小程序: -; 支付宝小程序: 5.31; Android: -; iOS: -; HarmonyOS: 4.61 | 当前查询的集合 | #### loadtime 的属性描述 | 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | auto | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 页面就绪后或属性变化后加载数据,默认为auto | | onready | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 页面就绪后不自动加载数据,属性变化后加载。适合在onLoad中接收上个页面的参数作为where条件时 | | manual | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61 | 手动模式,不自动加载数据。如果涉及到分页,需要先手动修改当前页,在调用加载数据 | ### UniCloudDBElement #### UniCloudDBElement 的属性值 | 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | dataList | Array\ | 是 | 已加载的数据 | #### UniCloudDBElement 的方法 ##### loadData(options?: UTSJSONObject): void @loaddata 加载数据 当 \ 组件的 manual 属性设为 true 或者 loadtime 属性设置为 manual 时,不会在页面初始化时联网查询数据,此时需要通过本方法在需要的时候手动加载数据。 ##### 参数 | 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | options | **UniCloudDBComponentLoadDataOptions** | 否 | 可选参数 | #### options 的属性描述 | 名称 | 类型 | 必备 | 默认值 | 描述 | | :- | :- | :- | :- | :- | | clear | boolean | 否 | false | 是否清空数据 | | current | number | 否 | | 当前第几页 | | success | (res?: [UniCloudDBGetResult](#uniclouddbgetresult-values)) => void | 否 | | 成功回调 | | fail | (err?: any) => void | 否 | | 失败回调 | | complete | () => void | 否 | | 完成回调 | ###### UniCloudDBGetResult 的属性值 @uniclouddbgetresult-values | 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | data | Array<[UTSJSONObject](/uts/buildin-object-api/utsjsonobject.md)> | 是 | 添加的记录的id列表 | | count | number | 否 | 匹配到的数据总量 | | requestId | string | 否 | 请求id | ##### loadMore(): void @loadmore 加载更多数据 在列表的加载下一页场景下,使用ref方式访问组件方法,加载更多数据,每加载成功一次,当前页 +1 ##### add(value: UTSJSONObject, options?: UTSJSONObject): void @add 新增数据 ##### 参数 | 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | value | [UTSJSONObject](/uts/buildin-object-api/utsjsonobject.md) | 是 | 新增数据. | | options | **UniCloudDBComponentAddOptions** | 否 | 可选参数 | #### options 的属性描述 | 名称 | 类型 | 必备 | 默认值 | 描述 | | :- | :- | :- | :- | :- | | showToast | boolean | 否 | true | 是否显示 Toast | | toastTitle | string | 否 | | Toast 标题 | | needLoading | boolean | 否 | true | 是否需要 Loading | | loadingTitle | string | 否 | | Loading 标题 | | success | (res?: [UniCloudDBAddResult](#uniclouddbaddresult-values)) => void | 否 | | 成功回调 | | fail | (err?: any) => void | 否 | | 失败回调 | | complete | () => void | 否 | | 完成回调 | ###### UniCloudDBAddResult 的属性值 @uniclouddbaddresult-values | 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | id | string | 是 | 添加的记录的id | | requestId | string | 否 | 请求id | ##### remove(): void @remove 移除数据 ##### remove(id?: any, options?: UTSJSONObject): void @remove ##### 参数 | 名称 | 类型 | 必填 | | :- | :- | :- | | id | any | 否 | | options | [UTSJSONObject](/uts/buildin-object-api/utsjsonobject.md) | 否 | ##### update(id: string, value: UTSJSONObject, options?: UTSJSONObject): void @update 更新数据 ##### 参数 | 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | id | string | 是 | 数据库字段的唯一标识. | | value | [UTSJSONObject](/uts/buildin-object-api/utsjsonobject.md) | 是 | 需要修改的新数据. | | options | **UniCloudDBComponentUpdateOptions** | 否 | 可选参数 | #### options 的属性描述 | 名称 | 类型 | 必备 | 默认值 | 描述 | | :- | :- | :- | :- | :- | | showToast | boolean | 否 | true | 是否显示更新后 Toast | | toastTitle | string | 否 | "" | 更新成功后 Toast 标题 | | confirmTitle | string | 否 | | 确认框标题 | | confirmContent | string | 否 | | 确认框内容 | | needConfirm | boolean | 否 | true | 是否显示更新确认框 | | needLoading | boolean | 否 | true | 是否需要 Loading | | loadingTitle | string | 否 | | Loading 标题 | | success | (res?: [UniCloudDBUpdateResult](#uniclouddbupdateresult-values)) => void | 否 | | 成功回调 | | fail | (err?: any) => void | 否 | | 失败回调 | | complete | () => void | 否 | | 完成回调 | ###### UniCloudDBUpdateResult 的属性值 @uniclouddbupdateresult-values | 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | updated | number | 是 | 更新成功的记录数 | | requestId | string | 否 | 请求id | ### 示例 示例为[hello uni-app x alpha分支](https://gitcode.com/dcloud/hello-uni-app-x/blob/prod_alpha/pages/component/unicloud-db/unicloud-db.uvue),与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例[另见](https://gitcode.com/dcloud/hello-uni-app-x/blob/master//pages/component/unicloud-db/unicloud-db.uvue) ::: preview https://hellouniappx.dcloud.net.cn/web/#/pages/component/unicloud-db/unicloud-db > appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/component/unicloud-db/unicloud-db >示例 ```vue ``` ::: ### 参见 - [unicloud-db组件教程](https://doc.dcloud.net.cn/uniCloud/unicloud-db.html)