新精神活性物质是什么:WordPressWidgets API

这是WordPress Widget（小工具）API（应用程序接口）的技术性文档，目标读者包括WordPress主题开发人员、插件开发人员以及所有希望开发单机widget的用户。文档假设读者对PHP脚本语言有基本了解。

widget是一个可在调用时利用echo命令将字符串数据输出到STDOUT上的PHP函数。要将这样的PHP函数转换成WordPress Widget，需要用一个PHP回调（PHP文档中的一个准型(Pseudo-Type)）将这些PHP函数注册为WordPress Widget。WordPress widget API函数会负责注册该PHP回调。

WordPress widget API位于 wp-includes/widgets.php中。

这是WordPress Widget（小工具）API（应用程序接口）的技术性文档，目标读者包括WordPress主题开发人员、插件开发人员以及所有希望开发单机widget的用户。文档假设读者对PHP脚本语言有基本了解。widget是一个可在调用时利用echo命令将字符串数据输出到STDOUT上的PHP函数。要将这样的PHP函数转换成WordPress Widget，需要用一个PHP回调（PHP文档中的一个准型(Pseudo-Type)）将这些PHP函数注册为WordPress Widget。WordPress widget API函数会负责注册该PHP回调。

WordPress widget API位于 wp-includes/widgets.php中。

目录

• 1 函数引用
• 2 定义侧边栏
• 3 开发Widgets
• 4 开发新widget
• 5 相关条目

函数引用

侧边栏函数

• is_active_sidebar
• register_sidebars
• register_sidebar
• unregister_sidebar
• is_dynamic_sidebar
• dynamic_sidebar
• register_sidebar_widget
• unregister_sidebar_widget
• wp_register_sidebar_widget
• wp_unregister_sidebar_widget
• wp_get_sidebars_widgets
• wp_set_sidebars_widgets

Widget函数

• is_active_widget
• the_widget
• register_widget
• unregister_widget
• register_widget_control
• unregister_widget_control
• wp_register_widget_control
• wp_unregister_widget_control
• wp_convert_widget_settings
• wp_get_widget_defaults
• wp_widget_description

