unlayer-export

导出内容

概览

Unlayer 支持多种导出格式。有些在客户端处理（免费），有些使用 Cloud API（付费）。

使用哪种导出方式？

方法	输出	是否付费？	适用场景
exportHtml	HTML + 设计 JSON	否	发送电子邮件、发布网页、保存设计
exportPlainText	纯文本 + 设计	否	SMS、无障碍备用内容
exportImage	PNG URL + 设计	是	缩略图、预览、社交分享
exportPdf	PDF URL + 设计	是	可直接打印的文档
exportZip	ZIP URL + 设计	是	离线下载包

重要： 务必将设计 JSON与任何导出内容一并保存。所有导出方法都会返回 data.design——请将其保存，以便用户之后编辑。

---

保存和加载设计

// 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

---

导出 HTML

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> 包装）时：

unlayer.exportHtml((data) => {
  const { body, css, fonts } = data.chunks;
  const myHtml = `<style>${css}</style>${fonts}${body}`;
});

---

导出纯文本

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

---

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

生成设计的 PNG 截图。图像会上传到你已连接的文件存储。

客户端：

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 在服务端调用（从 Dashboard > Project > Settings > API Keys 获取 API 密钥）：

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

---

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

// 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: {} });

---

自动保存模式

设计 + HTML（推荐）：

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);
});

设计 + HTML + 缩略图（完整）：

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
});

---

设计 JSON 速查

设计 JSON 的结构如下（完整 TypeScript 类型请参阅 references/design-json.md）：

JSONTemplate
├── counters          — Internal counters
├── schemaVersion     — Schema version number
└── 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。

---

常见错误

错误	修复方法
只保存 HTML，不保存设计 JSON	务必同时保存两者——所有导出方法都会返回 data.design
在 editor:ready 之前调用导出	先等待该事件
未为图像/PDF 导出配置文件存储	图像和 PDF 会上传到你已连接的文件存储
未对自动保存进行防抖	design:updated 会在每次按键时触发——请设置 1-3 秒的防抖时间
忽略 exportHtml 中的 chunks	只需要内容（不含 <!DOCTYPE> 包装）时，请使用 chunks.body
缺少图像/PDF/ZIP 所需的 API 密钥	需要 Cloud API 密钥——请从 Dashboard > Project > Settings > API Keys 获取

故障排除

问题	修复方法
exportImage 返回错误	检查 API 密钥和 Cloud API 方案，并确认设计不为空
导出的 HTML 与编辑器中的显示不同	使用 cleanup: true（默认值），并检查自定义 CSS
design:updated 触发过于频繁	务必进行防抖——该事件会在每次属性变更时触发
加载的设计显示为空白	检查 schemaVersion 兼容性，并验证 JSON 结构

资源

• 导出 HTML
• 导出图像
• 导出 PDF
• 导出纯文本
• 保存和加载设计
• Cloud API