WordPress Loop（循环）完全指南：从入门到精通

发布于 作者:

WordPress Loop（循环）是主题开发中核心的概念，它负责从数据库中获取文章并按照主题的模板文件进行展示。无论是首页的文章列表、单篇文章的详细内容，还是分类归档页面，都离不开 Loop。简单来说，WordPress Loop 会依次处理当前页面需要展示的每一篇文章，让你能通过模板标签（Template Tags）精确控制每个内容的呈现方式。本文将深入浅出地讲解 Loop 的工作原理、使用方法以及多个实际案例。无论你是刚开始接触 WordPress 主题开发，还是希望进一步理解 Loop 的内部机制，这篇文章都将为你提供清晰的指引。我们会从基础的循环结构讲起，逐步深入到多循环、条件判断等进阶技巧。

什么是 Loop？

WordPress Loop 说白了就是一个 PHP 循环，它负责处理当前页面需要显示的所有文章。每次循环都会从数据库取出一篇文章的数据，然后按照主题的设定来展示这篇文章。

核心机制： 后台“设置 → 阅读”中定义的“每页文章数量”决定了 Loop 一次取多少篇文章。在循环内部，WordPress 会把每篇文章的数据从数据库里提取出来，替换掉模板标签（比如 the_title()、the_content()），终生成你看到的 HTML 页面。

举个例子： 你的首页需要显示 10 篇文章的标题和摘要。Loop 就会跑 10 次，一次处理 1 篇文章，二次处理 2 篇……直到 10 篇结束。

基础 Loop 结构

简单的 Loop 代码如下：

php

<?php
if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        // 在这里放置模板标签，显示文章内容
    endwhile;
endif;
?>

拆解来看：

  • have_posts()：检查有没有文章。有就返回 true，没有就返回 false。
  • while ( have_posts() ) : the_post();：只要还有文章，就继续循环。the_post() 负责把当前文章的数据加载进来，这样后面的模板标签才能用。
  • 循环体里放模板标签，比如 the_title()、the_content() 等，用来显示文章的具体信息。
  • endwhile; 和 endif; 分别结束循环和条件判断。

在主题文件中使用 Loop

Loop 应该放在 index.php 以及其他需要展示文章信息的模板文件中（比如 archive.php、single.php 等）。通常，Loop 放在 get_header() 之后：

php

<?php
get_header();

if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        // 显示文章内容
    endwhile;
else :
    _e( '抱歉，没有找到符合条件的文章。', 'textdomain' );
endif;

get_sidebar();
get_footer();
?>

如果没有任何文章，else 部分会显示一条提示信息。这个 404 提示可以自定义，放在 endwhile 和 endif 之间就行。

Loop 能显示什么？

在 Loop 里，你可以用各种模板标签来控制每篇文章的展示内容。这里列举一些常用的：

模板标签作用
the_title()显示文章标题
the_content()显示文章正文
the_excerpt()显示文章摘要（默认 55 个词）
the_author()显示文章作者
the_category()显示文章所属分类
the_tags()显示文章标签
the_time()显示文章发布时间
the_ID()显示文章 ID
the_post_thumbnail()显示特色图片
next_post_link()下一篇文章的链接
previous_post_link()上一篇文章的链接

条件标签

在 Loop 内部或外部，你都可以用条件标签来判断当前页面类型，从而执行不同的逻辑：

php

if ( is_home() ) {
    // 这是首页
} elseif ( is_single() ) {
    // 这是单篇文章页
} elseif ( is_page() ) {
    // 这是页面
} elseif ( is_category( 'news' ) ) {
    // 这是 news 分类的归档页
} elseif ( is_author() ) {
    // 这是作者归档页
} elseif ( is_search() ) {
    // 这是搜索结果页
} elseif ( is_404() ) {
    // 这是 404 页面
}

实战案例

案例 1：博客首页

大多数博客首页会展示文章标题、特色图和摘要。下面这个 Loop 就能实现：

php

<?php
if ( have_posts() ) :
    while ( have_posts() ) : the_post(); ?>
        <h2><?php the_title(); ?></h2>
        <?php the_post_thumbnail( 'medium' ); ?>
        <?php the_excerpt(); ?>
    <?php endwhile;
else :
    _e( '抱歉，没有找到符合条件的文章。', 'textdomain' );
endif;
?>

案例 2：单篇文章页

在 single.php 中，你可能想展示完整的文章内容和标题：

php

<?php
if ( have_posts() ) :
    while ( have_posts() ) : the_post(); ?>
        <h1><?php the_title(); ?></h1>
        <div class="post-content"><?php the_content(); ?></div>
    <?php endwhile;
else :
    _e( '抱歉，没有找到符合条件的页面。', 'textdomain' );
endif;
?>

案例 3：根据不同分类改变样式

有时候你想让某个特定分类的文章显示得与众不同。比如 ID 为 3 的分类，用不同的 CSS 样式：

php

