公告: 旧版文档请移步 -> http://v2.laravel-filament.cn/docs

Languages

Version

Theme

面板构建器

配置

概述

默认情况下,配置文件位于 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

该命令会创建一个名为"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('');
}

请确保 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\')'),
);
}

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

设置域名

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

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

自定义最大内容宽度

默认情况下,Filament 会在页面中限制内容的宽度,这样在大屏幕中才不会变动过宽。你可以重写 getContentMaxWidth() 方法来修改它。选项对应于 Tailwind 的 max-width 尺度。选项值包括 ExtraSmallSmallMediumLargeExtraLargeTwoExtraLargeThreeExtraLargeFourExtraLargeFiveExtraLargeSixExtraLargeSevenExtraLargeFullMinContentMaxContentFitContentProseScreenSmallScreenMediumScreenLargeScreenExtraLargeScreenTwoExtraLarge。默认值为 SevenExtraLarge

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

生命周期钩子

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

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();
}

为特定 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(),
]);
}

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

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

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();
}

启用数据库事务

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

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

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

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

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

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

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

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

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

CreateAction::make()
->databaseTransaction()

而对于像创建资源编辑资源这样的页面,你可以在页面类中将 $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')),
]);
}

应用中间件

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

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

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

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([
// ...
]);
}

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

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);
}
Edit on GitHub

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

上一页
用户
下一页
Cluster