# uniCloud客户端sdk

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


## API

客户端API列表

|API							|描述																			|
|--								|--																				|
|uniCloud.importObject()		|获取云对象引用以调用云对象接口 [详情](uniCloud/cloud-obj.md)					|
|uniCloud.callFunction()		|客户端调用云函数 [详情](uniCloud/cf-functions.md?id=clientcallfunction)		|
|uniCloud.database()			|客户端访问云数据库，获取云数据库对象引用 [详情](uniCloud/clientdb.md)			|
|uniCloud.uploadFile()			|客户端直接上传文件到云存储 [详情](uniCloud/storage.md?id=uploadfile)			|
|uniCloud.getTempFileURL()		|客户端获取云存储文件的临时路径 [详情](uniCloud/storage.md?id=gettempfileurl)	|
|uniCloud.chooseAndUploadFile()	|客户端选择文件并上传 [详情](uniCloud/storage.md?id=chooseanduploadfile)		|
|uniCloud.getCurrentUserInfo()	|获取当前用户信息 [详情](#client-getcurrentuserinfo)							|
|uniCloud.init()				|同时使用多个服务空间时初始化额外服务空间 [详情](uniCloud/init.md)				|
|uniCloud.addInterceptor()		|新增拦截器 [详情](#add-interceptor)											|
|uniCloud.removeInterceptor()	|移除拦截器 [详情](#remove-interceptor)											|
|uniCloud.onResponse()			|监听服务端（云函数、云对象、clientDB）响应 [详情](#on-response)				|
|uniCloud.offResponse()			|移除监听服务端（云函数、云对象、clientDB）响应 [详情](#off-response)			|
|uniCloud.onNeedLogin()			|监听需要登录事件 [详情](#on-need-login)										|
|uniCloud.offNeedLogin()		|移除监听需要登录事件 [详情](#off-need-login)									|
|uniCloud.onRefreshToken()		|监听token更新事件 [详情](#on-refresh-token)									|
|uniCloud.offRefreshToken()		|移除监听token更新事件 [详情](#off-refresh-token)								|

### 获取当前用户信息getCurrentUserInfo@client-getcurrentuserinfo

> HBuilderX 3.1.0+

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

**注意**

- 此接口不会发送网络请求，**此接口仅仅是客户端接口，不校验token的合法性以及是否过期**
- 需要搭配uni-id使用并要求客户端必须将token存储在storage内的`uni_id_token`内
- 如需获取role、permission需要将角色权限缓存在token内，此功能自uni-id 3.0.0其默认开启，参考：[缓存角色权限](uniCloud/uni-id.md?id=cache-permission-in-token)

用法：`uniCloud.getCurrentUserInfo()`

该方法为同步方法。

**响应参数**

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

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

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

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

### 新增拦截器@add-interceptor

> 新增于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	|否		|				|完成回调拦截	|							|

示例

```js
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
  }
})
```

### 移除拦截器@remove-interceptor

> 新增于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	|否		|				|完成回调拦截	|							|

**注意：**

- 要移除的拦截器内方法需和添加的方法一致才可以移除，详情见下方示例

```js
// 错误用法，无法移除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
})
```

### 监听云端响应@on-response

> 新增于HBuilderX 3.4.13

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

代码示例：

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

**响应格式**

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

**以调用云对象方法为例**

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

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

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

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

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

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

### 移除云端响应的监听@off-response

> 新增于HBuilderX 3.4.13

用于移除onResponse添加的监听器

**注意**

- 要移除的监听内方法需和添加的方法一致才可以移除，详情见下方示例

```js
// 错误用法，无法移除监听
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)
```


### 监听需要登录事件@on-need-login

> 新增于HBuilderX 3.5.0

用于监听客户端需要登录事件，此接口需要搭配uniIdRouter使用，参考：[uniIdRouter](uniCloud/uni-id.md?id=uni-id-router)

代码示例：

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

**响应格式**

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

**注意**

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

### 移除需要登录事件的监听@off-need-login

> 新增于HBuilderX 3.5.0

**注意**

- 要移除的监听内方法需和添加的方法一致才可以移除，详情见下方示例

```js
// 错误用法，无法移除监听
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刷新事件@on-refresh-token

> 新增于HBuilderX 3.5.0

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

代码示例：

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

**响应格式**

```js
interface OnRefreshTokenEvent {
	token: string,
	tokenExpired: number
}
```

**注意**

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

### 移除需要登录事件的监听@off-need-login

> 新增于HBuilderX 3.5.0

**注意**

- 要移除的监听内方法需和添加的方法一致才可以移除，详情见下方示例

```js
// 错误用法，无法移除监听
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`

访问此属性会返回`tencent`、`aliyun`分别代表腾讯云和阿里云

## 错误对象@uni-cloud-error

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

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

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