Mechanisme voor dependency-matching
comp-hub gebruikt intelligente dependency-matching zodat componenten zich kunnen aanpassen aan verschillende lokale omgevingen.
Waarom dependency-matching nodig is
Wanneer componenten lokaal in preview worden bekeken, moeten ze dependencies laden die al in het lokale project zijn geïnstalleerd. Maar de realiteit is vaak:
- De component is afhankelijk van echarts 5.2.0
- Lokaal is echarts 5.0.0 geïnstalleerd
Als strikte versieconsistentie vereist zou zijn, kunnen veel componenten niet normaal in preview worden bekeken. Daarom biedt het platform flexibele regels voor dependency-matching.
Matching-regels
Onder "Instellingen → Preview-regel" kun je in de sectie Dependencies voor elke dependency van je project (dependencies en devDependencies) een matching-regel instellen:
| Regel | Beschrijving | Toepasselijk scenario | Kleurindicator |
|---|---|---|---|
| Auto | Geen versiebeperking, renderen met de huidige lokale omgeving | Standaard, houdt alles renderbaar | ⚪ Grijs (standaard) |
| Alleen geïnstalleerd | Zolang de dependency lokaal is geïnstalleerd, ongeacht de versie | Snelle preview, niet-productieomgeving | 🟢 Groen (meest soepel) |
| Major-versie | Het major-versienummer moet overeenkomen | Balanceert compatibiliteit en stabiliteit | 🔵 Blauw |
| Major.minor-versie | Zowel het major- als het minor-versienummer moet overeenkomen | Scenario's die gevoelig zijn voor versies | 🟠 Oranje (redelijk strikt) |
| Exacte match | Het versienummer moet exact hetzelfde zijn | Strikte versiecontrole | 🔴 Rood (meest strikt) |
De regels komen uit de package.json van je project en worden ook gebruikt bij het prebuilden van dependencies voor de preview.
Tip: elke matching-regel op de instellingenpagina heeft een bijbehorende gekleurde stip ervoor, zodat je snel kunt zien hoe strikt de matching is.
Voorbeeld
Stel dat de component afhankelijk is van echarts: 5.2.3:
| Lokale versie | Auto | Alleen geïnstalleerd | Major-versie | Major.minor | Exacte match |
|---|---|---|---|---|---|
| 5.0.0 | ✅ Gebruiken | ✅ Gebruiken | ✅ Gebruiken | ❌ Overslaan | ❌ Overslaan |
| 5.2.0 | ✅ Gebruiken | ✅ Gebruiken | ✅ Gebruiken | ❌ Overslaan | ❌ Overslaan |
| 5.2.3 | ✅ Gebruiken | ✅ Gebruiken | ✅ Gebruiken | ✅ Gebruiken | ✅ Gebruiken |
| 6.0.0 | ✅ Gebruiken | ✅ Gebruiken | ❌ Overslaan | ❌ Overslaan | ❌ Overslaan |
| Niet geïnstalleerd | ❌ Overslaan | ❌ Overslaan | ❌ Overslaan | ❌ Overslaan | ❌ Overslaan |
Standaardgedrag
- Dependencies zonder handmatig ingestelde regel gebruiken standaard Auto (geen versiebeperking, renderen met de huidige lokale omgeving)
- Een dependency die helemaal niet lokaal is geïnstalleerd matcht nooit — installeer hem en ververs de pagina
- Het framework wordt afgeleid uit de dependencies van het component zelf: een component dat
vueimporteert wordt als Vue gerenderd, een component datreactimporteert als React (React 17 en 18 worden beide ondersteund); een component dat beide importeert kan niet worden gerenderd
Problemen oplossen als een component niet wordt weergegeven
Als je een component niet ziet in de lijst "Aanbevolen", kan dat komen door een dependency-mismatch. Volg deze stappen om het probleem op te lossen:
1. Schakel over naar het filter "Alle"
Zet de filtervoorwaarde boven aan de componentmarkt op "Alle" om te zien of de component wordt weergegeven.
2. Controleer de dependency-status
Klik op de componentkaart en controleer de dependency-matchingstatus op de previewpagina:
- 🟢 Groen: dependency is succesvol gematcht
- 🔴 Rood: dependency komt niet overeen of ontbreekt
- ⚠️ Geel: de dependency-versie wijkt af, maar kan geprobeerd worden te draaien
3. Installeer ontbrekende dependencies
Als er wordt gemeld dat dependencies ontbreken, installeer ze dan in het lokale project:
npm install <package-name>Vernieuw de pagina na de installatie.
4. Pas de matching-regels aan
Als dependency-versies verschillen maar de functionaliteit niet beïnvloeden, kun je de matching-regels versoepelen onder "Instellingen → Preview-regel".
Best practices
Auteurs van componenten
- Vermeld de dependency-vereisten duidelijk in
README.md - Gebruik waar mogelijk dependency-versies met een goede compatibiliteit
- Vermijd het vertrouwen op functies van een specifieke minor-versie
Gebruikers van componenten
- Houd lokale dependency-versies redelijk recent om de compatibiliteit van componenten te verbeteren
- Voor niet-kritieke dependencies kun je "Alleen geïnstalleerd" of "Major-versie" matching gebruiken
- Controleer bij problemen eerst de foutmeldingen in de console
FAQ
V: Waarom meldt de component "Ontbrekende dependency" terwijl deze al lokaal is geïnstalleerd?
A: Mogelijke oorzaken:
- De naam van de dependency is anders gespeld (bijvoorbeeld
echartsvsECharts) - De dependency is geïnstalleerd in de
node_modulesvan een submap - Je moet de pagina vernieuwen om opnieuw te detecteren
V: Kan ik een component met niet-overeenkomende dependencies geforceerd laten draaien?
A: Je kunt de component bekijken in de lijst "Alle", maar of hij normaal draait hangt af van de werkelijke API-verschillen. Het is aanbevolen om eerst de dependency-problemen op te lossen.
V: Gelden de matching-regels ook voor gedownloade componenten?
A: Matching-regels beïnvloeden alleen de online preview. Gedownloade componenten draaien in jouw project met de dependency-versies van jouw project.