小部件将内容和功能添加到小部件区域(也称为 侧边栏)。小部件区域为用户提供了一种自定义其网站的方法。小部件区域可以出现在多个页面上,也可以在一页上出现。您的主题可能只有一个小部件区域或其中许多区域。
您可以使用小部件区域的一些示例是:
- 使用小部件布置主页。这允许站点所有者确定其主页的每个部分中应该出现的内容。
- 创建一个可以使用自己的内容自定义的页脚。
- 将可自定义的侧边栏添加到博客中。
小部件是输出一些HTML的PHP对象。相同类型的小部件可以在同一页面上多次使用(例如文本小部件)。小部件可以将数据保存在数据库中(在选项表中)。
当您创建一种新的小部件时,它将出现在用户的管理屏幕中 外观>小部件。用户可以将小部件添加到小部件区域,并从WordPress管理员自定义小部件设置。
内置与独立小部件
默认的WordPress安装中包含了一组小部件。除了这些标准小部件外,主题或插件还可以包括额外的小部件。主题或插件内置的小部件的优势是提供额外的功能并增加小部件的数量。
一个缺点是,如果更改主题或停用插件,则插件或主题小部件的功能将丢失。但是,小部件的数据和首选项将保存到选项表中,并在主题或插件重新激活时恢复。
如果您在主题中包含一个小部件,则只有在该主题处于活动状态时才能使用它。如果用户决定更改主题,他们将无法访问该小部件。但是,如果插件中包含小部件,则用户可以更改其主题而不会失去对小部件功能的访问。
小部件的解剖
从视觉上讲,一个小部件包括两个区域:
- 标题区域
- 小部件选项
例如,这是管理员和前端中内置文本小部件的布局:
此小部件的HTML输出看起来像这样:
<div id="text-7" class="widget widget_text">
<div class="widget-wrap">
<h4 class="widgettitle">
This is a text widget
</h4><!-- .widgettitle -->
<div class="textwidget">
I can put HTML in here. <a href="http://google.com/">Search me!</a>
</div><!-- .textwidget -->
</div><!-- .widget-wrap -->
</div><!-- #text-7 -->
每个小部件都有自己的方式输出与所显示的数据相关的HTML。小部件的包装标签由显示的小部件区域定义。
创建像内置文本小部件这样的小部件所需的PHP代码如下:
<?php
class My_Widget extends WP_Widget {
public function __construct() {
parent::__construct(
'my-text', // Base ID
'My Text' // Name
);
add_action( 'widgets_init', function() {
register_widget( 'My_Widget' );
});
}
public $args = array(
'before_title' => '<h4 class="widgettitle">',
'after_title' => '</h4>',
'before_widget' => '<div class="widget-wrap">',
'after_widget' => '</div></div>',
);
public function widget( $args, $instance ) {
echo $args['before_widget'];
if ( ! empty( $instance['title'] ) ) {
echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'] ) . $args['after_title'];
}
echo '<div class="textwidget">';
echo esc_html__( $instance['text'], 'text_domain' );
echo '</div>';
echo $args['after_widget'];
}
public function form( $instance ) {
$title = ! empty( $instance['title'] ) ? $instance['title'] : esc_html__( '', 'text_domain' );
$text = ! empty( $instance['text'] ) ? $instance['text'] : esc_html__( '', 'text_domain' );
?>
<p>
<label for="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>"><?php echo esc_html__( 'Title:', 'text_domain' ); ?></label>
<input class="widefat" id="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'title' ) ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>">
</p>
<p>
<label for="<?php echo esc_attr( $this->get_field_id( 'Text' ) ); ?>"><?php echo esc_html__( 'Text:', 'text_domain' ); ?></label>
<textarea class="widefat" id="<?php echo esc_attr( $this->get_field_id( 'text' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'text' ) ); ?>" type="text" cols="30" rows="10"><?php echo esc_attr( $text ); ?></textarea>
</p>
<?php
}
public function update( $new_instance, $old_instance ) {
$instance = array();
$instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';
$instance['text'] = ( ! empty( $new_instance['text'] ) ) ? $new_instance['text'] : '';
return $instance;
}
}
$my_widget = new My_Widget();
上面的代码将在文章后面详细说明。
开发小部件
要创建和显示小部件,您需要执行以下操作:
您的小部件课程
这 wp_widget 班级位于 WP-rudes/class-wp-widget.php
<?php
class My_Widget extends WP_Widget {
public function __construct() {
// actual widget processes
}
public function widget( $args, $instance ) {
// outputs the content of the widget
}
public function form( $instance ) {
// outputs the options form in the admin
}
public function update( $new_instance, $old_instance ) {
// processes widget options to be saved
}
}
这些功能的文档可以在“小部件类代码:”中找到:
construct
:用admin中的描述,名称和显示宽度设置您的小部件。widget
:处理小部件选项并在页面上显示HTML。这$args
参数提供您可以使用的HTML来显示小部件标题类和小部件内容类。form
:显示将用于为小部件设置选项的表单。如果您的小部件没有任何选项,则可以跳过此功能(尽管即使它是空的,也可以将其包括在内)。update
:将小部件选项保存到数据库中。如果您的小部件没有任何选项,则可以跳过此功能(尽管即使它是空的,也可以将其包括在内)。
注册一个小部件
这 register_widget() 功能用于注册小部件。
使用widgets_init挂钩调用此功能:
<?php
add_action( 'widgets_init', 'wpdocs_register_widgets' );
function wpdocs_register_widgets() {
register_widget( 'My_Widget' );
}
在您使用使用标题和小部件内容的类包装的HTML以及使用的类 register_sidebar()。
例子
示例文本小部件
在本文开头的示例中构建文本小部件。您将首先设置一个扩展的小部件类 wp_widget 班级。
在类构造函数中,您将调用父构建器并将其传递给小部件的基本ID和名称。同样在类构造函数中,您将挂接到widgets_init
行动以注册您的小部件。
接下来,您将声明创建小部件时将使用的参数。您必须定义四个论点,before_title
,after_title
,before_widget
,和after_widget
。这些参数将定义包含您的小部件标题和小部件本身的代码。
定义参数后,您将定义小部件函数。此功能需要两个参数,$args
从前的数组,$instance
窗口小部件的功能,是将从表单处理选项并显示网站前端上窗口小部件的HTML的功能。在上面的示例中,小部件函数简单地输出小部件标题,同时将其传递widget_title
筛选。然后,它放置了一个简单的小部件包装器和小部件文本字段的内容。如示例中所述,您可以访问存储在窗口小部件中$instance
。
接下来,您将定义表单函数。此功能采用一个参数,$instance
,并输出用户在小部件管理屏幕中创建小部件的形式。在上面的示例中,该函数从定义$title
和$text
如果存在这些值,则变量并将它们设置为先前输入的值。然后,它输出一个简单的表单,其中包含标题的文本字段和文本内容的Textarea。
最后,您将定义更新功能。此功能需要两个参数,$new_instance
和$old_instance
,并且负责在提交时使用新选项更新小部件。在这里,您只是定义$instance
作为一个空数组。然后,您将标题和文本键设置为$new_instance
值如果存在。然后您返回$instance
。
最后,当定义以上所有内容时,您就可以实例化新的小部件类并测试您的工作。
样本小部件
<?php
/**
* Adds Foo_Widget widget.
*/
class Foo_Widget extends WP_Widget {
/**
* Register widget with WordPress.
*/
public function __construct() {
parent::__construct(
'foo_widget', // Base ID
'Foo_Widget', // Name
array( 'description' => __( 'A Foo Widget', 'text_domain' ) ) // Args
);
}
/**
* Front-end display of widget.
*
* @see WP_Widget::widget()
*
* @param array $args Widget arguments.
* @param array $instance Saved values from database.
*/
public function widget( $args, $instance ) {
extract( $args );
$title = apply_filters( 'widget_title', $instance['title'] );
echo $before_widget;
if ( ! empty( $title ) ) {
echo $before_title . $title . $after_title;
}
echo __( 'Hello, World!', 'text_domain' );
echo $after_widget;
}
/**
* Back-end widget form.
*
* @see WP_Widget::form()
*
* @param array $instance Previously saved values from database.
*/
public function form( $instance ) {
if ( isset( $instance['title'] ) ) {
$title = $instance['title'];
} else {
$title = __( 'New title', 'text_domain' );
}
?>
<p>
<label for="<?php echo $this->get_field_name( 'title' ); ?>"><?php _e( 'Title:' ); ?></label>
<input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" />
</p>
<?php
}
/**
* Sanitize widget form values as they are saved.
*
* @see WP_Widget::update()
*
* @param array $new_instance Values just sent to be saved.
* @param array $old_instance Previously saved values from database.
*
* @return array Updated safe values to be saved.
*/
public function update( $new_instance, $old_instance ) {
$instance = array();
$instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';
return $instance;
}
} // class Foo_Widget
然后可以在widgets_init挂钩中注册此示例小部件:
<?php
// Register Foo_Widget widget
add_action( 'widgets_init', 'register_foo' );
function register_foo() {
register_widget( 'Foo_Widget' );
}
名称空间的示例
如果使用命名空间使用PHP 5.3,则应如下以下示例直接调用构造函数:
<?php
namespace a\b\c;
class My_Widget_Class extends \WP_Widget {
public function __construct() {
parent::__construct( 'baseID', 'name' );
}
// ... rest of the functions
}
并使用以下方式致电寄存器小部件
<?php
// Register Foo_Widget widget
add_action( 'widgets_init', 'register_my_widget' );
function register_my_widget() {
register_widget( 'a\b\c\My_Widget_Class' );
}
看 这个答案在Stack Exchange 有关更多细节。
特殊考虑
如果要在另一个模板文件中使用窗口小部件,而不是在侧边栏中,则可以使用the_widget()
以编程方式显示它。该函数接受小部件类名称。您将小部件类名称传递给了这样的函数:
<?php the_title(); ?>
<div class="content">
<?php the_content(); ?>
</div><!-- .content -->
<div class="widget-section">
<?php the_widget( 'My_Widget_Class' ); ?>
</div><!-- .widget-section -->
如果您需要在页面上的特定区域中使用窗口小部件,例如在网站首页上的部分中显示表单旁边的事件列表,或带有导航的大型曼努。