云策 WordPress 开发者社区

类文档

WP_Customize_Theme_Control

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

概述

WP_Customize_Theme_Control 是 WordPress 自定义器中的一个控件类，用于在主题选择界面中显示和管理主题。它继承自 WP_Customize_Control，主要通过 JavaScript 渲染内容，支持主题的预览、激活和安装操作。

关键要点

  • WP_Customize_Theme_Control 继承自 WP_Customize_Control，类型为 'theme'，用于自定义器中的主题控制。
  • 控件包含一个 WP_Theme 对象属性，用于存储主题信息，并通过 to_json() 方法将主题数据传递给 JavaScript。
  • render_content() 方法为空，因为控件内容通过 JavaScript 在加载时渲染，避免 PHP 直接渲染。
  • content_template() 方法提供 JavaScript 模板，用于动态显示主题详情、自定义、预览和安装按钮，支持多语言翻译。
  • 控件处理主题状态（如激活、更新需求），并显示相关通知，例如 WordPress 或 PHP 更新提示。

代码示例

class WP_Customize_Theme_Control extends WP_Customize_Control {
    public $type = 'theme';
    public $theme;

    public function to_json() {
        parent::to_json();
        $this->json['theme'] = $this->theme;
    }

    public function render_content() {}

    public function content_template() {
        $details_label = sprintf( __( 'Details for theme: %s' ), '{{ data.theme.name }}' );
        $customize_label = sprintf( __( 'Customize theme: %s' ), '{{ data.theme.name }}' );
        $preview_label = sprintf( __( 'Live preview theme: %s' ), '{{ data.theme.name }}' );
        $install_label = sprintf( __( 'Install and preview theme: %s' ), '{{ data.theme.name }}' );
        // 模板代码省略，包含主题显示和操作逻辑
    }
}

注意事项

  • 此控件自 WordPress 4.2.0 版本引入，主要用于自定义器界面，开发者需熟悉 WP_Customize_Control 基类。
  • 由于内容通过 JavaScript 渲染，开发时应确保主题数据正确传递到前端，并处理多语言字符串翻译。
  • 控件包含复杂的条件逻辑（如更新检查），在自定义或扩展时需注意兼容性和用户权限处理。
📄 原文内容

Customize Theme Control class.

Description

See also

Methods

NameDescription
WP_Customize_Theme_Control::content_templateRender a JS template for theme display.
WP_Customize_Theme_Control::render_contentDon’t render the control content from PHP, as it’s rendered via JS on load.
WP_Customize_Theme_Control::to_jsonRefresh the parameters passed to the JavaScript via JSON.

Source

class WP_Customize_Theme_Control extends WP_Customize_Control {

	/**
	 * Customize control type.
	 *
	 * @since 4.2.0
	 * @var string
	 */
	public $type = 'theme';

	/**
	 * Theme object.
	 *
	 * @since 4.2.0
	 * @var WP_Theme
	 */
	public $theme;

	/**
	 * Refresh the parameters passed to the JavaScript via JSON.
	 *
	 * @since 4.2.0
	 *
	 * @see WP_Customize_Control::to_json()
	 */
	public function to_json() {
		parent::to_json();
		$this->json['theme'] = $this->theme;
	}

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

