云策 WordPress 开发者社区

函数文档

the_post_navigation()

查看官方原文 ↗
💡 云策文档标注

概述

the_post_navigation() 是一个 WordPress 模板标签，用于在单篇文章页面显示上一篇和下一篇文章的导航链接。它基于 get_the_post_navigation() 函数生成输出，适用于开发者自定义导航样式和逻辑。

关键要点

  • 函数直接输出导航 HTML，无返回值，适用于模板文件中快速调用。
  • 接受一个可选数组参数 $args，用于自定义导航行为，如链接文本、同分类法限制等。
  • 参数详情参考 get_the_post_navigation()，包括 prev_text、next_text、in_same_term、taxonomy 等。
  • 自 WordPress 4.1.0 版本引入，是核心链接模板函数的一部分。

代码示例

the_post_navigation( array(
    'prev_text'          => __( 'prev chapter: %title' ),
    'next_text'          => __( 'next chapter: %title' ),
    'in_same_term'       => true,
    'taxonomy'           => __( 'post_tag' ),
    'screen_reader_text' => __( 'Continue Reading' ),
) );

注意事项

  • 导航仅在适用时显示（如存在上一篇或下一篇文章），否则不输出内容。
  • 开发者可通过 get_the_post_navigation() 获取导航 HTML 字符串，以便进行条件判断或进一步处理。
  • 参数 $args 的默认值来自 get_the_post_navigation()，需确保传递正确格式以避免错误。
📄 原文内容

Displays the navigation to next/previous post, when applicable.

Parameters

$argsarrayoptional
See get_the_post_navigation() for available arguments.

More Arguments from get_the_post_navigation( … $args )

Default post navigation arguments.

  • prev_text string
    Anchor text to display in the previous post link.
    Default '%title'.
  • next_text string
    Anchor text to display in the next post link.
    Default '%title'.
  • in_same_term bool
    Whether link should be in the same taxonomy term.
    Default false.
  • excluded_terms int[]|string
    Array or comma-separated list of excluded term IDs.
  • taxonomy string
    Taxonomy, if $in_same_term is true. Default 'category'.
  • screen_reader_text string
    Screen reader text for the nav element.
    Default ‘Post navigation’.
  • aria_label string
    ARIA label text for the nav element. Default 'Posts'.
  • class string
    Custom class for the nav element. Default 'post-navigation'.

Default:array()

Source

function the_post_navigation( $args = array() ) {
	echo get_the_post_navigation( $args );
}

View all references View on Trac View on GitHub

Uses Description
get_the_post_navigation()wp-includes/link-template.php

Retrieves the navigation to next/previous post, when applicable.

Changelog

Version Description
4.1.0 Introduced.

User Contributed Notes

  2. Skip to note 4 content


    talymo36


    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    In order to include a header before the navigation and show it only when the navigation links exist:

    $args = array(
    'prev_text' => sprintf( esc_html__( '%s Older', 'wpdocs_blankslate' ), '<span class="meta-nav"> < </span>' ),
    'next_text' => sprintf( esc_html__( 'Newer %s', 'wpdocs_blankslate' ), '<span class="meta-nav"> > </span>' )
);
$navigation = get_the_post_navigation( $args );
if ( $navigation ) :
    echo '<h4>View More</h4>';
    echo $navigation;
endif;