类文档

WP_Customize_Color_Control

💡 云策文档标注

概述

WP_Customize_Color_Control 是 WordPress 自定义工具中用于颜色选择器的控件类,继承自 WP_Customize_Control,专为颜色设置设计。

关键要点

  • 继承自 WP_Customize_Control,类型为 'color',用于在主题自定义工具中添加颜色选择器。
  • 提供构造函数、脚本/样式加载、JSON 参数传递和 JS 模板渲染等方法。
  • 通过 enqueue 方法自动加载 wp-color-picker 脚本和样式,简化颜色选择器集成。

代码示例

$wp_customize->add_control( 
    new WP_Customize_Color_Control( 
        $wp_customize, 
        'link_color', 
        array(
            'label'      => __( 'Header Color', 'mytheme' ),
            'section'    => 'your_section_id',
            'settings'   => 'your_setting_id',
        ) 
    ) 
);

📄 原文内容

Customize Color Control class.

Description

See also

Methods

Name Description
WP_Customize_Color_Control::__construct Constructor.
WP_Customize_Color_Control::content_template Render a JS template for the content of the color picker control.
WP_Customize_Color_Control::enqueue Enqueue scripts/styles for the color picker.
WP_Customize_Color_Control::render_content Don’t render the control content from PHP, as it’s rendered via JS on load.
WP_Customize_Color_Control::to_json Refresh the parameters passed to the JavaScript via JSON.

Source

class WP_Customize_Color_Control extends WP_Customize_Control {
	/**
	 * Type.
	 *
	 * @var string
	 */
	public $type = 'color';

	/**
	 * Statuses.
	 *
	 * @var array
	 */
	public $statuses;

	/**
	 * Mode.
	 *
	 * @since 4.7.0
	 * @var string
	 */
	public $mode = 'full';

	/**
	 * Constructor.
	 *
	 * @since 3.4.0
	 *
	 * @see WP_Customize_Control::__construct()
	 *
	 * @param WP_Customize_Manager $manager Customizer bootstrap instance.
	 * @param string               $id      Control ID.
	 * @param array                $args    Optional. Arguments to override class property defaults.
	 *                                      See WP_Customize_Control::__construct() for information
	 *                                      on accepted arguments. Default empty array.
	 */
	public function __construct( $manager, $id, $args = array() ) {
		$this->statuses = array( '' => __( 'Default' ) );
		parent::__construct( $manager, $id, $args );
	}

	/**
	 * Enqueue scripts/styles for the color picker.
	 *
	 * @since 3.4.0
	 */
	public function enqueue() {
		wp_enqueue_script( 'wp-color-picker' );
		wp_enqueue_style( 'wp-color-picker' );
	}

	/**
	 * Refresh the parameters passed to the JavaScript via JSON.
	 *
	 * @since 3.4.0
	 * @uses WP_Customize_Control::to_json()
	 */
	public function to_json() {
		parent::to_json();
		$this->json['statuses']     = $this->statuses;
		$this->json['defaultValue'] = $this->setting->default;
		$this->json['mode']         = $this->mode;
	}

	/**
	 * Don't render the control content from PHP, as it's rendered via JS on load.
	 *
	 * @since 3.4.0
	 */
	public function render_content() {}

