Guide de développement de composants métier

Pour les composants métier complexes qui incluent des dépendances tierces et des ressources statiques, des normes de développement spécifiques doivent être suivies pour garantir la portabilité.

Normes de développement

Références de ressources

Toutes les ressources dépendantes doivent être importées en utilisant des chemins relatifs :

<script>
// ✅ Correct : chemin relatif
import bgIcon from './assets/bg.png'

// ❌ Erreur : alias de chemin
import bgIcon from '@/assets/bg.png'
</script>

Déclaration des dépendances

Les dépendances tierces utilisées par les composants n'ont pas besoin d'être empaquetées, et ne sont pas non plus déclarées dans comp.json. Le système analyse les instructions import de vos fichiers sources et extrait les informations de dépendance.

Comme les dépendances sont résolues depuis le node_modules de votre projet local puis précompilées pour l'aperçu, chaque dépendance utilisée par le composant doit déjà être installée localement (npm install <pkg>) ; sinon l'aperçu signale une dépendance manquante.

Préprocesseurs CSS

Les préprocesseurs SCSS sont pris en charge. Utilisation :

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

Exemple complet

Voici un exemple de composant métier utilisant ECharts :

Structure de répertoire

Remarque sur le framework : cet exemple montre un composant Vue. Pour les composants React, remplacez index.vue par index.jsx (ou index.tsx), et utilisez des fichiers .jsx dans le dossier demo/.

UserGrowthChart/
├── index.vue          # Entrée du composant
├── README.md          # Documentation du composant
├── comp.json          # Fichier de configuration
└── demo/
    ├── index.vue      # Exemple d'aperçu en petite fenêtre
    └── full.vue       # Exemple d'aperçu en plein écran

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 (Aperçu en petite fenêtre)

```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 (Aperçu en plein écran)

<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>

FAQ

Q : L'aperçu du composant affiche des erreurs après le téléversement ?

R : Vérifiez ce qui suit :

1. Si les dépendances requises du composant sont installées localement
2. Si les chemins de ressources utilisent des chemins relatifs
3. Si la console du navigateur affiche des messages d'erreur spécifiques

Q : Comment déboguer un composant ?

R : Effectuez un débogage complet dans l'environnement de développement local avant le téléversement. Après le téléversement, cliquez sur « Actualiser » sur la page d'aperçu pour voir les derniers effets.

Q : Les styles du composant sont pollués par les styles globaux ?

R : Utilisez toujours l'attribut scoped pour isoler les styles. Si vous devez remplacer les styles du framework UI, utilisez le sélecteur :deep().