Back to Uni App

Unicloud Db

docs/component/unicloud-db.md

2.3.317.5 KB
Original Source
<!-- ## unicloud-db -->

::: sourceCode

unicloud-db

:::

组件类型:UniCloudDBElement

是一个数据库查询组件,它将clientDB的API封装为组件,进一步减少开发者使用所需的代码量。

兼容性

Web微信小程序AndroidiOSHarmonyOSHarmonyOS(Vapor)
4.04.413.934.114.61-

属性

名称类型默认值兼容性描述
idstring(string.IDString)-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: 4.61; HarmonyOS(Vapor): -唯一标识
v-slot:defaultstring-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -{data, loading, hasMore, pagination, error}
collectionstring(string.DBCollectionString)-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -表名
fieldstring(string.DBFieldString)-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -查询字段,多个字段用 , 分割
wherestring(string.JQLString)-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -查询条件
orderbystring-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -排序字段及正序倒叙设置
groupbystring-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -对数据进行分组
group-fieldstring-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -对数据进行分组统计
distinctboolean-Web: 4.0; 微信小程序: -; Android: 3.93; iOS: 4.11; HarmonyOS: -; HarmonyOS(Vapor): -是否对数据查询结果中重复的记录进行去重
page-datastring-Web: 4.0; 微信小程序: -; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -add 多次查询的集合, replace 当前查询的集合
page-currentnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -当前页
page-sizenumber-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -每页数据数量
getoneboolean-Web: 4.0; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x; HarmonyOS(Vapor): -指定查询结果是否返回数组第一条数据,默认 false。在false情况下返回的是数组,即便只有一条结果,也需要[0]方式获取。在true下,直接返回结果数据,少一层数组
getcountboolean-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -是否查询总数量
gettreeboolean-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -是否查询树状结构数据
startwithstring-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -gettree的第一层级条件,此初始条件可以省略,不传startWith时默认从最顶级开始查询
limitlevelnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -gettree查询返回的树的最大层级。超过设定层级的节点不会返回。默认10级,最大15,最小1
manualboolean-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -是否手动加载数据,默认为 false,页面onLoad时自动联网加载数据
loadtimestring-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -加载数据时机,默认auto,可选值 auto|onready|manual
actionstring(string.ClientDBActionString)-Web: 4.0; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x; HarmonyOS(Vapor): -云端执行数据库查询的前或后,触发某个action函数操作,进行预处理或后处理(推荐改用JQL触发器)
@load(data : Array<UTSJSONObject>, ended : boolean, pagination : UTSJSONObject) => void-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -成功回调。如联网返回结果后,想修改下数据再渲染界面,则在本方法里对data进行修改
@error(event: UniEvent) => void-Web: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -失败回调

v-slot:default 的属性描述

合法值兼容性描述
dataWeb: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -查询结果,类型为Array<UTSJSONObject>
loadingWeb: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -查询中的状态。可根据此状态,在template中通过v-if显示等待内容
hasMoreWeb: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -是否有更多数据。可根据此状态,在template中通过v-if显示没有更多数据了
errorWeb: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -查询错误。可根据此状态,在template中通过v-if显示等待内容
paginationWeb: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -分页属性
pagination 的属性描述
合法值兼容性描述
current-当前页号
size-分页大小
count-数据库的总数据量, 设置 :getcount=true 时有效

distinct 的属性描述

合法值兼容性描述
trueWeb: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -; HarmonyOS(Vapor): -去重
falseWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -; HarmonyOS(Vapor): -不去重

page-data 的属性描述

合法值兼容性描述
addWeb: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: 4.61; HarmonyOS(Vapor): -多次查询的集合
replaceWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: 4.61; HarmonyOS(Vapor): -当前查询的集合

loadtime 的属性描述

合法值兼容性描述
autoWeb: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -页面就绪后或属性变化后加载数据,默认为auto
onreadyWeb: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -页面就绪后不自动加载数据,属性变化后加载。适合在onLoad中接收上个页面的参数作为where条件时
manualWeb: 4.0; 微信小程序: 4.41; Android: 3.93; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): -手动模式,不自动加载数据。如果涉及到分页,需要先手动修改当前页,在调用加载数据

UniCloudDBElement

UniCloudDBElement 的属性值

名称类型必填兼容性描述
dataListArray<UTSJSONObject>-已加载的数据

UniCloudDBElement 的方法

loadData(options?: UTSJSONObject | null): void @loaddata

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

