---
title: Migration von Unlayer
description: Konvertieren Sie Unlayer-E-Mail-Templates mit @templatical/import-unlayer ins Templatical-Format.
---

# 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

::: code-group

```bash [npm]
npm install @templatical/import-unlayer
```

```bash [pnpm]
pnpm add @templatical/import-unlayer
```

```bash [yarn]
yarn add @templatical/import-unlayer
```

```bash [bun]
bun add @templatical/import-unlayer
```

:::

### Ohne Build-Schritt (CDN)

Sie können es auch von einem CDN laden:

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

## Verwendung {#usage}

```ts
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](https://play.templatical.com/scenes/import-unlayer)

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, ein [Divider ohne Linie](#undrawn-dividers), der keinen Platz einnimmt, 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`](/de/guide/migration-from-html).

## Sprachen {#languages}

`values._languages[locale]` liefert Overrides. Text und `textJson` werden zu Paragraph `content`; Heading `text`, Button `text`, Image `altText` und Menütext werden zu gehashten Texteinträgen. Image `src.url` wird zu `set.src`; Row `backgroundImage.url` wird zum `set.backgroundImage` der Sektion. Menüeinträge werden nur bei gleicher Anzahl nach Position zugeordnet; andernfalls entfällt die Menüübersetzung mit Warnung. Übersetzte Links in Menüeinträgen werden nicht übernommen; Warnungen nennen jeden verworfenen Schlüssel und jede Sprache einmal. Ein lokalisiertes Hintergrundbild erbt die nicht angegebenen Einstellungen des Standardbilds; eine explizit leere übersetzte URL speichert `set.backgroundImage = null` und entfernt das Bild nur in dieser Sprache.

Moderner Text nutzt Lexical `textJson` vor dem älteren `text`; der Inhaltstyp `paragraph` wird unterstützt. Lesbares Lexical-Block-Markup bleibt ohne zusätzlichen Absatz-Wrapper erhalten. Unlesbarer Lexical-Zustand fällt auf `values.text` zurück. Eine Übersetzung nutzt nur ihr eigenes `textJson` oder älteres `text`: Ist beides nicht lesbar, wird kein Texteintrag gespeichert, die Abdeckung bleibt fehlend und der Bericht warnt. Das JSON enthält weder Standardsprache noch sprachabhängige Schreibrichtung: Übergeben Sie die Standardsprache des Hosts als `defaultLocale`. Ohne diese Option nimmt ein mehrsprachiges Design `"en"` an und warnt. Übersetzungen unter `_override.<device>._languages` werden mit Warnungen verworfen. Unbekannte Übersetzungsschlüssel und HTML-Fallback-Ziele erzeugen ebenfalls Warnungen.

