文件
yjyf/yjyf-app/docs/FRONTEND_SPECIFICATION.md
YuanWen 7ab7429dee feat: 新增统一底部导航与全局样式系统,优化交互体验
新增全局 YjyfTabBar 组件,替换各页面自定义导航,实现一致的 tab 切换逻辑与图标样式
新增全局设计令牌与 SCSS 变量系统,统一色彩、间距、字阶、圆角与投影规范
新增 POST 请求防并发锁,避免重复提交
重构多个页面,添加骨架屏、空状态引导、点击反馈类,修复硬编码样式与假数据
删除废弃的后台入口文件与 nginx 配置,清理冗余代码
2026-11-02 14:00:19 +08:00

20 KiB

优匠优服(YJYF)小程序端前端开发与 UI/UX 体验设计规范

版本:v1.0.0
适用端:微信小程序 / Uni-App (Vue 3 + Vite)
制定日期:2026年11月
状态:正式发布(全项目统一遵循)


目录

  1. 规范总则与核心原则
  2. 设计系统与设计令牌 (Design Tokens)
    • 2.1 品牌与功能色盘
    • 2.2 字阶排版与可读性基线
    • 2.3 8rpx 间距模数阶梯
    • 2.4 圆角与弥散投影
  3. 布局与多端适配规范
    • 3.1 视口基准与单位准则
    • 3.2 导航体系与路由栈管控
    • 3.3 顶部状态栏与底部安全区适配
    • 3.4 通用页面布局骨架
  4. 图标与视觉资产规范
    • 4.1 核心图标禁令与替代规范
    • 4.2 统一矢量图标规格
    • 4.3 缺省与占位图规范
  5. 触控热区与微交互规范
    • 5.1 44×44px 最小触控热区
    • 5.2 即时触控反馈(Hover State)
    • 5.3 动效时序与物理缓动
  6. 状态完备性体验规范 (8 态模型)
    • 6.1 页面级骨架屏与渐进加载
    • 6.2 列表触底分页与刷新协议
    • 6.3 友好空状态设计
  7. 表单与交互反馈规范
    • 7.1 外部可见标签与占位符
    • 7.2 就近行内实时校验
    • 7.3 提交防重防抖与加载反馈
    • 7.4 原生键盘与弹层避让
  8. 工程化落地代码模版
    • 8.1 全局 uni.scss 核心变量集
    • 8.2 App.vue 全局基准与样式工具类
    • 8.3 request.js 请求体验增强
    • 8.4 交付前 10 步设计自检清单

1. 规范总则与核心原则

为了保证“优匠优服”产品矩阵在移动端具备高信任度、高商业审美、高可用性与流畅的操作手感,杜绝测试原型式粗糙感,特制定本规范。全员在进行任何页面开发、UI 重构或组件开发时,必须严格遵守以下四大原则:

  1. 一致性优先 (Consistency First):严禁在单个组件或页面中随意硬编码十六进制颜色与边距,所有样式必须溯源至全局 Design Tokens。
  2. 严防极小字号与低对比度 (Legibility Baseline):正文字号基线 ≥ 24rpx (12px),禁止出现低于 22rpx 的微字;文本与底色对比度必须满足 WCAG AA 级(≥ 4.5:1)。
  3. 消除伪图标与粗糙占位 (Professional Assets):严禁使用汉字单字(如“微、厅、单、钱”)充当功能图标,必须统一使用高质量 SVG 矢量图标或双色微拟物图标。
  4. 状态闭环与零白屏 (Zero-Blank Loading):每个页面和列表必须完整具备默认态、加载骨架态、空数据导流态和错误重试态,严禁在接口未完成前整屏白屏。

2. 设计系统与设计令牌 (Design Tokens)

2.1 品牌与功能色盘

