Foundation for Emails Ruby Gem 实战指南:在 Rails 中用 Inky 模板与 CSS Inliner 生成响应式 HTML 邮件

原创2026-09-27 15:06:071,998 阅读
文章标签:前端

Foundation for Emails Ruby Gem 实战指南:在 Rails 中用 Inky 模板与 CSS Inliner 生成响应式 HTML 邮件

本指南基于仓库 docs/pages/gem-guide.md 展开,系统讲解 Foundation for Emails 的 Ruby 生态:inky-rb 如何把简洁的自定义 HTML 标签编译成邮件必备的 table 布局,premailer-rails / roadie 如何自动内联样式,以及只需样式资产、不想要模板语言的场景下如何改用 foundation_emails。读完你可以在 Rails 项目中完成从 Gemfile 配置、生成器初始化、.inky 模板重命名到 Asset Pipeline 样式导入的完整接入,并了解背后 Rails Engine 的实现细节。

工作原理:从简单标签到邮件级表格

HTML 邮件几乎完全依赖 <table> 嵌套布局才能在各客户端(包括 Outlook)中稳定渲染。直接用表格手写邮件意味着大量重复、冗长、易错的结构代码。Inky 正是为解决这一问题而生的模板语言:它让你写 <row>、<columns> 这类语义化标签,再由编译器转换为复杂但合规的 table 结构。

inky-rb 是 Inky 模板语言的纯 Ruby 实现——它不依赖 Node/Gulp 工具链,直接内嵌于 Rails 应用。其工作流程如下图所示:

inky-rb 工作原理:Inky 自定义标签经编译转换为 table 布局,再由 CSS inliner 将样式内联进邮件 HTML

整体流程可以拆解为两步:

  1. Inky 编译:解析邮件模板中的 <row>、<column> 等自定义标签,将其展开为邮件所需的复杂 table 结构。这些自定义标签最终不会出现在收件人的收件箱里,因为它们在发送前已被翻译成标准的表格式 HTML。
  2. CSS 内联:使用 premailer-rails 或 roadie 等 CSS inliner 解析邮件模板,定位模板引用的样式表,遍历其中所有选择器,把匹配的样式逐一内联到文档对应元素上。这样一来,你无需在标记中手动嵌入 style 属性,模板依然保持精简。

两种能力组合的结果是:以传统方式手写邮件所需代码量的零头,产出同样精美、同样响应式的 HTML 邮件——模板保持可读,样式集中管理,渲染结果则由工具链保证兼容性。

快速上手:在 Rails 应用中接入 inky-rb

在 Rails 应用中安装 inky-rb 只需几个简单步骤。

1. 在 Gemfile 中声明依赖

打开应用的 Gemfile,添加以下两行:

gem 'inky-rb', require: 'inky'
# Stylesheet inlining for email
gem 'premailer-rails'

说明:

  • inky-rb 默认不会自动被 require,因此需要显式指定 require: 'inky',这样 Inky 模板渲染能力才会被加载进应用。
  • premailer-rails 负责第二步的样式内联;如果你更偏好 roadie,也可以用 gem 'roadie-rails' 替代,两者都是文档认可的 CSS inliner 方案。

2. 安装依赖

执行:

bundle install

3. 运行安装生成器

运行以下命令初始化所需的样式与 mailer 布局:

rails g inky:install

如果你想自定义生成的 mailer 布局文件名,可以像这样传入参数:

rails g inky:install some_name

(即生成器会把 some_name 作为邮件布局的名字。)

4. 重命名邮件模板为 .inky 扩展名

把你的邮件模板扩展名改为 .inky。注意:.inky 模板内部依然可以使用 ERB,所以原有的动态内容逻辑完全不受影响:

welcome.html      => welcome.html.inky
pw_reset.html.erb => pw_reset.html.inky

完成以上四步,你就可以直接在 Rails 应用里用 Inky 标签编写响应式邮件了——<container>、<row>、<columns> 这些标签会被自动编译为兼容各客户端的表格 HTML。

只想要样式资产:使用 foundation_emails 独立 Gem

如果你的需求仅仅是在 Asset Pipeline 里引入 Foundation for Emails 的样式,而不使用 Inky 模板语言,请使用 foundation_emails gem(对应仓库的 gem 目录)。这正好呼应 gem-guide 的「Standalone Assets」一节。

安装与导入

参考 gem/README.md:

