# unicloud-db组件简介

<unicloud-db> 组件是一个数据库查询组件,它是对clientDB的js库的再封装。

前端通过组件方式直接获取uniCloud的云端数据库中的数据,并绑定在界面上进行渲染。

在传统开发中,开发者需要在前端定义data、通过request联网获取接口数据、然后赋值给data。同时后端还需要写接口来查库和反馈数据。

有了<unicloud-db> 组件,上述工作只需要1行代码!写组件,设组件的属性,在属性中指定要查什么表、哪些字段、以及查询条件,就OK了!

HBuilderX中敲下udb代码块,得到如下代码,然后通过collection属性指定要查询表“table1”,通过field属性指定要查询字段“field1”,并且在where属性中指定查询id为1的数据。查询结果data就可以直接渲染在界面上。

<unicloud-db v-slot:default="{data, loading, error, options}" collection="table1" field="field1" :getone="true" where="id=='1'">
  <view>
    {{ data}}
  </view>
</unicloud-db>

<unicloud-db> 组件尤其适用于列表、详情等展示类页面。开发效率可以大幅度的提升。

<unicloud-db> 组件的查询语法是jql,这是一种比sql语句和nosql语法更简洁、更符合js开发者习惯的查询语法。没学过sql或nosql的前端,也可以轻松掌握。jql详见

<unicloud-db> 组件不仅支持查询。还自带了add、remove、update方法,见下文方法章节

平台差异及版本说明

App H5 微信小程序 支付宝小程序 百度小程序 抖音小程序、飞书小程序 QQ小程序 快应用 360小程序 快手小程序 京东小程序
x

需 HBuilderX 3.0+

<unicloud-db> 由原 <uni-clientdb>插件 升级而来,从 HBuilderX 3.0 起<unicloud-db>内置到框架,与小程序基础库版本无关。

如果需要 HBuilderX3.0 以下版本使用clientDB组件,则需要从插件市场单独下载<uni-clientdb>插件,下载地址为:https://ext.dcloud.net.cn/plugin?id=3256。但仍然推荐升级HBuilderX 3.0+。

# 属性

属性 类型 描述
v-slot:default 查询状态(失败、联网中)及结果(data)
ref string vue组件引用标记
spaceInfo Object 服务空间信息,新增于HBuilderX 3.2.11。同uniCloud.init参数,参考:uniCloud.init
collection string 表名。支持输入多个表名,用 , 分割,自HBuilderX 3.2.6起也支持传入tempCollection组成的数组
field string 指定要查询的字段,多个字段用 , 分割。不写本属性,即表示查询所有字段。支持用 oldname as newname方式对返回字段重命名
where string 查询条件,对记录进行过滤。见下
orderby string 排序字段及正序倒序设置
foreign-key String 手动指定使用的关联关系,HBuilderX 3.1.10+ 详情
page-data String 分页策略选择。值为 add 代表下一页的数据追加到之前的数据中,常用于滚动到底加载下一页;值为 replace 时则替换当前data数据,常用于PC式交互,列表底部有页码分页按钮,默认值为add
page-current Number 当前页
page-size Number 每页数据数量
getcount Boolean 是否查询总数据条数,默认 false,需要分页模式时指定为 true
getone Boolean 指定查询结果是否仅返回数组第一条数据,默认 false。在false情况下返回的是数组,即便只有一条结果,也需要[0]的方式获取。在值为 true 时,直接返回结果数据,少一层数组,一般用于非列表页,比如详情页
action string 云端执行数据库查询的前或后,触发某个action函数操作,进行预处理或后处理,详情。场景:前端无权操作的数据,比如阅读数+1
manual Boolean 已过时,使用 loadtime 替代 是否手动加载数据,默认为 false,页面onready时自动联网加载数据。如果设为 true,则需要自行指定时机通过方法this.$refs.udb.loadData()来触发联网,其中的udb指组件的ref值。一般onLoad因时机太早取不到this.$refs.udb,在onReady里可以取到
gettree Boolean 是否查询树状结构数据,HBuilderX 3.0.5+ 详情
startwith String gettree的第一层级条件,此初始条件可以省略,不传startWith时默认从最顶级开始查询,HBuilderX 3.0.5+
limitlevel Number gettree查询返回的树的最大层级。超过设定层级的节点不会返回。默认10级,最大15,最小1,HBuilderX 3.0.5+
groupby String 对数据进行分组,HBuilderX 3.1.0+
group-field String 对数据进行分组统计
distinct Boolean 是否对数据查询结果中重复的记录进行去重,默认值false,HBuilderX 3.1.0+
loadtime String 加载数据时机,默认auto,可选值 auto|onready|manual,详情 HBuilderX3.1.10+
ssr-key String 详情 HBuilderX 3.4.11+
@load EventHandle 成功回调。联网返回结果后,若希望先修改下数据再渲染界面,则在本方法里对data进行修改
@error EventHandle 失败回调