	/**
	 * Render a JS template for theme display.
	 *
	 * @since 4.2.0
	 */
	public function content_template() {
		/* translators: %s: Theme name. */
		$details_label = sprintf( __( 'Details for theme: %s' ), '{{ data.theme.name }}' );
		/* translators: %s: Theme name. */
		$customize_label = sprintf( __( 'Customize theme: %s' ), '{{ data.theme.name }}' );
		/* translators: %s: Theme name. */
		$preview_label = sprintf( __( 'Live preview theme: %s' ), '{{ data.theme.name }}' );
		/* translators: %s: Theme name. */
		$install_label = sprintf( __( 'Install and preview theme: %s' ), '{{ data.theme.name }}' );
		?>
		<# if ( data.theme.active ) { #>
			<div class="theme active" tabindex="0" aria-describedby="{{ data.section }}-{{ data.theme.id }}-action">
		<# } else { #>
			<div class="theme" tabindex="0" aria-describedby="{{ data.section }}-{{ data.theme.id }}-action">
		<# } #>

			<# if ( data.theme.screenshot && data.theme.screenshot[0] ) { #>
				<div class="theme-screenshot">
					<img data-src="{{ data.theme.screenshot[0] }}?ver={{ data.theme.version }}" alt="" />
				</div>
			<# } else { #>
				<div class="theme-screenshot blank"></div>
			<# } #>

			<span class="more-details theme-details" id="{{ data.section }}-{{ data.theme.id }}-action" aria-label="<?php echo esc_attr( $details_label ); ?>"></span>

			<div class="theme-author">
			
			</div>

			<# if ( 'installed' === data.theme.type && data.theme.hasUpdate ) { #>
				<# if ( data.theme.updateResponse.compatibleWP && data.theme.updateResponse.compatiblePHP ) { #>
					<div class="update-message notice inline notice-warning notice-alt" data-slug="{{ data.theme.id }}">
						<p>
							' . __( 'Update now' ) . '</button>'
								);
							}
							?>
						</p>
					</div>
				<# } else { #>
					<div class="update-message notice inline notice-error notice-alt" data-slug="{{ data.theme.id }}">
						<p>
							<# if ( ! data.theme.updateResponse.compatibleWP && ! data.theme.updateResponse.compatiblePHP ) { #>
								Please update WordPress</a>, and then <a href="%2$s">learn more about updating PHP</a>.' ),
										self_admin_url( 'update-core.php' ),
										esc_url( wp_get_update_php_url() )
									);
									wp_update_php_annotation( '</p><p><em>', '</em>' );
								} elseif ( current_user_can( 'update_core' ) ) {
									printf(
										/* translators: %s: URL to WordPress Updates screen. */
										' ' . __( '<a href="%s">Please update WordPress</a>.' ),
										self_admin_url( 'update-core.php' )
									);
								} elseif ( current_user_can( 'update_php' ) ) {
									printf(
										/* translators: %s: URL to Update PHP page. */
										' ' . __( '<a href="%s">Learn more about updating PHP</a>.' ),
										esc_url( wp_get_update_php_url() )
									);
									wp_update_php_annotation( '</p><p><em>', '</em>' );
								}
								?>
							<# } else if ( ! data.theme.updateResponse.compatibleWP ) { #>
								Please update WordPress</a>.' ),
										self_admin_url( 'update-core.php' )
									);
								}
								?>
							<# } else if ( ! data.theme.updateResponse.compatiblePHP ) { #>
								Learn more about updating PHP</a>.' ),
										esc_url( wp_get_update_php_url() )
									);
									wp_update_php_annotation( '</p><p><em>', '</em>' );
								}
								?>
							<# } #>
						</p>
					</div>
				<# } #>
			<# } #>

			<# if ( ! data.theme.compatibleWP || ! data.theme.compatiblePHP ) { #>
				<div class="notice notice-error notice-alt"><p>
					<# if ( ! data.theme.compatibleWP && ! data.theme.compatiblePHP ) { #>
						Please update WordPress</a>, and then <a href="%2$s">learn more about updating PHP</a>.' ),
								self_admin_url( 'update-core.php' ),
								esc_url( wp_get_update_php_url() )
							);
							wp_update_php_annotation( '</p><p><em>', '</em>' );
						} elseif ( current_user_can( 'update_core' ) ) {
							printf(
								/* translators: %s: URL to WordPress Updates screen. */
								' ' . __( '<a href="%s">Please update WordPress</a>.' ),
								self_admin_url( 'update-core.php' )
							);
						} elseif ( current_user_can( 'update_php' ) ) {
							printf(
								/* translators: %s: URL to Update PHP page. */
								' ' . __( '<a href="%s">Learn more about updating PHP</a>.' ),
								esc_url( wp_get_update_php_url() )
							);
							wp_update_php_annotation( '</p><p><em>', '</em>' );
						}
						?>
					<# } else if ( ! data.theme.compatibleWP ) { #>
						Please update WordPress</a>.' ),
								self_admin_url( 'update-core.php' )
							);
						}
						?>
					<# } else if ( ! data.theme.compatiblePHP ) { #>
						Learn more about updating PHP</a>.' ),
								esc_url( wp_get_update_php_url() )
							);
							wp_update_php_annotation( '</p><p><em>', '</em>' );
						}
						?>
					<# } #>
				</p></div>
			<# } #>

			<# if ( data.theme.active ) { #>
				<div class="theme-id-container">
					<h3 class="theme-name" id="{{ data.section }}-{{ data.theme.id }}-name">
						<span></span> {{ data.theme.name }}
					</h3>
					<div class="theme-actions">
						<button type="button" class="button button-primary customize-theme" aria-label="<?php echo esc_attr( $customize_label ); ?>"></button>
					</div>
				</div>
				 'success',
						'additional_classes' => array( 'notice-alt' ),
					)
				);
				?>
			<# } else if ( 'installed' === data.theme.type ) { #>
				<# if ( data.theme.blockTheme ) { #>
					<div class="theme-id-container">
						<h3 class="theme-name" id="{{ data.section }}-{{ data.theme.id }}-name">{{ data.theme.name }}</h3>
						<div class="theme-actions">
							<# if ( data.theme.actions.activate ) { #>
								
								<a href="{{{ data.theme.actions.activate }}}" class="button button-primary activate" aria-label="<?php echo esc_attr( $aria_label ); ?>"></a>
							<# } #>
						</div>
					</div>
					
					<# if ( data.theme.actions.activate ) { #>
						activate this theme</a>, and use the Site Editor to customize it.' ),
								'{{{ data.theme.actions.activate }}}'
							);
						?>
					<# } #>

					 'error',
							'additional_classes' => array( 'notice-alt' ),
						)
					);
					?>
				<# } else { #>
					<div class="theme-id-container">
						<h3 class="theme-name" id="{{ data.section }}-{{ data.theme.id }}-name">{{ data.theme.name }}</h3>
						<div class="theme-actions">
							<# if ( data.theme.compatibleWP && data.theme.compatiblePHP ) { #>
								<button type="button" class="button button-primary preview-theme" aria-label="<?php echo esc_attr( $preview_label ); ?>" data-slug="{{ data.theme.id }}"></button>
							<# } else { #>
								<button type="button" class="button button-primary disabled" aria-label="<?php echo esc_attr( $preview_label ); ?>"></button>
							<# } #>
						</div>
					</div>
					 'success',
							'additional_classes' => array( 'notice-alt' ),
						)
					);
					?>
				<# } #>
			<# } else { #>
				<div class="theme-id-container">
					<h3 class="theme-name" id="{{ data.section }}-{{ data.theme.id }}-name">{{ data.theme.name }}</h3>
					<div class="theme-actions">
						<# if ( data.theme.compatibleWP && data.theme.compatiblePHP ) { #>
							<button type="button" class="button button-primary theme-install preview" aria-label="<?php echo esc_attr( $install_label ); ?>" data-slug="{{ data.theme.id }}" data-name="{{ data.theme.name }}"></button>
						<# } else { #>
							<button type="button" class="button button-primary disabled" aria-label="<?php echo esc_attr( $install_label ); ?>" disabled></button>
						<# } #>
					</div>
				</div>
			<# } #>
		</div>
		</pre><p class="wporg-dot-link-list"><a href="https://developer.wordpress.org/reference/files/wp-includes/customize/class-wp-customize-theme-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-theme-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-theme-control.php#L17-L322">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

Changelog

VersionDescription
4.2.0Introduced.

User Contributed Notes

You must log in before being able to contribute a note or feedback.