发布于 由admin

阐述 `WP_Customize_Manager` 类的源码，它是如何管理主题定制器中的所有设置和控件的？

各位，今天咱们来聊聊 WordPress 主题定制器的核心——WP_Customize_Manager 类。 这家伙可是个大管家，掌管着主题定制器里所有的设置、控件，以及各种面板和版块。 想玩转主题定制器，就得先摸清它的脾气。 咱们今天就来扒一扒它的源码，看看它到底是怎么运转的。

一、WP_Customize_Manager：定制器的大脑

首先，WP_Customize_Manager 类位于 wp-includes/class-wp-customize-manager.php 文件中。 它是整个定制器的核心类，负责：

  • 注册和管理设置 (Settings): 比如主题颜色、站点标题、背景图片等等，用户可以在定制器中修改这些设置。
  • 注册和管理控件 (Controls): 这些是用户用来修改设置的界面元素，比如颜色选择器、文本框、下拉菜单等。
  • 注册和管理面板 (Panels) 和版块 (Sections): 用于组织设置和控件，方便用户查找和修改。
  • 处理 AJAX 请求: 保存用户的修改，预览效果，等等。
  • 生成定制器的 HTML 结构: 最终在浏览器中呈现给用户。
  • 权限管理: 确保只有授权用户才能进行定制。

简单来说，WP_Customize_Manager 就像一个指挥中心，协调各个部件，最终呈现出一个用户友好的主题定制界面。

二、实例化 WP_Customize_Manager

在 WordPress 后台，当你点击“外观” -> “定制” 菜单时，WordPress 会实例化 WP_Customize_Manager 类。 核心代码通常出现在 wp-admin/customize.php 文件中：

<?php
// 确保直接访问此文件是不允许的
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

// 引入 WordPress 管理后台的必要文件
require_once( ABSPATH . 'wp-admin/admin.php' );

// 检查用户权限
if ( ! current_user_can( 'customize' ) ) {
    wp_die(
        '<h1>' . __( '您没有权限自定义主题。' ) . '</h1>',
        403
    );
}

// 引入定制器相关的类和函数
require_once( ABSPATH . 'wp-includes/class-wp-customize-manager.php' );

// 实例化 WP_Customize_Manager 类
$wp_customize = new WP_Customize_Manager();

// 开始定制器流程
$wp_customize->prepare_control_templates();
$wp_customize->enqueue_scripts();
$wp_customize->print_header_scripts();
$wp_customize->wp_loaded();
$wp_customize->customize_loaded();
$wp_customize->admin_page();

这段代码的关键在于 $wp_customize = new WP_Customize_Manager();，它创建了一个 WP_Customize_Manager 类的实例，并将其赋值给 $wp_customize 变量。 之后，通过 $wp_customize 对象，就可以调用类中的各种方法，开始定制器的初始化和运行。

三、核心属性和方法

WP_Customize_Manager 类有很多属性和方法，我们重点关注几个核心的：

  • 属性：

    • settings: 一个数组，存储着所有已注册的设置 ( WP_Customize_Setting 对象)。
    • controls: 一个数组，存储着所有已注册的控件 ( WP_Customize_Control 对象)。
    • panels: 一个数组，存储着所有已注册的面板 ( WP_Customize_Panel 对象)。
    • sections: 一个数组，存储着所有已注册的版块 ( WP_Customize_Section 对象)。
    • transport: 设置传输方式，可以是 refresh (页面刷新) 或 postMessage (异步更新)。
    • errors: 存储错误信息。
    • nav_menus_available: 是否启用了导航菜单定制。

  • 方法：

    方法名 作用
    add_setting() 注册一个新的设置。
    get_setting() 获取一个已注册的设置对象。
    add_control() 注册一个新的控件。
    get_control() 获取一个已注册的控件对象。
    add_panel() 注册一个新的面板。
    get_panel() 获取一个已注册的面板对象。
    add_section() 注册一个新的版块。
    get_section() 获取一个已注册的版块对象。
    register() 注册设置、控件、面板和版块的回调函数。
    customize_loaded() 在定制器加载时执行，通常用于注册默认的设置、控件等。
    enqueue_scripts() 加载定制器所需的 CSS 和 JavaScript 文件。
    print_header_scripts() 在 <head> 标签中输出定制器所需的 JavaScript 代码。
    admin_page() 生成定制器的 HTML 结构，并在浏览器中呈现。
    save() 保存用户在定制器中所做的修改。
    validate_setting() 验证设置的值是否有效。
    sanitize_callback() 获取设置的清理回调函数。
    get_stylesheet() 根据定制器中的设置生成 CSS 代码。
    remove_control() 移除一个控件。
    remove_section() 移除一个版块。
    remove_panel() 移除一个面板。
    selective_refresh() 获取选择性刷新实例，用于局部刷新定制器预览。
    is_preview() 检查当前是否处于定制器预览模式。
    get_preview_url() 获取定制器预览的 URL。
    get_template_part() 获取主题模板部件，用于定制器预览。
    is_theme_active() 检查当前主题是否处于激活状态。
    get_stylesheet_url() 获取主题的样式表 URL。
    get_parent_stylesheet_url() 获取父主题的样式表 URL。
    get_template() 获取当前主题的模板目录。
    get_stylesheet() 获取当前主题的样式表目录。

