起步：了解WordPress自定义器JavaScript API

WBOY 原创: 2023-09-02 10:45:05 515浏览

WordPress 定制器自诞生以来一直在积极开发。 API 不断发展，包括 JavaScript API。然而，它是 WordPress Codex 中记录最少的 API 之一。因此，只有少数详细记录展示了如何实际利用 JavaScript API。

利用 WordPress 定制器中的 JavaScript API 实际上可以使我们在定制主题时提供更引人注目的实时体验，而不仅仅是将更改从控件投射到预览窗口。

您可能熟悉如何使用定制器 JavaScript API 将更改实时投射到预览窗口。为此，我们将设置 transport 模式设置为 postMessage 并添加相应的 JavaScript 代码，如下所示。

wp.customize( 'blogname', function( value ) {
	value.bind( function( to ) {
		$( '.site-title a' ).text( to );
	} );
} );

但是，我们还可以进一步扩展 API，例如隐藏、显示或移动部分、面板、控件，根据另一个设置值更改设置的值，以及互连预览和控件互动。这些就是我们将在本教程中研究的内容。

快速入门

我们通过几篇文章和几个系列对 WordPress 定制器进行了相当广泛的介绍，涵盖了定制器 API 的细节。

我想您已经掌握了 WordPress 定制器的核心概念以及面板、部分、设置和控制等组件。否则，我强烈建议您在进一步了解之前花一些时间学习我们有关该主题的教程和视频课程。

WordPress 主题定制器指南
WordPress 主题定制器
编写可供定制器使用的 WordPress 主题

设置和控件

首先，我们将检查定制器中为本教程添加的“设置”和“控件”。我们还将研究将它们放在适当位置的代码。

起步：了解WordPress自定义器JavaScript API

在本教程中，我们将重点关注网站“网站标题”。正如您在上面看到的，我们有两个控件：本机 WordPress“站点标题”输入字段和用于启用或禁用“站点标题”的自定义复选框。这两个控件位于“站点标识”部分。图像的右侧是预览，您可以在其中看到正在渲染的“网站标题”。

此外，正如您在下面看到的，我们还有两个位于“颜色”部分的控件，用于更改“网站标题”颜色及其 hover 状态颜色。

起步：了解WordPress自定义器JavaScript API

底层代码

我们的主题基于下划线，其中所有与定制器相关的代码都放置在 /inc/customizer.php 文件中。

function tuts_customize_register( $wp_customize ) {

	$wp_customize->get_setting( 'blogname' )->transport = 'postMessage';

	$wp_customize->get_setting( 'blogdescription' )->transport = 'postMessage';
	$wp_customize->get_control( 'blogdescription' )->priority = '12';

	$wp_customize->get_setting( 'header_textcolor' )->default = '#f44336';
	$wp_customize->get_setting( 'header_textcolor' )->transport = 'postMessage';

	// Checkbox to Display Blogname
	$wp_customize->add_setting( 'display_blogname', array(
		'transport' => 'postMessage',
	) );

	$wp_customize->add_control( 'display_blogname', array(
		'label'     => __( 'Display Site Title', 'tuts' ),
		'section'   => 'title_tagline',
		'type'      => 'checkbox',
		'priority'  => 11,
	) );

	// Add main text color setting and control.
	$wp_customize->add_setting( 'header_textcolor_hover', array(
		'default'           => '#C62828',
		'sanitize_callback' => 'sanitize_hex_color',
		'transport'         => 'postMessage',
	) );

	$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'header_textcolor_hover', array(
		'label'    => __( 'Header Text Color: Hover', 'tuts' ),
		'section'  => 'colors',
		'priority' => '11'
	) ) );
}
add_action( 'customize_register', 'tuts_customize_register' );

正如您在上面看到的，我们对代码进行了一些修改，以满足本教程中的需求。

我们将 WordPress 内置设置 blogdescription 降低为 12，以便复选框设置 display_blogname 出现在“站点标题”输入字段下方。
我们创建一个名为 display_blogname 的新控件。我们将 priority 设置为 11，在我们的示例中，它位于“网站标题”和“标语”输入字段之间。
将 header_text 默认颜色设置为 #f44336，并将 transport 类型设置为 postMessage。
我们还创建了一个新设置，header_text_color。同样，我们还将优先级设置为 11，使其出现在 header_textcolor 设置下方。

所有这些设置均通过 postMessage 设置，而不是通过 refresh 设置。 postMessage 选项允许异步传输值并实时显示在预览窗口中。但是，我们还必须编写自己的 JavaScript 来处理更改。

加载 JavaScript

我们需要创建两个 JavaScript 文件：一个文件 customizer-preview.js 用于处理预览，另一个文件 customizer-control.js 用于处理定制器面板内的控件。

js
├── customizer-preview.js // 1. File to handle the Preview
├── customizer-control.js // 2. File to handle the Controls
├── navigation.js
└── skip-link-focus-fix.js

在 customizer-preview.js 中包含以下代码。

( function( $ ) {
	// Codes here.
} )( jQuery );

它目前是一个空的封闭 JavaScript 函数。我们将在本系列的下一个教程中更具体地讨论如何在预览窗口中预览更改。

在另一个文件 customizer-control.js 中，我们添加以下代码：

(function( $ ) {
	wp.customize.bind( 'ready', function() {
		var customize = this;
		// Codes here
	} );
})( jQuery );

正如您在上面所看到的，我们将在自定义程序 ready 事件中将此代码包装在此文件中。这将确保在我们开始执行任何自定义功能之前，自定义程序中的所有内容都已完全准备好，包括设置、面板和控件。

最后，添加代码后，我们将在两个不同的位置加载这两个 JavaScript 文件。

// 1. customizer-preview.js
function tuts_customize_preview_js() {
	wp_enqueue_script( 'tuts_customizer_preview', get_template_directory_uri() . '/js/customizer-preview.js', array( 'customize-preview' ), null, true );
}
add_action( 'customize_preview_init', 'tuts_customize_preview_js' );

// 2. customizer-control.js
function tuts_customize_control_js() {
	wp_enqueue_script( 'tuts_customizer_control', get_template_directory_uri() . '/js/customizer-control.js', array( 'customize-controls', 'jquery' ), null, true );
}
add_action( 'customize_controls_enqueue_scripts', 'tuts_customize_control_js' );

customizer-preview.js 文件将通过 customize_preview_init 操作挂钩加载到定制器预览窗口中。 customizer-control.js 文件将加载到定制程序后端，其中的设置和控制元素可通过 customize_controls_enqueue_scripts 操作挂钩访问。