概述

get_the_post_navigation() 函数用于检索相邻文章的导航链接，当适用时返回包含上一篇文章和下一篇文章链接的 HTML 标记。它接受一个参数数组来自定义导航行为，如链接文本、分类限制和 ARIA 标签。

关键要点

• 函数返回一个字符串，包含上一篇文章和下一篇文章的导航链接标记。
• 参数 $args 是一个可选数组，用于自定义导航，包括 prev_text、next_text、in_same_term、excluded_terms、taxonomy、screen_reader_text、aria_label 和 class。
• 默认情况下，prev_text 和 next_text 使用 '%title' 作为占位符，显示文章标题。
• 如果设置了 screen_reader_text 但未设置 aria_label，则 aria_label 会回退到 screen_reader_text 的值。
• 函数内部使用 get_previous_post_link() 和 get_next_post_link() 生成链接，并通过 _navigation_markup() 包装为导航标记。
• 仅在存在可导航链接时（即 $previous 或 $next 非空）才输出导航标记。

代码示例

function get_the_post_navigation( $args = array() ) {
    // Make sure the nav element has an aria-label attribute: fallback to the screen reader text.
    if ( ! empty( $args['screen_reader_text'] ) && empty( $args['aria_label'] ) ) {
        $args['aria_label'] = $args['screen_reader_text'];
    }

    $args = wp_parse_args(
        $args,
        array(
            'prev_text'          => '%title',
            'next_text'          => '%title',
            'in_same_term'       => false,
            'excluded_terms'     => '',
            'taxonomy'           => 'category',
            'screen_reader_text' => __( 'Post navigation' ),
            'aria_label'         => __( 'Posts' ),
            'class'              => 'post-navigation',
        )
    );

    $navigation = '';

    $previous = get_previous_post_link(
        '%link',
        $args['prev_text'],
        $args['in_same_term'],
        $args['excluded_terms'],
        $args['taxonomy']
    );

    $next = get_next_post_link(
        '%link',
        $args['next_text'],
        $args['in_same_term'],
        $args['excluded_terms'],
        $args['taxonomy']
    );

    // Only add markup if there's somewhere to navigate to.
    if ( $previous || $next ) {
        $navigation = _navigation_markup( $previous . $next, $args['class'], $args['screen_reader_text'], $args['aria_label'] );
    }

    return $navigation;
}

注意事项

• 参数 $args 中的 excluded_terms 可以是整数数组或逗号分隔的字符串列表，用于排除特定分类术语。
• 当 in_same_term 设置为 true 时，链接将限制在同一分类术语内，默认使用 'category' 作为分类法。
• 函数从 WordPress 4.1.0 版本引入，后续版本添加了更多参数，如 class 和 aria_label。