使用Webpack打包文件，实现WordPress定制器实时设置修改

我最近在用Webpack打包主题文件，想要给WordPress定制器加上实时修改设置的功能，已经写好了一个承载定制器功能的类，先把这个类的代码放出来：

<?php
/**
 * 定制器专属功能。
 *
 * @since 1.0.0
 * @package mytheme
 */
namespace MyTheme\Customizer;
use MyTheme\Helpers as Helpers;
/**
 * 定制器类
 */
class Customizer {
    /**
     * 全局主题名称
     *
     * @var string
     *
     * @since 1.0.0
     */
    protected $theme_name;

    // 这里应该还有构造函数和注册定制器设置的方法，比如 customize_register 钩子的回调
}

接下来我就一步步实现实时预览的功能，分PHP配置、Webpack打包、JS监听三个部分：

一、完善定制器类，注册预览脚本 #

首先要在Customizer类里添加注册预览脚本的方法，并且绑定到WordPress的customize_preview_init钩子上，这个钩子专门用来加载定制器预览页面的脚本：

/**
 * 定制器类
 */
class Customizer {
    /**
     * 全局主题名称
     *
     * @var string
     *
     * @since 1.0.0
     */
    protected $theme_name;

    /**
     * 构造函数，绑定钩子
     */
    public function __construct() {
        $this->theme_name = wp_get_theme()->get( 'Name' );
        // 绑定定制器注册钩子（你原来的代码应该已经有这个）
        add_action( 'customize_register', [ $this, 'register_customizer_settings' ] );
        // 绑定预览脚本加载钩子
        add_action( 'customize_preview_init', [ $this, 'enqueue_preview_scripts' ] );
    }

    /**
     * 注册定制器实时预览脚本
     *
     * @since 1.0.0
     */
    public function enqueue_preview_scripts() {
        // 加载Webpack打包后的预览脚本，路径根据你的实际输出目录调整
        wp_enqueue_script(
            'mytheme-customizer-preview',
            get_theme_file_uri( 'assets/js/customizer-preview.js' ),
            [ 'customize-preview' ], // 依赖WordPress核心的定制器预览脚本
            wp_get_theme()->get( 'Version' ),
            true // 在页脚加载
        );
    }

    /**
     * 注册定制器设置的方法（示例）
     */
    public function register_customizer_settings( $wp_customize ) {
        // 示例：注册一个标题颜色设置
        $wp_customize->add_setting(
            'mytheme_site_title_color',
            [
                'default'           => '#2d2d2d',
                'sanitize_callback' => 'sanitize_hex_color',
                'transport'         => 'postMessage', // 关键！开启实时预览，不用刷新页面
            ]
        );

        $wp_customize->add_control(
            new \WP_Customize_Color_Control(
                $wp_customize,
                'mytheme_site_title_color',
                [
                    'label'    => __( '站点标题颜色', 'mytheme' ),
                    'section'  => 'title_tagline', // 放到默认的标题标语面板
                    'settings' => 'mytheme_site_title_color',
                ]
            )
        );
    }
}

这里要注意必须给设置加上transport: 'postMessage'，不然默认是refresh模式，修改设置后会刷新页面，达不到实时预览的效果。

二、配置Webpack，打包预览脚本 #

接下来调整Webpack的配置，把预览脚本作为单独的入口文件，这样可以单独打包，也能复用你现有的Webpack配置（比如Babel、压缩等）：

// webpack.config.js
const path = require('path');

module.exports = {
  entry: {
    // 你的其他主题脚本，比如主脚本
    main: './src/js/main.js',
    // 定制器预览脚本入口
    'customizer-preview': './src/js/customizer-preview.js',
  },
  output: {
    // 输出到主题的assets/js目录下
    path: path.resolve(__dirname, 'assets/js'),
    filename: '[name].js',
  },
  // 你的其他Webpack配置，比如Babel加载器、CSS处理等
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: 'babel-loader',
      },
    ],
  },
};

配置好之后，运行Webpack打包命令（比如npm run build），就能在assets/js目录下得到customizer-preview.js文件了。

三、编写实时预览的JS逻辑 #

最后在src/js/customizer-preview.js里编写监听设置变化的逻辑，当定制器里的设置修改时，实时更新页面上的元素：

// 监听站点标题颜色的变化
wp.customize('mytheme_site_title_color', function(value) {
  value.bind(function(newColor) {
    // 找到站点标题的DOM元素，修改颜色
    const siteTitle = document.querySelector('.site-title a');
    if (siteTitle) {
      siteTitle.style.color = newColor;
    }
  });
});

// 可以添加更多设置的监听，比如背景色
wp.customize('mytheme_header_background', function(value) {
  value.bind(function(newBgColor) {
    const header = document.querySelector('.site-header');
    if (header) {
      header.style.backgroundColor = newBgColor;
    }
  });
});

这里的wp.customize是WordPress提供的全局方法，用来获取对应的设置对象，然后通过bind方法监听值的变化，一旦值改变就执行回调函数修改DOM样式。

这样配置完成后，打开WordPress定制器，修改站点标题颜色的时候，页面上的标题颜色就会实时跟着变化，完全不用刷新页面！

内容的提问来源于stack exchange，提问作者dingo_d