client-sdk.md 10.1 KB
Newer Older
Q
qiang 已提交
1 2 3 4 5 6 7 8 9
# uniCloud客户端sdk

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


## API

客户端API列表

雪洛's avatar
雪洛 已提交
10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
|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)								|
Q
qiang 已提交
28 29 30 31 32 33 34

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

> HBuilderX 3.1.0+

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

雪洛's avatar
雪洛 已提交
35
**注意**
Q
qiang 已提交
36

雪洛's avatar
雪洛 已提交
37 38 39
- 此接口不会发送网络请求,**此接口仅仅是客户端接口,不校验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)
Q
qiang 已提交
40 41 42 43 44 45 46

用法:`uniCloud.getCurrentUserInfo()`

该方法为同步方法。

**响应参数**

雪洛's avatar
雪洛 已提交
47 48 49 50 51
| 字段			| 类型	| 说明																|
| ---				| ---		| ---																	|
| uid				| Number|当前用户uid													|
| role			| Array	|用户角色列表。admin用户返回["admin"]	|
| permission| Array	|用户权限列表。注意admin角色此数组为空|
Q
qiang 已提交
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167

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

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

**示例**
```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
})
```

雪洛's avatar
雪洛 已提交
168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258
### 监听云端响应@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)
```

雪洛's avatar
雪洛 已提交
259 260 261 262 263

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

> 新增于HBuilderX 3.5.0

雪洛's avatar
雪洛 已提交
264
用于监听客户端需要登录事件,此接口需要搭配uniIdRouter使用,参考:[uniIdRouter](uniCloud/uni-id.md?id=uni-id-router)
雪洛's avatar
雪洛 已提交
265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285

代码示例:

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

**响应格式**

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

**注意**

雪洛's avatar
雪洛 已提交
286
- 开发者自定监听onNeedLogin事件后,uniIdRouter的自动跳转登录页面功能会禁用,由开发者在`onNeedLogin`内自行处理跳转
雪洛's avatar
雪洛 已提交
287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338

### 移除需要登录事件的监听@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
}
```

**注意**

雪洛's avatar
雪洛 已提交
339
- 开发者自定监听onNeedLogin事件后,uniIdRouter的自动跳转登录页面功能会禁用,由开发者在`onNeedLogin`内自行处理跳转
雪洛's avatar
雪洛 已提交
340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365

### 移除需要登录事件的监听@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)
```

Q
qiang 已提交
366 367 368 369 370 371 372
## 属性

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

用法:`uniCloud.config.provider`

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