概述

wp_get_sidebars_widgets() 函数用于检索所有侧边栏及其小部件实例ID的完整列表。它会根据需要升级侧边栏小部件列表并保存更新，返回一个数组格式的数据。

关键要点

• 函数返回一个关联数组，包含侧边栏及其小部件实例ID的列表。
• 在非管理界面（前端）加载时，会优先使用全局变量 $_wp_sidebars_widgets 以提高性能，避免重复查询数据库。
• 在管理界面（后端）加载时，直接通过 get_option() 从数据库获取数据。
• 函数包含一个已弃用的参数 $deprecated，自 WordPress 2.8.1 起不再使用，调用时建议保持默认值 true。
• 返回的数据会通过 sidebars_widgets 过滤器进行过滤，允许开发者自定义输出。
• 函数会自动移除数组中的 array_version 键，确保数据格式兼容性。

代码示例

function wp_get_sidebars_widgets( $deprecated = true ) {
    if ( true !== $deprecated ) {
        _deprecated_argument( __FUNCTION__, '2.8.1' );
    }

    global $_wp_sidebars_widgets, $sidebars_widgets;

    if ( ! is_admin() ) {
        if ( empty( $_wp_sidebars_widgets ) ) {
            $_wp_sidebars_widgets = get_option( 'sidebars_widgets', array() );
        }
        $sidebars_widgets = $_wp_sidebars_widgets;
    } else {
        $sidebars_widgets = get_option( 'sidebars_widgets', array() );
    }

    if ( is_array( $sidebars_widgets ) && isset( $sidebars_widgets['array_version'] ) ) {
        unset( $sidebars_widgets['array_version'] );
    }

    return apply_filters( 'sidebars_widgets', $sidebars_widgets );
}

注意事项

• 参数 $deprecated 已弃用，应避免传递非 true 的值，否则会触发 _deprecated_argument() 警告。
• 函数依赖于全局变量 $_wp_sidebars_widgets 和 $sidebars_widgets，在自定义开发中需注意变量作用域。
• 返回的数组可能包含空侧边栏或无效小部件ID，调用方应进行适当的数据验证。
• 此函数在 WordPress 2.2.0 中引入，是处理侧边栏小部件数据的核心函数之一。