From 64a80fbf2996658313e861da5c3970448b01fd66 Mon Sep 17 00:00:00 2001 From: linju-json Date: Wed, 13 Oct 2021 16:19:41 +0800 Subject: [PATCH] =?UTF-8?q?-=20=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3=20-=20?= =?UTF-8?q?=E4=BF=AE=E5=A4=8Dlist=E9=A1=B5=E9=9D=A2where=E6=9D=A1=E4=BB=B6?= =?UTF-8?q?=E4=B8=AD=E7=BC=BA=E5=B0=91&=E7=AC=A6=EF=BC=8C=E5=AF=BC?= =?UTF-8?q?=E8=87=B4=E7=9A=84=E9=94=99=E8=AF=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 210 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 125 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index 7c26ca2..aea32f7 100644 --- a/README.md +++ b/README.md @@ -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、.. ### 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、.. -### 功能模块介绍 +## 功能模块介绍 +### 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 
 uni-starter
 ├─uniCloud-aliyun	
@@ -499,20 +539,20 @@ uni-starter
完整的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 -- GitLab