Skip to content
本页为翻译版本:如有出入,以英文文档为准。 阅读英文版

菜单预设和选项 ​

发布配置文件:

bash
php artisan vendor:publish --tag=filament-relation-navigator-config
php
'menu' => [
    'preset' => 'github',   // 'simple'、你自己的预设或视图名称
    'presets' => [
        'simple' => 'filament-relation-navigator::menu.simple',
        'github' => 'filament-relation-navigator::menu.github',
    ],
    'searchable' => true,   // 在列表顶部显示搜索框,与预设无关
    'search_from' => 0,     // ……从这么多项开始
    'badges' => 'lazy',     // relation manager 的徽章:'lazy' 在菜单打开时加载,true 随页面加载,false 关闭
    'max_height' => '24rem',
    'separator' => true,    // 记录页面和关联页面分成两组
    'mobile' => true,       // 在小屏幕上,菜单显示在标题上方
    'shortcut' => 'alt+shift+r', // 打开菜单;null 表示关闭
],

github(默认):面包屑的最后一项保持为文本,旁边的小箭头会打开一个面板,其中有标题、搜索框,当前页面上有一个对勾,类似 GitHub 的仓库切换器。菜单打开时搜索框自动获得焦点,按 Enter 打开第一个匹配项。

simple:面包屑的最后一项本身就会打开列表。要使用 1.2 及更早版本的菜单,设置 'preset' => 'simple' 和 'searchable' => false。

查看页面上的 simple 预设

徽章 ​

菜单会显示 relation manager 的徽章,与它们的标签页一样。默认情况下,徽章在菜单打开时加载:在此之前菜单是关闭的,所以页面渲染时不会执行它们的查询,每次重绘面包屑的 Livewire 请求也是如此。加载的那一小会儿会显示一个加载动画。

php
'badges' => 'lazy', // 默认;true:随页面加载;false:不显示徽章

在需要的地方关闭它们:

php
// 在页面或 resource(static)上:此菜单中不显示徽章
public function hasRelationNavigatorBadges(): bool
{
    return false;
}

// 在 relation manager 上(配合 InteractsWithRelationPage):它的徽章保留在
// 标签页中,不显示在菜单里
protected static bool $hasRelationNavigatorBadge = false;

在 Filament 中标签页徽章为 lazy 的 relation manager(protected static ?bool $isBadgeLazyLoaded = true;,或 Filament 4.13 上的 $isBadgeDeferred),在菜单中也是 lazy 的,即使设置了 'badges' => true。

无法延迟加载徽章的菜单视图(1.3 之前发布的本包视图,或自己渲染 $item->badge 的自定义预设)会像以前一样随页面获得徽章:不会有任何东西消失。

键盘:在搜索框中按向下键进入列表;向上和向下键在页面之间移动,Enter 打开页面,Escape 关闭菜单。

快捷键和 tooltip ​

菜单按钮的 tooltip,显示其快捷键

打开菜单的按钮带有一个显示快捷键的 tooltip,按 Mac 或 Windows/Linux 的按键显示。快捷键可以在页面的任何位置打开菜单,并且搜索框已准备好输入,类似 GitHub 的仓库切换器:Mac 上是 ⌥ ⇧ R,其他系统上是 Alt Shift R。可以在配置中或按页面修改:

php
'shortcut' => 'mod+shift+p', // mod 在 Mac 上是 ⌘,在其他系统上是 Ctrl
php
public function getRelationNavigatorShortcut(): ?string
{
    return null; // 此页面不使用快捷键
}

它的设计尽量不打扰你:

  • 它匹配的是物理按键,因此适用于任何键盘布局,也适用于 Mac 上的 Option 键(在 Mac 上 ⌥⇧R 会输入 ‰);
  • 在输入框中打字时它不会触发;
  • 绝不会占用 panel 全局搜索的快捷键(globalSearchKeyBindings()):这种情况下菜单没有快捷键;
  • 只会打开可见的那个菜单(面包屑中的或小屏幕上的)。

