README

友好的 Symfony 分页器，用于对一切进行分页

通常，此包基于 Knp Pager 组件。该组件引入了一种不同的分页处理方式。您可以在提供的文档链接中了解更多关于内部逻辑的信息。

注意：请将 knp-components 与此包保持同步。如果您想使用旧版本的 KnpPaginatorBundle，请使用存储库中的 v3.0 或 v4.X 标签，这适用于分页 ODM MongoDB 和 ORM 2.0 查询。

最新更新

有关最新更改的说明，请阅读 CHANGELOG，有关代码中所需更改的说明，请阅读文档的 UPGRADE 章节。

要求

• Knp Pager 组件 >=2.0。
• KnpPaginatorBundle 的 master 版本与 Symfony >=6.4 版本兼容。
• 如果您使用 Twig 模板引擎，则需要 >=3.0 版本的 Twig。

特性

• 不需要初始化特定的适配器。
• 可以根据需要以任何方式进行自定义，例如：分页视图、事件订阅者。
• 根据请求参数添加自定义过滤和排序功能。
• 关注点分离，分页器仅负责生成分页视图，分页视图用于表示。

注意：使用多个分页器需要设置 别名 以保持非冲突参数。

更详细的文档

• 创建 自定义分页订阅者
• 扩展分页类（待定，可能需要进行一些重构）
• 自定义视图模板和参数

安装和配置

使用 Composer 非常简单，运行

composer require knplabs/knp-paginator-bundle

将 PaginatorBundle 添加到您的应用程序内核

如果您不使用 flex（您应该使用），您需要手动启用包

// app/AppKernel.php
public function registerBundles()
{
    return [
        // ...
        new Knp\Bundle\PaginatorBundle\KnpPaginatorBundle(),
        // ...
    ];
}

配置示例

您可以配置默认查询参数名称和模板

YAML

knp_paginator:
    page_range: 5                       # number of links shown in the pagination menu (e.g: you have 10 pages, a page_range of 3, on the 5th page you'll see links to page 4, 5, 6)
    default_options:
        page_name: page                 # page query parameter name
        sort_field_name: sort           # sort field query parameter name
        sort_direction_name: direction  # sort direction query parameter name
        distinct: true                  # ensure distinct results, useful when ORM queries are using GROUP BY statements
        filter_field_name: filterField  # filter field query parameter name
        filter_value_name: filterValue  # filter value query parameter name
    template:
        pagination: '@KnpPaginator/Pagination/sliding.html.twig'     # sliding pagination controls template
        rel_links: '@KnpPaginator/Pagination/rel_links.html.twig'     # <link rel=...> tags template
        sortable: '@KnpPaginator/Pagination/sortable_link.html.twig' # sort link template
        filtration: '@KnpPaginator/Pagination/filtration.html.twig'  # filters template

PHP

// config/packages/paginator.php

<?php declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void
{
    $configurator->extension('knp_paginator', [
        'page_range' => 5,                        // number of links shown in the pagination menu (e.g: you have 10 pages, a page_range of 3, on the 5th page you'll see links
        'default_options' => [
            'page_name' => 'page',                // page query parameter name
            'sort_field_name' => 'sort',          // sort field query parameter name
            'sort_direction_name' => 'direction', // sort direction query parameter name
            'distinct' => true,                   // ensure distinct results, useful when ORM queries are using GROUP BY statements
            'filter_field_name' => 'filterField', // filter field query parameter name
            'filter_value_name' => 'filterValue'  // filter value query parameter name
        ],
        'template' => [
            'pagination' => '@KnpPaginator/Pagination/sliding.html.twig',     // sliding pagination controls template
            'rel_links' => '@KnpPaginator/Pagination/rel_links.html.twig',     // <link rel=...> tags template
            'sortable' => '@KnpPaginator/Pagination/sortable_link.html.twig', // sort link template
            'filtration' => '@KnpPaginator/Pagination/filtration.html.twig'   // filters template
        ]
    ]);
};

额外的分页模板

可以在 knp_paginator.template.pagination 键中直接使用

