acf_register_block_type（）

2020-06-28 / 1469阅 / 悠然

如何你看完本文还不知道如何使用该函数，可以联系我定制视频教程，50元/个函数，学不会全额退款

描述

在古腾堡编辑器中注册自定义块类型。

块是古腾堡（Gutenberg）编辑器的基本元素。WordPress提供了许多默认的块类型，例如段落，标题和图像。所述acf_register_block_type（）函数可用于通过PHP添加新的块类型。

一旦注册，您的块将在编辑字段组时显示在“块”位置规则中。这使您可以将字段映射到块并定义内容。

要渲染该块，请创建一个PHP模板（或回调函数）以使用PHP函数（如get_field（）和the_field（））输出该块HTML 。

注意：块类型注册应在acf / init操作中完成。这不是必需的，但是是确保ACF完全初始化的安全方法。

块类型可以支持任意数量的内置核心功能，例如名称，图标，描述，类别等。有关支持的功能的完整列表，请参见$ settings参数。

参量

acf_register_block_type( $settings );

$设置

（数组） （必需）用于注册块类型的参数数组。也可以使用JavaScript registerBlockType（）函数中的任何参数。

name
（String）标识块的唯一名称（无名称空间）。例如“推荐”。注意：块名称只能包含小写字母数字字符和破折号，并且必须以字母开头。'name' => 'testimonial',
title
（字符串）您的块的显示标题。例如“推荐”。'title' => __('Testimonial'),
description
（字符串）（可选）这是您的块的简短描述。'description' => __('My testimonial block.'),
类别
（字符串）块分为多个类别，以帮助用户浏览和发现它们。提供的核心类别是[common | 格式| 布局| 小部件| 嵌入]。插件和主题还可以注册自定义块类别。'category' => 'embed',
icon
（String | Array）（可选）可以指定icon属性以使其更容易识别块。这些可以是任何WordPress的Dashicons或自定义svg元素。// Specifying a dashicon for the block'icon' => 'book-alt',// Specifying a custom HTML svg for the block'icon' => '<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="none" d="M0 0h24v24H0V0z" /><path d="M19 13H5v-2h14v2z" /></svg>',// Specifying colors'icon' => array( // Specifying a background color to appear with the icon e.g.: in the inserter. 'background' => '#7e70af', // Specifying a color for the icon (optional: if not set, a readable color will be automatically defined) 'foreground' => '#fff', // Specifying a dashicon for the block 'src' => 'book-alt',),
keyword
（数组）（可选）搜索项的数组，可帮助用户在搜索时发现障碍。'keywords' => array('quote', 'mention', 'cite'),
post_types
（数组）（可选），用于限制此块类型的帖子类型数组。'post_types' => array('post', 'page'),
mode
（字符串）（可选）您的块的显示模式。可用的设置是“自动”，“预览”和“编辑”。默认为“预览”。自动：默认情况下显示预览，但是在选择块时会更改为编辑表单。预览：总是显示预览。选择块时，编辑表单将显示在侧栏中。编辑：始终显示编辑表单。注意。在“预览”或“编辑”模式下，图标将出现在块工具栏中，以在模式之间切换。'mode' => 'auto',
align
（字符串）（可选）默认块对齐。可用的设置为“左”，“中”，“右”，“宽”和“满”。默认为空字符串。'align' => 'full',
render_template
（字符串）用于呈现块HTML的模板文件的路径。这可以是活动主题内文件的相对路径，也可以是任何文件的完整路径。// Specifying a relative path within the active theme'render_template' => 'template-parts/blocks/testimonial/testimonial.php',// Specifying an absolute path'render_template' => plugin_dir_path( __FILE__ ) . 'template-parts/blocks/testimonial/testimonial.php',
render_callback
（Callable）（可选）除了提供render_template外，还可以指定一个回调函数名称来输出该块的HTML。// Specifying a function'render_callback' => 'my_acf_block_render_callback',// Specifying a class method'render_callback' => array($this, 'block_render_callback'),
enqueue_style
（字符串）（可选）每当显示您的块（前端和后端）时，都要将.css文件的网址加入队列。'enqueue_style' => get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.css',
enqueue_script
（字符串）（可选）每当显示您的块（前端和后端）时，要排队的.js文件的URL。'enqueue_script' => get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.js',
enqueue_assets
（可调用）（可选）每当显示您的块（前端和后端）并使脚本和/或样式排队时运行的回调函数。// Specifying a function name'enqueue_assets' => 'my_acf_block_enqueue_assets',// Specifying a class method'enqueue_assets' => array($this, 'block_enqueue_assets'),// Specifying an anonymouse function'enqueue_assets' => function(){ wp_enqueue_style( 'block-testimonial', get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.css' ); wp_enqueue_script( 'block-testimonial', get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.js', array('jquery'), '', true );},
支撑件
（阵列）的功能，以支持（可选）的数组。可以使用JavaScript 块支持文档中的所有属性。支持以下选项：'supports' => array( /* ... */ ),
- align
  此属性添加了块控件，允许用户更改块的对齐方式。默认为true。设置为false隐藏对齐工具栏。设置为特定对齐名称的数组以自定义工具栏。// disable alignment toolbar'align' => false,// customize alignment toolbar'align' => array( 'left', 'right', 'full' ),