TODO:暂不支持in子查询功能。后续会补充

注意:page-current/page-size 改变不重置数据(page-data="replace") 和 (loadtime="manual") 除外,collection/action/field/getcount/orderby/where 改变后清空已有数据

示例

比如云数据库有个user的表,里面有字段id、name,查询id=1的数据,那么写法如下:

注意下面示例使用了getone会返回一条对象形式的data,如不使用getone,data将会是数组形式,即多一层

<template>
  <view>
    <unicloud-db v-slot:default="{data, loading, error, options}" collection="user" field="name" :getone="true" where="id=='1'">
      <view>
          {{ data.name}}
      </view>
    </unicloud-db>
  </view>
</template>

注意:除非使用admin账户登录操作,否则需要在 uniCloud 控制台对要查询的表增加 Schema 权限配置。至少配置读取权限,否则无权在前端查询,详见 DB Schema

# v-slot:default

<unicloud-db v-slot:default="{data, pagination, loading, hasMore, error, options}"></unicloud-db>
属性 类型 描述
data Array|Object 查询结果,默认值为Array, 当 getone 指定为 true 时,值为数组中第一条数据,类型为 Object,减少了一层
pagination Object 分页属性
loading Boolean 查询中的状态。可根据此状态,在template中通过v-if显示等待内容,如<view v-if="loading">加载中...</view>
hasMore Boolean 是否有更多数据。可根据此状态,在template中通过v-if显示没有更多数据了,如<uni-load-more v-if="!hasMore" status="noMore"></uni-load-more>, <uni-load-more>详情 https://ext.dcloud.net.cn/plugin?id=29
error Object 查询错误。可根据此状态,在template中通过v-if显示等待内容,如<view v-if="error">加载错误</view>
options Object 在小程序中,插槽不能访问外面的数据,需通过此参数传递, 不支持传递函数

提示:如果不指定分页模式, data 为多次查询的集合

状态示例:

<unicloud-db v-slot:default="{data, loading, error, options}" collection="user">
	<view v-if="error">{{error.message}}</view>
	<view v-else-if="loading">正在加载...</view>
	<view v-else>
		{{data}}
	</view>
</unicloud-db>

# collection

collection有以下几种形式

单个collection字符串

<unicloud-db v-slot:default="{data, loading, error, options}" collection="user">
	<view v-if="error">{{error.message}}</view>
	<view v-else-if="loading">正在加载...</view>
	<view v-else>
		{{data}}
	</view>
</unicloud-db>

多个collection字符串拼接

用于联表查询,注意主表副表之间需要在schema内以foreignKey关联(副表支持多个)。如下示例以book作为主表,关联author表进行查询,在book表的schema内设置author_id字段指向author表

<unicloud-db v-slot:default="{data, loading, error, options}" collection="book,author">
	<view v-if="error">{{error.message}}</view>
	<view v-else-if="loading">正在加载...</view>
	<view v-else>
		{{data}}
	</view>
