Componentspecificatie

Deze pagina legt uit hoe je een component organiseert zodat het platform het herkent, kan previewen en kan publiceren. Een component is geen "één bestand", maar een map.

Entry-bestand

De mapnaam is de componentnaam. Het entry-bestand ligt per framework vast:

Framework	Entry-bestand	Beschrijving
Vue 2 / Vue 3	`index.vue`	Bestaat het bestand, dan is het Vue
React 17 / 18	`index.jsx` / `index.tsx`	Moet `default export` hebben
Web Component	`index.js`	Moet in de broncode een custom element registreren

Vertrouw niet tegelijk op vue en react, anders kan het platform het framework niet bepalen.

Aanbevolen mapstructuur

MyComponent/
├── index.vue          # Entry (verplicht)
├── README.md          # Properties, events, voorbeelden (aanbevolen)
├── comp.json          # Door het platform gegenereerd: __id__ / name / version
├── main.js            # Alleen globale bijwerkingen voor de previewomgeving (optioneel)
├── demo/
│   ├── index.vue      # Preview in klein venster
│   └── full.vue       # Preview op volledig scherm
├── assets/
│   └── bg.png         # Eigen resources van het component
└── screenshot_mini.png # Miniatuur (meestal automatisch gegenereerd)

demo/ is een afspraak, geen verplichting: elk .vue-, .jsx- of .tsx-bestand in de map kan als previewbestand worden gekozen; voor Web Components kies je een .html-bestand.

Resources refereren

Vue / React: gebruik relatieve paden met import, geen aliassen zoals @/.

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

// Fout: het platform kan projectaliassen niet herleiden
import bg from "@/assets/bg.png";

Web Component: de broncode is ESM die de browser direct uitvoert; afbeeldingen, lettertypen en styles kunnen niet worden geïmporteerd. Gebruik new URL om ze te lokaliseren:

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

Relatieve src / href / srcset in de preview-HTML worden door het platform ten opzichte van de componentmap herleid; schrijf dus gewoon relatieve paden.

Dependencies declareren

Externe dependencies hoeven niet in comp.json te staan. Het platform scant de import-statements in de broncode, haalt ze automatisch eruit en herleidt en precompileert ze uit de node_modules van je lokale project.

Daarom geldt: de pakketten die een component gebruikt, moeten lokaal al geïnstalleerd zijn.

bash

npm install echarts

Het scanresultaat verschijnt op de uploadpagina onder "Dependencies"; controleer het vóór het publiceren.

demo en preview

demo/index.vue: de preview in klein venster op de lijstkaart.
demo/full.vue: de preview op volledig scherm op de detailpagina; aanbevolen.

De preview van een Web Component is gewone HTML:

html

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

Vereisten:

Bevat minimaal één <script type="module">.
Het modulescript moet in de <body> staan; in de <head> wordt het genegeerd.
De src van het script wordt herleid ten opzichte van de locatie van de HTML zelf.

Automatisch schalen van mini-previews

Het platform meet automatisch de vaste breedte en hoogte van de mini-demo en past die met contain (proportioneel, volledig zichtbaar, gecentreerd) aan het paneel aan. In de democode hoef je geen schaallogica te schrijven.

Je hoeft de inhoud alleen op de ontwerpafmetingen vast te zetten:

vue

<template>
  <div class="mini-content">Inhoud ontworpen op 320 × 240</div>
</template>

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

Schrijf geen width: 100%

Als het root-element de container vult, meet het platform de "natuurlijke afmetingen" en verschuift de schaal met de inhoud mee. Zet de ontwerpafmetingen gewoon vast.

De rol van main.js

main.js wordt alleen in de previewomgeving uitgevoerd en is bedoeld voor globale bijwerkingen:

Vue 2: een UI-bibliotheek registreren

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

Vue.use(Antd);

Vue 3: registreren via de door het platform geleverde Vue.app

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: globale styles plaatsen

import "antd/dist/reset.css";

Zet globale styles niet in index.jsx: de consumerende partij voert ze mee uit bij het import van de component-entry, waardoor ze dubbel worden ingeladen.

Naamgevingsregels

Uniek binnen dezelfde ruimte (het publieke platform of een team).
Alleen PascalCase (UserGrowthChart) of kebab-case (alipay-data-table).
Geen _, geen camelCase, niet met een cijfer beginnen.
Gebruik bij voorkeur een prefix om het bedrijfsdomein aan te geven: bedrijfsnaam-domein-componentnaam.

Limieten voor grootte en aantal

Limiet	Maximum
Eén bestand	3 MB
Totale grootte van het component	10 MB
Aantal bestanden	30 (inclusief submappen)

Bij overschrijding comprimeer je eerst statische resources, of maak je grote bestanden extern gelinkt.

Minimaal voorbeeld

Vue

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: "Klik op mij" } }
};
</script>

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

React

jsx

// 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);

html

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

Checklist

[ ] De mapnaam voldoet aan de naamgevingsregels en is niet dubbel binnen de huidige ruimte.
[ ] Het entry-bestand bestaat; React heeft een default export.
[ ] Resources gebruiken relatieve paden; Web Components gebruiken new URL.
[ ] De gebruikte dependencies zijn lokaal geïnstalleerd.
[ ] De mini-demo heeft vaste ontwerpafmetingen.
[ ] De preview-HTML van de Web Component bevat een <script type="module"> in de <body>.
[ ] Bestandsgrootte en aantal blijven binnen de limieten.

Volgende stappen

Het component naar het platform sturen: Uploaden en publiceren
Na publicatie blijven itereren: Bijwerken en versies

Componentspecificatie ​

Entry-bestand ​

Aanbevolen mapstructuur ​

Resources refereren ​

Dependencies declareren ​

demo en preview ​

Automatisch schalen van mini-previews ​

De rol van main.js ​

Naamgevingsregels ​

Limieten voor grootte en aantal ​

Minimaal voorbeeld ​

Checklist ​

Volgende stappen ​