分析 `wp_list_pages()` 函数的源码，它是如何递归地生成页面列表的？ - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷们，晚上好！今天咱们不聊风花雪月，就来扒一扒 WordPress 里的一个老牌函数—— wp_list_pages()。这货看起来人畜无害，但骨子里却藏着递归的秘密。今天我们就来把它扒个精光，看看它是如何一层一层地生成页面列表的。

一、wp_list_pages()：初见，似曾相识燕归来

首先，我们得知道 wp_list_pages() 到底是干嘛的。简单来说，它就是用来生成页面列表的。你可以用它在你的主题里输出一个导航菜单，或者生成一个站点地图。

使用方法也很简单，直接在你的模板文件里调用它就行了：

<?php
wp_list_pages();
?>

当然，你也可以给它传递一些参数，来定制生成的列表。比如，你可以指定只显示某些页面，或者按照特定的顺序排列。这些参数都藏在一个数组里，像这样：

<?php
$args = array(
  'title_li'    => 'Pages', // 列表标题
  'depth'       => 1,      // 显示层级
  'sort_column' => 'menu_order, post_title', // 排序方式
);
wp_list_pages( $args );
?>

这里 title_li 指定了列表的标题，depth 指定了显示的层级（1 表示只显示顶级页面），sort_column 指定了排序方式。

二、剥开外衣：wp_list_pages() 的内部结构

wp_list_pages() 本身只是一个门面，真正干活的是另一个函数：_wp_page_template()。 wp_list_pages() 会先处理一下参数，然后把它们传递给 _wp_page_template()。

让我们来简单看一下 wp_list_pages() 的源码（为了便于理解，我做了一些简化）：

function wp_list_pages( $args = '' ) {
  $defaults = array(
    'depth'        => 0,
    'show_date'    => '',
    'date_format'  => get_option('date_format'),
    'child_of'     => 0,
    'exclude'      => '',
    'exclude_tree' => '',
    'include'      => '',
    'meta_key'     => '',
    'meta_value'   => '',
    'authors'      => '',
    'sort_column'  => 'post_title',
    'sort_order'   => '',
    'link_before'  => '',
    'link_after'   => '',
    'walker'       => '',
    'post_type'    => 'page',
    'post_status'  => 'publish'
  );

  $r = wp_parse_args( $args, $defaults );

  extract( $r, EXTR_SKIP );

  $output = '';

  $output = '<ul class="wp-list-pages">' . PHP_EOL;
  $output .= _wp_page_template( $r );
  $output .= '</ul>' . PHP_EOL;

  echo $output;
}

可以看到，wp_list_pages() 主要做了以下几件事：

定义默认参数： $defaults 数组里定义了一堆默认值，比如 depth、sort_column 等。
合并参数： wp_parse_args() 函数会把用户传递的参数和默认参数合并起来。如果用户传递了参数，就用用户的参数；否则就用默认值。
提取参数： extract() 函数会把数组里的键值对提取成变量。这样我们就可以直接用 $depth、$sort_column 等变量了。
调用 _wp_page_template()： 这是最关键的一步，它会调用 _wp_page_template() 函数来生成页面列表。
输出 HTML： 最后，wp_list_pages() 会把生成的 HTML 包裹在一个 <ul> 标签里，然后输出。

三、深入虎穴：_wp_page_template() 的递归奥秘

现在，重头戏来了。_wp_page_template() 才是真正实现递归生成页面列表的地方。让我们来仔细看看它的源码（同样，为了便于理解，我做了一些简化）：

