IDC资讯中心
本文目录
[隐藏]
- 1小工具 API
- 2函数参考
- 2.1小工具函数
- 2.2内部函数
- 3开发小工具
- 3.1默认用法
- 3.2示例
- 3.3使用 namespaces
- 3.4其他说明
小工具 API
本页包含 WordPress 小工具接口（Widgets API）的技术文档。 如果您是一位主题设计者、或者插件作者，希望创建一个有效的挂件，建议您阅读本文。本文假定您了解 PHP 脚本语言的基础语法。
所谓的小工具（widget）就是一个在被调用时会输出字符到标准输出的 PHP 函数。
WordPress 小工具接口部分的代码在 wp-includes/widgets.php 中。
函数参考
小工具函数
- is_active_widget()
- the_widget()
- register_widget()
- unregister_widget()
内部函数
- 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。
默认用法
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
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 钩子注册小工具：
1 2 3 |
add_action( 'widgets_init', function(){ register_widget( 'My_Widget' ); }); |
示例
下面的代码创建了一个名为 Foo_Widget 的小工具，它内置了一个更改标题的设置选项。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 |
/**
* 添加 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 钩子注册上面的小工具：
1 2 |
// 注册 Foo_Widget 小工具 add_action( 'widgets_init', create_function( '', 'register_widget( "foo_widget" );' ) ); |
使用 namespaces
如果你使用 PHP 5.3. 带 namespaces ，你可以使用下面的方法来调用 构造函数:
1 2 3 4 5 6 7 8 |
namespace a\b\c; class My_Widget_Class extends \WP_Widget { function __construct() { parent::__construct( 'baseID', 'name' ); } // ... 函数的其余部分 } |
然后调用注册小工具：
1 2 3 |
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() 方式。
- 原文：http://codex.wordpress.org/Widgets_API
- 翻译：倡萌@WordPress大学 – WordPress Widgets API（小工具接口）