</unicloud-db>

多个临时表组成的数组

同样用于联表查询,但是与直接拼接多个字符串的方式不同,可以先对主表进行处理再关联。和直接使用多个表名字符串拼接相比,在主表数据量大的情况下性能有明显提升

<template>
  <unicloud-db v-slot:default="{data, loading, error, options}" :collection="colList">
    <view v-if="error">{{error.message}}</view>
    <view v-else-if="loading">正在加载...</view>
    <view v-else>
      {{data}}
    </view>
  </unicloud-db>
</template>
<script>
  const db = uniCloud.database()
  export default {
    data() {
      return {
        colList: [
          db.collection('book').where('name == "水浒传"').getTemp(),
          db.collection('author').getTemp()
        ]
      }
    },
    onReady() {},
    methods: {}
  }
</script>

# where

where中指定要查询的条件。比如只查询某个字段的值符合一定条件的记录。

组件的where属性,与clientDB的JS API是一致的,且内容较多,所以详见js API中相关jql文档:详情

但组件与js API有一个差别,就是组件的属性中若使用js中的变量,需额外注意。

例如查询uni-id-users表,字段username的值由js变量指定,有如下几种方式:

方式1. 使用模板字符串,用${}包裹变量

<template>
	<view>
		<unicloud-db collection="uni-id-users" :where="`username=='${tempstr}'`"></unicloud-db>
	</view>
</template>
<script>
	export default {
		data() {
			return {
				tempstr: '123'
			}
		}
	}
</script>

方式2. 不在属性中写,而在js中拼接字符串

<template>
	<view>
		<unicloud-db ref="udb" collection="uni-id-users" :where="sWhere" loadtime="manual"></unicloud-db>
	</view>
</template>
<script>
	export default {
		data() {
			return {
				tempstr: '123',
				sWhere: ''
			}
		}
		onLoad() {
			this.sWhere = "id=='" + this.tempstr + "'"
			// 组件上配置了 loadtime = "manual", 这里需要手动加载数据
			this.$nextTick(() => {
			  this.$refs.udb.loadData()
			})
		}
	}
</script>

多条件查询示例:

方式1. 使用模板字符串,用${}包裹变量

<template>
    <view>
        <unicloud-db ref="udb" collection="uni-id-users" where="`id==${this.tempstr} && create_time > 1613960340000`"></unicloud-db>
    </view>
</template>
<script>
    export default {
        data() {
            return {
                tempstr: '123'
            }
        }
    }
</script>

方式2. 使用js拼接字符串

<template>
	<view>
		<unicloud-db ref="udb" collection="uni-id-users" :where="sWhere" loadtime="manual"></unicloud-db>
	</view>
</template>
<script>
export default {
  data() {
    return {
      tempstr: '123',
      sWhere: ''
    }
  }
  onLoad() {
    // id = this.tempstr 且 create_time > 1613960340000
    this.sWhere = "id=='" + this.tempstr + "' && create_time > 1613960340000"

    // id = this.tempstr 或 name != null
    // this.sWhere = "id=='" + this.tempstr + "' || name != null"

    // 组件上配置了 loadtime = "manual", 这里需要手动加载数据
    this.$nextTick(() => {
      this.$refs.udb.loadData()
    })
  }
}
</script>

上述示例使用的是==比较符,如需进行模糊搜索,则使用正则表达式。插件市场提供了完整的云端一体搜索模板,搜索类页面无需自行开发,可直接使用。详见

使用正则模糊查询示例:

<template>
	<view class="content">
		<input @input="onKeyInput" placeholder="请输入搜索值" />
		<unicloud-db v-slot:default="{data, loading, error, options}" collection="goods" :where="where">
			<view v-if="error">{{error.message}}</view>
			<view v-else>

			</view>
		</unicloud-db>
	</view>
</template>

