README

关于

Carbon Pagination - 一个方便的WordPress库，用于构建各种分页。

为主题和插件开发者提供了一种简单易行的方式，以构建和实现高度可定制的分页，具体针对他们的需求。

也可以用作WordPress插件。

用法与示例

基本用法

以下示例是显示文章分页的最基本方式（有关所有分页类型，请参阅分页类型），使用默认选项

<?php carbon_pagination('posts'); ?>

如果使用Carbon Pagination作为插件，最好检查该函数是否存在

<?php 
if ( function_exists('carbon_pagination') ) {
	carbon_pagination('posts'); 
}
?>

carbon_pagination()函数是围绕Carbon_Pagination_Presenter类的包装，该类处理分页展示。这意味着您也可以这样做

<?php Carbon_Pagination_Presenter::display('posts'); ?>

当然，如果使用Carbon Pagination作为插件，最好检查该类是否存在

<?php 
if ( class_exists('Carbon_Pagination_Presenter') ) {
	Carbon_Pagination_Presenter::display('posts');
}
?>

指定参数

您可以将您首选的参数指定为carbon_pagination()和Carbon_Pagination_Presenter::display()的第二个参数。示例

<?php 
carbon_pagination('posts', array(
	'wrapper_before' => '<div class="paging">',
	'wrapper_after' => '</div>',
	'enable_first' => false,
	'enable_last' => false,
	'enable_numbers' => false,
	'number_limit' => 5,
)); 
?>

以下是一个示例，包含您可以指定的所有可能的设置，以及它们的默认值。

<?php 
carbon_pagination('posts', array(
	'wrapper_before' => '<div class="paging">',
	'wrapper_after' => '</div>',
	'pages' => array(),
	'current_page' => 1,
	'total_pages' => 1,
	'enable_prev' => true,
	'enable_next' => true,
	'enable_first' => false,
	'enable_last' => false,
	'enable_numbers' => false,
	'enable_current_page_text' => false,
	'number_limit' => -1,
	'large_page_number_limit' => 0,
	'large_page_number_interval' => 10,
	'numbers_wrapper_before' => '<ul>',
	'numbers_wrapper_after' => '</ul>',
	'prev_html' => '<a href="{URL}" class="paging-prev">' . esc_html__( '« Previous Entries', 'crb' ) . '</a>',
	'next_html' => '<a href="{URL}" class="paging-next">' . esc_html__( 'Next Entries »', 'crb' ) . '</a>',
	'first_html' => '<a href="{URL}" class="paging-first"></a>',
	'last_html' => '<a href="{URL}" class="paging-last"></a>',
	'number_html' => '<li><a href="{URL}">{PAGE_NUMBER}</a></li>',
	'current_number_html' => '<li class="current"><a href="{URL}">{PAGE_NUMBER}</a></li>',
	'limiter_html' => '<li class="paging-spacer">...</li>',
	'current_page_html' => '<span class="paging-label">Page {CURRENT_PAGE} of {TOTAL_PAGES}</span>',
	'renderer' => 'Carbon_Pagination_Renderer',
	'collection' => 'Carbon_Pagination_Collection',
)); 
?>

以下是一个示例，初始化了一个类似于Twentyfifteen主题上的分页，包括其标记。这可以轻松替换Twentyfifteen的index.php中的the_posts_pagination()调用

<?php 
carbon_pagination('posts', array(
	'wrapper_before' => '<nav class="navigation pagination"><div class="nav-links">',
	'wrapper_after' => '</div></nav>',
	'prev_html' => '<a class="prev page-numbers" href="{URL}">Previous page</a>',
	'next_html' => '<a class="next page-numbers" href="{URL}">Next page</a>',
	'first_html' => '<a class="prev page-numbers" href="{URL}">First page</a>',
	'last_html' => '<a class="next page-numbers" href="{URL}">Last page</a>',
	'number_html' => '<a class="page-numbers" href="{URL}"><span class="meta-nav screen-reader-text">Page </span>{PAGE_NUMBER}</a>',
	'current_number_html' => '<span class="page-numbers current"><span class="meta-nav screen-reader-text">Page </span>{PAGE_NUMBER}</span>',
	'current_page_html' => '<span class="page-numbers paging-label">Page {CURRENT_PAGE} of {TOTAL_PAGES}</span>',
	'limiter_html' => '<span class="page-numbers dots">…</span>',
	'numbers_wrapper_before' => '',
	'numbers_wrapper_after' => '',
	'enable_numbers' => true,
	'enable_prev' => true,
	'enable_next' => true,
	'enable_numbers' => true,
	'number_limit' => 3,
	'large_page_number_limit' => 1,
));
?>

