MJML Head 组件完全指南:用 mj-head 掌控字体、默认属性、断点与样式

原创2026-10-10 16:40:271,368 阅读
文章标签:前端CLI

MJML Head 组件完全指南:用 mj-head 掌控字体、默认属性、断点与样式

MJML 邮件模板由 mjml 根标签统领,内部只允许两个直接子节点:mj-head 与 mj-body。其中 mj-head 承载的是整封邮件的"全局配置区"——导入字体、定义默认属性、创建 CSS 类、设置响应式断点、配置收件箱预览文本与文档标题。本文以仓库 doc/head_components.md 为主线,逐一拆解 MJML 标准 Head 组件的用法、属性与底层实现,让读者能够独立写出结构完整、可复用的邮件头部配置。

Head 组件是什么

Head components ease your development process, for example, enabling you to import fonts, define default styles or create classes for MJML components.

Head 组件用于减轻邮件开发负担:它让你导入网络字体(mj-font)、定义默认样式(mj-style、mj-attributes)、为 MJML 组件创建可复用的类(mj-class),还可以控制移动端与桌面端的切换宽度(mj-breakpoint)、设置邮件标题与预览文本(mj-title、mj-preview)以及向最终 HTML 注入自定义属性(mj-html-attributes)。

与 Body 组件(mj-section、mj-column、mj-text 等)不同,Head 组件不会直接输出可见的邮件内容,它们的作用是"写入配置",再由 MJML 引擎在渲染骨架时消费这些配置。

mj-head 在文档中的位置

一个标准的 MJML 文档骨架如下:

<mjml>
  <mj-head>
    <!-- 这里放置 head 组件 -->
  </mj-head>
  <mj-body>
    <!-- 这里放置 body 组件 -->
  </mj-body>
</mjml>

mj-head 本身是一个极简的容器组件,其源码只有一个 handler() 并转发给子组件处理:

// packages/mjml-head/src/index.js
export default class MjHead extends HeadComponent {
  static componentName = 'mj-head'

  handler() {
    return this.handlerChildren()
  }
}

handlerChildren() 定义在 mjml-core 的 HeadComponent 基类中:它遍历 mj-head 的子节点,对每个子标签初始化对应组件,并调用其 handler() 方法。也就是说,每个 Head 组件的核心逻辑都收敛在各自的 handler() 里,通过统一的 context.add() 接口把配置写入引擎的全局数据。

Head 组件的底层工作机制

在渲染主流程 mjml2html()(packages/mjml-core/src/index.js)中,引擎为 head 与 body 分别准备了独立的处理器。mj-head 及其子组件通过 headHelpers.add() 把数据写入名为 globalData 的全局对象:

const globalData = {
  breakpoint: '480px',
  classes: {},
  classesDefault: {},
  defaultAttributes: {},
  htmlAttributes: {},
  fonts,
  inlineStyle: [],
  headStyle: {},
  componentsHeadStyle: [],
  headRaw: [],
  mediaQueries: {},
  preview: '',
  style: [],
  title: '',
  forceOWADesktop: ...,
  lang: ...,
  dir: ...,
}

add(attr, ...params) 会根据目标字段的类型(数组 push、对象合并、单值赋值)把 mj-title 的标题、mj-preview 的预览文本、mj-font 的字体表、mj-attributes 的默认属性表等一一登记进去(见 packages/mjml-core/src/index.js)。

随后,引擎在组装最终 HTML 时,skeleton.js 会按顺序把各类配置渲染进 <head>:

  • <title> 来自 mj-title;
  • 字体 <link> 与 @import 由 buildFontsTags(fonts.js)生成;
  • 响应式媒体查询由 buildMediaQueriesTags(mediaQueries.js)基于 mj-breakpoint 与各组件登记的媒体查询生成;
  • mj-style 的内容经由 buildStyleFromTags 写入 <style>,inline="inline" 的样式则走 juice 内联流程(packages/mjml-core/src/index.js)。

理解这条"Head 组件 → globalData → 骨架 HTML"的流水线,就能明白为什么 Head 组件顺序无关、且各自职责单一。

逐一拆解七大标准 Head 组件

MJML 官方开箱即用的 Head 组件共七个,分别位于独立的 npm 包中(mjml-head-title、mjml-head-preview、mjml-head-font、mjml-head-breakpoint、mjml-head-style、mjml-head-attributes、mjml-head-html-attributes)。

mj-title:定义文档标题

mj-title 用于填充最终 HTML 的 <title> 标签(部分场景下显示在浏览器标签栏)。同时,它的内容还会被写入 body 标签直接子 div 的 aria-label 属性,用于辅助无障碍阅读(见 packages/mjml-head-title/README.md)。

<mjml>
  <mj-head>
    <mj-title>Hello MJML</mj-title>
  </mj-head>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text>Hello World!</mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

