creitive/breadcrumbs

简单的面包屑类

维护者

详细信息

github.com/creitive/breadcrumbs

主页

源代码

问题

安装: 420,659

依赖者: 6

建议者: 0

安全: 0

星标: 88

关注者: 10

分支: 28

开放问题: 4

v3.3.2 2020-04-18 09:24 UTC

Requires

  • php: >=5.3.0

Requires (Dev)

MIT a939432cee8e8e71b3019055a079920e508969c4

  • Milos Levacic <milos.levacic.woop@creitive.com>
  • Luka Macun <luka.macun.woop@creitive.com>

breadcrumbs

This package is auto-updated.

Last update: 2024-09-09 22:56:19 UTC

README

Build Status Latest Stable Version Total Downloads

Laravel支持说明

此仓库最初是为Laravel 4创建的软件包，包括服务提供者和外观。自那时起，Laravel 5已发布，它使用稍微不同的技术来处理软件包。我们曾考虑将支持Laravel 4和5的功能组合到一个软件包中，或者为这些功能设置单独的分支，但最终我们选择发布此软件包的新主要版本2.0.0，完全不依赖Laravel，而是专注于核心面包屑功能。

为了支持Laravel，请使用以下软件包之一

这样做是为了不破坏任何人的向后兼容性 - 使用Laravel 4应用的用户仍然可以依赖creitive/breadcrumbs:~1.0，并且他们的应用将继续工作。然而，1.0版本将不再更新，因为升级过程应该非常简单，我们敦促大家这样做

composer remove creitive/breadcrumbs
composer require creitive/laravel4-breadcrumbs

此软件包重组还提供了软件包之间关注点的适当分离，并允许其他人创建他们自己的特定框架集成软件包，如果他们希望这样做的话。

面包屑

一个简单的面包屑软件包。生成兼容Twitter Bootstrap的输出。

安装

只需在命令行上运行此命令

composer require creitive/breadcrumbs

用法

基本思想是在您的应用中的某个位置创建一个Creitive\Breadcrumbs\Breadcrumbs类的实例，并使用以下描述的提供方法添加面包屑。稍后，您可以在某处渲染输出（根据您的应用基础设施，可能是在视图中），这将生成兼容Twitter Bootstrap的HTML。

$breadcrumbs = new Creitive\Breadcrumbs\Breadcrumbs;

$breadcrumbs->addCrumb('Home', '/');

echo $breadcrumbs->render();

以下文档假设您有一个$breadcrumbs实例，您正在对其进行调用。

添加面包屑

$breadcrumbs->addCrumb('Home', '/');

第一个参数是面包屑的标题，第二个参数是该面包屑的地址。您可以通过几种方式传递地址参数 - 如果此参数以正斜杠或协议（http/https）开头，它将被视为一个完整的URL，相应的面包屑将直接链接到它。如果它不以这两个中的任何一个开头，它将被视为一个段，并将其附加到其前一个面包屑。

注意：您也可以使用add，它是addCrumb的别名

$breadcrumbs->add('Home', '/');

示例

$breadcrumbs->addCrumb('Home', '/');
$breadcrumbs->addCrumb('Pages', 'pages');
$breadcrumbs->addCrumb('Subpage', 'subpage');
$breadcrumbs->addCrumb('Subsubpage', '/subsubpage');
$breadcrumbs->addCrumb('Other website', 'http://otherwebsite.com/some-page');

echo $breadcrumbs->render();

第三个面包屑（"子页面"）将链接到/pages/subpage，基于前面的面包屑。然而，第四个面包屑将链接到/subsubpage，因为其地址以斜杠开头。最后一个面包屑显然将链接到传递的URL。

您也可以链式调用addCrumb来一次添加多个面包屑

$breadcrumbs->addCrumb('Home', '/')
    ->addCrumb('Pages', 'pages')
    ->addCrumb('Subpage', 'subpage')
    ->addCrumb('Subsubpage', '/subsubpage')
    ->addCrumb('Other website', 'http://otherwebsite.com/some-page');

注意：实际上，尽可能支持方法链，即所有预期不会返回特定值的 方法：setBreadcrumbs()、addCrumb()、add()、setCssClasses()、addCssClasses()、removeCssClasses()、setDivider()、setListElement()、removeAll()。

