WordPress源码深度解析之：`WordPress`的`Widgets API`：`register_widget()`的底层实现。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位码农朋友们，早上好（或者中午好，下午好，晚上好，甚至凌晨好！取决于你们肝代码的时间）。今天咱们来聊聊WordPress里一个相当实用，但又容易被忽略的家伙——Widgets API，特别是它的核心函数register_widget()。

别看这玩意儿名字平平无奇，它可是WordPress界面定制的幕后功臣。有了它，你就能在侧边栏、页脚等地方随意添加各种小工具，比如文章分类、搜索框、广告等等。咱们今天就扒开它的皮，看看里面到底藏着什么秘密。

一、Widget是个啥？你真的了解它吗？

首先，咱们得搞清楚，啥叫Widget？简单来说，Widget就是WordPress允许你添加到主题侧边栏或者其他“widget areas”的可重用组件。它们通常用于显示信息、提供功能或者让用户与网站互动。

你可以把Widget想象成一块块乐高积木，你可以随意组合它们，搭建出你想要的页面布局。WordPress自带了很多默认Widget，比如“最新文章”、“分类目录”、“搜索”等等。当然，你也可以自己编写Widget，实现各种各样的功能。

二、register_widget()：Widget注册的钥匙

register_widget()函数，顾名思义，就是用来注册Widget的。只有注册过的Widget，才能出现在WordPress后台的“外观 -> 小工具”页面，才能被添加到你的站点中。

这个函数接收一个参数：Widget类的名称（或者类实例）。没错，Widget在WordPress里是用类来定义的。

register_widget( 'My_Awesome_Widget' );

这行代码的意思就是：把名为My_Awesome_Widget的类注册成一个Widget。

三、WP_Widget：Widget类的基石

要想让你的类成为一个真正的Widget，它必须继承自WP_Widget这个基类。WP_Widget类定义了Widget的基本结构和行为，包括：

构造函数：初始化Widget
widget()：输出Widget的内容
form()：生成Widget的设置表单
update()：保存Widget的设置

咱们来看一个简单的Widget类的例子：

<?php
/**
 * 一个简单的Widget示例
 */
class My_Awesome_Widget extends WP_Widget {

    /**
     * 构造函数
     */
    function __construct() {
        parent::__construct(
            'my_awesome_widget', // Base ID
            __( '我的超棒Widget', 'text_domain' ), // Name
            array( 'description' => __( '这是一个超棒的Widget', 'text_domain' ), ) // Args
        );
    }

    /**
     * 输出Widget内容
     *
     * @param array $args
     * @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 __( '你好，世界！', 'text_domain' );
        echo $args['after_widget'];
    }

    /**
     * 生成Widget设置表单
     *
     * @param array $instance
     */
    public function form( $instance ) {
        $title = ! empty( $instance['title'] ) ? $instance['title'] : __( '新标题', 'text_domain' );
        ?>
        <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 esc_attr( $title ); ?>" />
        </p>
        <?php
    }

    /**
     * 保存Widget设置
     *
     * @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

// 注册Widget
function register_my_awesome_widget() {
    register_widget( 'My_Awesome_Widget' );
}
add_action( 'widgets_init', 'register_my_awesome_widget' );

这个例子定义了一个名为My_Awesome_Widget的类，它继承自WP_Widget。这个Widget的功能很简单，就是显示一个标题和一个“你好，世界！”的文本。

注意最后两行代码：

function register_my_awesome_widget() {
    register_widget( 'My_Awesome_Widget' );
}
add_action( 'widgets_init', 'register_my_awesome_widget' );

这里我们定义了一个名为register_my_awesome_widget()的函数，在这个函数里调用了register_widget()函数，把My_Awesome_Widget类注册成一个Widget。然后，我们使用add_action()函数，把register_my_awesome_widget()函数挂载到widgets_init这个action上。

widgets_init是一个WordPress的action，它会在Widget初始化的时候被触发。也就是说，当WordPress加载Widget的时候，它会执行register_my_awesome_widget()函数，从而注册我们的Widget。

四、register_widget()的底层实现：一步一步揭秘

现在，咱们终于要进入今天的重头戏了：register_widget()函数的底层实现。

register_widget()函数位于wp-includes/widgets.php文件中。它的代码并不复杂，主要做了以下几件事：

参数检查： 首先，它会检查传入的参数是否合法。如果传入的不是一个字符串（Widget类的名称）或者一个对象（Widget类的实例），它会直接返回。
实例化Widget类： 如果传入的是一个字符串，它会尝试实例化这个类。如果类不存在，或者实例化失败，它也会直接返回。
检查是否继承自WP_Widget： 它会检查实例化后的对象是否是WP_Widget类的实例。如果不是，它也会直接返回。
添加到全局变量： 如果以上检查都通过了，它会把Widget对象添加到一个名为$wp_widget_factory的全局变量中。$wp_widget_factory是一个WP_Widget_Factory类的实例，它负责管理所有的Widget。

咱们来看一下register_widget()函数的源码（简化版）：

/**
 * Registers a widget.
 *
 * @since 2.8.0
 *
 * @global WP_Widget_Factory $wp_widget_factory
 *
 * @param string|WP_Widget $widget_class The name of the widget class.
 */
function register_widget( $widget_class ) {
    global $wp_widget_factory;

    // 参数检查
    if ( is_string( $widget_class ) ) {
        // 实例化Widget类
        if ( ! class_exists( $widget_class ) ) {
            return;
        }

        $widget_class = new $widget_class();
    }

    // 检查是否继承自WP_Widget
    if ( ! is_a( $widget_class, 'WP_Widget' ) ) {
        return;
    }

    // 添加到全局变量
    $wp_widget_factory->widgets[ $widget_class->id_base ] = $widget_class;
}

可以看到，register_widget()函数的代码非常简洁，主要就是做了一些参数检查和对象添加的操作。

五、WP_Widget_Factory：Widget工厂的秘密

咱们刚才提到了一个名为WP_Widget_Factory的类，它是Widget管理的中心。这个类主要负责以下几件事：

存储所有的Widget对象
根据Widget的ID获取Widget对象
渲染Widget

WP_Widget_Factory类有一个名为widgets的属性，它是一个数组，用于存储所有的Widget对象。数组的键是Widget的id_base属性，值是Widget对象本身。

咱们来看一下WP_Widget_Factory类的源码（简化版）：

/**
 * Widget factory class.
 *
 * @since 2.8.0
 */
class WP_Widget_Factory {

