WordPress定制器JavaScript API：入门教程

wordpress Customizer 自成立以来一直在积极开发。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 Customizer 的核心概念以及 Panel、Section、Setting 和 Control 等组件。否则，我强烈建议您在更进一步之前花一些时间在我们的教程和视频课程上。

• WordPress主题定制器指南

• WordPress 主题定制器

• 编写定制器就绪的 WordPress 主题

设置和控制

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

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

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

底层代码

我们这里的主题是基于 Underscores的，它在文件中放置了所有与定制器相关的代码  。/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 );

正如您在上面看到的，我们将在 Customizer 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 操作挂钩访问。

下一步是什么？

WordPress 从一开始就在 PHP 上投入了大量资金。因此，支持生态系统的大多数开发人员比 JavaScript API 更精通和熟悉 PHP API 也就不足为奇了。

直到最近，它才通过定制器和 WP-API 广泛集成了 JavaScript。掌握 WordPress Customizer 中的 JavaScript API 可能是一个相当大的挑战。如前所述，这是目前记录最少的 WordPress 方面。因此，我们将彻底探讨这个主题。