SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场email-html-mjml

email-html-mjml

编程与开发

查看项目

更新于 10-15 14:57

技能介绍

用途

email-html-mjml 用于通过 MJML 5.x 框架生成响应式 HTML 邮件模板，并编译为可投入生产的 HTML。其首要目标是兼容性：覆盖 Outlook（2013–365）、Gmail（网页版/App）、Apple Mail 及主流移动客户端。每一份输出都必须能在 --config.validationLevel=strict 下编译通过，并且不超过 Gmail 的 102KB 裁剪限制。

当用户要求创建、生成、设计或构建邮件模板（包括欢迎邮件、促销邮件、订单确认、新闻简报等）时使用本技能。

主要能力

  • 生成合法、跨客户端可用的 MJML 5.x 模板，并编译为生产级 HTML。
  • 内置 9 条工程规则：结构完整性、响应式默认值、Outlook 兼容、Gmail 优化、深色模式、无障碍、样式效率、Hero 区块、模板支持。
  • 覆盖无障碍检查清单：设置 <mj-title>、根标签 lang 属性、图片与社交元素 alt、通过 mj-html-attributes 设置标题角色、4.5:1 对比度、避免文字烘焙进图片。
  • 提供深色模式模式（color-scheme / supported-color-schemes meta、亮暗 logo 切换、安全中性色 #121212 与 #F1F1F1）。
  • 提供组件索引，按 Head、Layout、Content、Interactive、Advanced 分组，写 MJML 前需先读取相应组件文件。
  • 提供四个示例文件：basic-layout.mjml（仅结构）、order-confirmation.mjml（事务类，含 mj-include 与 Handlebars）、promo-sale.mjml（促销类，含 mj-hero 与背景图）、newsletter.mjml（编辑类 + 深色模式）。示例中所有文案、图片 URL 与品牌均为占位符，不可直接发布。

使用方式

工作流程：

  1. 收集需求 — 从用户消息与对话上下文推断邮件类型、品牌色和内容。只询问真正缺失且阻塞进度的问题，不要一开始就抛出问卷。
  2. 规划布局 — 在写代码前先决定并说明结构（单栏、双栏网格、Hero + 内容等）。
  3. 加载组件参考 — 在写任何 MJML 之前，先从组件索引读取相关文件。
  4. 生成 MJML — 写出完整合法的 MJML，以 <mjml> 开头并包含完整 <mj-head>。
  5. 编译 — 遵循 compilation.md，运行带 --config.minify=true 的 npx mjml。
  6. 交付两个文件 — 始终同时输出 .mjml 源文件与编译后的 .html。

关键编译命令：

npx mjml template.mjml -o dist/template.html --config.minify=true --config.validationLevel=strict

硬性规则：绝不 npm install -g mjml；始终使用 npx 或 ./node_modules/.bin/mjml；若 package.json 中没有 mjml，建议 npm install -D mjml。

适用场景

  • 事务类邮件：如订单确认，含收据表格与带 scope="col" 表头。
  • 促销类邮件：含 mj-hero、section 背景图、mj-navbar、mj-group 不堆叠行、mj-social。
  • 编辑类邮件与新闻简报：含深色模式、mj-wrapper、aria-level 标题。
  • 需要模板插值的场景：普通插值 {{firstName}} 无需包裹即可通过；仅含 < 或 > 的块标签需要 <!-- htmlmin:ignore --> 保护。

限制与注意事项

  • JavaScript 在所有邮件客户端（Gmail、Outlook、Apple Mail、iOS Mail）中完全被屏蔽，无 onclick、无剪贴板 API、无任何交互；看似可交互的元素仅为装饰。
  • MJML 5 默认禁用 mj-include：需 CLI 加 --config.allowIncludes true，Node API 传 ignoreIncludes: false；仅支持 MJML、HTML、CSS include；模板自身目录之外的局部文件除非其目录被加入白名单否则会被拒绝。--config.validationLevel=strict 不会捕获此问题，编译成功不等于 include 已生效，交付前应 grep 输出中的已知局部内容。
  • Outlook：背景图 VML 仅为 <mj-section> 与 <mj-hero> 生成；背景定位仅支持关键字值（top、center、bottom），像素值会被忽略；background-repeat="no-repeat" 必须搭配明确的 background-size；mj-font 通过 MSO 条件注释对 Outlook 隐藏 @font-face。
  • Gmail：关键布局使用组件属性，CSS 类可能被剥离；始终以 --config.minify=true 编译以控制 102KB 裁剪。
  • iOS / Android 堆叠：MJML 5 的 minify 不再移除标签间空白，htmlnano 会将连续空白折叠为单个空格；仍有效的防堆叠手段是 MJML 加在父 <td> 上的 font-size:0px。可通过 --config.minifyOptions '{"collapseWhitespace":"all"}' 恢复 v4 的空白剥离行为。
  • 垂直对齐 bug：若某 section 中任一列设置了 vertical-align，则该 section 中所有列都必须显式设置。
  • 不得在列内内容组件之间放置 <mj-raw>，否则会在 </tr> 与 <tr> 之间输出内容导致标记非法；mj-raw 应放在 section 之间，且模板标签不应放进 <mj-style>。
  • 无头标题角色需通过 mj-html-attributes 设置，直接在 mj-text 上加 role/aria-level 在严格校验下非法。
  • 应避免使用 <mj-accordion> 与 <mj-carousel>，客户端支持太差。