本文目录
[隐藏]
- 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(小工具接口)