next_posts_link()
云策文档标注
概述
next_posts_link() 函数用于在 WordPress 中输出指向下一组文章的链接，通常用于分页导航。它基于当前查询，默认指向较旧的文章，并可通过参数自定义标签和最大页面限制。
关键要点
- 函数输出下一组文章的链接，适用于分页场景，通常与 previous_posts_link() 配对使用。
- 接受两个可选参数：$label（链接文本，默认 null）和 $max_page（最大页面数，默认 0 表示无限制）。
- 若需在 PHP 中获取链接值而非直接输出，应使用 get_next_posts_link()。
- 在自定义 WP_Query 查询时，需传递 $max_page 参数（如 $the_query->max_num_pages）以确保分页正确工作。
- 注意：函数在 mysql.trace_mode 启用时可能静默失败，可通过 ini_set('mysql.trace_mode', 0) 在 functions.php 中修复。
- is_single() 条件影响函数行为：在单篇文章或自定义文章类型页面上，自定义查询的分页链接可能不显示。
代码示例
// 在 WP_Query 循环中使用 next_posts_link()
$paged = ( get_query_var('paged') ) ? get_query_var('paged') : 1;
$the_query = new WP_Query( array(
'cat' => 1,
'paged' => $paged
) );
if ( $the_query->have_posts() ) :
while ( $the_query->have_posts() ) : $the_query->the_post();
the_title();
endwhile;
next_posts_link( __( 'Older Entries', 'textdomain' ), $the_query->max_num_pages );
previous_posts_link( __( 'Newer Entries', 'textdomain' ) );
wp_reset_postdata();
endif;注意事项
- 文章查询通常按时间倒序排列，因此 next_posts_link() 通常指向较旧条目，previous_posts_link() 指向较新条目。
- 使用前可通过 if ( get_next_posts_link() ) 检查链接是否存在，避免输出空链接。
- 相关函数：previous_posts_link() 和 next_post_link()（注意后者用于单篇文章导航）。
原文内容
Displays the next posts page link.
Parameters
$labelstringoptional-
Content for link text.
Default:
null $max_pageintoptional-
Max pages. Default 0.
Source
function next_posts_link( $label = null, $max_page = 0 ) {
echo get_next_posts_link( $label, $max_page );
}
Changelog
| Version | Description |
|---|---|
| 0.71 | Introduced. |
Skip to note 5 content
Codex
Usage when querying the loop with WP_Query
Add the $max_pages parameter to the next_posts_link() function when querying the loop with WP_Query. To get the total amount of pages you can use the ‘max_num_pages’ property of the custom WP_Query object.
// set the "paged" parameter (use 'page' if the query is on a static front page) $paged = ( get_query_var( 'paged' ) ) ? get_query_var( 'paged' ) : 1; // the query $the_query = new WP_Query( array( 'cat' => 1, 'paged' => $paged ); if ( $the_query->have_posts() ) : // the loop while ( $the_query->have_posts() ) : $the_query->the_post(); the_title(); endwhile; // next_posts_link() usage with max_num_pages. next_posts_link( __( 'Older Entries', 'textdomain' ), $the_query->max_num_pages ); previous_posts_link( __( 'Newer Entries', 'textdomain' ) ); // Clean up after the query and pagination. wp_reset_postdata(); else: ?> <p></p> </pre> </div><!-- .comment-content --> <section id='feedback-1297' class='wporg-has-embedded-code feedback hide-if-js' data-comment-count='0'> </section><!-- .feedback --> <footer class='feedback-links wporg-dot-link-list' > <a role="button" class="feedback-login" href="https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fnext_posts_link%2F%3Freplytocom%3D1297%23feedback-editor-1297" rel="nofollow">Log in to add feedback</a></footer> </article><!-- .comment-body --> </li> <li id="comment-6641" data-comment-id="6641" class="comment byuser comment-author-codeamp odd alt thread-odd thread-alt depth-1"> <article id="div-comment-6641" class="comment-body"> <a href="#comment-content-6641" class="screen-reader-text">Skip to note 6 content</a> <header class="comment-meta"> <div class="comment-author vcard"> <span class="comment-author-attribution"> <a href="https://profiles.wordpress.org/codeamp/" rel="external nofollow" class="url">Code Amp</a> </span> <a class="comment-date" href="https://developer.wordpress.org/reference/functions/next_posts_link/#comment-6641"> <time datetime="2023-08-22T08:39:22+00:00"> 3 years ago </time> </a> </div> <div class="user-note-voting" data-nonce="8621c33b75" data-can-vote="false"><a class="user-note-voting-up" title="You must log in to vote on the helpfulness of this note" data-id="6641" data-vote="up" href="https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fnext_posts_link%2F%23comment-6641"><span class="screen-reader-text">You must log in to vote on the helpfulness of this note</span></a><span class="user-note-voting-count " title="100% like this"><span class="screen-reader-text">Vote results for this note: </span>1</span><a class="user-note-voting-down" title="You must log in to vote on the helpfulness of this note" data-id="6641" data-vote="down" href="https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fnext_posts_link%2F%23comment-6641"><span class="screen-reader-text">You must log in to vote on the helpfulness of this note</span></a></div> </header> <!-- .comment-metadata --> <div class="wporg-has-embedded-code comment-content" id="comment-content-6641"> <p><strong>A warning when using with custom queries</strong></p> <p>This function <code>next_posts_link()</code> has a condition to run if <code>is_single()</code> is false.</p> <p>This is good to know when creating custom queries and adding pagination using this function because where you place your custom query can change whether the pagination shows or not.</p> <p>What’s interesting is that:<br /> – <code>is_single()</code> doesn’t work on pages (or media)<br /> – <code>is_single()</code> does work on CPTs and posts</p> <p>So custom queries with this pagination placed on a single page <strong>will work fine</strong>, but add the same custom query + pagination to a single CPT or post, and <strong>it will not show</strong>.</p> </div><!-- .comment-content --> <section id='feedback-6641' class='wporg-has-embedded-code feedback hide-if-js' data-comment-count='0'> </section><!-- .feedback --> <footer class='feedback-links wporg-dot-link-list' > <a role="button" class="feedback-login" href="https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fnext_posts_link%2F%3Freplytocom%3D6641%23feedback-editor-6641" rel="nofollow">Log in to add feedback</a></footer> </article><!-- .comment-body --> </li> <li id="comment-1295" data-comment-id="1295" class="comment byuser comment-author-codex even thread-even depth-1"> <article id="div-comment-1295" class="comment-body"> <a href="#comment-content-1295" class="screen-reader-text">Skip to note 7 content</a> <header class="comment-meta"> <div class="comment-author vcard"> <span class="comment-author-attribution"> <a href="https://profiles.wordpress.org/codex/" rel="external nofollow" class="url">Codex</a> </span> <a class="comment-date" href="https://developer.wordpress.org/reference/functions/next_posts_link/#comment-1295"> <time datetime="2016-02-27T12:10:56+00:00"> 10 years ago </time> </a> </div> <div class="user-note-voting" data-nonce="98655c9d37" data-can-vote="false"><a class="user-note-voting-up" title="You must log in to vote on the helpfulness of this note" data-id="1295" data-vote="up" href="https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fnext_posts_link%2F%23comment-1295"><span class="screen-reader-text">You must log in to vote on the helpfulness of this note</span></a><span class="user-note-voting-count " title=""><span class="screen-reader-text">Vote results for this note: </span>0</span><a class="user-note-voting-down" title="You must log in to vote on the helpfulness of this note" data-id="1295" data-vote="down" href="https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fnext_posts_link%2F%23comment-1295"><span class="screen-reader-text">You must log in to vote on the helpfulness of this note</span></a></div> </header> <!-- .comment-metadata --> <div class="wporg-has-embedded-code comment-content" id="comment-content-1295"> <p><strong>Basic Example</strong></p> <pre class="wp-block-code"><code lang="php" class="language-php ">Skip to note 8 content
Codex
Check if next link exists
if ( get_next_posts_link() ) : next_posts_link( 'Older Entries »', 0 ); endif;