function _wp_page_template( $args = '' ) {
  $defaults = array(
    'depth'        => 0,
    'show_date'    => '',
    'date_format'  => get_option('date_format'),
    'child_of'     => 0,
    'exclude'      => '',
    'exclude_tree' => '',
    'include'      => '',
    'meta_key'     => '',
    'meta_value'   => '',
    'authors'      => '',
    'sort_column'  => 'post_title',
    'sort_order'   => '',
    'link_before'  => '',
    'link_after'   => '',
    'walker'       => '',
    'post_type'    => 'page',
    'post_status'  => 'publish'
  );

  $r = wp_parse_args( $args, $defaults );
  extract( $r, EXTR_SKIP );

  // 获取页面列表
  $pages = get_pages( $r );

  if ( ! $pages )
    return '';

  $output = '';

  // 遍历页面列表
  foreach ( $pages as $page ) {
    $output .= '<li><a href="' . get_permalink($page->ID) . '">' . $page->post_title . '</a>';

    // 递归调用自身，生成子页面列表
    if ( $depth != 0 ) {
      $sub_args = $r;
      $sub_args['child_of'] = $page->ID;
      $sub_args['depth'] = $depth - 1;
      $sub_output = _wp_page_template( $sub_args );

      if ( $sub_output ) {
        $output .= '<ul class="children">' . $sub_output . '</ul>';
      }
    }

    $output .= '</li>';
  }

  return $output;
}

这段代码的核心在于以下几点：

获取页面列表： get_pages() 函数会根据参数 $r 获取符合条件的页面列表。
遍历页面列表： foreach 循环会遍历页面列表，对每个页面生成一个 <li> 标签。
递归调用： 这是最关键的一步。如果 $depth 不为 0，就说明还需要显示子页面。这时，函数会构造一个新的参数数组 $sub_args，把 child_of 设置为当前页面的 ID，把 depth 减 1，然后递归调用自身。
生成子页面列表： 递归调用会生成子页面的列表，然后把它们包裹在一个 <ul class="children"> 标签里，添加到当前页面的 <li> 标签中。

四、庖丁解牛：一步步分析递归过程

为了更好地理解递归过程，我们来举个例子。假设我们有以下页面结构：

- 页面A
  - 页面B
    - 页面C
  - 页面D

现在，我们调用 wp_list_pages()，并设置 depth 为 2。

第一次调用： wp_list_pages() 调用 _wp_page_template()，_wp_page_template() 获取到顶级页面列表（只有页面 A）。
遍历页面 A： _wp_page_template() 遍历到页面 A，生成 <li><a>页面A</a>。
递归调用： 由于 depth 为 2，_wp_page_template() 递归调用自身，child_of 设置为页面 A 的 ID，depth 设置为 1。
第二次调用： 递归调用的 _wp_page_template() 获取到页面 A 的子页面列表（页面 B 和页面 D）。
遍历页面 B： 递归调用的 _wp_page_template() 遍历到页面 B，生成 <li><a>页面B</a>。
再次递归调用： 由于 depth 为 1，递归调用的 _wp_page_template() 再次递归调用自身，child_of 设置为页面 B 的 ID，depth 设置为 0。
第三次调用： 再次递归调用的 _wp_page_template() 获取到页面 B 的子页面列表（页面 C）。
遍历页面 C： 再次递归调用的 _wp_page_template() 遍历到页面 C，生成 <li><a>页面C</a>。
不再递归： 由于 depth 为 0，再次递归调用的 _wp_page_template() 不再递归调用自身。
返回： 再次递归调用的 _wp_page_template() 返回页面 C 的列表。
添加到页面 B： 递归调用的 _wp_page_template() 把页面 C 的列表添加到页面 B 的 <li> 标签中，生成 <ul class="children"><li><a>页面C</a></li></ul>。
继续遍历： 递归调用的 _wp_page_template() 继续遍历到页面 D，生成 <li><a>页面D</a></li>。由于 depth 为 1，它也会递归调用自身，但是页面 D 没有子页面，所以不会生成任何内容。
返回： 递归调用的 _wp_page_template() 返回页面 B 和页面 D 的列表。
添加到页面 A： _wp_page_template() 把页面 B 和页面 D 的列表添加到页面 A 的 <li> 标签中，生成 <ul class="children"><li><a>页面B</a><ul class="children"><li><a>页面C</a></li></ul></li><li><a>页面D</a></li></ul>。
返回： _wp_page_template() 返回整个页面列表。
输出： wp_list_pages() 把整个页面列表包裹在一个 <ul> 标签里，然后输出。