支持的按键:alt、shift、ctrl、meta、mod 加上一个字母、一个数字或 / . , ;。

带搜索框的 github 预设

页面、resource 还是配置 ​

每个选项都有三个层级。页面优先,其次是 resource,最后是配置:

页面方法(在 resource 上为 static)配置键
getRelationNavigatorPreset(): stringmenu.preset
isRelationNavigatorSearchable(): boolmenu.searchable
hasRelationNavigatorBadges(): boolmenu.badges
hasDeferredRelationNavigatorBadges(): boolmenu.badges = 'lazy'
getRelationNavigatorShortcut(): ?stringmenu.shortcut
hasRelationNavigatorMobileMenu(): boolmenu.mobile
hasRelationNavigatorRecordNavigation(): boolrecord_navigation
shouldRelationNavigatorRecordNavigationFollowList(): boolrecord_navigation_follows_list
shouldRedirectRelationNavigatorTabs(): boolredirect_relation_tabs
php
// 在某个页面上
public function isRelationNavigatorSearchable(): bool
{
    return false;
}
php
// 在 resource 上:同一个方法,static,作用于它的所有页面
public static function hasRelationNavigatorRecordNavigation(): bool
{
    return true;
}

小屏幕 ​

Filament 在 40rem 以下会隐藏面包屑。此时菜单会显示在页面标题上方,适用于所有使用 HasRelationNavigator 的页面,预设选项相同。用 'mobile' => false 关闭,或按页面关闭:

php
public function hasRelationNavigatorMobileMenu(): bool
{
    return false;
}
手机上的菜单,位于页面标题上方

翻译 ​

支持 32 种语言,语言代码与 Filament 相同:阿拉伯语、保加利亚语、加泰罗尼亚语、中文(简体和繁体)、捷克语、丹麦语、荷兰语、英语、芬兰语、法语、德语、希腊语、希伯来语、匈牙利语、印度尼西亚语、意大利语、日语、韩语、挪威语、波斯语、波兰语、葡萄牙语(葡萄牙和巴西)、罗马尼亚语、俄语、斯洛伐克语、西班牙语、瑞典语、土耳其语、乌克兰语和越南语。在从右到左书写的语言中,上一条和下一条的箭头会反过来。发布翻译文件即可修改翻译或添加新语言:

bash
php artisan vendor:publish --tag=filament-relation-navigator-translations

自定义预设 ​

从本包的某个预设开始:

bash
php artisan make:filament-relation-navigator-preset compact --from=github

它会把预设复制到 resources/views/filament/relation-navigator/compact.blade.php。注册它,然后随意修改:

php
'preset' => 'compact',
'presets' => [
    // ...
    'compact' => 'filament.relation-navigator.compact',
],

任何视图名称也都可以用作 preset。要修改本包自带的预设,发布它们的视图:

bash
php artisan vendor:publish --tag=filament-relation-navigator-views

预设视图会接收以下变量:

变量内容
$label面包屑的最后一项
$items菜单项:key、label、url、icon、badge、badgeColor、isActive
$heading"Switch page",已翻译
$isSearchable是否显示搜索框
$hasSeparator是否把记录页面和关联页面分成两组
$shortcut快捷键,或 null
$shortcutKeys要显示的快捷键按键:['mac' => [...], 'other' => [...]]
$searchPlaceholder"Find a page…",已翻译
$emptyLabel"No pages found.",已翻译
$maxHeightmenu.max_height

要让你的按钮带上 tooltip 和快捷键,在它的标签内引入 filament-relation-navigator::menu.partials.trigger-attributes。每个菜单项还有 isRelationPage()。要复用搜索框、列表(包括分隔线和键盘导航)以及“无结果”那一行,引入 filament-relation-navigator::menu.partials.list 并传入 showCheck。

版本 1.8.1,发布于 2026-11-15 · MIT 许可证。