WordPress Widgets API（小工具接口）

小工具 API

本頁(yè)包含 WordPress 小工具接口（Widgets API）的技術(shù)文檔。 如果您是一位主題設(shè)計(jì)者、或者插件作者，希望創(chuàng)建一個(gè)有效的掛件，建議您閱讀本文。本文假定您了解 PHP 腳本語(yǔ)言的基礎(chǔ)語(yǔ)法。

所謂的小工具（widget）就是一個(gè)在被調(diào)用時(shí)會(huì)輸出字符到標(biāo)準(zhǔn)輸出的 PHP 函數(shù)。

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

函數(shù)參考

小工具函數(shù)

• is_active_widget()
• the_widget()
• register_widget()
• unregister_widget()

內(nèi)部函數(shù)

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

開發(fā)小工具

要?jiǎng)?chuàng)建一個(gè)小工具，你需要了解基本的 WP_Widget 類和的幾個(gè)函數(shù)就可以了。基類中包含了關(guān)于一個(gè)有效的掛件必須繼承函數(shù)的信息。WP_Widget 類位于 wp-includes/widgets.php。

默認(rèn)用法

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 鉤子注冊(cè)小工具：

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

示例

下面的代碼創(chuàng)建了一個(gè)名為 Foo_Widget 的小工具，它內(nèi)置了一個(gè)更改標(biāo)題的設(shè)置選項(xiàng)。

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

	/**
	 * 注冊(cè)一個(gè)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;
	}

	/**
	 * 保存小工具設(shè)置選項(xiàng)
	 *
	 * @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;
	}

	/**
	 * 后臺(tái)小工具表單
	 *
	 * @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 鉤子注冊(cè)上面的小工具：

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

使用 namespaces

如果你使用 PHP 5.3. 帶 namespaces ，你可以使用下面的方法來調(diào)用 構(gòu)造函數(shù):

namespace a\b\c;

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

然后調(diào)用注冊(cè)小工具：

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

這樣你就得到了一個(gè) 多部件（multi-widget），不在需要其他特殊的調(diào)整了。

其他說明

• 你可以通過自己的類來擴(kuò)展 WP_Widget ，只需要提供一個(gè) 構(gòu)造函數(shù)（constructor）和三個(gè)方法—— widget(), form(), 和 update() 。
  • widget() – 輸出小工具的實(shí)際內(nèi)容
  • update() – 要保存的設(shè)置選項(xiàng)
  • form() – 輸出選項(xiàng)表單
• 小工具是通過傳遞 小工具類 的 名稱 到 register_widget() 來注冊(cè)的。
• 通過 WP_Widget 撰寫的所有小工具都具備了重復(fù)使用的能力。
• 選項(xiàng)
  • 移植以前單個(gè)注冊(cè)的小工具的選項(xiàng)到 WP_Widget 將會(huì)升級(jí)到新的多選項(xiàng)存儲(chǔ)格式，這是一個(gè)通過 實(shí)例ID 鍵入的簡(jiǎn)單的多維數(shù)組。
  • 那些使用舊的多實(shí)例模式的小工具選項(xiàng)還是可以使用的。
  • 如果你的小工具需要自定義選項(xiàng)的存儲(chǔ)，你可以提過自己的 get_settings() 和 save_settings() 方式。

• 原文：http://codex.wordpress.org/Widgets_API
• 翻譯：倡萌@WordPress大學(xué) – WordPress Widgets API（小工具接口）