maizzle

Maizzle

使用 Vue 组件和 Tailwind CSS 构建并发送可在所有主流邮件客户端中正常显示的 HTML 邮件。

安装

创建项目骨架。Maizzle 6 官方起始模板为 maizzle/maizzle，分支为 master：

npx maizzle new maizzle/maizzle#master [directory]

对于 i18n（多语言）邮件，请使用 maizzle/starter-i18n#master。

添加到现有项目：

npm i @maizzle/framework

// package.json
{ "scripts": { "dev": "maizzle serve", "build": "maizzle build" } }

开发服务器会生成 .maizzle/（用于自动导入组件和组合式函数的类型定义 .d.ts）。请将其加入 tsconfig.json。支持 npm、yarn、pnpm、bun。

基础模板

<script setup>
defineConfig({
  name: { type: String, default: 'friend' },
})
</script>

<template>
  <Layout>
    <Container class="max-w-xl">
      <Section>
        <Heading level="1" class="text-2xl font-semibold mb-4">
          Welcome, {{ name }}!
        </Heading>
        <Text class="text-gray-700 mb-6">
          Build HTML emails with Vue and Tailwind.
        </Text>
        <Button class="bg-blue-600 text-white px-4 py-2 rounded" href="https://maizzle.com">
          Learn more
        </Button>
      </Section>
    </Container>
  </Layout>
</template>

组件

所有内置组件都会自动导入。完整的属性和用法见 references/COMPONENTS.md；多列布局模式见 references/PATTERNS.md。

文档结构 — <Layout>、<Html>、<Head>、<Body>、<Tailwind>、<Font>、<Preheader>

布局基元 — <Container>、<Section>、<Row>、<Column>

内容 — <Heading>、<Text>、<Link>、<Button>、<Img>、<Hr>、<Spacer>、<Markdown>、<CodeBlock>、<CodeInline>、<QrCode>

条件语句与逃生口 — <Outlook>、<NotOutlook>、<OutlookBg>、<Plaintext>、<NotPlaintext>、<Raw>、<NoWidows>、<WithUrl>

AMP4Email — <amp-*> 标签会原样保留（原生支持，不会解析组件）。<style amp-custom> 会像 <style embed> 一样保留——在其中使用 @apply 时，请使用 @reference "@maizzle/tailwindcss"（而非 @import）。

编写规则

精确修改：只更改要求修改的内容。除非明确要求，否则保留现有结构、组件和类列表。

除非明确要求，否则优先使用内置组件，而非原始 HTML —— 它们封装了电子邮件客户端的特殊兼容性处理。使用 Tailwind 工具类设置样式；也可以使用任意值。不要在 <Button> 上添加 box-border 或 align="left"（默认就是左对齐），也不要在 <Hr> 上添加 border-solid border-*（使用 bg-* 设置颜色）。

电子邮件中没有 box-sizing。 切勿在显式设置宽度的元素上设置 padding（或左右边框）——例如带有任何 w-*/min-w-*/max-w-* 的 <Column>，或指定了 width 的 <Section>/<Container>。padding 会加到外部宽度上（content-box），导致列溢出并上下堆叠，而不是并排显示。将宽度设在外层元素上，并将 padding 放在嵌套的 <Section class="px-* border-0"> 上（或者在手动编写的表格中，放在 <td> 上）。未设置宽度的 <Section>/<Container> 为 width:auto，可安全容纳 padding，因此可以在这些元素上使用 px-*。（上下边框和垂直 padding 不影响宽度，因此可以用于设置宽度的元素。）请参阅 PATTERNS.md → 列间距。

不要添加重复声明 text-* 尺寸内置行高的 leading-* —— text-* 尺寸自带配套的 line-height；只有需要偏离时才添加 leading-*（配对关系见 references/STYLING.md）。

不要添加 mso-style 来为 Outlook 重复设置 padding/背景 —— <Container>、<Section>、<Column> 会自动将类中的 background-color/padding* 提升到 MSO <td> 上。mso-style 仅用于 Outlook 专属覆盖。（如果元素有水平边框，或 <Column> 使用百分比宽度，则不会自动提升。）

在不同电子邮件客户端中的表现：

