发布于 由admin

深入理解 WordPress `WP_Widget` 类的源码：如何通过继承它来创建自定义小工具，并解释其生命周期。

好吧，各位观众老爷，准备好迎接一场关于WordPress小工具的源码剖析之旅了吗？今天我们就来扒一扒WP_Widget的底裤，看看如何利用它来打造属于你自己的小玩意儿，并深入了解它的生命周期。

第一章：WP_Widget，初次见面请多关照！

首先，让我们来认识一下WP_Widget这位主角。它位于wp-includes/class-wp-widget.php文件中。你可以把它想象成一个模板，或者说是一个基类，你所有的自定义小工具都需要继承它才能工作。

别害怕，源码并没有想象中那么可怕。我们先来看一个最简单的例子：

<?php
/**
 * 我的第一个小工具
 */
class My_Awesome_Widget extends WP_Widget {

    /**
     * 构造函数
     */
    function __construct() {
        parent::__construct(
            'my_awesome_widget', // 小工具的 ID
            __('我的超棒小工具', 'my-awesome-plugin'), // 小工具的名字
            array( 'description' => __( '这是一个超级棒的小工具！', 'my-awesome-plugin' ), ) // 描述
        );
    }

    /**
     * 小工具的前端显示部分
     *
     * @param array $args     由主题提供的 'before_widget', 'after_widget', 'before_title', 'after_title'
     * @param array $instance 小工具的设置选项
     */
    public function widget( $args, $instance ) {
        $title = apply_filters( 'widget_title', $instance['title'] );

        echo $args['before_widget'];
        if ( ! empty( $title ) ) {
            echo $args['before_title'] . $title . $args['after_title'];
        }
        echo __( '你好，世界！我是你的超棒小工具！', 'my-awesome-plugin' );
        echo $args['after_widget'];
    }

    /**
     * 小工具的管理表单
     *
     * @param array $instance 当前的设置选项
     */
    public function form( $instance ) {
        $title = isset( $instance['title'] ) ? esc_attr( $instance['title'] ) : '';
        ?>
        <p>
            <label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e( '标题:' ); ?></label>
            <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; ?>" />
        </p>
        <?php
    }

    /**
     * 更新小工具设置选项
     *
     * @param array $new_instance 新的设置选项
     * @param array $old_instance 旧的设置选项
     * @return array 更新后的设置选项
     */
    public function update( $new_instance, $old_instance ) {
        $instance = array();
        $instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';
        return $instance;
    }
} // class My_Awesome_Widget

// 注册小工具
function register_my_awesome_widget() {
    register_widget( 'My_Awesome_Widget' );
}
add_action( 'widgets_init', 'register_my_awesome_widget' );
?>

把这段代码保存到一个PHP文件中，比如my-awesome-widget.php，然后放到你的插件目录或者主题的functions.php文件中。

代码解释：

  • class My_Awesome_Widget extends WP_Widget: 这就是继承了WP_Widget类，告诉WordPress这是一个小工具。
  • __construct(): 构造函数，用于初始化小工具。
    • parent::__construct(): 调用父类的构造函数，传入小工具的ID、名字和描述。
    • 'my_awesome_widget': 小工具的唯一ID，非常重要！ 别和其他小工具重复了，不然就尴尬了。
    • __('我的超棒小工具', 'my-awesome-plugin'): 小工具的名字，会在小工具列表中显示。 使用__()函数是为了国际化。
    • array( 'description' => __( '这是一个超级棒的小工具！', 'my-awesome-plugin' ) ): 小工具的描述，也会在小工具列表中显示。
  • widget( $args, $instance ): 这个函数负责在前端显示小工具的内容。
    • $args: 这是一个数组，包含了主题提供的widget容器的相关HTML标签，比如before_widget、after_widget、before_title、after_title。 使用这些标签可以保证你的小工具风格和主题一致。
    • $instance: 这是一个数组，包含了小工具的设置选项，比如标题、内容等等。 这些选项是在管理界面设置的，通过form()函数生成的表单。
    • apply_filters( 'widget_title', $instance['title'] ): 这是一个过滤器，允许其他插件或者主题修改小工具的标题。
  • form( $instance ): 这个函数负责生成小工具的管理表单，让用户可以设置小工具的选项。
    • $instance: 当前的设置选项。
    • $this->get_field_id( 'title' ): 生成一个唯一的ID，用于表单元素的id属性。 保证ID的唯一性，防止和其他小工具或者页面元素冲突。
    • $this->get_field_name( 'title' ): 生成一个唯一的name，用于表单元素的name属性。 WordPress会根据这个name来保存设置选项。
  • update( $new_instance, $old_instance ): 这个函数负责更新小工具的设置选项。
    • $new_instance: 用户提交的新设置选项。
    • $old_instance: 之前的设置选项。
    • 在这个函数里，你需要对用户提交的数据进行验证和过滤，然后返回更新后的设置选项。
  • register_my_awesome_widget(): 注册小工具的函数。
  • add_action( 'widgets_init', 'register_my_awesome_widget' ): 在widgets_init钩子上注册小工具。

