# paginate_links() URL: https://chugunov.pro/api-wordpress/functions/paginate_links/ Проверено на WordPress 6.9, обновлено 06.08.2026. Источник: независимый русскоязычный справочник chugunov.pro. Не является официальной документацией WordPress. Тип: функция. Появился в версии: 2.1.0. ## Сигнатура ```php paginate_links( string|array $args = '' ): string|string[]|null ``` ## Описание Технически функцию можно использовать для создания списка постраничных ссылок для любой области. Аргумент 'base' задаёт URL, на основе которого создаются постраничные ссылки. Аргумент 'format' затем используется для подстановки номера страницы. Тем не менее, чаще всего и по умолчанию она применяется на страницах архивов записей. Аргумент 'type' управляет форматом возвращаемого значения. По умолчанию это 'plain' — просто строка со ссылками, разделёнными символом новой строки. Другие возможные значения — 'array' или 'list'. Значение 'array' возвращает массив списка постраничных ссылок, что даёт полный контроль над отображением. Значение 'list' помещает все постраничные ссылки в неупорядоченный HTML-список. Аргумент 'total' — это общее количество страниц, целое число. Аргумент 'current' — номер текущей страницы, также целое число. Пример аргумента 'base' — «http://example.com/all_posts.php%_%”, и '%_%' обязателен. '%_%' будет заменён содержимым аргумента 'format'. Пример аргумента 'format' — «?page=%#%», и '%#%' также обязателен. '%#%' будет заменён номером страницы. Можно включить ссылки на предыдущую и следующую страницы, установив аргумент 'prev_next' в true, что и является значением по умолчанию. Текст предыдущей страницы задаётся аргументом 'prev_text'. Текст следующей страницы задаётся аргументом 'next_text'. Если аргумент 'show_all' установлен в true, то будут показаны все страницы вместо короткого списка страниц рядом с текущей. По умолчанию 'show_all' установлен в false и управляется аргументами 'end_size' и 'mid_size'. Аргумент 'end_size' — сколько номеров показывать по краям списка, в начале и в конце, по умолчанию 1. Аргумент 'mid_size' — сколько номеров показывать по обе стороны от текущей страницы, не считая саму текущую страницу. К ссылке можно добавить переменные запроса с помощью аргумента 'add_args'; подробнее см. add_query_arg(). Аргументы 'before_page_number' и 'after_page_number' позволяют дополнять сами ссылки. Обычно это делается, чтобы добавить контекст к номерным ссылкам, чтобы пользователи программ чтения с экрана понимали, для чего эти ссылки. Текстовые строки добавляются перед номером страницы и после него — внутри тега-якоря. ## Параметры - `$args` `string|array` — необязательный, по умолчанию `''`. Массив или строка аргументов для генерации постраничных ссылок для архивов. base stringОснова (base) постраничного URL. format stringФормат структуры постраничной навигации. total intОбщее количество страниц. По умолчанию — значение max_num_pages из WP_Query или 1. current intНомер текущей страницы. По умолчанию — переменная запроса 'paged' или 1. aria_current stringЗначение атрибута aria-current. Возможные значения: 'page', 'step', 'location', 'date', 'time', 'true', 'false'. По умолчанию 'page'. show_all boolПоказывать ли все страницы. По умолчанию false. end_size intСколько номеров показывать по краям списка, в начале и в конце. Значение по умолчанию 1. mid_size intСколько номеров показывать по обе стороны от текущей страницы. Значение по умолчанию 2. prev_next boolВключать ли в список ссылки на предыдущую и следующую страницы. По умолчанию true. prev_text stringТекст предыдущей страницы. Значение по умолчанию '« Previous'. next_text stringТекст следующей страницы. Значение по умолчанию 'Next »'. type stringУправляет форматом возвращаемого значения. Возможные значения: 'plain', 'array' и 'list'. По умолчанию 'plain'. add_args arrayМассив переменных запроса для добавления. По умолчанию false. add_fragment stringСтрока, добавляемая к каждой ссылке. before_page_number stringСтрока, выводимая перед номером страницы. after_page_number stringСтрока, добавляемая после номера страницы. ## Возвращаемое значение `string|string[]|null` — 'type' ## Исходный код Файл: `wp-includes/general-template.php:4665` ```php 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 = $wp_query->max_num_pages ?? 1; $current = get_query_var( 'paged' ) ? (int) get_query_var( 'paged' ) : 1; /* * Ensures sites not using trailing slashes get links in the form * `/page/2` rather than `/page/2/`. On these sites, linking to the * URL with a trailing slash will result in a 301 redirect from the * incorrect URL to the correctly formatted one. This presents an * unnecessary performance hit. */ if ( $wp_rewrite->using_permalinks() && ! $wp_rewrite->use_trailing_slashes ) { $pagenum_link = untrailingslashit( $url_parts[0] ); } else { $pagenum_link = trailingslashit( $url_parts[0] ); } $pagenum_link .= '%_%'; // 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=%#%'; if ( $wp_rewrite->using_permalinks() && ! $wp_rewrite->use_trailing_slashes ) { $format = '/' . ltrim( $format, '/' ); } $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, 'aria_current' => 'page', '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 = $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 null; } $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']; $page_links[] = sprintf( '', /** * Filters the paginated links for the given archive pages. * * @since 3.0.0 * * @param string $link The paginated link URL. */ esc_url( apply_filters( 'paginate_links', $link ) ), $args['prev_text'] ); endif; for ( $n = 1; $n <= $total; $n++ ) : if ( $n === $current ) : $page_links[] = sprintf( '%s', esc_attr( $args['aria_current'] ), $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']; $page_links[] = sprintf( '%s', /** This filter is documented in wp-includes/general-template.php */ esc_url( apply_filters( 'paginate_links', $link ) ), $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 ) : $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']; $page_links[] = sprintf( '', /** This filter is documented in wp-includes/general-template.php */ esc_url( apply_filters( 'paginate_links', $link ) ), $args['next_text'] ); endif; switch ( $args['type'] ) { case 'array': return $page_links; case 'list': $r .= "\n"; break; default: $r = implode( "\n", $page_links ); break; } /** * Filters the HTML output of paginated links for archives. * * @since 5.7.0 * * @param string $r HTML output. * @param array $args An array of arguments. See paginate_links() * for information on accepted arguments. */ $r = apply_filters( 'paginate_links_output', $r, $args ); return $r; } ``` ## История изменений - 4.9.0 — Added the aria_current argument. - 2.1.0 — Introduced. ## Связанные Использует: [`wp_parse_str`](https://chugunov.pro/api-wordpress/functions/wp_parse_str/), [`untrailingslashit`](https://chugunov.pro/api-wordpress/functions/untrailingslashit/), [`urlencode_deep`](https://chugunov.pro/api-wordpress/functions/urlencode_deep/), [`get_query_var`](https://chugunov.pro/api-wordpress/functions/get_query_var/), `WP_Query`, [`get_pagenum_link`](https://chugunov.pro/api-wordpress/functions/get_pagenum_link/), [`user_trailingslashit`](https://chugunov.pro/api-wordpress/functions/user_trailingslashit/), `WP_Rewrite::using_index_permalinks`, `WP_Rewrite::using_permalinks`, [`__`](https://chugunov.pro/api-wordpress/functions/__/), [`esc_url`](https://chugunov.pro/api-wordpress/functions/esc_url/), [`esc_attr`](https://chugunov.pro/api-wordpress/functions/esc_attr/), [`trailingslashit`](https://chugunov.pro/api-wordpress/functions/trailingslashit/), [`wp_parse_args`](https://chugunov.pro/api-wordpress/functions/wp_parse_args/), [`add_query_arg`](https://chugunov.pro/api-wordpress/functions/add_query_arg/), [`number_format_i18n`](https://chugunov.pro/api-wordpress/functions/number_format_i18n/), [`apply_filters`](https://chugunov.pro/api-wordpress/functions/apply_filters/). Используется в: [`get_the_posts_pagination`](https://chugunov.pro/api-wordpress/functions/get_the_posts_pagination/), `WP_User_Search::do_paging`, [`media_upload_library_form`](https://chugunov.pro/api-wordpress/functions/media_upload_library_form/), [`wp_nav_menu_item_post_type_meta_box`](https://chugunov.pro/api-wordpress/functions/wp_nav_menu_item_post_type_meta_box/), [`wp_nav_menu_item_taxonomy_meta_box`](https://chugunov.pro/api-wordpress/functions/wp_nav_menu_item_taxonomy_meta_box/), [`paginate_comments_links`](https://chugunov.pro/api-wordpress/functions/paginate_comments_links/). Оригинал в официальной документации: https://developer.wordpress.org/reference/functions/paginate_links/