WordPress如何添加自定义小工具

本文将介绍如何在 WordPress 中创建自定义小工具。自定义小工具允许你扩展侧边栏、页脚等小工具区域的功能，展示特定内容。

创建小工具

要创建一个自定义小工具，你需要定义一个继承自 WP_Widget 基类的 PHP 类，并使用 register_widget() 函数进行注册。该函数必须在 widgets_init 钩子上调用。

下面是一个基础示例，创建一个显示随机文章的小工具：

class Random_Posts_Widget extends WP_Widget {
    // 构造函数，定义小工具基本信息
    function __construct() {
        parent::__construct(
            'random_posts', // 小工具 ID
            __('随机文章', 'text_domain'), // 小工具名称
            array('description' => __('显示随机文章列表', 'text_domain')) // 小工具描述
        );
    }

    // 前端显示小工具内容
    function widget($args, $instance) {
        // 输出小工具容器前的 HTML（如侧边栏定义的 before_widget）
        echo $args['before_widget'];

        // 输出小工具标题
        if (!empty($instance['title'])) {
            echo $args['before_title'] . apply_filters('widget_title', $instance['title']) . $args['after_title'];
        }

        // 查询并显示随机文章
        $query_args = array(
            'posts_per_page' => !empty($instance['number']) ? absint($instance['number']) : 5,
            'orderby' => 'rand'
        );
        $random_posts = new WP_Query($query_args);

        if ($random_posts->have_posts()) {
            echo '
';
            while ($random_posts->have_posts()) {
                $random_posts->the_post();
                echo '
' . get_the_title() . '
';
            }
            echo '
';
            wp_reset_postdata(); // 重置文章数据
        } else {
            echo '
暂无文章。
';
        }

        // 输出小工具容器后的 HTML
        echo $args['after_widget'];
    }
}

// 注册小工具
function register_random_posts_widget() {
    register_widget('Random_Posts_Widget');
}
add_action('widgets_init', 'register_random_posts_widget');

将上述代码添加到主题的 functions.php 文件或一个自定义插件中。之后，在 WordPress 后台的“外观”->“小工具”页面，你就能看到名为“随机文章”的小工具，可以将其拖放到侧边栏等区域。

添加小工具设置选项

为了让用户能自定义小工具内容（如标题、显示文章数量），我们需要在小工具类中实现 form() 和 update() 方法。

form() 方法：在小工具后台生成设置表单。
update() 方法：处理并保存用户提交的表单数据。

以下是增强了设置功能的完整示例：

class Random_Posts_Widget extends WP_Widget {
    function __construct() {
        parent::__construct(
            'random_posts',
            __('随机文章', 'text_domain'),
            array('description' => __('显示随机文章列表', 'text_domain'))
        );
    }

    // 前端显示
    function widget($args, $instance) {
        // 从实例中获取设置值，并设置默认值
        $title = apply_filters('widget_title', !empty($instance['title']) ? $instance['title'] : __('随机文章', 'text_domain'));
        $number = !empty($instance['number']) ? absint($instance['number']) : 5;

        echo $args['before_widget'];
        if (!empty($title)) {
            echo $args['before_title'] . $title . $args['after_title'];
        }

        $query_args = array(
            'posts_per_page' => $number,
            'orderby' => 'rand'
        );
        $random_posts = new WP_Query($query_args);

        if ($random_posts->have_posts()) {
            echo '
';
            while ($random_posts->have_posts()) {
                $random_posts->the_post();
                echo '
' . get_the_title() . '
';
            }
            echo '
';
            wp_reset_postdata();
        } else {
            echo '
暂无文章。
';
        }
        echo $args['after_widget'];
    }

    // 后台设置表单
    function form($instance) {
        // 合并默认值与现有实例值
        $instance = wp_parse_args((array) $instance, array('title' => '', 'number' => 5));
        $title = sanitize_text_field($instance['title']);
        $number = absint($instance['number']);
        ?>