WordPress Widgets API（小工具接口）

文章目录

小工具 API

本页包含 WordPress 小工具接口（Widgets API）的技术文档。如果您是一位主题设计者、或者插件作者，希望创建一个有效的挂件，建议您阅读本文。本文假定您了解 PHP 脚本语言的基础语法。

所谓的小工具（widget）就是一个在被调用时会输出字符到标准输出的 PHP 函数。

WordPress 小工具接口部分的代码在 wp-includes/widgets.php 中。

函数参考

小工具函数

内部函数

wp_register_widget_control()
wp_unregister_widget_control()
wp_convert_widget_settings()
wp_get_widget_defaults()
wp_widget_description()

开发小工具

要创建一个小工具，你需要了解基本的 WP_Widget 类和的几个函数就可以了。基类中包含了关于一个有效的挂件必须继承函数的信息。WP_Widget 类位于 wp-includes/widgets.php。

默认用法

class My_Widget extends WP_Widget {

	public function __construct() {
		// widget actual processes
	}

	public function widget( $args, $instance ) {
		// outputs the content of the widget
	}

 	public function form( $instance ) {
		// outputs the options form on admin
	}

	public function update( $new_instance, $old_instance ) {
		// processes widget options to be saved
	}

}

然后使用 widgets_init 钩子注册小工具：

add_action( 'widgets_init', function(){
     register_widget( 'My_Widget' );
});

示例

下面的代码创建了一个名为 Foo_Widget 的小工具，它内置了一个更改标题的设置选项。

/**
 * 添加 Foo_Widget 小工具
 */
class Foo_Widget extends WP_Widget {

	/**
	 * 注册一个WordPress小工具
	 */
	public function __construct() {
		parent::__construct(
	 		'foo_widget', // 基本 ID
			'Foo_Widget', // 名称
			array( 'description' => __( 'A Foo Widget', 'text_domain' ), ) // Args
		);
	}

	/**
	 * 前端显示小工具
	 *
	 * @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;
	}

	/**
	 * 保存小工具设置选项
	 *
	 * @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'] = strip_tags( $new_instance['title'] );

		return $instance;
	}

	/**
	 * 后台小工具表单
	 *
	 * @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_id( '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 
	}

} // class Foo_Widget

然后通过 widgets_init 钩子注册上面的小工具：

// 注册 Foo_Widget 小工具
add_action( 'widgets_init', create_function( '', 'register_widget( "foo_widget" );' ) );

使用 namespaces

如果你使用 PHP 5.3. 带 namespaces ，你可以使用下面的方法来调用构造函数:

namespace a\b\c;

class My_Widget_Class extends \WP_Widget {
	function __construct() {
       	    parent::__construct( 'baseID', 'name' );
        }
        // ... 函数的其余部分
}

然后调用注册小工具：

add_action( 'widgets_init', function(){
     register_widget( 'a\b\c\My_Widget_Class' );
});

这样你就得到了一个多部件（multi-widget），不在需要其他特殊的调整了。

其他说明

你可以通过自己的类来扩展 WP_Widget ，只需要提供一个构造函数（constructor）和三个方法—— widget(), form(), 和 update() 。
- widget() – 输出小工具的实际内容
- update() – 要保存的设置选项
- form() – 输出选项表单
小工具是通过传递小工具类的名称到 register_widget() 来注册的。
通过 WP_Widget 撰写的所有小工具都具备了重复使用的能力。
选项
- 移植以前单个注册的小工具的选项到 WP_Widget 将会升级到新的多选项存储格式，这是一个通过实例ID 键入的简单的多维数组。
- 那些使用旧的多实例模式的小工具选项还是可以使用的。
- 如果你的小工具需要自定义选项的存储，你可以提过自己的 get_settings() 和 save_settings() 方式。