CSS 类

有三种 CSS 类操作方法可供使用，它们的工作方式大致相同

$breadcrumbs->setCssClasses($classes);
$breadcrumbs->addCssClasses($classes);
$breadcrumbs->removeCssClasses($classes);

这些方法中的每一个都会操作将要应用到包含 <ul> 元素的类。所有这些方法都可以传递一个字符串或一个数组。如果传递一个字符串，CSS 类应该用空格分隔。

$stringClasses = 'class1 class2 class3';
$arrayClasses = array('class4', 'class5');

$breadcrumbs->addCssClasses($stringClasses);
$breadcrumbs->addCssClasses($arrayClasses);

// All five classes will now be applied to the containing `<ul>` element.

还可以配置一个自定义的 CSS 类，该类将应用到所有列表项上

$breadcrumbs->setListItemCssClass('breadcrumb-item');

分隔符

默认的面包屑分隔符是 /，这是 Twitter Bootstrap 2 的默认设置。Twitter Bootstrap 2。如果您想将其更改为，例如，»，可以这样做：

$breadcrumbs->setDivider('»');

分隔符以具有 divider CSS 类的 <span> 标签的形式呈现。如果您想使用新的 Bootstrap 3 HTML（它使用 ::before CSS 伪元素来样式分隔符），只需将分隔符设置为空字符串或 null，这些元素将不会在 HTML 中渲染。

列表元素

用于包裹面包屑的默认列表元素是 ul。要更改它，可以使用类似这样的 setListElement 方法

$breadcrumbs->setListElement('ol');

最后一个项目作为链接

默认情况下，列表中的最后一个项目不会作为链接渲染。如果您想更改此行为，可以使用 setLastItemWithHref() 方法进行控制，如下所示：

$breadcrumbs->setLastItemWithHref(true);

当然，如果您想稍后关闭此行为，可以传递 false，并且可以使用 getLastItemWithHref() 方法检查此设置的当前值。

输出

最后，当您实际想要显示面包屑时，只需在实例上调用 render() 方法即可

echo $breadcrumbs->render();

注意：您也可以像这样简单地回显实例：

echo $breadcrumbs;

请注意，面包屑标题在渲染时不会转义 HTML 字符，这是为了灵活性而设计的，允许您使用，例如，<img> 元素作为面包屑。这意味着您应该在添加面包屑时自行转义任何文本内容。

$breadcrumbs->addCrumb('<img src="/images/foo.png">', '/foo');
$breadcrumbs->addCrumb(htmlspecialchars($userSubmittedName), 'bar');

输出包含微数据标记 - 更多信息请参阅 Google 的 面包屑结构数据文档。

最佳实践

为了最小化代码重复，本节将提供一些关于如何组织面包屑处理的建议。由于此包最初是在我们内部的 CMS 内部开发的，因此它主要基于我们之前处理面包屑的方式。这些提示将假设项目基于 Laravel 4，但将它们推广到您可能使用的任何框架并不困难，因为大多数都有类似的控制器组织。

因此，我们通常有一个单一的 BaseController，所有其他控制器都扩展它。任何在其构造函数中执行某些操作的控制器都必须首先调用 parent::__construct()，因此 BaseController::__construct() 用于设置一些基本配置，这些配置从那时起对所有其他控制器都可用。

请注意，BaseController 没有任何操作（即没有路由调用 BaseController） - 它实际上是存在以提供所有其他控制器的基础。

在 BaseController::__construct() 中，我们通常会（在许多其他事情中）在类中存储面包屑实例，使其对子类可用，并调用类似 $this->breadcrumbs->addCrumb('Home', '/') 的内容，这基本上添加了一个名为“Home”的第一个面包屑，它链接到网站根目录 - 因此，所有页面都将始终有一个此面包屑（假设它们在视图中渲染面包屑）。

public function __construct()
{
    parent::__construct();

    $this->breadcrumbs = new \Creitive\Breadcrumbs\Breadcrumbs;
    $this->breadcrumbs->addCrumb('Home', '/');
}

