Back to Details

unlayer-export

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Export Content

导出内容

Overview

概述

Unlayer supports multiple export formats. Some are client-side (free), others use the Cloud API (paid).
Unlayer支持多种导出格式，部分为客户端免费功能，其余则需使用付费的Cloud API。

Which Export Method?

选择哪种导出方式？

MethodOutputPaid?Use When
exportHtml
HTML + design JSONNoEmail sending, web publishing, saving designs
exportPlainText
Plain text + designNoSMS, accessibility fallback
exportImage
PNG URL + designYesThumbnails, previews, social sharing
exportPdf
PDF URL + designYesPrint-ready documents
exportZip
ZIP URL + designYesOffline download packages
Critical: Always save the design JSON alongside any export. All export methods return 
data.design
— save it so users can edit later.
方式输出格式是否付费适用场景
exportHtml
HTML + design JSON否邮件发送、网页发布、保存设计
exportPlainText
纯文本 + 设计数据否SMS短信、无障碍内容备选
exportImage
PNG链接 + 设计数据是缩略图、预览图、社交分享
exportPdf
PDF链接 + 设计数据是可打印文档
exportZip
ZIP链接 + 设计数据是离线下载包
重要提示： 导出任何内容时，请务必同时保存design JSON。所有导出方法都会返回
data.design
——请保存该数据，以便用户后续编辑。

Save & Load Designs

保存与加载设计

javascript
// SAVE — use exportHtml to get both design JSON and HTML
unlayer.exportHtml(async (data) => {
  await fetch('/api/templates', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      design: data.design,  // Save this — needed to edit later
      html: data.html,      // The rendered HTML output
    }),
  });
});

// LOAD — restore a saved design (must wait for editor:ready)
unlayer.addEventListener('editor:ready', async () => {
  const response = await fetch('/api/templates/123');
  const saved = await response.json();
  unlayer.loadDesign(saved.design);   // Pass the saved JSON object
});

// LOAD BLANK
unlayer.loadBlank({ backgroundColor: '#ffffff', contentWidth: '600px' });

// LOAD AN UNLAYER TEMPLATE
unlayer.loadTemplate(templateId);     // ID from Unlayer dashboard
javascript
// SAVE — use exportHtml to get both design JSON and HTML
unlayer.exportHtml(async (data) => {
  await fetch('/api/templates', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      design: data.design,  // Save this — needed to edit later
      html: data.html,      // The rendered HTML output
    }),
  });
});

// LOAD — restore a saved design (must wait for editor:ready)
unlayer.addEventListener('editor:ready', async () => {
  const response = await fetch('/api/templates/123');
  const saved = await response.json();
  unlayer.loadDesign(saved.design);   // Pass the saved JSON object
});

// LOAD BLANK
unlayer.loadBlank({ backgroundColor: '#ffffff', contentWidth: '600px' });

// LOAD AN UNLAYER TEMPLATE
unlayer.loadTemplate(templateId);     // ID from Unlayer dashboard

Export HTML

导出HTML

javascript
unlayer.exportHtml((data) => {
  const { html, design, chunks } = data;

  // html     — Full HTML document (string)
  // design   — Design JSON (always save this!)
  // chunks   — { css, js, body, fonts, tags }
  //   body   — Just the content inside <body> (no wrapper)
  //   css    — Extracted CSS styles
  //   fonts  — Web fonts used in the design

  // Save both to your backend
  await fetch('/api/templates', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ design, html }),
  });
}, {
  // All options are optional
  cleanup: true,          // Remove editor markup (default: true)
  minify: false,          // Minify HTML output
  inlineStyles: false,    // Move CSS inline (for email clients)
  mergeTags: {},          // Replace merge tags with real values
  title: 'My Email',     // Set HTML <title>
});
Using chunks — when you need just the body content (no 
<!DOCTYPE>
wrapper):
javascript
unlayer.exportHtml((data) => {
  const { body, css, fonts } = data.chunks;
  const myHtml = `<style>${css}</style>${fonts}${body}`;
});
javascript
unlayer.exportHtml((data) => {
  const { html, design, chunks } = data;

  // html     — Full HTML document (string)
  // design   — Design JSON (always save this!)
  // chunks   — { css, js, body, fonts, tags }
  //   body   — Just the content inside <body> (no wrapper)
  //   css    — Extracted CSS styles
  //   fonts  — Web fonts used in the design

  // Save both to your backend
  await fetch('/api/templates', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ design, html }),
  });
}, {
  // All options are optional
  cleanup: true,          // Remove editor markup (default: true)
  minify: false,          // Minify HTML output
  inlineStyles: false,    // Move CSS inline (for email clients)
  mergeTags: {},          // Replace merge tags with real values
  title: 'My Email',     // Set HTML <title>
});
使用chunks — 当你仅需要主体内容（不含
<!DOCTYPE>
包裹）时：
javascript
unlayer.exportHtml((data) => {
  const { body, css, fonts } = data.chunks;
  const myHtml = `<style>${css}</style>${fonts}${body}`;
});

