WordPress 仪表盘小工具接口（Dashboard Widgets API）-IDC资讯中心

本文目录
[隐藏]

1概述
- 1.1相关函数
- 1.2动作钩子
2示例
- 2.1添加一个小工具
- 2.2进阶：将小工具显示在页面最上方
- 2.3进阶：移除仪表盘小工具
- 2.4进阶：创建小工具到侧栏
- 2.5在仪表板中聚合RSS订阅
3小工具选项
- 3.1获取小工具选项
- 3.2获取一个单独的小工具选项
- 3.3更新小工具选项

WordPress 2.7引入了新的仪表盘小工具接口（Dashboard Widgets API），用户可以轻松在管理面板中添加各种小工具。使用仪表盘小工具接口，应具备一定的PHP知识并熟悉WordPress插件API。对熟悉动作钩子（hook）和过滤器钩子（filter）的插件或主题开发人员来说，只要几分钟就可以熟练使用仪表盘小工具接口，并且可以通过小工具接口开发更实用的功能。

概述

动作钩子

运行wp_add_dashboard_widget() 函数前需要连接到相应的动作钩子上（此处即wp_dashboard_setup）。对于多站点网络仪表盘，可以使用 ‘wp_network_dashboard_setup’.

wp_dashboard_setup连接到核心代码：

1	do_action( 'wp_dashboard_setup' );

示例

添加一个小工具

下面是一个非常简单的小工具轮廓：

// 创建一个函数来输出仪表盘小工具的内容
 
function example_dashboard_widget_function() {
	// 输出任何你想要的内容
	echo "你好，我是一个仪表盘小工具";
} 
 
// 创建用语动作钩子的函数
 
function example_add_dashboard_widgets() {
	wp_add_dashboard_widget('example_dashboard_widget', 'Example Dashboard Widget', 'example_dashboard_widget_function');	
} 
 
// 挂载到 'wp_dashboard_setup' 钩子来注册我们其他的函数
 
add_action('wp_dashboard_setup', 'example_add_dashboard_widgets' ); // 提示：如果是多站点网络管理仪表盘，请使用 wp_network_dashboard_setup 替换 wp_dashboard_setup

进阶：将小工具显示在页面最上方

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

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

function example_add_dashboard_widgets() {
	wp_add_dashboard_widget('example_dashboard_widget', 'Example Dashboard Widget', 'example_dashboard_widget_function');
 
	// 全局化 metaboxes 数组, 应用于所有 wp-admin 的小工具
 
	global $wp_meta_boxes;
 
	// 获取常规仪表盘小工具数组 
	// (其中已经包含我们的新的小工具，只是在最底部罢了)
 
	$normal_dashboard = $wp_meta_boxes['dashboard']['normal']['core'];
 
	// 在数组的末端备份并删除我们新的仪表盘小工具
 
	$example_widget_backup = array('example_dashboard_widget' => $normal_dashboard['example_dashboard_widget']);
	unset($normal_dashboard['example_dashboard_widget']);
 
	// 合并这两个数组，使我们的小工具在前面
 
	$sorted_dashboard = array_merge($example_widget_backup, $normal_dashboard);
 
	// 保存排序后的数组到原来的 metaboxes 
 
	$wp_meta_boxes['dashboard']['normal']['core'] = $sorted_dashboard;
}

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

进阶：移除仪表盘小工具

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

要移除仪表盘小工具，我们需要使用 remove_meta_box() 这个函数。请参阅下面的示例代码所需的参数。

下面是默认仪表盘小工具：

// 主栏:
$wp_meta_boxes['dashboard']['normal']['high']['dashboard_browser_nag']
$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']

下面是一个简单的函数来移除快速发布（QuickPress）和链入链接（Incoming Links ）小工具：

// 创建用于动作钩子的函数
 
function example_remove_dashboard_widgets() {
	remove_meta_box( 'dashboard_quick_press', 'dashboard', 'side' );
	remove_meta_box( 'dashboard_incoming_links', 'dashboard', 'normal' );
} 
 
// 挂载到 'wp_dashboard_setup'钩子来注册我们的函数
 
add_action('wp_dashboard_setup', 'example_remove_dashboard_widgets' );

进阶：创建小工具到侧栏