<script>
export default {
  data() {
    return {
      searchVal: ''
    }
  },
  computed: {
    where() {
      return `${new RegExp(this.searchVal, 'i')}.test(name)` // 使用计算属性得到完整where
    }
  },
  methods: {
    onKeyInput(e) {
      // 实际开发中这里应该还有防抖或者节流操作,这里不做演示
      this.searchVal = e.target.value
    }
  }
}
</script>

再次强调,where条件内容较多,组件和api用法相同,完整的where条件文档在api文档中,另见:JQL文档

# orderby

格式为 字段名 空格 asc(升序)/desc(降序),多个字段用 , 分割,优先级为字段顺序

单字段排序,示例代码

<unicloud-db orderby="createTime desc"></unicloud-db>

多字段排序,示例代码

<unicloud-db orderby="createTime1 asc,createTime2 desc"></unicloud-db>

# loadtime

类型 描述
auto String 页面就绪后或属性变化后加载数据,默认为auto
onready String 页面就绪后不自动加载数据,属性变化后加载。适合在onready中接收上个页面的参数作为where条件时。
manual String 手动模式,不自动加载数据。如果涉及到分页,需要先手动修改当前页,在调用加载数据

# 事件

  • load事件

load事件在查询执行后、渲染前触发,一般用于查询数据的二次加工。比如查库结果不能直接渲染时,可以在load事件里先对data进行预处理。

...
<unicloud-db @load="handleLoad" />
...

handleLoad(data, ended, pagination) {
  // `data` 当前查询结果
  // `ended` 是否有更多数据
  // `pagination` 分页信息 HBuilderX 3.1.5+ 支持
}

数据库里的时间一般是时间戳,不能直接渲染。虽然可以在load事件中对时间格式化,但更简单的方式是使用<uni-dateformat>组件,无需写js处理。

  • error事件

error事件在查询报错时触发,比如联网失败。

...
<unicloud-db @error="handleError" />
...

handleError(e) {
  // {message}
}

# ssr-key

发行 H5 ssr 时有效,用于保证服务器端渲染和前端加载的数据对应

默认值:根据 (页面路径 + unicloud-db 组件代码中的行号)生成的唯一值

注意:页面同时出现2个及以上 unicloud-db 组件需要配置此属性,且要保证值整个应用唯一

# 方法

# loadData

<unicloud-db> 组件的 manual 属性设为 true 时,不会在页面初始化时联网查询数据,此时需要通过本方法在需要的时候手动加载数据。

this.$refs.udb.loadData() //udb为unicloud-db组件的ref属性值

一般onLoad因时机太早取不到this.$refs.udb,在onReady里可以取到。

举例常见场景,页面pagea在url中获取参数id,然后加载数据

请求地址:/pages/pagea?id=123

pagea.vue源码:

<template>
	<view>
		<unicloud-db ref="udb" collection="table1" :where="where" v-slot:default="{data,pagination,loading,error,options}" :options="options" manual>
			{{data}}
		</unicloud-db>
	</view>
</template>
<script>
export default {
	data() {
		return {
			_id:'',
			where: ''
		}
	},
	onLoad(e) {
		const id = e.id
		if (id) {
			this._id = id
			this.where = "_id == '" + this._id + "'"
		}
		else {
			uni.showModal({
				content:"页面参数错误",
				showCancel:false
			})
		}
	},
	onReady() {
		if (this._id) {
			this.$refs.udb.loadData()
		}
	}
}
</script>

下拉刷新示例

this.$refs.udb.loadData({clear: true}, callback)

可选参数 clear: true,是否清空数据和分页信息,true表示清空,默认false

callback 是回调函数,加载数据完成后触发(即使加载失败)

<script>
	export default {
		data() {
			return {
			}
		},
		// 页面生命周期,下拉刷新后触发
		onPullDownRefresh() {
			this.$refs.udb.loadData({
				clear: true
			}, () => {
				// 停止下拉刷新
				uni.stopPullDownRefresh()
			})
		}
	}
