如何利用`WP_Widget`和`WP_Customize_Control`构建现代化的主题小工具，并使其兼容区块编辑器？

构建现代化主题小工具：WP_Widget 与 WP_Customize_Control 的融合与区块编辑器兼容

大家好，今天我们来深入探讨如何利用 WP_Widget 和 WP_Customize_Control 构建现代化主题小工具，并确保它们与 WordPress 的区块编辑器（Gutenberg）无缝兼容。 这不仅仅是简单的代码堆砌，而是要理解 WordPress 的架构，结合现代前端技术，才能打造出既强大又易于使用的工具。

1. 传统小工具的局限性与现代化的需求

在过去，WP_Widget 是构建 WordPress 小工具的主要方式。 它提供了一个相对简单的 API 来创建可以在 WordPress 后台的小工具区域拖放的组件。 然而，传统的 WP_Widget 有几个明显的局限性：

• 界面陈旧： 小工具的配置界面通常基于基本的 HTML 表单元素，样式和交互性都比较有限。
• 实时预览缺失： 用户需要在后台保存小工具设置后才能在前台看到效果，体验不够直观。
• 与区块编辑器不兼容： 区块编辑器使用 JavaScript 和 React 构建，与传统的 PHP 渲染的小工具存在技术栈上的差异。

为了解决这些问题，我们需要对小工具的构建方式进行现代化改造，使其更符合现代 Web 开发的趋势，并与区块编辑器良好集成。 这就涉及到了 WP_Customize_Control 和一些前端技术的应用。

2. WP_Customize_Control 的优势与应用

WP_Customize_Control 是 WordPress Customizer API 的一部分。 它可以让我们创建自定义的控件，用于在 Customizer 界面中配置主题和其他设置。 相比传统的 WP_Widget 配置界面，WP_Customize_Control 具有以下优势：

• 实时预览： Customizer 支持实时预览，用户在修改设置时可以立即看到效果。
• 更丰富的控件类型： Customizer 提供了多种内置的控件类型，如颜色选择器、图像上传器、文本编辑器等，也可以自定义控件。
• 更好的用户体验： Customizer 的界面更现代化，交互性更强。

我们可以利用 WP_Customize_Control 来增强小工具的配置界面，提供更好的用户体验。 但需要注意的是，WP_Customize_Control 主要用于 Customizer 界面，并不能直接替代 WP_Widget 在小工具区域的作用。 因此，我们需要将两者结合起来。

3. WP_Widget 与 WP_Customize_Control 的融合：一个步骤指南

将 WP_Widget 和 WP_Customize_Control 融合的关键在于，将小工具的配置界面从传统的 WP_Widget::form() 方法迁移到 Customizer 中，然后在小工具的 WP_Widget::widget() 方法中使用 Customizer 中存储的设置来渲染小工具的内容。

以下是一个逐步的指南，展示如何实现这种融合：

步骤 1: 创建一个自定义的 WP_Widget 类

<?php
/**
 * 自定义的小工具类
 */
class My_Modern_Widget extends WP_Widget {

    /**
     * 构造函数
     */
    public function __construct() {
        parent::__construct(
            'my_modern_widget', // 小工具 ID
            '我的现代化小工具', // 小工具名称
            array( 'description' => '一个使用 Customizer 配置的现代化小工具' ) // 小工具描述
        );

        // 注册小工具的 CSS 和 JavaScript 文件
        add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_scripts' ) );
        add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_scripts' ) );
    }

    /**
     * 注册 CSS 和 JavaScript 文件
     */
    public function enqueue_scripts( $hook ) {
        if ( 'widgets.php' !== $hook && ! is_customize_preview() ) {
            return;
        }

        wp_enqueue_style( 'my-modern-widget-style', plugin_dir_url( __FILE__ ) . 'css/my-modern-widget.css' );
        wp_enqueue_script( 'my-modern-widget-script', plugin_dir_url( __FILE__ ) . 'js/my-modern-widget.js', array( 'jquery', 'customize-preview' ), false, true );

        wp_localize_script( 'my-modern-widget-script', 'myModernWidget', array(
            'ajax_url' => admin_url( 'admin-ajax.php' ),
        ));
    }

