开发规范

版本说明

时间	修改人	备注
2025-04-24	YG	补充文档

命名规范

文件命名

1. 组件文件：使用 PascalCase 命名，如 UserProfile.vue
2. 页面文件：使用 三级目录 命名，如 /pages/user/index.vue
3. 工具函数文件：使用 camelCase 命名，如 formatDate.js
4. 样式文件：使用 kebab-case 命名，如 common-style.scss

变量命名

1. 普通变量：使用 camelCase，如 userName
2. 常量：使用大写下划线，如 MAX_COUNT
3. 私有变量：使用下划线前缀，如 _privateVar
4. 组件引用：使用 PascalCase，如 UserProfile
5. 布尔值：使用 is/has/should 前缀，如 isVisible 、 hasPermission

函数命名

1. 普通函数：使用动词前缀，如 getUserInfo 、 handleSubmit
2. 事件处理函数：使用 handle/on 前缀，如 handleClick 、 onSubmit
3. Getter 函数：使用 get 前缀，如 getTotal
4. 异步函数：使用 async 前缀或 fetch/load 等，如 fetchUserData

Vue3 编码规范

组件定义

1. 使用 <script setup> 语法糖定义组件

<script setup>
import { ref, computed } from 'vue'

// 组件逻辑
</script>

2. 组件属性定义使用 defineProps 和 defineEmits

<script setup>
// 定义props
const props = defineProps({
  title: {
    type: String,
    required: true
  },
  count: {
    type: Number,
    default: 0
  }
})

// 定义事件
const emit = defineEmits(['update', 'delete'])

// 触发事件
const handleClick = () => {
  emit('update', { id: 1 })
}
</script>

3. 组件暴露方法使用 defineExpose

<script setup>
import { ref } from 'vue'

const count = ref(0)

const increment = () => {
  count.value++
}

// 暴露方法给父组件调用
defineExpose({
  increment
})
</script>

组件结构

组件应遵循以下结构：

<template>
  <!-- 模板内容 -->
</template>

<script setup>
// 导入
import { ref, computed, watch, onMounted } from 'vue'
import ComponentA from './ComponentA.vue'

// 属性定义
const props = defineProps({...})
const emit = defineEmits([...])

// 响应式数据
const count = ref(0)
const name = ref('')

// 计算属性
const doubleCount = computed(() => count.value * 2)

// 方法
const handleClick = () => {...}

// 生命周期钩子
onMounted(() => {...})

// 侦听器
watch(count, (newVal, oldVal) => {...})

// 暴露方法
defineExpose({...})
</script>

<style lang="scss" scoped>
/* 样式内容 */
</style>

响应式数据

1. 使用 ref 定义简单类型响应式数据
2. 使用 reactive 定义复杂类型响应式数据
3. 使用 computed 定义计算属性
4. 使用 watch 或 watchEffect 监听数据变化

<script setup>
import { ref, reactive, computed, watch } from 'vue'

// 简单类型
const count = ref(0)

// 复杂类型
const user = reactive({
  name: '张三',
  age: 25
})

// 计算属性
const doubleCount = computed(() => count.value * 2)

// 监听数据变化
watch(count, (newVal, oldVal) => {
  console.log(`count changed from ${oldVal} to ${newVal}`)
})
</script>

生命周期钩子

使用 Composition API 的生命周期钩子：

<script setup>
import { onMounted, onUpdated, onUnmounted, onBeforeUnmount } from 'vue'

onMounted(() => {
  console.log('组件已挂载')
})

onUpdated(() => {
  console.log('组件已更新')
})

onBeforeUnmount(() => {
  console.log('组件即将卸载')
})

onUnmounted(() => {
  console.log('组件已卸载')
})
</script>

自定义 Hooks

将可复用的逻辑抽离为自定义 Hooks：

// hooks/useCounter.js
import { ref } from 'vue'

export function useCounter(initialValue = 0) {
  const count = ref(initialValue)
  
  const increment = () => {
    count.value++
  }
  
  const decrement = () => {
    count.value--
  }
  
  return {
    count,
    increment,
    decrement
  }
}

使用自定义 Hooks：

<script setup>
import { useCounter } from '@/hooks/useCounter'

const { count, increment, decrement } = useCounter(10)
</script>

样式规范

样式命名

1. 使用 BEM 命名规范：Block-Element-Modifier
   • Block：功能独立的组件，如 .card
   • Element：Block 的组成部分，如 .card__title
   • Modifier：Block 或 Element 的状态或变体，如 .card--large
2. 避免使用 ID 选择器定义样式
3. 避免使用标签选择器定义样式
4. 避免使用 !important

样式组织

1. 使用 SCSS 预处理器
2. 使用 scoped 属性限制样式作用域
3. 全局样式放在 assets/styles 目录下
4. 组件样式使用 <style scoped> 定义

<style lang="scss" scoped>
.user-card {
  &__header {
    font-size: 18px;
    font-weight: bold;
  }
  
  &__content {
    padding: 10px;
  }
  
  &--active {
    border: 1px solid #f00;
  }
}
</style>

响应式设计

1. 使用 rpx 作为主要尺寸单位
2. 使用 flex 布局实现响应式设计
3. 使用媒体查询适配不同设备

.container {
  display: flex;
  flex-direction: column;
  
  @media screen and (min-width: 768px) {
    flex-direction: row;
  }
}

UniApp 特有规范

条件编译

使用条件编译处理平台差异：

<template>
  <view>
    <!-- #ifdef MP-WEIXIN -->
    <button open-type="share">微信分享</button>
    <!-- #endif -->
    
    <!-- #ifdef H5 -->
    <button @click="shareToH5">H5分享</button>
    <!-- #endif -->
  </view>
</template>

<script setup>
// #ifdef H5
const shareToH5 = () => {
  // H5分享逻辑
}
// #endif
</script>

页面配置

在 pages.json 中合理配置页面：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",
        "enablePullDownRefresh": true
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarBackgroundColor": "#F8F8F8",
    "backgroundColor": "#F8F8F8"
  },
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#5d87ff",
    "borderStyle": "black",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "static/tabs/home.png",
        "selectedIconPath": "static/tabs/home-active.png"
      }
    ]
  }
}

分包加载

对于较大的小程序，使用分包加载：

{
  "pages": [
    "pages/index/index"
  ],
  "subPackages": [
    {
      "root": "pagesA",
      "pages": [
        "list/index",
        "detail/index"
      ]
    }
  ]
}

小程序生命周期

在 UniApp 中使用小程序生命周期：

<script setup>
import { onLoad, onShow, onHide, onUnload } from '@dcloudio/uni-app'

onLoad((options) => {
  console.log('页面加载', options)
})

onShow(() => {
  console.log('页面显示')
})

onHide(() => {
  console.log('页面隐藏')
})

onUnload(() => {
  console.log('页面卸载')
})
</script>

Git 提交规范

分支管理

1. master / main：主分支，保持稳定可发布状态
2. dev：开发分支，最新开发代码
3. feature/*：功能分支，如 feature/login
4. bugfix/*：Bug修复分支
5. release/*：发布分支

提交信息

使用 Angular 提交规范：

<type>(<scope>): <subject>
<body>

类型（type）：

• feat：新功能
• fix：Bug修复
• docs：文档更新
• style：代码格式（不影响代码运行）
• refactor：重构
• perf：性能优化
• test：测试
• chore：构建过程或辅助工具变动 示例：

feat(login): 添加微信登录功能
实现微信小程序一键登录功能，包括获取用户信息和手机号