</script>

# loadMore

在列表的加载下一页场景下,使用ref方式访问组件方法,加载更多数据,每加载成功一次,当前页 +1

this.$refs.udb.loadMore() //udb为unicloud-db组件的ref属性值

# clear

清空已加载的数据,但不会重置当前分页信息

this.$refs.udb.clear() //udb为unicloud-db组件的ref属性值

# reset

重置当前分页信息,但不会清空已加载的数据

this.$refs.udb.reset() //udb为unicloud-db组件的ref属性值

# refresh

清空并重新加载当前页面数据

this.$refs.udb.refresh() //udb为unicloud-db组件的ref属性值

# remove

语法

this.$refs.udb.remove(id, options)

udb为unicloud-db组件的ref属性值

必选参数 id

属性 类型 默认值 描述
id string|Array 传入数据库的_id

可选参数 options

属性 类型 默认值 描述
action string 云端执行数据库查询的前或后,触发某个action函数操作,进行预处理或后处理,详情。场景:前端无权操作的数据,比如阅读数+1
confirmTitle string 提示 删除确认框标题
confirmContent string 是否删除该数据 删除确认框提示
needConfirm boolean true 控制是否有弹出框,HBuilderX 3.1.5+
needLoading boolean true 是否显示Loading,HBuilderX 3.1.5+
loadingTitle string '' 显示loading的标题,HBuilderX 3.1.5+
success function 删除成功后的回调
fail function 删除失败后的回调
complete function 完成后的回调

在列表页面,如果想删除一个item,原本要做很多事:

  1. 弹出删除确认框
  2. 弹出loading
  3. 调用clientDB的js api删除云端数据
  4. 接收云端删除结果,如果成功则关闭loading
  5. 进一步删除列表的data中对应的item,自动刷新页面

为减少重复开发,unicloud-db组件提供了remove方法,在列表渲染时绑定好index,直接调用remove方法即可一行代码完成上述5步。

首先在列表生成的时候给删除按钮绑定好id:

<unicloud-db ref="udb" :collection="collectionName" v-slot:default="{data,pagination,loading,error}">
	<uni-table :loading="loading" :emptyText="error.message || '没有更多数据'" border stripe >
		<uni-tr>
			<uni-th>用户名</uni-th>
			<uni-th>操作</uni-th>
		</uni-tr>
		<uni-tr v-for="(item,index) in data" :key="index">
			<uni-th>{{item.username}}</uni-th>
			<uni-td>
				<view>
					<button @click="confirmDelete(item._id)" type="warn">删除</button>
				</view>
			</uni-td>
		</uni-tr>
	</uni-table>
</unicloud-db>

然后confirmDelete方法里面只有一行代码:

confirmDelete(id) {
	this.$refs.udb.remove(id)
}

clientDB组件的remove方法的参数只支持传入数据库的_id进行删除,不支持其他where条件删除。

参数传入的_id支持单个,也支持多个,即可以批量删除。多个id的格式是:

this.$refs.udb.remove(["5f921826cf447a000151b16d", "5f9dee1ff10d2400016f01a4"])

在uniCloud的web控制台的DB Schema界面,可自助生成数据表的admin管理插件,其中有多行数据批选批删示例。

完整实例,第二个是可选参数。

var ids = ["5f921826cf447a000151b16d", "5f9dee1ff10d2400016f01a4"]
this.$refs.udb.remove(ids, {
  action: '', // 删除前后的动作
  confirmTitle: '提示', // 确认框标题
  confirmContent: '是否删除该数据',  // 确认框内容
  success: (res) => { // 删除成功后的回调
    const { code, message } = res
  },
  fail: (err) => { // 删除失败后的回调
    const { message } = err
  },
  complete: () => { // 完成后的回调
  }
})

# add

语法

this.$refs.udb.add(value, options)

udb为unicloud-db组件的ref属性值

必选参数 value

属性 类型 默认值 描述
value Object 新增数据

