通用 API – 仪表板小部件

我们常常会听到WordPress的仪表板小组件API，那么这个到底是个什么东西呢。了解这个API是用来做什么的，为什么它对你的WordPress站点如此重要，以及如何轻松地添加小组件到你的仪表板。提升你的站点功能。

什么是仪表板小部件 API

仪表板小部件API是WordPress提供的一套工具，它让你能够轻松地在仪表板上添加、删除或修改小工具。这非常适合那些想要直接与用户交流的人——不管是展示信息还是让用户执行某些动作。

看看这些例子吧：

• Jetpack插件：它能在仪表板上添加一个小工具，让你看到网站的访问统计数据，以及最受欢迎的帖子和页面。
• Seriously Simple Podcasting：这个插件带有Seriously Simple Stats，可以让你查看你的博客统计信息。另外，它还有一个显示Castos新闻的RSS提要小工具——Castos就是开发这个博客插件的公司。

这些API和小工具让你的WordPress仪表板更加强大和个性化，让信息展示和用户互动更加直接和高效。

如何使用仪表板小部件 API

从 WordPress 2.7 版开始，仪表板小部件 API 使向 WordPress 管理仪表板添加新小部件变得简单。你需要了解的主要功能是wp_add_dashboard_widget() function。该函数需要多个参数：

1. $widget_id– 你的小部件的唯一 ID，它也用作小部件 HTML 输出中的 id 属性
2. $widget_name– 你的小部件的名称
3. $callback– 将被调用以输出小部件内容的函数。该函数应该回显小部件的内容

此外，您还可以指定一些可选参数。

1. $control_callback– 一个可选函数，将被调用以输出控件来配置小部件的数据，以及处理控件已提交的任何数据
2. $callback_args– 将传递给回调函数的可选参数数组
3. $context– 一个可选字符串，定义小部件将显示的列。默认值为“正常”，但其他选项包括“side”、“column3”和“column4”
4. $priority– 一个可选字符串，定义上下文中小部件的优先级。默认值为“核心”，但其他选项包括“默认”、“高”和“低”

为了理解它是如何工作的，让我们构建一个示例仪表板小部件

添加仪表板小部件

初始设置和输出

首先，在 wp-content/plugins 目录中创建一个新的插件目录和插件 PHP 文件。对于此示例，你可以将其称为wp-learn-dashboard-widgets.

为了使该插件被识别为 WordPress 插件，你需要添加一个插件标头，至少包含一个插件名称值。

与大多数 WordPress API 一样，你将首先挂钩一个操作。在这种情况下，请使用该wp_dashboard_setup 操作，该操作在仪表板初始化时触发。你将在此处添加我们的小部件。

add_action( 'wp_dashboard_setup', 'wp_learn_dashboard_widget' );
function wp_learn_dashboard_widget(){
    wp_add_dashboard_widget(
        'wp_learn_dashboard_widget',
        'Learn WordPress Dashboard Widget',
        'wp_learn_dashboard_widget_callback'
    );
}

function wp_learn_dashboard_widget_callback(){
    echo '<p>Hello, World!</p>';
}

如果你将此代码添加到空插件文件中，激活插件并加载仪表板，你将在仪表板第一列的底部看到你的小部件。

你的内容回调函数具有很大的灵活性，只要它回显有效的 HTML。

wp_get_recent_posts() 尝试使用函数将最新帖子的列表添加到你的小部件中。

function wp_learn_dashboard_widget_callback(){
    $args = array(
        'numberposts' => 5,
        'post_status' => 'publish'
    );
    $recent_posts = wp_get_recent_posts( $args );
    echo '<ul>';
    foreach( $recent_posts as $recent ){
        echo '<li><a href="' . get_permalink( $recent['ID'] ) . '">' . $recent['post_title'] . '</a></li>';
    }
    echo '</ul>';
}

添加小部件控件

你还可以添加一些控件来配置您的小部件。假设你想要控制显示的帖子数量。为此，请配置控件回调函数。

添加一个调用的函数wp_learn_dashboard_widget_control()来处理数据。

function wp_learn_dashboard_widget_control(){
    echo '<label>Enter number of posts to display</label>';
    echo '<input type="text" name="wp_learn_dashboard_widget_numberposts"/>';
}

当你刷新仪表板时，似乎没有发生任何事情，但如果你将鼠标悬停在小部件上，你将看到一个显示“配置”的新链接。单击该链接将显示你刚刚创建的表单。

现在，你需要更新控件回调来处理表单提交的数据。

保存数据，使用update_option() 函数，该函数会将值存储在选项表中。

function wp_learn_dashboard_widget_control_callback(){
    if (isset($_POST['wp_learn_dashboard_widget_numberposts'])){
        update_option( 'wp_learn_dashboard_widget_numberposts', sanitize_text_field( $_POST['wp_learn_dashboard_widget_numberposts'] ) );
    }
    $number_posts = get_option( 'wp_learn_dashboard_widget_numberposts', 5 );
    echo '<label>Enter number of posts to display</label>';
    echo '<input type="text" name="wp_learn_dashboard_widget_numberposts" value='.$number_posts.' />';
}

然后，你需要返回到内容回调函数并更新数组$args以使用刚刚保存的值。要获取该值，你可以使用该get_option()函数。

function wp_learn_dashboard_widget_callback(){
    $numberposts = get_option( 'wp_learn_dashboard_widget_numberposts', 5 );
    $args = array(
        'numberposts' => $numberposts,
        'post_status' => 'publish'
    );
    $recent_posts = wp_get_recent_posts( $args );
    echo '<ul>';
    foreach( $recent_posts as $recent ){
        echo '<li><a href="' . get_permalink( $recent['ID'] ) . '">' . $recent['post_title'] . '</a></li>';
    }
    echo '</ul>';
}

结论

有关使用仪表板小部件的更多信息，包括如何使用可选回调参数、上下文和优先级参数的示例，请查看developer.wordpress.org 上的仪表板小部件 API 部分。