Spécification des composants

Cette page explique comment organiser un composant pour qu'il soit reconnu, prévisualisé et publié par la plateforme. Un composant n'est pas « un fichier », mais un dossier.

Fichier d'entrée

Le nom du dossier est le nom du composant. Le fichier d'entrée dépend du framework :

Framework	Fichier d'entrée	Remarque
Vue 2 / Vue 3	index.vue	Sa présence suffit à identifier Vue
React 17 / 18	index.jsx / index.tsx	default export obligatoire
Web Component	index.js	Le code source doit enregistrer un élément personnalisé

Ne dépendez pas à la fois de vue et de react, sinon la plateforme ne peut pas déterminer le framework.

Structure de répertoire recommandée

MyComponent/
├── index.vue          # Entrée (obligatoire)
├── README.md          # Propriétés, événements, exemples (recommandé)
├── comp.json          # Généré par la plateforme : __id__ / name / version
├── main.js            # Effets de bord globaux exécutés uniquement dans l'environnement d'aperçu (facultatif)
├── demo/
│   ├── index.vue      # Aperçu en petite fenêtre
│   └── full.vue       # Aperçu en plein écran
├── assets/
│   └── bg.png         # Ressources propres au composant
└── screenshot_mini.png # Vignette (généralement générée automatiquement)

demo/ est une convention et non une obligation : n'importe quel fichier .vue, .jsx ou .tsx du dossier peut être choisi comme fichier d'aperçu ; pour un Web Component, choisissez un .html.

Références aux ressources

Vue / React : utilisez des import avec des chemins relatifs, sans alias du type @/.

// Correct
import bg from "./assets/bg.png";

// Incorrect : la plateforme ne sait pas résoudre les alias du projet
import bg from "@/assets/bg.png";

Web Component : le code source est un ESM exécuté directement par le navigateur ; les images, polices et styles ne peuvent pas être importés. Utilisez new URL :

const bg = new URL("./assets/bg.png", import.meta.url);

Les src / href / srcset relatifs de la page HTML d'aperçu sont résolus par la plateforme par rapport au répertoire du composant ; il suffit d'écrire des chemins relatifs.

Déclaration des dépendances

Les dépendances tierces n'ont pas besoin d'être inscrites dans comp.json. La plateforme analyse les instructions import du code source pour les extraire automatiquement, puis les résout et les précompile depuis le node_modules de votre projet local.

Par conséquent, les paquets utilisés par le composant doivent déjà être installés localement.

npm install echarts

Le résultat de l'analyse s'affiche dans « Dépendances du composant » sur la page de téléversement ; vérifiez-le avant de publier.

demo et aperçu

• demo/index.vue : aperçu en petite fenêtre dans la carte de la liste.
• demo/full.vue : aperçu en plein écran sur la page de détail, recommandé.

L'aperçu d'un Web Component est du HTML ordinaire :

<!-- demo/mini.html -->
<my-element text="Hello"></my-element>
<script type="module" src="../index.js"></script>

Exigences :

• Contenir au moins un <script type="module">.
• Le script de module doit être dans <body> ; placé dans <head>, il est ignoré.
• Le src du script est résolu par rapport à l'emplacement du HTML lui-même.

Mise à l'échelle automatique de l'aperçu mini

La plateforme mesure automatiquement la largeur et la hauteur fixes du demo mini, puis l'adapte au panneau en contain (proportionnel, entièrement visible, centré). Aucune logique de mise à l'échelle n'est nécessaire dans le code du demo.

Il suffit de fixer le contenu aux dimensions de conception :

<template>
  <div class="mini-content">Contenu conçu en 320 × 240</div>
</template>

<style scoped>
.mini-content {
  width: 320px;
  height: 240px;
  overflow: hidden;
}
</style>

N'écrivez pas width: 100%

Si l'élément racine remplit le conteneur, la plateforme mesure la « taille naturelle » et le facteur d'échelle varie avec le contenu. Fixez simplement les dimensions de conception.

Rôle de main.js

main.js n'est exécuté que dans l'environnement d'aperçu, pour y placer des effets de bord globaux :

Vue 2 : enregistrer une bibliothèque UI

import Vue from "vue";
import Antd from "ant-design-vue";
import "ant-design-vue/dist/antd.css";

Vue.use(Antd);

Vue 3 : enregistrer via Vue.app fourni par la plateforme

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

Vue.app.use(ArcoVue);

React : placer les styles globaux

import "antd/dist/reset.css";

N'écrivez pas de styles globaux dans index.jsx : ils seraient exécutés lorsque l'utilisateur importe l'entrée du composant, provoquant des imports en double.

Conventions de nommage

• Unique dans un même espace (plateforme publique ou équipe).
• Seuls PascalCase (UserGrowthChart) et kebab-case (alipay-data-table) sont acceptés.
• _, le camelCase et un nom commençant par un chiffre ne sont pas acceptés.
• Il est conseillé de préfixer par domaine métier : nom-entreprise-domaine-nom-composant.

Limites de taille et de nombre

Élément	Limite
Fichier unique	3 Mo
Taille totale du composant	10 Mo
Nombre de fichiers	30 (sous-répertoires inclus)

En cas de dépassement, compressez d'abord les ressources statiques, ou remplacez les fichiers volumineux par des liens externes.

Exemple minimal

Vue

<!-- MyButton/index.vue -->
<template>
  <button class="my-button" @click="$emit('click')">{{ text }}</button>
</template>

<script>
export default {
  name: "MyButton",
  props: { text: { type: String, default: "Cliquez-moi" } }
};
</script>

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

React

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

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

Web Component

// MyElement/index.js
class MyElement extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `<span>${this.getAttribute("text") || "Hello"}</span>`;
  }
}

customElements.define("my-element", MyElement);

<!-- MyElement/demo/mini.html -->
<my-element text="Hello"></my-element>
<script type="module" src="../index.js"></script>

Liste de contrôle

• [ ] Le nom du dossier respecte les conventions de nommage et n'est pas déjà utilisé dans l'espace courant.
• [ ] Le fichier d'entrée existe ; pour React, il contient un default export.
• [ ] Les ressources utilisent des chemins relatifs ; un Web Component utilise new URL.
• [ ] Les dépendances utilisées sont installées localement.
• [ ] Le demo mini a des dimensions de conception fixes.
• [ ] Le HTML d'aperçu du Web Component contient <script type="module"> et celui-ci se trouve dans <body>.
• [ ] La taille et le nombre de fichiers ne dépassent pas les limites.

Prochaines étapes

• Envoyer le composant sur la plateforme : Téléverser et publier
• Continuer à itérer après la publication : Mise à jour et versions