Gutenberg-Block-Deprecation: Aktualisieren ohne Inhalte zu brechen

Zusammenfassung

Das Aktualisieren eines Gutenberg-Blocks führt oft dazu, dass bestehende Beiträge, die die alte Version verwenden, kaputtgehen. Dieser Artikel zeigt Ihnen, wie Sie die deprecated-Eigenschaft in block.json nutzen, um Abwärtskompatibilität zu gewährleisten. Sie lernen die genauen Schritte, um das aktuelle Block-Markup zu erfassen, eine oder mehrere veraltete Versionen zu definieren und Attribute korrekt zuzuordnen. Wir behandeln sowohl statische als auch dynamische Blöcke mit praktischen Beispielen. Der Artikel hinterfragt auch die Annahme, dass Deprecation immer der beste Ansatz ist, und diskutiert, wann ein sauberer Bruch besser sein könnte. Am Ende werden Sie in der Lage sein, Ihre Blöcke sicher zu aktualisieren, ohne die Inhalte Ihrer Benutzer zu beschädigen.

Das Szenario einer brechenden Änderung

Sie haben vor sechs Monaten einen benutzerdefinierten Testimonial-Block gestartet. Er gibt ein einfaches <div> mit einem Zitat und einem Autorennamen aus. Jetzt möchte Ihr Kunde ein neues Design: Der Autor soll über dem Zitat erscheinen, mit einer anderen CSS-Klasse. Sie aktualisieren die save-Funktion und den render_callback des Blocks. Sie testen mit einem neuen Beitrag – es sieht großartig aus. Dann navigieren Sie zu einem alten Beitrag, der den Block verwendet. Katastrophe: Der Zitattext ist verschwunden, der Autor ist an der falschen Stelle und das Styling ist daneben. Sie haben gerade jede Seite zerstört, die diesen Block verwendet.

Dies ist das klassische Problem einer "brechenden Änderung" in der Gutenberg-Block-Entwicklung. Blöcke sind im Wesentlichen Datenstrukturen, die mit Markup kombiniert werden. Wenn Sie das Markup ändern, kann der Editor alte Inhalte nicht automatisch auf die neue Struktur abbilden. Das Ergebnis ist entweder ein Validierungsfehler (der Block wird ungültig) oder – schlimmer – eine stille Korruption, bei der der Block falsch gerendert wird.

Was ist Block-Deprecation?

Block-Deprecation ist Gutenbergs eingebauter Mechanismus zur Handhabung von Versionsänderungen. Indem Sie ein deprecated-Array in Ihrer block.json definieren, teilen Sie dem Editor mit: "Wenn du auf einen Block triffst, der einer dieser älteren Versionen entspricht, wandle ihn in die aktuelle Version um." Jeder Deprecation-Eintrag spezifiziert die vorherigen attributes, supports und die save-Funktion (oder den render_callback). Wenn der Editor einen alten Block lädt, durchläuft er das Deprecation-Array der Reihe nach und wendet die erste passende Transformation an.

Diese Funktion wird oft wenig genutzt, weil Entwickler annehmen, dass sie niemals das Markup eines Blocks ändern müssen. In realen Projekten entwickeln sich die Anforderungen jedoch weiter. Wenn Sie auf Deprecation verzichten, zwingen Sie Benutzer entweder, Blöcke zu löschen und neu einzufügen (schlechte Erfahrung), oder Sie pflegen zwei separate Versionen des Blocks (unübersichtlich). Das offizielle WordPress-Entwicklerhandbuch behandelt dies im Block Editor Handbook, aber praktische Anleitungen fehlen.

Schritt 1: Erfassen des aktuellen Zustands

Bevor Sie Änderungen vornehmen, zeichnen Sie die genaue save-Ausgabe (oder den render_callback für dynamische Blöcke) und die attributes auf, die Ihr Block derzeit verwendet. Betrachten Sie es als eine Momentaufnahme. Für statische Blöcke speichern Sie das von der save-Funktion zurückgegebene JSX. Für dynamische Blöcke speichern Sie das vom render_callback generierte PHP-Markup.

