cykj/zkxw
1
0 Fork 0
Code Issues 1 Pull Requests 1 Packages Projects Releases Wiki Activity
Files
031e4566142687f4d3bf7f020f595f92f3c2c486
zkxw/docs/superpowers/specs/2026-08-10-mobile-h5-vant-ui-design.md
T
zlwuandCursor 031e456614 docs: record mobile-h5 Vant UI design, plan, and demo 
Link the workspace UI demo and implementation plan from the
miniprogram UI spec for the unified mobile workbench.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-10 14:03:36 +08:00

12 KiB
Raw Blame History

移动端（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 目标

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

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 首页菜单权限规则

  1. 菜单数据来自后台「菜单管理」中 移动端菜单 树（parent_id 指向移动端根）。
  2. 登录人仅展示其角色/职位授权内的菜单。
  3. 卡片样式：上方 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 骨架）

  1. 在 mobile-h5 目录用 HBuilderX 终端或本地 npm 安装： 
    npm init -y   # 若尚无 package.json
npm i @vant/weapp -S --production
  2. 在 pages.json 配置 easycom（按官方路径）： 
    "easycom": {
  "autoscan": true,
  "custom": {
    "^van-(.*)": "@vant/weapp/dist/$1/index"
  }
}
    （若发行报路径错误，改为 @vant/weapp/$1/index，以本机 node_modules/@vant/weapp 实际目录为准。）
  3. 微信小程序需在 manifest.json → mp-weixin 填入 appid；开发阶段可继续 urlCheck: false。
  4. 主题色：在全局样式覆盖 Vant CSS 变量 / 组件自定义色（见 §5.2），主色统一为 #0a9f6d。
  5. 页面中按需使用：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 业务页适配清单（复制即用）

新开一个业务列表页时：

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

6. 与现有文档的关系

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

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

  1. mobile-h5 增加 package.json + 安装 @vant/weapp，配置 pages.json easycom。
  2. 落地 styles/tokens.scss + vant-theme.scss + app.scss，在 App.vue 引入。
  3. 抽公共组件：MenuGrid、BizListCard、AttachList、FlowTimeline。
  4. 实现首页（菜单权限 mock → 再接真实菜单 API）。
  5. 实现列表 / 详情 / 表单样板页各一，作为后续业务复制模板。
  6. 回写 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 整合、全局样式目录与适配清单
Reference in new issue View Git Blame Copy Permalink