• @KnpPaginator/Pagination/sliding.html.twig（默认）
• @KnpPaginator/Pagination/bootstrap_v5_pagination.html.twig
• @KnpPaginator/Pagination/twitter_bootstrap_v4_pagination.html.twig
• @KnpPaginator/Pagination/twitter_bootstrap_v3_pagination.html.twig
• @KnpPaginator/Pagination/twitter_bootstrap_pagination.html.twig
• @KnpPaginator/Pagination/foundation_v6_pagination.html.twig
• @KnpPaginator/Pagination/foundation_v5_pagination.html.twig
• @KnpPaginator/Pagination/bulma_pagination.html.twig
• @KnpPaginator/Pagination/semantic_ui_pagination.html.twig
• @KnpPaginator/Pagination/materialize_pagination.html.twig
• @KnpPaginator/Pagination/tailwindcss_pagination.html.twig
• @KnpPaginator/Pagination/uikit_v3_pagination.html.twig

示例 rel 链接标签模板

可以在 knp_paginator.template.rel_links 键中直接使用

• @KnpPaginator/Pagination/rel_links.html.twig（默认）

额外的可排序模板

这可以在knp_paginator.template.sortable键中直接使用

• @KnpPaginator/Pagination/sortable_link.html.twig（默认）
• @KnpPaginator/Pagination/bootstrap_v5_bi_sortable_link.html.twig
• @KnpPaginator/Pagination/bootstrap_v5_fa_sortable_link.html.twig
• @KnpPaginator/Pagination/bootstrap_v5_md_sortable_link.html.twig
• @KnpPaginator/Pagination/twitter_bootstrap_v3_sortable_link.html.twig
• @KnpPaginator/Pagination/twitter_bootstrap_v4_font_awesome_sortable_link.html.twig
• @KnpPaginator/Pagination/twitter_bootstrap_v4_material_design_icons_sortable_link.html.twig
• @KnpPaginator/Pagination/semantic_ui_sortable_link.html.twig
• @KnpPaginator/Pagination/uikit_v3_sortable.html.twig

额外的过滤模板

这可以在knp_paginator.template.filtration键中直接使用

• @KnpPaginator/Pagination/filtration.html.twig（默认）
• @KnpPaginator/Pagination/bootstrap_v5_filtration.html.twig
• @KnpPaginator/Pagination/twitter_bootstrap_v4_filtration.html.twig

使用示例

控制器

目前分页器可以分页

• 数组
• Doctrine\DBAL\Query\QueryBuilder
• Doctrine\ORM\Query
• Doctrine\ORM\QueryBuilder
• Doctrine\ODM\MongoDB\Query\Query
• Doctrine\ODM\MongoDB\Query\Builder
• Doctrine\ODM\PHPCR\Query\Query
• Doctrine\ODM\PHPCR\Query\Builder\QueryBuilder
• Doctrine\Common\Collection\ArrayCollection - 包括任何Doctrine关系集合
• ModelCriteria - Propel ORM查询
• 包含Solarium_Client和Solarium_Query_Select的数组

// App\Controller\ArticleController.php

public function listAction(EntityManagerInterface $em, PaginatorInterface $paginator, Request $request)
{
    $dql   = "SELECT a FROM AcmeMainBundle:Article a";
    $query = $em->createQuery($dql);

    $pagination = $paginator->paginate(
        $query, /* query NOT result */
        $request->query->getInt('page', 1), /*page number*/
        10 /*limit per page*/
    );

    // parameters to template
    return $this->render('article/list.html.twig', ['pagination' => $pagination]);
}

视图

在<head>中

