小工具 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。

默认用法

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

示例

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

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

使用 namespaces

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

然后调用注册小工具:

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

其他说明

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