函数文档

switch_theme()

💡 云策文档标注

概述

switch_theme() 是 WordPress 中用于切换主题的核心函数,接受主题的样式表名称作为参数,并支持向后兼容的双参数签名。该函数执行主题切换的完整流程,包括验证主题要求、处理小工具和菜单位置、更新数据库选项以及触发相关钩子。

关键要点

  • 函数接受一个必需参数 $stylesheet(样式表名称),也支持双参数 $template 和 $stylesheet 以保持向后兼容。
  • 切换主题时,会验证主题要求(如 WordPress 和 PHP 版本),若失败则终止执行。
  • 处理小工具数据:在 Customizer 保存或现有小工具数组时,保存到主题修改中。
  • 更新数据库选项:包括 template、stylesheet、current_theme 等,并处理多主题目录情况。
  • 迁移旧版主题修改选项到新格式,并管理主题修改的自动加载设置。
  • 支持块主题:存储经典侧边栏数据供块主题使用。
  • 触发 switch_theme 动作钩子,传递新主题名称和 WP_Theme 对象。
  • 清理模板全局变量和模式缓存,确保新主题正确加载。

代码示例

// 切换到指定样式表名称的主题
switch_theme( 'twentytwentyfour' );

// 向后兼容的双参数用法
switch_theme( 'twentytwentyfour', 'twentytwentyfour' );

注意事项

  • 函数内部使用 wp_die() 处理验证错误,需确保在适当上下文中调用以避免意外终止。
  • 在 Customizer 保存操作中,会移除 sidebars_widgets 主题修改以防止覆盖小工具更改。
  • 多站点环境下,若未切换博客,会重置模板全局变量以确保新主题模板加载。
  • 切换主题后,旧主题的 theme_mods 选项设置为 autoload=no,新主题设置为 autoload=yes 以优化性能。

📄 原文内容

Switches the theme.

Description

Accepts one argument: $stylesheet of the theme. It also accepts an additional function signature of two arguments: $template then $stylesheet. This is for backward compatibility.

Parameters

$stylesheetstringrequired
Stylesheet name.

Source

function switch_theme( $stylesheet ) {
	global $wp_theme_directories, $wp_customize, $sidebars_widgets, $wp_registered_sidebars;

	$requirements = validate_theme_requirements( $stylesheet );
	if ( is_wp_error( $requirements ) ) {
		wp_die( $requirements );
	}

	$_sidebars_widgets = null;
	if ( 'wp_ajax_customize_save' === current_action() ) {
		$old_sidebars_widgets_data_setting = $wp_customize->get_setting( 'old_sidebars_widgets_data' );
		if ( $old_sidebars_widgets_data_setting ) {
			$_sidebars_widgets = $wp_customize->post_value( $old_sidebars_widgets_data_setting );
		}
	} elseif ( is_array( $sidebars_widgets ) ) {
		$_sidebars_widgets = $sidebars_widgets;
	}

	if ( is_array( $_sidebars_widgets ) ) {
		set_theme_mod(
			'sidebars_widgets',
			array(
				'time' => time(),
				'data' => $_sidebars_widgets,
			)
		);
	}

	$nav_menu_locations = get_theme_mod( 'nav_menu_locations' );
	update_option( 'theme_switch_menu_locations', $nav_menu_locations, true );

	if ( func_num_args() > 1 ) {
		$stylesheet = func_get_arg( 1 );
	}

	$old_theme = wp_get_theme();
	$new_theme = wp_get_theme( $stylesheet );
	$template  = $new_theme->get_template();

	if ( wp_is_recovery_mode() ) {
		$paused_themes = wp_paused_themes();
		$paused_themes->delete( $old_theme->get_stylesheet() );
		$paused_themes->delete( $old_theme->get_template() );
	}

	update_option( 'template', $template );
	update_option( 'stylesheet', $stylesheet );

	if ( count( $wp_theme_directories ) > 1 ) {
		update_option( 'template_root', get_raw_theme_root( $template, true ) );
		update_option( 'stylesheet_root', get_raw_theme_root( $stylesheet, true ) );
	} else {
		delete_option( 'template_root' );
		delete_option( 'stylesheet_root' );
	}

	$new_name = $new_theme->get( 'Name' );

	update_option( 'current_theme', $new_name );

	// Migrate from the old mods_{name} option to theme_mods_{slug}.
	if ( is_admin() && false === get_option( 'theme_mods_' . $stylesheet ) ) {
		$default_theme_mods = (array) get_option( 'mods_' . $new_name );
		if ( ! empty( $nav_menu_locations ) && empty( $default_theme_mods['nav_menu_locations'] ) ) {
			$default_theme_mods['nav_menu_locations'] = $nav_menu_locations;
		}
		add_option( "theme_mods_$stylesheet", $default_theme_mods );
	} else {
		/*
		 * Since retrieve_widgets() is called when initializing a theme in the Customizer,
		 * we need to remove the theme mods to avoid overwriting changes made via
		 * the Customizer when accessing wp-admin/widgets.php.
		 */
		if ( 'wp_ajax_customize_save' === current_action() ) {
			remove_theme_mod( 'sidebars_widgets' );
		}
	}

	// Stores classic sidebars for later use by block themes.
	if ( $new_theme->is_block_theme() ) {
		set_theme_mod( 'wp_classic_sidebars', $wp_registered_sidebars );
	}

	update_option( 'theme_switched', $old_theme->get_stylesheet() );

	/*
	 * Reset template globals when switching themes outside of a switched blog
	 * context to ensure templates will be loaded from the new theme.
	 */
	if ( ! is_multisite() || ! ms_is_switched() ) {
		wp_set_template_globals();
	}

	// Clear pattern caches.
	if ( ! is_multisite() ) {
		$new_theme->delete_pattern_cache();
		$old_theme->delete_pattern_cache();
	}

	// Set autoload=no for the old theme, autoload=yes for the switched theme.
	$theme_mods_options = array(
		'theme_mods_' . $stylesheet                  => 'yes',
		'theme_mods_' . $old_theme->get_stylesheet() => 'no',
	);
	wp_set_option_autoload_values( $theme_mods_options );

	/**
	 * Fires after the theme is switched.
	 *
	 * See 'after_switch_theme'.
	 *
	 * @since 1.5.0
	 * @since 4.5.0 Introduced the `$old_theme` parameter.
	 *
	 * @param string   $new_name  Name of the new theme.
	 * @param WP_Theme $new_theme WP_Theme instance of the new theme.
	 * @param WP_Theme $old_theme WP_Theme instance of the old theme.
	 */
	do_action( 'switch_theme', $new_name, $new_theme, $old_theme );
}

Hooks

do_action( ‘switch_theme’, string $new_name, WP_Theme $new_theme, WP_Theme $old_theme )

Fires after the theme is switched.

Changelog

Version Description
2.5.0 Introduced.