Novu 项目 React Email 组件参考从react-email/components到可上线的邮件模板【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu本篇技术指南围绕 Novu 仓库.agents中为 Agent 与开发者准备的 React Email 技能组件参考 展开系统梳理react-email/components提供的全部组件、Props 与推荐写法。读完本文你将能够基于TailwindpixelBasedPreset的组合独立搭建欢迎邮件、密码重置、通知确认等事务性邮件模板并掌握在客户端兼容性约束下不支持rem、flexbox、媒体查询等写出可直接用于 Novu 邮件工作流的高质量模板代码。这份文档在仓库中的定位在 Novu 仓库中.agents/skills/react-email目录是一份供编码 Agent 使用的完整技能包其中SKILL.md定义了技能主流程安装、开发服务器、模板骨架、样式约束而 COMPONENTS.md 是该技能包的组件级权威参考与 STYLING.md、PATTERNS.md、I18N.md、SENDING.md 互为补充。React Email 是一套高质量、无预设样式的 React 组件集合用组件化方式构建在主流邮件客户端均能正常渲染的 HTML 邮件。这一点与 Novu 本身高度契合Novu 的 Framework Email 步骤文档 明确推荐用 React Email 组件编写邮件模板、再通过render()输出 HTML 交由邮件工作流发送从而保证模板与品牌一致且易于维护。需要特别记住两条硬性约定只导入真正用到的组件。未使用却出现在代码中的组件不应被导入这既影响包体积也容易让模板校验误判依赖关系。所有组件统一从react-email/components导入含render与pixelBasedPreset。组件全景速览全部组件均从react-email/components导入按用途可分为四类类别组件一句话作用结构Html邮件根包裹始终作为最外层组件结构Head承载title、style、meta等文档级头部内容结构Body邮件正文的主包裹容器结构Container内容在断点处水平居中自带最大宽度约束结构Section可通过行/列进一步排版的分区结构Row/Column行内水平分隔内容区 / 列内垂直分隔内容区Column 必须配合 Row内容Preview收件箱中显示的预览文本内容Headingh1–h6 标题块内容Text以空白间隔的文本块内容Button外观像按钮的链接含 Outlook 内边距修复内容Link指向网页、邮件地址等 URL 的超链接内容Img展示图片内容Hr分隔不同内容区域的分割线专用Tailwind用 Tailwind CSS 包裹并统一样式专用CodeBlock基于 Prism.js 的主题化正则高亮代码块专用CodeInline在所有客户端表现一致的行内代码元素专用Markdown将 Markdown 转换为合法邮件模板代码专用Font声明自定义字体下文按Tailwind 主题 → 结构组件 → 内容组件 → 专用组件的顺序逐一讲解保证每个组件的代码示例、Props、最佳实践不遗漏。Tailwind推荐的样式方案组件参考文档明确将Tailwind定位为 React Email 组件推荐的样式方式——用组件包裹邮件内容再通过工具类utility classes完成排版与配色。import { Tailwind, pixelBasedPreset, Html, Body, Container, Heading, Text, Button } from react-email/components; export default function Email() { return ( Html langen Tailwind config{{ presets: [pixelBasedPreset], theme: { extend: { colors: { brand: #007bff, accent: #28a745 }, }, }, }} Body classNamebg-gray-100 font-sans Container classNamemax-w-xl mx-auto p-5 Heading classNametext-2xl font-bold text-brand mb-4 Welcome! /Heading Text classNametext-base text-gray-700 mb-4 Your content here. /Text Button hrefhttps://example.com classNamebg-brand text-white px-6 py-3 rounded-lg block text-center Get Started /Button /Container /Body /Tailwind /Html ); }PropsconfigTailwind 配置对象透传给底层 Tailwind 编译过程。底层工作方式Tailwind 工具类在构建阶段被自动转换为内联样式媒体查询被抽取出来放到head的style标签内CSS 变量如--brand会被解析成最终值RGB 颜色语法会被规范化以保证不同邮件客户端的兼容性。必须遵守的注意事项始终使用pixelBasedPreset——主流邮件客户端不支持rem单位只有像素级预设才能让间距、字号在所有客户端一致.agents/skills/react-email/SKILL.md的样式章节也重复强调了这一点自定义 config 是可选的默认配置在多数场景已足够扩展配色时优先使用theme.extendsm:、md:、lg:等响应式断点工具类虽然能通过媒体查询工作但由于邮件客户端对媒体查询支持有限应谨慎使用技能行为准则更是建议在用户主动要求时才考虑否则一律采用堆叠布局。结构组件搭好邮件的骨架Html邮件的根组件必须始终作为最外层为内容提供lang、dir语义。import { Html, Tailwind, pixelBasedPreset } from react-email/components; Html langen dirltr Tailwind config{{ presets: [pixelBasedPreset] }} {/* email content */} /Tailwind /HtmlPropslang语言代码如en、es、frdir文本方向ltr或rtl本地化邮件可借此支持阿拉伯语、希伯来语等从右向左语言。Head存放与文档相关的头部元素title、style、meta等。使用 Tailwind 时必须放在Tailwind内部以便抽取出的媒体查询与字体声明能正确落到此处。import { Head } from react-email/components; Head titleEmail Title/title /HeadHead也是自定义字体Font与国际化场景的标准挂载点。Body包裹邮件正文内容的组件通常在这里设置全局背景色与字体。import { Body } from react-email/components; Body classNamebg-gray-100 font-sans {/* email content */} /Body按技能默认结构Body 推荐使用font-sans py-10 bg-gray-100为内容留出垂直呼吸空间。Container一个在断点处将内容水平居中的布局组件内置37.5em的最大宽度约束换算为像素基准约 600px正是行业公认的邮件安全宽度。import { Container } from react-email/components; Container classNamemax-w-xl mx-auto p-5 {/* centered content */} /Container技能文档的Best Practices建议邮件整体最大宽度保持在 600px 左右并确保移动端表现良好Container 即承担这一职责。默认结构下 Container 通常为白色底、内容左对齐。Section表示一个内容分区分区内部可再用Row/Column编排是邮件表格布局语义化的关键组件。import { Section } from react-email/components; Section classNamep-5 bg-white {/* section content */} /SectionRow 与 ColumnRow在水平方向分隔内容区Column在垂直方向分隔内容区Column必须与Row组合使用即Row内部放多个Column。两者正是邮件客户端不支持 flexbox/grid 时替代多栏布局的官方方案——其底层输出为表格结构保证 Outlook、Gmail 渲染一致。import { Section, Row, Column } from react-email/components; Section Row Column classNamew-1/2 p-2 align-top Left column content /Column Column classNamew-1/2 p-2 align-top Right column content /Column /Row /SectionColumn 宽度建议优先使用百分比宽度类如w-1/2、w-1/3或使用 Tailwind 宽度工具类各列宽度之和应达到 100% 或等于容器宽度避免出现溢出或塌陷。内容组件填充邮件的血肉Preview出现在收件人收件箱列表中的预览文本在决定打开率上非常关键。import { Preview } from react-email/components; PreviewWelcome to our platform - Get started today!/Preview最佳实践控制在 140 字符以内文案要有吸引力、导向行动action-oriented始终作为Body内的第一个元素确保其在 DOM 中出现位置正确、行为可预期。Heading标题块支持 h1–h6 六级。import { Heading } from react-email/components; Heading ash1 classNametext-2xl font-bold text-gray-800 mb-4 Welcome to Acme /Heading Heading ash2 classNametext-xl font-semibold text-gray-600 mb-3 Getting Started /HeadingPropsasHTML 标题层级取值h1至h6。结合技能排版规范标题使用粗体、更大字号、更大外边距正文使用常规字重、更小字号与更小外边距形成清晰的内容层级。Text以空白间隔区分的文本块是邮件正文段落的标准载体。import { Text } from react-email/components; Text classNametext-base leading-6 text-gray-800 my-4 Your paragraph content here. /Text注意Text与普通p的差异Text被设计为跨客户端稳定渲染的块级文本段落间距建议通过外边距类显式控制。Button外观为按钮的链接针对 Outlook 的 padding 问题内置了 workaround是全模板最高频的 CTA 组件。import { Button } from react-email/components; Button hrefhttps://example.com/verify target_blank classNamebg-blue-600 text-white px-5 py-3 rounded block text-center no-underline font-medium Verify Email Address /ButtonPropshref必填链接目标 URLtarget打开方式默认_blank。样式技巧使用block让按钮占满容器宽度成为通栏按钮用text-center居中按钮文字加no-underline去掉按钮文字下划线按技能要求还应加上box-border避免内边距导致内容溢出 padding 区域。Link可以指向网页、mailto:邮箱地址等任何 URL 的超链接是正文内嵌链接的常规组件。import { Link } from react-email/components; Link hrefhttps://example.com target_blank classNametext-blue-600 underline Visit our website /LinkPropshref必填链接目标target默认_blank。Img展示图片的组件。邮件环境比 Web 严苛得多图片处理有一组硬性规范。import { Img } from react-email/components; Img srchttps://example.com/logo.png altCompany Logo width150 height50 classNameblock mx-auto /Propssrc必填图片 URL必须是绝对地址alt必填无障碍替代文本width/height以像素为单位的宽高。最佳实践始终使用托管在 CDN 上的绝对 URL技能要求先向用户确认生产环境静态资源地址禁止硬编码localhost:3000始终提供 alt 文本显式指定宽高防止布局位移用block类规避部分客户端对图片下方空隙的间距问题图片文件仅支持 PNG/JPGSVG 与 WEBP 在邮件客户端渲染不可靠应明确提醒用户。Hr分隔内容区域的分割线。import { Hr } from react-email/components; Hr classNameborder-gray-200 my-5 /由于邮件客户端对缩写边框如仅写border支持不一致技能规范要求始终明确边框类型border-solid、border-dashed等当只定义单侧边框时记得先用border-none重置其余三侧。专用组件代码、Markdown 与字体CodeBlock基于 Prism.js 渲染带主题与正则高亮的代码块适合发送给开发者用户的验证码/接入指引类邮件。import { CodeBlock, dracula } from react-email/components; const Email () { const code export default async (req, res) { try { const html await renderAsync( EmailTemplate({ firstName: John }) ); return NextResponse.json({ html }); } catch (error) { return NextResponse.json({ error }); } }; return ( div classNameoverflow-auto CodeBlock fontFamilymonospace theme{dracula} languagejavascript code{code} / /div ); };Propscode必填要渲染的实际代码纯字符串需自带正确的缩进language必填PrismLanguage中支持的语言如javascript、python、typescripttheme必填代码块主题从react-email/components导入dracula、github、nord等fontFamily可选代码块字体族如monospacelineNumbers可选是否自动显示行号布尔值默认false。两条硬性要求除非用户明确要求否则不要开启lineNumbers始终用带overflow-auto的div包裹CodeBlock避免横向溢出把邮件撑破。CodeInline提供在所有邮件客户端表现一致的行内代码 HTML 元素。普通code在各客户端的默认样式千差万别CodeInline用于消除这些差异。import { Text, CodeInline } from react-email/components; Text classNametext-base text-gray-800 Run CodeInline classNamebg-gray-100 px-1 roundednpm install/CodeInline to get started. /TextMarkdown将 Markdown 字符串转换为合法的 React Email 模板代码适合内容以文案为主的邮件如月刊、公告。import { Html, Markdown } from react-email/components; const Email () { return ( Html langen dirltr Markdown markdownCustomStyles{{ h1: { color: red }, h2: { color: blue }, codeInline: { background: grey }, }} markdownContainerStyles{{ padding: 12px, border: solid 1px black, }} {# Hello, World!}/Markdown {/* OR */} Markdown children{# This is a ~~strikethrough~~} / /Html ); };Propschildren必填Markdown 字符串markdownCustomStyles对转换后 HTML 元素h1、h2、p、a、codeInline等的样式覆写markdownContainerStyles容器div的样式。以上三种调用形态children 模板字符串、childrenprop 传入均等价可按可读性选择。Font声明邮件中使用的自定义网络字体。邮件客户端对自定义字体支持有限因此必须提供可靠的fallbackFontFamily。import { Head, Font } from react-email/components; Head Font fontFamilyRoboto fallbackFontFamilyArial, sans-serif webFont{{ url: https://fonts.gstatic.com/s/roboto/v27/KFOmCnqEu92Fr1Mu4mxKKTU1Kg.woff2, format: woff2 }} / /HeadPropsfontFamily必填字体族名称fallbackFontFamily加载失败时的回退字体栈webFont含url与format的对象。支持的字体格式woff2推荐体积最小、支持最广wofftruetypeopentype模板骨架与 Novu 工作流的衔接把组件串起来就得到技能文档中的标准邮件骨架——这一结构与 Novu 官方推荐的用法完全一致。在 Novu Framework 的 React Email 集成文档 中模板的编写与发送链路是安装依赖npm install react-email/components react-email编写邮件组件并通过render()导出 HTML 渲染函数例如文档中的render(TestEmailTemplate name{name} /)在 workflow 的step.email()中把渲染结果赋给body通过controlSchema/payloadSchema声明主题、用户姓名等变量交给 Novu 完成实际投递。因此本文所有组件知识都可直接迁移到 Novu 邮件工作流模板中模板内的{{}}占位符类变量不应硬编码进 JSX技能规范要求直接引用 props 字段把占位符值放入PreviewProps便于本地预览测试真正需要动态化的数据则通过 workflow 的 payload/controls 注入。一个可复制的组合骨架同时体现组件顺序与 Tailwind 用法import { Html, Head, Preview, Body, Container, Heading, Text, Button, Tailwind, pixelBasedPreset } from react-email/components; interface WelcomeEmailProps { name: string; verificationUrl: string; } export default function WelcomeEmail({ name, verificationUrl }: WelcomeEmailProps) { return ( Html langen Tailwind config{{ presets: [pixelBasedPreset] }} Head / PreviewWelcome - Verify your email/Preview Body classNamebg-gray-100 font-sans Container classNamemax-w-xl mx-auto p-5 Heading ash1 classNametext-2xl text-gray-800Welcome!/Heading Text classNametext-base text-gray-800Hi {name}, thanks for signing up!/Text Button href{verificationUrl} classNamebg-blue-600 text-white px-5 py-3 rounded block text-center no-underline box-border Verify Email /Button /Container /Body /Tailwind /Html ); }组件选型与邮件最佳实践速查选型建议需要页面级骨架Html→Tailwind→Head→Preview→Body需要单栏居中内容Container需要分块分区Section需要两/三栏SectionRowColumn宽度用百分比需要 CTAButton正文链接Link正文段落Text标题层级Heading需要呈现代码CodeBlock配overflow-auto容器/CodeInline需要自定义字体Head内的Font需要大段文案驱动的邮件Markdown。发送前的通用检查综合自技能参考与本文组件行为跨客户端测试Gmail、Outlook、Apple Mail、Yahoo Mail用 Litmus / Email on Acid 等做精确验证保持响应式主内容宽度 ≤ 600px并测试移动端图片一律绝对 URL CDN alt 文本提供纯文本版本render(..., { plainText: true })兼顾无障碍与部分客户端单封邮件体积控制在 102KB 以内超出会被 Gmail 截断为所有组件 props 定义 TypeScript 接口并补.PreviewProps便于开发期预览生产环境from地址使用已验证域名发送时检查返回的error。如需更贴近真实业务的组合模板密码重置、订单确认、多栏布局、自定义字体邮件等可继续阅读仓库内的 PATTERNS.md涉及多语言时参照 I18N.md要接入实际发送链路则参照 SENDING.md。三者与本文共同构成一套从组件认知到工程落地的完整邮件开发体系。【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考