Migration von Unlayer

Das Paket @templatical/import-unlayer konvertiert Unlayer-Design-JSON (die Ausgabe von editor.saveDesign(...) aus react-email-editor oder dem gehosteten Unlayer-Editor) in Templaticals TemplateContent-Format.

WARNING

Dieses Paket befindet sich in aktiver Entwicklung. Einige Inhaltstypen und erweiterte Funktionen werden möglicherweise noch nicht vollständig unterstützt. Testen Sie Ihre konvertierten Templates, bevor Sie sie in Produktion einsetzen.

Installation

npm

npm install @templatical/import-unlayer

pnpm

pnpm add @templatical/import-unlayer

yarn

yarn add @templatical/import-unlayer

bun

bun add @templatical/import-unlayer

Ohne Build-Schritt (CDN)

Sie können es auch von einem CDN laden:

<script type="module">
  import { convertUnlayerTemplate } from 'https://cdn.jsdelivr.net/npm/@templatical/import-unlayer/+esm';
  // ...dann konvertieren wie im Abschnitt „Verwendung“ unten
</script>

Verwendung

import { convertUnlayerTemplate } from '@templatical/import-unlayer';

// Laden Sie Ihr Unlayer-Design-JSON (was auch immer editor.saveDesign zurückgegeben hat)
const res = await fetch('/api/unlayer-templates/123');
const unlayerJson = await res.json();

// Ins Templatical-Format konvertieren
const { content, report } = convertUnlayerTemplate(unlayerJson);

// Im Editor verwenden
const editor = await init({
  container: '#editor',
  content,
});

// Den Konvertierungsbericht auf Probleme prüfen
console.log(report);

Im Playground öffnen

Die Funktion gibt ein ImportResult zurück mit:

• content — das konvertierte TemplateContent, bereit für den Editor
• report — ein Konvertierungsbericht mit dem Status jedes Inhaltsknotens (converted, approximated, html-fallback oder skipped)

Status	Bedeutung
converted	Ohne Verlust auf einen Templatical-Block abgebildet.
approximated	Abgebildet, mit Clamp oder Flatten — note sagt, was sich geändert hat.
html-fallback	Kein Block-Äquivalent; das Original-Markup ist ein HtmlBlock.
skipped	Keine Ausgabe (Formulare und alles, was der Konverter ablehnt).

Das Design-JSON, das Unlayers gehosteter Editor und editor.saveDesign() erzeugen, ist die Eingabe. Ein kompiliertes HTML-Export ist ein anderes Envelope — @templatical/import-html.

Block-Mapping

Unlayer-Inhaltstypen werden auf Templatical-Entsprechungen abgebildet:

Unlayer-Inhalt	Templatical-Block	Status
Text	paragraph	Konvertiert
Heading	title	Konvertiert
Image	image	Konvertiert (angenähert, wenn ein maxWidth unter 100% zu px wird; siehe Bildbreite)
Button	button	Konvertiert
Divider	divider	Konvertiert (angenähert, wenn ein Divider mit Teilbreite links oder rechts ausgerichtet ist)
Spacer	spacer	Konvertiert
Html	html	Konvertiert
Menu	menu	Angenähert (Stile können abweichen)
Social	social	Konvertiert
Video	video	Konvertiert
Timer	html	HTML-Fallback (manuell neu aufbauen)
Form	—	Übersprungen

Unbekannte Inhaltstypen werden als Fallback in HTML-Blöcke konvertiert.

Bildbreite

Unlayer-Bild	ImageBlock.width	Status
autoWidth (Standard), src.width schmaler als der Platz des Bildes	die px-Zahl	Konvertiert
autoWidth, src.width so breit wie der Platz oder breiter, oder fehlend	"full"	Konvertiert
autoWidth: false, maxWidth 100% oder fehlend	"full"	Konvertiert
autoWidth: false, maxWidth unter 100%, etwa 75%	dieser Anteil des Platzes in px	Angenähert
autoWidth: false, nicht lesbares maxWidth	"full"	Angenähert

