Mécanisme de correspondance des dépendances

comp-hub utilise une correspondance intelligente des dépendances pour permettre aux composants de s'adapter à différents environnements locaux.

Pourquoi la correspondance des dépendances est nécessaire

Lorsque les composants sont prévisualisés localement, ils doivent charger les dépendances déjà installées dans le projet local. Mais la réalité est souvent :

• Le composant dépend de echarts 5.2.0
• Localement installé est echarts 5.0.0

Si une stricte cohérence des versions était exigée, de nombreux composants ne pourraient pas être prévisualisés normalement. Par conséquent, la plateforme fournit des règles flexibles de correspondance des dépendances.

Règles de correspondance

Dans « Paramètres → Règle d'aperçu », la section Dépendances permet de configurer une règle de correspondance pour chaque dépendance du projet (dependencies et devDependencies) :

Règle	Description	Scénario applicable	Indicateur de couleur
Auto	Aucune restriction de version, rendu avec l'environnement local actuel	Par défaut, garde tout affichable	⚪ Gris (par défaut)
Uniquement installé	Tant que la dépendance est installée localement, peu importe la version	Aperçu rapide, environnement non-production	🟢 Vert (le plus permissif)
Version majeure	Le numéro de version majeure doit correspondre	Équilibre compatibilité et stabilité	🔵 Bleu
Version majeure.mineure	Les numéros de version majeure et mineure doivent correspondre	Scénarios sensibles aux versions	🟠 Orange (modérément strict)
Correspondance exacte	Le numéro de version doit être exactement le même	Contrôle strict des versions	🔴 Rouge (le plus strict)

Les règles proviennent du package.json de votre projet et sont aussi utilisées lors de la précompilation des dépendances pour l'aperçu.

Conseil : chaque règle de correspondance sur la page de paramètres possède un indicateur à point coloré devant elle, permettant d'identifier rapidement le niveau de stricteur de la correspondance.

Exemple

En supposant que le composant dépend de echarts: 5.2.3 :

Version locale	Auto	Uniquement installé	Version majeure	Majeure.mineure	Correspondance exacte
5.0.0	✅ Utiliser	✅ Utiliser	✅ Utiliser	❌ Ignorer	❌ Ignorer
5.2.0	✅ Utiliser	✅ Utiliser	✅ Utiliser	❌ Ignorer	❌ Ignorer
5.2.3	✅ Utiliser	✅ Utiliser	✅ Utiliser	✅ Utiliser	✅ Utiliser
6.0.0	✅ Utiliser	✅ Utiliser	❌ Ignorer	❌ Ignorer	❌ Ignorer
Non installée	❌ Ignorer	❌ Ignorer	❌ Ignorer	❌ Ignorer	❌ Ignorer

Comportement par défaut

• Les dépendances sans règle configurée manuellement utilisent par défaut Auto (aucune restriction de version, rendu avec l'environnement local actuel)
• Une dépendance pas du tout installée localement ne correspond à aucune règle — installez-la puis actualisez
• Le framework est détecté à partir des dépendances propres du composant : un composant qui importe vue est rendu comme Vue, un composant qui importe react est rendu comme React (React 17 et 18 sont pris en charge) ; un composant qui importe les deux ne peut pas être rendu

Résolution des problèmes de composant non affiché

Lorsque vous ne voyez pas un composant dans la liste « Recommandé », cela peut être dû à une non-correspondance des dépendances. Suivez ces étapes pour résoudre le problème :

1. Passez au filtre « Tout »

Passez la condition de filtre en haut du marché des composants à « Tout » pour voir si le composant est affiché.

2. Vérifiez l'état des dépendances

Cliquez sur la carte du composant et vérifiez l'état de correspondance des dépendances sur la page d'aperçu :

• 🟢 Vert : dépendance correspondante avec succès
• 🔴 Rouge : non-correspondance ou dépendance manquante
• ⚠️ Jaune : différences de version de dépendance mais peut tenter de s'exécuter

3. Installez les dépendances manquantes

Si des dépendances manquantes sont signalées, installez-les dans le projet local :

npm install <package-name>

Actualisez la page après l'installation.

4. Ajustez les règles de correspondance

Si les versions des dépendances diffèrent mais n'affectent pas la fonctionnalité, vous pouvez assouplir les règles de correspondance dans « Paramètres → Règle d'aperçu ».

Bonnes pratiques

Auteurs de composants

• Énoncez clairement les exigences de dépendances dans README.md
• Utilisez autant que possible des versions de dépendances avec une bonne compatibilité
• Évitez de vous fier à des fonctionnalités de version mineure spécifiques

Utilisateurs de composants

• Maintenez les versions de dépendances locales relativement récentes pour améliorer la compatibilité des composants
• Pour les dépendances non critiques, vous pouvez utiliser la correspondance « Uniquement installé » ou « Version majeure »
• En cas de problèmes, vérifiez en priorité les messages d'erreur de la console

FAQ

Q : Pourquoi le composant indique « Dépendance manquante » alors qu'il est déjà installé localement ?

R : Raisons possibles :

1. Incohérence d'orthographe du nom de la dépendance (par exemple, echarts vs ECharts)
2. La dépendance est installée dans le node_modules d'un sous-répertoire
3. Nécessite d'actualiser la page pour re-détecter

Q : Puis-je forcer l'exécution d'un composant dont les dépendances ne correspondent pas ?

R : Vous pouvez visualiser le composant dans la liste « Tout », mais son bon fonctionnement dépend des différences réelles de l'API. Il est recommandé de résoudre d'abord les problèmes de dépendances.

Q : Les règles de correspondance s'appliquent-elles aux composants téléchargés ?

R : Les règles de correspondance n'affectent que l'aperçu en ligne. Les composants téléchargés s'exécutent dans votre projet en utilisant les versions de dépendances de votre projet.