uniapp 多端 UI/UX 体验审计

核心原则

• UI/UX 优先：核心聚焦界面体验，兼容性功能问题只是附带检查
• 代码层面可诊断：即使没有真机和基座，也能通过扫描样式、布局、组件代码定位 80% 的 UI 问题
• 三端差异对比：iOS App、Android App、H5 三端分别检查，重点找不一致的地方
• 专项项目深度：识别项目类型（IM/游戏/通用），走对应的专项检查清单
• 落地可执行：不只是指出"体验不好"，要给出具体改哪个文件、改什么代码
• 问题分级：按影响程度（阻断/严重/一般/优化）分级输出
• 闭环修复：输出 Plan → 用户确认 → 直接改代码 → 清理旧样式 → 交付结果

技能分工路由（与 ios-ui-ux-dev / uniapp-release-notes 的边界）

本技能聚焦 iOS / Android / H5 三端水平广度；iOS 垂直深度与 API 版本核验分别由另外两个技能承接，不要重复造轮子：

协作方式：三端审计中凡落到 iOS WKWebView 渲染根因的问题，标注后转 ios-ui-ux-dev 按 H-* 规则复核；凡涉及 API 版本/兼容性结论，按 references/compatibility-rules.md「版本适配层」调用 uniapp-release-notes 脚本核验，不在本技能里凭印象下结论。

工作流程

Step 1: 项目 UI 基线扫描

自动读取 UI 相关文件，建立设计基线：

必扫文件：

1. uni.scss — 全局样式变量、设计令牌（颜色、字体、间距）
2. App.vue — 全局样式、全局样式类
3. pages.json — 导航栏样式、tabBar 样式、页面窗口配置
4. manifest.json — 版本号、安全区配置、窗口背景色
5. 全局样式文件 — common/、styles/ 目录下的全局 CSS

识别维度：

• 设计系统：有没有统一的设计变量（颜色、字体、间距、圆角）
• UI 组件库：uView / NutUI / uni-ui / ThorUI / 其他
• 设计风格：扁平化 / 新拟态 / 玻璃拟态 / 其他
• 三端样式隔离：有没有按平台分的样式文件（#ifdef APP-PLUS 样式块）
• 响应式方案：rpx 使用比例、适配方案
• 深色模式：有没有做暗色模式适配
• 项目类型识别：根据页面结构判断是 IM 聊天类 / 游戏类 / 通用业务类

项目类型识别方法：

# IM 类特征：聊天页、通讯录、消息列表等
ls pages/ | grep -E "chat|message|contact|session|im" && echo "IM 项目特征"

# 游戏类特征：canvas、游戏页、横竖屏配置
grep -r "canvas" pages/ --include="*.vue" -l | head -5
grep -r "landscape\|横屏" manifest.json pages.json && echo "游戏项目特征"

# 根据 tabBar 判断项目类型
grep -A 20 "tabBar" pages.json | grep -E "chat|message|game|mine|contact"

输出：UI 基线表（设计系统现状 + 三端样式差异点 + 项目类型）

Step 2: 三端 UI/UX 深度审计（核心）

这是技能的核心输出，按三端分别审计。详见 references/ux-checklist.md

审计维度（按优先级）：

1. 视觉一致性

• 三端同页面布局是否一致
• 颜色、字体、间距、圆角是否统一
• 组件样式是否按平台有不必要的差异
• 图标风格是否统一

2. 交互体验

• 点击反馈是否自然（iOS 柔和 / Android 明显）
• 滚动体验是否流畅（橡皮筋、回弹、惯性）
• 页面切换动画是否统一
• 弹窗、Toast 位置和样式是否一致

3. 安全区与适配

• iPhone 刘海屏/灵动岛适配
• 底部 Home 指示条适配
• Android 状态栏沉浸效果
• 不同屏幕尺寸下布局是否错乱

4. 输入与键盘

• 键盘弹起时输入框是否被遮挡
• 键盘弹出页面是否合理上推
• 输入框字号是否 ≥16px（防止 iOS 自动放大）
• 确认/取消按钮位置是否符合平台习惯

5. 导航与返回

• iOS 手势返回是否正常
• Android 物理返回键逻辑是否一致
• 导航栏样式三端是否统一
• tabBar 点击切换是否流畅

输出：UI/UX 问题清单（按三端分组，标注严重程度 + 文件位置）

Step 3: 项目类型专项审计

根据 Step 1 识别的项目类型，走对应的专项检查清单：

如果是 IM/聊天类项目

详见 references/im-checklist.md

专项检查重点：

• 聊天消息气泡布局三端一致性
• 输入栏适配（键盘弹起、表情面板、语音输入切换）
• 会话列表滚动性能
• 头像、图片、文件消息的尺寸适配
• 消息已读回执、未读角标样式
• 语音/视频通话页全屏沉浸
• 聊天页底部安全区适配
• 长按消息菜单样式

如果是游戏类项目

详见 references/game-checklist.md

专项检查重点：

• Canvas/WebGL 三端渲染性能差异
• 横竖屏切换适配
• 全屏沉浸模式（隐藏状态栏/导航栏）
• 触摸手势（多点触控、滑动、缩放）
• 游戏 UI 安全区适配
• 加载页、结算页、弹窗样式
• 不同分辨率屏幕下游戏画面比例

如果是通用业务项目

跳过专项审计，直接进入 Step 4。

输出：专项问题清单（按项目类型分组）

Step 4: 附带兼容性检查（快速扫）

快速扫一遍明显的兼容性硬伤，不作为重点输出。详见 references/compatibility-rules.md

快速扫描项：

