大江前端指南

# 前端规范

# 一、开发规范

# 1. 分支管理

分支名 说明
master 线上稳定版本
dev 测试与预发布分支
feature-功能名 新功能开发临时分支，合并后删除（feature 为例举，请根据实际情况修改）

# 2. 目录组织

  • 通用组件：src/components/ 通用组件放在外层
  • 业务组件：就近原则 放在页面目录下，与页面相邻存放
src/views/order/
├─ index.vue
├─ components/
│  ├─ order-submit.vue
│  ├─ order-list.vue
│  └─ order-detail.vue

# 3. 命名规范

类型 命名方式 示例
目录 中划线法 home-order/
组件 中划线法 home-header
文件 中划线法 home-header.vue
变量 小驼峰法 listData, _privateData
常量 全大写 LIST_DATA
函数 小驼峰法 getList
CSS 类名 中划线法 home-header, _private-header

# 4. 提交与沟通

  • 提交前必须自测，禁止提交未测试的代码。
  • 提交描述简短明确，一句话解释改动内容。
  • 优先使用 Google / ChatGPT 寻找解决方案，确实无法解决再求助团队。

# 二、组件实践

# 1. 页面结构

推荐统一为目录式结构：/模块/页面/index.vue

不推荐平铺式结构：/模块/页面.vue

对比点 平铺式 目录式
规划私有逻辑 ❌ 不方便，同级只能共用 ✅ 可建立各自 hooks/utils
结构清晰程度 中，一目了然页面 高，页面成为一个功能模块
扩展性（加逻辑文件） 难，不好加 强，可以加 hooks/, utils/ 等
页面复杂度支持 差，适合简单页面 强，适合任何复杂页面
多人协作清晰度 一般，容易文件堆叠混乱 高，每个页面就是一个独立小仓库
# 推荐示例
页面名/
├─ index.vue
├─ hooks/
├─ utils/
├─ components/

# 错误示例
页面名/
├─ order.vue
├─ order-detail.vue
├─ hooks/     # 错误，hooks 内无法区分 order 和 order-detail,只能共用目录
├─ utils/     # 同上
├─ components/ # 同上

# 2. 二次封装（如 Element Plus）

  • PC 端：props / slots 尽量透传
  • 移动端：复制 90% props 与 slots，适当简化

# 3. props / slot 使用建议

  • props 过多推荐使用对象形式传入
  • 标题或文案类内容建议通过 slot 提高灵活性

# 4. 样式处理（原子化 CSS + SCSS）

项目使用 UnoCSS 原子化工具类 + SCSS 作为补充：

UnoCSS 使用顺序建议：布局 > 尺寸 > 排版 > 边框背景 > 效果

顺序 类型 示例
1 布局类 display, position, flex/grid
2 尺寸类 width, height, margin, padding
3 排版类 font-size, font-weight, line-height, text-*
4 背景与边框类 background, border
5 效果类 shadow, opacity

SCSS 用于：

  • 深层样式覆盖（:deep）
  • 定制 UI 库默认样式
.home-header {
  :deep(.wd-card) {
    padding: 16px;
    border-radius: 8px;
    background-color: #fff;
    .wd-card__title {
      font-size: 18px;
      color: #333;
    }
  }
}

# 三、Hooks 与 Utils

# 1. utils 使用规范

  • 定义：纯函数，无副作用，不依赖 Vue
  • 场景：格式转换、校验、接口参数构造、通用处理等
  • 命名建议：formatXxx, parseXxx
export function formatData(raw) {
  return {
    id: raw.id,
    title: raw.name,
    pages: raw.pageCount || 0
  };
}

# 2. hooks 使用规范

  • 定义：组合式逻辑封装，包含响应式状态、生命周期、有副作用
  • 场景：组件行为管理、逻辑复用
  • 命名建议：useXxx
export function useFlipBook() {
  const currentPage = ref(1);
  const totalPages = ref(10);
  const nextPage = () => {
    if (currentPage.value < totalPages.value) currentPage.value++;
  };
  return { currentPage, totalPages, nextPage };
}

# 3. hooks vs utils 区分

对比项 utils（工具函数） hooks（组合逻辑）
作用范围 纯数据处理 响应式逻辑/状态管理
是否带状态 否 是
是否依赖 Vue 否 是（仅在 setup 中使用）
是否副作用 无 有（DOM 操作、watch、异步等）

副作用：当函数除了返回结果外，还对外部环境产生了影响时，就叫副作用。 简单理解：副作用 = 改变了函数作用域以外的东西

# 4. 副作用 vs 耦合度

  • 耦合度：函数与外部环境的依赖关系
  • 副作用：函数对外部环境的改变
function saveToStorage(data) {
  localStorage.setItem("data", JSON.stringify(data)); // 改变了外部存储
}

function setTitle(title) {
  document.title = title; // 改变了 DOM
}

function loadData() {
  fetch("/api/data"); // 发起了请求
}

# 4. 目录结构建议

/views/book/detail/
├─ index.vue
├─ hooks/
│   └─ useBookDetail.js
├─ utils/
│   └─ formatBookData.js
├─ components/
│   └─ detail-card.vue

# 四、交互体验

# 1. UI 还原标准

UI 还原度需达到 99%，剩余 1% 可用于适配优化。

  • 移动端 1px 圆角/边框 建议用 1.5px 确保视觉表现
  • 布局尽量使用相对单位代替固定值

# 2. 操作反馈

  • 所有异步操作需有 loading / 成功 / 失败 提示
  • 按钮状态需实时反映当前操作中状态

# 3. 防止误操作

  • 按钮点击需防抖处理
  • 删除等敏感操作需弹窗二次确认

# 4. 文本溢出

  • 默认使用 text-overflow: ellipsis 做省略，防止破坏布局

原则以客户需求为准

# 五、注释与可读性

# 1. 注释要求

  • 函数、复杂逻辑必须注释
  • 注释需表述清晰，关键函数、复杂逻辑需添加步骤说明，便于快速理解

# 2. 示例

<template>
  <!-- 顶部导航栏 -->
  <div class="home-header">
    <slot name="title"></slot>
  </div>

  <!-- 内容区域 -->
  <div class="home-body">
    <!-- 项目列表 -->
    <div class="home-body-item">
      <slot name="content"></slot>
    </div>
  </div>

  <!-- 底部操作区 -->
  <div class="home-footer">
    <slot name="footer"></slot>
  </div>
</template>

<script setup>
// 处理按钮点击逻辑
function handleClick() {
  // 步骤1: 检测权限
  // 步骤2: 提交数据
  console.log("点击了按钮");
}
</script>

<script>
export default {
  name: "HomeHeader",
  props: {
    title: {
      type: String,
      default: "默认标题"
    }
  }
};
</script>

# 六、核心理念

👨‍💻 代码可读性 & 安全性第一！

  • 遵循规范，利于团队维护
  • 降本增效，提高效率
  • 传承文化，协同成长

如需自动化脚本、页面模板、结构生成等支持，可按需补充。

项目说明 →