<?php
if ( have_posts() ) :
    while ( have_posts() ) : the_post();
        if ( in_category( 3 ) ) : ?>
            <div class="post-category-three">
        <?php else : ?>
            <div class="post">
        <?php endif; ?>

            <h2><?php the_title(); ?></h2>
            <p>发布者：<?php the_author_posts_link(); ?></p>
            <div class="entry"><?php the_content(); ?></div>
            <p>分类：<?php the_category( ', ' ); ?></p>

        </div><!-- 结束 .post 或 .post-category-three -->
    <?php endwhile;
else :
    _e( '抱歉，没有找到符合条件的文章。', 'textdomain' );
endif;
?>

这段代码用 in_category( 3 ) 判断文章是否属于 ID 为 3 的分类。如果是，div 的 class 就是 post-category-three，否则就是 post。这样你就可以通过 CSS 给不同分类的文章赋予不同的外观了。

多个 Loop 的使用

有些时候，一个页面需要跑多个 Loop。比如：顶部展示文章标题列表（目录），下方展示完整的文章内容。这种情况有两种处理方法。

方法一：用 rewind_posts() 重置循环

如果你想用同样的查询结果跑两次，可以用 rewind_posts() 把指针重置回开头：

php

<?php
// 一次 Loop：只显示标题
if ( have_posts() ) :
    while ( have_posts() ) : the_post(); ?>
        <h2><?php the_title(); ?></h2>
    <?php endwhile;
endif;

// 重置循环指针
rewind_posts();

// 二次 Loop：显示完整内容
while ( have_posts() ) : the_post(); ?>
    <div><?php the_content(); ?></div>
<?php endwhile; ?>

方法二：用 WP_Query 创建独立查询

更常见的场景是，你需要在页面里展示两组不同的文章。比如：主 Loop 展示当前文章，下面再用一个辅助 Loop 展示同一分类下的其他文章。

php

<?php
// 主 Loop
if ( have_posts() ) :
    while ( have_posts() ) : the_post(); ?>
        <h1><?php the_title(); ?></h1>
        <div><?php the_content(); ?></div>
    <?php endwhile;
endif;
wp_reset_postdata();

// 辅助 Loop：查询 "example-category" 分类下的文章
$secondary_query = new WP_Query( array( 'category_name' => 'example-category' ) );

if ( $secondary_query->have_posts() ) : ?>
    <ul>
    <?php while ( $secondary_query->have_posts() ) : $secondary_query->the_post(); ?>
        <li><?php the_title(); ?></li>
    <?php endwhile; ?>
    </ul>
<?php endif;
wp_reset_postdata();
?>

注意： 使用 WP_Query 创建辅助循环后，一定要用 wp_reset_postdata() 重置全局 $post 数据。否则后面的模板标签可能会指向错误的内容。

重置 Loop 的三种方法

多循环用完后不重置，会导致页面数据混乱。根据不同的场景，有三种重置方式：

函数适用场景
wp_reset_postdata()使用 WP_Query 自定义循环后，常用
wp_reset_query()使用 query_posts() 后（但 query_posts() 本身已不推荐使用）
rewind_posts()同一个查询想跑两次，重置指针位置

使用 wp_reset_postdata() 的完整示例：

php

<?php
$args = array( 'posts_per_page' => 3 );
$the_query = new WP_Query( $args );

if ( $the_query->have_posts() ) :
    while ( $the_query->have_posts() ) : $the_query->the_post(); ?>
        <h2><?php the_title(); ?></h2>
        <?php the_excerpt(); ?>
    <?php endwhile;
else :
    _e( '抱歉，没有找到符合条件的文章。', 'textdomain' );
endif;

wp_reset_postdata();
?>

注意： 不建议使用 query_posts() 修改主 Loop，它会直接改变全局查询，容易造成不可预知的问题。如果需要定制查询，请用 WP_Query 或 pre_get_posts 钩子。

总结

WordPress Loop 是主题开发中绕不开的核心知识点。掌握好 Loop，你就掌握了内容展示的基本逻辑。

几个要点：

  1. 标准结构：if ( have_posts() ) : while ( have_posts() ) : the_post(); ... endwhile; endif; 是基础的写法，任何展示文章的模板都离不开它。
  2. 模板标签：在 Loop 内部，用 the_title()、the_content() 等标签控制每篇文章的输出细节。
  3. 条件判断：用 in_category()、is_single() 等条件标签，可以让不同页面、不同分类展示不同的样式。
  4. 多循环：需要跑多个 Loop 时，用 WP_Query 创建新查询，记得每次用完都用 wp_reset_postdata() 收尾。
  5. 避免 query_posts()：它会在全局层面修改主查询，容易引发问题。推荐用 WP_Query 或 pre_get_posts 过滤器实现定制需求。

把 Loop 用好了，你的 WordPress 主题就能灵活地展示各种内容组合。从简单的博客到复杂的杂志型网站，Loop 都是你手中趁手的工具。