剖析 `register_sidebar()` 函数的源码，解释它如何将侧边栏信息添加到 `Array` 全局变量的？ - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

嘿，各位代码牛仔们，欢迎来到“WordPress侧边栏的秘密花园”讲座！今天咱们要聊聊WordPress里一个看似简单，实则蕴含着不少玄机的函数：register_sidebar()。别看它短短一行代码，却悄悄地操纵着整个侧边栏帝国的命运。咱们要做的就是扒开它的层层外衣，看看它到底是怎么把侧边栏信息塞进那个神秘的 Array 全局变量里的。

第一幕：register_sidebar() 的真面目

首先，让我们来认识一下这位主角：register_sidebar()。它的职责很简单，就是注册一个侧边栏，让用户可以在后台的“外观 -> 小工具”页面里看到它，并且往里面拖拽各种小工具。

它的基本用法是这样的：

register_sidebar(array(
  'name'          => __('我的超级侧边栏', 'textdomain'),
  'id'            => 'my-super-sidebar',
  'description'   => __('这是一个用于展示各种超级小工具的侧边栏', 'textdomain'),
  'before_widget' => '<div id="%1$s" class="widget %2$s">',
  'after_widget'  => '</div>',
  'before_title'  => '<h2 class="widget-title">',
  'after_title'   => '</h2>',
));

这个函数接收一个数组作为参数，数组里包含了侧边栏的各种属性，比如名字、ID、描述、小工具的前后缀等等。

第二幕：深入 register_sidebar() 的源码

光看用法还不够，咱们得深入到源码里，才能真正理解它背后的逻辑。 register_sidebar() 函数位于 wp-includes/widgets.php 文件中。为了方便理解，我们简化一下源码，去掉一些不必要的细节：

function register_sidebar( $args = array() ) {
  global $wp_registered_sidebars;

  $i = count( $wp_registered_sidebars );

  $id_is_valid = true;

  $args = wp_parse_args( $args, array(
    'name'          => sprintf( __( 'Sidebar %d' ), $i + 1 ),
    'id'            => "sidebar-$i",
    'description'   => '',
    'class'         => '',
    'before_widget' => '<li id="%1$s" class="widget %2$s">',
    'after_widget'  => '</li>',
    'before_title'  => '<h2 class="widgettitle">',
    'after_title'   => '</h2>',
  ) );

  $id = sanitize_title( $args['id'] );
  if ( empty( $id ) ) {
    $id_is_valid = false;
  } elseif ( is_numeric( $id ) ) {
    $id_is_valid = false;
  } else {
      $keys = array_keys( $wp_registered_sidebars );
      if ( in_array( $id, $keys ) ) {
          $id_is_valid = false;
      }
  }

  if( !$id_is_valid ) {
      _doing_it_wrong( __FUNCTION__, sprintf( __( '注册侧边栏时提供的无效侧边栏ID: %s' ), esc_html( $args['id'] ) ), '4.2.0' );
      return;
  }

  $args['id'] = $id;

  $wp_registered_sidebars[ $args['id'] ] = $args;

  return true;
}

让我们一行一行地解读这段代码：

global $wp_registered_sidebars;：这一行是关键！它声明了 $wp_registered_sidebars 是一个全局变量。这意味着我们可以在任何地方访问和修改这个变量。这个变量就是一个 Array，用来存储所有注册的侧边栏信息。
$i = count( $wp_registered_sidebars );：这一行获取当前已经注册的侧边栏的数量。 count() 函数会返回数组 $wp_registered_sidebars 中元素的个数。
$args = wp_parse_args( $args, array(...) );： wp_parse_args() 函数用于合并用户传入的参数和默认参数。如果用户没有指定某些参数，就使用默认值。例如，如果用户没有指定 name，就使用 Sidebar %d 作为默认值。
$id = sanitize_title( $args['id'] );: 这一行对侧边栏的ID进行安全处理。sanitize_title() 函数会将ID转换为一个适合URL的字符串，例如将空格替换为连字符，并将所有字符转换为小写。
if( !$id_is_valid ) { ... }: 这部分代码负责验证ID的有效性，确保它不为空，不是纯数字，并且没有被重复使用。如果ID无效，函数会触发一个 _doing_it_wrong() 错误提示并返回。
$wp_registered_sidebars[ $args['id'] ] = $args;：这一行是核心！它将侧边栏的信息添加到 $wp_registered_sidebars 数组中。以侧边栏的 id 作为数组的键，以包含所有属性的 $args 数组作为值。这意味着，我们可以通过侧边栏的 id 来访问它的所有信息。
return true;: 注册成功后返回 true。

