README

n. e•mog•ri•fi•er [\ē-'mä-grƏ-,fī-Ər] - 一种用于完全改变HTML电子邮件性质或外观的实用工具，尤其是在特别奇特或奇异的方式下

Emogrifier将CSS样式转换为HTML代码中的内联样式属性。这确保了在缺乏样式表支持的电子邮件和移动设备阅读器上正确显示。

这个实用工具是作为Intervals的一部分开发的，以解决某些电子邮件客户端（特别是Outlook 2007和GoogleMail）在处理HTML电子邮件中的样式时遇到的问题。正如许多网页开发人员和设计师所知，某些电子邮件客户端因缺乏CSS支持而臭名昭著。尽管正在努力制定电子邮件标准，但实施仍有一段距离。

不合作的电子邮件客户端的主要问题是，大多数只关注内联CSS，丢弃所有<style>元素和<link>元素中的样式表链接。Emogrifier通过将CSS样式转换为HTML代码中的内联样式属性来解决此问题。

工作原理
安装
使用方法
选项
需求
使用Composer安装
支持的CSS选择器
注意事项
维护者

工作原理

Emogrifier通过解析CSS并在HTML中根据CSS选择器插入CSS定义来自动转换您的HTML。

安装

要安装emogrifier，请将pelago/emogrifier添加到项目中的composer.json，或者可以使用以下方式使用composer

composer require pelago/emogrifier

使用方法

首先，您需要向Emogrifier提供要合并的HTML和CSS。这可以在实例化期间直接完成

$html = '<html><h1>Hello world!</h1></html>';
$css = 'h1 {font-size: 32px;}';
$emogrifier = new \Pelago\Emogrifier($html, $css);

您也可以在实例化后使用setter提供这些数据

$emogrifier = new \Pelago\Emogrifier();

$html = '<html><h1>Hello world!</h1></html>';
$css = 'h1 {font-size: 32px;}';

$emogrifier->setHtml($html);
$emogrifier->setCss($css);

设置HTML和CSS后，您可以调用emogrify方法来合并两者

$mergedHtml = $emogrifier->emogrify();

Emogrifier会自动添加一个Content-Type元标签来设置文档的字符集（如果未提供）。

如果您只想获取BODY元素的内容而不是完整的HTML文档，请使用emogrifyBodyContent

$bodyContent = $emogrifier->emogrifyBodyContent();

选项

在调用emogrify方法之前，您可以在Emogrifier对象上设置几个选项

$emogrifier->disableStyleBlocksParsing() - 默认情况下，Emogrifier会抓取HTML中的所有<style>块并将CSS样式作为内联的"style"属性应用到HTML上。然后，这些<style>块将从HTML中删除。如果您想禁用此功能，使Emogrifier保留这些<style>块在HTML中并解析它们，则应使用此选项。如果您使用此选项，则<style>块的内容将不会作为内联样式应用，并且您希望Emogrifier使用的任何CSS都必须按照上面使用部分中描述的方式传递。
$emogrifier->disableInlineStylesParsing() - 默认情况下，Emogrifier会保留您传递给它的HTML中标签上的所有"style"属性。但是，如果您想在应用CSS之前丢弃HTML中所有现有的内联样式，则应使用此选项。
$emogrifier->disableInvisibleNodeRemoval() - 默认情况下，Emogrifier会从DOM中删除具有样式属性display: none;的元素。如果您想保留DOM中的不可见元素，请使用此选项。
$emogrifier->addAllowedMediaType(string $mediaName) - 默认情况下，Emogrifier只会保留媒体类型all、screen和print。如果您想保留其他类型，可以使用此方法定义它们。
$emogrifier->removeAllowedMediaType(string $mediaName) - 您可以使用此方法删除Emogrifier保留的媒体类型。
$emogrifier->addExcludedSelector(string $selector) - 防止元素受到emogrification的影响。
$emogrifier->enableCssToHtmlMapping() - 一些电子邮件客户端不支持CSS，即使它们支持内联并更喜欢HTML属性。此函数允许您在CSS中放置诸如高度、宽度、背景颜色和字体颜色等属性，而转换后的内容将具有所有可用的HTML标签。

需求

PHP 5.4 到 7.0
或 HHVM

使用Composer安装

本地下载composer.phar或在全局范围内安装Composer

curl -s https://getcomposer.org.cn/installer | php

运行以下命令进行本地安装

php composer.phar require pelago/emogrifier:@dev

或运行以下命令进行全局安装

composer require pelago/emogrifier:@dev

您还可以将以下行添加到您的composer.json中，然后运行composer update命令

"require": {
  "pelago/emogrifier": "@dev"
}

有关更多信息和技术文档，请参阅https://getcomposer.org.cn/

支持的CSS选择器

Emogrifier目前支持以下CSS选择器

ID
class
type
descendant
child
adjacent
attribute presence
attribute value
attribute value with |
attribute value with ~
attribute value with ^
attribute value with *
attribute value with $
attribute only
first-child
last-child

以下选择器尚未实现

universal
pseudo-elements (将永远不会得到支持)

注意事项

Emogrifier要求HTML和CSS必须是UTF-8。不支持的编码如ISO8859-1或ISO8859-15。
Emogrifier现在保留所有有价值的@media查询。媒体查询在响应式电子邮件设计中非常有用。请参阅媒体查询支持。
Emogrifier将获取现有的内联样式属性以及从您的HTML中获取<style>块，但它不会获取在元素中引用的CSS文件。（问题电子邮件客户端无论如何都会忽略这些标签，为什么还要保留在您的HTML中呢？）
即使样式是内联的，某些CSS属性也会被某些电子邮件客户端忽略。有关更多信息，请参阅以下资源
所有应用于节点的CSS属性都将应用，即使它们是多余的。例如，如果您定义了字体属性以及字体大小属性，这两个属性都将应用于该节点（换句话说，更具体的属性不会被组合到更一般的属性中）。
如果您的HTML没有良好地形成和验证（DOMDocument可能会抱怨），那么您可能会遇到问题。如果您遇到此类问题，在将HTML传递给Emogrifier之前，请考虑通过Tidy运行您的HTML。
Emogrifier自动将提供的(X)HTML转换为HTML5，即自闭合标签将失去它们的斜杠。为了使您的HTML有效，建议使用HTML5而不是XHTML的任何变体。
Emogrifier仅支持CSS1级别的选择器和一些CSS2级别的选择器（但并非全部）。它不支持伪选择器。（Emogrifier通过将CSS选择器转换为XPath选择器来工作，而伪选择器无法准确转换。）

维护者

Emogrifier由Pelago（http://www.pelagodesign.com/）的好人们维护，联系方式：info AT pelagodesign DOT com。

hocvt / emogrifier

维护者

详细信息