云策 WordPress 开发者社区

函数文档

get_theme_mod()

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

概述

get_theme_mod() 函数用于检索活动主题的主题修改值，支持默认值处理和动态过滤器应用。当修改名称不存在且默认值为字符串时，会通过 sprintf() 函数处理模板和样式表目录 URI。

关键要点

  • 函数签名：get_theme_mod( $name, $default_value = false )，其中 $name 为必需的主题修改名称，$default_value 为可选的默认值。
  • 返回值：返回主题修改值，类型为 mixed。
  • 动态过滤器：通过 apply_filters( "theme_mod_{$name}", $mods[ $name ] ) 应用过滤器，允许开发者自定义修改值。
  • 默认值处理：如果 $default_value 是字符串且包含 sprintf() 格式模式，会替换 %s 为模板目录 URI 和样式表目录 URI。
  • 相关函数：包括 get_theme_mods()、get_template_directory_uri()、get_stylesheet_directory_uri() 和 apply_filters()。

代码示例

// 示例：调用自定义背景颜色作为页脚边框
.footer {
    border-top: solid 1px #;
}

注意事项

  • 必须使用适当的转义钩子对 get_theme_mod() 返回值进行转义，以确保安全性。
  • 函数自 WordPress 2.1.0 版本引入，广泛用于主题定制器相关功能。
📄 原文内容

Retrieves theme modification value for the active theme.

Description

If the modification name does not exist and $default_value is a string, then the default will be passed through the sprintf() PHP function with the template directory URI as the first value and the stylesheet directory URI as the second value.

Parameters

$namestringrequired
Theme modification name.
$default_valuemixedoptional
Theme modification default value.

Default:false

Return

mixed Theme modification value.

Source

function get_theme_mod( $name, $default_value = false ) {
	$mods = get_theme_mods();

	if ( isset( $mods[ $name ] ) ) {
		/**
		 * Filters the theme modification, or 'theme_mod', value.
		 *
		 * The dynamic portion of the hook name, `$name`, refers to the key name
		 * of the modification array. For example, 'header_textcolor', 'header_image',
		 * and so on depending on the theme options.
		 *
		 * @since 2.2.0
		 *
		 * @param mixed $current_mod The value of the active theme modification.
		 */
		return apply_filters( "theme_mod_{$name}", $mods[ $name ] );
	}

	if ( is_string( $default_value ) ) {
		// Only run the replacement if an sprintf() string format pattern was found.
		if ( preg_match( '#(?<!--%)%(?:d+$?)?s#', $default_value ) ) {
			// Remove a single trailing percent sign.
			$default_value = preg_replace( '#(?<!%)%$#', '', $default_value );
			$default_value = sprintf( $default_value, get_template_directory_uri(), get_stylesheet_directory_uri() );
		}
	}

	/** This filter is documented in wp-includes/theme.php */
	return apply_filters( "theme_mod_{$name}", $default_value );
}
</code--></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#L1067">View on Trac</a> <a href="https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/theme.php#L1067-L1096">View on GitHub</a></p></section>
		<section class="wp-block-wporg-code-reference-hooks"><h2 id="hooks" class="is-toc-heading wp-block-heading has-heading-5-font-size" tabindex="-1" ><a href="#hooks">Hooks</a></h2> <dl><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/theme_mod_name/"><span class="hook-func">apply_filters</span>( “theme_mod_{$name}”,  <nobr><span class="arg-type">mixed</span> <span class="arg-name">$current_mod</span></nobr> )</a></dt><dd><p>Filters the theme modification, or ‘theme_mod’, value.</p>
