paginate_links()

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 < 2="" )="" {="" return;="" }="" $current="(int)" $args['current'];="" $end_size="(int)" $args['end_size'];="" out="" of="" bounds?="" make="" it="" the="" default.="" if="" (="" $end_size="">< 1="" )="" {="" $end_size="1;" }="" $mid_size="(int)" $args['mid_size'];="" if="" (="" $mid_size="">< 0="" )="" {="" $mid_size="2;" }="" $add_args="$args['add_args'];" $r='' ;="" $page_links="array();" $dots="false;" if="" (="" $args['prev_next']="" &&="" $current="" &&="" 1="">< $current="" )="" :="" $link="str_replace(" '%_%',="" 2="=" $current="" ''="" :="" $args['format'],="" $args['base']="" );="" $link="str_replace(" '%#%',="" $current="" -="" 1,="" $link="" );="" if="" (="" $add_args="" )="" $link="add_query_arg(" $add_args,="" $link="" );="" $link="" .="$args['add_fragment'];" *="" *="" filter="" the="" paginated="" links="" for="" the="" given="" archive="" pages.="" *="" *="" @since="" 3.0.0="" *="" *="" @param="" string="" $link="" the="" paginated="" link="" url.="" */="" $page_links[]='' . $args['prev_text'] . '';
	endif;
	for ( $n = 1; $n <= $total;="" $n++="" )="" :="" if="" (="" $n="=" $current="" )="" :="" $page_links[]="" .="" $args['before_page_number']="" .="" number_format_i18n(="" $n="" )="" .="" $args['after_page_number']="" .="">";
			$dots = true;
		else :
			if ( $args['show_all'] || ( $n <= $end_size="" ||="" (="" $current="" &&="" $n="">= $current - $mid_size && $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 < $total="" ||="" -1="=" $total="" )="" )="" :="" $link="str_replace(" '%_%',="" $args['format'],="" $args['base']="" );="" $link="str_replace(" '%#%',="" $current="" +="" 1,="" $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['next_text'] . '';
	endif;
	switch ( $args['type'] ) {
		case 'array' :
			return $page_links;

		case 'list' :
			$r .= "
	";
			$r .= join("
	", $page_links);
			$r .= "

";
			break;

		default :
			$r = join("
", $page_links);
			break;
	}
	return $r;
}
更新版本 源码位置 使用 被使用
4.9.0 wp-includes/general-template.php:4067 6 16

笔记(Notes)

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

absint()

absint( mixed $maybeint )将值转换为非负整数,也就是取绝对值。Convert a value to non-negative integer.目录锚点:#参数#返回#源码#笔记参数(Parameters)参数类型必填说明$maybeint(mixed)必需要转换为非负整数的数据。返回(Return)(int)非负整数。源码(Source)function absint( $maybeint ) { return abs( intval( $maybeint ) );}/** *...

日期:2020-06-23 10:35:32 浏览:1232

activate_plugin()

activate_plugin( string $plugin, string $redirect = '', bool $network_wide = false, bool $silent = false )尝试激活插件,并在成功时重定向。Attempts activation of plugin in a “sandbox” and redirects on success.目录锚点:#说明#参数#返回#源码#笔记说明(Description)已激活的插件将不会再次尝试激活。其工作方式是在尝试包含插件...

日期:2020-06-23 10:39:26 浏览:981

activate_plugins()

activate_plugins( string|string[]&nbsp;$plugins, string&nbsp;$redirect&nbsp;=&nbsp;'', bool&nbsp;$network_wide&nbsp;=&nbsp;false, bool&nbsp;$silent&nbsp;=&nbsp;false&nbsp;)激活多个插件。Activate multiple plugins.目录锚点:#说明#参数#返回#源码说明(Description)当WP_Error返回时,并不意...

日期:2020-09-08 17:28:27 浏览:1038

activate_sitewide_plugin()

activate_sitewide_plugin()不推荐用于激活仅网络插件的功能。Deprecated functionality for activating a network-only plugin.目录锚点:#说明#返回#源码说明(Description)另见激活插件()返回(Return)无返回值源码(Source)更新版本源码位置使用被使用3.0.0 wp-admin/includes/ms-deprecated.php:5701 function...

日期:2020-09-08 17:28:28 浏览:1736

addslashes_gpc()

addslashes_gpc( string&nbsp;$gpc&nbsp;)添加斜线以转义字符串。Adds slashes to escape strings.目录锚点:#说明#参数#返回#源码说明(Description)如果设置了magic_quotes_gpc,将首先删除斜线,请参见https://www.php.net/magic_quotes更多细节。参数(Parameters)参数类型必填说明 $gpc (string) ...

日期:2020-09-21 12:46:52 浏览:889

addslashes_strings_only()

addslashes_strings_only( mixed&nbsp;$value&nbsp;)仅当提供的值是字符串时才添加斜杠。Adds slashes only if the provided value is a string.目录锚点:#参数#返回#源码参数(Parameters)参数类型必填说明 $value (mixed) 必需 返回(Return)(mixe...

日期:2020-09-24 15:58:41 浏览:1269

add_action()

add_action( string&nbsp;$tag, callable&nbsp;$function_to_add, int&nbsp;$priority&nbsp;=&nbsp;10, int&nbsp;$accepted_args&nbsp;=&nbsp;1&nbsp;)将函数挂接到特定操作上。Hooks a function on to a specific action.目录锚点:#说明#参数#返回#源码#笔记说明(Description)Actions是WordPress核心在执行期间...

日期:2020-09-08 17:28:28 浏览:1128

add_blog_option()

add_blog_option( int&nbsp;$id, string&nbsp;$option, mixed&nbsp;$value&nbsp;)为给定的博客id添加新选项。Add a new option for a given blog id.目录锚点:#说明#参数#返回#源码#笔记说明(Description)不需要序列化值。如果需要序列化该值,则在将其插入数据库之前将对其进行序列化。请记住,资源不能序列化或作为选项添加。可以创建不带值的选项,然后稍后更新这些值。现有选项将不会更新,并执行检...

日期:2020-08-26 10:53:23 浏览:944

add_clean_index()

add_clean_index( string&nbsp;$table, string&nbsp;$index&nbsp;)向指定表添加索引。Adds an index to a specified table.目录锚点:#参数#返回#源码#笔记参数(Parameters)参数类型必填说明 $table (string) 必需 数据库表名。 ...

日期:2020-09-08 17:28:29 浏览:945

add_comments_page()

add_comments_page( string&nbsp;$page_title, string&nbsp;$menu_title, string&nbsp;$capability, string&nbsp;$menu_slug, callable&nbsp;$function&nbsp;=&nbsp;'', int&nbsp;$position&nbsp;=&nbsp;null&nbsp;)将子菜单页添加到“注释”主菜单。Add submenu page to the Comments ma...

日期:2020-08-24 11:14:39 浏览:992