概述

wp_convert_widget_settings() 函数用于将小部件设置从单实例格式转换为多实例格式。它检查设置数组的结构，并在需要时更新 sidebars_widgets 选项以保持一致性。

关键要点

• 函数接受三个参数：$base_name（小部件类型的根ID）、$option_name（小部件类型的选项名）和 $settings（小部件实例设置数组）。
• 通过检查 $settings 数组的键来确定是否为单实例格式：如果数组为空或包含非数字键（除 'number' 外），则视为单实例。
• 如果是单实例，函数会将设置转换为多实例格式（例如，添加索引 2），并更新 sidebars_widgets 选项中的小部件名称以匹配新格式。
• 函数始终设置 $settings['_multiwidget'] = 1 以标记为多实例，并在管理界面中更新选项。
• 返回转换后的设置数组。

代码示例

function wp_convert_widget_settings( $base_name, $option_name, $settings ) {
    // This test may need expanding.
    $single  = false;
    $changed = false;

    if ( empty( $settings ) ) {
        $single = true;
    } else {
        foreach ( array_keys( $settings ) as $number ) {
            if ( 'number' === $number ) {
                continue;
            }
            if ( ! is_numeric( $number ) ) {
                $single = true;
                break;
            }
        }
    }

    if ( $single ) {
        $settings = array( 2 => $settings );

        // If loading from the front page, update sidebar in memory but don't save to options.
        if ( is_admin() ) {
            $sidebars_widgets = get_option( 'sidebars_widgets' );
        } else {
            if ( empty( $GLOBALS['_wp_sidebars_widgets'] ) ) {
                $GLOBALS['_wp_sidebars_widgets'] = get_option( 'sidebars_widgets', array() );
            }
            $sidebars_widgets = &$GLOBALS['_wp_sidebars_widgets'];
        }

        foreach ( (array) $sidebars_widgets as $index => $sidebar ) {
            if ( is_array( $sidebar ) ) {
                foreach ( $sidebar as $i => $name ) {
                    if ( $base_name === $name ) {
                        $sidebars_widgets[ $index ][ $i ] = "$name-2";
                        $changed                          = true;
                        break 2;
                    }
                }
            }
        }

        if ( is_admin() && $changed ) {
            update_option( 'sidebars_widgets', $sidebars_widgets );
        }
    }

    $settings['_multiwidget'] = 1;
    if ( is_admin() ) {
        update_option( $option_name, $settings );
    }

    return $settings;
}

注意事项

• 函数内部注释指出“This test may need expanding”，意味着单实例检测逻辑可能需要扩展以适应未来变化。
• 在非管理界面（如前端页面）中，sidebars_widgets 的更新仅保存在内存中（通过全局变量），而不会写入数据库，以避免性能问题。
• 转换后，小部件名称在 sidebars_widgets 中会添加“-2”后缀（例如，从“widget_name”变为“widget_name-2”），以区分多实例格式。