unlayer-elements

使用 Unlayer Elements 构建（代码优先）

概述

@unlayer/react-elements 是一组 React 组件，可用于通过代码构建电子邮件、页面和文档，无需编辑器。编写一次 JSX，即可将其渲染为：

• 电子邮件 — 基于表格的 HTML（兼容 Outlook/Gmail/Yahoo）
• 网页 — 响应式 div/flexbox HTML
• 文档 — 针对打印 / PDF 优化的 HTML

输出会忠实复现 Unlayer 编辑器生成的内容，因此设计可以通过 JSON 与编辑器往返转换：renderToJson() 会返回设计 JSON，供可视化编辑器通过 loadDesign() 打开，让非开发人员也能编辑你用代码构建的模板。全面支持 SSR（Next.js、Remix、renderToString）。

何时使用此技能，何时使用编辑器

你的需求是……	使用
通过代码生成 / 组装模板（AI 生成、程序化电子邮件、设计系统）	此技能（@unlayer/react-elements）
通过代码构建模板，并且让团队成员通过可视化方式编辑	此技能（renderToJson()）+ unlayer-integration（loadDesign()）
在应用中嵌入拖放式可视化编辑器	unlayer-integration
从已保存的设计 / Cloud API 导出 HTML/PDF	unlayer-export

安装

npm view @unlayer/react-elements version   # verify the published version first
npm install @unlayer/react-elements

此技能面向 @unlayer/react-elements 0.1.11+（运行 npm view @unlayer/react-elements version 查看版本），且仅使用已验证可用的写法。以下常见写法——字符串 / 数字尺寸、对象或字符串形式的 fontFamily、提取为独立变量的样式对象——均可通过 0.1.11+ 的类型检查；较旧版本请升级。

心智模型 — 结构严格

<Email> | <Page> | <Document>        ← root wrapper, sets the render mode
  <Row layout={ColumnLayouts.X}>     ← layout container; column count MUST match the layout
    <Column>                         ← only Columns go directly in a Row
      <Heading /> <Paragraph />      ← items only inside Columns (no nesting)
      <Button /> <Image /> ...

• <Email> = 电子邮件模式，<Page> = 网页模式，<Document> = 打印模式。它们会将模式传递给所有子元素。
• <Row> 接收 layout={ColumnLayouts.TwoEqual}（或 cells={[1,1]}），并且必须包含数量完全匹配的 <Column> 子元素。
• 项目（Heading、Paragraph、Button、Image、Divider、Social、Menu、Table、Video、Html）应放在 <Column> 内部，绝不能直接放在 <Row> 中。

渲染

import { renderToHtml, renderToJson } from '@unlayer/react-elements';

const html = renderToHtml(<Email>…</Email>);   // final HTML string (no hydration markers)
const json = renderToJson(<Email>…</Email>);   // Unlayer design JSON (import into the editor)

请直接传入根元素（<Email>/<Page>/<Document>）。如果你将模板封装在自己的组件中，请调用它——renderToJson(MyEmail())——不要传入 <MyEmail />（渲染器会读取根元素类型，因此无法识别包装组件）。

完整示例

import {
  Email, Row, Column, ColumnLayouts,
  Heading, Paragraph, Button,
} from '@unlayer/react-elements';

