WordPress控制板小工具API

WordPress 2.7引入了一个新的控制板 Widget（小工具）API，用户可以轻松在管理面板中添加各种小工具。使用控制板小工具API，应具备一定的PHP知识并熟悉WordPress插件API。对熟悉动作钩子（hook）和过滤器钩子的插件或主题开发人员来说，只要几分钟就可以熟练使用控制板widget API，并且可以通过widget API使自己开发的插件更具实用效果。

概述

相关函数

wp_add_dashboard_widget() 函数是用来添加控制板小工具的主要工具：

wp_add_dashboard_widget($widget_id, $widget_name, $callback, $control_callback = null)

• $widget_id —— 新加入的小工具的标识性别名。该参数值用来作为小工具数组中的css类以及键值。
• $widget_name ——新widget在标题部分显示的名称
• $callback —— 新创建的函数名称，该函数用来显示widget的实际内容
• $control_callback —— （可选）新创建的函数名称，该函数用以提交widget选项表并显示表单元素。

动作钩子

运行wp_add_dashboard_widget() 函数前需要连接到相应的动作钩子上（此处即wp_dashboard_setup）。wp_dashboard_setup连接到核心代码：

do_action( 'wp_dashboard_setup' );  

示例

添加一个widget

下面是一个非常简单的widget的大致轮廓：

// Create the function to output the contents of our Dashboard Widget

function example_dashboard_widget_function() {
// Display whatever it is you want to show
echo "Hello World, I'm a great Dashboard Widget";
}

// Create the function use in the action hook

function example_add_dashboard_widgets() {
wp_add_dashboard_widget('example_dashboard_widget', 'Example Dashboard Widget', 'example_dashboard_widget_function');
}

// Hoook into the 'wp_dashboard_setup' action to register our other functions

add_action('wp_dashboard_setup', 'example_add_dashboard_widgets' );

进阶：将widet显示在页面最上方

一般情况下，插件作者应该允许自己的用户通过拖放的方式将widget小工具放在控制板页面的任何位置。目前还没有简单的API可以预排序默认widget，这就意味着用户新加入的widget只能出现在widget列表的最下方。API不增加排序功能，这个问题就一直无法避免。

下面这个钩子函数示例尝试将新widget排列在默认widget上方。该函数手动更改metabox（此处metabox中的管理面板小工具都是同一种类型）的内部数组并将新widget显示在widget列表最上方。

function example_add_dashboard_widgets() {
wp_add_dashboard_widget('example_dashboard_widget', 'Example Dashboard Widget', 'example_dashboard_widget_function');

// Globalize the metaboxes array, this holds all the widgets for wp-admin

global $wp_meta_boxes;

// Get the regular dashboard widgets array
// (which has our new widget already but at the end)

$normal_dashboard = $wp_meta_boxes['dashboard']['normal']['core'];

// Backup and delete our new dashbaord widget from the end of the array

$example_widget_backup = array('example_dashboard_widget' => $normal_dashboard['example_dashboard_widget']);
unset($normal_dashboard['example_dashboard_widget']);

// Merge the two arrays together so our widget is at the beginning

$sorted_dashboard = array_merge($example_widget_backup, $normal_dashboard);

// Save the sorted array back into the original metaboxes

$wp_meta_boxes['dashboard']['normal']['core'] = $sorted_dashboard;
}

可惜的是，以上方法只适用于从来没有调整过widget列表顺序的用户。一旦用户修改了列表顺序，所做修改将优先于以上方法做出的排序，原有widget顶替新widget出现在列表最上方。

进阶：删除控制板widget

在某些情况下，尤其是在多作者博客上，删除管理界面上的widget小工具或许有一定帮助性。虽然说每个作者都可以在界面最上方的“选项设置”中关闭任何一个已有widget，但对不懂技术的作者来说，不显示这些widget或许更好。

要删除控制板小工具，需要在$wp_meta_box数组中手动取消对这些小工具的设置，也可以根据上文介绍的添加widget的方法在wp_dashboard_setup中进行类似操作。

下面是控制板上的所有metabox：

主栏

$wp_meta_boxes['dashboard']['normal']['core']['dashboard_right_now']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_recent_comments']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_incoming_links']
$wp_meta_boxes['dashboard']['normal']['core']['dashboard_plugins']

侧栏

$wp_meta_boxes['dashboard']['side']['core']['dashboard_quick_press']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_recent_drafts']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_primary']
$wp_meta_boxes['dashboard']['side']['core']['dashboard_secondary']

无论需要输出主栏或是侧栏的列表名，都可以使用以下代码（替换数组第二位的normal或core）：

foreach (array_keys($wp_meta_boxes['dashboard']['normal']['core']) as $name){
echo ("<p>");
echo ($name);
echo("</p>");

}

下面的这个函数示例，通过消除quickpress与incomming_links小工具的数组选项来删除这两个小工具。

// Create the function to use in the action hook

function example_remove_dashboard_widgets() {
// Globalize the metaboxes array, this holds all the widgets for wp-admin

global $wp_meta_boxes;

// Remove the quickpress widget

unset($wp_meta_boxes['dashboard']['side']['core']['dashboard_quick_press']);

// Remove the incomming links widget

unset($wp_meta_boxes['dashboard']['normal']['core']['dashboard_incoming_links']);
}

// Hoook into the 'wp_dashboard_setup' action to register our function

add_action('wp_dashboard_setup', 'example_remove_dashboard_widgets' );

整合控制板中的RSS订阅

很多默认的控制板widge整合了对WordPress开发博客和插件资源的订阅。推荐需要在widget中进一步整合RSS订阅的用户看这里。

分类：中文手册