云策 WordPress 开发者社区

函数文档

_custom_background_cb()

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

概述

_custom_background_cb() 是 WordPress 中用于处理自定义背景输出的默认回调函数。它根据主题设置生成背景样式，包括颜色、图像、位置、大小、重复和滚动属性，并确保在自定义器预览中正确显示。

关键要点

  • 函数获取自定义背景图像和颜色，使用 set_url_scheme() 和 get_background_image() 处理图像 URL，get_background_color() 获取颜色值。
  • 如果颜色与默认值相同，则设置为 false 以避免输出冗余样式。
  • 根据主题支持（如 HTML5）动态生成 style 标签的 type 属性。
  • 当无背景图像和颜色时，在自定义器预览中输出空样式标签，否则返回。
  • 背景图像处理包括位置（background_position_x/y）、大小（background_size）、重复（background_repeat）和滚动（background_attachment）属性，使用 get_theme_mod() 获取设置，并验证值有效性。
  • 使用 sanitize_url() 和 maybe_hash_hex_color() 确保数据安全性和格式正确。
  • 函数输出内联 CSS 样式，适用于主题开发中的自定义背景功能集成。

代码示例

// 示例：_custom_background_cb() 的核心逻辑片段
$background = set_url_scheme( get_background_image() );
$color = get_background_color();
if ( get_theme_support( 'custom-background', 'default-color' ) === $color ) {
    $color = false;
}
$style = $color ? 'background-color: ' . maybe_hash_hex_color( $color ) . ';' : '';
if ( $background ) {
    $image = ' background-image: url("' . sanitize_url( $background ) . '");';
    // 处理位置、大小、重复、滚动等属性
    $style .= $image . $position . $size . $repeat . $attachment;
}

注意事项

  • 此函数是内部回调，通常由 add_theme_support('custom-background') 自动调用，开发者无需直接使用。
  • 确保主题在 style.css 中定义了默认背景颜色，否则可能影响输出逻辑。
  • 在自定义器预览模式下，即使无背景设置也会输出空样式标签以保持预览一致性。
  • 函数依赖于多个 WordPress 核心函数（如 get_theme_mod、current_theme_supports），需确保主题正确支持相关功能。
📄 原文内容

Default custom background callback.

Source

function _custom_background_cb() {

	// $background is the saved custom image, or the default image.

	$background = set_url_scheme( get_background_image() );


	/*

	 * $color is the saved custom color.

	 * A default has to be specified in style.css. It will not be printed here.

	 */

	$color = get_background_color();


	if ( get_theme_support( 'custom-background', 'default-color' ) === $color ) {

		$color = false;

	}


	$type_attr = current_theme_supports( 'html5', 'style' ) ? '' : ' type="text/css"';


	if ( ! $background && ! $color ) {

		if ( is_customize_preview() ) {

			printf( '<style%s id="custom-background-css"></style>', $type_attr );

		}

		return;

	}


	$style = $color ? 'background-color: ' . maybe_hash_hex_color( $color ) . ';' : '';


	if ( $background ) {

		$image = ' background-image: url("' . sanitize_url( $background ) . '");';


		// Background Position.

		$position_x = get_theme_mod( 'background_position_x', get_theme_support( 'custom-background', 'default-position-x' ) );

		$position_y = get_theme_mod( 'background_position_y', get_theme_support( 'custom-background', 'default-position-y' ) );


		if ( ! in_array( $position_x, array( 'left', 'center', 'right' ), true ) ) {

			$position_x = 'left';

		}


		if ( ! in_array( $position_y, array( 'top', 'center', 'bottom' ), true ) ) {

			$position_y = 'top';

		}


		$position = " background-position: $position_x $position_y;";


		// Background Size.

		$size = get_theme_mod( 'background_size', get_theme_support( 'custom-background', 'default-size' ) );


		if ( ! in_array( $size, array( 'auto', 'contain', 'cover' ), true ) ) {

			$size = 'auto';

		}


		$size = " background-size: $size;";


		// Background Repeat.

		$repeat = get_theme_mod( 'background_repeat', get_theme_support( 'custom-background', 'default-repeat' ) );


		if ( ! in_array( $repeat, array( 'repeat-x', 'repeat-y', 'repeat', 'no-repeat' ), true ) ) {

			$repeat = 'repeat';

		}


		$repeat = " background-repeat: $repeat;";


		// Background Scroll.

		$attachment = get_theme_mod( 'background_attachment', get_theme_support( 'custom-background', 'default-attachment' ) );


		if ( 'fixed' !== $attachment ) {

			$attachment = 'scroll';

		}


		$attachment = " background-attachment: $attachment;";


		$style .= $image . $position . $size . $repeat . $attachment;

	}

	?>

<style<?php echo $type_attr; ?> id="custom-background-css">

body.custom-background {  }

</style>

	</pre><p class="wporg-dot-link-list"><a href="https://developer.wordpress.org/reference/files/wp-includes/theme.php/">View all references</a> <a href="https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/theme.php#L1885">View on Trac</a> <a href="https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/theme.php#L1885-L1961">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/functions/is_customize_preview/">is_customize_preview()</a><code>wp-includes/theme.php


Whether the site is being previewed in the Customizer.




maybe_hash_hex_color()wp-includes/formatting.php


Ensures that any hex color is properly hashed.




get_background_color()wp-includes/theme.php


Retrieves value for custom background color.




get_theme_support()wp-includes/theme.php


Gets the theme support arguments passed when registering that support.




get_background_image()wp-includes/theme.php


Retrieves background image for custom background.




get_theme_mod()wp-includes/theme.php


Retrieves theme modification value for the active theme.




set_url_scheme()wp-includes/link-template.php


Sets the scheme for a URL.




current_theme_supports()wp-includes/theme.php


Checks a theme’s support for a given feature.




sanitize_url()wp-includes/formatting.php


Sanitizes a URL for database or redirect usage.







Show 4 moreShow less

Changelog

Version Description
3.0.0 Introduced.