导航

概述

默认情况下，Filament 会为每一个 资源类 和 自定义页面 注册导航菜单。这些类中包含一些你可以重写的静态属性和静态方法，用以配置导航菜单和显示顺序：

自定义导航项标签

默认情况下，导航标签由资源或者页面的名字生成，你可以使用 $navigationItems 属性自定义该标签：

protected static ?string $navigationLabel = 'Custom Navigation Label';

此外，你也可以重写 $getNavigationLabel() 方法：

public static function getNavigationLabel(): ?string
{
    return 'Custom Navigation Label';
}

自定义导航项图标

你可以重写资源和页面类页面中的 $navigationIcon 属性，自读八卦图导航菜单项的图标：

protected static ?string $navigationIcon = 'heroicon-o-document-text';

激活时切换导航菜单图标

使用 $activeNavigationIcon 属性，可以分配一个仅用于激活项的导航图标：

protected static ?string $activeNavigationIcon = 'heroicon-o-document-text';

导航项排序

默认情况下，导航项按照字母顺序排序，你可以使用 $navigationSort 属性自定义排序：

protected static ?int $navigationSort = 3;

限制，使用低数值导航项会出现在高数值的前面 - 排序是升序的。

添加徽章到导航项

要在导航菜单项中添加徽章，可以使用 getNavigaionBadge() 方法，返回徽章内容：

public static function getNavigationBadge(): ?string
{
    return static::getModel()::count();
}

public static function getNavigationBadgeColor(): ?string
{
    return static::getModel()::count() > 10 ? 'warning' : 'primary';
}

导航项分组

你可以通过指定资源类resources 和 自定义页面的 $navigationGroup 属性对导航菜单项进行分组：

protected static ?string $navigationGroup = 'Settings';

在同一个导航分组中的所有菜单项会被集中到同一个分组标签下显示，比如本例的 "Settings"。未分组的菜单项会被保留在侧边栏顶部。

自定义导航分组

你可以在配置中调用 navigationGroups()，并按顺序传入 NavigationGroup 对象来自定义导航分组：

use Filament\Navigation\NavigationGroup;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->navigationGroups([
            NavigationGroup::make()
                 ->label('Shop')
                 ->icon('heroicon-o-shopping-cart'),
            NavigationGroup::make()
                ->label('Blog')
                ->icon('heroicon-o-pencil'),
            NavigationGroup::make()
                ->label('Settings')
                ->icon('heroicon-o-cog-6-tooth')
                ->collapsed(),
        ]);
}

本例中，我会传入了自定义的图标 icon()，并使其中一个默认是折叠的 collapsed()。

导航分组排序

$panel
    ->navigationGroups([
        'Shop',
        'Blog',
        'Settings',
    ])

使导航分组不可折叠

默认情况下，导航分组是可折叠的。你可以通过调用 NavigationGroup 对象上的 collapsible(false)可以禁用该行为：

use Filament\Navigation\NavigationGroup;

NavigationGroup::make()
    ->label('Settings')
    ->icon('heroicon-o-cog-6-tooth')
    ->collapsible(false);

或者，你也可以在配置中让所有的分组全局生效：

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->collapsibleNavigationGroups(false);
}

在桌面端折叠侧边栏

要让桌面端的侧边栏像移动端一样可折叠，你可以使用配置:

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->sidebarCollapsibleOnDesktop();
}

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->sidebarFullyCollapsibleOnDesktop();
}

注册自定义导航菜单项

你可以在配置中注册自定义导航菜单：

use Filament\Navigation\NavigationItem;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->navigationItems([
            NavigationItem::make('Analytics')
                ->url('https://filament.pirsch.io', shouldOpenInNewTab: true)
                ->icon('heroicon-o-presentation-chart-line')
                ->group('Reports')
                ->sort(3),
            // ...
        ]);
}

条件性隐藏导航菜单项

你也可以使用 visible() 或 hidden() 方法，传入条件，条件性隐藏导航项：

use Filament\Navigation\NavigationItem;

NavigationItem::make('Analytics')
    ->visible(auth()->user()->can('view-analytics'))
    // or
    ->hidden(! auth()->user()->can('view-analytics')),

禁用资源或页面的导航菜单项

如果你要阻止你的资源或者页面在导航中显示，你可以使用:

protected static bool $shouldRegisterNavigation = false;

使用顶部导航

默认情况下，Filament 使用侧边栏导航。你可以在配置设置使用顶部导航：

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->topNavigation();
}

导航自定义进阶

在配置中调用 navigation() 方法。允许你重写 Filament 自动生成的项目来创建一个自定义导航。该 API 是为了让你对导航有完全的控制权。

注册自定义导航项

调用 items() 方法，可以注册导航项目：

use App\Filament\Pages\Settings;
use App\Filament\Resources\UserResource;
use Filament\Navigation\NavigationBuilder;
use Filament\Navigation\NavigationItem;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->navigation(function (NavigationBuilder $builder): NavigationBuilder {
            return $builder->items([
                NavigationItem::make('Dashboard')
                    ->icon('heroicon-o-home')
                    ->isActiveWhen(fn (): bool => request()->routeIs('filament.pages.dashboard'))
                    ->url(route('filament.pages.dashboard')),
                ...UserResource::getNavigationItems(),
                ...Settings::getNavigationItems(),
            ]);
        });
}

注册自定义导航分组

如果你想要注册分组，可以调用 groups() 方法：

use App\Filament\Pages\HomePageSettings;
use App\Filament\Resources\CategoryResource;
use App\Filament\Resources\PageResource;
use Filament\Navigation\NavigationBuilder;
use Filament\Navigation\NavigationGroup;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->navigation(function (NavigationBuilder $builder): NavigationBuilder {
            return $builder->groups([
                NavigationGroup::make('Website')
                    ->items([
                        ...PageResource::getNavigationItems(),
                        ...CategoryResource::getNavigationItems(),
                        ...HomePageSettings::getNavigationItems(),
                    ]),
            ]);
        });
}

禁用导航

你可以传入 false 到 navigation() 方法来完全禁用导航：

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->navigation(false);
}

自定义用户菜单

用户菜单在后台布局的右上角，可以自定义。

要在用户菜单中注册新项目，你需要使用配置:

use Filament\Navigation\MenuItem;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->userMenuItems([
            MenuItem::make()
                ->label('Settings')
                ->url(route('filament.pages.settings'))
                ->icon('heroicon-o-cog-6-tooth'),
            // ...
        ]);
}

自定义 Profile 链接

要在用户菜单顶部自定义用户简介链接，用 profile 作为键名注册新的项目:

use Filament\Navigation\MenuItem;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->userMenuItems([
            'profile' => MenuItem::make()->label('Edit profile'),
            // ...
        ]);
}

更多关于创建 [Profile] 页面的信息，请查阅身份验证功能文档。

自定义退出登录链接

要在用户菜单的尾部自定义用户账户链接，用 logout 作为数组键名注册新的项目:

use Filament\Navigation\MenuItem;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->userMenuItems([
            'logout' => MenuItem::make()->label('Log out'),
            // ...
        ]);
}

禁用面包屑

默认布局会显示面包屑，用来显示当前页面在应用层次结构中的位置。

你可以在配置中禁用面包屑：

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->breadcrumbs(false);
}