    /**
     * 小工具的前台显示
     */
    public function widget( $args, $instance ) {
        $title = apply_filters( 'widget_title', $instance['title'] );
        $text = $instance['text'];

        echo $args['before_widget'];
        if ( ! empty( $title ) ) {
            echo $args['before_title'] . $title . $args['after_title'];
        }

        echo '<div class="my-modern-widget-content">';
        echo '<p>' . esc_html( $text ) . '</p>';
        echo '</div>';

        echo $args['after_widget'];
    }

    /**
     * 小工具的后台表单（不再使用，配置在 Customizer 中）
     */
    public function form( $instance ) {
        // 移除默认表单
        echo '<p>此小工具的配置位于主题自定义器中。</p>';
    }

    /**
     * 更新小工具设置（不再直接使用，通过 Customizer API 更新）
     */
    public function update( $new_instance, $old_instance ) {
        $instance = array();
        $instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';
        $instance['text'] = ( ! empty( $new_instance['text'] ) ) ? sanitize_textarea_field( $new_instance['text'] ) : '';
        return $instance;
    }
}

// 注册小工具
function register_my_modern_widget() {
    register_widget( 'My_Modern_Widget' );
}
add_action( 'widgets_init', 'register_my_modern_widget' );

步骤 2: 创建一个自定义的 WP_Customize_Control 类 (可选)

如果 WordPress 提供的标准控件类型不能满足需求，你可以创建自定义的 WP_Customize_Control 类。 例如，创建一个带颜色选择器的文本区域：

<?php
/**
 * 自定义颜色文本区域控件
 */
class My_Customize_Color_Textarea_Control extends WP_Customize_Control {
    public $type = 'color_textarea';

    public function render_content() {
        ?>
        <label>
            <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
            <span class="description customize-control-description"><?php echo esc_html( $this->description ); ?></span>
            <input type="color" value="<?php echo esc_attr( $this->value() ); ?>" class="my-color-picker" data-customize-setting-link="<?php echo $this->id; ?>" />
            <textarea rows="5" style="width:100%;" data-customize-setting-link="<?php echo $this->id; ?>_text"><?php echo esc_textarea( $this->value( '_text' ) ); ?></textarea>
        </label>
        <?php
    }
}

这个例子展示了一个简单的颜色选择器和文本区域组合的自定义控件。 render_content() 方法负责渲染控件的 HTML。

步骤 3: 将小工具设置添加到 Customizer

<?php
/**
 * 将小工具设置添加到 Customizer
 */
function my_modern_widget_customize_register( $wp_customize ) {

    // 添加一个 section
    $wp_customize->add_section( 'my_modern_widget_section', array(
        'title' => '我的现代化小工具设置',
        'description' => '配置我的现代化小工具的设置',
        'priority' => 160,
    ) );

    // 添加标题设置
    $wp_customize->add_setting( 'my_modern_widget_title', array(
        'default' => '默认标题',
        'sanitize_callback' => 'sanitize_text_field',
    ) );

    $wp_customize->add_control( 'my_modern_widget_title', array(
        'label' => '标题',
        'section' => 'my_modern_widget_section',
        'type' => 'text',
    ) );

    // 添加文本设置
    $wp_customize->add_setting( 'my_modern_widget_text', array(
        'default' => '默认文本',
        'sanitize_callback' => 'sanitize_textarea_field',
    ) );

    $wp_customize->add_control( 'my_modern_widget_text', array(
        'label' => '文本内容',
        'section' => 'my_modern_widget_section',
        'type' => 'textarea',
    ) );

    // 添加自定义控件 (如果使用了自定义控件)
    /*
    $wp_customize->add_setting( 'my_modern_widget_color_text', array(
        'default' => '#ffffff',
        'sanitize_callback' => 'sanitize_hex_color',
    ) );

    $wp_customize->add_control( new My_Customize_Color_Textarea_Control( $wp_customize, 'my_modern_widget_color_text', array(
        'label' => '颜色和文本',
        'section' => 'my_modern_widget_section',
        'settings' => 'my_modern_widget_color_text',
    ) ) );
    */
}
add_action( 'customize_register', 'my_modern_widget_customize_register' );

这段代码将小工具的标题和文本设置添加到 Customizer 中。 add_section() 创建一个新的 section，add_setting() 注册一个设置，add_control() 将设置与一个控件关联起来。

步骤 4: 在小工具的 widget() 方法中使用 Customizer 设置

