概述

get_the_posts_navigation() 函数用于生成文章分页导航的 HTML 标记，仅在有多页时输出。它基于 $wp_query 对象判断页面数量，并支持自定义导航参数。

关键要点

• 函数返回字符串类型的导航标记，适用于文章列表的分页场景。
• 参数 $args 为可选数组，可自定义 prev_text、next_text、screen_reader_text、aria_label 和 class 等属性。
• 内部使用 get_previous_posts_link() 和 get_next_posts_link() 获取链接，并通过 _navigation_markup() 包装为导航结构。
• 当 $wp_query->max_num_pages 大于 1 时才生成导航，避免单页时输出空标记。
• 在 WordPress 5.5.0 版本添加了 class 参数，5.3.0 版本添加了 aria_label 参数，最初于 4.1.0 版本引入。

代码示例

function get_the_posts_navigation( $args = array() ) {
	global $wp_query;

	$navigation = '';

	// Don't print empty markup if there's only one page.
	if ( $wp_query->max_num_pages > 1 ) {
		// 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'          => __( 'Older posts' ),
				'next_text'          => __( 'Newer posts' ),
				'screen_reader_text' => __( 'Posts navigation' ),
				'aria_label'         => __( 'Posts' ),
				'class'              => 'posts-navigation',
			)
		);

		$next_link = get_previous_posts_link( $args['next_text'] );
		$prev_link = get_next_posts_link( $args['prev_text'] );

		if ( $prev_link ) {
			$navigation .= '' . $prev_link . '';
		}

		if ( $next_link ) {
			$navigation .= '' . $next_link . '';
		}

		$navigation = _navigation_markup( $navigation, $args['class'], $args['screen_reader_text'], $args['aria_label'] );
	}

	return $navigation;
}

注意事项

• 确保在调用此函数前已设置好 $wp_query 对象，例如在文章循环中。
• 参数 $args 中的 aria_label 默认从 screen_reader_text 派生，但可单独指定以增强可访问性。
• 相关函数包括 the_posts_navigation()（用于直接显示导航）、get_previous_posts_link() 和 get_next_posts_link()。