WordPress中的paginate_links() 函数参数的详细解释

基本用法示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?php
global $wp_query;
echo paginate_links( array(
    'base'      => str_replace( 999999999, '%#%', esc_url( get_pagenum_link( 999999999 ) ) ),
    'format'    => '/page/%#%',
    'current'   => max( 1, get_query_var( 'paged' ) ),
    'total'     => $wp_query->max_num_pages,
    'prev_next' => true,
    'prev_text' => '',
    'next_text' => 'Next',
    'mid_size'  => 1,
    'end_size'  => 1,
    'type'      => 'plain', // 关键修改：使用 plain 类型
    'add_args'  => false,
    'show_all'  => false,
    'before_page_number' => '',
    'after_page_number'  => '',
) );
?>

核心参数解析

‘base’

1
2
'base' => str_replace( 999999999, '%#%', esc_url( get_pagenum_link( 999999999 ) )

‘format’

1
'format' => '/page/%#%'

显示控制参数

1
2
'prev_text' => '',       // 上一页按钮文本（此处为空）
'next_text' => 'Next',   // 下一页按钮显示 "Next"

高级配置参数

1
2
3
'before_page_number' => '',  // 页码前不添加内容
'after_page_number'  => ''   // 页码后不添加内容

效果示例（假设共5页，当前第3页）

1
2
3
4
5
6
7
8
<a class="prev page-numbers" href="/page/2">«</a>
<a class="page-numbers" href="/page/1">1</a>
<a class="page-numbers" href="/page/2">2</a>
<span class="page-numbers current">3</span>
<a class="page-numbers" href="/page/4">4</a>
<a class="page-numbers" href="/page/5">5</a>
<a class="next page-numbers" href="/page/4">Next</a>

type => ‘list’ 参数详解

修改为列表模式：

1
2
'type' => 'list'  // 将分页结构输出为 <ul> 列表

输出结构对比

原始代码 (type=plain)：

1
2
3
4
5
<a href="/page/1">1</a>
<span class="current">2</span>
<a href="/page/3">3</a>
<a class="next" href="/page/3">Next</a>

修改后 (type=list)：

1
2
3
4
5
6
7
8
<ul class="page-numbers">
    <li><a class="prev page-numbers" href="/page/1">«</a></li>
    <li><a class="page-numbers" href="/page/1">1</a></li>
    <li><span class="page-numbers current">2</span></li>
    <li><a class="page-numbers" href="/page/3">3</a></li>
    <li><a class="next page-numbers" href="/page/3">Next</a></li>
</ul>

使用 list 时的注意事项

不要重复添加 li 标签

1
2
3
4
5
6
7
8
// 错误！会导致双份 <li> 标签
'before_page_number' => '<li>',
'after_page_number'  => '</li>'

// 正确！保持为空
'before_page_number' => '',
'after_page_number'  => ''

CSS 样式控制

1
2
3
4
5
6
7
8
9
/* 自定义列表样式 */
.nav-links ul {
  display: flex;
  list-style: none;
}
.nav-links li:not(:last-child) {
  margin-right: 12px;
}

完整 list 模式示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
<nav class="navigation pagination">
    <ul class="page-numbers">
        <!-- 上一页 -->
        <li>
            <a class="prev page-numbers" href="/page/1">«</a>
        </li>
        
        <!-- 首页 -->
        <li>
            <a class="page-numbers" href="/page/1">1</a>
        </li>
        
        <!-- 当前页 -->
        <li>
            <span class="page-numbers current">2</span>
        </li>
        
        <!-- 中间页 -->
        <li>
            <a class="page-numbers" href="/page/3">3</a>
        </li>
        
        <!-- 跳页省略号 -->
        <li>
            <span class="page-numbers dots">…</span>
        </li>
        
        <!-- 末页 -->
        <li>
            <a class="page-numbers" href="/page/5">5</a>
        </li>
        
        <!-- 下一页 -->
        <li>
            <a class="next page-numbers" href="/page/3">Next</a>
        </li>
    </ul>
</nav>

模式选择建议

特性 plain 模式 list 模式
容器标签 无容器（直接包含链接） <ul>
CSS 控制 需自定义布局 更易实现水平/垂直导航
SEO 友好性 一般 更语义化
默认样式 无样式 有基础列表样式

选择 list 模式的情况：

需要符合 WAI-ARIA 无障碍标准时

使用 CSS Flex/Grid 布局实现复杂分页设计

需要区分移动端/桌面端分页样式时

主题已内置列表样式