<?php
    /**
     * 小工具的前台显示
     */
    public function widget( $args, $instance ) {
        $title = get_theme_mod( 'my_modern_widget_title', '默认标题' ); // 从 Customizer 获取标题
        $text = get_theme_mod( 'my_modern_widget_text', '默认文本' ); // 从 Customizer 获取文本

        echo $args['before_widget'];
        if ( ! empty( $title ) ) {
            echo $args['before_title'] . $title . $args['after_title'];
        }

        echo '<div class="my-modern-widget-content">';
        echo '<p>' . esc_html( $text ) . '</p>';
        echo '</div>';

        echo $args['after_widget'];
    }

在 widget() 方法中，我们使用 get_theme_mod() 函数从 Customizer 中获取设置的值。 get_theme_mod() 函数的第二个参数是默认值，如果 Customizer 中没有设置该值，则使用默认值。

步骤 5: 实现 Customizer 的实时预览 (JavaScript)

为了让 Customizer 的实时预览生效，我们需要使用 JavaScript 来监听 Customizer 中设置的变化，并更新小工具的显示。

(function( $ ) {
    wp.customize( 'my_modern_widget_title', function( value ) {
        value.bind( function( newval ) {
            $( '.widget.my_modern_widget .widget-title' ).html( newval );
        } );
    } );

    wp.customize( 'my_modern_widget_text', function( value ) {
        value.bind( function( newval ) {
            $( '.widget.my_modern_widget .my-modern-widget-content p' ).html( newval );
        } );
    } );
})( jQuery );

这段 JavaScript 代码监听了 my_modern_widget_title 和 my_modern_widget_text 设置的变化，并使用 jQuery 更新了小工具的标题和文本内容。

步骤 6: CSS 样式美化

添加适当的 CSS 样式，使小工具看起来更美观。 例如，在 my-modern-widget.css 文件中添加以下样式：

.my-modern-widget-content {
    padding: 10px;
    border: 1px solid #ccc;
    margin-top: 10px;
}

.my-modern-widget-content p {
    margin: 0;
    font-size: 16px;
    line-height: 1.5;
}

/* 自定义控件样式 */
.my-color-picker {
    margin-bottom: 5px;
}

4. 与区块编辑器兼容：创建一个区块

为了使小工具与区块编辑器兼容，我们需要创建一个对应的区块。 这意味着我们需要使用 JavaScript 和 React 来构建一个可以在区块编辑器中使用的组件。

步骤 1: 注册一个自定义区块

// my-modern-widget-block.js

wp.blocks.registerBlockType( 'my-plugin/my-modern-widget-block', {
    title: '我的现代化小工具',
    icon: 'info',
    category: 'widgets',
    attributes: {
        title: {
            type: 'string',
            default: '默认标题',
        },
        text: {
            type: 'string',
            default: '默认文本',
        },
    },
    edit: function( props ) {
        const { attributes, setAttributes } = props;

        return React.createElement(
            'div',
            { className: props.className },
            React.createElement(
                'h3',
                null,
                '我的现代化小工具'
            ),
            React.createElement(
                'label',
                { htmlFor: 'my-modern-widget-title' },
                '标题:'
            ),
            React.createElement(
                'input',
                {
                    type: 'text',
                    id: 'my-modern-widget-title',
                    value: attributes.title,
                    onChange: ( event ) => setAttributes( { title: event.target.value } ),
                }
            ),
            React.createElement(
                'label',
                { htmlFor: 'my-modern-widget-text' },
                '文本:'
            ),
            React.createElement(
                'textarea',
                {
                    id: 'my-modern-widget-text',
                    value: attributes.text,
                    onChange: ( event ) => setAttributes( { text: event.target.value } ),
                }
            )
        );
    },
    save: function( props ) {
        return React.createElement(
            'div',
            { className: props.className },
            React.createElement(
                'h3',
                null,
                props.attributes.title
            ),
            React.createElement(
                'p',
                null,
                props.attributes.text
            )
        );
    },
} );

这个 JavaScript 代码注册了一个名为 my-plugin/my-modern-widget-block 的区块。 edit 函数定义了区块在编辑器中的显示和交互，save 函数定义了区块在前台的显示。

步骤 2: 注册区块 (PHP)

<?php
/**
 * 注册自定义区块
 */
function my_modern_widget_register_block() {
    wp_register_script(
        'my-modern-widget-block',
        plugin_dir_url( __FILE__ ) . 'js/my-modern-widget-block.js',
        array( 'wp-blocks', 'wp-element', 'wp-editor' )
    );

    register_block_type( 'my-plugin/my-modern-widget-block', array(
        'editor_script' => 'my-modern-widget-block',
    ) );
}
add_action( 'init', 'my_modern_widget_register_block' );

