配置 - 面板构建器

概述

默认情况下，配置文件位于 app/Providers/Filament/AdminPanelProvider.php。继续阅读了解更多面板信息以及每个面板如何拥有自己的配置文件。

引入面板

默认情况下，当你安装完该包后，已经为你准备好了一个面板，它位于 /admin。你所创建的所有资源、页面及仪表盘 Widget 都注册到此面板中。

不过，你可以根据需要创建尽可能多的面板，每个都有一套它自己的资源、页面以及 Widget。

比如，你创建了一个面板，用户可以通过 /app 登录并访问它们的仪表盘，管理员可以通过 /admin 登录并管理应用。/app 面板及 /admin 面板都有它们自己的资源，因为每个用户组有不同的需求。Filament 通过提供创建多个面板的能力来允许你实现该功能。

默认的管理面板

当你运行 filament:install 后，在 app/Providers/Filament 下面新建了一个文件 —— AdminPanelProvider。该文件包含了 /admin 面板的配置文件。

此文档提及“配置”时，这就是你需要去编辑的那个文件。它允许你完全自定义应用。

创建新面板

要创建新面板，请使用 make:filament-panel 命令，传入新面板的唯一名称:

php artisan make:filament-panel app
php artisan make:filament-panel app

该命令会创建一个名为"app"的新面板。同时生成一个新配置文件 app/Providers/Filament/AppPanelProvider.php。你可以在 /app 中访问该面板，不过如果你不想要该路径你也可以自定义路径。

由于配置文件也是一个 Laravel 服务提供者，它需要在 bootstrap/providers.php (Laravel 11 和以上版本) 或 config/app.php (Laravel 10 和以下版本)中注册。Filament 会尝试为你完成此操作，不过如果你访问该面板时返回错误，那么可能是该操作失败。

修改路径

在面板配置文件中，你可以使用 path() 方法，修改该应用可访问的路径：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->path('app');
}
use Filament\Panel;

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

如果你想不使用前缀访问该应用，你可以将其设为空字符串：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->path('');
}
use Filament\Panel;

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

请确保 routes/web.php 未定义 '' 或 '/' 路由，因为它会被优先采用。

渲染钩子

Filament 允许你在应用布局中的不同点渲染 Blade 模板内容。这对于集成像 wire-elements/modal 这样的包非常有用，该包需要添加 Livewire 组件到你的应用中。下例中，使用 Filament 集成了 wire-elements/modal：

use Filament\Panel;
use Filament\View\PanelsRenderHook;
use Illuminate\Support\Facades\Blade;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->renderHook(
            PanelsRenderHook::BODY_START,
            fn (): string => Blade::render('@livewire(\'livewire-ui-modal\')'),
        );
}
use Filament\Panel;
use Filament\View\PanelsRenderHook;
use Illuminate\Support\Facades\Blade;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->renderHook(
            PanelsRenderHook::BODY_START,
            fn (): string => Blade::render('@livewire(\'livewire-ui-modal\')'),
        );
}

渲染钩子的全列表清单，请查阅此处.

设置域名

默认情况下，Filament 会对所有域名的请求进行响应。如果你想将其限制到特定域名，你可以使用 domain() 方法，它类似于 Laravel 中的 Route::domain()：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->domain('admin.example.com');
}
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->domain('admin.example.com');
}

自定义最大内容宽度

默认情况下，Filament 会在页面中限制内容的宽度，这样在大屏幕中才不会变动过宽。你可以重写 getContentMaxWidth() 方法来修改它。选项对应于 Tailwind 的 max-width 尺度。选项值包括 ExtraSmall、Small、Medium、Large、ExtraLarge、TwoExtraLarge、ThreeExtraLarge、FourExtraLarge、FiveExtraLarge、SixExtraLarge、SevenExtraLarge、Full、MinContent、MaxContent、FitContent、Prose、ScreenSmall、ScreenMedium、ScreenLarge、ScreenExtraLarge 及 ScreenTwoExtraLarge。默认值为 SevenExtraLarge。

use Filament\Panel;
use Filament\Support\Enums\MaxWidth;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->maxContentWidth(MaxWidth::Full);
}
use Filament\Panel;
use Filament\Support\Enums\MaxWidth;

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

如果你想为 SimplePage 类型的页面(如登录和注册页面)设置最大内容宽度，可以使用 simplePageMaxContentWidth() 方法。默认值为 Large：

use Filament\Panel;
use Filament\Support\Enums\MaxWidth;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->simplePageMaxContentWidth(MaxWidth::Small);
}
use Filament\Panel;
use Filament\Support\Enums\MaxWidth;

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

生命周期钩子

钩子可用于在面板的生命周期区间执行代码。bootUsing() 是在面板内每个请求上运行。如果你有多个面板，只有当前面板的 bootUsing() 会运行。该函数在所有服务提供者启动之后，在中间件中运行：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->bootUsing(function (Panel $panel) {
            // ...
        });
}
use Filament\Panel;

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

SPA 模式

SPA 模式使用 Livewire 的 wire:navigate 特性，使得你的服务器渲染的面板感觉像单页应用那样，使用更少的页面加载延迟并对长请求使用加载条。要启用面板的 SPA 模式，请使用 spa() 方法：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->spa();
}
use Filament\Panel;

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

为特定 URL 禁用 SPA 导航

默认情况下，当启用 SPA 模式时，任何与当前请求同域的 URL 都会使用 Livewire 的 wire:navigate 特性进行导航。如果你希望为特定 URL 禁用 SPA 导航，请使用 spaUrlExceptions() 方法：

