云策 WordPress 开发者社区

钩子文档

customize_preview_init

查看官方原文 ↗
💡 云策文档标注

概述

customize_preview_init 是一个 WordPress 动作钩子，在主题定制器预览初始化且 JavaScript 设置已打印后触发。主要用于在主题定制器中加载 JavaScript 文件，以实现实时预览功能。

关键要点

  • 触发时机：当主题定制器预览初始化完成，且 JavaScript 设置已输出后执行。
  • 主要用途：用于在主题定制器中加载脚本（如 theme-customizer.js），以支持实时预览，通常与 'transport'=>'postMessage' 设置配合使用。
  • 参数：接受一个 $manager 参数，类型为 WP_Customize_Manager 实例。
  • 注意事项：此钩子仅适用于主题定制器内部，如需在实时网站上输出保存的设置，仍需使用 wp_head 钩子输出生成的 CSS。
  • 版本历史：自 WordPress 3.4.0 版本引入。

代码示例

/**
 * 示例函数：加载主题定制器实时预览脚本
 */
public static function mytheme_customizer_live_preview()
{
    wp_enqueue_script( 
        'mytheme-themecustomizer',
        get_template_directory_uri().'/assets/js/theme-customizer.js',
        array( 'jquery','customize-preview' ),
        '',
        true
    );
}
add_action( 'customize_preview_init', 'mytheme_customizer_live_preview' );

注意事项

使用此钩子时，确保相关设置已设置为 'transport'=>'postMessage'，而非默认的 'refresh'，否则实时预览可能无法正常工作。可通过 customize_register 钩子覆盖默认设置。

📄 原文内容

Fires once the Customizer preview has initialized and JavaScript settings have been printed.

Parameters

$managerWP_Customize_Manager
WP_Customize_Manager instance.

More Information

This action hook allows you to enqueue assets (such as javascript files) directly in the Theme Customizer only. To output saved settings onto your live site, you still need to output generated CSS using the wp_head hook.

Generally, this hook is used almost exclusively to enqueue a theme-customizer.js file for controlling live previews in WordPress’s Theme Customizer.

For more information, see the Theme Handbook article on the Theme_Customization_API.

Source

do_action( 'customize_preview_init', $this );

View all references View on Trac View on GitHub

Used by Description
WP_Customize_Manager::customize_preview_init()wp-includes/class-wp-customize-manager.php

Prints JavaScript settings.

Changelog

Version Description
3.4.0 Introduced.

User Contributed Notes

  1. Skip to note 5 content


    Steven Lin


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Example migrated from Codex:

    Usage might look like this…

    /**
 * This outputs the javascript needed to automate the live settings preview.
 * Also keep in mind that this function isn't necessary unless your settings 
 * are using 'transport'=>'postMessage' instead of the default 'transport'
 * => 'refresh'
 * 
 * Used by hook: 'customize_preview_init'
 */
public static function mytheme_customizer_live_preview()
{
	wp_enqueue_script( 
		  'mytheme-themecustomizer',			//Give the script an ID
		  get_template_directory_uri().'/assets/js/theme-customizer.js',//Point to file
		  array( 'jquery','customize-preview' ),	//Define dependencies
		  '',						//Define a version (optional) 
		  true						//Put script in footer?
	);
}
add_action( 'customize_preview_init', 'mytheme_customizer_live_preview' );

  2. Skip to note 6 content


    Steven Lin


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Example migrated from Codex:

    Example Javascript Handler

    The following is one example of what a Javascript live preview file might look like for a custom implementation of the Theme Customizer…

    The contents of your theme-customizer.js file might look like this:

    /**
 * This file adds some LIVE to the Theme Customizer live preview. To leverage
 * this, set your custom settings to 'postMessage' and then add your handling
 * here. Your javascript should grab settings from customizer controls, and 
 * then make any necessary changes to the page using jQuery.
 */
( function( $ ) {

	// Update the site title in real time...
	wp.customize( 'blogname', function( value ) {
		value.bind( function( newval ) {
			$( '#site-title a' ).html( newval );
		} );
	} );
	
	//Update the site description in real time...
	wp.customize( 'blogdescription', function( value ) {
		value.bind( function( newval ) {
			$( '.site-description' ).html( newval );
		} );
	} );

	//Update site title color in real time...
	wp.customize( 'header_textcolor', function( value ) {
		value.bind( function( newval ) {
			$('#site-title a').css('color', newval );
		} );
	} );

	//Update site background color...
	wp.customize( 'background_color', function( value ) {
		value.bind( function( newval ) {
			$('body').css('background-color', newval );
		} );
	} );
	
	//Update site title color in real time...
	wp.customize( 'mytheme_options[link_textcolor]', function( value ) {
		value.bind( function( newval ) {
			$('a').css('color', newval );
		} );
	} );
	
} )( jQuery );

    As you can see from the example above, a single basic handler looks like this…

    wp.customize( 'YOUR_SETTING_ID', function( value ) {
	value.bind( function( newval ) {
		//Do stuff (newval variable contains your "new" setting data)
	} );
} );

    Note:
    Keep in mind that the above will only work if you have set all referenced SETTINGS to ‘transport‘=>’postMessage‘. By default, WordPress uses ‘transport‘=>’refresh‘ for all settings (including the ones that are built in). You can override those defaults using the customize_register action hook.

  3. Skip to note 7 content


    thejaydip


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    When using the theme customizer’s live preview, this is an example of how to enqueue scripts.

    function wpdocs_enqueue_customize_preview_script() {
	$theme = wp_get_theme();

	wp_register_script(
		'wpdocs-cript',
		get_theme_file_uri( 'js/script.js' ),
		array( 'jquery', 'customize-preview' ),
		$theme->get( 'Version' ),
	);

	wp_enqueue_script( 'wpdocs-script' );
}

add_action( 'customize_preview_init', 'wpdocs_enqueue_customize_preview_script' );