WordPress中文开发手册

WordPress主题开发 — 定制JavaScript API

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

预览JS和控件JS

定制应用程序当前分为两个不同的区域：自定义程序控件“窗格”和自定义预览。 该预览当前在一个iframe中，这意味着所有的JS都可以在控制窗格或预览中运行。 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 );
        }
    });
});

可以使用相似的逻辑来根据设置的值激活UI对象。 二十七主题包括一些有用的例子，用于利用自定义JS API来改善用户体验。 请注意，控制面板中有一个名为customize-controls.js的JS文件和一个名为customize-preview.js的自定义预览文件。 为了清楚起见，建议所有主题和插件遵循此命名约定，即使只在控件或预览中提供了自定义JS，而不是两者都提供。

本页的其余部分主要用于WordPress 4.1中内置的控件端JS API。

控件，部分和面板的模型

和PHP一样，每个Customizer对象类型都有一个JavaScript对应的对象。 有wp.customize.Control，wp.customize.Panel和wp.customize.Section模型，以及wp.customize.panel，wp.customize.section和wp.customize.control集合（是的，他们issingular） 存储所有控件实例。 您可以通过以下方式迭代面板，部分和控件：

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

一起关联控件，部分和面板

在PHP中注册新的控件时，您将传递父节ID：

$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获取节对象，请按照正常的方式查找该部分：wp.customize.section（id）。

您也可以使用此部分状态将控件移动到另一部分，此处将其移动到“导航”部分：

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

同样，您可以以相同的方式获取部分的面板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' );
});

上下文面板，部分和控件

控件，面板和节实例具有活动状态（一个wp.customize.Value实例）。 当活动状态发生变化时，面板，部分和控件实例调用各自的onChangeActive方法，该方法默认情况下分别向上和向下滑动容器元素，如果为false和true。 现在还有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
} });

请注意，只有在预览刷新或加载其他URL之前，手动更改活动状态才会保留。 activate（）/ deactivate（）方法被设计为遵循新扩展状态的模式。

聚焦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核心中用于在小部件管理页面上添加链接，以直接链接到定制器中的小部件面板，以及将自定义预览中的可见编辑快捷方式与自定义窗格中的关联控件进行连接。

重点

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

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

然后，您可以动态地更改优先级，并且Customizer UI将自动重新排列以反映新的优先级：

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

自定义控件，面板和部分

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

快速导航