四、注册设置、控件、面板和版块

这是 WP_Customize_Manager 最重要的功能之一。 我们可以通过 add_setting()、add_control()、add_panel() 和 add_section() 方法来注册它们。

1. 注册设置 (add_setting()):

$wp_customize->add_setting( 'my_theme_color', array(
    'default'   => '#000000',
    'transport' => 'postMessage', // 'refresh' or 'postMessage'
    'sanitize_callback' => 'sanitize_hex_color',
) );
  • 'my_theme_color': 设置的 ID，必须唯一。
  • 'default': 设置的默认值。
  • 'transport': 设置的传输方式，postMessage 表示使用 AJAX 异步更新，refresh 表示页面刷新。
  • 'sanitize_callback': 一个清理回调函数，用于验证和清理用户输入的值。 sanitize_hex_color 是 WordPress 内置的，用于清理十六进制颜色值。

2. 注册控件 (add_control()):

$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'my_theme_color', array(
    'label'   => __( '主题颜色', 'my-theme' ),
    'section' => 'colors', // 关联的版块 ID
    'settings'   => 'my_theme_color', // 关联的设置 ID
) ) );
  • new WP_Customize_Color_Control(...): 创建一个颜色选择器控件。 WordPress 提供了多种控件类，比如 WP_Customize_Control (基础控件)、WP_Customize_Color_Control (颜色选择器)、WP_Customize_Image_Control (图片上传)、WP_Customize_Upload_Control (文件上传) 等。
  • 'label': 控件的标签，显示在定制器中。
  • 'section': 控件所属的版块 ID。
  • 'settings': 控件关联的设置 ID。

3. 注册版块 (add_section()):

$wp_customize->add_section( 'my_theme_settings', array(
    'title'   => __( '主题设置', 'my-theme' ),
    'priority' => 20, // 版块的显示优先级
) );
  • 'my_theme_settings': 版块的 ID，必须唯一。
  • 'title': 版块的标题，显示在定制器中。
  • 'priority': 版块的显示优先级，数字越小，优先级越高。

4. 注册面板 (add_panel()):

$wp_customize->add_panel( 'my_theme_panel', array(
    'title'       => __( '我的主题面板', 'my-theme' ),
    'description' => __( '主题的各种设置都在这里。', 'my-theme' ), // 可选
    'priority'    => 160,
) );
  • 'my_theme_panel': 面板的 ID，必须唯一。
  • 'title': 面板的标题，显示在定制器中。
  • 'description': 面板的描述，可选。
  • 'priority': 面板的显示优先级。

将版块添加到面板：

$wp_customize->add_section( 'my_theme_section', array(
    'title'       => __( '我的主题版块', 'my-theme' ),
    'priority'    => 30,
    'panel'       => 'my_theme_panel', // 将版块添加到指定的面板
) );

关键在于 'panel' => 'my_theme_panel'，它指定了该版块属于 my_theme_panel 面板。

五、customize_register 钩子

注册设置、控件、面板和版块的最佳时机是在 customize_register 钩子中。 这个钩子会在 WP_Customize_Manager 对象实例化之后，但在定制器界面呈现之前触发。

add_action( 'customize_register', 'my_theme_customize_register' );

function my_theme_customize_register( $wp_customize ) {
    // 在这里注册你的设置、控件、面板和版块
    $wp_customize->add_setting( 'my_theme_color', array(
        'default'   => '#000000',
        'transport' => 'postMessage',
        'sanitize_callback' => 'sanitize_hex_color',
    ) );

    $wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'my_theme_color', array(
        'label'   => __( '主题颜色', 'my-theme' ),
        'section' => 'colors',
        'settings'   => 'my_theme_color',
    ) ) );

    $wp_customize->add_section( 'colors', array(
        'title'   => __( '颜色', 'my-theme' ),
        'priority' => 20,
    ) );
}

在这个例子中，my_theme_customize_register 函数会在 customize_register 钩子触发时执行，它接收 $wp_customize 对象作为参数，我们可以通过这个对象来注册设置、控件、面板和版块。

六、transport 属性：refresh vs postMessage