严禁各页面混用杂乱 Hex 值,全局严格执行 60-30-10 配色法则(60%中性底色 #F5F6F8、30%白卡底 #FFFFFF、10%核心行动橙色)。

语义名称 变量名 色值 / 渐变 适用场景
品牌主色 (Primary) $yjyf-primary #F0710D 核心 CTA 按钮、主强调色、选中标签、价格高亮
品牌亮橙 $yjyf-primary-light #FFA93F 渐变起点、次级强调、高光点缀
品牌浅橙底 $yjyf-primary-bg #FFF7F0 选中卡片底色、提示条底色、轻按钮底色
CTA 主渐变 $yjyf-gradient-primary linear-gradient(135deg, #FFA93F 0%, #F0710D 100%) 底部大按钮、主操作按钮、高光徽标
成功色 (Success) $yjyf-success #2FA84F 微信授权按钮、已完成状态、支付成功
警示危险 (Danger) $yjyf-danger #E8331B 取消订单、删除地址、申诉驳回、表单报错
提示关注 (Warning) $yjyf-warning #F98D25 急单标签、待支付倒计时、审核中
链接/信息 (Info) $yjyf-info #4A7CFF 待分配状态、跳转链接、协议文本

中性文字与背景层级

变量名 色值 对应层级与用途
$yjyf-text-main #1F1F1F 一级标题与核心正文:页面大标题、卡片主标题、订单名称
$yjyf-text-regular #444444 二级正文:列表详情、输入框文本、表单标签 Key
$yjyf-text-secondary #888888 三级辅助说明:地址详情、副标题、备注说明
$yjyf-text-muted #AAAAAA 四级弱化信息:时间戳、订单流水号、提示角标
$yjyf-text-disabled #C8C7CC 禁用态/占位符:未填 Placeholder、已失效操作项
$yjyf-bg-page #F5F6F8 全局页面底色
$yjyf-bg-card #FFFFFF 通用卡片底色
$yjyf-border-color #F0F0F2 卡片分割线/细描边(1rpx)

2.2 字阶排版与可读性基线

严格禁止出现 19rpx、20rpx、21rpx 等不可读字号。移动端全平台标准字阶如下:

字阶角色 字号 (rpx / px) 字重 行高 (Line-Height) 适用范围
Display 巨幅价格/数字 64rpx ~ 72rpx (32~36px) 700 (Bold) 1.1 钱包余额大数字、关键金额
Title 页面/主标题 36rpx ~ 40rpx (18~20px) 700 (Bold) 1.3 Hero 头部大标题、弹窗标题
SubTitle 模块/卡片标题 30rpx ~ 32rpx (15~16px) 600 (SemiBold) 1.4 卡片头部标题、服务项目名称
Body 正文基准 28rpx (14px) 400 (Regular) 1.5 表单输入、正文段落、列表主体
Caption 辅助说明 24rpx (12px) 400 (Regular) 1.4 服务描述、次级元数据、标签文字
Micro 极限微说明 22rpx (11px) 400 (Regular) 1.3 绝对下限:仅允许订单流水号、时间戳

2.3 8rpx 间距模数阶梯

所有布局 margin、padding、gap 必须基于 8rpx (4px) 模数梯度,严禁出现 22rpx、28rpx、34rpx 等不规则数值:

模数 Token 间距数值 典型应用场景
$yjyf-space-xs 8rpx (4px) 图标与文字微间距、标签内边距
$yjyf-space-sm 16rpx (8px) 相邻行间距、卡片内子模块微间隔
$yjyf-space-md 24rpx (12px) 卡片内边距 (Padding)、列表项垂直间距
$yjyf-space-lg 32rpx (16px) 页面两侧边距 (Gutter)、大模块外间距
$yjyf-space-xl 48rpx (24px) 头部装饰区高度、提交按钮上下外边距

2.4 圆角与弥散投影

拒绝生硬生冷的纯黑深阴影,统一采用具有品牌暖调的柔和弥散投影:

资产 Token 规格 适用场景
卡片圆角 border-radius: 20rpx; 内容卡片、表单区块、列表项
弹窗/Sheet 圆角 border-radius: 32rpx 32rpx 0 0; 底部弹出半屏 Sheet
药丸/按钮圆角 border-radius: 999rpx; 核心 CTA 胶囊按钮、筛选 Chip
品牌卡片投影 box-shadow: 0 6rpx 20rpx rgba(240, 113, 13, 0.06); 强调卡片、订单卡片
底部悬浮栏投影 box-shadow: 0 -6rpx 24rpx rgba(0, 0, 0, 0.06); 底部固定结算条、吸底栏

3. 布局与多端适配规范

3.1 视口基准与单位准则

  • 基准分辨率:统一按照 750rpx 设计稿还原(对应 iPhone 6/7/8 基准宽 375px,即 1px = 2rpx)。
  • 单位使用规则:
    • 页面排版、间距、宽高优先使用 rpx。
    • 边框分割线推荐使用 1rpx(在真机高清屏呈现细腻发丝线)。
    • 极端微小固定尺寸(如微小红点指示器)可使用 px 避免奇偶舍入抖动。

3.2 导航体系与路由栈管控

核心规定:严禁滥用自定义 Tabbar 压栈

  • 原生 Tabbar 接管全局四大入口: 在 pages.json 中配置原生 tabBar,覆盖:“首页 (pages/index/index)”、“订单 (pages/order/list)”、“消息 (pages/message/message)”、“我的 (pages/mine/mine)”。
  • 跳转动作规范:
    • 四大主 Tab 之间切换必须使用 uni.switchTab(),禁止使用 uni.navigateTo()。
    • 二级子页面进入(如服务详情、下单页、地址列表)使用 uni.navigateTo()。
    • 登录失效或角色彻底切换(如从业主切换到师傅工作台)使用 uni.reLaunch() 清理当前页面栈。

3.3 顶部状态栏与底部安全区适配

顶部自定义导航(Header)动态计算

所有自定义 NavigationBar 页面(navigationStyle: "custom")必须动态提取状态栏与胶囊位置,严禁硬编码 top: 92rpx:

// 统一状态栏计算混入或工具方法
export function useNavMetrics() {
  const statusBarHeight = ref(20);
  const navBarHeight = ref(44);

  try {
    const sys = uni.getSystemInfoSync();
    if (sys.statusBarHeight) statusBarHeight.value = sys.statusBarHeight;
    // 获取微信小程序右上角胶囊按钮位置
    // #ifdef MP-WEIXIN
    const menu = uni.getMenuButtonBoundingClientRect();
    if (menu && menu.top) {
      navBarHeight.value = (menu.top - sys.statusBarHeight) * 2 + menu.height;
    }
    // #endif
  } catch (e) {}

  return { statusBarHeight, navBarHeight };
}

底部安全区(全面屏 Home 条防遮挡)

所有底部吸底固定操作栏(Fixed Bottom Bar)必须添加双重环境安全区内边距:

.fixed-bottom-bar {
  position: fixed;
  left: 0;
  right: 0;
  bottom: 0;
  height: 120rpx;
  /* 必须兼顾新旧语法 */
  padding-bottom: constant(safe-area-inset-bottom);
  padding-bottom: env(safe-area-inset-bottom);
  background: #FFFFFF;
  box-shadow: 0 -6rpx 24rpx rgba(0, 0, 0, 0.06);
  z-index: 99;
}

/* 同时页面底部必须有占位,避免内容被固定栏覆盖 */
.page-bottom-placeholder {
  height: calc(130rpx + constant(safe-area-inset-bottom));
  height: calc(130rpx + env(safe-area-inset-bottom));
}

3.4 通用页面布局骨架

每个页面的结构骨架必须规范统一,结构模板:

<template>
  <view class="yjyf-page">
    <!-- 1. 自定义顶部导航栏 (可选) -->
    <view class="yjyf-nav-header" v-if="customNav" :style="{ paddingTop: statusBarHeight + 'px' }">
      <view class="nav-content" :style="{ height: navBarHeight + 'px' }">
        <view class="nav-back-hotspot" @tap="goBack">
          <image class="nav-icon" src="/static/icons/common/icon-back.svg" />
        </view>
        <text class="nav-title">{{ pageTitle }}</text>
      </view>
    </view>

    <!-- 2. 主页面流式内容 -->
    <view class="yjyf-content">
      <!-- 骨架屏占位 -->
      <view class="skeleton-group" v-if="pageLoading">...</view>
      <!-- 真实卡片流 -->
      <view class="yjyf-card" v-else>...</view>
    </view>

    <!-- 3. 底部占位与吸底按钮 -->
    <view class="page-bottom-placeholder" v-if="showBottomBar"></view>
    <view class="fixed-bottom-bar" v-if="showBottomBar">...</view>
  </view>
</template>

4. 图标与视觉资产规范

4.1 核心图标禁令与替代规范

Caution

绝对禁止在正式 UI 中使用系统 Emoji 表情或汉字单字(如“厅、单、价、钱、信、服、微、券”)充当模块图标。

  • 微信一键登录按钮:必须配置微信标准矢量 SVG Logo,禁止使用白色圆圈加单字“微”。
  • 师傅工作台九宫格:必须替换为高质量、双色扁平微拟物图标(24×24px 视口,描边统一 1.5px/2px)。
  • 缩略图缺省处理:当服务项目未下发真实图片时,展示对应分类的标准插画,禁止使用纯代码截取文字 name.slice(0, 2)。

4.2 统一矢量图标规格

所有图标资源归档在 /static/icons/ 下,按业务域分包:

  • /static/icons/common/:通用箭头(arrow-right.svg)、返回(back.svg)、关闭、勾选。
  • /static/icons/service/:沙发、卫浴、灯具、开锁、窗帘等服务品类双色图标。
  • /static/icons/workbench/:大厅、订单、报价、钱包、信用、客服。

5. 触控热区与微交互规范

5.1 44×44px 最小触控热区

所有移动端可点击组件必须保证视觉面积或外层响应面积 ≥ 44×44px(88×88rpx):

  • 小图标按钮(如返回键、关闭键、步进器 +/-):如果视觉图标仅为 32rpx,必须通过 padding 或外层容器扩展热区至 88rpx。
/* 小图标按钮热区扩展最佳实践 */
.icon-btn-hotspot {
  min-width: 88rpx;
  min-height: 88rpx;
  display: flex;
  align-items: center;
  justify-content: center;
}

5.2 即时触控反馈(Hover State)

用户点击瞬间必须产生即时感知,消除操作“死机”错觉。页面所有交互组件必须添加 hover-class="clickable-hover":

.clickable-hover {
  opacity: 0.82;
  transform: scale(0.985);
  transition: all 0.15s ease;
}

5.3 动效时序与物理缓动

  • 微交互与点击响应:150ms ~ 200ms,缓动曲线 cubic-bezier(0.4, 0, 0.2, 1)。
  • 底部半屏弹窗 (Sheet) 展开/收起:250ms ~ 300ms。
  • 严禁无意义的跳动与耗时超过 400ms 的拖沓过渡。

6. 状态完备性体验规范 (8 态模型)

任何一个页面、列表或表单控件必须设计并处理完整的状态闭环:

  1. 默认态 (Default)
  2. 悬浮/点击态 (Active/Hover)
  3. 聚焦态 (Focus)
  4. 禁用态 (Disabled)
  5. 加载中 (Loading/Skeleton)
  6. 空数据 (Empty)
  7. 错误重试 (Error/Retry)
  8. 已完成/成功态 (Success)

6.1 页面级骨架屏与渐进加载

针对 pages/service/detail.vue、pages/order/detail.vue 等长数据页面,接口请求期间严禁全屏空白:

  • 使用骨架屏组件展示卡片轮廓与轻微呼吸动画(Shimmer Animation)。
  • 数据加载完毕后以 200ms 淡入效果完成替换。

6.2 友好空状态设计规范

列表无数据时,严禁只展示一行灰色小字 <text>暂无数据</text>:

  • 必须元素:清晰轻量插图(160×160rpx)+ 明确的说明文案(28rpx)+ 引导行动按钮(如“去逛逛热门服务”)。
<view class="yjyf-empty-state" v-if="!loading && !list.length">
  <image class="empty-icon" src="/static/images/empty/empty-order.svg" mode="aspectFit" />
  <text class="empty-title">暂无相关订单</text>
  <text class="empty-sub">师傅随叫随到,快速响应,售后无忧</text>
  <button class="empty-btn" @tap="goServiceList">去预约服务</button>
</view>

7. 表单与交互反馈规范

7.1 外部可见标签与占位符

  • 严禁纯靠 Placeholder 代替表单 Label:输入框左侧或上方必须有稳定的标题(如“服务地址”、“联系电话”),避免输入内容后用户忘记该项含义。
  • Placeholder 文本风格:简明清晰,字号与正文保持 28rpx 一致,颜色为 $yjyf-text-disabled (#C8C7CC)。

7.2 就近行内实时校验

  • 校验不通过时,除弹窗或 Toast 提示外,必须定位至当前输入框并高亮边框:
.input-item {
  border-bottom: 1rpx solid #F0F0F2;
}
.input-item.has-error {
  border-bottom-color: #E8331B;
}
.error-tip-text {
  font-size: 22rpx;
  color: #E8331B;
  margin-top: 8rpx;
}

7.3 提交防重防抖与加载反馈

  • 双重锁拦截:
    1. JS 逻辑锁:在发起请求前校验 if (submitting.value) return; submitting.value = true;。
    2. 视图锁:提交按钮绑定 :disabled="submitting" 并显式呈现原生 Loading 动效与“提交中...”文案。
  • 网络并发去重:统一请求层 request.js 针对同一特征接口(同一 URL + 参数)实行 500ms 快速防并发锁。

7.4 原生键盘与弹层避让

  • 手机号输入框必须设置 type="number" 或 type="tel",限制 maxlength="11"。
  • 金额输入框设置 type="digit"。
  • 长表单在小程序端必须配置 :adjust-position="true" 和 cursor-spacing="50",确保软键盘弹起时不遮挡当前输入行。

8. 工程化落地代码模版

8.1 全局 uni.scss 核心变量集

// ==========================================
// 优匠优服(YJYF)全局统一设计令牌 (Design Tokens)
// ==========================================

// 1. 品牌核心色彩
$yjyf-primary: #F0710D;
$yjyf-primary-light: #FFA93F;
$yjyf-primary-bg: #FFF7F0;
$yjyf-gradient-primary: linear-gradient(135deg, #FFA93F 0%, #F0710D 100%);

// 2. 状态反馈与辅助色
$yjyf-success: #2FA84F;
$yjyf-danger: #E8331B;
$yjyf-warning: #F98D25;
$yjyf-info: #4A7CFF;

// 3. 中性文字阶梯
$yjyf-text-main: #1F1F1F;
$yjyf-text-regular: #444444;
$yjyf-text-secondary: #888888;
$yjyf-text-muted: #AAAAAA;
$yjyf-text-disabled: #C8C7CC;

// 4. 背景与边框
$yjyf-bg-page: #F5F6F8;
$yjyf-bg-card: #FFFFFF;
$yjyf-border-color: #F0F0F2;

// 5. 字阶尺寸 (rpx)
$yjyf-font-hero: 44rpx;
$yjyf-font-title: 32rpx;
$yjyf-font-body: 28rpx;
$yjyf-font-sub: 24rpx;
$yjyf-font-micro: 22rpx;

// 6. 8rpx 间距阶梯
$yjyf-space-xs: 8rpx;
$yjyf-space-sm: 16rpx;
$yjyf-space-md: 24rpx;
$yjyf-space-lg: 32rpx;
$yjyf-space-xl: 48rpx;

// 7. 圆角与投影
$yjyf-radius-sm: 12rpx;
$yjyf-radius-md: 20rpx;
$yjyf-radius-lg: 32rpx;
$yjyf-radius-pill: 999rpx;
$yjyf-shadow-card: 0 6rpx 20rpx rgba(240, 113, 13, 0.06);
$yjyf-shadow-bar: 0 -6rpx 24rpx rgba(0, 0, 0, 0.06);

8.2 App.vue 全局基准与样式工具类

<style lang="scss">
/* 页面与全局元素重置 */
page {
  background-color: $yjyf-bg-page;
  font-family: -apple-system, BlinkMacSystemFont, 'PingFang SC', 'Helvetica Neue', Arial, sans-serif;
  color: $yjyf-text-main;
  box-sizing: border-box;
}

view, text, image, input, textarea, scroll-view {
  box-sizing: border-box;
}

/* 统一安全区工具类 */
.safe-area-bottom {
  padding-bottom: constant(safe-area-inset-bottom);
  padding-bottom: env(safe-area-inset-bottom);
}

/* 统一卡片基础类 */
.yjyf-card {
  margin: $yjyf-space-md $yjyf-space-lg 0;
  padding: $yjyf-space-md;
  background-color: $yjyf-bg-card;
  border-radius: $yjyf-radius-md;
  box-shadow: $yjyf-shadow-card;
}

/* 统一触控点击微反馈 */
.clickable-hover {
  opacity: 0.82;
  transform: scale(0.985);
  transition: all 0.15s ease;
}

/* 统一主操作胶囊大按钮 */
.yjyf-btn-primary {
  height: 88rpx;
  line-height: 88rpx;
  padding: 0 $yjyf-space-xl;
  border-radius: $yjyf-radius-pill;
  background: $yjyf-gradient-primary;
  color: #FFFFFF;
  font-size: $yjyf-font-body;
  font-weight: 600;
  text-align: center;
  box-shadow: 0 8rpx 20rpx rgba(240, 113, 13, 0.28);
  border: none;
  display: flex;
  align-items: center;
  justify-content: center;

  &[disabled] {
    opacity: 0.65;
    box-shadow: none;
  }
}
</style>

9. 交付前 10 步设计与体验自检清单

所有前端业务代码提交前,必须完成以下 10 项逐一核对:

  • 1. 路由栈健康度:Tab 切换是否全部使用 switchTab?是否存在页面跳转压栈 > 5 层且无法顺利返回的问题?
  • 2. 极小字排查:整页是否存在低于 22rpx 的微字?正文字号是否全部 ≥ 24rpx?
  • 3. 间距模数校验:所有外边距、内边距是否均能被 8rpx (4px) 整除?卡片左右外距是否统一为 32rpx?
  • 4. 44px 热区保障:所有返回键、图标按钮、步进器 +/- 物理点击区域是否达到 88×88rpx?
  • 5. 图标专业度:是否已彻底清除汉字单字(微、厅、单、钱)充当图标的遗留代码?
  • 6. 零白屏加载:网络延迟时,详情页是否有骨架屏或清晰的 Loading 动画?
  • 7. 空态导流闭环:列表暂无数据时,是否包含指引插画与“去下单 / 去浏览”跳转按钮?
  • 8. 全面屏避让:底部固定栏是否添加了 env(safe-area-inset-bottom)?内容区是否留出了防遮挡垫高区?
  • 9. 表单防重锁:所有提交按钮是否具备 :disabled、:loading 以及防快速双击保护?
  • 10. 真实数据绑定:页面中是否还存在写死的假数据(如硬编码的用户昵称、假电话)?