在WordPress 4.1中,为所有Customizer对象介绍了新扩展的JavaScript API。整个JavaScript API当前位于一个文件中,wp-admin/js/customize-controls.js,其中包含所有对象,核心自定义控件等的模型。

预览JS和控制JS

Customizer应用程序当前分为两个不同的领域:定制器控件“窗格”和自定义预览。预览当前处于iframe中,这意味着所有JS都在控件窗格或预览中运行。邮政API用于在预览和控件之间进行通信。

大多数主题仅在自定义预览中实现JavaScript,并使用它通过后邮件实现设置的即时预览。但是,控件端上的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 );
			}
		});
	}
);

类似的逻辑可以用来activateUI对象基于设置的值。二十7个主题包括一些有用的示例,用于利用自定义JS API以改善用户体验。请注意,控件窗格有一个JS文件,命名为customize-controls.js和一个用于自定义预览的文件,名为customize-preview.js。为了清楚起见,建议所有主题和插件都遵循此命名约定,即使仅在控件或预览中提供自定义JS,但两者都不是两者。

此页面的其余部分主要专用于WordPress 4.1中构建的控件端JS API。

控制,部分和面板的模型

与PHP一样,每个定制器对象类型都具有JavaScript中的相应对象。有wp.customize.Control,wp.customize.Panel,wp.customize.Section 模型以及wp.customize.panel,wp.customize.section, and wp.customize.control存储所有控制实例的集合(是的,它们是单数)。您可以通过面板,部分和控件来迭代以下方式:

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

将控件,部分和面板相关联

在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' );

同样,您可以以相同的方式获得部分的面板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状态(awp.customize.Value实例)。当。。。的时候active国家变化,面板,部分和控制实例援引各自的onChangeActive方法,默认情况下,如果falsetrue分别。也有activate()deactivate()现在可以操纵这一点的方法active状态,用于面板,部分和控件。这些状态的主要目的是显示或隐藏对象,而无需完全从定制器中删除该对象。

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?autocus [panel] =小部件
  • …/wp-admin/customize.php?autocous [extions] =颜色
  • …/wp-admin/customize.php?autocus [control] = blogname

这用于WordPress核心 添加一个链接 在“小部件管理”页面上,可以直接链接到定制器中的小部件面板,并将自定义预览中的可见编辑快捷方式与自定义窗格中的关联控件连接起来。

优先事项

在注册面板,部分或控制PHP时,您可以提供priority范围。该值存储在一个wp.customize.Value每个相应的实例PanelSection,和Control实例。例如,您可以通过以下方式获得小部件面板的优先级:

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

然后,您可以动态更改优先级,并且定制器UI将自动重新安排以反映新的优先级:

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

自定义控件,面板和部分

在JS中使用自定义对象时,通常最容易检查WordPress Core中的自定义对象以了解代码结构。看 wp-admin/js/customize-controls.js,尤其是wp.customize.panel |部分|控制模型。请注意核心代码中的几个示例,尤其是在媒体控件中,这些示例通过对象层次结构建立在彼此的功能上。

By zhuon

发表回复

您的电子邮箱地址不会被公开。 必填项已用 * 标注