mjml-head-font 深入解析:MJML 中通过 mj-font 智能加载邮件外部字体
mjml-head-font 深入解析:MJML 中通过 mj-font 智能加载邮件外部字体
导读
mjml-head-font 是 MJML 框架中负责“外部字体导入”的核心 head 组件,其对应的标签为 mj-font。在邮件 HTML 中,外部字体通常需要以 <link> 或 @import 的方式声明,但 MJML 并不简单地把这段声明原样照搬进输出——它只会在模板正文确实使用到该字体时才注入对应的字体加载标签。本文将以 packages/mjml-head-font/README.md 为主线,结合 mj-font 组件源码 与 字体标签构建器 fonts.js,完整讲解 mj-font 的用法、两个核心属性、默认字体注册机制,以及“按需引入”背后的实现原理。读完本文,你将能在自己的 MJML 模板中正确注册并引入任意网络字体,并理解输出 HTML 中字体标签的生成规则。
一、mj-font 是什么:MJML 的外部字体声明组件
mj-font 是一个只允许出现在 <mj-head> 内部的头部组件(Head Component),它的唯一职责是导入外部字体(external fonts)。与 <mj-style> 直接内联 CSS 不同,mj-font 指向的是一个托管了 @font-face 声明的远程 CSS 文件,例如 Google Fonts 的样式表地址:
https://fonts.googleapis.com/css?family=Raleway
这个 URL 返回的 CSS 中包含 @font-face 规则,定义了 Raleway 字体的字形文件来源与字重变体。mj-font 的角色就是告诉 MJML 渲染器:“模板里可能会用到名为 Raleway 的字体,请从该地址加载它。”
从源码结构看,该组件被实现为一个继承自 HeadComponent 的类,包内仅有一个入口文件 packages/mjml-head-font/src/index.js,package.json 声明其唯一核心依赖是 mjml-core(同版本 5.4.0),并在构建时通过 Babel 输出到 lib/ 目录(见 packages/mjml-head-font/package.json)。
二、完整示例:注册 Raleway 并在正文中使用
原 README 给出了一个最小可用示例,这里保持原样并补充行内注释以便逐行理解:
<mjml>
<mj-head>
<!-- 声明外部字体:name 是字体名,href 是托管 @font-face 的 CSS 地址 -->
<mj-font name="Raleway"
href="https://fonts.googleapis.com/css?family=Raleway" />
</mj-head>
<mj-body>
<mj-section>
<mj-column>
<!-- 正文中通过 font-family 引用该字体 -->
<mj-text font-family="Raleway, Arial">
Hello World!
</mj-text>
</mj-column>
</mj-section>
</mj-body>
</mjml>
要点拆解:
<mj-font>必须放在<mj-head>之内;name="Raleway"与正文中font-family的第一个字体名保持大小写一致,这是触发字体加载的关键匹配条件;font-family="Raleway, Arial"提供了回退方案——当邮件客户端无法加载 Raleway 时,会依次回退到 Arial,最终回退到客户端默认字体。这是邮件中引用网络字体的标准写法,可以避免“字体加载失败导致样式异常”。
三、属性说明:href 与 name
原 README 的属性表如下,两列补充了各自的约束与行为细节:
| attribute | accepts | description | default value |
|---|---|---|---|
| href | string | URL of a hosted CSS file | (无默认值) |
| name | string | name of the font | (无默认值) |
结合源码 packages/mjml-head-font/src/index.js 可以看到,组件把 allowedAttributes 精确限制为这两个属性:
static allowedAttributes = {
name: 'string',
href: 'string',
}
属性行为细节:
name(必填语义上的字体标识):声明的字体名称,同时也是正文 CSSfont-family匹配时的“关键字”。它不必与@font-face内部定义的字体族名完全一致,但必须与正文中实际书写的字体名匹配才能触发加载(匹配逻辑见下文“按需注入”一节)。href(必填的样式表地址):指向一个托管 CSS 文件的 URL,该文件内需包含@font-face声明。它既可以是 Google Fonts 这类公共字体服务的地址,也可以是自托管字体服务或 CDN 上任意可公开访问的样式表地址。- 两者在 README 中均未标注默认值,即未声明时不产生任何字体注册效果;若只写了
name而没有href,或反之,该字体同样不会被正确加载。
四、仅注入实际使用的字体:按需加载的核心机制
mj-font 最值得注意的行为是 README 第一句强调的:“only applied if the template uses the font”(仅当模板使用该字体时才生效)。这一点从组件与核心渲染器的配合中可以看得非常清楚。
4.1 组件层:把字体注册进全局 context
组件自身的 handler 并不直接输出任何 HTML,而是把 (name, href) 这对映射写入渲染上下文:
handler() {
const { add } = this.context
add('fonts', this.getAttribute('name'), this.getAttribute('href'))
}
(见 packages/mjml-head-font/src/index.js)
也就是说,mj-font 完成的是声明注册,真正的 HTML 输出发生在后续骨架(skeleton)拼装阶段。
4.2 渲染器层:比对正文后决定是否输出
在 packages/mjml-core/src/helpers/skeleton.js 中,buildFontsTags 被嵌入到 <head> 的生成流程里:
${buildFontsTags(content, inlineStyle, fonts)}
而 packages/mjml-core/src/helpers/fonts.js 实现了完整的按需判定逻辑:
export function buildFontsTags(content, inlineStyle, fonts = {}) {
const toImport = []
forEach(fonts, (url, name) => {
const regex = new RegExp(`"[^"]*font-family:[^"]*${name}[^"]*"`, 'gmi')
const inlineRegex = new RegExp(`font-family:[^;}]*${name}`, 'gmi')
if (content.match(regex) || inlineStyle.some((s) => s.match(inlineRegex))) {
toImport.push(url)
}
})
if (toImport.length > 0) {
return `
<!--[if !mso]><!-->
${map(toImport,
(url) => `<link href="${url}" rel="stylesheet" type="text/css">`,
).join('\n')}
<style type="text/css">
${map(toImport, (url) => `@import url(${url});`).join('\n')}
</style>
<!--<![endif]-->\n
`
}
return ''
}
这里的关键判断逻辑可以拆成三步:
- 遍历已注册字体:以
fonts对象({ name: url }结构)为输入,逐个检查模板正文; - 两类匹配规则:
content.match(regex):在正文 HTML 中查找形如font-family:...且包含字体名的属性值字符串(用于匹配如font-family="Raleway, Arial"这类属性写法);inlineStyle.some(...):在所有内联样式(inlineStyle数组)中查找font-family:声明里出现该字体名的片段(用于匹配组件样式属性中生成的 style 内容);- 正则均带
i标志,即匹配时不区分大小写;
- 只对“被用到”的字体生成标签:只有命中匹配的字体 URL 才会被收集进
toImport,进而输出加载代码;若没有任何字体被实际使用,函数直接返回空字符串,<head>中不会出现多余的<link>或@import。
4.3 输出形态:link + @import 双保险,且绕过 Outlook
命中的字体最终会以如下形式注入输出 HTML 的 <head>:
<!--[if !mso]><!-->
<link href="https://fonts.googleapis.com/css?family=Raleway" rel="stylesheet" type="text/css">
<style type="text/css">
@import url(https://fonts.googleapis.com/css?family=Raleway);
</style>
<!--<![endif]-->
两个细节值得注意:
- 双通道加载:同时输出
<link rel="stylesheet">与<style>@import</style>两种方式,提高不同邮件客户端的兼容概率; - 条件注释
<!--[if !mso]><!--> ... <!--<![endif]-->:整段字体加载代码被包裹在“非 Microsoft Office(Outlook)”的条件注释中,即 Outlook 桌面客户端不会加载这些字体(Outlook 对@font-face支持有限,通常会回退到系统字体)。这正是正文中font-family="Raleway, Arial"需要带回退字体的现实原因。
(输出逻辑详见 packages/mjml-core/src/helpers/fonts.js)
五、默认字体注册与全局 fonts 选项
除了 <mj-font> 显式注册外,MJML 渲染器还内置了一组默认字体映射。在 packages/mjml-core/src/index.js 中可以找到:
fonts = {
'Open Sans': 'https://fonts.googleapis.com/css?family=Open+Sans:300,400,500,700',
'Droid Sans': 'https://fonts.googleapis.com/css?family=Droid+Sans:300,400,500,700',
Lato: 'https://fonts.googleapis.com/css?family=Lato:300,400,500,700',
Roboto: 'https://fonts.googleapis.com/css?family=Roboto:300,400,500,700',
Ubuntu: 'https://fonts.googleapis.com/css?family=Ubuntu:300,400,500,700',
},
含义与用法:
- 这 5 个字体(Open Sans、Droid Sans、Lato、Roboto、Ubuntu)无需
<mj-font>声明即可在模板正文中直接使用,只要正文出现font-family引用,就会走 4.2 节同样的“按需注入”逻辑; - 该默认表是
mjml()渲染函数的选项级默认值,用户可以在调用mjml(mjmlString, { fonts: {...} })时整体覆盖,例如换成自定义字体服务地址或追加新字体; - 这个
fonts对象最终被写入渲染的全局数据(globalData.fonts,见 packages/mjml-core/src/index.js),并在骨架拼装阶段由 skeleton.js 的buildFontsTags(content, inlineStyle, fonts)消费——也就是说,<mj-font>注册的字体与默认字体、选项传入的字体,最终在同一个映射表里统一处理。
所以从使用角度可以这样理解:
| 字体来源 | 声明方式 | 是否需按需匹配 |
|---|---|---|
| 默认内置字体 | 无需声明,直接使用 | 是 |
| 自定义外部字体 | <mj-font name="..." href="..." /> |
是 |
| 运行时注入 | mjml(input, { fonts: {...} }) 选项 |
是 |
六、常见问题与使用建议
- 字体名大小写/拼写不一致导致加载失败:按需匹配依赖字符串比对(正则带
i标志,大小写不敏感,但拼写必须一致)。请确保<mj-font name>与正文font-family中的字体名完全相同。 - 不要忘记回退字体:由于字体加载段被包裹在
[if !mso]条件注释中,Outlook 桌面端必然回退到第二个字体名。因此font-family="Raleway, Arial"这类带兜底的字体系列是邮件内的推荐写法。 - href 必须是可直接访问的 CSS:
href指向的必须是返回 CSS 文本(含@font-face)的 URL,而不是字体文件(.woff2/.ttf)本身。 - 未使用不产生体积成本:如果声明了
<mj-font>但正文从未引用该字体,输出 HTML 中不会出现任何相关<link>或@import,不会给邮件体积带来负担。 - 自定义字体服务:如果希望使用自己的字体 CDN,只需把
href换成自托管样式表地址,或在mjml()选项的fonts中自行注册。
七、相关源码与测试入口
以下文件是理解 mj-font 完整行为链路的推荐阅读入口:
- mj-font 组件声明与 handler ——
allowedAttributes与字体注册逻辑; - 按需注入的字体标签构建器 —— 正则匹配与
<link>/@import输出; - 骨架模板中字体标签的插入位置 ——
buildFontsTags的调用点; - 默认字体表与 fonts 选项 —— 5 个内置字体及覆盖方式;
- 包的依赖与构建配置 —— 组件包与
mjml-core的版本关联。
MJML 官方组件文档(doc/body_components.md、doc/head_components.md 等)与 packages/mjml-head-font/README.md 一并构成了学习头部组件用法的资料体系,可按需查阅。