移动端（mobile-h5）UI 设计与 Vant 整合方案

日期：2026-08-10
工程：mobile-h5（HBuilderX 创建的 uni-app Vue3，发布微信小程序）
视觉 Demo：mobile-ui/zkxw-mobile-vant-ui-demo.html
相关需求：docs/中科兴皖需求V0.3.md（小程序端 Vue3 + vant-ui）
品牌 Token：对齐 docs/miniprogram-ui-spec-sanqiang.md 三墙色板（非 web-admin Fresh Mint）

1. 目标与约束

1.1 目标

固化本轮 Demo 已确认的页面风格（首页 / 列表 / 详情 / 表单 / 组件合集）。
在不改动 HBuilderX 工程骨架（保留 manifest.json / pages.json / main.js / App.vue 等原生结构）前提下，接入 Vant，并建立可复用的全局样式层，方便后续业务页快速适配。
首页为单一工作台：功能菜单卡片受「菜单管理 → 移动端菜单」+ 角色/职位权限控制。

1.2 硬约束

项	约定
工程形态	继续使用 HBuilderX + uni-app，不迁移为独立 Vite CLI 工程
UI 库	Vant 体系（微信端使用 `@vant/weapp`）
Vue	Vue 3（`manifest.json` → `vueVersion: "3"`）
主色	`#0a9f6d` / `#087f57` / `#e9f9f2`（禁止混用 web-admin `#10b981`）
发布	HBuilderX 发行到微信小程序

1.3 非目标（本期不做）

不改造 web-admin。
不实现完整业务 API 联调（本设计只定 UI / 样式 / 工程骨架）。
不引入第二套 UI 框架（如 uView / wot 与 Vant 并存）。

2. 视觉权威与页面模式

2.1 权威文件

角色	路径
交互与视觉 Demo（本轮定稿）	`mobile-ui/zkxw-mobile-vant-ui-demo.html`
品牌 Token 基线	`docs/miniprogram-ui-spec-sanqiang.md` §2
本设计说明	本文档

后续业务页 SHALL 以 Demo 中对应页面区块为准；Token SHALL 以三墙色板为准。

2.2 已定稿页面

模式	Demo 入口	结构摘要
P-Home 首页工作台	「1. 首页」	绿渐变 Header → 权限菜单 4 列宫格（上 Icon 下标题）→ 待办统计卡 + 待办条目
P-List 列表	「2. 列表」	Hero + 内嵌搜索 → 悬浮分段筛选 → 状态着色业务卡（图标/金额或进度/操作）
P-Detail 详情	「3. 详情」	状态色 Hero → 指标 Dock → 分区卡片（基础信息 / Steps / 缴费 / 附件 / 流转）→ 底栏
P-Form 新增编辑	「4. 表单」	绿顶栏 → `van-form` 分组 Field → 底栏取消/保存
P-Comps 组件合集	「5. 组件」	按钮 / Tag / Cell / 通知空态加载 / Feedback / 分段步骤 / 附件

2.3 首页菜单权限规则

菜单数据来自后台「菜单管理」中 移动端菜单 树（parent_id 指向移动端根）。
登录人仅展示其角色/职位授权内的菜单。
卡片样式：上方 Icon，下方标题；推荐 4 列宫格；触达区域 ≥ 44×44。

3. 设计 Token（全局变量）

在 uni-app 中以 SCSS 变量 + CSS 变量 双轨落地，业务页优先用 CSS 变量，便于运行时/主题覆盖。

// styles/tokens.scss（设计源）
$brand-green: #0a9f6d;
$brand-green-dark: #087f57;
$brand-green-soft: #e9f9f2;
$barley-yellow: #d6a343;
$barley-yellow-soft: #fff7e8;
$bg-page: #f5f8f7;
$surface: #ffffff;
$text-primary: #1f2a26;
$text-muted: #6b7b74;
$border: #dcebe4;
$danger: #d14343;
$warning: #cf8a19;   // Demo 中部分强调用 #a67b20 / #d6a343 同族
$success: #189b65;

$radius-card: 14px;
$radius-lg: 20px;    // Hero 下缘可用 28px
$space: 8px;         // 节奏：8 / 10 / 12 / 14 / 16

映射到页面根（App.vue 或 styles/app.scss）：

