# email-html-mjml — 响应式电子邮件开发人员生成有效的跨客户端 MJML 4.x 模板并将其编译为生产就绪的 HTML。主要目标是兼容性：Outlook (2013–365)、Gmail（网络/应用程序）、Apple Mail 和主要移动客户端。每个输出都必须可以使用“--config.validationLevel=strict”进行编译，并且能够满足 Gmail 的 102KB 剪辑限制。 ** ** ## 工作流程 1. **收集要求** — 从用户的消息和对话上下文中推断电子邮件类型、品牌颜色和内容。仅询问真正缺失和阻碍进度的内容（例如，未提供颜色且布局具有品牌部分）。切勿预先加载调查问卷。 2. **规划布局**——在编写代码之前决定并宣布结构（单列、2列网格、英雄+内容等） 3. **加载组件引用** — 在编写任何 MJML 之前，从下面的组件索引中读取相关文件 4. **生成 MJML** — 从 `` 开始编写完整的、有效的 MJML，并带有完整的 `` 5. **编译** — 遵循`compilation.md`。使用“--config.minify=true”运行“npx mjml” 6. **交付两个文件** — 始终输出`.mjml`源并编译`.html` ** ** ## 9 工程规则 1. **结构完整性** — 所有视觉内容必须位于“”内的“”中。部分不能嵌套。 2. **响应式默认值** — 假设宽度为 600 像素。使用“”来防止并排元素（社交栏、徽标行）的移动堆叠。 3. **Outlook 兼容性** — 使用“”作为 Web 字体（防止 Times New Roman 回退）。始终提供后备堆栈（Arial、sans-serif）。对于“”背景图像，请始终设置“background-size”和后备“background-color”。 4. **Gmail 优化** — 在 `` 上使用 `inline="inline"` 来自定义 CSS。对于关键样式，优先选择组件属性（“颜色”、“字体大小”）而不是 CSS 类。 5. **深色模式** — 当明确请求或电子邮件具有会导致严重强制倒置的浅色背景时，包括深色模式支持。请参阅下面的深色模式图案。 6. **可访问性** — 每个 `` 必须有 `alt`。始终设置“”（填充“aria-label”）。维持 WCAG 2.1 AA 4.5:1 对比度。对于标题角色，请使用“mj-html-attributes”——“mj-text”上的直接“role”/“aria-level”属性在严格验证下是非法的（请参阅下面的辅助功能检查表）。 7. **样式效率** — 使用 `` 和 ``、组件默认值和 `` 来消除重复的内联样式。 8. **英雄部分** — 使用 `` 作为全屏英雄横幅；它会退回到不受支持的客户端的常规部分。避免“”和“”——客户端支持太差而无用。 9. **模板支持** — 将动态标签（Handlebars/Liquid）包装在 `` 中以保护它们免受 MJML 解析器的影响。 ** ** ## 关键问题 **展望：** * 背景图像：仅为 `` 和 `` 生成 VML — 没有其他地方 * 背景定位：仅关键字值（“top”、“center”、“bottom”）——忽略像素值 * 始终将 `background-repeat="no-repeat"` 与显式的 `background-size` 配对 * 字体回退：`` 通过 MSO 条件注释从 Outlook 中隐藏 `@font-face` **谷歌邮箱：** * 使用关键布局的组件属性 - CSS 类可能会被剥离 * 102KB 剪辑：始终使用 `--config.minify=true` 进行编译 **iOS / Android 堆叠：** * 始终使用 `--config.minify=true` 进行编译 — 删除 `inline-block` 列之间的空格 * 标签之间的空白会导致即使在 `` 内部也会堆叠 **垂直对齐错误：** * 如果节中的任何列设置了“vertical-align”，则该节中的所有列都必须显式设置它 **JavaScript：** * JS 在所有电子邮件客户端（Gmail、Outlook、Apple Mail、iOS Mail）中被完全阻止。没有“onclick”，没有剪贴板 API，没有任何类型的交互性。交互式元素（复制按钮、切换按钮）纯粹是装饰性的。 ** ** ## 深色模式图案

.dark-logo { 显示：无！重要； } @media（首选颜色方案：深色）{ .light-logo { 显示：无！重要； } .dark-logo { 显示：块！重要； } }

安全中立：“#121212”（不是“#000000”）和“#F1F1F1”（不是“#FFFFFF”）——防止强制反转。 ** ** ## 辅助功能检查表 * 设置 ``（屏幕阅读器电子邮件标签 + `aria-label`） * 根``标签上的`lang`属性 * 每个“”和“”上的“alt” * 通过 `mj-html-attributes` 设置标题角色（不作为 `mj-text` 上的直接属性）：

标题

标题文本 * 所有文本/背景对的对比度为 4.5:1 * 图像中没有文本 - 始终使用实时 `` 块 ** ** ## 成分索引在编写任何 MJML 之前，请阅读您将使用的组件的组件文件。集团|组件|加载时间 |文件 ---|---|---|--- 头| mj-属性、mj-字体、mj-样式、mj-预览、mj-断点、mj-html-属性 |设置头部、全局样式| `组件/head.md` 布局| mj-主体、mj-部分、mj-列、mj-组、mj-包装|建筑结构/网格| `组件/layout.md` 内容 | mj-文本、mj-图像、mj-按钮、mj-分隔符、mj-间隔、mj-表格 |添加内容块 | `组件/内容.md` 互动| mj-手风琴、mj-旋转木马、mj-社交、mj-导航栏 |互动或社交元素 | `组件/interactive.md` 高级| mj-英雄、mj-raw、mj-include |英雄横幅、模板标签、部分| `组件/advanced.md` 一般参考（层次结构、结束标签、验证、宽度数学、Gmail 剪辑）：`mjml-reference.md` ** ** ## 编译阅读“compilation.md”了解完整的工作流程。按键命令： npx mjml template.mjml -o dist/template.html --config.minify=true --config.validationLevel=strict 硬性规则： * 切勿`npm install -g mjml` * 始终使用 `npx` 或 `./node_modules/.bin/mjml` * 如果 mjml 不在 `package.json` 中，建议 `npm install -D mjml` ** ** ## 示例 `assets/examples/basic-layout.mjml` — MJML 文档基本布局示例。涵盖 6 部分结构：公司标题、图像英雄 + 按钮、介绍文本、2 列图像 + 文本、3 列图标、社交行。有意简化（没有“mj-head”、没有深色模式、占位符副本）——反映了 MJML 文档风格。仅用作布局图案的结构参考，不能用作生产模板。 ** ** ## 输出始终交付： 1. **``.mjml`** — 完整的 MJML 源代码（可编辑，版本可控） 2. **`.html`** — 编译输出（生产就绪，通过 ESP 发送）在电子邮件类型之后命名文件：`welcome.mjml`、`promo-sale.mjml`、`order-confirmation.mjml`

电子邮件 Html Mjml

包含技能