Erstellen Sie eine neue Datei in Ihrem Plugin namens deprecated.js (oder ähnlich) und speichern Sie dort die alte save-Funktion. Alternativ können Sie die veralteten Versionen direkt in der Haupt-JavaScript-Datei des Blocks behalten. Der Schlüssel ist, diesen Code genau so zu bewahren, wie er war, als der Block zum ersten Mal bereitgestellt wurde.

Schritt 2: Definieren Ihrer veralteten Versionen

Fügen Sie in Ihrer block.json ein deprecated-Array hinzu. Jeder Eintrag ist ein Objekt, das Folgendes enthalten kann:

• attributes (Objekt): Die vorherigen Attributdefinitionen.
• supports (Objekt): Alle vorherigen Support-Einstellungen, die sich geändert haben.
• save (Funktion oder String): Die vorherige Save-Funktion. Für reine JavaScript-Blöcke importieren Sie die alte Funktion. Für PHP-gerenderte dynamische Blöcke können Sie stattdessen migrate und render_callback verwenden.
• migrate (Funktion): Eine Funktion, die alte Attribute auf neue abbildet (optional).

Beispiel:

"deprecated": [
  {
    "attributes": {
      "quote": { "type": "string", "source": "html", "selector": ".quote" },
      "author": { "type": "string", "source": "html", "selector": ".author" }
    },
    "supports": {},
    "save": "() => <div className=\"testimonial-legacy\"><p className=\"quote\">{attributes.quote}</p><p className=\"author\">{attributes.author}</p></div>"
  }
]

Hinweis: Die save-Funktion in block.json wird normalerweise in JavaScript definiert. Wenn Sie ein externes Skript verwenden, müssen Sie es einbinden und auf den Funktionsnamen verweisen. Alternativ können Sie die Funktion als String inline setzen (dies wird jedoch für komplexe Blöcke nicht empfohlen).

Schritt 3: Attribute zuordnen

Oft ändern Sie nicht nur das Markup, sondern auch die Attributnamen oder -quellen. Beispielsweise könnten Sie davon abweichen, den Autor als einfachen String zu speichern, hin zu einem Rich-Text-Feld. In solchen Fällen verwenden Sie die migrate-Eigenschaft, um alte Attribute in neue umzuwandeln.

migrate: (attributes) => {
  return {
    quote: attributes.quote,
    author: { content: attributes.author, level: 2 }
  };
}

Wenn Sie keine migrate-Funktion bereitstellen, übergibt der Editor die alten Attribute einfach direkt an den neuen Block. Das könnte zu Fehlern führen, wenn sich Attributnamen geändert haben.

Schritt 4: Testen mit echten Inhalten

Nachdem Sie die veraltete Version definiert haben, testen Sie gründlich. Erstellen Sie einen neuen Beitrag, fügen Sie den alten Block ein (Sie können simulieren, indem Sie den serialisierten Blockcode aus einem bestehenden Beitrag einfügen) und überprüfen Sie, ob er ohne Validierungsfehler in die neue Version konvertiert wird. Testen Sie auch das Bearbeiten und Speichern des konvertierten Blocks. Wiederholen Sie dies für mehrere veraltete Versionen, falls vorhanden.

Für dynamische Blöcke ist der Prozess ähnlich, aber mit einer Besonderheit: Die save-Funktion für einen dynamischen Block gibt normalerweise null zurück (der Block wird über PHP gerendert). Im Deprecation-Eintrag können Sie entweder save auf das vorherige statische Markup setzen, das verwendet wurde, bevor Sie auf dynamisches Rendering umgestellt haben, oder Sie verwenden einen render_callback in PHP, der sowohl alte als auch neue Attributstrukturen verarbeitet. Dies ist komplexer, aber machbar.