- 模式
  此属性允许用户通过按钮在编辑和预览模式之间切换。默认为true。// disable preview/edit toggle'mode' => false,
- 多个
  此属性允许多次添加块。默认为true。'multiple' => false,
示例
（数组）（可选）用于构造在块插入器中显示的预览的结构化数据数组。输入到“数据”属性数组中的所有值将通过$block['data']或在块渲染模板/回调中可用 get_field()。'example' => array( 'attributes' => array( 'mode' => 'preview', 'data' => array( 'testimonial' => "Your testimonial text here", 'author' => "John Smith" ) ))

（数组）已验证和已注册的块设置。

变更日志

在版本5.8.0中添加

例子

用模板注册块

本示例说明如何使用render_template设置注册块。

functions.php

add_action('acf/init', 'my_acf_blocks_init');
function my_acf_blocks_init() {

    // Check function exists.
    if( function_exists('acf_register_block_type') ) {

        // Register a testimonial block.
        acf_register_block_type(array(
            'name'              => 'testimonial',
            'title'             => __('Testimonial'),
            'description'       => __('A custom testimonial block.'),
            'render_template'   => 'template-parts/blocks/testimonial/testimonial.php',
            'category'          => 'formatting',
        ));
    }
}

template-parts / blocks / testimonial / testimonial.php

<?php

/**
 * Testimonial Block Template.
 *
 * @param   array $block The block settings and attributes.
 * @param   string $content The block inner HTML (empty).
 * @param   bool $is_preview True during AJAX preview.
 * @param   (int|string) $post_id The post ID this block is saved to.
 */

// Create id attribute allowing for custom "anchor" value.
$id = 'testimonial-' . $block['id'];
if( !empty($block['anchor']) ) {
    $id = $block['anchor'];
}

// Create class attribute allowing for custom "className" and "align" values.
$className = 'testimonial';
if( !empty($block['className']) ) {
    $className .= ' ' . $block['className'];
}
if( !empty($block['align']) ) {
    $className .= ' align' . $block['align'];
}

// Load values and assing defaults.
$text = get_field('testimonial') ?: 'Your testimonial here...';
$author = get_field('author') ?: 'Author name';
$role = get_field('role') ?: 'Author role';
$image = get_field('image') ?: 295;
$background_color = get_field('background_color');
$text_color = get_field('text_color');

