概述

retrieve_widgets() 函数用于验证并重新映射“孤立”小部件到 wp_inactive_widgets 侧边栏，并保存小部件设置。它必须在每次主题更改时至少运行一次，以确保小部件数据的一致性。

关键要点

• 主要功能：检测并处理因主题切换导致的孤立小部件，将其移至 wp_inactive_widgets 侧边栏。
• 参数：$theme_changed（可选），布尔值或字符串，'customize' 值可延迟更新以适配 Customizer。
• 返回值：更新后的侧边栏小部件数组。
• 注意事项：函数会更新数据库和全局变量 $sidebars_widgets，因此不应在前端运行，除非 $theme_changed 为 'customize'。

代码示例

function retrieve_widgets( $theme_changed = false ) {
	global $wp_registered_sidebars, $sidebars_widgets, $wp_registered_widgets;

	$registered_sidebars_keys = array_keys( $wp_registered_sidebars );
	$registered_widgets_ids   = array_keys( $wp_registered_widgets );

	if ( ! is_array( get_theme_mod( 'sidebars_widgets' ) ) ) {
		if ( empty( $sidebars_widgets ) ) {
			return array();
		}

		unset( $sidebars_widgets['array_version'] );

		$sidebars_widgets_keys = array_keys( $sidebars_widgets );
		sort( $sidebars_widgets_keys );
		sort( $registered_sidebars_keys );

		if ( $sidebars_widgets_keys === $registered_sidebars_keys ) {
			$sidebars_widgets = _wp_remove_unregistered_widgets( $sidebars_widgets, $registered_widgets_ids );

			return $sidebars_widgets;
		}
	}

	// Discard invalid, theme-specific widgets from sidebars.
	$sidebars_widgets = _wp_remove_unregistered_widgets( $sidebars_widgets, $registered_widgets_ids );
	$sidebars_widgets = wp_map_sidebars_widgets( $sidebars_widgets );

	// Replace non-array values inside the array with an empty array.
	foreach ( $sidebars_widgets as $key => $value ) {
		if ( ! is_array( $value ) ) {
			$sidebars_widgets[ $key ] = array();
		}
	}

	// Find hidden/lost multi-widget instances.
	$shown_widgets = array_merge( ...array_values( $sidebars_widgets ) );
	$lost_widgets  = array_diff( $registered_widgets_ids, $shown_widgets );

	foreach ( $lost_widgets as $key => $widget_id ) {
		$number = preg_replace( '/.+?-([0-9]+)$/', '$1', $widget_id );

		// Only keep active and default widgets.
		if ( is_numeric( $number ) && (int) $number < 2 ) {
			unset( $lost_widgets[ $key ] );
		}
	}

	if ( ! empty( $lost_widgets ) ) {
		$sidebars_widgets['wp_inactive_widgets'] = array_merge( $lost_widgets, $sidebars_widgets['wp_inactive_widgets'] ?? array() );
	}

	if ( 'customize' !== $theme_changed ) {
		wp_set_sidebars_widgets( $sidebars_widgets );
	}

	return $sidebars_widgets;
}