# uniCloud客户端sdk

uniCloud分为客户端和云端两部分,有些接口名称相同,参数也相近,在此列举客户端sdk内可以使用的接口/属性,避免混淆

# API

客户端API列表

API 描述
uniCloud.importObject() 获取云对象引用以调用云对象接口 详情
uniCloud.callFunction() 客户端调用云函数 详情
uniCloud.database() 客户端访问云数据库,获取云数据库对象引用 详情
uniCloud.uploadFile() 客户端直接上传文件到云存储 详情
uniCloud.getTempFileURL() 客户端获取云存储文件的临时路径 详情
uniCloud.chooseAndUploadFile() 客户端选择文件并上传 详情
uniCloud.getCurrentUserInfo() 获取当前用户信息 详情
uniCloud.init() 同时使用多个服务空间时初始化额外服务空间 详情
uniCloud.addInterceptor() 新增拦截器 详情
uniCloud.removeInterceptor() 移除拦截器 详情
uniCloud.onResponse() 监听服务端(云函数、云对象、clientDB)响应 详情
uniCloud.offResponse() 移除监听服务端(云函数、云对象、clientDB)响应 详情
uniCloud.onNeedLogin() 监听需要登录事件 详情
uniCloud.offNeedLogin() 移除监听需要登录事件 详情
uniCloud.onRefreshToken() 监听token更新事件 详情
uniCloud.offRefreshToken() 移除监听token更新事件 详情

# 获取当前用户信息getCurrentUserInfo

HBuilderX 3.1.0+

解析客户端token获取用户信息。常用于在前端判断当前登录的用户状态和用户权限,比如根据不同的权限显示隐藏某些按钮。

注意

  • 此接口不会发送网络请求,此接口仅仅是客户端接口,不校验token的合法性以及是否过期
  • 需要搭配uni-id使用并要求客户端必须将token存储在storage内的uni_id_token
  • 如需获取role、permission需要将角色权限缓存在token内,此功能自uni-id 3.0.0其默认开启,参考:缓存角色权限

用法:uniCloud.getCurrentUserInfo()

该方法为同步方法。

响应参数

字段 类型 说明
uid Number 当前用户uid
role Array 用户角色列表。admin用户返回["admin"]
permission Array 用户权限列表。注意admin角色此数组为空
tokenExpired Number token过期时间

未能获取用户信息时返回以下结果

{
  uid: null,
  role: [],
  permission: [],
  tokenExpired: 0
}

示例

console.log(uniCloud.getCurrentUserInfo().role.indexOf('admin')>-1); // 如果是admin用户的话,打印结果为true

# 新增拦截器

新增于HBuilderX 3.1.20

接口形式:uniCloud.addInterceptor(String apiName, Object interceptorMap)

平台兼容性

阿里云 腾讯云

入参说明

字段 类型 必填 说明
apiName string 要拦截的Api名称,可选值:callFunction、database、uploadFile
interceptorMap object 要添加的拦截器

interceptorMap参数说明

参数名 类型 必填 默认值 说明 平台差异说明
invoke Function 拦截前触发
success Function 成功回调拦截
fail Function 失败回调拦截
complete Function 完成回调拦截

示例

uniCloud.addInterceptor('callFunction', {
  invoke(param) {
    // param为拦截Api的参数 例 {name: 'functionName', data: {'functionParam1': 1, 'functionParam2': 2}}
    // 此处返回错误可终止api执行
  },
  success(res) {
    // res为callFunction的返回值,此处可以对返回值进行修改
  },
  fail(err) {
    // err为callFunction抛出的错误
  },
  complete(res){
    // complete内res为上面的res或err
  }
})

# 移除拦截器

新增于HBuilderX 3.1.20

接口形式:uniCloud.removeInterceptor(String apiName, Object interceptorMap)

入参说明

字段 类型 必填 说明
apiName string 要拦截的Api名称,可选值:callFunction、database、uploadFile
interceptorMap object 要移除的拦截器,选填,不传递此参数时移除此Api所有拦截器

interceptorMap参数说明

参数名 类型 必填 默认值 说明 平台差异说明
invoke Function 拦截前触发
success Function 成功回调拦截
fail Function 失败回调拦截
complete Function 完成回调拦截

注意:

  • 要移除的拦截器内方法需和添加的方法一致才可以移除,详情见下方示例
// 错误用法,无法移除invoke拦截器
uniCloud.addInterceptor('callFunction', {
  invoke(param) {
    console.log('callFunction invoked, with param:',param)
  }
})
uniCloud.removeInterceptor('callFunction', {
  invoke(param) {
    console.log('callFunction invoked, with param:',param)
  }
})

