nadar/quill-delta-parser

一个PHP库,用于将Quill WYSIWYG编辑器的deltas解析为HTML - 具有灵活性和可扩展性,适用于自定义元素。

资助包维护!
nadar

3.4.2 2024-04-05 14:44 UTC

README

一个PHP库,用于将Quill WYSIWYG编辑器的deltas解析为HTML - 具有灵活性和可扩展性,适用于自定义元素。每个元素都通过相同的机制解析,使得扩展和理解变得容易。它还清理输出值,使其更加安全,尤其是在使用用户生成文本时。

Tests Maintainability Test Coverage Latest Stable Version Total Downloads License

什么是Quill?Quill是一个免费的、开源的WYSIWYG编辑器,专为现代网络构建。凭借其模块化架构和表达式的API,它可以完全自定义以适应任何需求。

安装

该包仅通过Composer提供

composer require nadar/quill-delta-parser

用法

// Ensure to load the autoload file from Composer somewhere in your application.
require __DIR__ . '/vendor/autoload.php';

// Create the lexer object with your given Quill JSON delta code (either PHP array or JSON string).
$lexer = new \nadar\quill\Lexer($json);

// Echo the HTML for the given JSON ops.
echo $lexer->render();

其中$json是从Quill的ops JSON数组,例如

{
  "ops": [
    {
      "insert": "Hello"
    },
    {
      "attributes": {
        "header": 1
      },
      "insert": "\n"
    },
    {
      "insert": "\nThis is the PHP Quill "
    },
    {
      "attributes": {
        "bold": true
      },
      "insert": "parser"
    },
    {
      "insert": "!\n"
    }
  ]
}

这将渲染以下HTML

<h1>Hello</h1>
<p><br></p>
<p>This is the PHP Quill <strong>parser</strong>!</p>

扩展解析器

为了通过添加自己的监听器扩展解析器(如果使用的是生成自定义delta代码的Quill插件,则可能是这种情况),必须决定它是一个

  • 内联元素:用新解析的内容替换内容,通常在与Quill扩展一起工作时。
  • 块元素:用标签包围整个输入,例如标题。

例如,一个提及插件生成的以下delta {"insert":{"mention":{"id":"1","value":"Basil","denotationChar":"@"}}};一个内联插件可能看起来像这样

class Mention extends InlineListener
{
    /**
     * {@inheritDoc}
     */
    public function process(Line $line)
    {
        // Check if input is JSON, decodes to an array, and checks if the key "mention" 
        // exists. If yes, return the value for this key.
        $mention = $line->insertJsonKey('mention');
        if ($mention) {
            // Apply the inline behavior, updates the content and append to the next "block" element.
            // The value in this example would be "<strong>Basil</strong>".
            $this->updateInput($line, '<strong>'.$mention['value'].'</strong>');
        }
    }
}

现在注册监听器

$lexer = new Lexer($json);
$lexer->registerListener(new Mention());
echo $lexer->render();

覆盖内置监听器

某些监听器(图像、视频、颜色)产生的HTML输出可能不适合您的用例,因此您可以选择覆盖这些插件的属性并重新注册监听器。以下是一个使用图像标签的示例

$image = new Image();


$image->wrapper = '<img src="{src}" class="my-image" />';

// Override the default listener behavior for image color:
$lexer = new Lexer($json);
$lexer->registerListener($image);
echo $lexer->render();

如果您想用您自己的图像类替换一个类,请使用overwriteListener以完全自定义类的方式达到相同的结果。原因是监听器是通过其类名注册的。

$mySuperClass = new class() extends Image {
  // Here is the custom class code ...
};

$lexer->overwriteListener(new Image(), $mySuperClass);

或者,当然,如果您有用于类的单独文件

class MySuperDuperImageClass extends Image
{
    // Here is the custom class code ...
}

$lexer->overwriteListener(new Image(), new MySuperDuperImageClass());

调试

有时,理解如何处理和解析delta可能会在调试时具有挑战性。因此,您可以使用调试器类,它将打印一个包含有关数据如何解析的信息的表格。

$lexer = new Lexer($json);
$lexer->render(); // Make sure to run the render before calling debugPrint().
 
$debug = new Debug($lexer);
echo $debug->debugPrint();

还有一个内置的Docker Compose文件,它提供了对output.php文件的访问。该output.php文件有助于在显示渲染内容的同时直接使用Quill编辑器编写内容,包括所有调试信息。要在Git仓库克隆的根目录中运行此Docker web服务器,请执行以下命令

docker-compose up

并在浏览器中访问http://localhost:5555/

致谢