?>
<div id="<?php echo esc_attr($id); ?>" class="<?php echo esc_attr($className); ?>">
    <blockquote class="testimonial-blockquote">
        <span class="testimonial-text"><?php echo $text; ?></span>
        <span class="testimonial-author"><?php echo $author; ?></span>
        <span class="testimonial-role"><?php echo $role; ?></span>
    </blockquote>
    <div class="testimonial-image">
        <?php echo wp_get_attachment_image( $image, 'full' ); ?>
    </div>
    <style type="text/css">
        #<?php echo $id; ?> {
            background: <?php echo $background_color; ?>;
            color: <?php echo $text_color; ?>;
        }
    </style>
</div>

用回调注册一个块

本示例说明如何使用render_callback设置注册块。

functions.php

<?php
add_action('acf/init', 'my_register_blocks');
function my_register_blocks() {

    // check function exists.
    if( function_exists('acf_register_block_type') ) {

        // register a testimonial block.
        acf_register_block_type(array(
            'name'              => 'testimonial',
            'title'             => __('Testimonial'),
            'description'       => __('A custom testimonial block.'),
            'render_callback'   => 'my_acf_block_render_callback',
            'category'          => 'formatting',
        ));
    }
}

/**
 * Testimonial Block Callback Function.
 *
 * @param   array $block The block settings and attributes.
 * @param   string $content The block inner HTML (empty).
 * @param   bool $is_preview True during AJAX preview.
 * @param   (int|string) $post_id The post ID this block is saved to.
 */
function my_acf_block_render_callback( $block, $content = '', $is_preview = false, $post_id = 0 ) {

    // Create id attribute allowing for custom "anchor" value.
    $id = 'testimonial-' . $block['id'];
    if( !empty($block['anchor']) ) {
        $id = $block['anchor'];
    }

    // Create class attribute allowing for custom "className" and "align" values.
    $className = 'testimonial';
    if( !empty($block['className']) ) {
        $className .= ' ' . $block['className'];
    }
    if( !empty($block['align']) ) {
        $className .= ' align' . $block['align'];
    }

    // Load values and assing defaults.
    $text = get_field('testimonial') ?: 'Your testimonial here...';
    $author = get_field('author') ?: 'Author name';
    $role = get_field('role') ?: 'Author role';
    $image = get_field('image') ?: 295;
    $background_color = get_field('background_color');
    $text_color = get_field('text_color');

    ?>
    <div id="<?php echo esc_attr($id); ?>" class="<?php echo esc_attr($className); ?>">
        <blockquote class="testimonial-blockquote">
            <span class="testimonial-text"><?php echo $text; ?></span>
            <span class="testimonial-author"><?php echo $author; ?></span>
            <span class="testimonial-role"><?php echo $role; ?></span>
        </blockquote>
        <div class="testimonial-image">
            <?php echo wp_get_attachment_image( $image, 'full' ); ?>
        </div>
        <style type="text/css">
            #<?php echo $id; ?> {
                background: <?php echo $background_color; ?>;
                color: <?php echo $text_color; ?>;
            }
        </style>
    </div>
    <?php
}

添加块样式?

为了确保在编辑器和前端中都正确设置了样式，我们建议使用enqueue_style或enqueue_assets设置，如下所示：

functions.php

acf_register_block_type(array(
    'name'              => 'testimonial',
    'title'             => __('Testimonial'),
    'description'       => __('A custom testimonial block.'),
    'render_template'   => get_template_directory() . '/template-parts/blocks/testimonial/testimonial.php',
    'enqueue_style'     => get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.css',
));

testimonial.php

<blockquote class="testimonial">
    ...
</blockquote>

证明书

.testimonial {
    background: #00e4ba;
    color: #fff;
}

注意：如果创建个人样式表不是您的最佳选择，请查看WordPress提供的enqueue_block_assets和enqueue_block_editor_assets操作，以使您的样式入队。

添加块脚本

与样式类似，我们建议使用enqueue_script或enqueue_assets设置为您的块正确地加入JavaScript。

为了使JavaScript在编辑器和前端都能按预期运行，在编辑帖子时了解块的生命周期非常重要。

