_register_widget_update_callback()

💡 云策文档标注

概述

_register_widget_update_callback() 函数用于注册小部件的更新回调，管理小部件实例的更新逻辑。它通过全局变量 $wp_registered_widget_updates 存储回调信息，支持可选参数传递。

关键要点

函数签名：_register_widget_update_callback( $id_base, $update_callback, $options = array(), ...$params )
参数 $id_base 为小部件的基础 ID，$update_callback 为更新回调方法，$options 为控制选项数组，...$params 为可选附加参数
如果 $id_base 已存在且 $update_callback 为空，则从全局数组中移除该条目；否则将回调信息合并到全局数组
控制选项 $options 可包含 height、width、id_base 等，具体参考 wp_register_widget_control()

代码示例

function _register_widget_update_callback( $id_base, $update_callback, $options = array(), ...$params ) {
	global $wp_registered_widget_updates;

	if ( isset( $wp_registered_widget_updates[ $id_base ] ) ) {
		if ( empty( $update_callback ) ) {
			unset( $wp_registered_widget_updates[ $id_base ] );
		}
		return;
	}

	$widget = array(
		'callback' => $update_callback,
		'params'   => $params,
	);

	$widget                                   = array_merge( $widget, $options );
	$wp_registered_widget_updates[ $id_base ] = $widget;
}

注意事项

此函数主要用于内部小部件系统，开发者通常通过 WP_Widget 类间接使用
在 WordPress 5.3.0 中，...$params 参数被正式添加到函数签名中
控制选项 $options 的详细说明可参考 wp_register_widget_control() 函数文档

📄 原文内容

Registers the update callback for a widget.

Parameters

$id_basestringrequired

The base ID of a widget created by extending WP_Widget.

$update_callbackcallablerequired

Update callback method for the widget.

$optionsarrayoptional

Widget control options. See wp_register_widget_control() .

More Arguments from wp_register_widget_control( … $options )

Array or string of control options.

height int
Never used. Default 200.
width int
Width of the fully expanded control form (but try hard to use the default width).
Default 250.
id_base int|string
Required for multi-widgets, i.e widgets that allow multiple instances such as the text widget. The widget ID will end up looking like {$id_base}-{$unique_number}.

Default:array()

$paramsmixedoptional

Optional additional parameters to pass to the callback function when it’s called.

Source

function _register_widget_update_callback( $id_base, $update_callback, $options = array(), ...$params ) {
	global $wp_registered_widget_updates;

	if ( isset( $wp_registered_widget_updates[ $id_base ] ) ) {
		if ( empty( $update_callback ) ) {
			unset( $wp_registered_widget_updates[ $id_base ] );
		}
		return;
	}

	$widget = array(
		'callback' => $update_callback,
		'params'   => $params,
	);

	$widget                                   = array_merge( $widget, $options );
	$wp_registered_widget_updates[ $id_base ] = $widget;
}

View all references View on Trac View on GitHub

Used by	Description
WP_Widget::_register_one()`wp-includes/class-wp-widget.php`	Registers an instance of the widget class.

Changelog

Version	Description
5.3.0	Formalized the existing and already documented `...$params` parameter by adding it to the function signature.
2.8.0	Introduced.

函数文档

概述