業務元件開發指南

對於包含第三方依賴和靜態資源的複雜業務元件，需要遵循特定的開發標準以確保可移植性。

開發標準

資源引用

所有依賴資源必須使用相對路徑匯入：

<script>
// ✅ 正確：相對路徑
import bgIcon from './assets/bg.png'

// ❌ 錯誤：路徑別名
import bgIcon from '@/assets/bg.png'
</script>

依賴宣告

元件使用的第三方依賴不需要打包，也不需要在 comp.json 中宣告。系統會掃描原始碼中的 import 語句並提取依賴資訊。

依賴是從本機專案的 node_modules 解析並預先編譯後供預覽使用的，因此元件用到的依賴必須已在本機安裝（npm install <pkg>），否則預覽會提示依賴缺失。

CSS 預處理器

支援 SCSS 預處理器。用法：

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

完整範例

以下是一個使用 ECharts 的業務元件範例：

目錄結構

框架說明：此範例展示的是 Vue 元件。對於 React 元件，將 index.vue 替換為 index.jsx（或 index.tsx），並在 demo/ 資料夾中使用 .jsx 檔案。

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: 'User Growth Trend'
    },
    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 User Growth Chart

A line chart component displaying user growth trends, implemented based on ECharts.

## Properties

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| title | String | No | Chart title, default "User Growth Trend" |
| data | Array | Yes | Chart data, format [{ date: '2024-01', value: 100 }] |

## Usage Example

```vue
<template>
  <UserGrowthChart
    title="Monthly Active Users"
    :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>

Dependencies

• 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: 'Jan', value: 120 },
        { date: 'Feb', value: 200 },
        { date: 'Mar', value: 150 }
      ]
    }
  }
}
</script>

demo/full.vue（全螢幕預覽）

<template>
  <div style="width: 100%; height: 500px; padding: 20px;">
    <UserGrowthChart
      title="2024 User Growth Trend"
      :data="data"
    />
  </div>
</template>

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

export default {
  components: { UserGrowthChart },
  data() {
    return {
      data: [
        { date: 'Jan', value: 1200 },
        { date: 'Feb', value: 2000 },
        { date: 'Mar', value: 1500 },
        { date: 'Apr', value: 2800 },
        { date: 'May', value: 3200 },
        { date: 'Jun', value: 4000 }
      ]
    }
  }
}
</script>

常見問題

Q：上傳後元件預覽顯示錯誤？

A：請檢查以下幾點：

1. 元件所需的依賴是否已在本機安裝
2. 資源路徑是否使用相對路徑
3. 瀏覽器控制台是否顯示具體錯誤訊息

Q：如何偵錯元件？

A：在上傳前先在本機開發環境中完成偵錯。上傳後，點擊預覽頁上的「重新整理」即可查看最新效果。

Q：元件樣式被全域樣式污染？

A：請務必使用 scoped 屬性隔離樣式。如果需要覆蓋 UI 框架樣式，請使用 :deep() 選擇器。