大家好，欢迎来到今天的“WordPress 深度游”讲座！今天咱们要扒的是 WordPress 主题定制的核心组件之一：WP_Customize_Setting 类。这玩意儿听着高大上，其实说白了，就是负责把主题选项和数据库牢牢绑在一起的红娘，让你的主题配置改动能够持久化，而不是刷新一下页面就灰飞烟灭。
第一部分：什么是 WP_Customize_Setting？（理论先行，别打瞌睡！）
WP_Customize_Setting 是 WordPress 自定义设置 API 的一个关键类。它代表着一个单独的可定制的设置项，例如主题的颜色方案、页脚文本、logo 图片等等。每个 WP_Customize_Setting 实例都负责以下几个关键任务：
- 注册设置： 告诉 WordPress 存在这么一个设置项，以及它的一些基本属性（例如 ID、数据类型、传输方式）。
- 验证设置： 检查用户输入的值是否有效，确保不会把数据库搞崩。
- 清理设置： 对用户输入的值进行清理，例如去除多余的空格、HTML 标签等等，保证数据的干净。
- 存储设置： 把设置值保存到数据库中，通常是
wp_options表。 - 读取设置： 从数据库中读取设置值，并提供给主题使用。
简单来说，WP_Customize_Setting 就是一个双向通道，负责在用户界面（主题定制器）和数据库之间传递数据，并确保数据的完整性和有效性。
第二部分：WP_Customize_Setting 的家族成员（了解继承关系，才能更好地理解用法！）
WP_Customize_Setting 本身是一个抽象类，不能直接实例化。我们需要使用它的子类来实现具体的设置项。WordPress 提供了几个常用的子类：
WP_Customize_Theme_Option： 最常用的子类，用于存储主题选项。设置值保存在wp_options表中，选项名通常以theme_mods_开头。WP_Customize_Nav_Menu_Setting： 用于存储导航菜单的信息。WP_Customize_Sidebar_Setting： 用于存储侧边栏的信息。
当然，你也可以自定义 WP_Customize_Setting 的子类，以满足更特殊的需求。
第三部分：WP_Customize_Setting 的核心方法（掌握这些方法，才能玩转主题定制！）
WP_Customize_Setting 类定义了一些非常重要的方法，这些方法决定了设置项的行为。下面列出几个最常用的：
| 方法名 | 作用 |
|---|---|
__construct() |
构造函数，用于初始化设置项。需要传入设置 ID 和一些配置参数。 |
value() |
获取设置值。这个方法会从数据库中读取设置值，并进行必要的处理（例如反序列化）。 |
update() |
更新设置值。这个方法会先验证和清理用户输入的值，然后将其保存到数据库中。 |
sanitize() |
对用户输入的值进行清理。这个方法可以接受一个回调函数，用于自定义清理逻辑。 |
validate() |
验证用户输入的值。这个方法可以接受一个回调函数，用于自定义验证逻辑。 |
transport() |
获取设置的传输方式。传输方式决定了设置值的更新方式，可以是 refresh（刷新整个页面）或 postMessage（使用 JavaScript 异步更新）。 |
preview() |
在主题定制器预览中显示设置效果。这个方法通常用于 postMessage 传输方式，需要在 JavaScript 中实现相应的预览逻辑。 |
第四部分：代码实战：创建一个自定义主题选项（撸起袖子，开始敲代码！）
光说不练假把式，咱们来写一段代码，创建一个自定义主题选项，让大家更直观地了解 WP_Customize_Setting 的用法。
假设我们要创建一个主题选项，用于设置网站的版权信息。
- 注册设置：
<?php
/**
* 注册主题定制设置
*/
function my_theme_customize_register( $wp_customize ) {
// 添加一个设置
$wp_customize->add_setting(
'my_theme_copyright_text', // 设置 ID，必须唯一
array(
'default' => 'Copyright © 2023', // 默认值
'sanitize_callback' => 'sanitize_text_field', // 清理回调函数，这里使用 WordPress 内置的 `sanitize_text_field` 函数
'transport' => 'refresh', // 传输方式，这里使用 `refresh`，表示刷新整个页面
)
);
// 添加一个控制项，用于在主题定制器中显示设置
$wp_customize->add_control(
'my_theme_copyright_text',
array(
'label' => __( '版权信息', 'my-theme' ), // 控制项标签
'section' => 'title_tagline', // 控制项所属的 section，这里使用 WordPress 内置的 `title_tagline` section
'type' => 'text', // 控制项类型，这里使用 `text`，表示一个文本输入框
)
);
}
add_action( 'customize_register', 'my_theme_customize_register' );
?>这段代码做了以下几件事：
- 使用
add_action( 'customize_register', 'my_theme_customize_register' )钩子，在主题定制器初始化时执行my_theme_customize_register函数。 - 在
my_theme_customize_register函数中，使用$wp_customize->add_setting()方法注册一个名为my_theme_copyright_text的设置。 add_setting()方法接受两个参数：设置 ID 和一个配置数组。- 配置数组中，
default属性指定了设置的默认值，sanitize_callback属性指定了清理回调函数，transport属性指定了传输方式。 - 使用
$wp_customize->add_control()方法添加一个控制项，用于在主题定制器中显示设置。 add_control()方法接受两个参数：设置 ID 和一个配置数组。- 配置数组中，
label属性指定了控制项的标签，section属性指定了控制项所属的 section，type属性指定了控制项的类型。
- 在主题中使用设置：
<?php
/**
* 获取版权信息
*/
function my_theme_get_copyright_text() {
return get_theme_mod( 'my_theme_copyright_text', 'Copyright © 2023' ); // 从数据库中读取设置值，如果不存在则使用默认值
}
?>
<p><?php echo my_theme_get_copyright_text(); ?></p>这段代码做了以下几件事：
- 定义了一个名为
my_theme_get_copyright_text的函数，用于获取版权信息。 - 在
my_theme_get_copyright_text函数中，使用get_theme_mod()函数从数据库中读取设置值。 get_theme_mod()函数接受两个参数：设置 ID 和一个默认值。- 如果数据库中存在该设置，则返回设置值；否则返回默认值。
- 在主题的页脚中调用
my_theme_get_copyright_text()函数，显示版权信息。
现在，打开主题定制器，你应该能看到一个名为“版权信息”的文本输入框。修改这个输入框的值，保存后，网站的页脚中显示的版权信息也会随之改变。
第五部分：高级用法：自定义清理和验证（打造更健壮的主题！）
上面的例子使用了 WordPress 内置的 sanitize_text_field 函数作为清理回调函数。但有时候，我们需要更复杂的清理和验证逻辑。这时候，就需要自定义清理和验证回调函数。
- 自定义清理回调函数：
<?php
/**
* 自定义清理回调函数
*/
function my_theme_sanitize_copyright_text( $input ) {
// 去除 HTML 标签
$input = wp_strip_all_tags( $input );
// 限制长度
$input = mb_substr( $input, 0, 100 );
return $input;
}
?>这个函数做了以下几件事：
- 使用
wp_strip_all_tags()函数去除 HTML 标签，防止用户输入恶意代码。 - 使用
mb_substr()函数限制字符串长度，防止数据库溢出。
- 自定义验证回调函数：
<?php
/**
* 自定义验证回调函数
*/
function my_theme_validate_copyright_text( $validity, $value ) {
if ( empty( $value ) ) {
$validity->add_error( 'empty_copyright_text', __( '版权信息不能为空', 'my-theme' ) );
}
return $validity;
}
?>这个函数做了以下几件事：
- 检查输入的值是否为空。
- 如果为空，则使用
$validity->add_error()方法添加一个错误信息。 - 错误信息会在主题定制器中显示给用户。
- 更新
add_setting()方法：
<?php
$wp_customize->add_setting(
'my_theme_copyright_text',
array(
'default' => 'Copyright © 2023',
'sanitize_callback' => 'my_theme_sanitize_copyright_text', // 使用自定义的清理回调函数
'validate_callback' => 'my_theme_validate_copyright_text', // 使用自定义的验证回调函数
'transport' => 'refresh',
)
);
?>将 sanitize_callback 和 validate_callback 属性分别设置为自定义的清理和验证回调函数。
现在，如果用户输入的版权信息包含 HTML 标签或超过 100 个字符，或者为空，主题定制器会显示相应的错误信息，并阻止用户保存设置。
第六部分：postMessage 传输方式（让主题定制更流畅！）
前面的例子使用了 refresh 传输方式，这意味着每次修改设置后，都需要刷新整个页面才能看到效果。这在用户体验上不太友好。postMessage 传输方式可以解决这个问题，它允许使用 JavaScript 异步更新设置值，无需刷新页面。
- 更新
add_setting()方法：
<?php
$wp_customize->add_setting(
'my_theme_copyright_text',
array(
'default' => 'Copyright © 2023',
'sanitize_callback' => 'sanitize_text_field',
'transport' => 'postMessage', // 使用 `postMessage` 传输方式
)
);
?>- 添加 JavaScript 代码：
( function( $ ) {
wp.customize( 'my_theme_copyright_text', function( value ) {
value.bind( function( newval ) {
$( '.copyright-text' ).html( newval ); // 使用 JavaScript 更新页面上的版权信息
} );
} );
} )( jQuery );这段代码做了以下几件事：
- 使用
wp.customize()方法监听my_theme_copyright_text设置的变化。 - 当设置值发生变化时，执行回调函数。
- 在回调函数中，使用 jQuery 更新页面上 class 为
copyright-text的元素的 HTML 内容。
- 更新主题模板：
<p class="copyright-text"><?php echo my_theme_get_copyright_text(); ?></p>给版权信息添加一个 class copyright-text，以便 JavaScript 代码可以找到它。
现在，打开主题定制器，修改版权信息，你会发现页面上的版权信息会立即更新，无需刷新页面。
第七部分：总结（记住这些要点，从此告别主题定制的坑！）
WP_Customize_Setting 类是 WordPress 主题定制的核心组件，它负责将主题选项和数据库牢牢绑在一起。通过学习 WP_Customize_Setting 类的用法，我们可以创建自定义主题选项，并实现更复杂的主题定制功能。
记住以下几个要点：
WP_Customize_Setting是一个抽象类，需要使用它的子类来实现具体的设置项。WP_Customize_Theme_Option是最常用的子类，用于存储主题选项。add_setting()方法用于注册设置，add_control()方法用于添加控制项。sanitize_callback属性指定清理回调函数，validate_callback属性指定验证回调函数。transport属性指定传输方式，可以是refresh或postMessage。- 使用
get_theme_mod()函数从数据库中读取设置值。 - 使用 JavaScript 可以实现
postMessage传输方式的预览效果。
掌握了这些要点，你就可以轻松玩转 WordPress 主题定制，打造更强大的主题！
今天的讲座就到这里，感谢大家的参与！希望大家有所收获，下次再见！