根据是否显示块预览以及是否进行了更改，您的块在单个页面加载期间可能会多次渲染。在这种情况下，术语“渲染”表示已通过对您的PHP模板或回调函数的AJAX调用来更新/替换了该块的HTML。

每次渲染块时，都会丢弃先前的HTML，并显示新的HTML。结果，对先前DOM元素的任何JavaScript修改也将丢失。

要解决此问题，只需挂接到我们的JS操作“ render_block_preview / type = {$ type}”，然后应用您的JavaScript功能，就像重新绘制了该块一样。

此示例演示了如何使脚本入队，同时提供与块的前端和后端状态的兼容性。

functions.php

acf_register_block_type(array(
    'name'              => 'testimonial',
    'title'             => __('Testimonial'),
    'description'       => __('A custom testimonial block.'),
    'render_template'   => get_template_directory() . '/template-parts/blocks/testimonial/testimonial.php',
    'enqueue_script'    => get_template_directory_uri() . '/template-parts/blocks/testimonial/testimonial.js',
));

testimonial.php

<blockquote class="testimonial">
    <img src="..." />
    ...
</blockquote>

testimonial.js

(function($){

    /**
     * initializeBlock
     *
     * Adds custom JavaScript to the block HTML.
     *
     * @date    15/4/19
     * @since   1.0.0
     *
     * @param   object $block The block jQuery element.
     * @param   object attributes The block attributes (only available when editing).
     * @return  void
     */
    var initializeBlock = function( $block ) {
        $block.find('img').doSomething();
    }

    // Initialize each block on page load (front end).
    $(document).ready(function(){
        $('.testimonial').each(function(){
            initializeBlock( $(this) );
        });
    });

    // Initialize dynamic block preview (editor).
    if( window.acf ) {
        window.acf.addAction( 'render_block_preview/type=testimonial', initializeBlock );
    }

})(jQuery);

添加块预览?

块预览提供了一种优雅的解决方案，用于识别和区分插入器面板中显示的各种块类型。

要增加对块预览的支持，请使用“ example”设置来定义WordPress用于构建预览的属性数组，如以下示例所示。

functions.php

acf_register_block_type(array(
    'name'              => 'testimonial',
    'title'             => __('Testimonial'),
    'description'       => __('A custom testimonial block.'),
    'example'           => array(
        'attributes' => array(
            'mode' => 'preview',
            'data' => array(
                'testimonial'   => "Blocks are...",
                'author'        => "Jane Smith",
                'role'          => "Person",
                'is_preview'    => true
            )
        )
    )
));

在“数据”属性数组中定义的所有值将通过$block['data']或在块渲染模板/回调中可用get_field()。

在上面的示例中，定义了三个与三个现有自定义字段（“个人鉴定”，“作者”和“角色”）名称匹配的值。定义了一个附加的非自定义字段值（'is_preview'），该值可在渲染器中用于显示替代标记。

?由于预览旨在传达视觉设计，我们建议您使用“预览” 模式，但是，也可以将其设置为“编辑”，这将显示连接到该块的自定义字段。

添加内部块?‍?‍?

术语“内部块”是指启用嵌套内容（块内的块）的功能。这个简短的视频演示了如何使用内部块仅使用基本PHP来创建日期限制的块。

要增加对内部块的支持，请<InnerBlocks />在渲染模板/回调中使用Component定义可编辑区域。编辑内容时，此特殊元素将显示为本机“块插入区域”，查看内容时，将显示为已保存的“内部块内容”。请注意，<InnerBlocks />每个块只能使用一个组件。

为了使<innerBlocks />Component在基于React的块编辑器中运行，必须首先将块HTML解析为JSX。通过添加对该__experimental_jsx属性的支持，可以轻松完成此操作。

下面的示例演示如何创建前面提到的“受限制的”内容块。

functions.php