可选参数 options

属性 类型 默认值 描述
action string 云端执行数据库查询的前或后,触发某个action函数操作,进行预处理或后处理,详情。HBuilder 3.1.0+
showToast boolean true 是否显示更新成功后的提示框
toastTitle string 新增成功 新增成功后的toast提示
needLoading boolean true 是否显示Loading,HBuilderX 3.1.5+
loadingTitle string '' 显示loading的标题,HBuilderX 3.1.5+
success function 新增成功后的回调
fail function 新增失败后的回调
complete function 完成后的回调
<unicloud-db ref="udb" :collection="collectionName" v-slot:default="{data,pagination,loading,error}">
</unicloud-db>
this.$refs.udb.add(value)

完整实例

this.$refs.udb.add(value, {
  toastTitle: '新增成功', // toast提示语
  success: (res) => { // 新增成功后的回调
    const { code, message } = res
  },
  fail: (err) => { // 新增失败后的回调
    const { message } = err
  },
  complete: () => { // 完成后的回调
  }
})

# update

语法

this.$refs.udb.update(id, value, options)

udb为unicloud-db组件的ref属性值

必选参数 id

属性 类型 默认值 描述
id string 数据的唯一标识

必选参数 value

属性 类型 默认值 描述
value Object 需要修改的新数据

可选参数 options

属性 类型 默认值 描述
action string 云端执行数据库查询的前或后,触发某个action函数操作,进行预处理或后处理,详情。HBuilder 3.1.0+
showToast boolean true 是否显示更新成功后的提示框
toastTitle string 修改成功 修改成功后的toast提示
needConfirm boolean true 控制是否有更新确认弹出框,HBuilderX 3.1.5+
confirmTitle string true 更新确认弹出框标题,HBuilderX 3.1.5+
confirmContent string true 更新确认弹出框内容,HBuilderX 3.1.5+
needLoading boolean true 是否显示Loading,HBuilderX 3.1.5+
loadingTitle string '' 显示loading的标题,HBuilderX 3.1.5+
success function 更新成功后的回调
fail function 更新失败后的回调
complete function 完成后的回调

使用unicloud-db组件的update方法,除了更新云数据库中的数据外,也会同时更新当前页面的unicloud-db组件中的data数据,自然也会自动差量更新页面渲染的内容。同时update方法还封装了修改成功的toast提示。

<unicloud-db ref="udb" :collection="collectionName" v-slot:default="{data,pagination,loading,error}" :getone="true">
</unicloud-db>

第一个参数 id 是数据的唯一标识,第二个参数 value 是需要修改的新数据

this.$refs.udb.update(id, value)

完整实例,第三个是可选参数

this.$refs.udb.update(id, value, {
  toastTitle: '修改成功', // toast提示语
  success: (res) => { // 更新成功后的回调
    const { code, message } = res
  },
  fail: (err) => { // 更新失败后的回调
    const { message } = err
  },
  complete: () => { // 完成后的回调
  }
})

注意:

  • 如果列表分页采取分页组件,即page-data值为replace,每页有固定数量,那么clientDB组件的remove方法删除数据后,会重新请求当前页面数据。
  • 如果列表采取滚动加载方式,即page-data值为add,滚动加载下一页数据,那么clientDB组件的remove方法删除数据后,不会重新请求数据,而是从已有数据移除已删除项。(组件版本1.1.0+支持)

# dataList

在js中,获取<unicloud-db> 组件的data的方法如下:

console.log(this.$refs.udb.dataList);

如果修改了dataList的值,组件渲染的界面也会同步变化。

但是在浏览器控制台里无法使用this来打印查看数据,为此特别新增了unidev.clientDB.data方法以优化调试体验。

H5平台,开发模式下浏览器控制台输入 unidev.clientDB.data,可查看组件内部数据,多个组件通过索引查看 unidev.clientDB.data[0]

# 联表查询