// 正确用法
function invokeInterceptor(param) {
  console.log('callFunction invoked, with param:',param)
}
uniCloud.addInterceptor('callFunction', {
  invoke: invokeInterceptor
})
uniCloud.removeInterceptor('callFunction', {
  invoke: invokeInterceptor
})

# 监听云端响应

新增于HBuilderX 3.4.13

用于监听云函数、云对象、clientDB的请求响应

代码示例:

uniCloud.onResponse(function(event) {
	// event格式见下方说明
})

响应格式

interface OnResponseEvent {
	type: 'cloudobject' | 'cloudfunctions' | 'clientdb',
	content: {} // content同云对象方法、云函数、clientDB请求的返回结果或错误对象
}

以调用云对象方法为例

uniCloud.onResponse(function(e){
	console.log(e)
})
const todo = uniCloud.importObject('todo')
const res = await to.add('todo title', 'todo content')

上述代码中打印的e格式如下

// 成功响应
e = {
	type: 'cloudobject',
	content: { // content内容和上方代码块中的res一致
		errCode: 0
	}
}

// 失败响应
e = {
	type: 'cloudobject',
	content: {
		errCode: 'invalid-todo-title',
		errMsg: 'xxx'
	}
}

可以通过判断content内是否有真值的errCode判断是失败还是成功的响应

uniCloud.onResponse(function(e){
	if(e.content.errCode) {
		console.log('请求出错')
	}
})

# 移除云端响应的监听

新增于HBuilderX 3.4.13

用于移除onResponse添加的监听器

注意

  • 要移除的监听内方法需和添加的方法一致才可以移除,详情见下方示例
// 错误用法,无法移除监听
uniCloud.onResponse(function(e) {
	console.log(e)
})
uniCloud.offResponse(function(e) {
	console.log(e)
})

// 正确用法
function logResponse(e) {
	console.log(e)
}
uniCloud.onResponse(logResponse)
uniCloud.offResponse(logResponse)

# 监听需要登录事件

新增于HBuilderX 3.5.0

用于监听客户端需要登录事件,此接口需要搭配uniIdRouter使用,参考:uniIdRouter

代码示例:

uniCloud.onNeedLogin(function(event) {
	// event格式见下方说明
})

响应格式

interface OnNeedLoginEvent {
	errCode: number | string,
	errMsg: string,
	uniIdRedirectUrl: string // 触发onNeedLogin页面前的页面地址(包含路径和参数的完整页面地址)
}

注意

  • 开发者自定监听onNeedLogin事件后,uniIdRouter的自动跳转登录页面功能会禁用,由开发者在onNeedLogin内自行处理跳转

# 移除需要登录事件的监听

新增于HBuilderX 3.5.0

注意

  • 要移除的监听内方法需和添加的方法一致才可以移除,详情见下方示例
// 错误用法,无法移除监听
uniCloud.onNeedLogin(function(e) {
	console.log(e)
})
uniCloud.offNeedLogin(function(e) {
	console.log(e)
})

// 正确用法
function log(e) {
	console.log(e)
}
uniCloud.onNeedLogin(log)
uniCloud.offNeedLogin(log)

# 监听token刷新事件

新增于HBuilderX 3.5.0

用于监听客户端token刷新事件,包括云对象返回newToken时自动更新token及clientDB自动更新token,注意uni-id-co登录返回的token也会触发此事件

代码示例:

uniCloud.onRefreshToken(function(event) {
	// event格式见下方说明
})

响应格式

interface OnRefreshTokenEvent {
	token: string,
	tokenExpired: number
}

注意

  • 开发者自定监听onNeedLogin事件后,uniIdRouter的自动跳转登录页面功能会禁用,由开发者在onNeedLogin内自行处理跳转

# 移除需要登录事件的监听

新增于HBuilderX 3.5.0

注意

  • 要移除的监听内方法需和添加的方法一致才可以移除,详情见下方示例
// 错误用法,无法移除监听
uniCloud.onNeedLogin(function(e) {
	console.log(e)
})
uniCloud.offNeedLogin(function(e) {
	console.log(e)
})

// 正确用法
function log(e) {
	console.log(e)
}
uniCloud.onNeedLogin(log)
uniCloud.offNeedLogin(log)

# 属性

# 获取当前uniCloud实例的服务商

用法:uniCloud.config.provider

访问此属性会返回tencentaliyun分别代表腾讯云和阿里云

# 错误对象

客户端请求云端时(包括请求云函数、云对象、clientDB、云存储等)可能存在抛出错误的场景,此时会抛出uniCloud标准的错误对象(以下记为uniCloudError),uniCloudError包含以下属性

属性 类型 必备 说明
errCode string 错误码
errMsg string 错误信息
requestId string 请求Id,用于排查错误
detail object 仅云对象主动返回错误对应的响应体规范时会有此属性

另外uniCloudError对象上还有code属性和message属性,两者均不推荐使用。