mj-title 是结束标签组件(endingTag = true),不支持任何属性。其 handler() 极为简单——直接调用 add('title', this.getContent())(packages/mjml-head-title/src/index.js)。

mj-preview:设置收件箱预览文本

mj-preview 用于设置邮件在收件人收件箱列表中显示的预览文字(preheader text),它同样不支持任何属性(packages/mjml-head-preview/README.md)。

<mjml>
  <mj-head>
    <mj-preview>Hello MJML</mj-preview>
  </mj-head>
  <mj-body>
    ...
  </mj-body>
</mjml>

引擎会把预览文本渲染为一个隐藏的 div,其实现位于 packages/mjml-body/src/helpers/preview.js:通过 display:none;font-size:1px;color:#ffffff;...opacity:0;overflow:hidden 等技巧,让文本对用户不可见、又对邮件客户端可读。

mj-font:按需导入外部字体

mj-font 用于导入网络字体,是制作品牌化邮件最常用的 Head 组件之一。它的两个属性如下(packages/mjml-head-font/README.md):

属性 类型 说明 默认值
href string 托管 CSS 文件的 URL(该 CSS 需包含 @font-face 声明) 无
name string 字体名称 无

例如引入 Google Fonts 的 Raleway 字体:

<mjml>
  <mj-head>
    <mj-font
      name="Raleway"
      href="https://fonts.googleapis.com/css?family=Raleway"
    />
  </mj-head>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text font-family="Raleway, Arial">Hello World!</mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

"按需导入"机制:mj-font 声明后并不会无条件输出 <link>。从 fonts.js 的源码可见,引擎会用正则 font-family:[^;}]*${name} 扫描最终内容与内联样式,只有模板中确实使用了该字体时,才会生成对应的 <link> 与 @import 标签。这意味着你可以放心地在 Head 中声明多种候选字体,未使用的不会被加载,从而避免拖慢邮件加载。

mj-breakpoint:控制响应式切换宽度

mj-breakpoint 允许你控制布局从桌面版切换到移动版(或反之)的临界宽度。其唯一属性如下(packages/mjml-head-breakpoint/README.md):

属性 类型 说明 默认值
width px 单位 断点值 480px
<mjml>
  <mj-head>
    <mj-breakpoint width="320px" />
  </mj-head>
  <mj-body>
    ...
  </mj-body>
</mjml>

默认值与底层影响:globalData.breakpoint 的默认值为 480px(packages/mjml-core/src/index.js),skeleton.js 中同样以 breakpoint = '480px' 兜底。mj-breakpoint 的 handler() 将 width 写入断点后,mediaQueries.js 会生成形如 @media only screen and (min-width:${breakpoint}) 的媒体查询,同时配合 makeLowerBreakpoint.js 生成 min-width - 1px 的移动端下界,确保桌面与移动样式无缝衔接。

其 allowedAttributes 声明为 width: 'unit(px)'(packages/mjml-head-breakpoint/src/index.js),说明该值必须是像素单位,传入其他单位会在校验阶段被拒绝。

mj-style:写入全局 CSS(含内联模式)

mj-style 允许你编写自定义 CSS,应用于 MJML 文档与最终输出的 HTML(packages/mjml-head-style/README.md)。默认情况下样式会写入渲染结果 <head> 的 <style> 中;加上 inline="inline" 属性后,样式会被内联到每个 HTML 元素上。

属性 类型 说明 默认值
inline string 设为 inline 以启用内联 无

典型用法是与所有 Body 组件都支持的 css-class 属性配合:

<mjml>
  <mj-head>
    <mj-attributes>
      <mj-class name="mjclass" color="green" font-size="30px" />
    </mj-attributes>
    <mj-style inline="inline">
      .blue-text div {
        color: blue !important;
      }
    </mj-style>
    <mj-style>
      .red-text div {
        color: red !important;
        text-decoration: underline !important;
      }
    </mj-style>
  </mj-head>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text css-class="red-text">I'm red and underlined</mj-text>
        <mj-text css-class="blue-text">I'm blue because of inline</mj-text>
        <mj-text mj-class="mjclass">I'm green</mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

实现细节:从 packages/mjml-head-style/src/index.js 可见,handler() 会根据 inline 属性把内容分别写入 inlineStyle(内联样式数组)或 style(常规样式数组)。内联样式最终由 juice 库在渲染阶段完成注入(packages/mjml-core/src/index.js),inlineStyle 通过 extraCss 参数参与内联计算。

实用提示:MJML 的一个标签会生成多个 HTML 标签,css-class 默认应用在最外层 HTML 标签上。因此要精准命中内部子标签(如 div)时,需要先查看生成的 HTML 来确定选择器写法。

mj-attributes:全局默认属性与 CSS 类