transport 属性决定了设置的更新方式。

  • refresh (默认): 当用户修改设置时，整个定制器预览页面会刷新。 这种方式简单粗暴，但会影响用户体验。
  • postMessage (推荐): 当用户修改设置时，通过 JavaScript 使用 AJAX 异步更新预览页面，无需刷新。 这种方式更加流畅，用户体验更好。

如果使用 postMessage，还需要编写 JavaScript 代码来监听设置的改变，并更新预览页面。

( function( $ ) {
    wp.customize( 'my_theme_color', function( value ) {
        value.bind( function( newval ) {
            $( 'body' ).css( 'background-color', newval );
        } );
    } );
} )( jQuery );

这段 JavaScript 代码监听 my_theme_color 设置的改变，当用户修改颜色时，它会将 <body> 元素的背景颜色更新为新的颜色值。

七、sanitize_callback：数据清理

sanitize_callback 是一个非常重要的参数，它用于验证和清理用户输入的值，防止恶意代码注入，确保数据的安全性。

WordPress 提供了很多内置的清理函数，比如：

  • sanitize_text_field(): 清理文本字段。
  • sanitize_email(): 清理邮箱地址。
  • sanitize_url(): 清理 URL。
  • sanitize_hex_color(): 清理十六进制颜色值。
  • absint(): 将值转换为绝对整数。
  • wp_kses_post(): 清理 HTML 代码，只允许安全的标签和属性。

也可以自定义清理函数：

function my_theme_sanitize_text( $input ) {
    return wp_kses_post( force_balance_tags( $input ) );
}

$wp_customize->add_setting( 'my_theme_text', array(
    'default'   => '',
    'transport' => 'postMessage',
    'sanitize_callback' => 'my_theme_sanitize_text',
) );

在这个例子中，my_theme_sanitize_text 函数使用 wp_kses_post 和 force_balance_tags 来清理文本输入，确保 HTML 代码的安全性。

八、错误处理

WP_Customize_Manager 类也有错误处理机制，可以通过 $wp_customize->errors 属性来访问错误信息。 可以添加错误：

$wp_customize->add_setting( 'my_setting', array(
    'sanitize_callback' => function( $value ) use ( $wp_customize ) {
        if ( empty( $value ) ) {
            $wp_customize->add_error( 'my_setting', __( '此字段不能为空。' ) );
            return '';
        }
        return $value;
    },
) );

并在定制器界面显示错误信息。

九、移除默认控件、版块和面板

有时候，你可能需要移除 WordPress 默认的控件、版块或面板。 可以使用 remove_control()、remove_section() 和 remove_panel() 方法。

add_action( 'customize_register', 'my_theme_customize_register' );

function my_theme_customize_register( $wp_customize ) {
    $wp_customize->remove_control( 'blogdescription' ); // 移除站点描述控件
    $wp_customize->remove_section( 'colors' ); // 移除颜色版块
    // $wp_customize->remove_panel( 'nav_menus' ); // 移除导航菜单面板
}

十、选择性刷新 (Selective Refresh)

选择性刷新是 WordPress 4.5 引入的一个特性，允许只刷新预览页面中的特定区域，而不是整个页面。 这可以大大提高定制器的性能和用户体验。

要使用选择性刷新，需要在主题中支持它，并使用 WP_Customize_Selective_Refresh 类。

首先，在 functions.php 文件中添加以下代码：

add_action( 'after_setup_theme', 'my_theme_setup' );

function my_theme_setup() {
    add_theme_support( 'customize-selective-refresh-widgets' );
}

然后，在 customize_register 钩子中，注册一个选择性刷新部件：

add_action( 'customize_register', 'my_theme_customize_register' );

function my_theme_customize_register( $wp_customize ) {
    $wp_customize->selective_refresh->add_partial( 'blogname', array(
        'selector' => '.site-title a',
        'render_callback' => 'my_theme_customize_partial_blogname',
    ) );
}

function my_theme_customize_partial_blogname() {
    return get_bloginfo( 'name' );
}
  • 'selector': 要刷新的 CSS 选择器。
  • 'render_callback': 一个回调函数，用于生成新的 HTML 代码。

十一、总结

WP_Customize_Manager 类是 WordPress 主题定制器的核心，它负责管理所有的设置、控件、面板和版块。 通过 add_setting()、add_control()、add_panel() 和 add_section() 方法，我们可以注册自定义的设置和控件，从而扩展定制器的功能。 transport 属性决定了设置的更新方式，sanitize_callback 用于验证和清理用户输入的数据。 选择性刷新可以提高定制器的性能和用户体验。

掌握 WP_Customize_Manager 类，可以让你更好地定制 WordPress 主题，为用户提供更加个性化的体验。 当然，这只是冰山一角，还有很多高级用法等待你去探索。 希望今天的讲解能帮助你入门，开启你的主题定制之旅！

好了，今天就到这里。 祝大家学习愉快！ 咱们下次再见！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注