src.width und src.height sind die Größe der hochgeladenen Datei. Der Platz des Bildes ist die Breite seiner Spalte abzüglich des linken und rechten containerPadding. src.height wird nicht importiert, sodass das Bild in der angezeigten Breite das Seitenverhältnis der Datei behält.

TIP

Eine px-Breite behält auf dem Smartphone ihre Größe, während ein Prozentwert mit der Spalte schrumpft. Deshalb ist ein maxWidth unter 100% angenähert.

Divider-Breite

Unlayer-width	DividerBlock.width	Status
fehlt, oder 100%	"full"	Konvertiert
ein Prozentwert unter 100%, etwa 50%	derselbe Prozentwert auf zwei Nachkommastellen, "50%"	Konvertiert
unter 0% oder über 100%	begrenzt auf "0%" bzw. "full"	Angenähert
px, schmaler als die Spannweite der Linie	die px-Zahl	Konvertiert
px, so breit wie diese Spannweite oder breiter	"full"	Konvertiert
jeder andere Wert	"full"	Angenähert

Eine px-Breite wird mit der Spannweite der Linie verglichen: der Breite ihrer Spalte abzüglich des linken und rechten containerPadding des Dividers. Die Breite einer Spalte ist ihr Anteil an settings.width gemäß dem Spaltenlayout der Section, und settings.width ist eine px-Angabe in contentWidth, sonst 600.

TIP

mj-divider zeichnet 100% über diese Spannweite, eine px-Breite, die sie erreicht, sieht deshalb aus wie "full". "full" wird außerdem auf dem Smartphone mit der Spalte schmaler.

Templatical zentriert jeden Divider. Ein Divider mit Teilbreite, den Unlayer links oder rechts ausrichtet (textAlign), ist angenähert; seine note nennt die Ausrichtung.

Konvertierung des Spaltenlayouts

Unlayer organisiert Inhalte in Reihen mit Spalten, deren Breiten aus einem cells-Gewichtungsarray stammen. Diese werden auf Templaticals SectionBlock mit dem passenden ColumnLayout abgebildet:

Unlayer-cells	Templatical-Layout
[1] (einzelne Spalte)	'1'
[1, 1] (gleiche Hälften)	'2'
[1, 1, 1] (gleiche Drittel)	'3'
[1, 2]	'1-2'
[2, 1]	'2-1'
4+ Zellen	auf eine einzelne Spalte reduziert, mit Warnung

Zellverhältnisse, die keinem Standardlayout entsprechen, werden auf das nächstliegende verfügbare abgebildet.

Section-Hintergrund

Unlayer-Reihenwerte	section.styles.backgroundColor
columnsBackgroundColor gesetzt	columnsBackgroundColor
nur backgroundColor gesetzt	backgroundColor

Setzt eine Reihe beide auf unterschiedliche Farben, übernimmt die Section columnsBackgroundColor, und report.warnings nennt das verworfene backgroundColor.

TIP

columnsBackgroundColor füllt die Inhaltsbreite, also die Fläche, die eine Section einfärbt. backgroundColor füllt den Streifen außerhalb davon, und eine Templatical-Section hat keinen Streifen über die volle Breite.

Hintergrundbild der Section

Das backgroundImage einer Reihe wird zum backgroundImage der Section:

backgroundImage.fullWidth	Ergebnis
false (die Inhaltsfläche)	Das Bild der Section, exakt.
true, columnsBackgroundColor nicht gesetzt	Das Bild der Section, in Inhaltsbreite gezeichnet; report.warnings vermerkt das.
true, columnsBackgroundColor gesetzt	Verworfen, da in Unlayer die Inhaltsfarbe es innerhalb der Inhaltsbreite verdeckt; report.warnings nennt es.

