定制器设置转区块模式 - 主题开发手册

前提条件：对定制器、主题修改、安全和区块模式有中级知识。

场景示例

经典主题有一个自定义选项，可以在网站页眉中显示一个动作调用。
动作调用被限制在一个位置，由主题开发者选择。用户只能打开或关闭它，不能重新定位或多次使用它。 用户只能定制一个文本输入，而且颜色选择有限。

原始的定制器选项有以下设置：

显示或隐藏动作调用（切换）
动作调用文本（文本输入字段）
动作调用链接（url / 文本输入字段）
文本调色板（WP_Customize_Color_Control）
背景调色板（WP_Customize_Color_Control）

该主题还必须处理净化定制器选项，并为选项添加一个定制器面板或板块。不包括安全措施，代码大约是100行。

我们的目标是将定制器选项转换为一个区块模式。通过将动作调用转换为区块模式，用户可以：

把不同内容放在他们想要的任何地方
改变排版、间距、边框（如果主题有启用这些设置）
使用更多的颜色选项
将自定义图片或其他内容放入区块内

第1步：在区块编辑器中重新创建动作调用

在编辑器中使用区块重新创建动作调用的目的是为了获得一份HTML的副本，即区块标记，你将在模式中使用。你可以使用组、行或按钮块，这取决于你的偏好。

添加现有的实用类

一旦你有了一份标记副本，为了使这些区块与现有的动作调用相匹配，重新添加原始组件中的任何实用的CSS类。
你将在区块注释中加入"className":"call-to-action__large"，并在元素的class属性中加入call-to-action__large。

第2步：注册区块模式

注册区块模式使用register_block_pattern()，这个函数从WordPress 5.5开始可用。如果主题的最低要求的WordPress版本低于5.5，需要在使用该函数之前检查它是否存在。
需要在init钩子上注册

<?php
if ( function_exists( 'register_block_pattern' ) ) {
    function myfirsttheme_register_block_pattern() {
        register_block_pattern(
            'myfirsttheme/call-to-action',
            array(
                'title'       => esc_html__( 'Call to action', 'myfirsttheme' ),
                'categories'  => array( 'featured' ),
                'content'     =>'
                    <!-- wp:group {"style":{"border":{"width":"4px","style":"solid","radius":"8px"},"color":{"background":"#8550cc"}},"borderColor":"tertiary","layout":{"inherit":true},"className":"call-to-action__large"} -->
                    <div class="wp-block-group call-to-action__large has-border-color has-tertiary-border-color has-background" style="background-color:#8550cc;border-radius:8px;border-style:solid;border-width:4px"><!-- wp:paragraph {"align":"center","style":{"color":{"text":"#fefefe"},"elements":{"link":{"color":{"text":"#fefefe"}}}},"fontSize":"large"} -->
<p class="has-text-align-center has-text-color has-link-color has-large-font-size" style="color:#fefefe">Call to Action</p>
                    <!-- /wp:paragraph --></div>
                    <!-- /wp:group -->
                ',
            )
        );
    }
    add_action( 'init', 'myfirsttheme_register_block_pattern', 9 );
}
?>

第3步：将定制器的选项值添加到区块模式中

首先，我们来添加文本内容和链接。原始定制器选项的名称是：myfirsttheme_action_link和myfirsttheme_action_text。

如果主题已经有一个返回链接和文本的函数，该函数可以在模式内重复使用。如果没有，你需要创建一个新的PHP函数，检查是否使用了theme mod，转义内容，并返回它。

<?php
function myfirsttheme_action_text() {
    $action_text = '';
    if ( get_theme_mod( 'myfirsttheme_action_link' ) ) {
        $action_text .= '<a href="' . esc_url( get_theme_mod( 'myfirsttheme_action_link' ) ) . '">';
    }
    $action_text .= wp_kses_post( get_theme_mod( 'myfirsttheme_action_text' ) );
    if ( get_theme_mod( 'myfirsttheme_action_link' ) ) {
        $action_text .= '</a>';
    }

    return $action_text;
}
?>

用函数替换段落块内的段落文本：

<p class="has-text-align-center has-text-color has-link-color has-large-font-size" style="color:#fefefe">Call to Action</p>

变成：

<p class="has-text-align-center has-text-color has-link-color has-large-font-size" style="color:#fefefe">' . myfirsttheme_action_text() . '</p>

'content'     =>'
    <!-- wp:group {"style":{"border":{"width":"4px","style":"solid","radius":"8px"},"color":{"background":"#8550cc"}},"borderColor":"tertiary","layout":{"inherit":true},"className":"call-to-action__large"} -->
    <div class="wp-block-group call-to-action__large has-border-color has-tertiary-border-color has-background" style="background-color:#8550cc;border-radius:8px;border-style:solid;border-width:4px"><!-- wp:paragraph {"align":"center","style":{"color":{"text":"#fefefe"},"elements":{"link":{"color":{"text":"#fefefe"}}}},"fontSize":"large"} -->
    <p class="has-text-align-center has-text-color has-link-color has-large-font-size" style="color:#fefefe">' . myfirsttheme_action_text() . '</p><!-- /wp:paragraph --></div>
    <!-- /wp:group -->
',

接下来，你需要从文本和背景颜色选项中获取颜色代码。

颜色theme mod的名称是：myfirsttheme_action_text_color和myfirsttheme_action_bgcolor。

用esc_attr()转义theme mod，并将动作调用的默认颜色作为回退：

esc_attr( get_theme_mod( 'myfirsttheme_action_text_color', '#000' ) )

"background":"' . esc_attr( get_theme_mod( 'myfirsttheme_action_bgcolor', '#fff' ) ) . '"

记住，每种颜色都需要在区块注释和HTML标签的样式属性中被替换：

'content'     =>'
    <!-- wp:group {"style":{"border":{"width":"4px","style":"solid","radius":"8px"},"color":{"background":"' . esc_attr( get_theme_mod( 'myfirsttheme_action_bgcolor', '#fff' ) ) . '"}},"borderColor":"tertiary","layout":{"inherit":true},"className":"call-to-action__large"} -->
<div class="wp-block-group call-to-action__large has-border-color has-tertiary-border-color has-background" style="background-color:' . esc_attr( get_theme_mod( 'myfirsttheme_action_bgcolor', '#fff' ) ). ';border-radius:8px;border-style:solid;border-width:4px"><!-- wp:paragraph {"align":"center","style":{"color":{"text":"' . esc_attr( get_theme_mod( 'myfirsttheme_action_text_color', '#000' ) ) . '"},"elements":{"link":{"color":{"text":"' . esc_attr( get_theme_mod( 'myfirsttheme_action_text_color', '#000' ) ). '"}}}},"fontSize":"large"} -->
<p class="has-text-align-center has-text-color has-link-color has-large-font-size" style="color:' . esc_attr( get_theme_mod( 'myfirsttheme_action_text_color', '#000' ) ). '">' . myfirsttheme_action_text() . '</p><!-- /wp:paragraph -->
</div>
<!-- /wp:group -->
',

第4步：显示区块模式

如果你要将主题页眉区转换为可编辑的模板片段，你可以在模板片段加入模式区块：

<!-- wp:pattern {"slug":"myfirsttheme/call-to-action"} /-->

如果你保留了PHP页眉模板，如果你愿意，你可以用do_blocks()渲染区块模式。

echo do_blocks( '<!-- wp:pattern {"slug":"myfirsttheme/call-to-action"} /-->' );

在这之后，你可以从你的主题中删除定制器的选项。用户的原始值仍然保存在数据库中。用户可以在编辑器中定制区块。