add_action('acf/init', 'my_acf_init_blocks');
function my_acf_init_blocks() {

    // Check function exists.
    if( function_exists('acf_register_block_type') ) {

        // Register a restricted block.
        acf_register_block_type(array(
            'name'              => 'restricted',
            'title'             => 'Restricted',
            'description'       => 'A restricted content block.',
            'category'          => 'formatting',
            'mode'              => 'preview',
            'supports'          => array(
                'align' => true,
                'mode' => false,
                '__experimental_jsx' => true
            ),
            'render_template' => 'template-parts/blocks/restricted/restricted.php',
        ));
    }
}

template-parts / blocks / restricted / restricted.php

<?php
/**
 * Restricted Block Template.
 *
 * @param   array $block The block settings and attributes.
 * @param   string $content The block inner HTML (empty).
 * @param   bool $is_preview True during AJAX preview.
 * @param   (int|string) $post_id The post ID this block is saved to.
 */

// Create class attribute allowing for custom "className" and "align" values.
$classes = '';
if( !empty($block['className']) ) {
    $classes .= sprintf( ' %s', $block['className'] );
}
if( !empty($block['align']) ) {
    $classes .= sprintf( ' align%s', $block['align'] );
}

// Load custom field values.
$start_date = get_field('start_date');
$end_date = get_field('end_date');

// Restrict block output (front-end only).
if( !$is_preview ) {
    $now = time();
    if( $start_date && strtotime($start_date) > $now ) {
        echo sprintf( '<p>Content restricted until %s. Please check back later.</p>', $start_date );
        return;
    }
    if( $end_date && strtotime($end_date) < $now ) {
        echo sprintf( '<p>Content expired on %s.</p>', $end_date );
        return;
    }
}

// Define notification message shown when editing.
if( $start_date && $end_date ) {
    $notification = sprintf( 'Content visible from %s until %s.', $start_date, $end_date );
} elseif( $start_date ) {
    $notification = sprintf( 'Content visible from %s.', $start_date );
} elseif( $end_date ) {
    $notification = sprintf( 'Content visible until %s.', $end_date );
} else {
    $notification = 'Content unrestricted.';
}
?>
<div class="restricted-block <?php echo esc_attr($classes); ?>">
    <span class="restricted-block-notification"><?php echo esc_html( $notification ); ?></span>
    <InnerBlocks  />
</div>

该<InnerBlocks />组件还可以与作为记录中的以下属性定制InnerBlocks部件指南。

allowedBlocks
（Array）一个块名称数组，限制了可以插入的内容类型。$allowed_blocks = array( 'core/image', 'core/paragraph' );echo '<innerBlocks allowedBlocks="' . esc_attr( wp_json_encode( $allowed_blocks ) ) . '" />';
template
（数组）（模板）CPT块模板指南中记录的块内容的结构化数组。可以结合使用名为templateLock的附加属性来锁定模板内容。$template = array( array( 'core/paragraph', array( 'placeholder' => 'Add a root-level paragraph', ) ), array( 'core/columns', array(), array( array( 'core/column', array(), array( array( 'core/image', array() ), ) ), array( 'core/column', array(), array( array( 'core/paragraph', array( 'placeholder' => 'Add a inner paragraph' ) ), ) ), ) ));echo '<innerBlocks template="' . esc_attr( wp_json_encode( $template ) ) . '" templateLock="all" />';
templateLock
（字符串）锁定模板内容。可用设置为“全部”或“插入”。有关更多信息，请参见InnerBlocks组件。

大家谈论

我的见解

ACF插件函数

acf_register_block_type（）

如何你看完本文还不知道如何使用该函数，可以联系我定制视频教程，50元/个函数，学不会全额退款

描述

参量

$设置

返回

变更日志

例子

用模板注册块

functions.php

template-parts / blocks / testimonial / testimonial.php

用回调注册一个块

functions.php

添加块样式?

functions.php

testimonial.php

证明书

添加块脚本

functions.php

testimonial.php

testimonial.js

添加块预览?

functions.php

添加内部块?‍?‍?

functions.php

template-parts / blocks / restricted / restricted.php