您可以在配置选项部分中了解更多关于每个设置的信息。

作为对象使用和操作分页

如果您需要操作分页，可以将分页定义为对象

$pagination = new Carbon_Pagination_Posts(array(
	'wrapper_before' => '<div class="paging">',
	'wrapper_after' => '</div>',
));

然后您可以使用Carbon_Pagination或Carbon_Pagination_HTML类的任何get/set方法。示例

// whether the first link is enabled
$first_link_enabled = $pagination->get_enable_first();

// disable first page link
$pagination->set_enable_first(false);

// enable last page link
$pagination->set_enable_last(true);

// disable page number links
$pagination->set_enable_numbers(false);

// set the limit of page number links to 5
$pagination->set_number_limit(5);

最后，当您想要渲染您的分页时，您可以简单地调用

$pagination->render();

术语词典

本节解释并简要描述了在此库中使用的一些术语。

分页

分页是一个构建标记的完整功能集，用于显示多页内容的某些页面链接。这些链接可以包括（但不限于）上一页、下一页、第一页、最后一页或特定页面 - 第2页、第6页等。

包装器

用于在某个项目之前或之后显示某些HTML。一个"之前"包装器和"之后"包装器一起形成一个围绕项目的整个HTML包装。包装器通常由一个或多个HTML标签组成。通常，"之前"包装器包含打开标签，而"之后"包装器包含关闭标签。

页面

此术语可以在各种上下文中使用，但在Carbon Pagination的上下文中，它通常指的是您正在分页（导航）的项目。通常，这些将是数字，从1到总页数，但在某些情况下，这些可以是文章ID或对象 - 无论您想要分页什么。

项目/分页项目

表示分页的特定片段或部分。不同分页项目的示例包括：prev、1、20、last、...、第1页，共20页等等。

数字页面

页码，有时也简称为“号码”，代表一种特定的分页项目，它通过特定的页码来标识。例如页码20将指向第20页。页码可以通过“号码限制”来限制，该限制指定了当前页码两侧将显示多少个项目（-1表示全部，0表示没有，正整数（例如5）表示特定数量的项目）。

大号页码/大页码

一种特定的页码，代表大页码项目。大号页码以一定间隔（默认为10）显示，因此一组示例大号页码将包括：10、20、30等。大号页码可以通过“大号页码限制”来限制，该限制指定了将显示多少个大号页码项目——例如4将显示：10、20、30、40。您还可以更改大页码增长间隔——默认为10，但如果更改为5，大号页码将为：5、10、15、20。

限制器

一种特定的分页项目，通常表示为省略号("...")，当某些页面因某些原因不会显示时，会显示限制器。例如，2、3、4、...、10、20、30——注意数字页码与大号页码之间的...限制器。

数字包装器

表示一个"之前"或"之后"的包装器，但在包装数字页码项目时。数字页码项目包括：数字页码、大数字以及相应的限制器。

当前页HTML

一种特定的分页项目，代表在总页数中指示当前页的文本。它通常以以下方式显示：第1页，共20页。

集合

代表将要渲染的分页项目的集合的类。您可以像操作数组一样完全操作集合。

渲染器

一个将渲染特定分页项目的类。

展示者

一个处理分页展示的类——它用于渲染特定的分页。使用其工厂方法display()，它还可以使用提供的参数初始化、构建和展示一个新的分页。

分页类型

默认情况下，库支持4种分页类型。如果您需要创建新的分页类型，可以轻松扩展库。

在调用分页时，您必须指定您想要显示的类型。默认类型为

帖子

最常用的分页类型。用于在非单页上下文中分页帖子列表——通常在帖子页、所有类型的存档和搜索结果中。此分页使用当前的全局$wp_query，这意味着您可以使用它与自定义查询循环一起使用。

文章

用于在单页上下文中分页文章。通常用于单篇文章——single.php，但也可以用于分页任何已注册的文章类型（包括内建的如page）。使用全局$post来确定当前文章，并分页相同类型的所有其他文章。您可以使用carbon_pagination_post_pagination_query过滤器来过滤检索所有文章的查询——请参阅操作和过滤器部分以获取更多信息。