第三幕：$wp_registered_sidebars 的数据结构

现在我们知道了 $wp_registered_sidebars 是一个全局数组，那么它的数据结构是什么样的呢？让我们假设我们注册了两个侧边栏：

register_sidebar(array(
  'name' => __('主要侧边栏', 'textdomain'),
  'id' => 'primary-sidebar',
  'description' => __('这是网站的主要侧边栏', 'textdomain'),
));

register_sidebar(array(
  'name' => __('底部侧边栏', 'textdomain'),
  'id' => 'footer-sidebar',
  'description' => __('这是网站的底部侧边栏', 'textdomain'),
));

那么 $wp_registered_sidebars 数组的数据结构大概是这样的：

$wp_registered_sidebars = array(
  'primary-sidebar' => array(
    'name' => '主要侧边栏',
    'id' => 'primary-sidebar',
    'description' => '这是网站的主要侧边栏',
    'class' => '',
    'before_widget' => '<li id="%1$s" class="widget %2$s">',
    'after_widget' => '</li>',
    'before_title' => '<h2 class="widgettitle">',
    'after_title' => '</h2>',
  ),
  'footer-sidebar' => array(
    'name' => '底部侧边栏',
    'id' => 'footer-sidebar',
    'description' => '这是网站的底部侧边栏',
    'class' => '',
    'before_widget' => '<li id="%1$s" class="widget %2$s">',
    'after_widget' => '</li>',
    'before_title' => '<h2 class="widgettitle">',
    'after_title' => '</h2>',
  ),
);

我们可以看到，$wp_registered_sidebars 是一个关联数组，它的键是侧边栏的 id，值是一个包含侧边栏所有属性的数组。

第四幕：如何使用 $wp_registered_sidebars？

既然我们已经知道了 $wp_registered_sidebars 的数据结构，那么我们该如何在代码中使用它呢？最常见的用法是在主题文件中显示侧边栏。 WordPress 提供了 dynamic_sidebar() 函数来实现这个功能。

<?php if ( is_active_sidebar( 'primary-sidebar' ) ) : ?>
  <div id="primary" class="widget-area">
    <?php dynamic_sidebar( 'primary-sidebar' ); ?>
  </div>
<?php endif; ?>

这段代码首先使用 is_active_sidebar() 函数检查 primary-sidebar 是否有小工具。如果有，就使用 dynamic_sidebar() 函数显示侧边栏。

dynamic_sidebar() 函数会根据 $wp_registered_sidebars 数组中的信息，自动生成侧边栏的 HTML 代码。它会循环遍历侧边栏中的所有小工具，并根据 before_widget、after_widget、before_title 和 after_title 属性，将小工具包裹在相应的 HTML 标签中。

第五幕：更深入的挖掘：wp_get_sidebars_widgets()

除了 dynamic_sidebar() 函数之外，还有一个函数也与 $wp_registered_sidebars 密切相关：wp_get_sidebars_widgets()。这个函数返回一个数组，包含了所有侧边栏及其包含的小工具的信息。

$sidebars_widgets = wp_get_sidebars_widgets();

// 打印所有侧边栏的小工具信息
echo '<pre>';
print_r( $sidebars_widgets );
echo '</pre>';

这个函数返回的数组结构大概是这样的：

