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。一个 "before" 包装器和 "after" 包装器一起形成一个围绕项目的整个HTML包装。包装器通常由一个或多个HTML标签组成。 "before" 包装器通常包含打开标签，而 "after" 包装器包含关闭标签。

页面

此术语可以在各种上下文中使用，但在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

(整数)。默认：10.

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

numbers_wrapper_before

(字符串)。默认：'<ul>'.

页码链接之前的包装器。

numbers_wrapper_after

(字符串)。默认：'</ul>'.

页码链接之后的包装器。

prev_html

(字符串)。默认：'<a href="{URL}" class="paging-prev"></a>'.

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

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

next_html

(字符串)。默认：'<a href="{URL}" class="paging-next"></a>'.

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

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

first_html

(字符串)。默认：'<a href="{URL}" class="paging-first"></a>'.

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

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

last_html

(字符串)。默认：'<a href="{URL}" class="paging-last"></a>'.

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

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

number_html

(字符串)。默认：'<li><a href="{URL}">{PAGE_NUMBER}</a></li>'.

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

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

current_number_html

(字符串)。默认：'<li class="current"><a href="{URL}">{PAGE_NUMBER}</a></li>'.

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

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

limiter_html

(字符串)。默认：'<li class="paging-spacer">...</li>'.

页码链接之间的限制器HTML。

current_page_html

(字符串)。默认：'<span class="paging-label">第 {CURRENT_PAGE} 页，共 {TOTAL_PAGES} 页</span>'.

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

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

renderer

(字符串)。默认：'Carbon_Pagination_Renderer'.

分页渲染器对象的类名。

collection

(字符串)。默认：'Carbon_Pagination_Collection'.

分页项集合对象的类名。

操作与过滤器

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

过滤器

carbon_pagination_default_options

$defaults (数组)。分页的默认选项。

$pagination (Carbon_Pagination)。分页对象。

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

carbon_pagination_current_page_text

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

$item (Carbon_Pagination_Item_Current_Page_Text)。项对象。

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

carbon_pagination_html

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

$item (Carbon_Pagination_Item_HTML)。项对象。

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

carbon_pagination_limiter

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

$item (Carbon_Pagination_Item_Limiter)。项对象。

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

carbon_pagination_page_link

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

$item (Carbon_Pagination_Item_Page)。项对象。

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

carbon_pagination_autogenerate_collection_items

$autogenerate (bool)。True表示自动生成，false表示不生成。

$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)。当前渲染的分页项。

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