云策 WordPress 开发者社区

类文档

WP_Customize_Image_Control

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

概述

WP_Customize_Image_Control 是 WordPress 自定义器中的一个控件类，用于处理图像上传和选择。它继承自 WP_Customize_Upload_Control，专门用于图像类型的媒体控制。

关键要点

  • WP_Customize_Image_Control 继承自 WP_Customize_Upload_Control，用于在主题自定义器中添加图像控件。
  • 该类存储图像的 URL，而非附件 ID；如需存储附件 ID，应使用 WP_Customize_Media_Control。
  • 多个方法（如 add_tab、prepare_control、print_tab_image、remove_tab）已在 4.1.0 版本中弃用。
  • 相关类包括 WP_Customize_Cropped_Image_Control、WP_Customize_Background_Image_Control 和 WP_Customize_Header_Image_Control。

代码示例

$wp_customize->add_control(
    new WP_Customize_Image_Control(
        $wp_customize,
        'logo',
        array(
            'label'      => __( 'Upload a logo', 'theme_name' ),
            'section'    => 'your_section_id',
            'settings'   => 'your_setting_id',
            'context'    => 'your_setting_context'
        )
    )
);

注意事项

  • 使用 WP_Customize_Image_Control 时，建议结合 sanitize_callback 函数（如 ic_sanitize_image）进行图像验证，以确保文件类型安全。
  • 注意弃用方法，避免在代码中使用，以保持兼容性和最佳实践。
📄 原文内容

Customize Image Control class.

Description

See also

Methods

Name Description
WP_Customize_Image_Control::add_tab — deprecated
WP_Customize_Image_Control::prepare_control — deprecated
WP_Customize_Image_Control::print_tab_image — deprecated
WP_Customize_Image_Control::remove_tab — deprecated

Source

class WP_Customize_Image_Control extends WP_Customize_Upload_Control {
	/**
	 * Control type.
	 *
	 * @since 3.4.0
	 * @var string
	 */
	public $type = 'image';

	/**
	 * Media control mime type.
	 *
	 * @since 4.1.0
	 * @var string
	 */
	public $mime_type = 'image';

	/**
	 * @since 3.4.2
	 * @deprecated 4.1.0
	 */
	public function prepare_control() {}

	/**
	 * @since 3.4.0
	 * @deprecated 4.1.0
	 *
	 * @param string $id
	 * @param string $label
	 * @param mixed  $callback
	 */
	public function add_tab( $id, $label, $callback ) {
		_deprecated_function( __METHOD__, '4.1.0' );
	}

	/**
	 * @since 3.4.0
	 * @deprecated 4.1.0
	 *
	 * @param string $id
	 */
	public function remove_tab( $id ) {
		_deprecated_function( __METHOD__, '4.1.0' );
	}

	/**
	 * @since 3.4.0
	 * @deprecated 4.1.0
	 *
	 * @param string $url
	 * @param string $thumbnail_url
	 */
	public function print_tab_image( $url, $thumbnail_url = null ) {
		_deprecated_function( __METHOD__, '4.1.0' );
	}
}

View all references View on Trac View on GitHub

Uses Description
WP_Customize_Upload_Controlwp-includes/customize/class-wp-customize-upload-control.php

Customize Upload Control Class.
Used by Description
WP_Customize_Cropped_Image_Controlwp-includes/customize/class-wp-customize-cropped-image-control.php

Customize Cropped Image Control class.
WP_Customize_Background_Image_Controlwp-includes/customize/class-wp-customize-background-image-control.php

Customize Background Image Control class.
WP_Customize_Header_Image_Controlwp-includes/customize/class-wp-customize-header-image-control.php

Customize Header Image Control class.

Changelog

Version Description
3.4.0 Introduced.

User Contributed Notes

  2. Skip to note 5 content


    Chetan Satasiya


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

    This class is used with the Theme Customization API to render the custom image control on the Theme Customizer in WordPress 3.4 or newer.

    $wp_customize->add_control(
       new WP_Customize_Image_Control(
           $wp_customize,
           'logo',
           array(
               'label'      => __( 'Upload a logo', 'theme_name' ),
               'section'    => 'your_section_id',
               'settings'   => 'your_setting_id',
               'context'    => 'your_setting_context' 
           )
       )
   );

  3. Skip to note 6 content


    Mehedi Foysal


    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

    $wp_customize->add_setting( 'logo', array(
	'capability'        => 'edit_theme_options',
	'default'           => '',
	'sanitize_callback' => 'ic_sanitize_image',
) );
$wp_customize->add_control( new WP_Customize_Image_Control( $wp_customize, 'logo',
	array(
		'label'    => __( 'Logo', 'text-domain' ),
		'section'  => 'general',
		'settings' => 'logo',
	)
) );

    Callback function

    /**
 * Validation: image
 * Control: text, WP_Customize_Image_Control
 *
 * @uses    wp_check_filetype()        <a href="https://developer.wordpress.org/reference/functions/wp_check_filetype/" rel="ugc">https://developer.wordpress.org/reference/functions/wp_check_filetype/</a>
 * @uses    in_array()                <a href="http://php.net/manual/en/function.in-array.php" rel="nofollow ugc">http://php.net/manual/en/function.in-array.php</a>
 */
function ic_sanitize_image( $file, $setting ) {

	$mimes = array(
		'jpg|jpeg|jpe' => 'image/jpeg',
		'gif'          => 'image/gif',
		'png'          => 'image/png',
		'bmp'          => 'image/bmp',
		'tif|tiff'     => 'image/tiff',
		'ico'          => 'image/x-icon'
	);

	//check file type from file name
	$file_ext = wp_check_filetype( $file, $mimes );

	//if file has a valid mime type return it, otherwise return default
	return ( $file_ext['ext'] ? $file : $setting->default );
}