paginate_links( string|array $args = ” )

检索存档文章页的分页链接。
Retrieve paginated link for archive post pages.

目录锚点：#说明#返回#源码#笔记

---

说明（Description）

说明#

说明

从技术上讲，该函数可用于为任何区域创建分页链接列表。“base”参数用于引用url，该url将用于创建分页链接。然后使用“format”参数替换页码。但是，在默认情况下，它很可能用于存档日志页。

“type”参数控制返回值的格式。默认值是’plain’，它只是一个由换行符分隔的链接字符串。其他可能的值是“array”或“list”。“array”值将返回分页链接列表的数组，以提供对显示的完全控制。“list”值将把所有分页的链接放在无序的HTML列表中。

“total”参数是总页数，是整数。“current”参数是当前页码，也是整数。

“base”参数的一个例子是”http://example.com/all_posts.php%“%”是必需的。“%”将被“format”参数中的内容替换。“format”参数的一个例子是“？页=%#%”和“%#%”也是必需的。“%#%”将替换为页码。

通过将“prev_next”参数设置为true（默认为true），可以在列表中包含上一个和下一个链接。可以使用“prev_text”参数设置上一个文本。可以通过设置“next_text”参数来设置下一个文本。

如果“show_all”参数设置为true，则它将显示所有页面，而不是当前页面附近的简短页面列表。默认情况下，“show_all”设置为false，并由“end_size”和“mid_size”参数控制。“end U size”参数是开始列表边和结束列表边上的数字数目，默认为1。“mid_size”参数是当前页两边有多少个数字，但不包括当前页。

可以使用“add_args”参数向链接添加查询变量，有关详细信息，请参阅add_query_arg（）。

“before_page_number”和“after_page_number”参数允许用户自己扩展链接。通常，这可能是将上下文添加到编号的链接，以便屏幕阅读器用户了解链接的用途。文本字符串在页码前后添加–在锚定标记内。

---

返回（Return）

（string|array|void）页面链接的string或页面链接的数组，具体取决于“type”参数。如果总页数小于2，则无效。

---

源码（Source）

