云策 WordPress 开发者社区

函数文档

wp_register_sidebar_widget()

查看官方原文 ↗
💡 云策文档标注

概述

wp_register_sidebar_widget() 函数用于注册一个 widget 实例，使其在 WordPress 侧边栏中可用。该函数也可通过将 $output_callback 参数设为空字符串来注销 widget。

关键要点

  • 函数核心功能是注册或注销 widget 实例，基于 $output_callback 参数是否为空。
  • 参数包括 $id（widget ID）、$name（显示标题）、$output_callback（回调函数）、$options（可选数组，包含 classname、description、show_instance_in_rest 等选项）和 $params（可选附加参数）。
  • 默认选项 'classname' 可被覆盖，show_instance_in_rest 选项仅适用于基于 WP_Widget 的 widget。
  • 函数内部处理 widget 注册逻辑，包括检查回调函数可调用性、合并选项，并触发 wp_register_sidebar_widget 钩子。
  • 相关函数包括 wp_unregister_sidebar_widget()、WP_Widget::_register_one() 等，用于 widget 管理。
  • 版本变更：5.8.0 添加 show_instance_in_rest 选项，5.3.0 正式化 $params 参数，2.2.0 引入函数。

代码示例

wp_register_sidebar_widget(
    'wpdocs_widget_1',        // widget ID
    'Wpdocs Widget',          // widget 名称
    'wpdocs_widget_display',  // 回调函数
    array(                    // 选项数组
        'description' => 'Description of what the widget does'
    )
);

function wpdocs_widget_display($args) {
   echo $args['before_widget'];
   echo $args['before_title'] . 'The Wpdocs Widget' .  $args['after_title'];
   echo $args['after_widget'];
   echo __( 'Wpdocs Widget Test', 'textdomain' );
}

注意事项

  • 此 widget 只能在一个侧边栏中使用一次；如需可重复添加的 widget，请参考 Register Widget 函数。
  • 确保回调函数（如 wpdocs_widget_display）正确定义并处理 $args 参数以正确显示 widget。
📄 原文内容

Registers an instance of a widget.

Description

The default widget option is ‘classname’ that can be overridden.

The function can also be used to un-register widgets when $output_callback parameter is an empty string.

Parameters

$idint|stringrequired
Widget ID.
$namestringrequired
Widget display title.
$output_callbackcallablerequired
Run when widget is called.
$optionsarrayoptional
An array of supplementary widget options for the instance.

  • classname string
    Class name for the widget’s HTML container. Default is a shortened version of the output callback name.
  • description string
    Widget description for display in the widget administration panel and/or theme.
  • show_instance_in_rest bool
    Whether to show the widget’s instance settings in the REST API.
    Only available for WP_Widget based widgets.

Default:array()

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

Source

function wp_register_sidebar_widget( $id, $name, $output_callback, $options = array(), ...$params ) {
	global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates, $_wp_deprecated_widgets_callbacks;

	$id = strtolower( $id );

	if ( empty( $output_callback ) ) {
		unset( $wp_registered_widgets[ $id ] );
		return;
	}

	$id_base = _get_widget_id_base( $id );
	if ( in_array( $output_callback, $_wp_deprecated_widgets_callbacks, true ) && ! is_callable( $output_callback ) ) {
		unset( $wp_registered_widget_controls[ $id ] );
		unset( $wp_registered_widget_updates[ $id_base ] );
		return;
	}

	$defaults = array( 'classname' => $output_callback );
	$options  = wp_parse_args( $options, $defaults );
	$widget   = array(
		'name'     => $name,
		'id'       => $id,
		'callback' => $output_callback,
		'params'   => $params,
	);
	$widget   = array_merge( $widget, $options );

	if ( is_callable( $output_callback ) && ( ! isset( $wp_registered_widgets[ $id ] ) || did_action( 'widgets_init' ) ) ) {

		/**
		 * Fires once for each registered widget.
		 *
		 * @since 3.0.0
		 *
		 * @param array $widget An array of default widget arguments.
		 */
		do_action( 'wp_register_sidebar_widget', $widget );
		$wp_registered_widgets[ $id ] = $widget;
	}
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘wp_register_sidebar_widget’, array $widget )

Fires once for each registered widget.

Uses Description
did_action()wp-includes/plugin.php

Retrieves the number of times an action has been fired during the current request.
_get_widget_id_base()wp-includes/widgets.php

Retrieves the widget ID base value.
wp_parse_args()wp-includes/functions.php

Merges user defined arguments into defaults array.
do_action()wp-includes/plugin.php

Calls the callback functions that have been added to an action hook.

Show 2 moreShow less

Used by Description
register_sidebar_widget()wp-includes/deprecated.php

Register widget for sidebar with backward compatibility.
WP_Widget::_register_one()wp-includes/class-wp-widget.php

Registers an instance of the widget class.
wp_unregister_sidebar_widget()wp-includes/widgets.php

Remove widget from sidebar.

Changelog

Version Description
5.8.0 Added show_instance_in_rest option.
5.3.0 Formalized the existing and already documented ...$params parameter by adding it to the function signature.
2.2.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note

    Example
    The following code will create a widget called “Wpdocs Widget” which will become available in the WordPress Administrative Panels. The widget can then be dragged to an available sidebar for display.

    Note that this widget can only be used once in exactly 1 of the sidebars. For recursive widgets (widgets you can add to multiple times and add to multiple sidebars) please see the Register Widget function.

    wp_register_sidebar_widget(
	'wpdocs_widget_1',		// wpdocs unique widget id
	'Wpdocs Widget',		// widget name
	'wpdocs_widget_display',	// callback function
	array(				// options
		'description' => 'Description of what the widget does'
	)
);

/**
 * Display the wpdocs widget
 */
function wpdocs_widget_display($args) {
   echo $args['before_widget'];
   echo $args['before_title'] . 'The Wpdocs Widget' .  $args['after_title'];
   echo $args['after_widget'];
   // Print some HTML for the widget to display here.
   echo __( 'Wpdocs Widget Test', 'textdomain' );
}