编辑“WordPressWidgets API”

<span style="border:1px solid #000; text-align:center; float:right; padding:6px;"><strong>导航:</strong> [[WordPress开发文档|上一页]] | {{Template:WordPress导航}}</span>
<div style="clear:both;"></div>

这是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，需要用一个[http://www.php.net/manual/en/language.pseudo-types.php PHP回调]（PHP文档中的一个准型(Pseudo-Type)）将这些PHP函数注册为WordPress   Widget。WordPress widget API函数会负责注册该PHP回调。

WordPress widget API位于 [http://core.trac.wordpress.org/browser/trunk/wp-includes/widgets.php wp-includes/widgets.php]中。
==函数引用==
<STRONG>侧边栏函数</STRONG>
*[http://codex.wordpress.org/Function_Reference/is_active_sidebar is_active_sidebar]
*[http://codex.wordpress.org/Function_Reference/register_sidebars register_sidebars]
*[http://codex.wordpress.org/Function_Reference/register_sidebar register_sidebar]
*[http://codex.wordpress.org/Function_Reference/unregister_sidebar unregister_sidebar]
*[http://codex.wordpress.org/Function_Reference/is_dynamic_sidebar is_dynamic_sidebar]
*[http://codex.wordpress.org/Function_Reference/dynamic_sidebar dynamic_sidebar]
*[http://codex.wordpress.org/Function_Reference/register_sidebar_widget register_sidebar_widget]
*[http://codex.wordpress.org/Function_Reference/unregister_sidebar_widget unregister_sidebar_widget]
*[http://codex.wordpress.org/Function_Reference/wp_register_sidebar_widget wp_register_sidebar_widget]
*[http://codex.wordpress.org/index.php?title=Function_Reference/wp_unregister_sidebar_widget&action=edit&redlink=1 wp_unregister_sidebar_widget]
*[http://codex.wordpress.org/index.php?title=Function_Reference/wp_get_sidebars_widgets&action=edit&redlink=1 wp_get_sidebars_widgets]
*[http://codex.wordpress.org/index.php?title=Function_Reference/wp_set_sidebars_widgets&action=edit&redlink=1 wp_set_sidebars_widgets] </LI>

<STRONG>Widget函数</STRONG>
*[http://codex.wordpress.org/Function_Reference/is_active_widget is_active_widget]
*[http://codex.wordpress.org/index.php?title=Function_Reference/the_widget&action=edit&redlink=1 the_widget]
*[http://codex.wordpress.org/index.php?title=Function_Reference/register_widget&action=edit&redlink=1 register_widget]
*[http://codex.wordpress.org/index.php?title=Function_Reference/unregister_widget&action=edit&redlink=1 unregister_widget]
*[http://codex.wordpress.org/Function_Reference/register_widget_control register_widget_control]
*[http://codex.wordpress.org/Function_Reference/unregister_widget_control unregister_widget_control]
*[http://codex.wordpress.org/index.php?title=Function_Reference/wp_register_widget_control&action=edit&redlink=1 wp_register_widget_control]
*[http://codex.wordpress.org/index.php?title=Function_Reference/wp_unregister_widget_control&action=edit&redlink=1 wp_unregister_widget_control]
*[http://codex.wordpress.org/index.php?title=Function_Reference/wp_convert_widget_settings&action=edit&redlink=1 wp_convert_widget_settings]
*[http://codex.wordpress.org/index.php?title=Function_Reference/wp_get_widget_defaults&action=edit&redlink=1 wp_get_widget_defaults]
*[http://codex.wordpress.org/index.php?title=Function_Reference/wp_widget_description&action=edit&redlink=1 wp_widget_description] 

注意：不推荐使用以"wp_"开始的函数，因为这些函数可能会随着新版本的发布而有所变化。这也是我们用 [Fhttp://codex.wordpress.org/Function_Reference/register_sidebar_widget register_sidebar_widget()]代替[http://codex.wordpress.org/Function_Reference/wp_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' => "</li>n",
 'before_title' => '< h2 class="widgettitle">',
 'after_title' => "</h2>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">
 <?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar() ) : ?>
 < li>{static sidebar item 1}</li>
 < li>{static sidebar item 2}</li>
 <?php endif; ?>
 </ul> 

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

==开发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']);
 ?>
 <?php echo $before_widget; ?>
 <?php if ( $title )
 echo $before_title . $title . $after_title; ?>
 Hello, World!
 <?php echo $after_widget; ?>
 <?php
 }

 /** @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><label for="<?php echo $this->get_field_id('title'); ?>"><?php _e('Title:'); ?> <input class="widefat" 
 id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" 
 type="text" value="<?php echo $title; ?>" /></label></p>
 <?php 
 }
 } // class FooWidget 

然后可以在widgets_init钩子（hook）中注册这个示例widget：
 // register FooWidget widget  
 add_action('widgets_init', create_function('', 'return register_widget("FooWidget");'));  

OK，现在你就拥有一个通用widget了，不需要再对它做特别修改。

更多信息请看[http://codex.wordpress.org/Version_2.8#New_Widgets_API WordPress 2.8]的版本信息。

==开发新widget==
Google Search Widget （曾经是 [http://downloads.wordpress.org/plugin/widgets.zip original widget   plugin] 插件的一部分，该插件已停用）文件的每个部分都做了注释，你可以考虑用它作为widget的开发教程。此外还有一些注意事项：

*加载插件时不要执行任何代码。请使用plugins_loaded钩子，否则会因为未定义函数而导致致命错误。   
*用register_sidebar_widget($name, $callback) 将widget添加到管理界面。   
*将以下模板作为示范： 

<BLOCKQUOTE>
  function widget_myuniquewidget($args)   {<BR>
    extract($args);<BR>
    ?&gt;<BR>
    &lt;?php echo $before_widget; ?&gt;<BR>
    &lt;?php   echo $before_title<BR>
    . 'My Unique Widget'<BR>
    . $after_title; ?&gt;<BR>
    Hello,   World!<BR>
    &lt;?php echo $after_widget;   ?&gt;<BR>
    &lt;?php<BR>
    }<BR>
    register_sidebar_widget('My Unique   Widget',<BR>
    'widget_myuniquewidget'); 
</BLOCKQUOTE>
重要提示：如果要在插件中使用上述模板，应将其包裹在：
function widget_myuniquewidget_register() {<BR>
  --the above goes   here--<BR>
  register_sidebar_widget('My Unique   Widget','widget_myuniquewidget');}<BR>
  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，也可能会将变量作为参数，告诉另一个模板标签怎样格式化输出内容。   
*也可以使用下列语句在管理界面中添加配置页面。你的回调会被用在主表单中，因此不能包含任何&lt;form&gt;标签或表单提交按钮。<BR>
      <PRE>      register_widget_control($name, $callback [, $width [, $height ]] );  </PRE>
*给你的表单元素命名空间，不要让它们与其它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的链接（不接受附件），有人会审核的。 

<STRONG>我还能用widget做些什么？</STRONG>

*开发一个主题，里面含有一个特别的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用户使用。 

<STRONG>Widget——一次性或多次性</STRONG>
可以对widget进行编码，让它只出现一次或者出现多次。只要你遵守一些操作规则，WordPress会自动帮你多次显示widget。

==相关条目==
*[[Drupal]] 
*[[OBLOG]] 
*[[X-Space]] 
*[[SaBlog-X]] 
*[[Bo-Blog]]

[[category:WordPress中文文档|A]]
[[category:WordPress网站开发|A]]
[[category:WordPress开发文档|A]]