注意：不推荐使用以"wp_"开始的函数，因为这些函数可能会随着新版本的发布而有所变化。这也是我们用 [Fhttp://codex.wordpress.org/Function_Reference/register_sidebar_widget register_sidebar_widget()]代替wp_register_sidebar_widget()的原因。

定义侧边栏

下面这些函数可以使侧边栏在主题中正常显示。

注册多个侧边栏

register_sidebars( $count, $args );  

注册一个或多个侧边栏以供当前主题使用。大多数主题都只有一个侧边栏。因此count参数不是必需参数，且默认值为1。

$args参数将被传递给register_sidebar()并遵循其格式，但参数名除外，若count参数值为双数，$args参数名将与sprintf()合作，在每个侧边栏中插入或添加一个唯一数字。

例如，以下代码会生成两个分别名为"Foobar 1"与 "Foobar 2"的侧边栏。

register_sidebars(2, array('name'=>'Foobar %d'));  

注册一个侧边栏

register_sidebar( $args ); 可选的args参数是一个关联数组，该关联数组将作为第一个参数被传递给所有已激活的widget回调。（若传递的是字符串而非数组，该参数将被parse_str()遍历，从而生成一个关联数组。）传递指定主题的HTML标签以包裹widget与其标题，这是参数的基本用法。下面是参数默认值：

'before_widget' => '< li id="%1$s" class="widget %2$s">','after_widget' => "n",'before_title' => '< h2 class="widgettitle">','after_title' => "n" 

只有在你希望为侧边栏赋予独有名称时，如"Right Sidebar"与"Left Sidebar"，或侧边栏需要被特别标记时，才有必要使用register_sidebar函数而不是register_sidebars函数。侧边栏名称只出现在管理面板中，但也会被用作一个保存侧边栏排列的索引。因此，如果有另一个主题使用相同的侧边栏名称，那么侧边栏就可以再利用并重写它们的排列。

before/after参数的默认值适用于可生成带有“h2”标题的列表型侧边栏的主题。我们推荐所有主题都采用这种侧边栏，以这种方式构建的主题可以轻松注册侧边栏而无需担心before/after标签。如果主题由于某些原因无法以这种方式构建，那么注册侧边栏时一定要指定before/after标签。推荐逐字复制id和class属性，以使内部sprintf调用得以运行，CSS样式也能够被应用到单个widget上。

在主题上显示侧边栏

dynamic_sidebar( $sidebar ); 该函数按顺序逐个调用已启用的widget，从而输出侧边栏的框架。如果你有不止一个侧边栏，你需要向该函数指明你希望输出的侧边栏名称或编号。若显示成功，该函数返回TRUE，若失败则返回FALSE。

用返回的值决定是否显示静态侧边栏。这可保证即使在未激活widgets插件的情况下，主题也能够正常显示。下面是对该函数推荐用法，附带一个可避免致命错误的测试。

< ul id="sidebar">< li>{static sidebar item 1}< li>{static sidebar item 2} 

如果按编号注册侧边栏，那么检索时应该按编号检索。如果按名称注册侧边栏，检索时也应按名称检索。

开发Widgets

在WordPress 2.8及更高版本中开发widgets

自WordPress 2.8起，widget开发开始变得简单起来。要创建一个widget，你只需要扩展标准widget类和它的一些函数。

在标准类中，也可以找到用以开发widget的函数的信息。

默认用法

class My_Widget extends WP_Widget {function My_Widget() {// widget actual processes}function form($instance) {// outputs the options form on admin}function update($new_instance, $old_instance) {// processes widget options to be saved} function widget($args, $instance) {// outputs the content of the widget}}register_widget('My_Widget'); 

示例

下面的代码示例可生成一个名为FooWidget的widget工具，该widget具有一个可更改显示名称的设置表单。

/*** FooWidget Class*/class FooWidget extends WP_Widget {/** constructor */function FooWidget() {parent::WP_Widget(false, $name = 'FooWidget'); }

/** @see WP_Widget::widget */function widget($args, $instance) { extract( $args );$title = apply_filters('widget_title', $instance['title']);?>Hello, World!
/** @see WP_Widget::update */function update($new_instance, $old_instance) { return $new_instance;}/** @see WP_Widget::form */function form($instance) { $title = esc_attr($instance['title']);?>< p> 
然后可以在widgets_init钩子（hook）中注册这个示例widget：
// register FooWidget widget  add_action('widgets_init', create_function(, 'return register_widget("FooWidget");'));  
OK，现在你就拥有一个通用widget了，不需要再对它做特别修改。
更多信息请看WordPress 2.8的版本信息。
 开发新widget
Google Search Widget （曾经是 original widget plugin 插件的一部分，该插件已停用）文件的每个部分都做了注释，你可以考虑用它作为widget的开发教程。此外还有一些注意事项：
加载插件时不要执行任何代码。请使用plugins_loaded钩子，否则会因为未定义函数而导致致命错误。 
用register_sidebar_widget($name, $callback) 将widget添加到管理界面。 
将以下模板作为示范： 
 function widget_myuniquewidget($args) {
 extract($args);
  ?>
 
  . 'My Unique Widget'
 . $after_title; ?>
 Hello, World!
 
  }
 register_sidebar_widget('My Unique Widget',
 'widget_myuniquewidget'); 
重要提示：如果要在插件中使用上述模板，应将其包裹在：function widget_myuniquewidget_register() {
 --the above goes   here--
 register_sidebar_widget('My Unique   Widget','widget_myuniquewidget');}
 add_action('init',   widget_myuniquewidget_register); 
中。
不要忽略$before_widget, $after_widget, $before_title与$after_title。出于对不同主题兼容性的考虑，这些参数都是必要的。 
谨慎命名widget及其函数。widget名称字符串和函数名称字符串都会被用作HTML属性，不要在一个HTML文档中出现两个相同的id。 
在内部进行本地化，以保留HTML的id属性。如果你希望自己的widget名称以文本域定位，请传递array($name, $textdomain)来代替 $name。 
要容纳多个widget（如文本widget和RSS widget），你可以传递一个名称为array($name_as_sprintf_pattern, $textdomain, $replacement)的更新值。参见源代码。 
你可以以多种方式使用上文中提到的变量，在某些情况下甚至可以忽略它们。比如有些widget可能不需要标题。有些widget会多次使用 $before_widget 与 $after_widget，也可能会将变量作为参数，告诉另一个模板标签怎样格式化输出内容。 
也可以使用下列语句在管理界面中添加配置页面。你的回调会被用在主表单中，因此不能包含任何
标签或表单提交按钮。
 
      register_widget_control($name, $callback [, $width [, $height ]] );  
给你的表单元素命名空间，不要让它们与其它widgets冲突 
每个widget都必须有一个独一无二的名称。你可以提供一个回调，注册另一个相同名称的widget来代替某个已经注册的widget。 
将register_sidebar_widget()或 register_widget_control()的其它任何参数传递给回调。以文本widget和RSS widget为例。 
给注册函数传递空字符串，可以“取消”widget的注册 
可能有些没有记录的函数。推荐你查看源代码，了解我们怎样用这些函数制作标准widget。 
在Classic和Default主题（这两个WordPress自带主题都使用ul/li/h2构造）之外选择几个主题测试widget。 
发布自己的widget前请确认其安全性 
如果你希望自己开发的widget出现在WordPress.com上，可以给widgets@wordpress.com发送邮件，在邮件里注明widget的链接（不接受附件），有人会审核的。 
我还能用widget做些什么？
开发一个主题，里面含有一个特别的widget，和其它主题区分开来 
这个做法怎么样：用一个WordPress Loop循环来显示边注 
注册一个替代widget，缓冲原始widget，并在一定程度上改变原始widget 
记住，“侧边栏”只是对列表的一个称呼，它可以以垂直方式显示，也可以以水平方式显示。 
同样要记住的是，“widget”只是对一段配置型代码段的称呼。widget可以是隐藏的，也可以放在显要的位置上。 
在脚本中使用widget的id和class属性，使侧边栏更有生机 
用script.aculo.us 或dbx（WordPress内置）工具使得widget可拖拽或者甚至可分解 
记住，widget控制台API只是为了方便。你可以设置自己的管理界面。 
给用户提供技术支持，从用户那里获取对widget的反馈信息。在你的widget控制台下方给出你的email地址或者网站。 
给widgets@wordpress.com发送邮件，在邮件里注明你的widget的链接，如果经过审核，你的widget会被发布在WordPress.com上供所有WordPress用户使用。 
Widget——一次性或多次性可以对widget进行编码，让它只出现一次或者出现多次。只要你遵守一些操作规则，WordPress会自动帮你多次显示widget。