Guide de téléversement de composants

Le téléversement de composants sur comp-hub ne prend que trois étapes : sélectionner le dossier, configurer l'aperçu et cliquer sur publier.

Prérequis

Avant le téléversement, assurez-vous que le composant répond aux conditions suivantes :

1. Format de dossier : les composants doivent exister sous forme de dossiers, le nom du dossier étant le nom du composant
2. Fichier d'entrée : un fichier d'entrée est requis — index.vue pour les composants Vue, index.jsx / index.js / index.tsx pour les composants React
3. Exécution indépendante : les composants doivent être autonomes, avec les dépendances importées via des chemins relatifs

Structure de répertoire recommandée :

MyComponent/           # Nom du composant
├── index.vue         # Fichier d'entrée (obligatoire)
├── README.md         # Documentation du composant (recommandée)
├── comp.json         # Fichier de configuration (généré automatiquement)
└── assets/           # Ressources statiques (le cas échéant)
    └── logo.png

Limites de téléversement

Les limites suivantes s'appliquent lors du téléversement de composants :

Limite	Description
Taille de fichier individuelle	Chaque fichier ne doit pas dépasser 3 Mo. Compressez les fichiers volumineux (audio, vidéo, images haute résolution) avant de les téléverser
Taille totale	Tous les fichiers du composant combinés ne doivent pas dépasser 10 Mo
Nombre de fichiers	Le nombre total de fichiers (y compris les sous-répertoires) ne doit pas dépasser 30

Si vous voyez une erreur de taille de fichier lors de la soumission, vérifiez les ressources statiques trop volumineuses et compressez-les ou supprimez-les avant de réessayer.

Support des frameworks UI

Les aperçus de composants peuvent s'exécuter sur Vue ou React. Tous les frameworks UI de l'un ou l'autre écosystème peuvent être utilisés directement.

Comment le framework est détecté

Vous ne déclarez le framework nulle part. comp-hub le détecte à partir des dépendances trouvées dans le code source du composant :

• Le composant importe vue → il est traité comme un composant Vue
• Le composant importe react → il est traité comme un composant React
• Un composant qui importe à la fois vue et react → le framework ne peut pas être déterminé, et la page de téléversement ne pourra ni le vérifier ni le rendre

Composants Vue

Pour les composants Vue, ajoutez un fichier main.js dans le répertoire racine du composant et enregistrez le framework UI souhaité :

Vue 2

import Vue from 'vue';
import Antd from 'ant-design-vue';
import 'ant-design-vue/dist/antd.css';
Vue.use(Antd);

Vue 3

Remarque : Vue 3 n'exporte pas d'instance app par défaut. Ici, Vue.app est créé en interne par l'outil et monté sur Vue. Cela diffère de l'approche officielle consistant à appeler createApp() soi-même — utilisez-le simplement directement.

import * as Vue from 'vue'
import ArcoVue from '@arco-design/web-vue';
import '@arco-design/web-vue/dist/arco.css';

Vue.app.use(ArcoVue);

Composants React

Les composants React n'ont pas besoin de fichier main.js, et les dépendances ne sont pas déclarées dans comp.json — importez-les simplement dans votre composant comme d'habitude :

import { Button, Card } from "antd";
import { LikeOutlined } from "@ant-design/icons";

export default function MyCard() {
  return <Card>Hello</Card>;
}

Lorsque vous sélectionnez le dossier du composant sur la page de téléversement, comp-hub analyse les instructions import de vos fichiers sources, résout chaque dépendance depuis le node_modules de votre projet local et la précompile pour l'aperçu. Cela signifie :

• Chaque dépendance utilisée par le composant doit déjà être installée dans le projet local (npm install <pkg>) ; sinon l'aperçu signale une dépendance manquante
• Les dépendances détectées et leurs versions sont listées dans l'onglet Dépendances de la zone de configuration, où vous pouvez les vérifier avant de publier
• Le fichier d'entrée doit comporter un export par défaut ; un composant qui n'a que des exports nommés échoue avec Component has no default export
• React 18 (react-dom/client) et React 17 (react-dom) sont tous deux pris en charge — la bonne API de rendu est choisie automatiquement

Conventions de nommage