• Windows 上的 Outlook 桌面版使用 Word 作为渲染器 —— 不支持 border-radius、background-image、现代 CSS 或媒体查询。Maizzle 的组件会在需要时加入 MSO 幽灵表格 / VML。
• Gmail 会截断超过约 102 KB 的电子邮件。保持模板精简；生产环境中应进行压缩。<QrCode> 可能会很占空间。
• 布局：较旧的客户端不支持 flex/grid。使用 <Row> / <Column>。
• 响应式：sm:（≤600px）、xs:（≤430px）——许多客户端支持，可作为渐进增强。
• 深色模式：通过 prefers-color-scheme 使用 dark:。支持情况不一；应将其视为增强功能。
• 图片：生产环境中使用 PNG/JPEG/GIF；通过 <Img dark-src motion-src> 提供变体。始终设置 alt 和 width。
• 间距：区块元素之间优先使用 <Spacer>（Outlook 会忽略部分外边距）。文本上的外边距可以使用。
• 避免使用：position: absolute/relative、嵌入式 SVG（Gmail）、用于布局的内联 <style> 块。

关于品牌颜色和 Logo 的收集、深度样式指南、深色模式和页脚模式，请参阅 references/STYLING.md。

静态资源和 URL

将静态文件放在 public/ 中。通过绝对路径引用（/logo.png）。构建时会将 public/ 复制到输出目录。

生产环境中的重写（相对 URL → 绝对 URL）通过配置中的 url.base 实现，或使用 <WithUrl> 限定作用范围：

// maizzle.config.ts
export default defineConfig({
  url: { base: 'https://cdn.example.com/emails/' },
})

<WithUrl base="https://cdn.example.com/emails/">
  <Img src="/logo.png" alt="Logo" width="120" />
</WithUrl>

两者都会跳过绝对 URL、数据 URI、协议相对 URL 和片段。UTM/查询参数：使用全局 url.query，或使用限定作用范围的 <WithUrl parameters="utm_source=...">。

以模板标签开头的值（{{、{%、<%，例如 Twig/Liquid/Blade/ERB）永远不会添加前缀。若要让特定元素的 URL 保持编写时的内容，请在该元素（HTML 标签或组件）上添加 no-base-url。它仅应用于该元素，不影响其子元素，并会从输出中移除：

<Img src="/logo.png" alt="Logo" width="120" no-base-url />

样式概览

Maizzle 通过 @maizzle/tailwindcss 使用 Tailwind CSS 4，提供适用于电子邮件的重置样式、MSO 工具类和客户端变体。<Layout> 已导入该插件。如需手动控制：

<Head>
  <style>@import "@maizzle/tailwindcss";</style>
</Head>

默认情况下，css.inline、css.purge、css.shorthand、css.safe、css.preferUnitless、css.sixHex 和 html.decodeEntities 均已启用。html.minify 已关闭。

客户端变体：gmail:、gmail-android:、apple-mail:、ios:、outlook-mac:、outlook-android:、yahoo:、thunderbird:、superhuman:、notion:、spark:、……

完整的 CSS / HTML / 流水线配置项：references/CONFIGURATION.md 和 references/TRANSFORMERS.md。

编程式渲染

import { render } from '@maizzle/framework'

const { html, plaintext } = await render('emails/welcome.vue', {
  config: { css: { inline: true, purge: true }, plaintext: true },
})

接受 SFC 路径、原始 SFC 字符串或导入的 Vue 组件。运行 SSR 和完整的转换器流水线。

纯文本

全局启用：

export default defineConfig({ plaintext: true })

也可以在每个模板的 <script setup> 中通过 usePlaintext() 启用。传入对象即可自定义目标路径、扩展名和去除 HTML 的选项。参见 references/COMPOSABLES.md。

CLI

使用 npx maizzle …，或通过 npm i -g maizzle 全局安装。完整的命令和标志参考：references/CLI.md。

参考文档

• references/COMPONENTS.md — 所有组件、属性和示例。
• references/PATTERNS.md — 列布局 / 响应式布局模式。
• references/STYLING.md — Tailwind、颜色令牌、品牌简介和编写原则。
• references/CONFIGURATION.md — 所有配置项、默认值和示例。
• references/COMPOSABLES.md — defineConfig、useConfig、useTransformers、useBaseUrl、useUrlQuery、useEvent、useDoctype、usePlaintext、usePreheader、useHead。
• references/TRANSFORMERS.md — 流水线顺序和各阶段行为。
• references/CLI.md — 所有 CLI 命令、标志和用法。
• references/CONVERT-REACT-EMAIL.md — 从 React Email 迁移的指南。
• references/CONVERT-MAIZZLE-V5.md — 从 Maizzle 5 升级到 Maizzle 6 的指南。