docs: uni-id hx 3.5.0

docs/collocation/pages.md

@@ -17,6 +17,7 @@
 |[leftWindow](/collocation/pages?id=leftwindow)|Object|否|大屏左侧窗口|H5|
 |[topWindow](/collocation/pages?id=topwindow)|Object|否|大屏顶部窗口|H5|
 |[rightWindow](/collocation/pages?id=rightwindow)|Object|否|大屏右侧窗口|H5|
+|[uniIDRouter](/uniCloud/uni-id-summary.md?id=uni-id-router)|Object|否|自动跳转相关配置，新增于HBuilderX 3.5.0||
 
 以下是一个包含了所有配置选项的 `pages.json` ：
 

docs/uniCloud/_sidebar.md

@@ -38,7 +38,10 @@
   * [云存储API](uniCloud/storage.md)
   * [腾讯云自定义登录](uniCloud/authentication.md)
   * [腾讯云权限管理](uniCloud/policy-tcb.md)
-* [uni-id用户体系](uniCloud/uni-id.md)
+* uni-id用户体系
+  * [综述](uniCloud/uni-id-summary.md)
+  * [uni-id-common](uniCloud/uni-id-common.md)
+  * [uni-id-pages](uniCloud/uni-id-pages.md)
 * [uni一键登录](uniCloud/univerify.md)
 * [发送短信](uniCloud/send-sms.md)
 * [前端网页托管](uniCloud/hosting.md)

docs/uniCloud/client-sdk.md

@@ -7,19 +7,24 @@ uniCloud分为客户端和云端两部分，有些接口名称相同，参数也
 
 客户端API列表
 