• Les noms de composants sont uniques au sein d'un même espace (le hub public, ou une équipe) et ne peuvent pas dupliquer des noms existants
• Seuls deux formats sont acceptés : PascalCase (UserGrowthChart) ou kebab-case (alipay-data-table)
• Non pris en charge : les underscores _, le camelCase (myComponent) et les noms commençant par un chiffre
• Le nommage par préfixe est recommandé, par exemple : company-business-domain-component-name : alipay-data-table

Gestion des composants dupliqués

La plateforme effectue une détection de similarité sur les composants téléversés. S'il est jugé comme un composant dupliqué :

• Il n'entrera pas dans les listes publiques telles que « Recommandé », « Populaire », « Récent »
• Il ne peut être consulté et géré que dans « Mes composants »
• Il apparaîtra dans la liste des composants similaires recommandés
• Les mises à jour ne bénéficient pas non plus de la pondération de recommandation

Il est recommandé de vérifier s'il existe des composants fonctionnellement similaires avant le téléversement afin d'éviter de réinventer la roue.

Étapes de téléversement

1. Entrer sur la page de téléversement

Après avoir démarré comp-hub, cliquez sur « Téléverser un composant » dans le menu de gauche.

2. Sélectionner le composant

• L'arborescence de fichiers à gauche affiche le répertoire spécifié par dir dans .comphub.json ou .comphub.js
• Accédez au dossier du composant et sélectionnez-le
• Cliquez sur « Sélectionner » pour confirmer

3. Configurer l'aperçu

La page de téléversement est divisée en zones supérieure et inférieure :

Zone d'aperçu supérieure

• Affichage en temps réel de l'effet de rendu du composant
• Prise en charge de l'actualisation et du changement de couleur de fond

Zone de configuration inférieure

• Aperçu en petite fenêtre : choisissez le fichier à rendre sur la page de liste — par convention demo/index.vue (ou le composant lui-même)
• Aperçu en plein écran : choisissez le fichier à rendre sur la page de détail — par convention demo/full.vue (recommandé)
• Dépendances : dépendances détectées automatiquement dans votre code source, avec leurs versions locales ; vérifiez-les ici
• Remarques : brève description de la fonction et des scénarios applicables du composant
• Informations supplémentaires : description détaillée, prend en charge les mots-clés de recherche

N'importe quel fichier se terminant par .vue, .jsx ou .tsx dans le dossier du composant peut être choisi comme fichier d'aperçu — le dossier demo/ est une convention, pas une obligation. Pour les composants React, utilisez des fichiers .jsx / .tsx.

4. Générer la configuration

Cliquez sur le bouton « Générer la configuration », et le système créera automatiquement un fichier comp.json contenant :

{
  "__id__": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "MyComponent",
  "version": "1.0.0"
}

comp.json ne contient que ces trois champs. Le champ __id__ est rempli par le serveur après la première publication réussie — ne le modifiez pas manuellement. Les dépendances sont détectées dans votre code source, pas dans ce fichier.

5. Publier le composant

Après avoir confirmé que la configuration est correcte, cliquez sur le bouton « Publier » pour terminer le téléversement.

Exemple minimal

Voici un composant téléversable le plus simple possible :

<!-- MyButton/index.vue -->
<template>
  <button class="my-button" @click="handleClick">
    {{ text }}
  </button>
</template>

<script>
export default {
  name: 'MyButton',
  props: {
    text: {
      type: String,
      default: 'Click Me'
    }
  },
  methods: {
    handleClick() {
      this.$emit('click')
    }
  }
}
</script>

<style scoped>
.my-button {
  padding: 8px 16px;
  background: #409eff;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}
</style>

Exemple React minimal

// MyCard/index.jsx
import { Card } from "antd";

export default function MyCard({ title = "Hello" }) {
  return <Card>{title}</Card>;
}

antd doit être installé dans le projet local ; l'export default est obligatoire.

Bonnes pratiques

• Rédigez un README : explication détaillée de l'utilisation, des propriétés, des événements et des exemples du composant
• Fournissez une démo : créez un répertoire demo pour présenter l'utilisation typique du composant
• Versionnage sémantique : suivez la spécification major.minor.patch
• Gérez les dépendances : les dépendances tierces doivent uniquement être installées localement, sans être empaquetées dans le composant