假设我们有一个名为 StoreController 的控制器，该控制器列出了网站上可用的各种商店。当然，这个控制器扩展了 BaseController，所以其构造函数可能看起来像这样

public function __construct()
{
    parent::__construct();

    $this->breadcrumbs->addCrumb('Stores', 'stores');
}

现在假设我们有一个名为 getStores 的操作（用于列出可用的商店），以及 getStore（用于列出单个商店的主页）。StoreController::getStores() 不需要添加自己的面包屑，因为它已经在控制器构造函数中添加了，前提是该控制器所有操作都将包含这个面包屑。

自然地，StoreController::getStore() 会做类似 $this->breadcrumbs->addCrumb($store->name, $store->slug) 的事情，以便添加该商店的 slug 作为下一个面包屑。

在这个时候渲染面包屑会产生如下类似的 HTML（为了简洁，省略了 ul、li 和分隔元素）

<a href="/">Home</a>
<a href="/stores">Stores</a>
<a href="/stores/foo-store">Foo Store</a>

如果系统有一个管理面板，在 BaseController::__construct() 中添加的“首页”面包屑可能在那里没有用途。我们通常通过有一个 Admin\BaseController（它扩展了 BaseController，没有操作，并且所有管理控制器都扩展了它）来解决这个问题，并在其构造函数中做如下操作

public function __construct()
{
    parent::__construct();

    $this->breadcrumbs->removeAll();
    $this->breadcrumbs->addCrumb('Home', '/admin');
}

现在，像 Admin\StoreController 这样的控制器（它扩展了 Admin\BaseController）可以在其构造函数中做 $this->breadcrumbs->addCrumb('Stores', 'stores')（当然，在调用 parent::__construct() 之后），以添加它自己的面包屑。

对于稍微复杂一些的应用程序，我们倾向于不会在所有地方硬编码路由，所以我们可能会这样做

$this->breadcrumbs->addCrumb(Lang::('pages.home'), URL::action('HomeController@getIndex'));
$this->breadcrumbs->addCrumb(Lang::('pages.stores'), URL::action('StoreController@getStores'));
$this->breadcrumbs->addCrumb($store->name, URL::action('StoreController@getStore', array('storeId' => $store->id)));

然而，这超出了本包文档的范围，所以我们不会在这方面进行过多说明，因为它涉及到如何组织应用程序的更一般性的解释（并假设可以访问 Laravel 的一些基础设施，这使我们能够根据定义的应用程序路由生成 URL）。

推荐的 CSS

此插件默认使用 breadcrumbs CSS 类在包含的 ul 元素上，这是我们在我们自己的 CSS 框架中使用的方法。《a href="https://bootstrap.ac.cn" rel="nofollow noindex noopener external ugc">Bootstrap 默认使用 breadcrumb，所以如果你使用 Bootstrap 的 CSS，你应该使用 $this->breadcrumbs->setCssClasses('breadcrumb') 进行配置，例如在 BaseController::__construct() 中。

此外，该包会始终将 active 类添加到最后一个 li 元素（其中包含最后一个添加的面包屑），并在所有面包屑之间渲染一个具有 divider 类的 span 元素。

如果你在寻找一些运行面包屑所需的最低限度的 CSS，你可以使用在项目问题跟踪器的第 #6 个问题中由 @SaintPeter 提供的代码

.breadcrumbs {
    list-style: none;
    overflow: hidden;
}

.breadcrumbs li {
    float: left;
}

进一步的想法和替代方案

此包旨在处理非常基本的简单面包屑，这是我们长时间使用的东西，尽管最初并不是与 Laravel 一起使用的。

我们考虑过将其升级为具有高级功能，如支持面包屑配置、能够引用父级面包屑或使用闭包，或能够定义自己的视图进行渲染，但我们决定不这样做。

已经有一个功能强大的面包屑包可以做到大多数这些事情 - https://github.com/davejamesmiller/laravel-breadcrumbs - 我们强烈推荐此包用于复杂项目，我们自己也在使用它。如果你在寻找替代方案，我们发现了另一个可在 https://github.com/noherczeg/breadcrumb 处获得的包，但我们还没有尝试过它。

许可协议

代码根据 MIT 许可证授权，可在 LICENSE 文件中找到。