	/**
	 * Render a JS template for the content of the color picker control.
	 *
	 * @since 4.1.0
	 */
	public function content_template() {
		?>
		<#
		var defaultValue = '#RRGGBB',
			defaultValueAttr = '',
			inputId = _.uniqueId( 'customize-color-control-input-' ),
			isHueSlider = data.mode === 'hue';

		if ( data.defaultValue && _.isString( data.defaultValue ) && ! isHueSlider ) {
			if ( '#' !== data.defaultValue.substring( 0, 1 ) ) {
				defaultValue = '#' + data.defaultValue;
			} else {
				defaultValue = data.defaultValue;
			}
			defaultValueAttr = ' data-default-color=' + defaultValue; // Quotes added automatically.
		}
		#>
		<# if ( data.label ) { #>
			<span class="customize-control-title">{{{ data.label }}}</span>
		<# } #>
		<# if ( data.description ) { #>
			<span class="description customize-control-description">{{{ data.description }}}</span>
		<# } #>
		<div class="customize-control-content">
			<label for="{{ inputId }}"><span class="screen-reader-text">{{{ data.label }}}</span></label>
			<# if ( isHueSlider ) { #>
				<input id="{{ inputId }}" class="color-picker-hue" type="number" min="1" max="359" data-type="hue" />
			<# } else { #>
				<input id="{{ inputId }}" class="color-picker-hex" type="text" maxlength="7" placeholder="{{ defaultValue }}" {{ defaultValueAttr }} />
			<# } #>
		</div>
		</pre><p class="wporg-dot-link-list"><a href="https://developer.wordpress.org/reference/files/wp-includes/customize/class-wp-customize-color-control.php/">View all references</a> <a href="https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/customize/class-wp-customize-color-control.php#L17">View on Trac</a> <a href="https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/customize/class-wp-customize-color-control.php#L17-L126">View on GitHub</a></p></section>
		
		<section class="wp-block-wporg-code-reference-related" data-nosnippet="true"><h2 id="related" class="is-toc-heading wp-block-heading has-heading-5-font-size" tabindex="-1" ><a href="#related">Related</a></h2> <section style="margin-top:var(--wp--preset--spacing--20)" class="wp-block-wporg-code-table" id="uses"><figure class="wp-block-table "><table><thead><tr><th scope="col">Uses</th><th scope="col">Description</th></tr></thead><tbody><tr class=""><td><a href="https://developer.wordpress.org/reference/classes/wp_customize_control/">WP_Customize_Control</a><code>wp-includes/class-wp-customize-control.php</code></td><td></td></tr></tbody></table></figure></section>  </section>
		<section class="wp-block-wporg-code-reference-changelog"><h2 id="changelog" class="is-toc-heading wp-block-heading has-heading-5-font-size" tabindex="-1" ><a href="#changelog">Changelog</a></h2> <section style="margin-top:var(--wp--preset--spacing--20)" class="wp-block-wporg-code-table"><figure class="wp-block-table "><table><thead><tr><th scope="col">Version</th><th scope="col">Description</th></tr></thead><tbody><tr class=""><td><a href="https://developer.wordpress.org/reference/since/3.4.0/">3.4.0</a></td><td>Introduced.</td></tr></tbody></table></figure></section> </section>
		<section class="wp-block-wporg-code-reference-comments" data-nosnippet="true"><h2 id="user-contributed-notes" class="is-toc-heading wp-block-heading" tabindex="-1" ><a href="#user-contributed-notes">User Contributed Notes</a></h2> <ol class="comment-list">			<li id="comment-2034" data-comment-id="2034" class="comment byuser comment-author-ketuchetan even thread-even depth-1">
			<article id="div-comment-2034" class="comment-body">

							<a href="#comment-content-2034" class="screen-reader-text">Skip to note 3 content</a>
				<header class="comment-meta">
					<div class="comment-author vcard">
						<span class="comment-author-attribution">
						<a href="https://profiles.wordpress.org/ketuchetan/" rel="external nofollow" class="url">Chetan Satasiya</a>						</span>
						<a class="comment-date" href="https://developer.wordpress.org/reference/classes/wp_customize_color_control/#comment-2034">
							<time datetime="2017-01-03T07:55:51+00:00">
							9 years ago							</time>
						</a>

																													</div>
					<div class="user-note-voting" data-nonce="293e2f0841" data-can-vote="false"><a class="user-note-voting-up" title="You must log in to vote on the helpfulness of this note" data-id="2034" data-vote="up" href="https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Fclasses%2Fwp_customize_color_control%2F%23comment-2034"><span class="screen-reader-text">You must log in to vote on the helpfulness of this note</span></a><span class="user-note-voting-count " title=""><span class="screen-reader-text">Vote results for this note: </span>0</span><a class="user-note-voting-down" title="You must log in to vote on the helpfulness of this note" data-id="2034" data-vote="down" href="https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Fclasses%2Fwp_customize_color_control%2F%23comment-2034"><span class="screen-reader-text">You must log in to vote on the helpfulness of this note</span></a></div>				</header>
				<!-- .comment-metadata -->
			
				<div class="wporg-has-embedded-code comment-content" id="comment-content-2034">
				<p>This class is used with the Theme Customization API to render the custom color selector control on the Theme Customizer in WordPress 3.4 or newer.</p>
<pre class="wp-block-code"><code lang="php" class="language-php line-numbers">$wp_customize->add_control( 
	new WP_Customize_Color_Control( 
	$wp_customize, 
	'link_color', 
	array(
		'label'      => __( 'Header Color', 'mytheme' ),
		'section'    => 'your_section_id',
		'settings'   => 'your_setting_id',
	) ) 
);

  • Skip to note 4 content

    $wp_customize->add_setting( 'button_color', array(
    	'capability'        => 'edit_theme_options',
    	'default'           => '',
    ) );
    $wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'button_color',
    	array(
    		'label'    => __( 'Button Color', 'text-domain' ),
    		'section'  => 'color_settings',
    		'settings' => 'button_color',
    	)
    ));