跳到主要内容

组件开发指南

命名规范​

所有全局公共组件统一使用 c- 前缀命名，放置在 src/components/ 目录下。每个组件以独立文件夹存在，文件夹名与组件名一致。

components/
├── c-button/
│   └── c-button.vue
├── c-header/
│   └── c-header.vue
├── c-search/
│   └── c-search.vue
└── ...

组件清单​

基础交互​

组件说明
c-button通用按钮组件，封装样式变体
c-col-btn列布局按钮，用于底部操作栏
c-checkbox复选框组件
c-tabs选项卡切换组件
c-primary-tabs主选项卡组件
c-search搜索框组件
c-search-prod商品搜索框（带跳转逻辑）
c-password-input密码输入框（数字键盘）
c-password-keyboard自定义数字键盘
c-password-popup密码输入弹窗

表单相关​

组件说明
c-form-input-item表单项-输入框（含校验、图标）
c-form-uploader-item表单项-图片上传（支持多图、预览）
c-code-verify验证码输入与倒计时
c-address-select地址三级联动选择器

内容展示​

组件说明
c-prod商品卡片（图片、标题、价格）
c-order-prod订单商品行（含规格、数量）
c-order-steps订单状态步骤条
c-evaluate评价展示卡片
c-evaluation评价输入组件
c-info / c-info-2信息展示卡片
c-subtitle副标题组件
c-swiper轮播图组件
c-image图片组件（含懒加载）
c-empty空状态占位
c-parse富文本解析渲染

业务功能​

组件说明
c-header页面顶部导航栏（支持自定义标题、返回按钮）
c-tabbar自定义底部 Tabbar
c-login-form登录表单（手机号+密码/验证码）
c-mp-login-popup小程序登录弹窗
c-coupon-item优惠券卡片
c-sku-specs商品 SKU 规格选择弹窗
c-share-button分享按钮（区分平台）
c-live-status直播状态标签
c-top-fixed-video顶部固定视频播放器
c-bottom-wrapper底部安全区域适配

组件开发模板​

<template>
  <view class="c-xxx">
    <!-- 组件内容 -->
  </view>
</template>

<script setup lang="ts">
// Props 定义
interface Props {
  title?: string
  // ...
}
const props = withDefaults(defineProps<Props>(), {
  title: '',
})

// Emits 定义
const emit = defineEmits<{
  (e: 'change', value: string): void
}>()
</script>

<style lang="scss" scoped>
.c-xxx {
  // 样式
}
</style>

样式规范​

  • 所有组件样式使用 scoped，避免全局污染
  • 样式文件采用 SCSS 编写，变量定义在 common/style/public.scss
  • 尺寸单位使用 rpx，通过 rpx2px() 工具函数转换
  • 组件类名统一使用 c- 前缀，与组件名保持一致

全局样式​

src/common/style/public.scss 定义了全局公共样式变量和基础类：

  • 颜色变量：主色、辅助色、文字色、背景色等
  • 间距变量：统一的内外间距规范
  • 字体变量：字号、字重
  • 圆角变量：统一的圆角半径

典型组件示例​

c-sku-specs（SKU 规格选择）​

该组件是项目中较复杂的组件，负责商品规格的选择和价格联动：

// Props
interface Props {
  spuId: number          // 商品 SPU ID
  selectedSkuId?: number // 默认选中的 SKU
}

// 核心逻辑
// 1. 根据 spuId 加载规格数据
// 2. 用户选择规格后计算对应 SKU 的价格和库存
// 3. 通过 emit 通知父组件选中的 SKU 信息

c-login-form（登录表单）​

支持多种登录方式的表单组件：

  • 手机号 + 密码登录
  • 手机号 + 验证码登录
  • App 一键登录（号码认证）
  • 微信小程序授权登录

c-form-uploader-item（图片上传）​

// 核心功能
// - 支持多图上传（最大数量可配置）
// - 图片预览与删除
// - 调用 /app-api/infra/file/upload 接口
// - 上传进度展示

组件间通信​

项目中组件通信采用多种方式，根据场景选择：

方式场景示例
Props / Emits父子组件c-sku-specs 选择规格
uni.$emit / uni.$on跨层级/跨页面订单列表刷新、地址选择
Pinia Store全局状态共享用户信息、字典数据
provide / inject祖先→后代页面级配置下发

�������ָ��

���ĵ����ڽ����У������ڴ���