激活你的插件或者主题，然后去外观 -> 小工具 页面，你就能看到你的“我的超棒小工具”了！

第二章：WP_Widget的内心世界：方法详解

现在我们来更深入地了解一下WP_Widget类中几个重要的方法：

方法名 作用
__construct() 构造函数，用于初始化小工具。 必须调用父类的构造函数，传入小工具的ID、名字和描述。
widget() 小工具的前端显示部分。 接收 $args 和 $instance 两个参数，分别包含主题提供的widget容器的HTML标签和用户设置的选项。
form() 小工具的管理表单。 接收 $instance 参数，包含当前的设置选项。 你需要在这个函数里生成表单，让用户可以设置小工具的选项。 使用 $this->get_field_id() 和 $this->get_field_name() 来生成唯一的ID和name。
update() 更新小工具设置选项。 接收 $new_instance 和 $old_instance 两个参数，分别包含用户提交的新设置选项和之前的设置选项。 你需要对用户提交的数据进行验证和过滤，然后返回更新后的设置选项。
get_field_id() 生成一个唯一的ID，用于表单元素的id属性。
get_field_name() 生成一个唯一的name，用于表单元素的name属性。
get_settings() 获取所有小工具实例的设置。 返回一个数组，键是小工具的实例ID，值是设置选项。
get_field_id_suffix() 获取字段ID的后缀。
number() 获取小工具实例的编号。
id_base() 获取小工具的ID基础。
name() 获取小工具的名称。

更复杂一点的例子：带选项的小工具

现在我们来创建一个更实用的小工具，让用户可以设置标题和显示的文章数量。

<?php
/**
 * 显示最新文章的小工具
 */
class My_Recent_Posts_Widget extends WP_Widget {

    function __construct() {
        parent::__construct(
            'my_recent_posts_widget',
            __('我的最新文章', 'my-awesome-plugin'),
            array( 'description' => __( '显示最新的文章', 'my-awesome-plugin' ), )
        );
    }

    public function widget( $args, $instance ) {
        $title = apply_filters( 'widget_title', $instance['title'] );
        $number = isset( $instance['number'] ) ? absint( $instance['number'] ) : 5; // 默认显示5篇文章

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

        $r = new WP_Query( apply_filters( 'widget_posts_args', array(
            'posts_per_page'      => $number,
            'no_found_rows'       => true,
            'post_status'         => 'publish',
            'ignore_sticky_posts' => true
        ) ) );

        if ( $r->have_posts() ) :
            ?>
            <ul>
                <?php while ( $r->have_posts() ) : $r->the_post(); ?>
                    <li>
                        <a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
                    </li>
                <?php endwhile; ?>
            </ul>
            <?php
            wp_reset_postdata();
        endif;

        echo $args['after_widget'];
    }

    public function form( $instance ) {
        $title = isset( $instance['title'] ) ? esc_attr( $instance['title'] ) : '';
        $number = isset( $instance['number'] ) ? absint( $instance['number'] ) : 5;
        ?>
        <p>
            <label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e( '标题:' ); ?></label>
            <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; ?>" />
        </p>
        <p>
            <label for="<?php echo $this->get_field_id( 'number' ); ?>"><?php _e( '显示文章数量:' ); ?></label>
            <input class="tiny-text" id="<?php echo $this->get_field_id( 'number' ); ?>" name="<?php echo $this->get_field_name( 'number' ); ?>" type="number" step="1" min="1" value="<?php echo $number; ?>" size="3" />
        </p>
        <?php
    }