{# rel links for pagination #}
{{ knp_pagination_rel_links(pagination) }}

在<body>中

{# total items count #}
<div class="count">
    {{ pagination.getTotalItemCount }}
</div>
<table>
    <tr>
        {# sorting of properties based on query components #}
        <th>{{ knp_pagination_sortable(pagination, 'Id', 'a.id') }}</th>
        <th{% if pagination.isSorted('a.title') %} class="sorted"{% endif %}>
            {{ knp_pagination_sortable(pagination, 'Title', 'a.title') }}
        </th>
        <th{% if pagination.isSorted(['a.date', 'a.time']) %} class="sorted"{% endif %}>
            {{ knp_pagination_sortable(pagination, 'Release', ['a.date', 'a.time']) }}
        </th>
    </tr>

    {# table body #}
    {% for article in pagination %}
        <tr {% if loop.index is odd %}class="color"{% endif %}>
            <td>{{ article.id }}</td>
            <td>{{ article.title }}</td>
            <td>{{ article.date | date('Y-m-d') }}, {{ article.time | date('H:i:s') }}</td>
        </tr>
    {% endfor %}
</table>
{# display navigation #}
<div class="navigation">
    {{ knp_pagination_render(pagination) }}
</div>

视图中的翻译

翻译以下文本

• %foo% name，翻译键为table_header_name。翻译在域messages中。
• {0} No author|{1} Author|[2,Inf] Authors，翻译键为table_header_author。翻译在域messages中。

translationCount和translationParameters可以组合使用。

<table>
    <tr>
       {# sorting of properties based on query components #}
       <th>{{ knp_pagination_sortable(pagination, 'Id'|trans({foo:'bar'},'messages'), 'a.id' )|raw }}</th>
       <th{% if pagination.isSorted('a.Title') %} class="sorted"{% endif %}>{{ knp_pagination_sortable(pagination, 'Title', 'a.title')|raw }}</th>
       <th>{{ knp_pagination_sortable(pagination, 'Author'|trans({}, 'messages'), 'a.author' )|raw }}</th>
    </tr>

    <!-- Content of the table -->
</table>

添加翻译文件

您也可以通过创建以下名称格式的翻译文件来覆盖翻译：domain.locale.format。因此，为了为该捆绑包创建翻译文件，您需要在project_root/translations/下创建一个KnpPaginatorBundle.tr.yaml文件，并在其中添加您的翻译

label_previous: "Önceki"
label_next: "Sonraki"
filter_searchword: "Arama kelimesi"

如果您为配置设置了默认翻译

framework:
    default_locale: tr

Symfony将自动选择。

依赖注入

您可以通过使用knp_paginator.injectable DIC标签自动将分页器服务注入到另一个服务中。该标签接受一个可选参数paginator，它是应注入的分页器服务的ID。默认为knp_paginator。

接收KnpPaginator服务的类必须实现Knp\Bundle\PaginatorBundle\Definition\PaginatorAwareInterface。如果您太懒，也可以直接扩展Knp\Bundle\PaginatorBundle\Definition\PaginatorAware基类。

⚠警告使用PaginatorAwareInterface是不推荐的，并且可能在未来的版本中删除。您不应依赖于setter注入，而应仅依赖于正确的构造函数注入。使用Symfony内置的自定义注入机制是建议的做法。

延迟服务

如果已安装包symfony/proxy-manager-bridge，则knp_paginator服务将延迟创建。

有关延迟服务的更多信息，请参阅Symfony关于依赖注入的文档。

XML配置示例

<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <parameters>
        <parameter key="my_bundle.paginator_aware.class">MyBundle\Repository\PaginatorAwareRepository</parameter>
    </parameters>

    <services>
        <service id="my_bundle.paginator_aware" class="my_bundle.paginator_aware.class">
            <tag name="knp_paginator.injectable" paginator="knp_paginator" />
        </service>
    </services>
</container>

故障排除

• 请确保在您的Symfony配置中启用了翻译器

framework:
    translator: { fallbacks: ['%locale%'] }

• 如果您的地区不可用，请在translations/KnpPaginatorBundle.en.yml（如有必要，将“en”替换为您自己的语言代码）中创建自己的翻译文件。然后添加以下行

label_next: Next
label_previous: Previous

• 请注意，<rel>链接仅在使用分页时才有意义，它们与排序或过滤无关。

维护者

请首先阅读这篇文章。

该库由以下人员维护（按字母顺序排序）

• @garak
• @polc