const sans = { label: 'Sans', value: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Arial, sans-serif" };

export function Welcome() {
  return (
    <Email backgroundColor="#F6F9FC" contentWidth="600px" fontFamily={sans} previewText="You're all set — get started inside.">
      <Row layout={ColumnLayouts.OneColumn} backgroundColor="#FFFFFF" padding="32px 40px 8px 40px">
        <Column>
          <Heading headingType="h4" fontSize="12px" fontWeight={700} color="#635BFF" letterSpacing="0.08em">
            WELCOME
          </Heading>
          <Heading headingType="h1" fontSize="30px" fontWeight={700} color="#1A1F36" lineHeight="120%">
            You're all set.
          </Heading>
          <Paragraph html="Everything's ready — here's how to get started." fontSize="16px" color="#697386" lineHeight="155%" />
        </Column>
      </Row>
      <Row layout={ColumnLayouts.OneColumn} backgroundColor="#FFFFFF" padding="16px 40px 36px 40px">
        <Column>
          <Button href="https://example.com" backgroundColor="#635BFF" color="#FFFFFF"
            fontSize="16px" fontWeight={600} padding="14px 28px" borderRadius="8px" textAlign="center">
            Get started
          </Button>
        </Column>
      </Row>
    </Email>
  );
}

关键约定 — 使用规范写法

这些写法适用于所有版本。非规范写法（字符串形式的 fontFamily、纯数字形式的 fontSize）并不可靠。

• fontFamily 是一个对象：{ label, value }，例如 { label: 'Arial', value: 'arial, sans-serif' }。只定义一次并重复使用。
• fontWeight 是数字（700）。fontSize / padding / lineHeight / letterSpacing 是带单位的字符串：fontSize="28px"、padding="20px 40px"（以及 "0px"，绝不能用 "0"）、lineHeight="150%"（或无单位的 "1.5"）、letterSpacing="0.08em"。
• 大数字 / 金额必须使用 <Heading>，绝不能使用 <Paragraph>——段落的边距会随字号增大而膨胀，导致布局失衡。
• 列数必须与 Row 布局匹配（TwoEqual → 恰好 2 个 <Column>），否则该行将渲染为空。
• 行内格式应放在 <Paragraph html="…"> 中，并使用真实标签（<b>、<a href>）。Heading/Paragraph 的子元素必须是纯字符串——传入带标签的 JSX 子元素无法正确渲染。任何格式化内容都应使用 html。
• 根元素上的 previewText 会在渲染出的电子邮件 HTML 中显示收件箱预览文本。

图像尺寸——匹配 Unlayer 的模型

src 是一个 URL 字符串或 { url, width?, height? }，其中 width/height 是图像的自然尺寸，不是显示宽度。

• 默认是响应式——图像会填满所在列，但不会超过其自然尺寸。<Image src="…" /> 和 <Image src={{ url, width: 400, height: 260 }} /> 都会以响应式方式渲染。如果知道自然 width/height，请提供。
• 要设置固定显示尺寸，请在 src 对象上设置 autoWidth:false 和 maxWidth（相对于容器的百分比）：

  <Image src={{ url: 'https://…', autoWidth: false, maxWidth: '50%' }} altText="…" />
  

• **注意：**大型／主视觉图像目前渲染宽度最多约为 500px，无法完全铺满边到边——请将其在背景上居中。

让邮件真正美观

Agent 生成的邮件往往看起来很廉价。要让它们真正赏心悦目：

• 详情列表或明细项中，切勿使用 <Table headers={…} data={…}>。这种简写会渲染出带边框且没有内边距的电子表格。请改用标签／值行——左侧是柔和的标签，右侧是加粗的值，两者之间用 Column 的 border 对象绘制细线：

  const HAIRLINE = { borderBottomWidth: '1px', borderBottomStyle: 'solid', borderBottomColor: '#EBEBEB' };
  function detailRow(label: string, value: string, last = false) {
    const cell = { padding: '14px 0', border: last ? undefined : HAIRLINE };
    return (
      <Row layout={ColumnLayouts.TwoEqual} backgroundColor="#FFFFFF" padding="0 40px">
        <Column {...cell}><Paragraph html={label} fontSize="14px" color="#717171" /></Column>
        <Column {...cell}><Paragraph html={`<b>${value}</b>`} fontSize="14px" color="#222222" textAlign="right" /></Column>
      </Row>
    );
  }
  // call it inline: {detailRow('Total', '$1,248.00', true)} — NOT <detailRow/>;
  // a Row must be a direct child of the root, so a section helper must return a <Row>.
  

• 使用品牌的真实配色；在浅灰色的 Email backgroundColor 上放置白色内容行，营造卡片效果。

• 添加一个眉题：在主标题上方，用强调色显示小号大写 <Heading fontSize="12px" fontWeight={700} letterSpacing="0.08em">。

• 使用宽裕且一致的40–48px 水平内边距，并保持有意安排的垂直节奏。品牌 CTA 使用纯色，并设置约 8–10px 的 borderRadius。

• 全宽按钮（需要时）——传入顶层 width 属性（"100%"，或固定宽度 "200px"）：

  <Button width="100%" href="…" backgroundColor="…" color="#FFFFFF"
    fontSize="16px" fontWeight={700} padding="14px 28px" borderRadius="8px" textAlign="center">Get started</Button>
  

组件速查

Email/Page/Document（backgroundColor、contentWidth、fontFamily、textColor、previewText） · Row（layout/cells、backgroundColor、padding） · Column（padding、backgroundColor、borderRadius、border） · Heading（headingType h1–h6 / level、text/字符串子项、fontSize、fontWeight、color、lineHeight、letterSpacing、textAlign、fontFamily） · Paragraph（html 或字符串子项/text） · Button（href、backgroundColor、color、padding、borderRadius、textAlign；固定宽度通过 values 设置 size） · Image（src 字符串或对象、altText、action） · Divider（borderTop*） · Social（icons={[{name,url}]}） · Menu（items={[{text,href}]}） · Table（headers/data——仅用于真正的表格数据） · Video（videoUrl） · Html（html）。

完整属性表请参阅 references/component-reference.md；可直接使用的分区方案请参阅 references/patterns.md。

不在范围内

此技能是代码优先的库。关于拖放式可视化编辑器 SDK，请参阅 unlayer-integration；关于导出／Cloud API，请参阅 unlayer-export。