    public function update( $new_instance, $old_instance ) {
        $instance = array();
        $instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';
        $instance['number'] = ( ! empty( $new_instance['number'] ) ) ? absint( $new_instance['number'] ) : 5;
        return $instance;
    }
} // class My_Recent_Posts_Widget

function register_my_recent_posts_widget() {
    register_widget( 'My_Recent_Posts_Widget' );
}
add_action( 'widgets_init', 'register_my_recent_posts_widget' );
?>

代码解释：

  • 我们在form()函数中添加了一个新的表单字段，用于设置显示的文章数量。
  • 在widget()函数中，我们使用WP_Query类来获取最新的文章，并根据用户设置的数量来显示。
  • 在update()函数中，我们对用户提交的数量进行了验证，确保它是一个整数。

第三章：WP_Widget的生命周期：从生到死

现在让我们来深入了解一下WP_Widget的生命周期，看看它从被创建到被销毁都经历了哪些阶段：

  1. 注册 (Registration):

    • 当WordPress加载你的插件或主题时，register_widget()函数会被调用，将你的小工具类注册到WordPress。
    • 这个过程发生在widgets_init钩子上。

  2. 实例化 (Instantiation):

    • 当用户进入外观 -> 小工具 页面时，或者当主题需要显示小工具时，WordPress会创建你的小工具类的一个实例。
    • 这个过程会调用你的小工具类的构造函数__construct()。

  3. 显示管理表单 (Form Display):

    • 当用户在外观 -> 小工具 页面添加或者编辑你的小工具时，form()函数会被调用，生成小工具的管理表单。

  4. 更新选项 (Update Options):

    • 当用户提交小工具的管理表单时，update()函数会被调用，更新小工具的设置选项。
    • WordPress会将更新后的选项保存到数据库中。

  5. 显示前端 (Frontend Display):

    • 当主题需要显示你的小工具时，widget()函数会被调用，生成小工具的前端内容。
    • widget()函数会接收 $args 和 $instance 两个参数，分别包含主题提供的widget容器的HTML标签和用户设置的选项。

  6. 销毁 (Destruction):

    • 当小工具被从侧边栏移除，或者当主题不再需要显示小工具时，WordPress会销毁你的小工具实例。
    • PHP的垃圾回收机制会自动处理销毁过程。

第四章：WP_Widget的高级玩法：钩子与过滤器

WP_Widget本身也提供了一些钩子和过滤器，让你可以在不同的阶段自定义小工具的行为：

  • widget_title 过滤器:

    • 作用：允许你修改小工具的标题。
    • 位置：widget()函数中，apply_filters( 'widget_title', $instance['title'] )。
    • 示例：
    add_filter( 'widget_title', 'my_awesome_widget_title', 10, 3 );
function my_awesome_widget_title( $title, $instance = array(), $id_base = '' ) {
    if ( $id_base == 'my_recent_posts_widget' ) { // 只修改特定小工具的标题
        $title = '【最新】' . $title;
    }
    return $title;
}

  • widget_posts_args 过滤器:

    • 作用：允许你修改WP_Query的参数，从而改变小工具显示的文章。
    • 位置：widget()函数中，apply_filters( 'widget_posts_args', array(...) )。
    • 示例：
    add_filter( 'widget_posts_args', 'my_awesome_widget_posts_args', 10, 1 );
function my_awesome_widget_posts_args( $args ) {
    $args['category_name'] = '新闻'; // 只显示“新闻”分类下的文章
    return $args;
}

第五章：实战演练：创建一个显示特定分类文章的小工具

为了巩固我们学到的知识，我们来创建一个显示特定分类文章的小工具，用户可以在管理界面设置显示的分类和文章数量。

<?php
/**
 * 显示特定分类文章的小工具
 */
class My_Category_Posts_Widget extends WP_Widget {

    function __construct() {
        parent::__construct(
            'my_category_posts_widget',
            __('我的分类文章', 'my-awesome-plugin'),
            array( 'description' => __( '显示特定分类的文章', 'my-awesome-plugin' ), )
        );
    }