评论

用于特定帖子的评论分页。通常在“设置 -> 讨论”中启用评论分页时在single.php中使用，但也可以用于非单一上下文中的帖子。当然，您必须执行以下操作才能在非单一循环中列出评论：

global $withcomments;
$withcomments = true;

此分页类型支持对任何已注册帖子类型的帖子评论的分页。

自定义

用于创建自定义灵活的分页。您可以自己指定总页数和当前页。此外，您还需要指定用于构建分页链接的查询变量（默认使用page）。

如果您没有指定当前页和总页数，此分页类型可以用于任何帖子类型（包括page）的单个帖子的内容分页。可以通过使用默认的WordPress快速标记进行分页。

如果您需要更复杂的自定义分页，您可能想扩展此分页类型 - 它由Carbon_Pagination_Custom类表示。

配置选项

您可以通过将它们作为关联数组传递给调用carbon_pagination()、Carbon_Pagination_Presenter::display()或创建任何分页类的新实例时的$args参数来指定这些配置选项（有关完整列表，请参阅Carbon_Pagination::__construct()）。

在部分配置选项（HTML类型的）中，您可以使用占位符。这些占位符将自动替换为来自分页的动态内容（例如页码、页链接URL、总页数等）。

有关如何传递这些配置选项的示例，请参阅使用与示例部分。

可用的配置选项包括

wrapper_before

（字符串）。默认值：'<div class="paging">'.

显示在整个分页之前的HTML。

wrapper_after

（字符串）。默认值：'</div>'.

显示在整个分页之后的HTML。

pages

（数组）。可选。默认值：array().

可以用来包含ID，如果您想通过特定的ID循环而不是连续的页码。如果没有定义，则回退到从1到$total_pages的所有页面的数组。

current_page

（整数）。默认值：1.

当前页码。

total_pages

（整数）。默认值：1.

可用的总页数。如果您已指定pages，则不是必需的。

enable_prev

（布尔值）。默认值：true.

是否显示上一页链接。

enable_next

（布尔值）。默认值：true.

是否显示下一页链接。

enable_first

（布尔值）。默认值：false.

是否显示第一页链接。

enable_last

（布尔值）。默认值：false.

是否显示最后一页链接。

enable_numbers

（布尔值）。默认值：false.

是否显示页码链接。

enable_current_page_text

（布尔值）。默认值：false.

是否显示当前页文本第X页，共Y页。

number_limit

（整数）。默认值：-1.

应显示的页码链接数量。使用0表示只显示当前页项。使用-1表示没有限制（将显示所有页码链接）。这与paginate_links的mid_size参数类似。

large_page_number_limit

（整数）。默认值：0.

应显示的较大页码链接数量。较大的页码可以是：10、20、30等。使用0表示没有（将不显示较大的页码链接）。这与paginate_links的end_size参数类似，但需要与"large_page_number_interval" => 1结合使用才能达到相同的效果。

large_page_number_interval

(int). 默认值: 10.

较大页面链接之间的间隔。如果设置为 5，较大页面号将是 5、10、15、20 等。

numbers_wrapper_before

(string). 默认值: '<ul>'.

页面链接之前的包装器。

numbers_wrapper_after

(string). 默认值: '</ul>'.

页面链接之后的包装器。

prev_html

(string). 默认值: '<a href="{URL}" class="paging-prev"></a>'.

上一页链接的HTML。可以使用以下占位符

• {URL} - 链接URL
• {TITLE} - 文章标题 - 仅适用于文章分页

next_html

(string). 默认值: '<a href="{URL}" class="paging-next"></a>'.

下一页链接的HTML。可以使用以下占位符

• {URL} - 链接URL
• {TITLE} - 文章标题 - 仅适用于文章分页

first_html

(string). 默认值: '<a href="{URL}" class="paging-first"></a>'.

第一页链接的HTML。可以使用以下占位符

• {URL} - 链接URL
• {TITLE} - 文章标题 - 仅适用于文章分页

last_html

(string). 默认值: '<a href="{URL}" class="paging-last"></a>'.

最后一页链接的HTML。可以使用以下占位符

• {URL} - 链接URL
• {TITLE} - 文章标题 - 仅适用于文章分页

number_html

