unlayer-elements

Unlayer Elements を使った構築（コードファースト）

概要

@unlayer/react-elements は、メール、ページ、ドキュメントをコードで構築するための React コンポーネント集です。エディターは必要ありません。JSX を一度記述するだけで、次の形式にレンダリングできます。

• メール — テーブルベースの HTML（Outlook／Gmail／Yahoo で安全）
• ウェブ — レスポンシブな div／flexbox HTML
• ドキュメント — 印刷／PDF に最適化された HTML

出力は Unlayer エディターが生成するものを忠実に再現するため、デザインは JSON としてエディターに戻せます。renderToJson() は、ビジュアルエディターが loadDesign() で開けるデザイン JSON を返します。これにより、開発者以外のメンバーもコードで構築したテンプレートを編集できます。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> は使用しないでください。段落のマージンはフォントサイズに応じて拡大するため、レイアウトが大きく崩れます。
• <Column> の数は <Row> のレイアウトと一致させる必要があります（TwoEqual → <Column> が正確に 2 つ）。一致しない場合、行は空でレンダリングされます。
• インライン書式は、実際のタグ（<b>、<a href>）を使って <Paragraph html="…"> に記述してください。Heading／Paragraph の子要素にはプレーンな文字列を指定する必要があります。タグを含む JSX を子要素として渡しても正しくレンダリングされません。書式を設定する場合は html を使用してください。
• ルートの previewText は、レンダリングされたメール HTML に受信トレイのプレビューテキストを表示します。

画像サイズ — Unlayer のモデルに合わせる

src は URL 文字列、または { url, width?, height? } です。ここで width／height は表示幅ではなく、画像の NATURAL サイズです。

• デフォルトはレスポンシブです — 画像はカラムいっぱいに広がり、自然なサイズを上限とします。<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で表示され、端から端までは広がりません。背景の中央に配置してください。

見栄えを良くする方法

エージェントが生成したメールは、安っぽく見えることがよくあります。本当に見栄え良く仕上げるには、次の点に注意してください。

• 詳細リストや明細には、<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 に、borderRadius は約8〜10pxを設定します。

• ボタンを全幅にする場合 — 最上位の 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 を参照してください。