README

Retcon是一个小巧的Craft CMS插件，添加了一系列强大的Twig过滤器，用于修改HTML内容。以下是Retcon可以执行的一些操作：

使用CSS选择器（例如 'img'、'div.foobar'、'p:first-child' 等）添加属性（例如 class="foobar"、style="color:red;" 或 data-foo）
向现有属性追加值
完全删除属性（例如删除所有内联 style 属性）
转换内联图像（如果已安装，甚至使用 Imager）
向内联图像添加 srcset 或懒加载（如果已安装，再次使用 Imager）
删除或解包DOM节点
包裹DOM节点（例如，将所有  标签包裹在  中）
提取DOM节点（例如，删除除 <img> 标签之外的所有内容）
注入字符串或HTML内容
更改标签名称（例如，将所有  的出现更改为 ，或将 div.foobar 更改为 p.foobar）

...等等！

需求

此插件需要Craft CMS 5.0+

它是如何工作的？

Retcon使用PHP的本地 DOMDocument 类来解析和修改HTML。此外，使用 Masterminds的HTML5库以支持HTML5，并使用Symfony的 DomCrawler 和 CssSelector 组件来启用强大的类似jQuery的选择器语法。

基本用法

Retcon公开了一系列不同的方法来修改HTML。大多数方法接受一个 selector 参数（即您想要修改的元素的选择器，例如 'img'、'p' 或 'div.foobar'），并且一些方法接受额外的参数以进行进一步配置。

请注意，无论您的HTML来自WYSIWYG字段（Redactor或CK Editor）还是普通的字符串，都没有关系。如果是HTML，Retcon就会处理它。

Twig过滤器

Retcon的所有方法都作为Twig过滤器公开，这是Retcon主要设计的方式。例如，如果您想向名为 body 的Redactor字段中的所有图像添加类名 'image'，那么看起来是这样的

{{ entry.body | retconAttr('img', { class: 'image' }) }}

请注意，对于Twig过滤器，将 retcon 前缀添加到方法名中——即 attr 方法变为 retconAttr 过滤器，transform 方法变为 retconTransform 过滤器等。

过滤器标签对

对于HTML不在字段或变量中的用例，应用标签对 语法工作得很好——以下示例向所有具有 target="_blank" 的 <a> 标签添加 rel="noopener noreferrer"

{% apply retconAttr('a[target="_blank"]:not([rel])', { rel: 'noopener noreferrer' }) %}
    {# A whole bunch of HTML in here #}
    ....
{% endapply %}

捕获所有过滤器

由于是Twig过滤器，因此当然可以链接多个Retcon方法

{{ entry.body | retconChange('h1,h2,h4,h5,h6', 'h3') | retconAttr('h3', { class: 'heading') }}

另一种选择是使用“捕获所有”过滤器 retcon，它接受一个包含您想要按顺序运行的函数名称及其参数的单一数组

{{ entry.body | retcon([
    ['change', 'h1,h2,h4,h5,h6', 'h3'],
    ['attr', 'h3', { class: 'heading' }]
]) }}

PHP

如果您想在Craft插件或模块中使用Retcon，所有方法都可通过mmikkel/retcon/Retcon::getInstance()->retcon服务使用（注意：与Twig过滤器不同，服务方法名称中没有retcon前缀 - 换句话说，retconAttr就是attr()）

use mmikkel\retcon\Retcon;
echo Retcon::getInstance()->retcon->attr($entry->body, ['class' => 'image']);

实际用例示例；以下是如何在模块中使用rel="noopener noreferrer"示例（基本上，以下代码会自动将rel="noopener noreferrer"添加到模板中的所有所有<a target="_blank">标签中，当然除非它们已经设置了rel属性）

use mmikkel\retcon;

public function init() {

    Event::on(
        View::class,
        View::EVENT_AFTER_RENDER_TEMPLATE,
        function (TemplateEvent $event) {
            if (!Craft::$app->getRequest()->getIsSiteRequest()) {
                return;
            }

            if ($event->output && Craft::$app->getPlugins()->getPlugin('retcon')) {
                $event->output =
                    Retcon::getInstance()->retcon->attr(
                        $event->output,
                        'a[target="_blank"]:not([rel])', [
                            'rel' => 'noopener noreferrer',
                        ]);
            }

        }
    );
}

选择器

在Retcon中，“选择器”与CSS中的选择器相同；即类似'img'、'.foo'或h3 + p这样的东西。

Retcon的选择器支持与CSS几乎完全相同，但并非所有选择器都适用。有关更多信息，请参阅CssSelector文档。

多个选择器

多个选择器可以定义为逗号分隔的字符串（例如'p, span'）或数组（例如['p', 'span']）。

仅选择顶级节点

新功能（仅限Retcon 3.1.0+）:

如果您需要将选择限制为仅顶级节点，可以使用'body'元素选择器与子组合器（'>'）一起使用。例如

{# Make all top level <p> tags red #}
{% apply retconAttr('body > p', { style: 'color: red;' }) %} 
    <p>I wanna be red</p>
    <div>
        <p>I wanna be left alone</p>
    </div>
{% endapply %}

结果

<p style="color: red;">I wanna be red</p>
<div>
    <p>I wanna be left alone</p>
</div>

对于所有过滤器，都支持body元素选择器。

方法

transform 对所有图像应用命名或内联图像转换。如果已安装，Retcon将使用Imager应用转换。新功能：Retcon还支持Imager的继任者，Imager X。

srcset 对所有图像应用一组命名或内联图像转换，以支持简单的srcset。如果已安装，Retcon将使用Imager应用转换。

lazy 将图像标签的src属性替换为透明的、基于64的SVG（保留原始图像的宽高比）；将原始src URL放在data属性中

dimensions 如果缺少width和height属性，则向图像节点添加这些属性（并且图像节点中的src属性引用的是本地图像文件）。新功能：

autoAlt 为缺少alt标签的图像添加资产标题或文件名作为替代文本

attr 添加、替换、追加或删除一组属性和属性值 - 例如class。 可用于删除内联样式。

renameAttr 对匹配选择器的现有属性进行重命名，保留属性值

wrap 将一些内容包裹在其他内容中（例如，将所有标签包裹在标签中）

unwrap 删除匹配元素的父母节点；保留其内容

remove 删除所有匹配给定选择器（s）的元素

removeEmpty 删除所有空元素。新增功能

only 删除除匹配给定选择器的元素之外的所有元素

change 更改匹配给定选择器的所有元素标签类型。也可以用来完全删除标签，但保留其内容。

inject 注入字符串或HTML

免责声明与支持

Retcon免费提供。作者不对数据丢失或使用此插件引起的任何其他问题负责。请参阅Wiki页面以获取文档和示例。并在此处报告任何错误、功能请求或其他问题。由于Retcon是一个业余项目，不保证响应时间、功能实现或错误修正。

mmikkel / retcon

维护者

详细信息