★ FEATURED ARTICLE 没用若依RuoYi的 App 版之前我以为它不过是把 PC 后台的页面逻辑搬到 uniapp 里套了一层壳登录、首页、列表能跑就行。真拿到项目源码、开始在真机上改页面时我才发现自己低估了这套页面的设计密度。RuoYi-App 版的页面不是一个“移动端后台”它是一整套按业务模块切分好的、可以直接落地的移动端工程模板。这篇文章我会从页面开发者的视角把 RuoYi-App 版里那些“你看得到但未必想得明白”的页面设计逻辑拆开来讲。适合刚拿到若依 App 源码、准备接公司业务的开发者也适合带团队做移动端管理系统的技术负责人。我会结合自己改造这套页面时遇到的真实问题说清楚为什么列表页要这样写、表单页为什么要走组件化、工作台首页怎么挂业务入口。1. RuoYi-App 版不只是一层“套壳页面”项目定位与页面覆盖全貌1.1 这套页面解决的是什么RuoYi-App 版本质上是一个基于 uniapp 的移动端解决方案后端服务仍然是你熟悉的那套若依 Spring Boot 服务。页面这套东西解决的问题很直接让一个本来就习惯了若依开发模式的后端团队也能比较快地做出一个 iOS、Android、H5 都能跑的移动端业务系统不需要再单独养一个原生开发团队。我看到的页面结构里官方已经把通用后台里最常出现的那批页面都搬过来了。比如登录页、首页 / 工作台、个人中心、我的待办、消息通知、用户管理、角色管理、菜单管理、部门管理、字典管理、参数设置、日志管理甚至还有文件上传、轮播图、富文本这类基础组件页。不要小看这套“全”它不是在堆页面数量而是在帮你定义移动端后台的交互基线——哪些入口该放首页、哪些操作用弹窗、哪些详情该单独开页官方已经替你趟过一遍。1.2 页面模块的依赖关系这套页面本身依赖两条线。第一条线是 uniapp 的pages.json路由体系和manifest.json的应用配置。第二条线是若依后端那套基于 JWT 的认证接口和数据字典接口。页面模块并不是彼此孤立的比如你要打开“部门管理”页前提是登录接口能拿到 tokentoken 失效时要能请求 refreshed token 的接口你要在表单里看到“所属部门”下拉前提是字典接口或者部门树接口能返回数据。这套依赖关系决定了一个很实际的逻辑改页面之前先弄清楚这个页面消费的是哪些后端接口而不是看到 vue 文件就开始改 UI。我第一次改“用户管理”页时直接改了下拉选项的静态数据结果后端权限一校验选项和数据对不上反而平白多出一堆无意义的沟通成本。从目录结构上看RuoYi-App 版把页面文件放在src/pages下每个业务域一个文件夹。这种按业务域组织页面的方式和 PC 端若依的views目录结构是对应得上的。你在移动端看到的“用户管理”本质上就是 PC 端“系统管理 - 用户管理”同款后端接口换了一套移动端的交互容器。2. 以“列表—表单—详情”三段式拆解页面套路移动端后台页面本质上是三个形态的循环列表页做数据总览和入口表单页做数据录入和编辑详情页做数据展示和操作聚合。RuoYi-App 版的页面也逃不开这三个形态但它在细节上有不少值得借鉴的地方。2.1 列表页的过滤状态与分页加载RuoYi-App 版的列表页通常带有筛选条件。筛选区一般用view和picker组件做展开收起或者是用顶部 tab 切换不同的数据状态。这里有一个很容易做得“不像移动端”的点把 PC 端那一整排查询条件直接堆到手机屏幕上。RuoYi-App 版的处理方式是“默认只展示一个搜索框 一个筛选按钮点开以后才展开完整筛选区”。分页加载的逻辑是移动端列表页的重头戏。页面里通常维护queryParams.pageNum和queryParams.pageSize初次加载请求pageNum1上拉触底时把pageNum 1然后把新返回的列表追加到已有数组后面而不是覆盖。这个看起来是个常识但我见过不少团队真上了生产才发现“滑动到底部之后列表没变化”——原因基本都出在忘记拼接或者触发了多次重复请求。// 伪代码列表加载逻辑的关键点 function loadList(isAppend) { const params { ...this.queryParams, pageNum: isAppend ? this.queryParams.pageNum 1 : 1 } api.list(params).then((res) { const list res.rows || [] this.list isAppend ? [...this.list, ...list] : list this.total res.total this.loading false }) }一个容易忽略的细节是“筛选状态变化后要重置 pageNum”。如果你从“全部”切到“已完成”不清空列表数据、不把页码拨回 1那拿到的就是第二页的“已完成”数据会漏掉第一页内容。我在实际改动时特意在筛选条件的 watch 里加了重置逻辑这类小问题不踩一次很难意识到。2.2 表单页的校验规则与数据字典RuoYi-App 版的表单页大量使用 uniapp 的uni-forms组件配合rules校验规则做必填、格式、长度控制。这个选择我认为是明智的比每个字段手写if-else要整齐得多而且uni-forms的校验触发时机可以配置成 blur 或者 change移动端体验上更贴近原生写法。数据字典在表单页和列表页里都是高频依赖。字典数据的加载一般放在页面onLoad或者onShow里通过后端字典接口拿到数组再用picker当下拉数据源。很多新手在这里会踩一个坑直接用一个全局常量替代字典接口但这样做一旦后端改了字典项App 端如果不发版永远看不到新数据。保持字典接口的动态性这是 RuoYi-App 版页面和普通静态 H5 页面最大的区别。表单提交前要处理的一类问题是“参数清洗”。uniapp 的uni-forms提交时拿到的是整个表单对象但后端接口未必接受全量字段。比如创建时间和更新时间的字段通常是后端生成前端提交时应该从参数里去掉或者明确置为 null。如果不做清洗轻则接口报多余的字段错误重则因为字段格式类型解析失败数据直接写不进去。2.3 详情页的“操作聚合”思路详情页在 RuoYi-App 版里不单纯做只读展示常见的做法是底部固定一个操作栏放编辑、删除、审核通过、驳回这类按钮。操作按钮的显隐条件往往和页面加载的数据状态绑定比如只有当前单据状态是“待审核”时才出现审核按钮。这种设计我很认可因为移动端页面空间有限把操作全部堆进页面中间会使滚动区域过长。底部固定栏可以保证用户无论浏览到详情页的哪一段都能直接发起操作。改造的时候要注意你的安全区适配iPhone 底部的 Home Indicator 区域需要额外留出高度否则按钮会被系统手势区挡住。我是通过constant.css里的安全区变量处理的不同机型上表现基本稳定。3. 页面和若依后端“对表”的几个关键环节页面单独好看没用得和后端真正对得上。RuoYi-App 版页面用到的后端接口和 PC 端若依基本一致所以我在这里要提醒几个页面对接时常被忽略的点。3.1 请求封装与 token 刷新RuoYi-App 版对网络请求做了二次封装统一在请求拦截器里带上 token在响应拦截器里处理 401 跳转登录页。这个机制保证了页面里的每一次接口调用都不用显式关心 token 是否过期。我建议你在动手改页面之前先把src/utils/request.js完整读一遍。明白 retry 机制怎么做的、token 过期后是怎么重新登录的、loading 是哪个页面控制的后面调接口会省很多事。我见过有团队在页面里自己存了一份 token结果服务端一刷新两边的 token 就错位了所有请求都在 401 的边缘试探。3.2 验证码、加密参数和权限点登录页用了若依后端的验证码接口这个是标准的。真正容易出问题的是业务接口里的加密参数和权限点检测。RuoYi 后端接口通常用自定义注解做权限控制前端页面按钮要和后端权限标识保持一致否则你调接口时会得到“没有权限”的提示。页面能跳进来不代表你有该页面的操作权限按钮列表的显隐也要走后端返回的权限集合来判断。这种前端页面和后端权限点对不上的情况排查起来最耗时。我的办法是在页面加载时先打一次日志把后端返回的权限集合打印出来和页面里硬编码的v-if条件做比对。这个方法笨但很稳。4. 二次开发把新业务页面接进 RuoYi-App 版的工作台对多数团队来说用 RuoYi-App 版不是看 demo而是要在这个框架里长出自己公司的业务。这里我把接一个新业务页面的完整链路走一遍。4.1 在 pages.json 里注册页面并设计入口任何一个新页面都要先写进src/pages.json否则 uniapp 编不出来。RuoYi-App 版里的pages.json已经按模块划分出pages/dept、pages/user、pages/login这些目录路径新业务页面最规范的做法是新建一个pages/xxxBusiness目录而不是往现成目录里塞。{ path: pages/order/index, style: { navigationBarTitleText: 工单管理 } }页面文件本身分成index.vue、form.vue、detail.vue三兄弟。列表页走index.vue新开工单走form.vue看工单详情走detail.vue这套命名规范在 RuoYi-App 版里已经成型新业务照葫芦画瓢就行团队成员接手时也会觉得熟悉。4.2 工作台首页入口和菜单权限的配合RuoYi-App 版的工作台首页或者叫首页、仪表盘通常会放置一个宫格导航或一组业务卡片。新业务页面接进去时要配两样东西一是在首页的数据配置里加一个入口项二是到后端菜单管理里把对应页面的路由信息配好。很多开发者忽略的是App 端的页面跳转依赖的是前端路由路径而后端返回的菜单数据里也有路由字段。两者配对不上时首页的入口点击以后会提示“找不到页面”但日志里没有任何报错。我排查过一次类似问题最后发现是后端菜单里配置的 component 路径多写了一个斜杠前端匹配不上。像这类问题建议先检查统一跳转方法再看路径字符串不要一上来就怀疑框架。4.3 新页面的边界条件处理新业务页面接入以后立刻要处理的一类问题是空数据状态、网络异常状态、加载失败重试。RuoYi-App 版里有一套空态图和异常提示组件但页面多了以后很容易出现“每个页面的空态各写各的”的情况。可以参考若依自带页面里对loading、empty、error三个状态变量的管理方式把状态提示组件抽成一个公共组件。接口没数据时显示空态图接口请求失败时显示“点击重试”请求中时用一个骨架屏或者加载动画占住位置。这些看起来是小优化但在真机上体验差异很大尤其弱网环境下一段空白页面会让用户认为 App 卡死了。5. 我在 RuoYi-App 版页面上踩过的几个坑5.1 输入框被键盘遮挡这是移动端表单页出现频率最高的问题。RuoYi-App 版里如果直接使用 uniapp 的input组件弹出键盘时键盘可能会遮住底部输入框。很多人的第一反应是去加adjust-position属性但实测在某些 Android 机型上还是会出现错位。我的处理方案是从页面结构上解决表单页外面套一层可滚动容器键盘弹起时滚动当前聚焦的输入框到可视区域。另外配合cursor-spacing属性给输入框一个合适的间距让输入框拥有足够的提升空间。如果你用的是uni-forms内部封装的输入控件可以在uni-forms外层再包一层scroll-view实测稳定很多。5.2 上拉触底的重复加载与数据重复列表页通常用onReachBottom生命周期做上拉触底加载。这个生命周期在 uniapp 里只对页面生效对scroll-view不生效所以不同列表页的触底逻辑写法会不一样。我在改造过程中发现两类问题一类是触底事件触发两次因为页面快速滑动时onReachBottom会连续触发需要在方法入口加一个this.loading判断如果正在加载就直接return。另一类是下拉刷新后没有重置列表数组导致下一页的数据拼接在旧数据后面出现了“第一页旧数据 第二页新数据”的错位展示。重置列表数组的时机一定要在接口请求之前而不是在数据返回之后否则极短时间内会出现旧数据闪一下的视觉问题。5.3 picker 联动选项的数据错位多级联动选择比如省市区、部门层级在 RuoYi-App 版里经常用多项picker或自定义联动选择器实现。我踩过的坑是第一级选项变化后第二级选项数组还在用旧数据导致选择A 省时显示的还是上一个省的城市列表。根治的办法是在一级选项的 change 事件里同步重置二级和三级选择器的数据源与选中索引。单纯清除选中值还不够因为picker内部可能还缓存着上一次的选中列索引用户一旦滑动到上一次的索引附近数据就会错位。我现在的做法是每次联动变化后强制重置column数据后再赋值避免旧索引残留。5.4 暗色模式下自定义样式失效RuoYi-App 版支持暗黑模式页面样式里大量使用 CSS 变量控制背景和文字颜色。但自定义业务页面如果没有区分亮色和暗色会遇到文字看不清、背景突兀这类问题。我在接入新页面时明显感受到官方页面里那套 CSS 变量设计是花了心思的但从 PC 端抄过来的那段样式直接搬进 App 页面往往会把深色背景和深色文字同时写上。排查的时候建议先看目标页面里有没有引用theme.scss或者uni.scss里的变量再看App.vue的全局样式影响范围。如果只是个别页面要适配直接用media (prefers-color-scheme: dark)处理也行但要注意 uniapp 在 App 端对 CSS 媒体查询的兼容性不如 H5 端稳定更稳妥的做法是跟随主题状态动态切换 class。6. 关于 RuoYi-App 版页面的个人使用建议用 RuoYi-App 版做移动端后台最怕的就是“觉得页面已经齐了直接往里填业务”。页面齐不齐只是表面你能不能在里面顺畅地加新页面、换数据源、调整主题才是这套框架真正的价值所在。我的习惯是拿到新版本先花半天把pages.json和request.js过一遍搞清楚这个版本里的页面依赖和接口封装有没有变化然后再动手改业务。改页面时字段的命名和后端保持完全一致是我在团队里一直坚持的规矩。不要前端叫userName、后端叫name然后页面里做一堆字段映射。这样的映射一开始只是多写几行代码等到列表筛选、表单校验、详情回显三处都要做映射时光对齐字段就够你加班到天黑。RuoYi-App 版的页面设计本身是遵循后端字段命名的保持这个惯性团队成员交接时也轻松一些。另外如果你准备把 RuoYi-App 版页面用于生产环境建议提前把图片资源、字体文件这些静态资源做统一管理不要散落在各个页面目录里。这个版本对主题样式、空态图、加载图的组织方式是模块化的顺着它的思路去整理自己的业务资源后面换肤也好、打包也好都会省心不少。最后再分享一个小技巧每个新页面开发完先在 H5 端跑一遍交互再上真机测一遍键盘和底部手势区最后再打包 App。这个顺序虽然多花点时间但能把页面问题拦截在最早阶段比全部写完再统一调试要高效得多。
阅读完成 · 觉得有帮助？
