Filament 中文文档

主题

全部文档

Clusters（集群） ​

简介 ​

Clusters 是面板中的层级结构，可将 resources 与 自定义页面 分组。有助于把面板整理成逻辑分区，并缩小侧栏体积。

带有子导航的 cluster 页面带有子导航的 cluster 页面

使用 cluster 时会发生以下情况：

  • 导航中会新增一项，指向该 cluster 中的第一个 resource 或页面。
  • 这些 resource 或页面各自的导航项不再出现在主导航中。
  • cluster 内每个 resource 或页面会增加子导航 UI，其中包含该 cluster 内资源与页面的导航项。
  • cluster 内的 resources 与页面会获得以 cluster 名称作为前缀的新 URL。若你正确生成指向 [resources](/5.x/resources/overview#generating-urls-to-resource-pages) 与 [pages](/5.x/navigation/custom-pages#generating-urls-to-pages) 的 URL，这一变更会自动处理。
  • cluster 名称会出现在其中所有 resources 与页面的面包屑中。点击后会进入该 cluster 的第一个 resource 或页面。

创建 cluster ​

创建第一个 cluster 之前，需告知面板 cluster 类所在位置。在配置中，除了 discoverResources()、discoverPages() 等方法，还可使用 discoverClusters()：

php
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->discoverResources(in: app_path('Filament/Resources'), for: 'App\\Filament\\Resources')
        ->discoverPages(in: app_path('Filament/Pages'), for: 'App\\Filament\\Pages')
        ->discoverClusters(in: app_path('Filament/Clusters'), for: 'App\\Filament\\Clusters');
}

现在可用 php artisan make:filament-cluster 命令创建 cluster：

bash
php artisan make:filament-cluster Settings

这会在 app/Filament/Clusters 目录创建新的 cluster 类：

php
<?php

namespace App\Filament\Clusters\Settings;

use BackedEnum;
use Filament\Clusters\Cluster;
use Filament\Support\Icons\Heroicon;

class SettingsCluster extends Cluster
{
    protected static string | BackedEnum | null $navigationIcon = Heroicon::OutlinedSquares2x2;
}

默认会定义 $navigationIcon 属性，因为你多半会立刻自定义它。其他所有导航属性与方法也可用，包括 $navigationLabel、$navigationSort 与 $navigationGroup。它们用于自定义 cluster 的主导航项，方式与自定义 resource 或页面的导航项相同。

将 resources 与页面加入 cluster ​

要将 resources 与页面加入 cluster，只需在 resource 或页面类上定义 $cluster 属性，并设为你创建的 cluster 类：

php
use App\Filament\Clusters\SettingsCluster;

protected static ?string $cluster = SettingsCluster::class;

使用 clusters 的面板代码结构建议 ​

使用 clusters 时，建议把所有 resources 与页面移到与 cluster 同名的目录下。例如，使用名为 Settings 的 cluster、包含 ColorResource 与两个自定义页面的面板目录结构如下：

.
+-- Clusters
|   +-- Settings
|   |   +-- SettingsCluster.php
|   |   +-- Pages
|   |   |   +-- ManageBranding.php
|   |   |   +-- ManageNotifications.php
|   |   +-- Resources
|   |   |   +-- Colors
|   |   |   |   +-- ColorResource.php
|   |   |   |   +-- Pages
|   |   |   |   |   +-- CreateColor.php
|   |   |   |   |   +-- EditColor.php
|   |   |   |   |   +-- ListColors.php

这只是建议而非强制。只要 cluster 内的 resources 与页面使用 $cluster 属性，面板结构可任意组织。这只是帮助保持面板整洁的建议。

面板中已有 cluster 时，用 make:filament-resource 或 make:filament-page 生成新 resources 或页面，会按上述指南询问是否创建在 cluster 目录内。若选择是，Filament 还会为 resource 或页面类自动设置正确的 $cluster 属性；若否，则需自行定义 $cluster 属性。

设置 cluster 内所有页面的子导航位置 ​

默认情况下，子导航渲染在每个页面的起始侧。可按页面单独自定义，也可通过设置 $subNavigationPosition 属性一次性为整个 cluster 自定义。取值可为 SubNavigationPosition::Start、SubNavigationPosition::End，或用 SubNavigationPosition::Top 将子导航渲染为标签页：

php
use Filament\Pages\Enums\SubNavigationPosition;

protected static ?SubNavigationPosition $subNavigationPosition = SubNavigationPosition::End;
子导航位于末尾的 cluster子导航位于末尾的 cluster

SubNavigationPosition::Top 选项会将子导航以标签页形式渲染在页面内容上方：

子导航位于顶部的 cluster子导航位于顶部的 cluster

自定义 cluster 面包屑 ​

cluster 名称会出现在其中所有 resources 与页面的面包屑中。

可在 cluster 类中用 $clusterBreadcrumb 属性自定义面包屑名称：

php
protected static ?string $clusterBreadcrumb = 'cluster';

或者，可用 getClusterBreadcrumb() 定义动态面包屑名称：

php
public static function getClusterBreadcrumb(): string
{
    return __('filament/clusters/cluster.name');
}

从 cluster 中移除子导航 ​

默认情况下，cluster 内所有 resources 与页面都会显示子导航。若要从整个 cluster 的 resources 与页面中移除子导航，可在 cluster 类中将 $shouldRegisterSubNavigation 设为 false：

php
protected static bool $shouldRegisterSubNavigation = false;

或者，可重写 shouldRegisterSubNavigation() 方法以定义动态行为：

php
public static function shouldRegisterSubNavigation(): bool
{
    return FeatureFlag::active();
}