    public function widget( $args, $instance ) {
        $title = apply_filters( 'widget_title', $instance['title'] );
        $category = isset( $instance['category'] ) ? absint( $instance['category'] ) : 0;
        $number = isset( $instance['number'] ) ? absint( $instance['number'] ) : 5;

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

        $r = new WP_Query( apply_filters( 'widget_posts_args', array(
            'posts_per_page'      => $number,
            'no_found_rows'       => true,
            'post_status'         => 'publish',
            'ignore_sticky_posts' => true,
            'cat'                 => $category // 指定分类
        ) ) );

        if ( $r->have_posts() ) :
            ?>
            <ul>
                <?php while ( $r->have_posts() ) : $r->the_post(); ?>
                    <li>
                        <a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
                    </li>
                <?php endwhile; ?>
            </ul>
            <?php
            wp_reset_postdata();
        endif;

        echo $args['after_widget'];
    }

    public function form( $instance ) {
        $title = isset( $instance['title'] ) ? esc_attr( $instance['title'] ) : '';
        $category = isset( $instance['category'] ) ? absint( $instance['category'] ) : 0;
        $number = isset( $instance['number'] ) ? absint( $instance['number'] ) : 5;
        ?>
        <p>
            <label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e( '标题:' ); ?></label>
            <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; ?>" />
        </p>
        <p>
            <label for="<?php echo $this->get_field_id( 'category' ); ?>"><?php _e( '分类:' ); ?></label>
            <?php
            wp_dropdown_categories( array(
                'orderby'            => 'name',
                'hierarchical'       => 1,
                'show_option_all'    => __('所有分类'),
                'show_option_none'   => __('无分类'),
                'name'               => $this->get_field_name( 'category' ),
                'id'                 => $this->get_field_id( 'category' ),
                'selected'           => $category
            ) );
            ?>
        </p>
        <p>
            <label for="<?php echo $this->get_field_id( 'number' ); ?>"><?php _e( '显示文章数量:' ); ?></label>
            <input class="tiny-text" id="<?php echo $this->get_field_id( 'number' ); ?>" name="<?php echo $this->get_field_name( 'number' ); ?>" type="number" step="1" min="1" value="<?php echo $number; ?>" size="3" />
        </p>
        <?php
    }

    public function update( $new_instance, $old_instance ) {
        $instance = array();
        $instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';
        $instance['category'] = ( ! empty( $new_instance['category'] ) ) ? absint( $new_instance['category'] ) : 0;
        $instance['number'] = ( ! empty( $new_instance['number'] ) ) ? absint( $new_instance['number'] ) : 5;
        return $instance;
    }
} // class My_Category_Posts_Widget

function register_my_category_posts_widget() {
    register_widget( 'My_Category_Posts_Widget' );
}
add_action( 'widgets_init', 'register_my_category_posts_widget' );
?>

代码解释：

  • 我们在form()函数中添加了一个新的表单字段，使用wp_dropdown_categories()函数生成一个分类下拉列表。
  • 在widget()函数中，我们使用cat参数来指定要显示的分类。
  • 在update()函数中，我们对用户提交的分类ID进行了验证，确保它是一个整数。

第六章：WP_Widget的注意事项：安全第一！

  • 数据验证和过滤： 在update()函数中，务必对用户提交的数据进行验证和过滤，防止XSS攻击和SQL注入。 使用strip_tags()、esc_attr()、absint()等函数来清理数据。
  • 权限控制： 如果你的小工具涉及到敏感操作，比如修改数据库或者访问私有API，务必进行权限控制，确保只有授权用户才能执行这些操作。
  • 代码规范： 遵循WordPress的代码规范，保持代码的可读性和可维护性。 使用清晰的注释来解释你的代码。
  • 国际化： 使用__()函数来包裹你的文本，以便进行国际化。

第七章：总结与展望

好了，各位观众老爷，今天的WP_Widget源码剖析之旅就到这里了。 希望通过今天的学习，你已经掌握了如何使用WP_Widget类来创建自定义小工具，并深入了解了它的生命周期。

小工具是WordPress的重要组成部分，它可以让你轻松地扩展WordPress的功能，并为用户提供更加个性化的体验。 掌握小工具的开发技巧，可以让你在WordPress的世界里更加游刃有余。

未来，随着WordPress的发展，小工具也会不断进化，出现更多新的特性和功能。 希望大家能够持续学习，不断探索，创造出更加优秀的小工具！

感谢大家的观看，我们下期再见！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注