</dd></dl></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/get_theme_mods/">get_theme_mods()</a><code>wp-includes/theme.php</code></td><td><p>Retrieves all theme modifications.</p>
</td></tr><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/get_template_directory_uri/">get_template_directory_uri()</a><code>wp-includes/theme.php</code></td><td><p>Retrieves template directory URI for the active theme.</p>
</td></tr><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/get_stylesheet_directory_uri/">get_stylesheet_directory_uri()</a><code>wp-includes/theme.php</code></td><td><p>Retrieves stylesheet directory URI for the active theme.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/apply_filters/">apply_filters()</a><code>wp-includes/plugin.php</code></td><td><p>Calls the callback functions that have been added to a filter hook.</p>
</td></tr></tbody></table></figure><a class="wp-block-wporg-code-table-show-more" href="#">Show 1 more</a><a class="wp-block-wporg-code-table-show-less" href="#">Show less</a></section>  <section style="margin-top:var(--wp--preset--spacing--20)" class="wp-block-wporg-code-table" id="used-by"><figure class="wp-block-table "><table><thead><tr><th scope="col">Used by</th><th scope="col">Description</th></tr></thead><tbody><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/_wp_block_theme_register_classic_sidebars/">_wp_block_theme_register_classic_sidebars()</a><code>wp-includes/widgets.php</code></td><td><p>Registers the previous theme’s sidebars for the block themes.</p>
</td></tr><tr class=""><td><a href="https://developer.wordpress.org/reference/classes/wp_rest_server/add_site_logo_to_index/">WP_REST_Server::add_site_logo_to_index()</a><code>wp-includes/rest-api/class-wp-rest-server.php</code></td><td><p>Exposes the site logo through the WordPress REST API.</p>
</td></tr><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/get_media_states/">get_media_states()</a><code>wp-admin/includes/template.php</code></td><td><p>Retrieves an array of media states from an attachment.</p>
</td></tr><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/wp_map_sidebars_widgets/">wp_map_sidebars_widgets()</a><code>wp-includes/widgets.php</code></td><td><p>Compares a list of sidebars with their widgets against an allowed list.</p>
</td></tr><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/wp_get_custom_css_post/">wp_get_custom_css_post()</a><code>wp-includes/theme.php</code></td><td><p>Fetches the <code>custom_css</code> post for a given theme.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/get_header_video_url/">get_header_video_url()</a><code>wp-includes/theme.php</code></td><td><p>Retrieves header video URL for custom header.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/_custom_logo_header_styles/">_custom_logo_header_styles()</a><code>wp-includes/theme.php</code></td><td><p>Adds CSS to hide header text for custom logo, based on Customizer setting.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/has_custom_logo/">has_custom_logo()</a><code>wp-includes/general-template.php</code></td><td><p>Determines whether the site has a custom logo.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/get_custom_logo/">get_custom_logo()</a><code>wp-includes/general-template.php</code></td><td><p>Returns a custom logo, linked to home unless the theme supports removing the link on the home page.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/classes/wp_customize_setting/get_root_value/">WP_Customize_Setting::get_root_value()</a><code>wp-includes/class-wp-customize-setting.php</code></td><td><p>Get the root value for a setting, especially for multidimensional ones.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/classes/custom_image_header/show_header_selector/">Custom_Image_Header::show_header_selector()</a><code>wp-admin/includes/class-custom-image-header.php</code></td><td><p>Displays UI for selecting one of several default headers.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/classes/custom_background/admin_page/">Custom_Background::admin_page()</a><code>wp-admin/includes/class-custom-background.php</code></td><td><p>Displays the custom background page.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/get_background_color/">get_background_color()</a><code>wp-includes/theme.php</code></td><td><p>Retrieves value for custom background color.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/_custom_background_cb/">_custom_background_cb()</a><code>wp-includes/theme.php</code></td><td><p>Default custom background callback.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/_delete_attachment_theme_mod/">_delete_attachment_theme_mod()</a><code>wp-includes/theme.php</code></td><td><p>Checks an attachment being deleted to see if it’s a header or background image.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/get_header_textcolor/">get_header_textcolor()</a><code>wp-includes/theme.php</code></td><td><p>Retrieves the custom header text color in 3- or 6-digit hexadecimal form.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/display_header_text/">display_header_text()</a><code>wp-includes/theme.php</code></td><td><p>Whether to display the header text.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/get_header_image/">get_header_image()</a><code>wp-includes/theme.php</code></td><td><p>Retrieves header image for custom header.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/_get_random_header_data/">_get_random_header_data()</a><code>wp-includes/theme.php</code></td><td><p>Gets random header image data from registered images in theme.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/is_random_header_image/">is_random_header_image()</a><code>wp-includes/theme.php</code></td><td><p>Checks if random header image is in use.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/get_custom_header/">get_custom_header()</a><code>wp-includes/theme.php</code></td><td><p>Gets the header image data.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/get_background_image/">get_background_image()</a><code>wp-includes/theme.php</code></td><td><p>Retrieves background image for custom background.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/switch_theme/">switch_theme()</a><code>wp-includes/theme.php</code></td><td><p>Switches the theme.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/get_nav_menu_locations/">get_nav_menu_locations()</a><code>wp-includes/nav-menu.php</code></td><td><p>Retrieves all registered navigation menu locations and the menus assigned to them.</p>
</td></tr><tr class="wporg-hidden"><td><a href="https://developer.wordpress.org/reference/functions/retrieve_widgets/">retrieve_widgets()</a><code>wp-includes/widgets.php</code></td><td><p>Validates and remaps any “orphaned” widgets to wp_inactive_widgets sidebar, and saves the widget settings. This has to run at least on each theme change.</p>
</td></tr></tbody></table></figure><a class="wp-block-wporg-code-table-show-more" href="#">Show 20 more</a><a class="wp-block-wporg-code-table-show-less" href="#">Show less</a></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/2.1.0/">2.1.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-682" data-comment-id="682" class="comment byuser comment-author-codex odd alt thread-odd thread-alt depth-1">
			<article id="div-comment-682" class="comment-body">

							<a href="#comment-content-682" class="screen-reader-text">Skip to note 4 content</a>
				<header class="comment-meta">
					<div class="comment-author vcard">
						<span class="comment-author-attribution">
						<a href="https://profiles.wordpress.org/codex/" rel="external nofollow" class="url">Codex</a>						</span>
						<a class="comment-date" href="https://developer.wordpress.org/reference/functions/get_theme_mod/#comment-682">
							<time datetime="2015-07-10T09:33:58+00:00">
							11 years ago							</time>
						</a>

																													</div>
					<div class="user-note-voting" data-nonce="7a16d0a8d4" 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="682" data-vote="up" href="https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_theme_mod%2F%23comment-682"><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="88% like this"><span class="screen-reader-text">Vote results for this note: </span>6</span><a class="user-note-voting-down" title="You must log in to vote on the helpfulness of this note" data-id="682" data-vote="down" href="https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_theme_mod%2F%23comment-682"><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-682">
				<p><strong>Calling the custom background color</strong><br />
This example could be used to add the custom background color as a border on the top of the footer. It would be css inserted in the header:</p>
<pre class="wp-block-code"><code lang="php" class="language-php ">.footer {
     border-top: solid 1px #;
}

  • Skip to note 5 content


    bdthemes


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

    Calling Background color with a default value
    Sometimes you need to set default value for avoid any bad situation. This example could be used to add the custom background color as a border on the top of the footer with default color white. It would be css inserted in the header:

    .footer {
     border-top: solid 1px #;
}