1. 搜索 100vh — H5 端地址栏问题，建议替换为 100%
2. 搜索 position: fixed — iOS 键盘弹起位置偏移问题
3. 搜索 #ifdef 样式块 — 检查三端样式分支是否合理
4. 搜索 safe-area — 安全区适配是否完整
5. 搜索 px 硬编码 — 有没有混用 px 和 rpx

输出：兼容性硬伤清单（只有阻断级和严重级才输出，一般级跳过）

Step 5: 设计系统一致性检查

检查项目有没有统一的设计规范，还是各页面各写各的：

检查项：

• 颜色值有没有统一管理（uni.scss 变量）
• 间距、圆角、字号有没有统一规范
• 按钮样式有没有统一组件
• 卡片、列表、输入框样式有没有统一规范
• 有没有硬编码的颜色值、字号、间距散落各处

输出：设计系统缺口清单 + 优化建议

Step 6: 诊断报告输出

输出结构：

## UI 基线概览
[设计系统现状 + UI 组件库 + 项目类型 + 三端样式差异概述]

## UI/UX 问题汇总
| 类别 | 阻断 | 严重 | 一般 | 优化建议 |
|------|------|------|------|----------|
| 视觉一致性 | X | X | X | X |
| 交互体验 | X | X | X | X |
| 安全区适配 | X | X | X | X |
| 输入键盘 | X | X | X | X |
| 导航返回 | X | X | X | X |
| 专项（IM/游戏） | X | X | X | X |
| 设计系统 | - | - | X | X |

## 详细问题清单
### 🔴 阻断级（必须修复）
[问题描述 + 平台 + 文件位置 + 修复方案]

### 🟠 严重级（影响体验）
...

### 🟡 一般级（小瑕疵）
...

### 🔵 优化建议（锦上添花）
...

## 修复执行计划
1. [第一步]
2. [第二步]
...

等待用户确认后，进入 Step 7 执行修复。

Step 7: UI/UX 修复执行（用户确认 Plan 后）

用户确认修复 Plan 后，按以下流程执行：

执行原则：

• 逐项修复，每修完一项验证一项
• 样式修改必须最小化，不擅自改其他无关代码
• 旧样式清理必须彻底，不留下死代码和注释
• 每修复完一项，更新问题清单的状态

执行步骤：

1. 全局样式修复：修改 uni.scss / 全局样式文件 / App.vue 全局样式
2. 页面级样式修复：修改具体页面的样式块，增加平台条件编译
3. 组件级样式修复：修改公共组件的样式
4. 配置修复：修改 pages.json 导航栏样式 / manifest.json 窗口配置
5. 清理旧代码：
   • 删除废弃的样式类
   • 删除重复的样式定义
   • 清理注释掉的旧代码
6. 验证：
   • 样式无语法错误
   • 无残留硬编码值
   • 三端条件编译完整闭合
   • 关键页面布局逻辑正确

输出格式：

## 已完成 UI 修复清单
✅ [修复项 1]：[文件位置]
✅ [修复项 2]：[文件位置]
...

## 变更文件统计
| 类型 | 数量 | 文件列表 |
|------|------|----------|
| 修改样式 | X | xxx.vue, xxx.scss |
| 修改配置 | X | pages.json, manifest.json |
| 新增样式 | X | xxx.css |
| 清理删除 | X | 废弃样式类 X 处 |

## 待确认事项
[需要用户在真机/设计稿上确认的项]

## 后续建议
[本次未修复的优化项，可排期]

状态标记规范：

• ✅ 已修复并验证
• ⚠️ 需用户真机/设计稿确认
• 📋 本次未做，后续排期

脚本速查（Python 3.8+，纯标准库）

# UI/UX 与兼容性静态扫描，输出 markdown 报告（含 P0-P3 分级）
python scripts/uniapp_scan.py <工程目录> --format md --out uniapp-uiux-report.md
# 只看 P0/P1（阻断/严重）
python scripts/uniapp_scan.py <工程目录> --min-severity P1
# 退出码：存在 P0/P1 时为 1，可接 CI；--no-fail 恒 0

• 脚本自动跳过 node_modules/unpackage/dist/.git 等目录。
• 规则编号（U-*）与 references/ux-checklist.md、references/compatibility-rules.md 对应；脚本是底线覆盖，不替代人工三端对比审计。

注意事项

• 扫描代码时使用 Grep 工具批量搜索关键词，不要逐文件读取
• 兼容性问题必须给出具体的代码行号或文件路径
• 修复方案必须可直接落地，不要只说"需要适配"
• 区分"项目代码问题"和"uniapp 框架已知 bug"——后者引导用户查版本
• 不要编造不存在的 API 或配置项，不确定的明确标注"需确认"
• 版本验证必须做：所有 API 兼容性结论必须结合项目实际版本，不能凭印象说"支持/不支持"。具体走 references/compatibility-rules.md「版本适配层」流程，调用平行技能 uniapp-release-notes/scripts/query_releasenotes.py 查新增/修复/变更，不在本技能里臆断
• uni-app x 单独判断：如果是 uni-app x 项目，API 兼容性和经典版不同，需用 --module "uni-app x" 过滤查询
• 升级建议要量化：如果建议升级 uniapp 版本，说明从哪个版本升级到哪个版本，升级后能解决什么问题，有什么 breaking change
• 修复必须闭环：用户确认 Plan 后，必须实际执行修改，不能只给建议就结束
• 清理必须彻底：修复涉及替换/删除的，必须检查所有引用点，确保无残留死代码
• 修复要可验证：每修复一项，都要说明验证方式（构建通过、类型检查通过、逻辑正确）
• 不做过度修改：只修复问题清单里的项，不擅自重构或美化其他代码