---
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 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).

## 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 |
| 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 {#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 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](/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: 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)