/**
* Retrieve paginated link for archive post pages.
*
* Technically, the function can be used to create paginated link list for any
* area. The ‘base’ argument is used to reference the url, which will be used to
* create the paginated links. The ‘format’ argument is then used for replacing
* the page number. It is however, most likely and by default, to be used on the
* archive post pages.
*
* The ‘type’ argument controls format of the returned value. The default is
* ‘plain’, which is just a string with the links separated by a newline
* character. The other possible values are either ‘array’ or ‘list’. The
* ‘array’ value will return an array of the paginated link list to offer full
* control of display. The ‘list’ value will place all of the paginated links in
* an unordered HTML list.
*
* The ‘total’ argument is the total amount of pages and is an integer. The
* ‘current’ argument is the current page number and is also an integer.
*
* An example of the ‘base’ argument is “http://example.com/all_posts.php%_%”
* and the ‘%_%’ is required. The ‘%_%’ will be replaced by the contents of in
* the ‘format’ argument. An example for the ‘format’ argument is “?page=%#%”
* and the ‘%#%’ is also required. The ‘%#%’ will be replaced with the page
* number.
*
* You can include the previous and next links in the list by setting the
* ‘prev_next’ argument to true, which it is by default. You can set the
* previous text, by using the ‘prev_text’ argument. You can set the next text
* by setting the ‘next_text’ argument.
*
* If the ‘show_all’ argument is set to true, then it will show all of the pages
* instead of a short list of the pages near the current page. By default, the
* ‘show_all’ is set to false and controlled by the ‘end_size’ and ‘mid_size’
* arguments. The ‘end_size’ argument is how many numbers on either the start
* and the end list edges, by default is 1. The ‘mid_size’ argument is how many
* numbers to either side of current page, but not including current page.
*
* It is possible to add query vars to the link by using the ‘add_args’ argument
* and see {@link add_query_arg()} for more information.
*
* The ‘before_page_number’ and ‘after_page_number’ arguments allow users to
* augment the links themselves. Typically this might be to add context to the
* numbered links so that screen reader users understand what the links are for.
* The text strings are added before and after the page number – within the
* anchor tag.
*
* @since 2.1.0
*
* @global WP_Query $wp_query
* @global WP_Rewrite $wp_rewrite
*
* @param string|array $args {
* Optional. Array or string of arguments for generating paginated links for archives.
*
* @type string $base Base of the paginated url. Default empty.
* @type string $format Format for the pagination structure. Default empty.
* @type int $total The total amount of pages. Default is the value WP_Query’s
* `max_num_pages` or 1.
* @type int $current The current page number. Default is ‘paged’ query var or 1.
* @type bool $show_all Whether to show all pages. Default false.
* @type int $end_size How many numbers on either the start and the end list edges.
* Default 1.
* @type int $mid_size How many numbers to either side of the current pages. Default 2.
* @type bool $prev_next Whether to include the previous and next links in the list. Default true.
* @type bool $prev_text The previous page text. Default ‘« Previous’.
* @type bool $next_text The next page text. Default ‘« Previous’.
* @type string $type Controls format of the returned value. Possible values are ‘plain’,
* ‘array’ and ‘list’. Default is ‘plain’.
* @type array $add_args An array of query args to add. Default false.
* @type string $add_fragment A string to append to each link. Default empty.
* @type string $before_page_number A string to appear before the page number. Default empty.
* @type string $after_page_number A string to append after the page number. Default empty.
* }
* @return array|string|void String of page links or array of page links.
*/
function paginate_links( $args = ” ) {
global $wp_query, $wp_rewrite;

// Setting up default values based on the current URL.
$pagenum_link = html_entity_decode( get_pagenum_link() );
$url_parts = explode( ‘?’, $pagenum_link );

// Get max pages and current page out of the current query, if available.
$total = isset( $wp_query->max_num_pages ) ? $wp_query->max_num_pages : 1;
$current = get_query_var( ‘paged’ ) ? intval( get_query_var( ‘paged’ ) ) : 1;

// Append the format placeholder to the base URL.
$pagenum_link = trailingslashit( $url_parts[0] ) . ‘%_%’;

// URL base depends on permalink settings.
$format = $wp_rewrite->using_index_permalinks() && ! strpos( $pagenum_link, ‘index.php’ ) ? ‘index.php/’ : ”;
$format .= $wp_rewrite->using_permalinks() ? user_trailingslashit( $wp_rewrite->pagination_base . ‘/%#%’, ‘paged’ ) : ‘?paged=%#%’;

$defaults = array(
‘base’ => $pagenum_link, // http://example.com/all_posts.php%_% : %_% is replaced by format (below)
‘format’ => $format, // ?page=%#% : %#% is replaced by the page number
‘total’ => $total,
‘current’ => $current,
‘show_all’ => false,
‘prev_next’ => true,
‘prev_text’ => __(‘« Previous’),
‘next_text’ => __(‘Next »’),
‘end_size’ => 1,
‘mid_size’ => 2,
‘type’ => ‘plain’,
‘add_args’ => array(), // array of query args to add
‘add_fragment’ => ”,
‘before_page_number’ => ”,
‘after_page_number’ => ”
);

$args = wp_parse_args( $args, $defaults );

if ( ! is_array( $args[‘add_args’] ) ) {
$args[‘add_args’] = array();
}

// Merge additional query vars found in the original URL into ‘add_args’ array.
if ( isset( $url_parts[1] ) ) {
// Find the format argument.
$format = explode( ‘?’, str_replace( ‘%_%’, $args[‘format’], $args[‘base’] ) );
$format_query = isset( $format[1] ) ? $format[1] : ”;
wp_parse_str( $format_query, $format_args );

// Find the query args of the requested URL.
wp_parse_str( $url_parts[1], $url_query_args );

// Remove the format argument from the array of query arguments, to avoid overwriting custom format.
foreach ( $format_args as $format_arg => $format_arg_value ) {
unset( $url_query_args[ $format_arg ] );
}

$args[‘add_args’] = array_merge( $args[‘add_args’], urlencode_deep( $url_query_args ) );
}

// Who knows what else people pass in $args
$total = (int) $args[‘total’];
if ( $total “;
$dots = true;
else :
if ( $args[‘show_all’] || ( $n = $current – $mid_size && $n $total – $end_size ) ) :
$link = str_replace( ‘%_%’, 1 == $n ? ” : $args[‘format’], $args[‘base’] );
$link = str_replace( ‘%#%’, $n, $link );
if ( $add_args )
$link = add_query_arg( $add_args, $link );
$link .= $args[‘add_fragment’];

/** This filter is documented in wp-includes/general-template.php */
$page_links[] = “” . $args[‘before_page_number’] . number_format_i18n( $n ) . $args[‘after_page_number’] . “”;
$dots = true;
elseif ( $dots && ! $args[‘show_all’] ) :
$page_links[] = ” . __( ‘…’ ) . ”;
$dots = false;
endif;
endif;
endfor;
if ( $args[‘prev_next’] && $current && ( $current

更新版本 源码位置 使用 被使用 4.9.0 wp-includes/general-template.php:4067 6 16

---

笔记（Notes）

自定义查询示例
提高无障碍性
基本示例