README

Bard Mutator

此Statamic插件允许您修改Bard字段类型渲染的标签，让您完全控制最终的HTML。您可以为标签添加、删除和修改属性，包装标签和内容，或完全重命名和替换标签。

安装

使用Composer安装插件

composer require jacksleight/bard-mutator

示例

首先让我们通过一些示例来看看这个插件能做什么！

为所有项目符号列表添加类

use JackSleight\BardMutator\Facades\Mutator;

Mutator::tag('bullet_list', function ($tag) {
    $tag[0]['attrs']['class'] = 'list';
    return $tag;
});

为所有外部链接添加noopener

use JackSleight\BardMutator\Facades\Mutator;
use Statamic\Facades\URL;

Mutator::tag('link', function ($tag) {
    if (URL::isExternal($tag[0]['attrs']['href'])) {
        $tag[0]['attrs']['rel'] = 'noopener';
    }
    return $tag;
});

为所有二级标题添加自动生成的ID

use JackSleight\BardMutator\Facades\Mutator;

Mutator::tag('heading', function ($tag, $data) {
    if ($data->attrs->level === 2) {
        $tag[0]['attrs']['id'] = str_slug(collect($data->content)->implode('text', ''));
    }
    return $tag;
});

为所有表格添加包装div

use JackSleight\BardMutator\Facades\Mutator;

Mutator::tag('table', function ($tag) {
    array_unshift($tag, [
        'tag' => 'div',
        'attrs' => ['class' => 'table-wrapper'],
    ]);
    return $tag;
});

为所有列表项内容添加包装span

use JackSleight\BardMutator\Facades\Mutator;

Mutator::tag('list_item', function ($tag) {
    array_push($tag, 'span');
    return $tag;
});

将所有图像转换为自定义元素

use JackSleight\BardMutator\Facades\Mutator;

Mutator::tag('image', function ($tag) {
    $tag[0]['tag'] = 'fancy-image';
    return $tag;
});

创建Mutators

您应在服务提供者的boot()方法中添加mutators。它们将接收两个参数

• tag (数组): 标准的标签值
• data (对象): 原始节点或标记数据

您应返回一个标签值。

您可以为同一节点或标记添加多个mutators，它们将按添加的顺序执行。

它是如何工作的

渲染过程

以下是ProseMirror（Bard的内容格式和渲染背后的魔法）如何处理渲染过程的大致情况

1. 原始内容以ProseMirror文档的形式存储在您的条目中，这些文档由节点和标记组成
2. ProseMirror将原始节点和标记数据转换为它们的标准标签值
3. Bard Mutator在这里介入，允许您修改标签值
4. ProseMirror将标签值渲染为HTML字符串

标签值

完全展开的标签值看起来像这样

[
    [
        'tag' => 'a',
        'attrs' => [
            'href' => 'http://...'
        ]
    ]
]

完全展开的标签值是项的数组，其中每个项都是包含两个键的关联数组

• tag (字符串): 标签的名称
• attrs (数组): 属性的名/值数组

包含多个元素的数组将渲染嵌套标签，内容放置在内层（最后）标签中。

如果没有属性，则项目可以是标签名

[
    ['p']
]

如果只有一个没有属性的元素，整个标签值可以是标签名

'p'

内置的节点和标记类返回这些格式的混合体，但为了简便和一致性，Bard Mutator在传递给您的mutators之前将它们规范化为完全展开的格式。您可以返回任何您喜欢的格式。

重要：单关联数组的标签值不支持

// Don't do this, it won't work! Wrap it in another array.
return [
    'tag' => 'a',
    'attrs' => [
        'href' => 'http://...'
    ]
];

可用节点与标记

Bard Mutator将用支持变更的扩展版本替换所有内置节点和标记类，除了Statamic的Set节点。这些是

• 节点
  • blockquote
  • bullet_list
  • code_block
  • hard_break
  • heading
  • horizontal_rule
  • image
  • list_item
  • ordered_list
  • paragraph
  • table
  • table_cell
  • table_header
  • table_row
• 标记
  • bold
  • code
  • italic
  • link
  • subscript
  • underline
  • strike
  • superscript

🚨 其他插件与潜在不兼容性

由于ProseMirror的工作方式，Bard Mutator必须用其自己的替换所有内置节点和标记类。而且只有当没有其他插件（或用户代码）尝试做同样的事情时，它才能可靠地做到这一点。

实际上，我开发这个插件的主要原因是让多个插件能够修改内置节点和标记，而无需争夺同一组类。

我的其他Bard插件（Bard Paragraph Style）完全与之兼容。如果安装了Bard Mutator，它将使用底层的那个而不是它自己的节点类。

然而，如果您有其他插件（或用户代码）替换了任何内置节点或标记类，Bard Mutator可能无法正常工作。不幸的是，我认为我无法解决这个问题。

这不会影响自定义节点和标记。