README

开发者使用高级自定义字段 PRO 功能注册 Gutenberg 块的优雅方式。

• 安装
• 定义块
• 注册块
• 配置字段
• 检索数据
• 定义类
• 渲染块

安装

您可以通过 composer 安装此包

composer require starring-jane/acf-gutenberg-blocks

定义块

您可以通过创建扩展此包提供的基类的基础块类的类来定义自定义块

通过扩展基类，您可以轻松地以最少的配置定义自定义块

use StarringJane\GutenbergBlocks\Block;

class MyCustomBlock extends Block
{
    protected $name = "custom";

    protected $title = "My Custom block";

    protected $description = "This is a custom block!";

    protected $category = 'custom';
    
    public function render()
    {
        // Render the HTML
    }
}

基块类默认在后台配置了一些事情，以便方便地使用，但可以轻松更改。以下属性是默认定义的

protected $name;

protected $title;

protected $description;

protected $keywords = [];

protected $category;

protected $icon;

protected $mode = 'preview';

protected $default_align = '';

protected $align = ['wide', 'full'];

protected $allow_mode_switch = true;

protected $allow_multiple = true;

protected $parent = [];

protected $inner_blocks = false;

protected $wrap = true;

注册块

要启用自定义块，您需要通过挂钩到 acf/init 过滤器来注册它们。这允许灵活地定义哪些块应该被启用。

您可以通过传递包含类的数组来启用块

add_filter('acf/init', function () {
    \StarringJane\GutenbergBlocks\Gutenberg::register([
        MyCustomBlock::class,
    ]);
});

要自动注册目录中的所有块，可以提供当前主题中的相对路径

add_filter('acf/init', function () {
    // Registers all blocks in `wp-content/themes/{current_theme}/blocks`
    \StarringJane\GutenbergBlocks\Gutenberg::register('blocks');
});

定义父块

您可以通过在您的块类上更新 $parent 属性来定义一个块具有父块。这将导致块在 Gutenberg 的块列表中隐藏，但仅作为父块的“子块”可用。

class ChildBlock extends Block
{
    // ...

    protected $parent = [
        ParentBlock::class,
    ];
}

为了使子块在父块中可选，您需要在父块上设置 $inner_blocks = true。

配置字段

可以通过在类上定义一个 fields() 方法并将它返回一个要添加的字段数组来向自定义块添加字段。

此包包含 wordplate/extended-acf，以简单优雅的方式定义块的字段。请确保阅读文档以查看哪些字段类型可用。

以下是如何使用此包定义字段的示例

public function fields()
{
    return [
        Text::make('Title')
            ->required(),

        Text::make('Body'),

        Url::make('Link', 'url')
            ->required()
            ->instructions('The url that should be displayed.'),
    ];
}

检索数据

从定义的字段检索数据有几种选择。

// Retrieve all fields as an array
$data = $this->data();

// Retrieve only the title
$title = $this->get('title');

// Retrieve the body and provide a default value as fallback
$body = $this->get('body', 'Hello world!');

// ...

定义类

默认情况下，添加了一些类到包装器 HTML 元素中，以便添加通用样式和特定于块的样式，并尊重 Gutenberg 编辑器的对齐和其他输入。

您可以使用 getClasses() 简单地获取 CSS 类。
要覆盖或扩展添加的类，请定义自己的 setClasses()

// Override the default classes
protected function setClasses($block)
{
    return [
        'my-custom-css-class',
        //
    ]);
}

// Extend the default classes
protected function setClasses($block)
{
    return array_merge(parent::setClasses($block), [
        'my-custom-css-class',
    ]);
}

请注意，当覆盖默认类时，一些 Gutenberg 行为将不再工作，并必须从 $block 参数添加以防止这种情况发生！

渲染块

所有块都需要实现 render() 方法。您渲染块的方式由您自己决定，以下给出了使用 WordPress 的 get_template_part() 的示例。

public function render()
{
    // Make the data available in our template
    set_query_var('data', $this->data());

    return get_template_part('path-to-my-block-template');
}

另一个不错的选择是使用我们的 Wordpress Blade package。这将启用许多用于处理自定义块视图的有用功能。要使用 blade 进行渲染，您只需包含提供的 trait 即可。

use StarringJane\GutenbergBlocks\Block;
use StarringJane\WordpressBlade\RendersBlade;

class MyCustomBlock extends Block
{
    use RendersBlade;

    // ...

    public function render()
    {
        return $this->view('blade.custom-block', [
            'data' => $this->data(),
        ]);
    }
}

包装元素

默认情况下，每个块在渲染时都包装在一个带有默认类的 <div> 中。您可以在注册块之前通过调用 Gutenberg::withoutWrapping() 全局禁用此功能。

当禁用包装时，您想在您的模板中添加默认 CSS 类，可以像这样添加它们

public function render()
{
    // Make the CSS-classes available as a variable in the template
    set_query_var('default_classes', $this->getClasses());

    return get_template_part('path-to-my-block-template');
}

许可证

MIT 许可协议 © Starring Jane