-|API							|描述																									|
-|--								|--																										|
-|uniCloud.callFunction()		|客户端调用云函数 [详情](https://uniapp.dcloud.net.cn/uniCloud/cf-functions?id=clientcallfunction)		|
-|uniCloud.database()			|客户端访问云数据库，获取云数据库对象引用 [详情](https://uniapp.dcloud.net.cn/uniCloud/clientdb)		|
-|uniCloud.uploadFile()			|客户端直接上传文件到云存储 [详情](https://uniapp.dcloud.net.cn/uniCloud/storage?id=uploadfile)			|
-|uniCloud.getTempFileURL()		|客户端获取云存储文件的临时路径 [详情](https://uniapp.dcloud.net.cn/uniCloud/storage?id=gettempfileurl)	|
-|uniCloud.chooseAndUploadFile()	|客户端选择文件并上传 [详情](https://uniapp.dcloud.net.cn/uniCloud/storage?id=chooseanduploadfile)		|
-|uniCloud.getCurrentUserInfo()	|获取当前用户信息 [详情](#client-getcurrentuserinfo)													|
-|uniCloud.init()				|同时使用多个服务空间时初始化额外服务空间 [详情](https://uniapp.dcloud.net.cn/uniCloud/init)			|
-|uniCloud.addInterceptor()		|新增拦截器 [详情](#add-interceptor)	|
-|uniCloud.removeInterceptor()	|移除拦截器 [详情](#remove-interceptor)	|
-|uniCloud.onResponse()			|监听服务端（云函数、云对象、clientDB）响应 [详情](#on-response)	|
-|uniCloud.offResponse()			|移除监听服务端（云函数、云对象、clientDB）响应 [详情](#off-response)	|
+|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
 
@@ -251,6 +256,113 @@ 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实例的服务商

docs/uniCloud/uni-id-common.md

+uni-id-common是uni-id的公共逻辑部分。不同于旧版本uni-id，uni-id-common仅包含token校验、生成及刷新功能，而仅在用户中心有用的接口对应的实现都挪到了uni-id-co内。这样不仅减小了公共模块的体积，也简化了学习成本。
+
+一般开发者无需了解uni-id-common公共模块的API，直接使用[uni-id-pages](uniCloud/uni-id-pages.md)
+
+如果想了解uni-id-common公共模块内部实现，可以阅读本章节。
+
+## uni-id-common公共模块的API列表@api
+
+### 创建uni-id实例@create-instance
+
+用法：`uniID.createInstance(Object CreateInstanceParams);`
+
+CreateInstanceParams内可以传入云函数context，也可以传入clientInfo参数，作用和context类似。方便在云对象内获取clientInfo后直接传入，[什么是云对象？](uniCloud/cloud-obj.md)。
+
+```js
+// 云函数代码，传入context
+const uniID = require('uni-id-common')
+exports.main = async function(event,context) {
+  context.APPID = '__UNI__xxxxxxx' // 替换为当前客户端的APPID，通过客户端callFunction请求的场景可以使用context.APPID获取
+  context.PLATFORM = 'h5' // 替换为当前客户端的平台类型，通过客户端callFunction请求的场景可以使用context.PLATFORM获取
+  context.LOCALE = 'zh-Hans' // 替换为当前客户端的语言代码，通过客户端callFunction请求的场景可以使用context.LOCALE获取
+  const uniIDIns = uniID.createInstance({ // 创建uni-id实例
+    context: context,
+    // config: {} // 完整uni-id配置信息，使用config.json进行配置时无需传此参数
+  })
+  payload = await uniIDIns.checkToken(event.uniIdToken) // 后续使用uniIDIns调用相关接口
+  if (payload.code) {
+  	return payload
+  }
+  const res = await uniIDIns.updateUser({
+    uid: payload.uid,
+    nickname: 'user nickname'
+  })
+  return res
+}
+
+// 云对象代码传入clientInfo
+const uniID = require('uni-id-common')
+module.exports = {
+	_before() {
+		const clientInfo = this.getClientInfo()
+		this.uniID = uniID.createInstance({ // 创建uni-id实例，其上方法同uniID
+			clientInfo
+		})
+	},
+	login() {
+		// ...
+		// this.uniID.login()
+	}
+}
+```
+
+**为什么需要自行创建uni-id实例**
+
+默认情况下uni-id-common某些接口会自动从全局context内获取客户端的PLATFORM（平台，如：app、h5、mp-weixin）等信息。
+
+在单实例多并发的场景下可能无法正确获取（全局对象会被后面的请求覆盖，可能会导致前面一次请求使用了后面一次请求的PLATFORM信息）。因此推荐在开启云函数单实例多并发后，自行为uni-id传入context。
+
+此外云函数url化时无法获取客户端信息，也需要使用这种方式将客户端信息传入uni-id。
+
+### token校验@checktoken
+
+一个校验客户端发起请求（uniCloud.callFunction）自带的uniIdToken，获得用户的uid、token、token的过期时间、角色、权限、用户信息(uni-id-users全部字段)的API。
+
+这是非常高频且重要的API通常用于换取操作当前云函数的用户Id。
+
+#### 思考
+
+如果你并没有服务端开发经验，可能会想：为什么需要通过token去换取用户Id，而不是让客户端直接传递用户Id更方便？
+这里就涉及到安全问题，有一句话叫做：“前端传递的参数都是不可信任的”。比如：你去银行取款，柜台会要求出示你的身份证来证明你是谁，而不是你直接告诉银行柜台你是谁就管用。否则这是一个极大的安全漏洞。
+综上所述：所有服务端操作涉及账户信息相关内容，都需要使用token来获得，而不是使用前端传递的参数。
+
+用法：`uniID.checkToken(String token, Object checkTokenOptions)`
+
+**参数说明**
+
+| 字段							| 类型		| 必填	| 说明								|
+| ---							| ---		| ---	| ---								|
+| token							| String	| 是	|客户端callFunction带上的token		|
+| options						| object	| 否	|checkToken方法的选项				|
+|  |- autoRefresh| boolean	| 否	|是否需要自动判断刷新token，默认true	|
+
+**说明**
+
+- 角色内包含admin时返回的permission是一个空数组，因此判断一个用户是否有权限时应注意admin角色额外进行判断
+
+**响应参数**
+
+| 字段			| 类型				| 说明																								|
+| ---			| ---				| ---																								|
+| errCode		| Number|String|错误码，0表示成功																					|
+| message		| String			|详细信息																							|
+| uid			| String			|用户Id，校验成功之后会返回																			|
+| token			| String			|用户token快要过期时，新生成的token，只有在config内配置了`tokenExpiresThreshold`的值时才会有此行为	|
+| tokenExpired	| TimeStamp			|新token的过期时间，单位毫秒																		|
+| role			| Array				|-																									|
+| permission	| Array				|用户权限列表。																						|
+
+uni-id使用jwt生成token，jwt所生成的token包含三部分，其中存储的信息为明文信息，uni-id只根据tokenSecret来校验客户端token是否合法。
+
+
+角色权限将被缓存在token中，此举能减少或消除checkToken的查库次数（有效节省费用、减少响应时间）
+
+**注意：**
+
+- 客户端会自动查找storage内的token在callFunction时插入
+- HBuilderX 2.9.5+ 客户端允许开发者自行在callFunction时传入uniIdToken，此时不再从storage获取token
+- HBuilderX 2.8.0版本起token存储在storage内推荐使用使用蛇形`uni_id_token`，会在一段时间内兼容驼峰形式`uniIdToken`
+
+### 主动刷新token@refresh-token
+
+> 新增于uni-id 3.3.14
+
+用法：`uniID.refreshToken(Object RefreshTokenParams);`
+
+**参数说明**
+
+| 字段| 类型	| 必填| 说明	|
+| ---	| ---		| ---	| ---		|
+| token	| String| 是	|用户token|
+
+**示例**
+
+```js
+const {
+  token,
+  tokenExpired
+} = await uniID.refreshToken({
+  token: 'xxx'
+})
+```
+
+**注意**
+
+- 刷新token时会自动更新token内uid对应的角色权限
+
+### 生成token@createtoken
+
+用法：`uniID.createToken(Object CreateTokenParams)`
+
+**参数说明**
+
+| 字段		| 类型	| 必填	| 说明					|
+| ---		| ---	| ---	| ---					|
+| uid		| String| 是	|用户Id					|
+| role		| Array	| 否	|指定缓存在token内的角色|
+| permission| Array	| 否	|指定缓存在角色内的权限	|
+
+**响应参数**
+
+| 字段				| 类型	| 必填| 说明										|
+| ---					| ---		| ---	| ---											|
+| token				| String| 是	|生成的token							|
+| tokenExpired| Number| 是	|token过期时间对应的时间戳|
+
+**说明**
+
+- 创建token时如果未传角色权限会自动获取uid对应的角色权限

docs/uniCloud/uni-id.md

+本文档为uni-id旧版本文档，已不再维护。新文档请查看：[uni-id文档](uniCloud/uni-id-summary.md)，如何从旧版本升级到uni-id-pages请查看：[升级到uni-id-pages](uniCloud/uni-id-pages.md?id=m-to-co)
+
 # 需求背景
 
 99%的应用，都要开发用户注册、登录、发送短信验证码、密码加密保存、修改密码、token管理等功能，从前端到后端都需要。