该函数不允许你选择小工具加载的位置和自动添加它到左侧的“核心”中，但是你可以使用它来将你的小工具添加到仪表盘右侧：

// 全局化 $wp_meta_boxes 变量（这将允许我们改变数组）
 global $wp_meta_boxes;
 
 // 备份你的小工具
 $my_widget = $wp_meta_boxes['dashboard']['normal']['core']['{widget id here}'];
 
 // 取消数组中的某些部分
 unset($wp_meta_boxes['dashboard']['normal']['core']['{widget id here}']);
 
 // 加载你想要的小工具
 $wp_meta_boxes['dashboard']['side']['core']['{widget id here}'] = $my_widget;

在仪表板中聚合RSS订阅

如果你需要整合RSS到你的小工具中，你可以看下这个文件的实现方式： /wp-admin/includes/dashboard.php

小工具选项

WordPress 并没有提供内置的方式来获取特定小工具的选项。默认情况下，你需要使用 get_option( ‘dashboard_widget_options’ ) 来获取所有的小工具选项，然后手动过滤返回的数组。本节介绍了一些功能，可以很容易地添加到一个主题或插件，以帮助获取和设置小工具选项。

获取小工具选项

此函数可以获取所有小工具的选项，或者特定小工具的选项：

/**
 * 获取所有小工具的选项，或者某个已经给出ID的特定小工具的选项
 *
 * @param string $widget_id Optional. If provided, will only get options for that widget.
 * @return array An associative array
 */
public static function get_dashboard_widget_options( $widget_id='' )
{
    //从数据库中获取所有小工具的选项
    $opts = get_option( 'dashboard_widget_options' );
 
    //如果没有指定特定小工具的ID，返回所有选项
    if ( empty( $widget_id ) )
        return $opts;
 
    //如果存在我们所检索的小工具选项，就返回
    if ( isset( $opts[$widget_id] ) )
        return $opts[$widget_id];
 
    //当初错时……
    return false;
}

获取一个单独的小工具选项

如果你打算获取一个单独的小工具选项（用来在主题中输出），下面的函数就很有用：

这个例子要用在前面的“获取小工具选项”的函数中：

/**
 * 获取特定小工具的一个单独的选项
 * @param $widget_id
 * @param $option
 * @param null $default
 *
 * @return string
 */
public static function get_dashboard_widget_option( $widget_id, $option, $default=NULL ) {
 
    $opts = get_dashboard_widget_options($widget_id);
 
    //如果小工具选项不存在，返回false
    if ( ! $opts )
        return false;
 
    //否则获取选项或默认选项
    if ( isset( $opts[$option] ) && ! empty($opts[$option]) )
        return $opts[$option];
    else
        return ( isset($default) ) ? $default : false;
 
}

更新小工具选项

该函数可以用来更新一个小工具的所有选项。它还可以用来添加一个小工具选项。只需简单设置 $add_option 参数为 true，而且这个不会覆盖所有已有的选项

/**
 * 保存单个小工具的选项数组到数据库
 * 也可用来设定小工具的默认值
 *
 * @param string $widget_id The name of the widget being updated
 * @param array $args An associative array of options being saved.
 * @param bool $add_only Set to true if you don't want to override any existing options.
 */
public static function update_dashboard_widget_options( $widget_id , $args=array(), $add_only=false )
{
    //从数据库中获取所有仪表盘小工具的选项
    $opts = get_option( 'dashboard_widget_options' );
 
    //获取我们所需的小工具选项，或者设置空数组
    $w_opts = ( isset( $opts[$widget_id] ) ) ? $opts[$widget_id] : array();
 
    if ( $add_only ) {
        //获取缺失的选项(现有的覆盖新的)
        $opts[$widget_id] = array_merge($args,$w_opts);
    }
    else {
        //合并新选项和已有选项，并且返回到小工具数组中
        $opts[$widget_id] = array_merge($w_opts,$args);
    }
 
    //保存整个小工具数组到数据库中
    return update_option('dashboard_widget_options', $opts);
}

原文：http://codex.wordpress.org/Dashboard_Widgets_API
编译：倡萌@WordPress大学

WordPress 仪表盘小工具接口（Dashboard Widgets API）

概述

相关函数