Einschränkungen und Abwägungen

Deprecation ist mächtig, hat aber Nachteile. Jede veraltete Version fügt Ihrem Plugin Code hinzu. Mit der Zeit können Sie eine Kette von fünf oder sechs Legacy-Versionen ansammeln, die selten verwendet, aber gewartet werden müssen. Das WordPress-Kernteam empfiehlt, mindestens zwei Versionen zurückzubehalten, aber darüber hinaus könnten Sie einen sauberen Bruch in Betracht ziehen, wenn die Anzahl der betroffenen Beiträge gering ist.

Eine weitere Nuance: Die Reihenfolge der Deprecation-Einträge ist wichtig. Der Editor durchläuft das Array von Index 0 aufwärts und verwendet die erste Übereinstimmung. Wenn zwei veraltete Versionen ähnlich sind, könnte die falsche angewendet werden. Listen Sie immer die aktuellste veraltete Version zuerst auf (diejenige, die der aktuellen Version direkt vorausgeht).

Schließlich behandelt Deprecation keine Inhalte, die mit einer seitenweiten Stiländerung bearbeitet wurden (z.B. über theme.json). Wenn das Erscheinungsbild Ihres Blocks auf globalen Stilen basierte, die sich inzwischen geändert haben, wird die Deprecation das nicht anpassen. Möglicherweise müssen Sie ein Migrationsskript hinzufügen, das beim Speichern oder über einen Plugin-Update-Hook ausgeführt wird.

Wann Deprecation nicht die Antwort ist

Die meisten Tutorials stellen Deprecation als obligatorisch dar. In der Realität gibt es Situationen, in denen ein sauberer Bruch besser ist. Wenn Ihr Block neu ist und nur in wenigen Beiträgen verwendet wird, könnte das manuelle Aktualisieren dieser wenigen Instanzen schneller sein als das Schreiben und Testen von Deprecation-Code. Wenn das zugrunde liegende Datenmodell des Blocks grundlegend anders ist (z.B. wenn Sie zwei Blöcke zu einem zusammenführen), ist Deprecation möglicherweise nicht flexibel genug. Schreiben Sie in diesem Fall ein einmaliges Migrationsskript, das beim Update des Plugins ausgeführt wird und alte Blöcke in das neue Format konvertiert.

Ein weiterer kontroverser Punkt: Deprecation sollte nicht als Ersatz für gutes Design verwendet werden. Wenn Sie häufige Änderungen erwarten, gestalten Sie Ihren Block von Anfang an mit Versionierung – z.B. durch Speichern eines version-Attributes und Verwendung von bedingtem Rendering. Dieser Ansatz, der in Beyond Basic Blocks diskutiert wird, ist leichter als Deprecation, erfordert aber Voraussicht.

Fazit

Block-Deprecation ist ein unverzichtbares Werkzeug für jeden ernsthaften Gutenberg-Entwickler. Es ermöglicht Ihnen, Ihre Blöcke weiterzuentwickeln, ohne die Inhalte der Benutzer zu beschädigen. Die wichtigsten Schritte sind: Erfassen Sie den aktuellen Zustand, definieren Sie die veraltete Version in block.json, ordnen Sie Attribute bei Bedarf zu und testen Sie mit echten Inhalten. Aber denken Sie daran, dass Deprecation mit Wartungskosten verbunden ist. Manchmal ist ein sauberer Bruch oder ein versioniertes Blockdesign pragmatischer. Nutzen Sie Deprecation strategisch, nicht automatisch, und Ihre Blöcke werden robust durch viele Aktualisierungen bleiben.

Für eine breitere Perspektive zur Erstellung wartbarer Plugins siehe Building Robust WordPress Plugins. Und wenn Sie neu in der Block-Entwicklung sind, hilft Ihnen Beyond Basic Blocks beim Einstieg.