_(string). 默认值: '<li><a href="{URL}">{PAGE_NUMBER}</a></li>'_.

页面链接的HTML。可以使用以下占位符

• {URL} - 链接URL
• {PAGE_NUMBER} - 特定页面号
• {TITLE} - 文章标题 - 仅适用于文章分页

current_number_html

_(string). 默认值: '<li class="current"><a href="{URL}">{PAGE_NUMBER}</a></li>'_.

当前页面号链接的HTML。可以使用以下占位符

• {URL} - 链接URL
• {PAGE_NUMBER} - 特定页面号
• {TITLE} - 文章标题 - 仅适用于文章分页

limiter_html

(string). 默认值: '<li class="paging-spacer">...</li>'.

页面号链接之间的限制器HTML。

current_page_html

_(string). 默认值: '<span class="paging-label">第 {CURRENT_PAGE} 页，共 {TOTAL_PAGES} 页</span>'_.

当前页面文本的HTML。可以使用以下占位符

• {CURRENT_PAGE} - 当前页码
• {TOTAL_PAGES} - 总页数

renderer

(string). 默认值: 'Carbon_Pagination_Renderer'.

分页渲染器对象的类名。

collection

(string). 默认值: 'Carbon_Pagination_Collection'.

分页项集合对象的类名。

操作 & 过滤器

以下操作和过滤器可以让开发者修改默认行为，并在各种情况下挂钩以添加自定义功能。

过滤器

carbon_pagination_default_options

$defaults (array). 分页的默认选项。

$pagination (Carbon_Pagination). 分页对象。

此过滤器允许您修改默认分页选项及其值。

carbon_pagination_current_page_text

$html (string). 此项目的原始HTML，包括任何未解析的占位符。

$item (Carbon_Pagination_Item_Current_Page_Text). 项目对象。

此过滤器允许您修改当前项目文本的HTML。

carbon_pagination_html

$html (string). 此项目的原始HTML，包括任何未解析的占位符。

$item (Carbon_Pagination_Item_HTML). 项目对象。

此过滤器允许您修改HTML项目的HTML。

carbon_pagination_limiter

$html (string). 此项目的原始HTML，包括任何未解析的占位符。

$item (Carbon_Pagination_Item_Limiter). 项目对象。

此过滤器允许您修改限制器项目的HTML。

carbon_pagination_page_link

$html (string). 此项目的原始HTML，包括任何未解析的占位符。

$item (Carbon_Pagination_Item_Page). 项目对象。

此过滤器允许您修改数字页面项的HTML。

carbon_pagination_autogenerate_collection_items

$autogenerate (bool). 自动生成为真，不生成为假。

$collection (Carbon_Pagination_Collection). 集合对象。

此过滤器允许您指定是否自动生成此集合中所有默认分页项。

carbon_pagination_default_collection_items

$item_classes (数组)。自动生成的项目类数组。键是分页对象中的方法名，值是基于这些方法是否为真或假生成的类名。

$collection (Carbon_Pagination_Collection). 集合对象。

此过滤器允许您修改自动生成的默认项目类，以及它们所依赖的分页对象的方法。

carbon_pagination_items_before_render

$items (数组)。将要渲染的项目数组。

$renderer (Carbon_Pagination_Renderer)。渲染对象。

此过滤器允许您修改将要渲染的项目。

carbon_pagination_renderer_output

$output (字符串)。将要渲染的项目输出。

$renderer (Carbon_Pagination_Renderer)。渲染对象。

此过滤器允许您在渲染之前修改项目输出。

carbon_pagination_post_pagination_query

$args (数组)。查询参数。

$pagination (Carbon_Pagination_Post)。文章分页对象。

此过滤器允许您修改分页将要导航通过的文章的查询参数。

carbon_pagination_render_item_html

$html (字符串)。项目的渲染HTML。

$item (Carbon_Pagination_Item)。当前渲染的分页项。

此过滤器允许您修改项目的渲染HTML。

操作

carbon_pagination_collection_after_generate

$collection (Carbon_Pagination_Collection). 集合对象。

此操作在生成默认集合项目后立即调用。

carbon_pagination_before_setup_item

$item (Carbon_Pagination_Item)。当前渲染的分页项。

此操作允许您在设置之前修改项目。

carbon_pagination_after_setup_item

$item (Carbon_Pagination_Item)。当前渲染的分页项。

此操作允许您在设置之后修改项目。