Die Abbildung folgt [Unlayers dokumentierten Overrides](https://docs.unlayer.com/builder/templates/multi-language), geprüft am 2026-10-28. Die Fixtures stammen aus dieser Dokumentation, nicht aus echten mehrsprachigen Exporten.

Codes werden von `_` nach `-` normalisiert und müssen `isLocaleTag` bestehen. Nicht unterstützte Tags werden mit einer Warnung unter Angabe der Sprache verworfen. Texteinträge enthalten `{ value, sourceHash }`, gehasht aus dem importierten Standardwert. Aktivieren Sie `init({ localization: { locales } })` mit den importierten Sprachen, um das Sprachmenü anzuzeigen. Prüfen Sie das Ergebnis mit `template-tools validate imported.json --locale <tag>` und kontrollieren Sie `report.warnings`.

## Optionen {#options}

`convertUnlayerTemplate` akzeptiert als zweites Argument `ConvertUnlayerOptions`. `defaultLocale?: string` setzt `settings.locale`, wenn die Quelle keine Standardsprache angibt; andernfalls gilt `"en"`. Eine deklarierte Standardsprache hat Vorrang. Sprachcodes werden von `_` nach `-` normalisiert. Eine deklarierte Standardsprache oder ein `defaultLocale`, das danach kein Sprach-Tag ist, etwa ein Platzhalter <code v-pre>{{lang}}</code>, wird mit einem `report.warnings`-Eintrag ignoriert, der den Wert nennt; dann gilt der nächste gültige Wert oder `"en"`.

Dieses JSON-Format liefert dem Importer keine Standardsprache. Übergeben Sie die vom Host konfigurierte Sprache als `defaultLocale`.

```ts
export interface ConvertUnlayerOptions {
  defaultLocale?: string;
}
```

## 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](#image-width)) |
| Button | `button` | Konvertiert (angenähert, wenn `size.width` begrenzt wird oder unbrauchbar ist, siehe [Button-Breite](#button-width), oder `lineHeight` nicht lesbar ist, siehe [Zeilenhöhe von Buttons](#button-line-height)) |
| Divider | `divider`, oder `spacer`, wenn er [keine Linie zeichnet](#undrawn-dividers) | Konvertiert (angenähert, wenn ein Divider mit Teilbreite links oder rechts ausgerichtet ist; übersprungen, wenn er keine Linie zeichnet und keinen Platz einnimmt) |
| 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 {#image-width}

| 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 (siehe [Divider-Breite](#divider-width)) 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.
:::

### Button-Breite {#button-width}

| Unlayer-`size` | `ButtonBlock.width` | Status |
|---|---|---|
| fehlt, oder `autoWidth` `true` (Standard) | keine, der Button passt sich seiner Beschriftung an | Konvertiert |
| `autoWidth: false`, `width` `100%` | `"full"` | Konvertiert |
| `autoWidth: false`, `width` über 0 und unter `100%`, etwa `40%` | dieser Prozentwert auf zwei Nachkommastellen, `"40%"` | Konvertiert |
| `autoWidth: false`, `width` über `100%` | `"full"` | Angenähert |
| `autoWidth: false`, `width`, das auf `0%` rundet | keine, der Button passt sich seiner Beschriftung an | Angenähert |
| `autoWidth: false`, `width` fehlt oder ist kein Prozentwert | keine, der Button passt sich seiner Beschriftung an | Angenähert |

Unlayer wendet `width` nur an, wenn `autoWidth` `false` ist. Ein Prozentwert ist ein Anteil der Spalte abzüglich des `containerPadding` des Buttons, der Box, an der ein prozentuales `ButtonBlock.width` gemessen wird; der Button schrumpft daher auf dem Smartphone mit seiner Spalte. `fullWidthOnMobile` wird nicht importiert.

### Zeilenhöhe von Buttons {#button-line-height}

`lineHeight` wird zu `ButtonBlock.lineHeight`, ein Vielfaches der Schriftgröße der Beschriftung. Ein Prozentwert ist diese Zahl geteilt durch 100 (`150%` ist `1.5`), eine Zahl ohne Einheit ist sie selbst, eine px-Länge ist diese Pixelzahl geteilt durch die Schriftgröße des Buttons, und eine `em`-Länge ist die Zahl. Sie wird auf zwei Nachkommastellen gerundet. `120%` (Unlayers Standard), `normal` und ein fehlender Wert lassen es ungesetzt, was 1.2 rendert. Ein nicht lesbarer Wert wird mit 1.2 importiert, und der Eintrag ist angenähert, mit einer Notiz, die ihn nennt: `Button line-height "auto" could not be read; imported at 1.2.`

### Divider-Breite {#divider-width}

| 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, gemäß dem Spaltenlayout der Section oder ihren `columnWidths`, an der inneren Breite der Reihe, also an `settings.width` abzüglich des linken und rechten `padding` der Reihe, 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.

### Divider ohne Linie {#undrawn-dividers}

Ein Divider zeichnet keine Linie, wenn `border.borderTopWidth` 0 ist, `borderTopStyle` `none` oder `hidden` ist oder `borderTopColor` transparent ist: `transparent` oder eine Farbe mit Alpha 0 wie `rgba(0, 0, 0, 0)` oder `#ffffff00`. Ein solcher Divider fügt nur Abstand ein.

| Unlayer-Divider | Ergebnis | Status |
|---|---|---|
| zeichnet eine Linie | `divider`, nach den Regeln oben | Konvertiert |
| zeichnet keine Linie, Padding und transparenter Rahmen ergeben mehr als 0px | `spacer` | Konvertiert, mit einer `note`, die die Höhe nennt |
| zeichnet keine Linie und nimmt keinen Platz ein | kein Block | Übersprungen |

Die `height` des Spacers ist das obere plus das untere `containerPadding` plus die Breite eines transparenten Rahmens. Ein `containerPadding` mit einer negativen Seite zählt als kein Padding, weil CSS es verwirft. Ein Rahmen mit `none` oder `hidden` nimmt keinen Platz ein, seine Breite zählt also nicht. Ein Spacer rendert kein Padding, deshalb ist sein eigenes Padding 0. Ein Divider ganz ohne `border` wird als durchgezogene schwarze Linie von 1px importiert.

## 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'` |
| `[1, 3]` | `'1-3'` |
| `[3, 1]` | `'3-1'` |
| `[1, 2, 1]` | `'1-2-1'` |
| `[1, 1, 1, 1]` (gleiche Viertel) | `'4'` |
| 5+ Zellen | auf eine einzelne Spalte reduziert, mit Warnung |

Zellen sind relative Gewichte: Der Anteil einer Spalte ist ihre Zelle geteilt durch die Summe der Zellen der Reihe. Zellen, deren Anteile denen eines Presets entsprechen, behalten dieses Layout und setzen kein `columnWidths`; `[2, 4]` ist also `'1-2'` und `[3, 3, 3]` ist `'3'`. Jedes andere Verhältnis von zwei, drei oder vier Zellen behält das gleichmäßige Layout dieser Anzahl (`'2'`, `'3'` oder `'4'`) und setzt [`columnWidths`](/de/guide/sections-and-columns#custom-column-widths) auf die auf 100 skalierten Anteile. `[7, 3]` ist `[70, 30]`, `[2, 5, 2]` ist `[22.22, 55.56, 22.22]` und `[6, 2, 2, 2]` ist `[50, 16.67, 16.67, 16.66]`. Der Import gibt für dieses Verhältnis keine Warnung aus. Eine Zelle, die keine Zahl über 0 ist, lässt das gleichmäßige Layout ohne `columnWidths`. Wenn die Zellen zusammen mehr als 0 ergeben, nennt eine Warnung das Verhältnis: `Row with 2 columns at ratio 1:0 was kept as an even split. A cell that is not above 0 cannot be stored as column widths.` Zellen, die zusammen 0 oder weniger ergeben, erzeugen keine Warnung.

### Section-Hintergrund

| Unlayer-Reihenwerte | `section.styles.backgroundColor` |
|---|---|
| `columnsBackgroundColor` gesetzt | `columnsBackgroundColor` |
| nur `backgroundColor` gesetzt | ungesetzt; die Farbe liegt auf dem fensterbreiten Wrapper |

Setzt eine Reihe `backgroundColor`, wird diese Farbe zu `section.wrapper.backgroundColor` mit `wrapper.fullWidth: true`, auch wenn sie mit `columnsBackgroundColor` übereinstimmt. Die Section behält `columnsBackgroundColor`. Ohne Inhaltsfarbe bleibt der Section-Hintergrund ungesetzt, sodass der Streifen durch die Inhaltsbox scheint.

::: tip
`columnsBackgroundColor` füllt die Inhaltsbreite, also die Fläche, die eine Section einfärbt. `backgroundColor` füllt den Streifen außerhalb davon und liegt auf `section.wrapper` mit `fullWidth: true`, sodass der Streifen bis zum Fensterrand läuft.
:::

### Hintergrundbild der Section

Das `backgroundImage` einer Reihe wird zum `backgroundImage` der Section:

| `backgroundImage.fullWidth` | Ergebnis |
|---|---|
| `false` (die Inhaltsfläche) | Das Bild der Section, exakt. |
| weggelassen oder `true` | `wrapper.backgroundImage` mit `wrapper.fullWidth: true`. Die Section behält `columnsBackgroundColor` oder bleibt ungesetzt, wenn diese Farbe fehlt. |

Eine Streifenfarbe bleibt vom Wrapper, wenn die Section ein Bild der Inhaltsfläche behält (`fullWidth: false`): Outlook für Desktop malt eine Wrapper-Farbe über dieses Bild, und `report.warnings` nennt die verworfene Farbe.

`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](/de/guide/display-conditions), 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](/de/guide/custom-blocks) 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: das Rendern braucht einen serverseitigen GIF-Dienst, den das SDK nicht mitliefert. 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)
