README

Navigator

Navigator是一个用于在Laravel应用程序中创建无头导航菜单的包

// In a Service Provider

Nav::define(fn ($user) => [
    Nav::item('Dashboard')
        ->for('dashboard')
        ->icon('dashboard.svg')
        ->when($user->can('access.dashboard'))
])

// In a view

@foreach(navitems() as $item)
    //
@endforeach

// Or as json...

Nav::toJson()

这是一个无头包，因此您可以完全自由地按照自己的意愿进行样式设计。

安装

您可以通过composer安装此包

composer require nedwors/navigator

用法

选择一个服务提供者 - 或者也许可以创建一个专用的服务提供者 - 然后将以下内容添加进去

Nav::define(fn () => [
    Nav::item('Dashboard')
        ->for('dashboard')
        ->icon('dashboard')
]);

Et voila! 现在您已经有一个可用的菜单了。您可以通过以下方式检索项目

@foreach(navitems())
    //
@endforeach

// or

@foreach(Nav::items())
    //
@endforeach

现在，您可能需要不仅仅是仪表板链接 - 或者也许不需要，这是您的应用程序！ - 但希望您能看出它启动起来的简单性。

让我们进一步了解您可用的功能

API

此包由两个主要功能组成 - 每个Nav及其内部的Items。我们将首先探索Item，然后是Nav。

在此点值得注意，Item扩展了Illuminate\Support\Fluent，以便根据每个项目进行自定义方法/属性。此外，Nav是可宏化的，以便在您的项目中实现自定义功能。

Item

• 名称
• URL
• 图标
• 条件
• 确定活动状态
• 子项目

Nav

• 定义
• 项目
• toJson
• 过滤
• 活动时

Item

名称

使用Nav::item()方法创建一个新的Item。此方法接收Item的名称

Nav::item('Dashboard')

$item->name // Dashboard

名称在输出之前通过Laravel __()语言助手传递。

URL

如下定义并检索URL

Nav::item('Dashboard')->for('/dashboard')

$item->url // /dashboard

for()方法也可以用来构建Laravel路由

Nav::item('Dashboard')->for('dashboard.show', $customer)

对于项目来说，URL不是必需的。默认情况下，所有项目都有一个null URL。

图标

可以定义并检索应用中的图标引用如下

Nav::item('Dashboard')->icon('dashboard.svg')

$item->icon

您可能想使用令人惊叹的Blade Heroicons包，该包本身使用令人惊叹的Heroicons图标集。它们可以定义如下 - 可能用于动态组件

Nav::item('Dashboard')->heroicon('o-cog')

$item->heroicon

条件

可以定义条件以确定给定的Item是否应该显示或隐藏

Nav::item('Billing')->when(auth()->user()->is_subscribed)

Nav::item('Registration')->unless(auth()->user()->is_subscribed)

它们也可以组合使用

Nav::item('Billing')
    ->when($aCheck)
    ->unless($someOtherCheck)
    ->when($yetAnotherCheck)

当加载导航项目时，任何假值Items都会默认过滤掉。

如果需要，可以修改此行为

确定活动状态

任何菜单项目的基本需求是确定它是否处于活动状态。要这样做，只需访问active属性即可

@if ($item->active)
...
@endif

默认情况下，如果当前URL与项目的URL匹配，则项目返回true。您可以通过配置此行为

子项目

为任何给定项目创建子项目很简单 - 只需按如下方式定义

Nav::item('Billing')->subItems([
    Nav::item('Invoices'),
    ...
])

子菜单的数量没有限制，子菜单本身也可以有子菜单。这种情况可能很少见，但如果需要，功能是存在的。

Nav::item('Billing')->subItems([
    // Sub Items here...
])

有关更多信息，请参阅定义部分。

当有子菜单时，一个常见的需求是确定是否有任何子项处于活动状态，比如为了展开父项的 Item 下拉列表。与其遍历每个子代并判断其是否处于 活动 状态，您可以直接调用 hasActiveDescendants

@if ($item->hasActiveDescendants)
...
@endif

无论嵌套多深，此方法都将返回 true，即使对于孙子或曾孙等（你明白这个意思）。如果一个父项的子项处于活动状态，尽管 hasActiveDescendants 将返回 true，但 active 仍然不会。这仅适用于访问 Item 的地方。

Nav

现在我们已经了解了如何创建一些 Items，我们需要实际创建一个菜单！最简单的做法是定义一个菜单并检索它。但我们还可以控制像过滤这样的高级功能。让我们先创建一个菜单

定义

要创建一个菜单，请使用 define 方法

Nav::define(fn () => [
    // Items go here...
]);

如你所见，define 方法应该传递一个返回 可迭代对象 的闭包。

传递给 define 的闭包将接收 auth()->user() 和 app() 以便方便使用——想想 条件

Nav::define(fn (?Authenticable $user, Application $app) => [
    // Items go here...
]);

关于多个菜单呢？没问题，只需将菜单名称作为每个菜单定义的第二个参数传递即可

Nav::define(fn () => [
    // Items go here...
], 'admin');

项目

现在我们已经定义了菜单，我们需要在视图中输出它们！这可以通过以下方式实现

Nav::items()

// or

navitems()

这两个方法都返回一个菜单 Items 的 Collection。如果您需要访问特定的菜单，可以将它作为参数传递

Nav::items('admin')

// or

navitems('admin')

您可能需要将 Nav::items() 的别名添加到您的 app.php 配置文件中，以便无需完整命名空间即可使用

toJson

菜单项也可以以它们的 JSON 表示形式检索

Nav::toJson()

就像 Nav::items() 一样，如果您需要访问特定的菜单，可以将它作为参数传递

Nav::toJson('admin')

过滤

您设置的所有那些 条件 都需要做点什么吧？好吧，默认情况下，所有因为条件而不会返回 true 的 Items 都会被过滤掉。如果您想控制应该过滤掉什么，请使用 filter 方法。此方法接受一个具有与 Collection 过滤器相同结构的 Closure

Nav::filter(fn (Item $item) => ...)

您还可以为多个菜单定义过滤器

Nav::filter(fn (Item $item) => ..., 'app')
Nav::filter(fn (Item $item) => ..., 'admin')

所有 过滤器 都将应用于给定菜单的所有子项。

您可能不需要使用此功能，但如果需要，它就在那里。

活动时

默认情况下，Items 的活动属性将在当前 URL 是 Item 的 URL 时为 true。这适用于您是使用命名路由还是 URL 定义 Item。如果您想覆盖什么构成 Item 的活动状态，可以使用 activeWhen 方法。这应该传递一个接收 Item 的 Closure

Nav::activeWhen(fn (Item $item) => ...)

这可能对传统路由之外的用例很有用。就像 `filter' 一样，这可以针对每个菜单进行定义

Nav::activeWhen(fn (Item $item) => ..., 'app')
Nav::activeWhen(fn (Item $item) => ..., 'admin')

活动检查也将用于菜单中的所有子菜单。

测试

composer test

变更日志

请参阅 CHANGELOG 了解最近更改的信息。

贡献

请参阅 CONTRIBUTING 了解详细信息。

安全

如果您发现任何安全相关的问题，请通过电子邮件 nedwors@gmail.com 而不是使用问题跟踪器。

致谢

• Sam Rowden
• 所有贡献者

许可证

MIT 许可证 (MIT)。请参阅 许可证文件 了解更多信息。