size cover und contain werden übernommen, custom ist das Bild in Originalgröße (auto). Die neun position-Schlüsselwörter werden auf den passenden Rasterpunkt abgebildet. Bei einer custom-Position rastet ein Prozentwert in customPosition auf das nächste von links, Mitte und rechts (oben, Mitte und unten) ein, eine Länge auf den linken bzw. oberen Rand. repeat-x und repeat-y werden zu repeat. Die Flags cover und center älterer Designs werden gelesen, wenn size und position fehlen: cover wird zu cover (false zu auto), center zu oben mittig (false zu links oben). Jeder Wert ohne exaktes Schlüsselwort fügt report.warnings eine Zeile hinzu.

Template-Einstellungen

Globale Template-Einstellungen werden übertragen, wo möglich:

• Breite — Unlayers body.values.contentWidth wird auf settings.width abgebildet
• Hintergrundfarbe — body.values.backgroundColor wird auf settings.backgroundColor abgebildet
• Hintergrundbild — body.values.backgroundImage hat keine Templatical-Entsprechung, da der E-Mail-Body nur eine Farbe kennt. Es wird verworfen, und report.warnings nennt es.
• Textfarbe — body.values.textColor wird auf settings.textColor abgebildet. Überschriften, Menüs und Absätze ohne eigene Farbe übernehmen sie.
• Links — body.values.linkStyle.linkColor wird auf settings.linkColor abgebildet, linkStyle.linkUnderline auf settings.linkUnderline. Setzt linkStyle kein linkUnderline, werden Links unterstrichen, wie in Unlayer.
• Preheader — body.values.preheaderText wird auf settings.preheaderText abgebildet und entfällt, wenn er leer ist
• Schriftfamilie — body.values.fontFamily.value wird auf settings.fontFamily übertragen. Der gesamte Stack wird übernommen, sodass seine Fallbacks erhalten bleiben; ein Stack, der genau dem einer eingebauten Schriftart entspricht (Arial, sans-serif), wird als bloßer Name gespeichert.

Bekannte Einschränkungen

• Custom Fonts — Unlayers Custom-Font-Deklarationen werden nicht automatisch importiert. Fügen Sie sie manuell über die fonts-Konfigurationsoption hinzu.
• Anzeigebedingungen / dynamische Inhalte — Unlayers Syntax für bedingte Inhalte hat keine direkte Entsprechung und wird bei der Konvertierung verworfen. Nutzen Sie Templaticals Anzeigebedingungen, um sie neu aufzubauen.
• Custom-Module / Blöcke aus kostenpflichtigen Tarifen — Unlayers Custom Blocks werden in Platzhalter-HTML-Blöcke konvertiert. Bauen Sie sie als Custom Block neu auf, wenn sie wiederverwendbar sind.
• Formulare — Unlayers Formular-Blöcke werden übersprungen. Die meisten E-Mail-Clients blockieren aus Sicherheitsgründen das Absenden von Formularen; bauen Sie den Call-to-Action als Button neu auf, der auf ein gehostetes Formular verlinkt.
• Timer / Countdowns — Werden als Platzhalter-HTML-Block importiert. Kein type: "countdown" erzeugen: dieser Block braucht Clouds serverseitiges GIF, der OSS-Renderer kann es nicht erzeugen. Als statischen Titel oder Absatz neu aufbauen (Datum, oder „noch X Tage“) oder den HTML-Platzhalter behalten.
• Hover-Linkstile und Linkstile einzelner Blöcke — linkStyle.linkHoverColor und linkHoverUnderline haben kein Templatical-Feld und werden verworfen. Den eigenen linkStyle eines Textblocks liest der Konverter nicht; dessen Links übernehmen die Link-Einstellungen des Dokuments.
• AMP for Email — wird in Templatical derzeit nicht unterstützt.

Konvertierte Templates überprüfen

Überprüfen Sie nach der Konvertierung die Ausgabe im Editor auf:

1. Fehlende Bilder (bei Bedarf neu hochladen oder URLs aktualisieren)
2. Schriftdarstellung (Custom Fonts zur Editor-Konfiguration hinzufügen)
3. Spaltenverhältnisse (Layouts anpassen, falls das automatische Mapping nicht passt)
4. Abstände und Padding (im Block-Einstellungspanel feinjustieren)