README

简介

此 Symfony 扩展包通过路由配置和 Twig 模板渲染提供面包屑的集成。此扩展包受到了已停用的 thormeier/breadcrumb-bundle 的极大启发。

要求

Symfony >= 6.0.*
php >= 8.0

安装

步骤 1: Composer require

$ composer require azri/symfony-breadcrumb

步骤 2: 在 kernel 中启用扩展包

<?php
// config/bundles.php

return [
    // ...
    Azri\BreadcrumbBundle\AzriBreadcrumbBundle::class => ['all' => true],
];

配置

在您的 config/azri_breadcrumb.yaml 中启用扩展包

# config/azri_breadcrumb.yaml
azri_breadcrumb: ~

默认模板非常基础，提供了一个 <ul>，其中包含每个面包屑的 <li> 和 <a>。

用法

基本

通过路由的 defaults 中的 label 和 parent_route 字段创建面包屑树。基本树示例

# routing.yml

acme_demo_home:
    path: /
    options:
        breadcrumb:
            label: Home

acme_demo_contact:
    path: /contact
    options:
        breadcrumb:
            label: Contact
            parent_route: acme_demo_home

acme_demo_catalogue:
    path: /catalogue
    options:
        breadcrumb:
            label: 'Our Catalogue'
            parent_route: acme_demo_home

acme_demo_catalogue_categories:
    path: /catalogue/categories
    options:
        breadcrumb:
            label: 'All categories'
            parent_route: acme_demo_catalogue

将生成如下面包屑树

acme_demo_home
    |- acme_demo_contact
    `- acme_demo_catalogue
       `- acme_demo_catalogue_categories

如果当前路由是 acme_demo_catalogue，则面包屑将显示如下

Home > Our Catalogue

由于面包屑的配置发生在路由配置中，因此通常与如何进行路由配置无关。这意味着通过注释等方式配置面包屑是完全可以的。

/**
 * ...
 * @Route(
 *    "/contact",
 *    name="acme_demo_contact",
 *    options={
 *        "breadcrumb" = {
 *            "label" = "Contact",
 *            "parent_route" = "acme_demo_home"
 *        }
 *    })
 * ...
 */

#[Route(
    '/contact', 
    name: 'acme_demo_contact',
    options: [
        'breadcrumb' => [
            'label' => 'Contact',
            'parent_route' => 'acme_demo_home'
        ]
    ],
)]

配置也可以使用 XML 和 PHP 完成。

动态路由

如果您需要用于面包屑的动态路由或动态翻译，可以定义如下

# routing.yml

acme_demo_product_detail:
    path: /products/{id}
    options:
        breadcrumb:
            label: 'Produkt: %%name%%'
            parent_route: acme_demo_catalogue

(此示例使用在路由中带有占位符的字符串。您还可以在翻译文件中定义标签文本，并仅使用翻译键作为标签。模板将处理翻译和替换。)

注意标签中的双 % 用于转义参数。这需要这样做，因为 routing.yml 正在被 Symfony 容器解析，并识别诸如 %name% 之类的构造，并尝试注入这些参数。双 % 转义它，模板处理其余部分。

然后您可以直接在 Breadcrumb 对象上设置参数，例如

<?php
// MyController

use Azri\BreadcrumbBundle\Provider\BreadcrumbProviderInterface;

// ...

public function productDetailAction(BreadcrumbProviderInterface $breadcrumbProvider)
{
    $product = ...;

    // ...

    $breadcrumbProvider
        ->getBreadcrumbByRoute('acme_demo_product_detail')
        ->setRouteParams([
            'id' => $product->getId(),
        ])
        ->setLabelParams([
            'name' => $product->getName(),
        ]);
        
    // ...
}

请注意，必须先在路由上定义面包屑才能设置参数。

动态面包屑

如果您有一个动态路由树，例如可以无限深入的分类页面树，您可以在不定义在路由上的情况下动态添加面包屑。例如如下

<?php

use Azri\BreadcrumbBundle\Model\Breadcrumb;

// ...

// Route of the product, we want the categories before this
$productCrumb = $breadcrumbProvder->getBreadcrumbByRoute('acme_demo_product_detail');
$collection = $breadcrumbProvider->getBreadcrumbs();

foreach ($product->getCategories() as $category) {
    $newCrumb = new Breadcrumb(
        'Category: %name%',              // Label
        'acme_demo_category',            // Route
        ['id' => $category->getId()],    // Route params
        ['name' => $category->getName()] // Label params
    );
    
    // Adds $newCrumb right in front of $productCrumb
    $collection->addBreadcrumbBeforeCrumb($newCrumb, $productCrumb);
    
    // Or: ->addBreadcrumb(), ->addBreadcrumbAtPosition(), ->addBreadcrumbAfterCrumb(), ->addBreadcrumbToStart()
}

不过，这些面包屑不会存储在缓存中。

在 twig 中显示

按照以下方式调用 twig 扩展

{# someTemplate.html.twig #}
{# ... #}

{{ breadcrumbs() }}

{# ... #}

使用 bootstrap 模板

此扩展包还提供对 Bootstrap 的默认实现。可以使用以下方式使用它

# config/azri_breadcrumb.yaml
azri_breadcrumb:
    template: '@AzriBreadcrumb/breadcrumbs_bootstrap.html.twig'

替换默认模板

如果您想使用自定义模板，请将以下内容添加到您的 config/azri_breadcrumb.yaml 中

# config/azri_breadcrumb.yaml
azri_breadcrumb:
    template: 'my twig template path'

您的自定义面包屑模板接收一个名为 breadcrumbs 的变量，它是一个集合，表示您的面包屑，按从树中最高的到最低的顺序排列。

单个 breadcrumb 具有字段 route、routeParameters、label 和 labelParameters。route 和 routeParameters 用于在 twig 中生成路径，即 path(breadcrumb.route, breadcrumb.routeParameters)，而 label 和 labelParameters 用于生成面包屑文本，即 {{ (breadcrumb.label)|trans(breadcrumb.labelParameters) }}。

您的自定义模板可能看起来像这样

{# myBreadcrumbs.html.twig #}

<div>
    {% for breadcrumb in breadcrumbs %}
        <a href="{{ path(breadcrumb.route, breadcrumb.routeParameters) }}">
            {{ breadcrumb.label|replace({"%%": "%"})|trans(breadcrumb.labelParameters) }}
        </a>
    {% endfor %}
</div>

模板内将 %% 替换为单个 %。请参阅 "动态路由" 了解为什么需要这样做。

查看 Resources/views/breadcrumbs.html.twig 和 Resources/views/breadcrumbs_bootstrap.html.twig 以了解默认实现。

自定义实现

模型类及其集合可以被自己的实现替换，这些实现需要实现 Azri\BreadcrumbBundle\Model\BreadcrumbInterface 和 Azri\BreadcrumbBundle\Model\BreadcrumbCollectionInterface 接口。

# config/azri_breadcrumb.yaml
azri_breadcrumb:
    model_class: 'Acme\Breadcrumbs\Model\MyModel'
    collection_class: 'Acme\Breadcrumbs\Model\MyCollection'

可以通过设置参数 provider_service_id 来替换提供者服务 ID。

# config/azri_breadcrumb.yaml
azri_breadcrumb:
    provider_service_id: acme.breadcrumbs.my_provider

缓存

此包使用路由缓存来存储每个路由的面包屑列表在 cache:warmup 上。然后，在需要时将它们转换为 BreadcrumbCollection。

azri / symfony-breadcrumb

维护者

详细信息