最终生成的 HTML 如下：

<ul class="wp-list-pages">
  <li><a href="#">页面A</a>
    <ul class="children">
      <li><a href="#">页面B</a>
        <ul class="children">
          <li><a href="#">页面C</a></li>
        </ul>
      </li>
      <li><a href="#">页面D</a></li>
    </ul>
  </li>
</ul>

五、参数详解：定制你的页面列表

wp_list_pages() 提供了很多参数，可以让你定制生成的页面列表。下面是一些常用的参数：

参数名	类型	描述
`title_li`	string	列表的标题。如果设置为空字符串，则不显示标题。
`depth`	int	显示的层级。0 表示显示所有层级，1 表示只显示顶级页面，2 表示显示顶级页面和一级子页面，以此类推。
`child_of`	int	只显示指定 ID 页面的子页面。
`exclude`	string	排除指定 ID 的页面，多个 ID 用逗号分隔。
`include`	string	只显示指定 ID 的页面，多个 ID 用逗号分隔。
`sort_column`	string	排序方式。常用的值有 `post_title` (按标题排序)、`menu_order` (按菜单顺序排序)、`post_date` (按发布日期排序)。
`sort_order`	string	排序顺序。常用的值有 `ASC` (升序)、`DESC` (降序)。
`walker`	object	用于遍历页面树的 Walker 对象。你可以自定义 Walker 对象，来实现更复杂的页面列表生成逻辑。
`post_type`	string	要显示的页面类型。默认为 `page`。
`post_status`	string	要显示的页面状态。默认为 `publish`。
`exclude_tree`	string	排除指定 ID 页面的整个子树，多个 ID 用逗号分隔。

六、自定义 Walker：更上一层楼

如果你觉得 wp_list_pages() 的默认行为不够灵活，你可以自定义 Walker 对象，来实现更复杂的页面列表生成逻辑。

Walker 对象是一个用于遍历树形结构的类。WordPress 提供了一个 Walker_Page 类，可以用于遍历页面树。你可以继承 Walker_Page 类，并重写它的 start_lvl()、end_lvl()、start_el()、end_el() 方法，来定制生成的 HTML。

例如，你可以创建一个自定义的 Walker 对象，来给每个页面添加一个自定义的 CSS 类：

class My_Page_Walker extends Walker_Page {
  function start_el( &$output, $page, $depth = 0, $args = array(), $current_object_id = 0 ) {
    $css_class = array('my-custom-class');
    $css_class = apply_filters( 'page_css_class', $css_class, $page, $depth, $args, $current_object_id );
    $args['walker'] = $this;

    $output .= '<li class="' . implode( ' ', $css_class ) . '"><a href="' . get_permalink($page->ID) . '">' . $page->post_title . '</a>';
  }
}

$args = array(
  'walker' => new My_Page_Walker(),
);

wp_list_pages( $args );

这段代码会给每个 <li> 标签添加一个 my-custom-class 类。

七、总结：递归的魅力与陷阱

wp_list_pages() 的递归实现非常巧妙，它能够轻松地生成任意层级的页面列表。但是，递归也存在一些陷阱：

性能问题： 如果页面层级太深，递归调用次数太多，可能会导致性能问题。
堆栈溢出： 极端情况下，递归调用可能会导致堆栈溢出。

因此，在使用 wp_list_pages() 时，要注意控制 depth 的值，避免生成过深的页面列表。如果需要生成非常复杂的页面列表，最好考虑使用其他方法，比如自定义 SQL 查询。

好了，今天的讲座就到这里。希望大家对 wp_list_pages() 的递归实现有了更深入的了解。下次再见！

发表回复 取消回复

发表回复取消回复