Export Plain Text

导出纯文本

javascript
unlayer.exportPlainText((data) => {
  const { text, design } = data;
  // Use as email plain-text fallback
}, {
  ignorePreheader: false,
  ignoreLinks: false,
  ignoreImages: false,
  mergeTags: {},
});
javascript
unlayer.exportPlainText((data) => {
  const { text, design } = data;
  // Use as email plain-text fallback
}, {
  ignorePreheader: false,
  ignoreLinks: false,
  ignoreImages: false,
  mergeTags: {},
});

Export Image (Paid — Cloud API)

导出图片（付费——Cloud API）

Generates a PNG screenshot of the design. The image uploads to your connected File Storage.
Client-side:
javascript
unlayer.exportImage((data) => {
  // data.url    — PNG URL
  // data.design — Design JSON (always save this!)
  console.log('Image URL:', data.url);
}, {
  fullPage: false,           // true = entire page, false = viewport
  mergeTags: {},
});
Server-side via Cloud API (get API key from Dashboard > Project > Settings > API Keys):
javascript
const response = await fetch('https://api.unlayer.com/v2/export/image', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Basic ' + Buffer.from('YOUR_API_KEY:').toString('base64'),
  },
  body: JSON.stringify({
    displayMode: 'email',
    design: designJSON,       // The saved design JSON object
    mergeTags: {},
  }),
});

const data = await response.json();
// data.url — image URL
生成设计的PNG截图，图片会上传至你关联的文件存储服务。
客户端实现：
javascript
unlayer.exportImage((data) => {
  // data.url    — PNG URL
  // data.design — Design JSON (always save this!)
  console.log('Image URL:', data.url);
}, {
  fullPage: false,           // true = entire page, false = viewport
  mergeTags: {},
});
通过Cloud API服务端实现（从控制台>项目>设置>API密钥获取API密钥）：
javascript
const response = await fetch('https://api.unlayer.com/v2/export/image', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Basic ' + Buffer.from('YOUR_API_KEY:').toString('base64'),
  },
  body: JSON.stringify({
    displayMode: 'email',
    design: designJSON,       // The saved design JSON object
    mergeTags: {},
  }),
});

const data = await response.json();
// data.url — image URL

Export PDF / ZIP (Paid — Cloud API)

导出PDF / ZIP（付费——Cloud API）

javascript
// PDF
unlayer.exportPdf((data) => {
  // data.url    — PDF URL
  // data.design — Design JSON
}, { mergeTags: {} });

// ZIP
unlayer.exportZip((data) => {
  // data.url    — ZIP URL
  // data.design — Design JSON
}, { mergeTags: {} });
javascript
// PDF
unlayer.exportPdf((data) => {
  // data.url    — PDF URL
  // data.design — Design JSON
}, { mergeTags: {} });

// ZIP
unlayer.exportZip((data) => {
  // data.url    — ZIP URL
  // data.design — Design JSON
}, { mergeTags: {} });

Auto-Save Pattern

自动保存模式

Design + HTML (recommended):

设计数据 + HTML（推荐）：

javascript
let saveTimeout;

unlayer.addEventListener('design:updated', () => {
  clearTimeout(saveTimeout);
  saveTimeout = setTimeout(() => {
    unlayer.exportHtml(async (data) => {
      await fetch('/api/templates/123', {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ design: data.design, html: data.html }),
      });
    });
  }, 1000);
});
javascript
let saveTimeout;

unlayer.addEventListener('design:updated', () => {
  clearTimeout(saveTimeout);
  saveTimeout = setTimeout(() => {
    unlayer.exportHtml(async (data) => {
      await fetch('/api/templates/123', {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ design: data.design, html: data.html }),
      });
    });
  }, 1000);
});

Design + HTML + Thumbnail (full):

设计数据 + HTML + 缩略图（完整方案）：

javascript
let saveTimeout;