联表查询有以下两种写法,对于数据量稍大的表推荐使用多个临时表组成的数组作为collection,可以在主表的getTemp内先进行过滤减小联表时的性能消耗。

更多关于联表查询的内容请参考:JQL联表查询

多个collection字符串拼接

用于联表查询,注意主表副表之间需要在schema内以foreignKey关联(副表支持多个)。如下示例以book作为主表,关联author表进行查询,在book表的schema内设置author_id字段指向author表

<unicloud-db v-slot:default="{data, loading, error, options}" collection="book,author">
	<view v-if="error">{{error.message}}</view>
	<view v-else-if="loading">正在加载...</view>
	<view v-else>
		{{data}}
	</view>
</unicloud-db>

多个临时表组成的数组

同样用于联表查询,但是与直接拼接多个字符串的方式不同,可以先对主表进行处理再关联。和直接使用多个表名字符串拼接相比,在主表数据量大的情况下性能有明显提升

<template>
  <unicloud-db v-slot:default="{data, loading, error, options}" :collection="colList">
    <view v-if="error">{{error.message}}</view>
    <view v-else-if="loading">正在加载...</view>
    <view v-else>
      {{data}}
    </view>
  </unicloud-db>
</template>
<script>
  const db = uniCloud.database()
  export default {
    data() {
      return {
        colList: [
          db.collection('book').where('name == "水浒传"').getTemp(),
          db.collection('author').getTemp()
        ]
      }
    },
    onReady() {},
    methods: {}
  }
</script>

# 列表分页

unicloud-db组件简化了列表分页的写法,只需简单的配置每页需要多少数据(默认是20条),不管是数据库的分页查询还是前端的列表分页展示,都自动封装了。

列表分页有2种模式,一种是手机上常见的拉到底部加载下一页,另一种是pc常见的底部列出页码,点击页码跳转页面。

  • 列表分页模式1:拉到底部加载下一页。此时下一页的查询结果会追加合并到data里,列表一直在增长。

下面的示例代码没有使用uList组件,实际开发时建议使用uList组件来避免长列表的性能问题。

<template>
  <view class="content">
    <unicloud-db ref="udb" v-slot:default="{data, pagination, loading, error, options}"
      :options="options"
      collection="table1"
      orderby="createTime desc"
      field="name,subType,createTime"
      :getone="false"
      :action="action"
      :where="where"
      @load="onqueryload" @error="onqueryerror">
      <view v-if="error" class="error">{{error.message}}</view>
      <view v-else class="list">
        <view v-for="(item, index) in data" :key="index" class="list-item">
		      {{item.name}}
          <!-- 使用日期格式化组件,详情见插件 https://ext.dcloud.net.cn/search?q=date-format -->
          <uni-dateformat :date="item.createTime" />
        </view>
      </view>
      <view v-if="loading" class="loading">加载中...</view>
    </unicloud-db>
  </view>
</template>

<script>
  export default {
    data() {
      return {
        options: {}, // 插槽不能访问外面的数据,通过此参数传递, 不支持传递函数
        action: '',
        where: {} // 类型为对象或字符串
      }
    },
    onPullDownRefresh() { //下拉刷新
      this.$refs.udb.loadData({
        clear: true //可选参数,是否清空数据
      }, () => {
        uni.stopPullDownRefresh()
      })
    },
    onReachBottom() { //滚动到底翻页
      this.$refs.udb.loadMore()
    },
    methods: {
      onqueryload(data, ended) {
		    // 可在此处预处理数据,然后再渲染界面
      },
      onqueryerror(e) {
        // 加载数据失败
      }
    }
  }
</script>

<style>
  .content {
    display: flex;
    flex-direction: column;
    background-color: #f0f0f0;
  }

  .list-item {
    background-color: #fff;
    margin-bottom: 1px;
    padding: 30px 15px;
  }

  .loading {
    padding: 20px;
    text-align: center;
  }

  .error {
    color: #DD524D;
  }