这段 PHP 代码注册了 my-modern-widget-block.js 脚本，并将其与 my-plugin/my-modern-widget-block 区块关联起来。

步骤 3: 将区块的数据同步到 Customizer (可选)

如果希望区块的数据与 Customizer 中的设置同步，可以使用 update_option 或 update_theme_mod 函数来更新 Customizer 中的设置。 例如，可以在区块的 save 函数中使用 AJAX 请求来更新 Customizer 中的设置。

步骤 4: 在主题中渲染区块的数据 (PHP)

为了在前台显示区块的数据，可以使用 the_content 过滤器来拦截文章内容，并渲染区块的数据。

<?php
/**
 * 渲染区块的数据
 */
function my_modern_widget_render_block( $content ) {
    global $post;

    if ( is_singular() && has_blocks( $post->post_content ) ) {
        $blocks = parse_blocks( $post->post_content );

        foreach ( $blocks as $block ) {
            if ( $block['blockName'] === 'my-plugin/my-modern-widget-block' ) {
                $title = isset( $block['attrs']['title'] ) ? $block['attrs']['title'] : '默认标题';
                $text = isset( $block['attrs']['text'] ) ? $block['attrs']['text'] : '默认文本';

                $widget_content = '<div class="my-modern-widget-content">';
                $widget_content .= '<h3>' . esc_html( $title ) . '</h3>';
                $widget_content .= '<p>' . esc_html( $text ) . '</p>';
                $widget_content .= '</div>';

                $content = str_replace( $block['innerHTML'], $widget_content, $content );
            }
        }
    }

    return $content;
}
add_filter( 'the_content', 'my_modern_widget_render_block' );

这段 PHP 代码拦截了文章内容，并查找 my-plugin/my-modern-widget-block 区块。 如果找到该区块，则从区块的属性中获取标题和文本，并将其渲染为 HTML。

5. 最佳实践与注意事项

• 代码组织： 将代码组织成不同的文件，例如 widget.php, customize.php, block.js, style.css，以提高代码的可读性和可维护性。
• 数据验证和转义： 对用户输入的数据进行验证和转义，以防止安全漏洞。 使用 sanitize_text_field(), sanitize_textarea_field(), esc_html(), esc_attr() 等函数来处理数据。
• 性能优化： 避免在小工具的 widget() 方法中执行耗时的操作。 尽可能使用缓存来提高性能。
• 可访问性： 确保小工具和区块是可访问的，符合 WCAG 标准。 使用 ARIA 属性来增强可访问性。
• 测试： 对小工具和区块进行充分的测试，以确保其在不同的浏览器和设备上都能正常工作。
• 版本控制： 使用版本控制系统（例如 Git）来管理代码。

6. 示例代码结构

以下是一个示例代码结构，展示如何组织小工具和区块的代码：

my-modern-widget/
├── my-modern-widget.php       (主插件文件)
├── widget.php                (WP_Widget 类)
├── customize.php           (Customizer 设置)
├── js/
│   ├── my-modern-widget.js     (小工具 JavaScript)
│   ├── my-modern-widget-block.js (区块 JavaScript)
├── css/
│   └── my-modern-widget.css    (小工具 CSS)

7. 表格总结：WP_Widget vs. WP_Customize_Control vs. 区块

特性	WP_Widget	WP_Customize_Control	区块
主要用途	在小工具区域显示内容	在 Customizer 中配置主题设置	在区块编辑器中编辑和显示内容
配置界面	WP_Widget::form() 方法生成的 HTML 表单	自定义的控件 (例如文本框、颜色选择器)	JavaScript 和 React 构建的组件
实时预览	不支持	支持	编辑器内预览，可配置实时预览
技术栈	PHP	PHP 和 JavaScript	JavaScript 和 React
兼容性	传统小工具区域	Customizer	区块编辑器
灵活性	有限	较高	非常高
与区块编辑器集成	需要额外的工作	需要额外的工作，通常用于同步设置	原生支持

8. 总结

通过将 WP_Widget 和 WP_Customize_Control 结合起来，我们可以创建具有现代化配置界面和实时预览的小工具。 为了与区块编辑器兼容，我们需要创建一个对应的区块，并将其数据与 Customizer 中的设置同步。 掌握这些技术，就能构建出更强大、更易于使用的 WordPress 小工具。