unlayer.addEventListener('design:updated', () => {
  clearTimeout(saveTimeout);
  saveTimeout = setTimeout(() => {
    // Save design + HTML immediately
    unlayer.exportHtml(async (data) => {
      await fetch('/api/templates/123', {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ design: data.design, html: data.html }),
      });
    });

    // Generate thumbnail (slower, paid — debounce longer or do on manual save)
    unlayer.exportImage(async (data) => {
      if (!data.url) return;
      await fetch('/api/templates/123/thumbnail', {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ thumbnailUrl: data.url }),
      });
    }, { fullPage: false });
  }, 3000); // Longer debounce for image generation
});
javascript
let saveTimeout;

unlayer.addEventListener('design:updated', () => {
  clearTimeout(saveTimeout);
  saveTimeout = setTimeout(() => {
    // Save design + HTML immediately
    unlayer.exportHtml(async (data) => {
      await fetch('/api/templates/123', {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ design: data.design, html: data.html }),
      });
    });

    // Generate thumbnail (slower, paid — debounce longer or do on manual save)
    unlayer.exportImage(async (data) => {
      if (!data.url) return;
      await fetch('/api/templates/123/thumbnail', {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ thumbnailUrl: data.url }),
      });
    }, { fullPage: false });
  }, 3000); // Longer debounce for image generation
});

Design JSON Quick Reference

设计JSON快速参考

The design JSON has this structure (see references/design-json.md for full TypeScript types):
JSONTemplate
├── counters          — Internal counters
├── schemaVersion     — Currently 16
└── body
    ├── rows[]        — Each row contains columns
    │   ├── cells[]   — Column ratios: [1,1] = 50/50
    │   └── columns[]
    │       └── contents[]  — Content items (text, image, button...)
    ├── headers[]     — Same as rows (with headersAndFooters feature)
    ├── footers[]     — Same as rows
    └── values        — Body-level styles (backgroundColor, contentWidth, fontFamily)
Content types: 
text
, 
heading
, 
button
, 
image
, 
divider
, 
social
, 
html
, 
video
, 
menu
, 
timer
.
设计JSON的结构如下（完整TypeScript类型请参考references/design-json.md）：
JSONTemplate
├── counters          — Internal counters
├── schemaVersion     — Currently 16
└── body
    ├── rows[]        — Each row contains columns
    │   ├── cells[]   — Column ratios: [1,1] = 50/50
    │   └── columns[]
    │       └── contents[]  — Content items (text, image, button...)
    ├── headers[]     — Same as rows (with headersAndFooters feature)
    ├── footers[]     — Same as rows
    └── values        — Body-level styles (backgroundColor, contentWidth, fontFamily)
内容类型包括：
text
、
heading
、
button
、
image
、
divider
、
social
、
html
、
video
、
menu
、
timer
。

Common Mistakes

常见错误

MistakeFix
Only saving HTML, not design JSONAlways save both — all export methods return 
data.design
Calling export before 
editor:ready
Wait for the event first
Not configuring File Storage for image/PDF exportImage and PDF uploads go to your connected File Storage
Not debouncing auto-save
design:updated
fires on every keystroke — debounce 1-3 seconds
Ignoring 
chunks
in exportHtml		Use 
chunks.body
when you need just content without 
<!DOCTYPE>
wrapper
Missing API key for image/PDF/ZIPCloud API key required — get from Dashboard > Project > Settings > API Keys
错误修复方案
仅保存HTML，未保存设计JSON务必同时保存两者——所有导出方法都会返回
data.design
在
editor:ready
事件触发前调用导出方法		先等待该事件触发
未为图片/PDF导出配置文件存储服务图片和PDF会上传至你关联的文件存储服务，请先完成配置
未对自动保存做防抖处理
design:updated
事件会在每次按键时触发——设置1-3秒的防抖延迟
忽略
exportHtml
中的
chunks
参数		当你需要不含
<!DOCTYPE>
包裹的内容时，请使用
chunks.body
图片/PDF/ZIP导出时缺少API密钥需使用Cloud API密钥——从控制台>项目>设置>API密钥获取

Troubleshooting

故障排查

ProblemFix
exportImage
returns error		Check API key, check Cloud API plan, verify design isn't empty
Exported HTML looks different from editorUse 
cleanup: true
(default), check custom CSS
design:updated
fires too often		Always debounce — it fires on every property change
Loaded design shows blankCheck 
schemaVersion
compatibility, validate JSON structure
问题修复方案
exportImage
返回错误		检查API密钥、Cloud API套餐，确认设计内容非空
导出的HTML与编辑器预览效果不一致使用默认的
cleanup: true
配置，检查自定义CSS
design:updated
事件触发过于频繁		务必添加防抖处理——该事件会在每次属性变更时触发
加载的设计显示空白检查
schemaVersion
兼容性，验证JSON结构是否正确

Resources

参考资源