Array
(
    [wp_inactive_widgets] => Array
        (
            [0] => search-2
            [1] => recent-posts-2
        )

    [sidebar-1] => Array
        (
            [0] => search-3
            [1] => recent-posts-3
            [2] => categories-2
        )

    [sidebar-2] => Array
        (
        )

    [footer-sidebar] => Array
        (
            [0] => meta-2
        )
)

我们可以看到，这个数组的键是侧边栏的 id，值是一个包含小工具 ID 的数组。我们可以使用这个数组来获取特定侧边栏的所有小工具，或者获取所有侧边栏的小工具信息。

第六幕：register_sidebar() 的高级用法

除了基本的用法之外，register_sidebar() 还有一些高级用法，可以让我们更灵活地控制侧边栏的显示。

使用 class 属性添加自定义 CSS 类：

我们可以使用 class 属性为侧边栏添加自定义 CSS 类，方便我们对侧边栏进行样式定制。
```
register_sidebar(array(
  'name' => __('我的超级侧边栏', 'textdomain'),
  'id' => 'my-super-sidebar',
  'class' => 'my-custom-sidebar', // 添加自定义 CSS 类
));
```
然后在 CSS 文件中，我们就可以使用 .my-custom-sidebar 来定制侧边栏的样式。
使用 before_widget 和 after_widget 属性自定义小工具的 HTML 结构：

我们可以使用 before_widget 和 after_widget 属性自定义小工具的 HTML 结构。例如，我们可以将小工具包裹在一个 <div> 标签中，并添加一些自定义的 CSS 类。
```
register_sidebar(array(
  'name' => __('我的超级侧边栏', 'textdomain'),
  'id' => 'my-super-sidebar',
  'before_widget' => '<div id="%1$s" class="widget %2$s my-custom-widget">', // 自定义小工具的前缀
  'after_widget' => '</div>', // 自定义小工具的后缀
));
```
注意：%1$s 会被替换为小工具的 ID，%2$s 会被替换为小工具的 CSS 类。
使用 before_title 和 after_title 属性自定义小工具标题的 HTML 结构：

我们可以使用 before_title 和 after_title 属性自定义小工具标题的 HTML 结构。例如，我们可以将小工具标题包裹在一个 <h2> 标签中，并添加一些自定义的 CSS 类。
```
register_sidebar(array(
  'name' => __('我的超级侧边栏', 'textdomain'),
  'id' => 'my-super-sidebar',
  'before_title' => '<h2 class="widget-title my-custom-title">', // 自定义小工具标题的前缀
  'after_title' => '</h2>', // 自定义小工具标题的后缀
));
```

第七幕：register_sidebar() 的总结与注意事项

我们已经深入了解了 register_sidebar() 函数的源码和用法，现在让我们来总结一下：

register_sidebar() 函数用于注册侧边栏，让用户可以在后台的“外观 -> 小工具”页面里看到它。
register_sidebar() 函数会将侧边栏的信息添加到 $wp_registered_sidebars 全局数组中。
$wp_registered_sidebars 是一个关联数组，它的键是侧边栏的 id，值是一个包含侧边栏所有属性的数组。
可以使用 dynamic_sidebar() 函数在主题文件中显示侧边栏。
可以使用 wp_get_sidebars_widgets() 函数获取所有侧边栏及其包含的小工具的信息。
可以使用 class、before_widget、after_widget、before_title 和 after_title 属性自定义侧边栏的显示效果。

在使用 register_sidebar() 函数时，需要注意以下几点：

侧边栏的 id 必须是唯一的，不能重复。
侧边栏的 id 应该是一个有效的字符串，不能包含空格和特殊字符。
应该使用 __() 函数对侧边栏的 name 和 description 进行本地化处理。

总结

好了，今天的讲座就到这里。希望通过今天的学习，大家对 register_sidebar() 函数有了更深入的理解。记住，理解源码是成为一名优秀的 WordPress 开发者的关键！下次再遇到类似的问题，不要害怕，勇敢地深入到源码中去，你会发现一个全新的世界！感谢大家的参与！

发表回复 取消回复

发表回复取消回复