</style>

  • 列表分页模式2:使用分页控件,点击第二页则只显示第二页数据,第一页数据清空。data会重置为下一页的查询结果,上一页数据丢弃
<template>
  <view class="content">
    <unicloud-db ref="udb" v-slot:default="{data, pagination, loading, error, options}"
      :options="options"
      collection="table1"
      orderby="createTime desc"
      field="name,subType,createTime"
      :getcount="true"
      @load="onqueryload" @error="onqueryerror">
      <view>{{pagination}}</view>
      <view v-if="error" class="error">{{error.errMsg}}</view>
      <view v-else class="list">
        <view v-for="(item, index) in data" :key="index" class="list-item">
		  {{item.name}}
          <!-- 使用日期格式化组件,详情见插件 https://ext.dcloud.net.cn/search?q=date-format -->
          <uni-dateformat :date="item.createTime" />
        </view>
      </view>
      <view class="loading" v-if="loading">加载中...</view>
      <!-- 分页组件 -->
      <uni-pagination show-icon :page-size="pagination.size" :total="pagination.count" @change="onpagination" />
    </unicloud-db>
  </view>
</template>

<script>
  export default {
    data() {
      return {
        options: {}, // 插槽不能访问外面的数据,通过此参数传递, 不支持传递函数
      }
    },
    onPullDownRefresh() { //下拉刷新(一般此场景下不使用下拉刷新)
      this.$refs.udb.loadData({
        clear: true
      }, () => {
        uni.stopPullDownRefresh()
      })
    },
    methods: {
      onqueryload(data, ended) {
		// 可在此处预处理数据,然后再渲染界面
      },
      onqueryerror(e) {
        // 加载数据失败
      },
      onpagination(e) {
        this.$refs.udb.loadData({
          current: e.current
        })
      }
    }
  }
</script>

<style>
  .content {
    display: flex;
    flex-direction: column;
    background-color: #f0f0f0;
  }

  .list-item {
    background-color: #fff;
    margin-bottom: 1px;
    padding: 30px 15px;
  }

  .loading {
    padding: 20px;
    text-align: center;
  }

  .error {
    color: #DD524D;
  }
</style>

使用分页控件,常见于PC端。在uniCloud Admin中,有完整的分页展示数据、新增删除数据的示例代码。

# 组件嵌套

<unicloud-db> 组件支持嵌套。

子组件中访问父组件 data 时,需options传递数据

如下示例演示了2个组件的嵌套,以及在子组件中如何访问父组件 data

<unicloud-db v-slot:default="{data, loading, error, options}" :options="options" collection="table1"
    orderby="createTime desc" field="name,createTime">
    <view v-if="error" class="error">{{error.errMsg}}</view>
    <view v-else class="list">
      <!-- table1 返回的数据 -->
      <view v-for="(item, index) in options" :key="index" class="list-item">
        {{ item.name }}
      </view>
    </view>
    <!-- 嵌套 -->
    <!-- :options="data",将 父组件返回的 data 通过 options 传递到组件,子组件通过 options 访问 -->
    <unicloud-db ref="dataQuery1" v-slot:default="{loading, data, error, options}" :options="data" collection="table2"
      orderby="createTime desc" field="name,createTime" @load="onqueryload" @error="onqueryerror">
      <!-- 父组件 table1 返回的数据 -->
      <view v-for="(item, index) in options" :key="index" class="list-item">
        {{ item.name }}
      </view>
      <!-- 子组件 table2 返回的数据 -->
      <view v-for="(item, index) in data" :key="index" class="list-item">
        {{ item.name }}
      </view>
    </unicloud-db>
  </unicloud-db>

完整项目示例见插件市场的示例项目: https://ext.dcloud.net.cn/plugin?id=2574

调试小技巧

  • H5平台,开发模式下浏览器控制台输入 unidev.clientDB.data,可查看组件内部数据,多个组件通过索引查看 unidev.clientDB.data[0]