the_widget()
云策文档标注
概述
the_widget() 是一个 WordPress 模板标签函数，用于在主题模板中直接输出任意已注册的小部件。它允许开发者通过代码动态显示小部件，无需依赖侧边栏或小部件区域。
关键要点
- 函数接受三个参数：$widget（小部件的 PHP 类名，必需）、$instance（小部件实例设置数组，可选，默认空数组）和 $args（配置小部件显示的参数数组，可选）。
- $args 参数包括 before_widget、after_widget、before_title 和 after_title，用于自定义小部件输出的 HTML 包装。
- 支持 WordPress 核心小部件，如 WP_Widget_Archives、WP_Widget_Categories 等，也支持自定义小部件类。
- 使用前需确保小部件已通过 register_widget() 注册，否则会触发 _doing_it_wrong() 警告。
- 函数内部应用了 widget_display_callback 过滤器，并触发了 the_widget 动作钩子，允许开发者干预小部件显示过程。
代码示例
// 默认显示分类小部件
the_widget( 'WP_Widget_Categories' );
// 带设置显示分类小部件
the_widget( 'WP_Widget_Categories', 'dropdown=1&count=1' );
// 使用数组参数显示自定义小部件
$instance = array(
'title' => 'Title',
'text' => 'Text'
);
$args = array(
'before_widget' => '<div class="custom-widget">',
'after_widget' => '</div>',
'before_title' => '<h2>',
'after_title' => '</h2>'
);
the_widget( 'My_Custom_Widget', $instance, $args );注意事项
- 调用 the_widget() 前应验证小部件是否已注册，以避免错误日志记录。可参考用户贡献的 check_widget_registered() 辅助函数。
- 小部件实例设置需符合对应小部件类的预期结构，例如分类小部件的 dropdown 和 count 参数。
- 该函数自 WordPress 2.8.0 版本引入，适用于主题开发中的灵活小部件集成。
原文内容
Outputs an arbitrary widget as a template tag.
Parameters
$widgetstringrequired-
The widget’s PHP class name (see class-wp-widget.php).
$instancearrayoptional-
The widget’s instance settings.
Default:
array() $argsarrayoptional-
Array of arguments to configure the display of the widget.
before_widgetstringHTML content that will be prepended to the widget’s HTML output.
Default<div class="widget %s">, where%sis the widget’s class name.after_widgetstringHTML content that will be appended to the widget’s HTML output.
Default</div>.before_titlestringHTML content that will be prepended to the widget’s title when displayed.
Default<h2 class="widgettitle">.after_titlestringHTML content that will be appended to the widget’s title when displayed.
Default</h2>.
Default:
array()
Source
function the_widget( $widget, $instance = array(), $args = array() ) {
global $wp_widget_factory;
if ( ! isset( $wp_widget_factory->widgets[ $widget ] ) ) {
_doing_it_wrong(
__FUNCTION__,
sprintf(
/* translators: %s: register_widget() */
__( 'Widgets need to be registered using %s, before they can be displayed.' ),
'<code>register_widget()</code>'
),
'4.9.0'
);
return;
}
$widget_obj = $wp_widget_factory->widgets[ $widget ];
if ( ! ( $widget_obj instanceof WP_Widget ) ) {
return;
}
$default_args = array(
'before_widget' => '<div class="widget %s">',
'after_widget' => '</div>',
'before_title' => '<h2 class="widgettitle">',
'after_title' => '</h2>',
);
$args = wp_parse_args( $args, $default_args );
$args['before_widget'] = sprintf( $args['before_widget'], $widget_obj->widget_options['classname'] );
$instance = wp_parse_args( $instance );
/** This filter is documented in wp-includes/class-wp-widget.php */
$instance = apply_filters( 'widget_display_callback', $instance, $widget_obj, $args );
if ( false === $instance ) {
return;
}
/**
* Fires before rendering the requested widget.
*
* @since 3.0.0
*
* @param string $widget The widget's class name.
* @param array $instance The current widget instance's settings.
* @param array $args An array of the widget's sidebar arguments.
*/
do_action( 'the_widget', $widget, $instance, $args );
$widget_obj->_set( -1 );
$widget_obj->widget( $args, $instance );
}
Hooks
- do_action( ‘the_widget’, string $widget, array $instance, array $args )
-
Fires before rendering the requested widget.
- apply_filters( ‘widget_display_callback’, array $instance, WP_Widget $widget, array $args )
-
Filters the settings for a particular widget instance.
Changelog
| Version | Description |
|---|---|
| 2.8.0 | Introduced. |
Skip to note 4 content
truongwp
Show widget with default settings:
the_widget( 'WP_Widget_Categories' );Show widget with settings:
the_widget( 'WP_Widget_Categories', 'dropdown=1&count;=1' );Show widget with custom arguments:
$instance = array( 'dropdown' => 1, 'count' => 1, ); $args = array( 'before_widget' => '<div id="%1$s" class="widget %2$s">', 'after_widget' => '</div>', 'before_title' => '<div class="widget-title">', 'after_title' => '</div>' ); the_widget( 'WP_Widget_Categories', $instance, $args );Skip to note 5 content
Nico Andrade
Example:
$args = array( 'before_widget' => '<div class="widget %s">', 'after_widget' => '</div>', 'before_title' => '<h2 class="widget-title">', 'after_title' => '</h2>' ); $instance = array( 'title' => 'Title', 'text' => 'Text' ); the_widget( 'My_Custom_Widget', $instance, $args );Skip to note 6 content
vee
This function will be showing error in the log file “Widgets need to be registered using register_widget() , before they can be displayed” if the specified widget name is not exists.
The widgets on this page can be removed by some ways even they are core widgets.
To prevent this, you need to check before call
the_widget()that widget is really regietered/exists.But sadly, currently there is no function to check it easily. However, the code below can help.
<br />
function check_widget_registered(string $widget_class_name) {<br />
global $wp_widget_factory;</p>
<p> if ( ! empty( $wp_widget_factory->widgets ) && array_key_exists( $widget_class_name, $wp_widget_factory->widgets ) ) {<br />
return true;<br />
} else {<br />
return false;<br />
}<br />
}<br />
The code above generated by Gemini.
To use,
<br />
if (check_widget_registered('WP_Widget_Recent_Posts')) {<br />
the_widget('WP_Widget_Recent_Posts');<br />
}<br />