mj-attributes 是 Head 组件中功能最强的一个,支持三类子标签(packages/mjml-head-attributes/README.md):

  1. 组件标签(如 <mj-text />):覆盖该组件的默认设置;
  2. mj-all:影响所有 MJML 组件;
  3. mj-class:创建一组命名属性,可通过 mj-class="<name>" 应用到任意组件上。

完整示例:

<mjml>
  <mj-head>
    <mj-attributes>
      <mj-text padding="0" />
      <mj-class name="blue" color="blue" />
      <mj-class name="big" font-size="20px" />
      <mj-all font-family="Arial" />
    </mj-attributes>
  </mj-head>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text mj-class="blue big">Hello World!</mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

属性合并优先级(官方明确顺序):

  1. 标签内联属性(inline attributes,优先级最高);
  2. mj-attributes 中组件标签声明的属性(如 mj-text);
  3. mj-attributes 中 mj-all 声明的属性;
  4. MJML 内置默认值(优先级最低)。

这一顺序与源码 applyAttributes() 中的合并逻辑吻合:...defaultAttributes<a href="https://link.gitcode.com/i/cff7121fd2ec35828381a86ad146bf22" target="_blank">tagName] → ...classes → ...defaultAttributesForClasses → ...omit(attributes, ['mj-class']),最后展开的显式属性覆盖前面的默认值([packages/mjml-core/src/index.js)。

mj-class 的特殊能力:mj-class 还允许通过嵌套子标签为特定组件定制属性,例如:

<mj-attributes>
  <mj-class name="myClass" color="red">
    <mj-text font-size="24px" />
  </mj-class>
</mj-attributes>

此时 mj-class="myClass" 的组件会获得 color:red,而其中的 mj-text 还会叠加 font-size:24px。这一机制由 mjml-head-attributes/src/index.js 中的 classesDefault 分支实现——它把 mj-class 的子节点按 tagName 汇总成默认属性表。

mj-html-attributes:用 CSS 选择器注入自定义属性

mj-html-attributes 允许你基于 CSS 选择器,向生成 HTML 中的任意标签添加自定义属性(如 data-id),典型场景是可编辑模板(editable templates)与第三方系统集成(packages/mjml-head-html-attributes/README.md)。

<mjml>
  <mj-head>
    <mj-html-attributes>
      <mj-selector path=".custom div">
        <mj-html-attribute name="data-id">42</mj-html-attribute>
      </mj-selector>
    </mj-html-attributes>
  </mj-head>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text css-class="custom">Hello World!</mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

工作原理:mj-text 在输出 HTML 中会变成带 class="custom" 的 td 及其内部的 div。上面的配置会让 td 内部的 div 获得 data-id="42" 属性。一个 mj-html-attributes 中可以包含多个 mj-selector,一个 mj-selector 中可以包含多个 mj-html-attribute。

从 mjml-head-html-attributes/src/index.js 的源码可见,引擎先收集 path → {name: value} 映射表,然后在渲染完成后用 cheerio 以 xmlMode 解析 HTML,按选择器逐个注入属性(packages/mjml-core/src/index.js)。因此选择器必须与最终生成 HTML 的结构匹配,必要时请先查看渲染输出再确定 path。

Head 组件组合实战:一封带完整配置的邮件

将上述组件组合起来,可以得到一个结构完整的邮件模板:

<mjml owa="desktop" lang="fr" dir="ltr">
  <mj-head>
    <mj-title>Monthly Newsletter</mj-title>
    <mj-preview>Your monthly digest is ready</mj-preview>

    <mj-font
      name="Raleway"
      href="https://fonts.googleapis.com/css?family=Raleway"
    />
    <mj-breakpoint width="520px" />

    <mj-attributes>
      <mj-all font-family="Raleway, Helvetica, Arial" />
      <mj-text padding="0 20px" color="#525252" />
      <mj-class name="headline" font-size="28px" color="#F45E43" />
    </mj-attributes>

    <mj-style>
      .footer-note { font-size: 11px; color: #888888; }
    </mj-style>
  </mj-head>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text mj-class="headline">Hello there!</mj-text>
        <mj-text>Welcome to this month's newsletter.</mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

几点说明:

  • 根标签上的 owa="desktop" 会令 globalData.forceOWADesktop 为 true,为不支持媒体查询的老版(自托管)Outlook.com 强制输出桌面版样式(packages/mjml-core/src/index.js);lang、dir 则会被写入 <html> 标签。
  • mj-all font-family 定义了全局字体族;mj-class="headline" 使该段文字继承类属性;组件内显式属性(如果有)仍享有最高优先级。
  • 断点设为 520px 后,媒体查询按 min-width:520px 生成(mediaQueries.js),低于该宽度时移动端样式生效。

延伸阅读与源码索引

掌握这七个 Head 组件,你就能在不触碰 HTML 邮件脏细节的前提下,为模板建立起统一的字体体系、属性约定、响应式断点与自定义注入能力,让 MJML 的"语义化邮件开发"体验真正落地。

登录后查看全文
mjml