GrapesJS Custom Components Leitfaden (2026)

Komponenten definieren das Verhalten, nicht nur das Markup

Eine GrapesJS-Komponente ist ein typisiertes Modell mit Standardeinstellungen, Eigenschaften (editierbaren Einstellungen), und eine optionale Ansicht. Du meldest einen bei DomComponents.addType. Dieser Leitfaden baut eine benutzerdefinierte Komponente mit einem trait und zeigt, wie HTML darauf importiert wurde.

1. Einen Bauteiltyp registrieren

editor.DomComponents.addType('rating', {
  // Map matching HTML onto this type when content is loaded.
  isComponent: (el) => el.classList?.contains('rating') && { type: 'rating' },

  model: {
    defaults: {
      tagName: 'div',
      classes: ['rating'],
      // Editable settings shown in the trait panel:
      traits: [
        { type: 'number', name: 'stars', label: 'Stars', min: 1, max: 5 },
      ],
      stars: 5,
    },
  },
});

2. Auf Merkmalsänderungen in einer Ansicht reagieren

editor.DomComponents.addType('rating', {
  model: {
    defaults: { tagName: 'div', classes: ['rating'], stars: 5,
      traits: [{ type: 'number', name: 'stars', min: 1, max: 5 }] },
  },
  view: {
    init() {
      this.listenTo(this.model, 'change:stars', this.render);
    },
    onRender() {
      const n = this.model.get('stars');
      this.el.textContent = '★'.repeat(n) + '☆'.repeat(5 - n);
    },
  },
});

3. Es als Block freilegen

editor.BlockManager.add('rating', {
  label: 'Rating',
  category: 'Widgets',
  content: { type: 'rating', stars: 4 },
});

Denn erkennt isComponent Elemente .rating , Belastung gespeichertes HTML stellt die Komponente neu – Traits und Verhalten intakt.

Häufige Fehler

Benutzerdefinierte Komponenten versagen auf vorhersehbare Weise. Wenn du isComponent (meistens{ type }) keinen Truthy-Wert zurückgibst, um DOM zu übereinstimmen, wird geladenes HTML nicht auf deinen Typ abgebildet und die Eigenschaften verschwinden beim Neuladen. Wenn die Ansicht das change:<trait> Ereignis des Modells nicht listenTo ausführt, werden Bearbeitungen im Trait-Panel nicht neu gerendert. Ein erneutes Rendern innerhalb eines Handlers, der selbst eine Änderung auslöst, kann eine Endlosschleife verursachen – aktualisieren Sie das DOM direkt, anstatt wenn möglich ein vollständiges Rendering aufzurufen. Und so einstellendraggable, dassdroppable dein Bauteil nur dort platziert werden kann, wo es Sinn macht.

Voraussetzungen

Du brauchst einen laufenden GrapesJS-Editor und einfaches JavaScript. Komponenten sind registriert mit DomComponents.addType; die drei Teile sind die Detektion (isComponent), das Modell (Standardwerte + Traits) und eine optionale Ansicht (Leinwandverhalten).

Modell: Standardwerte, Eigenschaften und Einschränkungen

Das Modell definiert, was die Komponente ist. Über Eigenschaften hinaus kannst du einschränken, wo es möglich ist Go und was es mit draggable, droppable, und akzeptiert editable:

editor.DomComponents.addType('rating', {
  isComponent: (el) => el.classList?.contains('rating') && { type: 'rating' },
  model: {
    defaults: {
      tagName: 'div',
      classes: ['rating'],
      droppable: false,
      traits: [{ type: 'number', name: 'stars', min: 1, max: 5 }],
      stars: 5,
    },
  },
});

Ansicht: Reaktion auf Merkmalsänderungen

view: {
  init() { this.listenTo(this.model, 'change:stars', this.render); },
  onRender() {
    const n = this.model.get('stars');
    this.el.textContent = '★'.repeat(n) + '☆'.repeat(5 - n);
  },
}

Warum isComponent wichtig ist

isComponent läuft, wenn HTML in den Editor geladen wird. Rückgabe des Typs Das Objekt zum Abgleich der Elemente ermöglicht es, gespeichertes Markup in deine Komponente zu rehydratisieren Mit seinen Eigenschaften und seinem Verhalten intakt – ohne ihn dreht ein Nachladen deine Komponente zurück in einfaches HTML.

Best Practices

Halte das Modell deklarativ und setze das Verhalten in die Ansicht. Vermeiden Sie es, einen vollständigen Auslöser auszulösen innerhalb eines Change Handlers rendern, der selbst eine Änderung verursacht – aktualisieren Sie das DOM direkt auf Vermeide Schleifen. Setzen draggable/droppable absichtlich so ein Die Komponente kann nur dort platziert werden, wo es Sinn macht. Zeigen Sie bedeutungsvolle Eigenschaften, damit Redakteure kann die Komponente ohne Code konfigurieren.

Nächste Schritte

Oberflächenkomponenten als dragbare Einheiten in der Leitfaden für benutzerdefinierte Blöcke, Bündel sie in einem benutzerdefinierten Plugin oder Durchsuchen Sie GrapesJS-Plugins auf GJS.Market.

FAQ

Wie erstelle ich eine benutzerdefinierte Komponente in GrapesJS?

Ruf editor.DomComponents.addType(type, { isComponent, model, view }) — die Erkennung, Standard-/Traits- und Canvas-Verhalten definiert.

Was sind Eigenschaften?

Eigenschaften sind die bearbeitbaren Einstellungen, die im Eigenschaftsfeld für eine ausgewählte Person angezeigt werden Komponente; Deklarieren Sie sie in model.defaults.traits.

Wie funktioniert isComponent?

Es erhält ein DOM-Element und gibt einen truthy-Wert zurück (oft { type }), wenn dieses Element deine Komponente werden sollte, also importiert HTML passt zu deinem Typ.