loadData 兼容性
Web微信小程序AndroidiOSHarmonyOSHarmonyOS(Vapor)
------
参数
名称类型必填默认值兼容性描述
optionsUniCloudDBComponentLoadDataOptions--可选参数

options 的属性描述

名称类型必备默认值兼容性描述
clearbooleanfalse-是否清空数据
currentnumber--当前第几页
success(res?: T) => void--成功回调
fail(err?: any) => void--失败回调
complete() => void--完成回调
loadMore(): void @loadmore

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

loadMore 兼容性
Web微信小程序AndroidiOSHarmonyOSHarmonyOS(Vapor)
------
add(value: UTSJSONObject, options?: UTSJSONObject | null): void @add

新增数据

add 兼容性
Web微信小程序AndroidiOSHarmonyOSHarmonyOS(Vapor)
------
参数
名称类型必填默认值兼容性描述
valueUTSJSONObject--新增数据.
optionsUniCloudDBComponentAddOptions--可选参数

options 的属性描述

名称类型必备默认值兼容性描述
showToastbooleantrue-是否显示 Toast
toastTitlestring--Toast 标题
needLoadingbooleantrue-是否需要 Loading
loadingTitlestring--Loading 标题
success(res?: T) => void--成功回调
fail(err?: any) => void--失败回调
complete() => void--完成回调
remove(): void @remove

移除数据

remove 兼容性
Web微信小程序AndroidiOSHarmonyOSHarmonyOS(Vapor)
------
remove(id?: any, options?: UTSJSONObject | null): void @remove
remove 兼容性
Web微信小程序AndroidiOSHarmonyOSHarmonyOS(Vapor)
------
参数
名称类型必填默认值兼容性描述
idany---
optionsUTSJSONObject--
update(id: string, value: UTSJSONObject, options?: UTSJSONObject | null): void @update

更新数据

update 兼容性
Web微信小程序AndroidiOSHarmonyOSHarmonyOS(Vapor)
------
参数
名称类型必填默认值兼容性描述
idstring--数据库字段的唯一标识.
valueUTSJSONObject--需要修改的新数据.
optionsUniCloudDBComponentUpdateOptions--可选参数

options 的属性描述

名称类型必备默认值兼容性描述
showToastbooleantrue-是否显示更新后 Toast
toastTitlestring""-更新成功后 Toast 标题
confirmTitlestring--确认框标题
confirmContentstring--确认框内容
needConfirmbooleantrue-是否显示更新确认框
needLoadingbooleantrue-是否需要 Loading
loadingTitlestring--Loading 标题
success(res?: T) => void--成功回调
fail(err?: any) => void--失败回调
complete() => void--完成回调

示例

示例为hello uni-app x alpha分支,与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

该 API 不支持 Web,请运行 hello uni-app x 到 App 平台体验

uvue
<template>
  <view class="content">
    <unicloud-db ref="udbRef" v-slot:default="{data, pagination, loading, error}" :collection="collection" :getcount="true"
      loadtime="manual">
      <list-view v-if="data.length>0" ref="listViewRef" class="list" :scroll-y="true" @scrolltolower="loadMore()">
        <list-item class="list-item" v-for="(item, _) in data">
          <view class="list-item-fill">
            <text>{{item}}</text>
          </view>
          <view>
            <text class="list-item-remove" @click="remove(item.getString('_id')!)">❌</text>
          </view>
        </list-item>
      </list-view>
      <text class="loading" v-if="loading">Loading...</text>
      <view v-if="error!=null">{{error.errMsg}}</view>
      <view class="pagination" v-if="data.length>0">
        <text class="pagination-item">{{data.length}} / {{pagination.count}}</text>
      </view>
    </unicloud-db>
    <view class="btn-group">
      <button class="btn" @click="add()">Add</button>
      <button class="btn" @click="get()">Get</button>
    </view>
  </view>
</template>

<script setup lang="uts">

const db = uniCloud.databaseForJQL()

// Template refs
const udbRef = ref<UniCloudDBElement | null>(null)
const listViewRef = ref<UniListViewElement | 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 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
      }
    },
    fail: (err : any | null) => {
      showError(err)
    }
  })
}

function onQueryLoad(data : Array<UTSJSONObject>, ended : boolean, pagination : UTSJSONObject) {
  console.log(data, ended, pagination)
}

function showError(err : any | null) {
  const error = err as UniCloudError
  uni.showModal({
    content: error.errMsg,
    showCancel: false
  })
}

// 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>

参见