# Gemfile
gem 'foundation_emails'

执行 bundle install 后,在邮件样式表(如 app/assets/stylesheets/your_emails_stylesheet.scss)中导入:

@import "foundation-emails";

背后的实现:一个极简的 Rails Engine

从源码看,foundation_emails 是一个典型的「资源型」gem:

  • gem/lib/foundation_emails.rb 是入口,依次 require 版本号与引擎:
    require "foundation_emails/version"
    require "foundation_emails/engine"
    
  • gem/lib/foundation_emails/engine.rb 定义了一个继承 ::Rails::Engine 的空引擎类:
    require "rails"
    
    module FoundationEmails
      class Engine < ::Rails::Engine
      end
    end
    
    这个空引擎的作用是让 Rails 自动把 gem 内的资产目录(vendor/assets 等)挂载进 Asset Pipeline,从而使 @import "foundation-emails" 在应用中直接可用。
  • gem/foundation-emails.gemspec 中可以看到打包规则:spec.files 除常规文件外,还通过 Dir.glob("vendor/assets/stylesheets/foundation-emails/**/*.*") 显式包含样式资产,spec.require_paths = ["lib"] 指定加载路径。
  • 当前仓库中 gem 的版本号定义在 gem/lib/foundation_emails/version.rb,值为 2.4.0.0。
  • 仓库还提供了最小化的 RSpec 测试 gem/spec/foundation/emails_spec.rb,验证 FoundationEmails::VERSION 存在;配合 gem/spec/spec_helper.rb 与 gem/Rakefile(task :default => :spec),可通过 bundle exec rake 运行测试。

两条路线如何选择

场景 推荐方案 依赖 是否使用 Inky 标签
想用 <row>、<columns> 等模板标签写邮件 inky-rb + premailer-rails Ruby 实现 Inky 编译 + CSS 内联 是
只想引入现成样式、手写 table 或混合编写 foundation_emails 纯样式资产,经 Rails Engine 注入 Asset Pipeline 否

两条路线都绕开了「手动把样式写进每个元素」的痛点:前者通过 inliner 自动内联,后者则直接使用框架自带的、已在各大邮件客户端测试过的样式体系。

配套知识:Inky 支持哪些标签

虽然 gem-guide 的重点是 Rails 集成,但理解 Inky 标签体系能帮你更快上手模板编写。仓库的 docs/pages/inky.md 列出了当前支持的标签:

  • 网格:<container>、<row>、<columns>
  • 按钮:<button>
  • 提示框:<callout>
  • 菜单:<menu>、<item>

例如一个最基础的模板骨架:

<container>
  <row>
    <columns>Put content in me!</columns>
  </row>
</container>

这些标签在发送前都会被转换为合法的表格 HTML,不会真正出现在收件人的邮箱中。注意 Inky 是可选的——你完全可以用纯 table 编写邮件,或在同一封邮件中混用 table 与 Inky 标签(详见 docs/pages/inky.md 的 FAQ 部分)。

常见问题与注意事项

  • .inky 模板里还能用 ERB 吗? 可以。文档明确说明 .inky 扩展名不影响 ERB 的使用,pw_reset.html.erb 重命名为 pw_reset.html.inky 后动态内容照常渲染。
  • 生成器布局名如何定制? rails g inky:install 默认生成 mailer 布局,追加一个参数(如 some_name)即可自定义布局文件名。
  • inliner 与模板的关系? inliner 会解析模板中引用的样式表、遍历选择器并匹配文档元素,所以模板里应正确引用外部样式表,而不是把样式写死在标签内。
  • 适用前提:以上配置均以当前仓库文档描述为准,适用于使用 Rails Asset Pipeline 与 Sass(@import)的项目;若你的构建链完全不同(如纯 Gulp 前端流程),则对应的是 Inky 的 Node 实现而非本文所述的 Ruby Gem 方案。

小结

Foundation for Emails 的 Ruby 生态给出了两把钥匙:inky-rb 让你用声明式标签写邮件并自动编译成表格 HTML,配合 premailer-rails 等 inliner 免去手动内联样式;foundation_emails 则只把经过各客户端验证的样式资产接入 Asset Pipeline。从 Gemfile 一行声明到 rails g inky:install、再到 .inky 模板重命名,接入成本极低,而源码中那个精简的 Rails::Engine 正是「资产即插即用」这一体验的实现基石。

登录后查看全文
foundation-emails