uni-appuni-app xunicloud-db 云数据库组件完全指南属性、方法、分页与增删改查实战【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app本文基于 uni-app 开源仓库中 docs/component/unicloud-db.md 编写并结合仓库内示例页、自动化测试与数据表 Schema 进行源码级验证与扩展。unicloud-db 是一个数据库查询组件它将 clientDB 的 API 封装为组件进一步减少开发者使用所需的代码量。读者阅读本文后将能掌握该组件的全部属性配置、作用域插槽状态、组件方法loadData / loadMore / add / remove / update及参数细节并可直接在项目里复刻完整的列表查询 分页 增删改查场景。组件定位与适用场景在 uni-app x.uvue与 uni-app 跨端项目中开发者常见的数据库操作方式是直接调用uniCloud.databaseForJQL()等 clientDB API。而unicloud-db组件把这些 API 封装成了声明式组件你只需要在模板中声明collection、where、field等属性组件即可自动完成联网查询、状态管理与数据渲染配合v-slot:default作用域插槽将data、loading、hasMore、pagination、error五个状态直接暴露给视图层。这一设计带来的收益是列表页无需手写请求与 loading 逻辑模板内通过v-if即可切换加载中 / 出错 / 空数据等状态分页通过page-current、page-size与loadMore()方法协作完成天然贴合滚动加载更多的移动端列表交互增删改查通过组件方法 内置 Toast / Loading / 确认框配置完成减少样板代码。仓库中与本组件直接相关的实物包括示例页源码、自动化测试用例 以及配套数据表 unicloud-db-test.schema.json本文后续的实战章节将逐一对齐这些实现。兼容性说明组件类型为UniCloudDBElement各端最低可用版本如下| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 4.0 | 4.41 | 3.93 | 4.11 | 4.61 |个别属性/方法在不同端存在差异例如distinct去重仅微信小程序4.41支持 true 值getone、~~action~~在 Android / iOS / HarmonyOS(VDOM) 上标记为x不支持需结合下方属性表逐项核对。属性Props全解| 名称 | 类型 | 描述 | | :- | :- | :- | | id | stringstring.IDString | 唯一标识 | | v-slot:default | string | 作用域插槽暴露{data, loading, hasMore, pagination, error}| | collection | stringstring.DBCollectionString | 表名数据库集合名称 | | field | stringstring.DBFieldString | 查询字段多个字段用,分割 | | where | stringstring.JQLString | 查询条件 | | orderby | string | 排序字段及正序倒序设置 | | groupby | string | 对数据进行分组 | | group-field | string | 对数据进行分组统计 | | distinct | boolean | 是否对数据查询结果中重复的记录进行去重 | | page-data | string |add多次查询的集合replace当前查询的集合 | | page-current | number | 当前页 | | page-size | number | 每页数据数量 | | getone | boolean | 是否只返回数组第一条数据默认false。false时返回数组即便只有一条结果也需要[0]方式取值true时直接返回结果数据少一层数组 | | getcount | boolean | 是否查询总数量 | | gettree | boolean | 是否查询树状结构数据 | | startwith | string | gettree 的第一层级条件此初始条件可以省略不传 startWith 时默认从最顶级开始查询 | | limitlevel | number | gettree 查询返回的树的最大层级。超过设定层级的节点不会返回。默认 10 级最大 15最小 1 | | manual | boolean | 是否手动加载数据默认为false页面 onLoad 时自动联网加载数据 | | loadtime | string | 加载数据时机默认auto可选值auto \| onready \| manual| |action| stringstring.ClientDBActionString | 云端执行数据库查询的前或后触发某个 action 函数操作进行预处理或后处理官方推荐改用 JQL 触发器故属性已废弃标记 | | load |(data : ArrayUTSJSONObject, ended : boolean, pagination : UTSJSONObject) void| 成功回调。如联网返回结果后想修改数据再渲染界面可在此方法里修改 data | | error |(event: UniEvent) void| 失败回调 |其中id、collection、field、where、action等字符串属性在 HBuilder 中会被识别为 UTS 的特殊值域 string 类型能够获得代码提示与语法校验。这些特殊值域在 docs/uts/data-type.md 中有完整清单string.IDString代表元素全局属性id的值string.DBCollectionString代表 uniCloud 数据库集合的名称string.DBFieldString代表数据库字段名称string.JQLString代表数据库要操作的集合与要查询的字段。需要说明的是这些类型属于开发期类型运行时会被统一抹平为string。v-slot:default 作用域插槽属性| 合法值 | 描述 | | :- | :- | | data | 查询结果类型为ArrayUTSJSONObject| | loading | 查询中的状态。可根据此状态在 template 中通过 v-if 显示等待内容 | | hasMore | 是否有更多数据。可根据此状态在 template 中通过 v-if 显示没有更多数据了 | | error | 查询错误。可根据此状态在 template 中通过 v-if 显示错误内容 | | pagination | 分页属性 |pagination 分页对象| 合法值 | 描述 | | :- | :- | | current | 当前页号 | | size | 分页大小 | | count | 数据库的总数据量设置:getcounttrue时有效 |distinct 去重开关| 合法值 | 描述 | | :- | :- | | true | 去重仅微信小程序 4.41 支持 | | false | 不去重 |page-data 数据合并策略| 合法值 | 描述 | | :- | :- | | add | 多次查询的集合微信小程序 4.41、HarmonyOS 4.61 | | replace | 当前查询的集合HarmonyOS 4.61 |loadtime 加载时机| 合法值 | 描述 | | :- | :- | | auto | 页面就绪后或属性变化后加载数据默认为 auto | | onready | 页面就绪后不自动加载数据属性变化后加载。适合在 onLoad 中接收上个页面的参数作为 where 条件时 | | manual | 手动模式不自动加载数据。如果涉及到分页需要先手动修改当前页再调用加载数据 |UniCloudDBElement 组件实例通过ref可以拿到UniCloudDBElement类型的组件实例。其公开的属性与方法如下。属性值| 名称 | 类型 | 必填 | 描述 | | :- | :- | :- | :- | | dataList |ArrayUTSJSONObject| 是 | 已加载的数据 |loadData(options?: UTSJSONObject): void加载数据。当unicloud-db组件的manual属性设为true或者loadtime属性设置为manual时页面初始化时不会联网查询数据此时需要通过本方法在需要的时候手动加载数据。options 参数类型为UniCloudDBComponentLoadDataOptions| 名称 | 类型 | 必备 | 默认值 | 描述 | | :- | :- | :- | :- | :- | | clear | boolean | 否 | false | 是否清空数据 | | current | number | 否 | - | 当前第几页 | | success |(res?: UniCloudDBGetResult) void| 否 | - | 成功回调 | | fail |(err?: any) void| 否 | - | 失败回调 | | complete |() void| 否 | - | 完成回调 |UniCloudDBGetResult 返回值| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | data |ArrayUTSJSONObject| 是 | 查询到的记录列表 | | count | number | 否 | 匹配到的数据总量 | | requestId | string | 否 | 请求 id |loadMore(): void加载更多数据。在列表的加载下一页场景下使用 ref 方式访问组件方法每加载成功一次当前页 1。通常与列表的scrolltolower事件配合实现触底加载。add(value: UTSJSONObject, options?: UTSJSONObject): void新增数据。value为新增数据UTSJSONObjectoptions 类型为UniCloudDBComponentAddOptions| 名称 | 类型 | 必备 | 默认值 | 描述 | | :- | :- | :- | :- | :- | | showToast | boolean | 否 | true | 是否显示 Toast | | toastTitle | string | 否 | - | Toast 标题 | | needLoading | boolean | 否 | true | 是否需要 Loading | | loadingTitle | string | 否 | - | Loading 标题 | | success |(res?: UniCloudDBAddResult) void| 否 | - | 成功回调 | | fail |(err?: any) void| 否 | - | 失败回调 | | complete |() void| 否 | - | 完成回调 |UniCloudDBAddResult 返回值| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | id | string | 是 | 添加的记录的 id | | requestId | string | 否 | 请求 id |remove(id?: any, options?: UTSJSONObject): void移除数据。可选传id要删除的记录 id与optionsUTSJSONObject。update(id: string, value: UTSJSONObject, options?: UTSJSONObject): void更新数据。id为数据库字段的唯一标识必填value为需要修改的新数据必填options 类型为UniCloudDBComponentUpdateOptions| 名称 | 类型 | 必备 | 默认值 | 描述 | | :- | :- | :- | :- | :- | | showToast | boolean | 否 | true | 是否显示更新后 Toast | | toastTitle | string | 否 | | 更新成功后 Toast 标题 | | confirmTitle | string | 否 | - | 确认框标题 | | confirmContent | string | 否 | - | 确认框内容 | | needConfirm | boolean | 否 | true | 是否显示更新确认框 | | needLoading | boolean | 否 | true | 是否需要 Loading | | loadingTitle | string | 否 | - | Loading 标题 | | success |(res?: UniCloudDBUpdateResult) void| 否 | - | 成功回调 | | fail |(err?: any) void| 否 | - | 失败回调 | | complete |() void| 否 | - | 完成回调 |UniCloudDBUpdateResult 返回值| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | updated | number | 是 | 更新成功的记录数 | | requestId | string | 否 | 请求 id |与add/update不同remove的 options 在文档中标注为通用UTSJSONObject仓库示例中通过传入showToast: false、needConfirm: false、needLoading: false来关闭确认弹窗与转圈实现静默删除并在 success 回调中通过UniCloudDBRemoveResult取得deleted字段确认删除行数。实战列表查询、分页与增删改查仓库示例对齐仓库中 unicloud-db.uvue 就是该组件的完整可用示例其配套数据表 unicloud-db-test.schema.json 定义了title、comment、create_date等字段title、comment必填create_date由$env: now自动填充。示例核心要点通过refudbRef拿到组件实例类型标注为refUniCloudDBElement | null设置:collectioncollection、:getcounttrue与loadtimemanual即采用手动加载模式、并统计总数使用list-viewlist-itemv-for渲染data点击 ❌ 调用remove(item.getString(_id)!)底部展示{{data.length}} / {{pagination.count}}用于观察分页总数在onReady中调用get()即loadData({clear: true})完成首次加载在onPullDownRefresh中同样以clear: true重新拉取并调用uni.stopPullDownRefresh()结束下拉刷新动画。下面给出可在项目中直接使用的完整示例对齐官方示例并补充关键注释template view classcontent page-intro content本页演示 unicloud-db 云数据库组件集合查询、分页与 loadtime manual列表展示与 Add/Get 操作。/page-intro unicloud-db refudbRef v-slot:default{data, pagination, loading, error} :collectioncollection :getcounttrue loadtimemanual list-view v-ifdata.length0 reflistViewRef classlist :scroll-ytrue scrolltolowerloadMore() list-item classlist-item v-for(item, _) in data :keyitem.getString(_id) view classlist-item-fill text{{item}}/text /view view text classlist-item-remove clickremove(item.getString(_id)!)❌/text /view /list-item /list-view text classloading v-ifloadingLoading.../text view v-iferror!null{{error.errMsg}}/view view classpagination v-ifdata.length0 text classpagination-item{{data.length}} / {{pagination.count}}/text /view /unicloud-db view classbtn-group button classbtn clickadd()Add/button button classbtn clickget()Get/button /view /view /template script setup languts const db uniCloud.databaseForJQL() // Template refs const udbRef refUniCloudDBElement | null(null) const listViewRef refUniListViewElement | null(null) // Data const collection ref(unicloud-db-test) const collectionList ref([ db.collection(book).where(name 水浒传).getTemp(), ] as UTSJSONObject[]) const isTesting ref(false) const addResult ref({}) const updateResult ref({}) const removeResult ref({}) // Methods function loadMore() { udbRef.value!.loadMore() } function get() { udbRef.value!.loadData({ clear: true }) } function showError(err : any | null) { const error err as UniCloudError uni.showModal({ content: error.errMsg, showCancel: false }) } function add() { const value { title: title- Date.now(), comment: comment Date.now() } udbRef.value!.add(value, { showToast: false, success: (res : UniCloudDBAddResult) { addResult.value { id: res.id } get() }, fail: (err : any | null) { showError(err) } }) } function update(id : string) { const value { title: title- Date.now(), comment: comment Date.now() } udbRef.value!.update(id, value, { showToast: false, needLoading: true, needConfirm: false, loadingTitle: 正在更新..., success: (res : UniCloudDBUpdateResult) { updateResult.value { updated: res.updated } }, fail: (err : any | null) { showError(err) } }) } function remove(id : string) { udbRef.value!.remove(id, { showToast: false, needConfirm: false, needLoading: false, success: (res : UniCloudDBRemoveResult) { removeResult.value { deleted: res.deleted } get() }, fail: (err : any | null) { showError(err) } }) } function onQueryLoad(data : ArrayUTSJSONObject, ended : boolean, pagination : UTSJSONObject) { console.log(data, ended, pagination) } // Lifecycle onReady(() { get() }) onPullDownRefresh(() { udbRef.value!.loadData({ clear: true, success: (_ : UniCloudDBGetResult) { uni.stopPullDownRefresh() } }) }) /script style .content { flex: 1; flex-direction: column; } .list { flex: 1; flex-direction: column; } .list-item { flex-direction: row; padding: 10px; } .list-item-fill { flex: 1; } .list-item-remove { padding: 10px; } .loading { padding: 10px; text-align: center; } .pagination { flex-direction: row; background-color: #f2f2f2; } .pagination-item { margin: auto; padding: 5px 10px; } .btn-group { flex-direction: row; } .btn { flex: 1; margin: 10px; } /style关键交互链路拆解首次加载loadtimemanual阻止了自动查询onReady中调用loadData({clear: true})主动触发联网查询成功回调中可通过UniCloudDBGetResult拿到data/count/requestId分页加载更多list-view的scrolltolower事件触发loadMore()组件内部自动将当前页 1 并追加查询插槽中的pagination对象会同步更新current/size/count新增后刷新add成功后通过get()重新loadData({clear: true})保证列表即时可见新记录删除remove(_id)静默删除关闭 Toast / Loading / 确认框成功后同样调用get()刷新错误处理add/update/remove的fail回调把错误统一交给showError转换为UniCloudError后用uni.showModal展示errMsg。自动化测试佐证add → update → remove 全链路仓库中 unicloud-db.test1.js 为上述示例页编写了端到端自动化测试完整覆盖了本文介绍的组件方法调用链const PAGE_PATH /pages/unicloud-db/unicloud-db describe(unicloud-db, () { let page beforeAll(async () { page await program.reLaunch(PAGE_PATH) await page.waitFor(500) }) it(add/get/update/remove, async () { await page.callMethod(add) await page.waitFor(3000) const { $addResult } await page.data() expect($addResult[id].length 0).toBe(true) await page.callMethod(update, $addResult[id]) await page.waitFor(3000) const { $updateResult } await page.data() expect($updateResult[updated]).toBe(1) await page.callMethod(remove, $addResult[id]) await page.waitFor(3000) const { $removeResult } await page.data() expect($removeResult[deleted]).toBe(1) }) })该用例验证了三件事add成功后返回的id非空update返回的updated为 1恰好影响一条记录remove返回的deleted为 1恰好删除一条记录。这与上文 options 文档中UniCloudDBAddResult.id、UniCloudDBUpdateResult.updated、UniCloudDBRemoveResult.deleted的字段定义完全吻合是组件方法行为最直接的源码级证据。进阶查询能力与树形数据的组合使用除基础列表外unicloud-db还支持以下组合能力全部通过属性声明即可获得字段裁剪fieldtitle,comment只查询指定字段减少传输数据量条件过滤where传入 JQL 条件字符串例如wherestatus 1 type news排序orderbycreate_date desc按创建时间倒序分组统计groupby分组 group-field分组统计字段树形查询gettree开启树形数据查询配合startwith指定第一层级条件可省略默认从最顶级开始、limitlevel限制返回层级默认 10 级最大 15最小 1总数统计:getcounttrue开启后pagination.count才是有效的总数据量单条获取getone为true时直接返回结果数据省去[0]解包。注意事项与最佳实践manual 与 loadtime 的选择需要接收上个页面参数后再查询的场景优先使用loadtimeonready页面就绪后不自动加载、属性变化后加载需要完全自主控制查询时机如配合下拉刷新、按钮刷新时使用loadtimemanual并在合适的生命周期调用loadData列表数据修改若联网返回结果后想修改数据再渲染界面请在load成功回调中直接修改data数组废弃属性 action云端前后置处理请优先使用 JQL 触发器方案action属性已被废弃标记不建议新代码使用类型提示collection、field、where、id等属性在 HBuilder 中会匹配 UTS 特殊值域 string 类型详见 docs/uts/data-type.md可享受代码提示与校验运行时这些类型会统一为普通 string跨端差异distinct、getone、page-data、~~action~~等属性在部分平台不可用上线前请对照上文兼容性表逐项核对目标平台版本。相关资源组件 API 文档docs/component/unicloud-db.md示例页源码src/pages/component/unicloud-db/unicloud-db.uvue自动化测试src/pages/component/unicloud-db/unicloud-db.test1.js配套数据表 Schemasrc/uniCloud-aliyun/database/unicloud-db-test.schema.jsonUTS 特殊值域 string 类型docs/uts/data-type.mdUTSJSONObject 内置对象docs/uts/buildin-object-api/utsjsonobject.md通用组件事件类型 UniEventdocs/component/common.md【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考