page, :root {
  --brand-green: #0a9f6d;
  --brand-green-dark: #087f57;
  --brand-green-soft: #e9f9f2;
  --barley-yellow: #d6a343;
  --barley-yellow-soft: #fff7e8;
  --bg-page: #f5f8f7;
  --surface: #ffffff;
  --text-primary: #1f2a26;
  --text-muted: #6b7b74;
  --border: #dcebe4;
  --danger: #d14343;
  --warning: #cf8a19;
  --success: #189b65;
  --radius-card: 14rpx; /* 实现时按 rpx 换算，见 §5.3 */
  --shadow-soft: 0 8rpx 32rpx rgba(8, 127, 87, 0.08);
}

语义状态色（列表卡 / Tag / 详情 Hero）：

状态	主强调	用途
待处理	琥珀 / 大麦黄	warning 卡、Tag
进行中	品牌绿	primary 卡、实心 Tag
异常	`#d14343`	danger
已完成	`#189b65`	success 浅绿底

4. Vant 整合方案（推荐）

4.1 选型说明

方案	说明	结论
A. `@vant/weapp`	Vant 官方微信小程序版，HBuilderX 发微信主路径最稳	推荐（默认）
B. `vant`（Web Vue3）	仅适合纯 H5；微信端组件不兼容	仅作 H5 调试补充，不作为主路径
C. 其它 uni UI	与需求「vant-ui」不符	不采用

需求原文要求 vant-ui；在 uni-app → 微信小程序场景下，@vant/weapp 即 Vant 在微信端的官方落地形态。

4.2 接入步骤（不破坏 HBuilderX 骨架）

在 mobile-h5 目录用 HBuilderX 终端或本地 npm 安装：
```
npm init -y   # 若尚无 package.json
npm i @vant/weapp -S --production
```
1. 在 pages.json 配置 easycom（按官方路径）： json "easycom": { "autoscan": true, "custom": { "^van-(.*)": "@vant/weapp/dist/$1/index" } } （若发行报路径错误，改为 @vant/weapp/$1/index，以本机 node_modules/@vant/weapp 实际目录为准。）
微信小程序需在 manifest.json → mp-weixin 填入 appid；开发阶段可继续 urlCheck: false。
主题色：在全局样式覆盖 Vant CSS 变量 / 组件自定义色（见 §5.2），主色统一为 #0a9f6d。
页面中按需使用：van-button、van-search、van-field、van-nav-bar、van-tag、van-empty、van-loading、van-notice-bar、van-steps、van-action-sheet、van-dialog、van-toast 等。

4.3 与自定义样式的边界

用 Vant	用项目全局样式 / 业务组件
按钮、表单 Field、导航栏、Toast/Dialog/Sheet、Steps、Empty、Loading、NoticeBar、基础 Tag	首页菜单宫格、待办统计、列表业务卡、详情 Hero/指标 Dock、附件卡、流转时间线、分段 Chip/Seg

原则：交互控件跟 Vant；业务信息架构跟 Demo 自定义类名，避免在每个页面复制大段 CSS。

5. 全局样式怎么写（方便后续适配）

5.1 推荐目录（在 `mobile-h5` 内增量，不改框架入口文件职责）

mobile-h5/
  App.vue                 # 引入全局样式；生命周期
  main.js                 # 保持 HBuilderX 默认
  pages.json
  manifest.json
  uni.scss                # 覆盖/扩展 uni 变量（可 @import tokens）
  styles/
    tokens.scss           # 色板、圆角、间距（唯一 Token 源）
    vant-theme.scss       # Vant 主题覆盖
    mixins.scss           # 渐变 Hero、卡片、安全区等 mixin
    app.scss              # page 背景、通用工具类
    components/
      menu-grid.scss      # 首页菜单宫格
      todo.scss           # 待办
      list.scss           # 列表 Hero / Seg / biz-card
      detail.scss         # 详情 Hero / Dock / section
      attach.scss         # 附件上传与文件卡
      flow.scss           # 流转记录
      form-shell.scss     # 表单底栏等
  components/             # 可复用 Vue 组件（后续落地）
    AppHero.vue
    MenuGrid.vue
    BizListCard.vue
    AttachList.vue
    FlowTimeline.vue
    ...
  pages/
    index/                # 工作台首页
    ...
  api/                    # 后续
  store/                  # 后续
  utils/

5.2 Vant 主题覆盖（示例）

