概述

_register_widget_form_callback() 函数用于注册小工具的表单回调，以便在小工具控制界面中处理表单显示和交互。它通过全局变量 $wp_registered_widget_controls 存储小工具控制信息，支持参数验证和默认值设置。

关键要点

• 函数注册小工具的表单回调，用于小工具控制界面的表单处理。
• 参数包括 $id（小工具ID）、$name（名称属性）、$form_callback（回调函数）、$options（控制选项数组）和 ...$params（可选额外参数）。
• 控制选项 $options 可指定宽度、高度和 id_base 等，默认宽度为250、高度为200。
• 函数内部使用 wp_parse_args() 合并默认选项，并确保 $wp_registered_widget_controls 全局数组正确更新。
• 在 widgets_init 动作触发前，如果小工具ID已注册，函数会提前返回以避免重复注册。

代码示例

_register_widget_form_callback( $id, $name, $form_callback, $options = array(), ...$params ) {
    global $wp_registered_widget_controls;

    $id = strtolower( $id );

    if ( empty( $form_callback ) ) {
        unset( $wp_registered_widget_controls[ $id ] );
        return;
    }

    if ( isset( $wp_registered_widget_controls[ $id ] ) && ! did_action( 'widgets_init' ) ) {
        return;
    }

    $defaults          = array(
        'width'  => 250,
        'height' => 200,
    );
    $options           = wp_parse_args( $options, $defaults );
    $options['width']  = (int) $options['width'];
    $options['height'] = (int) $options['height'];

    $widget = array(
        'name'     => $name,
        'id'       => $id,
        'callback' => $form_callback,
        'params'   => $params,
    );
    $widget = array_merge( $widget, $options );

    $wp_registered_widget_controls[ $id ] = $widget;
}

注意事项

• 确保 $form_callback 不为空，否则会从小工具控制数组中移除对应条目。
• 在 widgets_init 动作前调用时，如果小工具ID已存在，函数会静默返回，避免初始化问题。
• 控制选项中的 width 和 height 会被强制转换为整数类型，确保数据一致性。
• 对于多实例小工具（如文本小工具），需在 $options 中设置 id_base 参数以生成唯一ID。