自定义程序器 JavaScript 应用程序接口 (API)

最后更新：2026-10-05 15:56:51

在 WordPress 4.1 中，为所有自定义器对象引入了新扩展的 JavaScript API。整个 JavaScript API 目前位于单个文件中：wp-admin/js/customize-controls.js，其中包含所有对象的模型、核心自定义控件等。

预览 JS 和 Controls JS

自定义器应用程序目前分为两个不同的区域：自定义器控件“面板”（pane）和自定义化预览。预览当前位于 iframe 中，这意味着所有 JavaScript 运行在控件面板或预览中。使用 postMessage API 在预览和控件之间进行通信。

大多数主题仅在自定义预览中实现 JavaScript，并使用它通过 postMessage 实施设置的即时预览。但是，控件侧的 JS 可用于许多事情，例如根据其他设置的值动态显示和隐藏控件、更改预览 URL、聚焦预览的部分内容等。以下是核心中一个与预览交互的控件侧 JS 示例，在本例中，当帖子页面发生变化时更改预览 URL：

// Change the previewed URL to the selected page when changing the page_for_posts.
wp.customize(
	'page_for_posts',
	function( setting ) {
		setting.bind( function( pageId ) {
			pageId = parseInt( pageId, 10 );
			if ( pageId > 0 ) {
				api.previewer.previewUrl.set( api.settings.url.home + '?page_id=' + pageId );
			}
		});
	}
);

可以使用类似的逻辑来根据设置值activate（激活） UI 对象。Twenty Seventeen 主题包含一些利用自定义 JS API 以改善用户体验的有用示例。请注意，控件面板有一个名为 customize-controls.js 的 JavaScript 文件，还有一个用于自定义预览的文件，名为 customize-preview.js。为了清晰起见，建议所有主题和插件都遵循此命名约定，即使仅提供控件或预览中的自定义 JS（而非两者）。

本页面其余部分主要致力于在 WordPress 4.1 中构建的控件侧 JS API。

Controls、Sections 和 Panels 的模型

与 PHP 一样，每个 Customizer 对象类型在 JavaScript 中都有一个对应的对象。有 wp.customize.Control, wp.customize.Panel, 和 wp.customize.Section 模型，以及存储所有控件实例的 wp.customize.panel, wp.customize.section, andwp.customize.control集合（是的，它们是单数），您可以通过以下方式遍历面板、部分和控件：

wp.customize.panel.each( function ( panel ) { /* ... */ } );
wp.customize.section.each( function ( section ) { /* ... */ } );
wp.customize.control.each( function ( control ) { /* ... */ } );

将 Controls、Sections 和 Panels 关联在一起

在 PHP 中注册新控件时，您传入父部分 ID：

<?php
$wp_customize->add_control(
	'blogname',
	array(
		'label'   => __( 'Site Title' ),
		'section' => 'title_tagline',
	)
);
?>

在 JavaScript API 中，可以可预测地获取控件的部分：

id = wp.customize.control( 'blogname' ).section(); // returns title_tagline by default

要从 ID 获取部分对象，像往常一样通过 ID 查找该部分：wp.customize.section( id ).

您可以使用此 section（部分）状态将控件移动到另一个部分，此处将其移至导航部分：

wp.customize.control( 'blogname' ).section( 'nav' );

同样，您可以以相同方式获取部分的 panel ID：

id = wp.customize.section( 'sidebar-widgets-sidebar-1' ).panel(); // returns widgets by default

您也可以反向操作，获取面板和部分子项：

sections = wp.customize.panel( 'widgets' ).sections();controls = wp.customize.section( 'title_tagline' ).controls();

您可以使用这些将控件从一个部分移动到另一个部分：

_.each( wp.customize.section( 'title_tagline' ).controls(), function ( control ) {  
    control.section( 'nav' );
} );

上下文面板、部分和控件

Control, Panel, 和 Section实例具有active（活动）状态（一个 wp.customize.Value 实例）。当active状态改变时，面板、部分和控件实例调用各自的 onChangeActive方法，默认情况下分别向上或向下滑动容器元素，如果为false和true。现在还有用于操纵此active（活动）状态的 activate() 和 deactivate()方法，适用于面板、部分和控件。这些状态的主要目的是显示或隐藏对象，而不完全将其从自定义器中移除。

wp.customize.section( 'nav' ).deactivate(); // slide up
wp.customize.section( 'nav' ).activate({ duration: 1000 }); // slide down slowly
wp.customize.section( 'colors' ).deactivate({ duration: 0 }); // hide immediately
wp.customize.section( 'nav' ).deactivate({ completeCallback:
function () {  
    wp.customize.section( 'colors' ).activate(); // show after nav hides completely
} } );

请注意，手动更改active（活动）状态只会持续到预览刷新或加载另一个 URL 为止。activate()/deactivate()方法旨在遵循新的 expanded（扩展）状态的样式。

聚焦 UI 对象

基于面板、部分和控件的expand()/collapse()方法，这些模型还支持一个 focus()方法，它不仅扩展所有必要的元素，还将目标容器滚动到视图并将浏览器焦点放在容器中的第一个可聚焦元素上。例如，要展开“静态主页”部分并聚焦于“首页”的下拉选择框：

wp.customize.control( 'page_on_front' ).focus()

聚焦功能用于实现自动聚焦：在自定义器内部链接到面板、部分和控件的深度链接。请考虑这些 URL：

…/wp-admin/customize.php?autofocus[panel]=widgets
…/wp-admin/customize.php?autofocus[section]=colors
…/wp-admin/customize.php?autofocus[control]=blogname

这在 WordPress 核心中用于添加链接，在 widgets（小工具）管理页面上直接链接到自定义器内的 widgets 面板，以及将可见的编辑快捷方式与自定义器面板中的相关控件连接起来。

优先级

当在 PHP 中注册面板、部分或控件时，您可以提供一个 priority（优先级）参数。此值存储在每个相应的Panel, Section,和Control实例的 wp.customize.Value实例中。例如，您可以通过以下方式获取 widgets 面板的优先级：

priority = wp.customize.panel( 'widgets' ).priority(); // returns 110 by default

然后您可以动态更改优先级，自定义器 UI 将自动重新排列以反映新的优先级：

wp.customize.panel( 'widgets' ).priority( 1 ); // move Widgets to the top

Custom Controls、Panels 和 Sections

在使用 JS 中的自定义 Customizer 对象时，通常最容易检查 WordPress 核心中的自定义对象以了解代码结构。参见 wp-admin/js/customize-controls.js，特别是 wp.customize.Panel|Section|Control模型。注意核心代码中的几个示例，特别是在媒体控件中，它们通过对象层次结构构建彼此的功能。