/* styles/vant-theme.scss */
page {
  --van-primary-color: #0a9f6d;
  --van-success-color: #189b65;
  --van-warning-color: #cf8a19;
  --van-danger-color: #d14343;
  --van-border-color: #dcebe4;
  --van-background: #f5f8f7;
  --van-text-color: #1f2a26;
  --van-text-color-2: #6b7b74;
  --van-button-primary-background: #0a9f6d;
  --van-button-primary-border-color: #0a9f6d;
  --van-nav-bar-background: transparent;
  --van-nav-bar-title-text-color: #ffffff;
  --van-nav-bar-icon-color: #ffffff;
}

App.vue：

<style lang="scss">
  @import "@/styles/tokens.scss";
  @import "@/styles/vant-theme.scss";
  @import "@/styles/app.scss";
  @import "@/styles/components/menu-grid.scss";
  @import "@/styles/components/list.scss";
  @import "@/styles/components/detail.scss";
  @import "@/styles/components/attach.scss";
  @import "@/styles/components/flow.scss";
  /* 按需继续 import */
</style>

HBuilderX Vue3 若 @ 别名未配置，可用相对路径 ./styles/...，或在项目中按 uni-app 惯例配置。

5.3 rpx 适配约定

Demo 以 375 逻辑宽 为基准（与小程序规范一致）。
换算经验：1px ≈ 2rpx（375 设计稿）。
全局样式落地时：字号、间距、圆角、图标容器用 rpx；1px 边框可用 1rpx 或 0.5px（按端表现微调）。
触达高度：按钮 / 底栏主按钮 ≥ 88rpx（约 44px）。

5.4 可复用「壳」类名（与 Demo 对齐，落地时保持稳定）

后续新页面优先组合下列类，而不是新起一套命名：

类名 / 区块	用途
`.page-shell` + 浅绿径向背景	列表/详情/组件页底
`.hero` / `.list-hero` / `.detail-hero`	绿/状态色顶区 + 大圆角下缘
`.filter-dock` / `.seg-tabs`	悬浮筛选、四格分段
`.biz-card.status-*`	列表业务卡
`.detail-section` + `.sec-hd`	详情分区
`.d-attach-` / `.flow-`	附件、流转
`.menu-grid` / `.menu-card`	首页菜单
`.form-footer` / `.detail-footer`	底栏

5.5 业务页适配清单（复制即用）

新开一个业务列表页时：

pages.json 注册路由；顶栏可用自定义 Hero，隐藏默认 navigationBar 或设透明。
结构：hero（搜索） → seg-tabs → biz-card 列表。
状态枚举映射到 status-warning | status-primary | status-danger | status-success。
主按钮仅一处实心 type="primary"（或项目封装的主按钮 class）。
附件、流转直接引用 AttachList / FlowTimeline 组件（落地后）。

6. 与现有文档的关系

docs/miniprogram-ui-spec-sanqiang.md：继续作为三墙 Token / 媒体比例等基线；其中旧「客户端购物车三端」Demo 与本「统一工作台」产品形态不同，工作台信息架构以 zkxw-mobile-vant-ui-demo.html 为准。
建议在 miniprogram-ui-spec-sanqiang.md 增加一节「移动工作台（mobile-h5）」指向 Demo + 本文档（实现阶段文档任务，可与代码一并改）。
颜色隔离：web-admin 仍用 Fresh Mint；mobile-h5 只用三墙绿。

7. 实施顺序建议（供下一阶段 plan）

mobile-h5 增加 package.json + 安装 @vant/weapp，配置 pages.json easycom。
落地 styles/tokens.scss + vant-theme.scss + app.scss，在 App.vue 引入。
抽公共组件：MenuGrid、BizListCard、AttachList、FlowTimeline。
实现首页（菜单权限 mock → 再接真实菜单 API）。
实现列表 / 详情 / 表单样板页各一，作为后续业务复制模板。
回写 miniprogram-ui-spec-sanqiang.md 工作台章节。

8. 验收标准

Demo 中五种页面模式在文档与样式类名上可一一对应。
全局 Token 仅一处定义（tokens.scss），Vant 主色与品牌绿一致。
HBuilderX 仍可正常运行到微信开发者工具 / 发行。
新业务页可在不复制大段 CSS 的情况下，组合 shell + Vant 控件完成布局。
不出现 web-admin #10b981 主色。

9. 修订记录

日期	说明
2026-08-10	初稿：定稿 Demo、Token、`@vant/weapp` 整合、全局样式目录与适配清单

2026-08-10-mobile-h5-vant-ui-design.md 12 KB Permalink History Raw