xepozz / breadcrumbs-bundle
Symfony5 的一个小型面包屑组件
Requires
- php: >=7.2
- symfony/framework-bundle: ^5.0
- symfony/templating: ^5.0
Requires (Dev)
- phpunit/phpunit: ^8.5
- symfony/browser-kit: ^5.0
- symfony/twig-bridge: ^5.0
- symfony/twig-bundle: ^5.0
- twig/twig: ^3.0
README
composer require xepozz/breadcrumbs-bundle
基本配置到此结束。更多选项请查看 配置 部分。
用法
在您的应用程序控制器方法中
use Xepozz\BreadcrumbsBundle\Model\Breadcrumbs; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\Routing\Generator\UrlGeneratorInterface; class Controller extends AbstractController { public function action(Breadcrumbs $breadcrumbs, UrlGeneratorInterface $urlGenerator) { // Simple example $breadcrumbs->addItem('Home', $urlGenerator->generate('index')); // Example without URL $breadcrumbs->addItem('Some text without link'); // Example with parameter injected into translation "user.profile" $breadcrumbs->addItem('Account: %user%', '', ['%user%' => 'Username']); } }
然后,在您的模板中
{{ wo_render_breadcrumbs() }}
以渲染面包屑的 html 视图。
面包屑集合中的最后一个项将自动以纯文本形式渲染,而不是 <a>...</a>
标签。
addItem()
方法将项目添加到面包屑集合的 末尾。您可以使用 prependItem()
方法将项目添加到面包屑集合的 开头。当与分层数据(例如 Doctrine Nested-Set)结合使用时,这很有用。此示例使用产品目录中的类别
use Xepozz\BreadcrumbsBundle\Model\Breadcrumbs; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\Routing\Generator\UrlGeneratorInterface; class Controller extends AbstractController { public function action(Category $category, Breadcrumbs $breadcrumbs) { $node = $category; while ($node) { $breadcrumbs->prependItem($node->getName(), '<category URL>'); $node = $node->getParent(); } } }
如果您不想手动生成 URL,可以轻松地通过传递路由名称和任何所需的参数来添加面包屑项,使用 addRouteItem()
和 prependRouteItem()
方法
use Xepozz\BreadcrumbsBundle\Model\Breadcrumbs; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\Routing\Generator\UrlGeneratorInterface; class Controller extends AbstractController { public function action(Breadcrumbs $breadcrumbs, UrlGeneratorInterface $urlGenerator) { // Pass "_demo" route name without any parameters $breadcrumbs->addRouteItem('Demo', '_demo'); // Pass "_demo_hello" route name with route parameters $breadcrumbs->addRouteItem('Hello Breadcrumbs', '_demo_hello', [ 'name' => 'Breadcrumbs', ]); // Add "homepage" route link at the start of the breadcrumbs $breadcrumbs->prependRouteItem('Home', 'homepage'); } }
Schema.org/BreadcrumbList
如果您需要渲染 Schema.org/BreadcrumbList 的面包屑
{{ wo_render_breadcrumbs_schema() }}
配置
以下 默认 参数可以在您的 config.yml
或类似文件中覆盖
# config/services.yml breadcrumbs: separator: '/' separatorClass: 'separator' listId: 'wo-breadcrumbs' listClass: 'breadcrumb' itemClass: '' linkRel: '' locale: ~ # defaults to null, so the default locale is used translation_domain: ~ # defaults to null, so the default domain is used viewTemplate: '@Breadcrumbs/microdata.html.twig'
这些也可以在渲染面包屑时作为参数传递给视图 - 例如
{{ wo_render_breadcrumbs({separator: '>', listId: 'breadcrumbs'}) }}
注意: 如果您需要在同一页面上生成多个面包屑集合,您可以使用命名空间。默认情况下,面包屑使用
default
命名空间,但您可以添加更多。要将面包屑添加到自定义命名空间,请使用addNamespaceItem
/prependNamespaceItem
或addNamespaceRouteItem
/prependNamespaceRouteItem
方法,例如
use Xepozz\BreadcrumbsBundle\Model\Breadcrumbs; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\Routing\Generator\UrlGeneratorInterface; class Controller extends AbstractController { public function action(Breadcrumbs $breadcrumbs, UrlGeneratorInterface $urlGenerator) { // Simple example $breadcrumbs->prependNamespaceItem('subsection', 'Home', $urlGenerator->generate('index')); // Example without URL $breadcrumbs->addNamespaceItem('subsection', 'Some text without link'); // Example with parameter injected into translation "user.profile" $breadcrumbs->addNamespaceItem('subsection', $txt, $url, ['%user%' => $user->getName()]); // Example with route name with required parameters $breadcrumbs->addNamespaceRouteItem('subsection', $user->getName(), 'user_show', ['id' => $user->getId()]); } }
然后,要在模板中渲染 subsection
面包屑,请指定此命名空间作为选项
{{ wo_render_breadcrumbs({namespace: "subsection"}) }}
高级用法
您可以一次添加一个对象数组
$breadcrumbs->addObjectArray(array $objects, $text, $url, $translationParameters);
objects: array of objects
text: name of object property or closure
url: name of URL property or closure
示例
$that = $this; $breadcrumbs->addObjectArray($selectedPath, 'name', function($object) use ($that) { return $that->generateUrl('_object_index', ['slug' => $object->getSlug()]); });
您也可以添加一个树路径
$breadcrumbs->addObjectTree($object, $text, $url = '', $parent = 'parent', array $translationParameters = [], $firstPosition = -1)
object: object to start with
text: name of object property or closure
url: name of URL property or closure
parent: name of parent property or closure
firstPosition: position to start inserting items (-1 = determine automatically)
注意: 您可以使用
addNamespaceObjectArray
和addNamespaceObjectTree
分别在同一个页面上处理多个面包屑。
覆盖模板
有两种方法可以做到这一点。
-
您可以通过复制
Resources/views/microdata.html.twig
文件到templates/Breadcrumbs/views
中并按需自定义来覆盖组件使用的模板。有关更多信息,请参阅 覆盖组件模板 文档部分。 -
使用
viewTemplate
配置参数{{ wo_render_breadcrumbs({ viewTemplate: 'templates/breadcrumbs/view.html.twig' }) }}
注意: 如果您想使用 JSON-LD 格式,已存在一个模板在
@Breadcrumbs/json-ld.html.twig
。只需将此模板设置为viewTemplate
的值即可,无论是在您的 Twig 函数调用中(见上面的步骤 2)还是在您的组件 配置 中。