提交 64a80fbf 编写于 作者: DCloud_JSON's avatar DCloud_JSON

- 更新文档 - 修复list页面where条件中缺少&符,导致的错误

上级 036b6779
......@@ -6,9 +6,9 @@
注:视频会有滞后问题,入门为主。最新的完整功能请看以下文档
#### 简介
`uni-starter`是一个集成了大量商用项目常见功能的,云端一体应用快速开发基本项目模版。
uni-starter是一个集成了大量商用项目常见功能的,云端一体应用快速开发基本项目模版。
APP有很多通用的功能,比如登录注册、头像、设置、banner、...`uni-starter`将这些功能都已经集成好。
APP有很多通用的功能,比如登录注册、头像、设置、banner、... uni-starter将这些功能都已经集成好。
直接在`hbuilderx`新建项目选择`uni-starter`模板,即可在此基础上快速开发自己的特色业务。
......@@ -22,30 +22,33 @@ APP有很多通用的功能,比如登录注册、头像、设置、banner、..
<img src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/0625ae17-1262-45cb-a713-cdbf02df5c0a.png" style="width: 120px;">
### uni-starter集成包括:
1. 用户管理:
1. 用户管理:
- 登录注册(用户名密码登录、手机号验证码登录、APP一键登录、微信登录、Apple登录、微信小程序登录)
- 修改密码、忘记密码、头像更换(集成图片裁剪)、昵称修改、积分查看、退出登录
2. 系统设置:
2. 系统设置:
- App更新(整包升级、wgt升级、强制升级,后台搭配uniCloud admin的升级中心插件管理)
- 推送开关(app)、清除缓存(app)
- 指纹解锁(app)、人脸解锁(app)
- 多语言切换
3. 隐私权限:内置Android先弹出隐私协议对话框,然后再向用户申请设备权限
4. 权限引导:当应用拒绝授权某些权限,但在后续使用中又需要这个权限;此时实现:引导用户可“一键跳转至系统设置”中开启。而不是报错让用户自己去找解决方案(更好的用户体验)。采用高内聚低耦合的设计结构,直接在应用启动时,应用拦截器中实现。免去在每个业务代码中处理这类问题,更优雅更方便。
- 账号注销(正在完善中...)
3. 隐私权限:内置Android先弹出隐私协议对话框,然后再向用户申请设备权限
4. 权限引导:当应用拒绝授权某些权限,但在后续使用中又需要这个权限;此时实现:引导用户可“一键跳转至系统设置”中开启。
- 而不是报错让用户自己去找解决方案(更好的用户体验)。
- 采用高内聚低耦合的设计结构,直接在应用启动时,应用拦截器中实现。免去在每个业务代码中处理这类问题,更优雅更方便。
- 已实现项目:摄像头、相册、获取GPS定位、网络2/3/4/5G和Wi-Fi。你可以参考这些实现,处理更多该类场景的处理。uni-starter也会持续更新完善。
5. 实用功能
5. 实用功能
- 问题与反馈、关于、隐私政策、用户服务协议
- banner(后台搭配uniCloud admin的banner插件管理)
- 新闻的搜索、列表、详情、分享。通过clientDB实现,开发者直接修改定义的表名等参数,即可轻松改为自己的业务
- 可覆盖原生层的分享菜单
- h5版在页面顶部(全局悬浮)引导用户点击下载App
- 营销裂变:点击“分销推荐”,生成带用户inviteCode参数的应用下载页(H5),一键分享到微信或微信朋友圈等。被邀请人打开下载页面点击下载,设备剪贴板的内容会被自动设置为邀请者的inviteCode。被邀请人下载app之后通过任何方式登陆(含:注册并登陆),uni-starter框架会自动获取设备剪切板中的inviteCode提交到服务端绑定关联关系。
6. 更好的性能:首页采用nvue,fast编译模式,加快App端启动速度
7. 内置拦截器:
- 页面路由拦截,配置需强制登录的页面;打开时检测,如果token无效就自动跳转到登录页
6. 更好的性能:首页采用nvue,fast编译模式,加快App端启动速度
7. 内置拦截器:
- 页面路由拦截,配置需强制登录的页面;打开时自动检测`token`无效就自动跳转到登录页
- 调用云函数(callFunction)拦截器,自动携带必要参数、自动处理响应体。详见9.自动完成1-2
8. 自动完成:
- 分析uniCloud.callfunction和clientDB操作的响应体,判断code执行对应的操作如跳转到登陆页,自动续期token
8. 自动完成:
- 分析uniCloud.callfunction和clientDB操作的响应体,判断code执行对应的操作如跳转到登陆页,自动续期token
- 操作注册/登陆操作自动获取客户端设备:push_clientid、imei、oaid、idfa新增/更新到数据表uni-id-device
- 异常恢复处理:断网恢复后自动重连“因网络错误导致的”网络请求
- 为迎合苹果App Store的规则,登陆与分享功能项显示之前自动检测是否安装了对应客户端。比如:设备未安装微信则不显示微信快捷登陆和微信分享选项
......@@ -62,53 +65,92 @@ APP有很多通用的功能,比如登录注册、头像、设置、banner、..
<img style="width:61.8%" src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/78b3f17c-cf70-4cdf-9ada-1796753ffeac.jpg" />
<img style="width:61.8%" src="https://vkceyugu.cdn.bspapp.com/VKCEYUGU-f184e7c3-1912-41b2-b81f-435d1b37c7b4/09916d79-4753-4baa-9b95-baa831f1a873.jpg" />
### 功能模块介绍
## 功能模块介绍
### 1.登录模块
|登陆类型 |描述 |
|-- |-- |
|smsCode |验证码登录 |
|univerify |读取手机SIM卡一键登录 |
|username |账号密码登录 |
|weixin |微信登录 |
|apple |苹果登录 |
配置文件:`项目根目录/uni-starter.config.js`
```js
{
"router":{
"login":["username","smsCode"]
}
}
```
#### 启用登陆方式
如上示例配置为:`["username","smsCode"]`,表示启用:验证码登录、账号密码登录。
同理配置为:`["weixin","username","smsCode"]`则表示启用:微信登录、验证码登录、账号密码登录。
总结:需要几项列举几项即可。
#### 1.登录模块配置
- uni-start集成的登录方式有:验证码登录(smsCode)、读取手机SIM卡一键登录(univerify)、账号密码登录(username)、微信登录(weixin)、苹果登录(apple)
- 登陆项及优先级配置:在 `uni-starter.config.js`->`router`->`login`下完全列举你需要的登录方式。这里支持用[条件编译](https://uniapp.dcloud.io/platform?id=%e6%9d%a1%e4%bb%b6%e7%bc%96%e8%af%91)因此你可以配置在不同平台下拥有的登录方式。
- 优先级:
如果:配置内容为:["username","smsCode"],用户执行如下代码:
```js
uni.navigateTo({
url: "/pages/ucenter/login-page/index/index"
})
```
访问登录页面,会被拦截器自动切换到"配置的第0项(这里是`username`)的登录方式对应的页面”,即`账户登录`方式页面,路径:`/pages/ucenter/login-page/pwd-login/pwd-login`
- 生效策略:登陆方式有如上5种,你希望有几种登陆方式就在配置中列举几种。有的登陆方式可能因为设备环境问题而不被支持;比如你正确地配置了微信登陆,但是用户的手机并没有安装微信,这样微信登陆功能就无法使用,并且如果出现这种情况你的app会被iOS的App Store拒绝上架。所以在这里,我们的生效策略在检测:你是否有列举到某个配置项为前提的情况下,增加了检测当前环境是否支持,如果不支持会自动隐藏。
- 其他配置:
+ 应用模块:`manifest.json` App模块配置 --> OAuth(登录鉴权)--> 勾选并配置你所需要的模块
- 一键登录:
+ [开通配置](https://dev.dcloud.net.cn/uniLogin)
+ [使用指南](https://uniapp.dcloud.io/univerify)
- [苹果登陆集成指南](https://ask.dcloud.net.cn/article/36651)
- 短信登陆:
+ 使用本功能需要在[DCloud开发者中心](https://dev.dcloud.net.cn/uniSms)开通并充值
+ 教程参考[短信服务开通指南](https://ask.dcloud.net.cn/article/37534)
+ 修改短信注册/登陆发生验证码的模板id,在文件`/uniCloud-aliyun/cloudfunctions/uni-id-cf/index.js` 搜索 `const templateId = '11753'` 替换为自己申请的模板id
+ 服务端:uni-starter服务端使用[uni-config-center](https://ext.dcloud.net.cn/plugin?id=4425)统一管理这些配置,文件路径`/uni_modules/uni-config-center/uniCloud/cloudfunctions/common/uni-config-center/uni-id/config.json`详情下文[目录结构](#id=catalogue)[uni-id配置说明](https://uniapp.dcloud.io/uniCloud/uni-id?id=configjson%e7%9a%84%e8%af%b4%e6%98%8e)
#### 2.路由控制
uni-starter提供了仅需简单配置即可实现的路由拦截功能。
你只需要在项目根目录的框架配置文件:`uni-starter.config.js``router`->`needLogin``login`中配置完整的路由名称即可:
优先级
在uni-starter框架中执行`uni.navigateTo({url: "/pages/ucenter/login-page/index/index"})`,会根据配置跳转到相应的登陆页面。如果配置内容为:`["username","smsCode"]`会自动切换到"配置的第0项,也就是`username`类型的登录方式对应的页面”,即`账户登录`方式页面,路径:`/pages/ucenter/login-page/pwd-login/pwd-login`
#### 平台差异性配置
这里支持用[条件编译](https://uniapp.dcloud.io/platform?id=%e6%9d%a1%e4%bb%b6%e7%bc%96%e8%af%91)因此你可以配置在不同平台下拥有的登录方式。
如下配置,即表示仅在APP端启用“短信验证码登陆”
```js
"login": [
"username","univerify","weixin","apple"
// #ifdef APP-PLUS
"smsCode",
// #endif
]
```
#### 生效策略
登陆方式有如上5种,虽然你希望有几种登陆方式就在配置中列举几种。但是有的登陆方式可能因为设备环境问题而不被支持;
比如你正确地配置了微信登陆,而用户的手机并没有安装微信,这样微信登陆功能就无法使用。
并且如果出现这种情况你的app会被iOS的App Store拒绝上架。
所以在这里,我们的生效策略在检测:你是否有列举到某个配置项为前提的情况下,增加了检测当前环境是否支持,如果不支持会自动隐藏。
#### 在uni-app框架中配置:
在应用模块:`manifest.json` App模块配置 --> OAuth(登录鉴权)--> 勾选并配置你所需要的模块
+ 一键登录:
[开通配置](https://dev.dcloud.net.cn/uniLogin)
[使用指南](https://uniapp.dcloud.io/univerify)
+ [苹果登陆集成指南](https://ask.dcloud.net.cn/article/36651)
+ 短信登陆:
使用本功能需要在[DCloud开发者中心](https://dev.dcloud.net.cn/uniSms)开通并充值
教程参考[短信服务开通指南](https://ask.dcloud.net.cn/article/37534)
修改短信注册/登陆发生验证码的模板id,在文件`/uniCloud-aliyun/cloudfunctions/uni-id-cf/index.js` 搜索 `const templateId = '11753'` 替换为自己申请的模板id
#### 服务端配置
uni-starter服务端使用[uni-config-center](https://ext.dcloud.net.cn/plugin?id=4425)统一管理这些配置,
文件路径`/uni_modules/uni-config-center/uniCloud/cloudfunctions/common/uni-config-center/uni-id/config.json`
详情下文[目录结构](#id=catalogue)[uni-id配置说明](https://uniapp.dcloud.io/uniCloud/uni-id?id=configjson%e7%9a%84%e8%af%b4%e6%98%8e)
### 2.路由拦截
#### 应用场景
有些页面,限允许已经登陆后用户才访问。
常规的做法是打开这类页面之前,检查(前端校验)uni_id_token的值是否有效,如果无效会自动跳转到登陆页面。
而这样的页面有很多,入口也不少。面向过程的写法会产生大量的代码冗余,且不易维护。
而uni-starter基于拦截器(`uni.addInterceptor`),提供了仅需简单配置即可实现的路由拦截功能。
#### 配置方式
支持两种模式(二选一)
##### 黑名单模式
列举需要强制登陆的页面完整路径(支持正则)
##### 白名单模式
列举不需要强制登陆即可访问的页面完整路径(支持正则)
#### 配置示例
配置文件:`项目根目录/uni-starter.config.js`
```js
"router": {
/*名词解释:“强制登陆页”
在打开定义的需强制登陆的页面之前会自动检查(前端校验)uni_id_token的值是否有效,
如果无效会自动跳转到登陆页面
两种模式:
1.needLogin:黑名单模式。枚举游客不可访问的页面。
2.visitor:白名单模式。枚举游客可访问的页面。
* 注意:黑名单与白名单模式二选一 */
//needLogin:配置强制需要登陆的页面,在打开这些页面之前会自动检查(前端校验)uni_id_token的值是否有效,如果无效会自动跳转到登陆页面
// "needLogin" : [
// {pattern:/^\/pages\/list.*/}, //支持正则表达式
// "/uni_modules/uni-news-favorite/pages/uni-news-favorite/list",
// "/uni_modules/uni-feedback/pages/uni-feedback/add"
// ],
"needLogin" : [
{pattern:/^\/pages\/list.*/}, //支持正则表达式
"/uni_modules/uni-news-favorite/pages/uni-news-favorite/list",
"/uni_modules/uni-feedback/pages/uni-feedback/add"
],
/*
请注意上下,黑名单(needLogin)、白名单(visitor)两种配置模式二选一不可同时使用
*/
"visitor" : [
"/",//注意入口页必须直接写 "/"
{"pattern":/^\/pages\/list.*/}, //支持正则表达式
......@@ -119,52 +161,49 @@ uni-starter提供了仅需简单配置即可实现的路由拦截功能。
"/pages/ucenter/guestbook/guestbook",
"/pages/ucenter/about/about",
"/pages/ucenter/settings/settings"
],
/*
login:配置登陆类型与优先级
未列举到的,或设备环境不支持的选项,将被隐藏。如果你需要在不同平台有不同的配置,直接用条件编译即可
根据数组的第0项,决定登录方式的第一优先级。
*/
"login": ["username","univerify","weixin", "smsCode", "apple"]
]
}
```
##### 优势:
传统的路由管理方式是对uni-app框架路由写法的二次封装,自定义的写法不支持ide的代码提示,且不优雅。
另外不同插件作者封装不同的路由管理方式,这样做出来的插件与用户的项目结合时,路由写法不统一的差异需要去磨平。
用拦截器(下文有详细介绍)实现路由管理并不需要改变原来路由的写法。
为此`uni-starter`基于`uni.addInterceptor`(拦截器)实现路由管理。
##### 注意:
- 首页需要强制登陆才能访问的场景,不由路由控制。而是uni-starter的callFunction拦截器,根据响应体决定是否跳转到登陆页
- uni-starter框架不能将登陆页设置为首页,否则由拦截器实现的路由管理将生效。
- uni-starter的路由拦截,仅在调用路由API(navigateTo、redirectTo、reLaunch、switchTab)时触发。应用的首页是由系统自动打开,不会触发拦截器。首页需要强制登陆才能访问的场景,不由路由控制。但不用担心,如果未登陆的用户,打开了需要登陆才能访问页面,必定会触发需要携带有效token才能访问的API。此时则会返回相应的响应体,uni-starter监测到token无效这类的响应体也会自动跳转到登陆页(这种效果需要前后端都开发完成才体验到)
- uni-starter框架不能将登陆页`/pages/ucenter/login-page/index/index`设置为首页,否则由拦截器实现的路由管理将生效。
- 拦截器实现的路由控制,是在路由跳转未完成之前触发。路由切换方式(navigateTo、redirectTo、reLaunch、switchTab)URL参数必须使用绝对路径路
#### 3.h5版在页面顶部引导用户`点击下载App`
- 把h5端用户引流到APP端是一个非常常用的功能,相对于h5,APP端有更高的用户留存和更好的产品体验。
- 这同时也是一个演示开发者如何在h5端做全局悬浮块的例子。你可以在`/common/openApp.js`中修改他的样式等代码等,注意他只支持普通js语法。
### 3.h5版在页面顶部引导用户`点击下载App`
把h5端用户引流到APP端,是一个非常实用的功能。相对于h5,APP端有更高的用户留存和更好的产品体验。
uni-starter集成了这个功能,你只需直接在`项目根目录/uni-starter.config.js`的"h5"->"openApp"中配置相关内容,即可开启全局悬浮的下载引导。
这也是一个演示开发者如何在h5端做全局悬浮块的例子。你也可以在`/common/openApp.js`中修改他的样式等代码等,注意他只支持原生js语法。
#### 4.分享模块
### 4.分享模块
一个可覆盖原生层分享模块
- 应用配置:`manifest.json` App模块配置 --> Share --> 勾选并配置你所需要的模块
- 分享功能配置参数,随着应用的业务场景决定,在各场景调用的时候配置。参考uni-starter的`/pages/list/detail.vue``methods -> shareClick`
- 更多`uni-share`的介绍 [详情](https://ext.dcloud.net.cn/plugin?id=4860)
#### 5.升级中心相关
### 5.升级中心相关
为了解决开发者维护多个 App 升级繁琐,重复逻辑过多,管理不便的问题,升级中心`uni-upgrade-center`应运而生。
提供了简单、易用、统一的 App 管理、App 版本管理、安装包发布管理,升级检测更新管理。
- 升级中心分为两个部分:`uni-upgrade-center` Admin管理后台和`uni-upgrade-center - Admin`前台检测更新。
- `uni-upgrade-center`的介绍 [详情](https://ext.dcloud.net.cn/plugin?id=4542)
- `uni-upgrade-center - Admin`的介绍 [详情](https://ext.dcloud.net.cn/plugin?id=4470)
#### 6.意见反馈
### 6.意见反馈
- 客户端[详情](https://ext.dcloud.net.cn/plugin?id=50)
- admin端[详情](https://ext.dcloud.net.cn/plugin?id=4992)
#### 7.指纹识别模块
### 7.指纹识别模块
- `manifest.json` App模块配置 --> `Fingerprint`指纹识别
#### 8.消息推送模块
### 8.消息推送模块
- `manifest.json` App模块配置 --> `push`消息推送
#### 9.隐私政策弹框
### 9.隐私政策弹框
根据工业和信息化部关于开展APP侵害用户权益专项整治要求,App提交到应用市场必须满足以下条件:
- 应用启动运行时需弹出隐私政策协议,说明应用采集用户数据
- 应用不能强制要求用户授予权限,即不能“不给权限不让用”
......@@ -215,7 +254,7 @@ uni-starter提供了仅需简单配置即可实现的路由拦截功能。
1. 最新的华为应用市场要求,隐私政策提示框上接受按钮的文本,必须为“同意”而不能是其他有歧义的文字。
2. 配置后提交云端打包后生效。理论上绝大部分和`manifest.json`生效相关的配置均需要提交云打包后生效
#### 10.拦截器改造后的uniCloud
### 10.拦截器改造后的uniCloud
1. Debug,调试期间开启Debug。接口一旦fail就会弹出真实错误信息。否则将弹出,系统错误请稍后再试!
```js
if(Debug){
......@@ -230,7 +269,7 @@ uni-starter提供了仅需简单配置即可实现的路由拦截功能。
3. 常规的errCoder自动执行对应程序,如token无效/过期自动跳转到登陆页面。
4. token自动续期。
#### 11.举例路由控制原理,深入了解拦截器的使用
### 11.举例路由控制原理,深入了解拦截器的使用
比如你希望在打开用户中心等页面之前,都检查一下该用户是否登陆,否则就重定向到登陆页面。使用拦截器你可以用以下写法在应用入口定义全局生效:
```js
......@@ -304,7 +343,7 @@ uni-starter提供了仅需简单配置即可实现的路由拦截功能。
})
```
#### 12.关于升级
### 12.关于升级
- 项目升级
uni-starter遵循uni-app的插件模块化规范,即:[uni_modules](https://uniapp.dcloud.io/uni_modules) 。他是个项目类型的插件。在项目的根目录下有一个符合uni_modules规范的package.json文件,在这个文件右键-从插件市场更新即可更新该插件。
......@@ -313,10 +352,11 @@ uni-starter提供了仅需简单配置即可实现的路由拦截功能。
非项目类型的uni_modules插件,是项目根目录下的uni_modules目录下。以插件ID为插件文件夹命名,在该目录右键也会看到“从插件市场更新”选项,点击即可更新该插件。
#### 13.多语言国际化
### 13.多语言国际化
uni-starter支持多语言国际化。默认开启,可以在`uni-starter.config.js`->`i18n`->`enable`中配置
如果你启用了多语言国际化需要先阅读:[uni-app多语言国际化](https://uniapp.dcloud.io/collocation/i18n?id=%e6%a1%86%e6%9e%b6%e5%86%85%e7%bd%ae%e7%bb%84%e4%bb%b6%e5%92%8capi%e5%9b%bd%e9%99%85%e5%8c%96)
### 应用启动时序介绍
## 应用启动时序介绍
文件路径: App.vue
```js
import initApp from '@/common/appInit.js';
......@@ -341,8 +381,8 @@ onLaunch生命周期执行了
- 优雅实现:自动引导打开`选择图片`所需要的权限。当调用`uni.chooseImage`时检测到无权限自动开启引导。并不是在每次调用接口时处理这类问题,你可以参考该例子做更多该类场景的处理。uni-starter也会持续完善
##### 配置文件
uni-starter提供了uni-starter.config.js,可指定该应用是否强制登录才能进入某个页面,可配置选择登录注册方式以及不同方式的优先级等。配置项内容如下:
## 配置文件
uni-starter提供了`uni-starter.config.js`,可配置选择登录注册方式及优先级等,可指定该应用是否强制登录才能进入某个页面。配置项内容如下:
```js
module.exports = {
"h5": {
......@@ -411,7 +451,7 @@ module.exports = {
}
```
#### 目录结构@catalogue
## 目录结构@catalogue
<pre>
uni-starter
├─uniCloud-aliyun
......@@ -499,20 +539,20 @@ uni-starter
</pre>
完整的uni-app目录结构[详情](https://uniapp.dcloud.io/frame?id=%e7%9b%ae%e5%bd%95%e7%bb%93%e6%9e%84)
### 常见API示范
## 常见API示范
1. 判断当前用户是否拥有某角色`uniIDHasRole` 演示页面:`/pages/grid/grid` [API文档详情:](https://uniapp.dcloud.io/api/global?id=uniidhasrole)
2. 指纹解锁、人脸解锁 演示页面:`/pages/ucenter/settings/settings` [API文档详情:](https://uniapp.dcloud.io/api/system/authentication)
### 注意事项
## 注意事项
1. 真机运行需要制作自定义基座,制作后选择运行到自定义基座
2. 苹果登录的图标,需要满足苹果应用市场的审核规范请勿随便修改;如需修改请先阅读:[Sign in with Apple Button](https://appleid.apple.com/signinwithapple/button)
3. 应用登录功能,默认不勾选同意隐私权限是响应安卓应用市场的规范;请勿修改该逻辑。
### FAQ:常见问题
## FAQ:常见问题
1. 提示“公共模块uni-id缺少配置信息”解决方案:在cloudfunctions右键‘上传所有云函数、公共模块及actions’之后,需要在cloudfunctions -> common -> uni-config-center 目录单独上传一次,右键‘上传公共模块’。
2. 本项目代码可以商用,无需为DCloud付费。但不能把本项目的代码改造用于非uni-app和uniCloud的技术体系。即,不能将后台改成php、java等其他后台,这将违反使用许可协议。
### 第三方插件(感谢插件作者,排名不分前后):
## 第三方插件(感谢插件作者,排名不分前后):
1. 图片裁剪 [limeClipper](https://ext.dcloud.net.cn/plugin?id=3594) @作者: 陌上华年
2. 二维码生成 [Sansnn-uQRCode](https://ext.dcloud.net.cn/plugin?id=1287) @作者: 3snn
3. clipboard.js [clipboard](https://clipboardjs.com/)
\ No newline at end of file
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册