use App\Filament\Resources\PostResource;
use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->spa()
        ->spaUrlExceptions(fn (): array => [
            url('/admin'),
            PostResource::getUrl(),
        ]);
}
use App\Filament\Resources\PostResource;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->spa()
        ->spaUrlExceptions(fn (): array => [
            url('/admin'),
            PostResource::getUrl(),
        ]);
}

本例中，我们使用资源上的 getUrl() 来获取资源首页的 URL。不过该功能需要面板已经注册，而配置是在请求生命周期的早期运行，因此无法在此时运行。你可以使用函数来返回 URL，该函数将在面板注册后运行：

这些 URL 需要与当前请求完全匹配，包括域名和协议。如果你希望使用通配符来匹配多个 URL，你可以使用一个星号 (*) 作为通配符字符：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->spa()
        ->spaUrlExceptions([
            '*/admin/posts/*',
        ]);
}
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->spa()
        ->spaUrlExceptions([
            '*/admin/posts/*',
        ]);
}

未保存的修改提醒

当用户视图离开页面时，你可以提醒用户页面上修改未保存。这适用于资源的创建页和编辑页，以及任何打开的 Action 模态框。要启用此功能，请使用 unsavedChangesAlerts() 方法：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->unsavedChangesAlerts();
}
use Filament\Panel;

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

启用数据库事务

默认情况下，Filament 不会将操作包装到数据库事务中，而用户需要测试以确保操作包装到事物中是安全的，才能启用事务。不过，你可以使用 databaseTransactions() 方法，一次性为所有操作启用数据库事务：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->databaseTransactions();
}
use Filament\Panel;

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

对于任何你不想包装到事务的操作，你可以使用 databaseTransaction(false) 方法：

CreateAction::make()
    ->databaseTransaction(false)
CreateAction::make()
    ->databaseTransaction(false)

而对于像创建资源和编辑资源这样的页面，你可以在页面类中将 $hasDatabaseTransactions 属性设置为 false：

use Filament\Resources\Pages\CreateRecord;
 
class CreatePost extends CreateRecord
{
    protected ?bool $hasDatabaseTransactions = false;
    
    // ...
}
use Filament\Resources\Pages\CreateRecord;

class CreatePost extends CreateRecord
{
    protected ?bool $hasDatabaseTransactions = false;
    
    // ...
}

为特定操作和页面选择性启用数据库事务

你可以为特定的操作和页面选择加入数据库事务，而不是到处启用数据库事务然后选择性退出。

对于 Action，你可以使用 databaseTransaction() 方法:

CreateAction::make()
    ->databaseTransaction()
CreateAction::make()
    ->databaseTransaction()

而对于像创建资源和编辑资源这样的页面，你可以在页面类中将 $hasDatabaseTransactions 属性设置为 true：

use Filament\Resources\Pages\CreateRecord;
 
class CreatePost extends CreateRecord
{
    protected ?bool $hasDatabaseTransactions = true;
    
    // ...
}
use Filament\Resources\Pages\CreateRecord;

class CreatePost extends CreateRecord
{
    protected ?bool $hasDatabaseTransactions = true;
    
    // ...
}

为面板注册资源

你可以注册只加载到指定面板页面的资源，而不在应用的其他地方使用。为此，请传递资源数组到 asserts() 方法：

use Filament\Panel;
use Filament\Support\Assets\Css;
use Filament\Support\Assets\Js;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->assets([
            Css::make('custom-stylesheet', resource_path('css/custom.css')),
            Js::make('custom-script', resource_path('js/custom.js')),
        ]);
}
use Filament\Panel;
use Filament\Support\Assets\Css;
use Filament\Support\Assets\Js;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->assets([
            Css::make('custom-stylesheet', resource_path('css/custom.css')),
            Js::make('custom-script', resource_path('js/custom.js')),
        ]);
}

要使用这些资源(assets)，你需要运行 php artisan filament:assets。

应用中间件

传入中间件列数组到配置的 middleware() 方法，你可以在所有路由中应用额外的中间件：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->middleware([
            // ...
        ]);
}
use Filament\Panel;

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

默认情况下，中间件会在页面首次加载时运行，而不会在随后的 Livewire AJAX 请求时运行。如果你想让中间件在所有请求中运行，可以传入 true 给 middleware() 方法的第二个参数，使之持久化(persistent)：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->middleware([
            // ...
        ], isPersistent: true);
}
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->middleware([
            // ...
        ], isPersistent: true);
}

将中间件应用到经过身份验证的路由

你可以将中间件类数组传递到配置的 authMiddleware() 方法，将中间件应用到所有验证过的路由：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->authMiddleware([
            // ...
        ]);
}
use Filament\Panel;

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

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->authMiddleware([
            // ...
        ], isPersistent: true);
}
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->authMiddleware([
            // ...
        ], isPersistent: true);
}

禁用广播

默认情况下，如果已在已发布的 config/filament.php 配置文件中设置了凭据，Laravel Echo 将自动连接每个面板。要在面板中禁用此自动连接，可以使用 broadcasting(false) 方法：

use Filament\Panel;
 
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->broadcasting(false);
}
use Filament\Panel;

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

Edit on GitHub

Still need help? Join our Discord community or open a GitHub discussion

#概述

#引入面板

#默认的管理面板

#创建新面板

#修改路径

#渲染钩子

#设置域名

#自定义最大内容宽度

#生命周期钩子

#SPA 模式

#为特定 URL 禁用 SPA 导航

#未保存的修改提醒

#启用数据库事务

#为特定操作和页面选择性启用数据库事务

#为面板注册资源

#应用中间件

#将中间件应用到经过身份验证的路由

#禁用广播

概述