    /**
     * Registered widgets.
     *
     * @since 2.8.0
     * @var array
     */
    public $widgets = array();

    /**
     * PHP4 Constructor - Calls the PHP5 Constructor
     *
     * @deprecated 4.3.0
     */
    public function WP_Widget_Factory() {
        _deprecated_constructor( __CLASS__, '4.3.0',  '__construct()' );
        self::__construct();
    }

    /**
     * Constructor
     *
     * @since 4.3.0
     */
    public function __construct() {}

    /**
     * Registers a widget object.
     *
     * @since 2.8.0
     *
     * @param string $name Widget name.
     * @param WP_Widget $widget_obj WP_Widget object.
     */
    public function register( $name, &$widget_obj ) {
        $this->widgets[ $name ] = &$widget_obj;
    }

    /**
     * Unregisters a widget object.
     *
     * @since 2.8.0
     *
     * @param string $name Widget name.
     */
    public function unregister( $name ) {
        unset( $this->widgets[ $name ] );
    }

    /**
     * Retrieves a widget object.
     *
     * @since 2.8.0
     *
     * @param string $name Widget name.
     * @return WP_Widget|null WP_Widget object if found, null otherwise.
     */
    public function get_widget( $name ) {
        if ( isset( $this->widgets[ $name ] ) ) {
            return $this->widgets[ $name ];
        }

        return null;
    }
}

可以看到，WP_Widget_Factory类的代码也很简单，主要就是维护了一个widgets数组，用于存储和管理所有的Widget对象。

六、Widget的渲染过程：从注册到显示

现在，咱们来梳理一下Widget的整个渲染过程：

注册Widget： 通过register_widget()函数，把Widget类注册到WordPress中。
添加到Widget Area： 在WordPress后台的“外观 -> 小工具”页面，把注册好的Widget拖拽到你想要显示的Widget Area中。
保存设置： 设置Widget的标题、内容等参数，并保存设置。
渲染Widget： 当WordPress渲染页面的时候，它会遍历所有的Widget Area，找到添加到该Widget Area的Widget，并调用Widget的widget()方法，输出Widget的内容。

这个过程可以用一个表格来概括：

步骤	描述	涉及的函数/类
1. 注册Widget	使用`register_widget()`函数将Widget类注册到WordPress中。	`register_widget()`， `WP_Widget_Factory`
2. 添加到Widget Area	在WordPress后台，将注册的Widget拖拽到指定的Widget Area（例如侧边栏、页脚等）。	WordPress后台界面，主题的`functions.php`文件（用于定义Widget Area）
3. 保存设置	配置Widget的标题、内容等参数，并保存设置。	`WP_Widget::form()` (生成表单), `WP_Widget::update()` (保存设置)
4. 渲染Widget	当WordPress渲染页面时，它会遍历所有Widget Area，找到添加到该区域的Widget，并调用Widget的`widget()`方法输出内容。	`WP_Widget::widget()`, 主题的模板文件 (例如 `sidebar.php`, `footer.php`)，`dynamic_sidebar()`

七、一些需要注意的地方

Widget ID： 每个Widget都有一个唯一的ID，用于区分不同的Widget。Widget的ID由id_base属性和Widget的实例编号组成。
Widget Area： Widget Area是主题中用于显示Widget的区域。Widget Area通常位于侧边栏、页脚等地方。
dynamic_sidebar()： dynamic_sidebar()函数用于在主题中显示Widget Area。它会遍历该Widget Area中的所有Widget，并调用它们的widget()方法，输出Widget的内容。
安全问题： 在编写Widget的时候，一定要注意安全问题，防止XSS攻击等。

八、总结：Widget API的魅力

总而言之，WordPress的Widgets API提供了一种灵活、可扩展的方式，让你能够轻松地定制你的网站界面。register_widget()函数是Widgets API的核心，它负责注册Widget，让Widget能够被添加到你的站点中。

通过深入了解register_widget()函数的底层实现，我们可以更好地理解Widgets API的工作原理，从而编写出更加强大、更加灵活的Widget。

希望今天的讲解对大家有所帮助！下次再见！

发表回复 取消回复

发表回复取消回复