业务组件开发指南

对于包含第三方依赖、静态资源的复杂业务组件，需要遵循特定的开发规范以确保可移植性。

开发规范

资源引用

所有依赖的资源必须使用相对路径引入：

<script>
// ✅ 正确：相对路径
import bgIcon from './assets/bg.png'

// ❌ 错误：路径别名
import bgIcon from '@/assets/bg.png'
</script>

依赖声明

组件使用的第三方依赖无需打包，系统会自动识别组件中的 import 语句并提取依赖信息。

UI 框架支持

目前平台支持以下 UI 框架：

框架	Vue 版本	引入方式
Element UI	Vue 2	自动全局引入
Element Plus	Vue 3	自动全局引入

使用时无需手动导入，可直接在模板中使用：

<template>
  <el-button type="primary">点击</el-button>
  <el-input v-model="value" />
</template>

CSS 预处理器

支持 SCSS 预处理器，使用方式：

<style lang="scss" scoped>
.component {
  &__title {
    font-size: 16px;
    
    &:hover {
      color: #409eff;
    }
  }
}
</style>

完整示例

以下是一个使用 ECharts 的业务组件示例：

目录结构

UserGrowthChart/
├── index.vue          # 组件入口
├── README.md          # 组件文档
├── comp.json          # 配置文件
└── demo/
    ├── index.vue      # 小窗预览示例
    └── full.vue       # 全屏预览示例

index.vue

<template>
  <div class="chart-container">
    <h3 class="chart-title">{{ title }}</h3>
    <div ref="chartRef" class="chart"></div>
  </div>
</template>

<script>
import * as echarts from 'echarts'

export default {
  name: 'UserGrowthChart',
  props: {
    title: {
      type: String,
      default: '用户增长趋势'
    },
    data: {
      type: Array,
      required: true
    }
  },
  data() {
    return {
      chart: null
    }
  },
  mounted() {
    this.initChart()
    window.addEventListener('resize', this.handleResize)
  },
  beforeDestroy() {
    window.removeEventListener('resize', this.handleResize)
    this.chart?.dispose()
  },
  methods: {
    initChart() {
      this.chart = echarts.init(this.$refs.chartRef)
      this.chart.setOption({
        xAxis: { type: 'category', data: this.data.map(d => d.date) },
        yAxis: { type: 'value' },
        series: [{
          data: this.data.map(d => d.value),
          type: 'line',
          smooth: true
        }]
      })
    },
    handleResize() {
      this.chart?.resize()
    }
  }
}
</script>

<style lang="scss" scoped>
.chart-container {
  width: 100%;
  height: 100%;
  padding: 16px;
  box-sizing: border-box;
  
  .chart-title {
    margin: 0 0 12px;
    font-size: 16px;
    color: #333;
  }
  
  .chart {
    width: 100%;
    height: calc(100% - 40px);
  }
}
</style>

README.md

# UserGrowthChart 用户增长图表

展示用户增长趋势的折线图组件，基于 ECharts 实现。

## 属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| title | String | 否 | 图表标题，默认"用户增长趋势" |
| data | Array | 是 | 图表数据，格式 [{ date: '2024-01', value: 100 }] |

## 使用示例

```vue
<template>
  <UserGrowthChart
    title="月度活跃用户"
    :data="growthData"
    style="height: 400px"
  />
</template>

<script setup>
import UserGrowthChart from './UserGrowthChart/index.vue'

const growthData = [
  { date: '2024-01', value: 1200 },
  { date: '2024-02', value: 1500 },
  { date: '2024-03', value: 1800 }
]
</script>

依赖

• echarts: ^5.0.0

### demo/index.vue（小窗预览）

```vue
<template>
  <div style="width: 320px; height: 240px;">
    <UserGrowthChart :data="data" />
  </div>
</template>

<script>
import UserGrowthChart from '../index.vue'

export default {
  components: { UserGrowthChart },
  data() {
    return {
      data: [
        { date: '1月', value: 120 },
        { date: '2月', value: 200 },
        { date: '3月', value: 150 }
      ]
    }
  }
}
</script>

demo/full.vue（全屏预览）

<template>
  <div style="width: 100%; height: 500px; padding: 20px;">
    <UserGrowthChart
      title="2024年用户增长趋势"
      :data="data"
    />
  </div>
</template>

<script>
import UserGrowthChart from '../index.vue'

export default {
  components: { UserGrowthChart },
  data() {
    return {
      data: [
        { date: '1月', value: 1200 },
        { date: '2月', value: 2000 },
        { date: '3月', value: 1500 },
        { date: '4月', value: 2800 },
        { date: '5月', value: 3200 },
        { date: '6月', value: 4000 }
      ]
    }
  }
}
</script>

常见问题

Q：组件上传后预览报错？

A：检查以下几点：

1. 本地是否安装了组件所需的依赖
2. 资源路径是否为相对路径
3. 浏览器控制台是否有具体错误信息

Q：如何调试组件？

A：在本地开发环境中完成调试后再上传。上传后可在预览页面点击「刷新」查看最新效果。

Q：组件依赖的样式被全局污染？

A：建议始终使用 scoped 属性隔离样式。如需覆盖 UI 框架样式，使用 :deep() 选择器。